feat(AppData): Refactor AppData class for declarative env mapping and enhanced static helpers
This commit is contained in:
@@ -3,6 +3,6 @@
|
||||
*/
|
||||
export const commitinfo = {
|
||||
name: '@push.rocks/npmextra',
|
||||
version: '5.1.4',
|
||||
version: '5.3.0',
|
||||
description: 'A utility to enhance npm with additional configuration, tool management capabilities, and a key-value store for project setups.'
|
||||
}
|
||||
|
||||
@@ -1,13 +1,224 @@
|
||||
import * as plugins from './npmextra.plugins.js';
|
||||
import * as paths from './npmextra.paths.js';
|
||||
import { KeyValueStore } from './npmextra.classes.keyvaluestore.js';
|
||||
|
||||
// ============================================================================
|
||||
// Singleton Qenv Provider
|
||||
// ============================================================================
|
||||
let sharedQenv: plugins.qenv.Qenv | undefined;
|
||||
|
||||
function getQenv(): plugins.qenv.Qenv {
|
||||
if (!sharedQenv) {
|
||||
sharedQenv = new plugins.qenv.Qenv(
|
||||
process.cwd(),
|
||||
plugins.path.join(process.cwd(), '.nogit')
|
||||
);
|
||||
}
|
||||
return sharedQenv;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Type Converters - Centralized conversion logic
|
||||
// ============================================================================
|
||||
function toBoolean(value: unknown): boolean {
|
||||
if (typeof value === 'boolean') return value;
|
||||
if (value == null) return false;
|
||||
const s = String(value).toLowerCase();
|
||||
return s === 'true';
|
||||
}
|
||||
|
||||
function toJson<T = any>(value: unknown): T | undefined {
|
||||
if (value == null) return undefined;
|
||||
if (typeof value === 'string') {
|
||||
try {
|
||||
return JSON.parse(value);
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
return value as T;
|
||||
}
|
||||
|
||||
function fromBase64(value: unknown): string | undefined {
|
||||
if (value == null) return undefined;
|
||||
try {
|
||||
return Buffer.from(String(value), 'base64').toString('utf8');
|
||||
} catch {
|
||||
return String(value);
|
||||
}
|
||||
}
|
||||
|
||||
function toNumber(value: unknown): number | undefined {
|
||||
if (value == null) return undefined;
|
||||
const num = Number(value);
|
||||
return Number.isNaN(num) ? undefined : num;
|
||||
}
|
||||
|
||||
function toString(value: unknown): string | undefined {
|
||||
if (value == null) return undefined;
|
||||
return String(value);
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Declarative Pipeline Architecture
|
||||
// ============================================================================
|
||||
type Transform = 'boolean' | 'json' | 'base64' | 'number';
|
||||
|
||||
type MappingSpec = {
|
||||
source:
|
||||
| { type: 'env'; key: string }
|
||||
| { type: 'hard'; value: string };
|
||||
transforms: Transform[];
|
||||
};
|
||||
|
||||
// Transform registry for extensibility
|
||||
const transformRegistry: Record<string, (v: unknown) => unknown> = {
|
||||
boolean: toBoolean,
|
||||
json: toJson,
|
||||
base64: fromBase64,
|
||||
number: toNumber,
|
||||
};
|
||||
|
||||
/**
|
||||
* Parse a mapping string into a declarative spec
|
||||
*/
|
||||
function parseMappingSpec(input: string): MappingSpec {
|
||||
const transforms: Transform[] = [];
|
||||
let remaining = input;
|
||||
|
||||
// Check for hardcoded prefixes with type conversion
|
||||
if (remaining.startsWith('hard_boolean:')) {
|
||||
return {
|
||||
source: { type: 'hard', value: remaining.slice(13) },
|
||||
transforms: ['boolean']
|
||||
};
|
||||
}
|
||||
|
||||
if (remaining.startsWith('hard_json:')) {
|
||||
return {
|
||||
source: { type: 'hard', value: remaining.slice(10) },
|
||||
transforms: ['json']
|
||||
};
|
||||
}
|
||||
|
||||
if (remaining.startsWith('hard_base64:')) {
|
||||
return {
|
||||
source: { type: 'hard', value: remaining.slice(12) },
|
||||
transforms: ['base64']
|
||||
};
|
||||
}
|
||||
|
||||
// Check for generic hard: prefix
|
||||
if (remaining.startsWith('hard:')) {
|
||||
remaining = remaining.slice(5);
|
||||
// Check for legacy suffixes on hardcoded values
|
||||
if (remaining.endsWith('_JSON')) {
|
||||
transforms.push('json');
|
||||
remaining = remaining.slice(0, -5);
|
||||
} else if (remaining.endsWith('_BASE64')) {
|
||||
transforms.push('base64');
|
||||
remaining = remaining.slice(0, -7);
|
||||
}
|
||||
return {
|
||||
source: { type: 'hard', value: remaining },
|
||||
transforms
|
||||
};
|
||||
}
|
||||
|
||||
// Check for env var prefixes
|
||||
if (remaining.startsWith('boolean:')) {
|
||||
transforms.push('boolean');
|
||||
remaining = remaining.slice(8);
|
||||
} else if (remaining.startsWith('json:')) {
|
||||
transforms.push('json');
|
||||
remaining = remaining.slice(5);
|
||||
} else if (remaining.startsWith('base64:')) {
|
||||
transforms.push('base64');
|
||||
remaining = remaining.slice(7);
|
||||
}
|
||||
|
||||
// Check for legacy suffixes on env vars
|
||||
if (remaining.endsWith('_JSON')) {
|
||||
transforms.push('json');
|
||||
remaining = remaining.slice(0, -5);
|
||||
} else if (remaining.endsWith('_BASE64')) {
|
||||
transforms.push('base64');
|
||||
remaining = remaining.slice(0, -7);
|
||||
}
|
||||
|
||||
return {
|
||||
source: { type: 'env', key: remaining },
|
||||
transforms
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve the source value (env var or hardcoded)
|
||||
*/
|
||||
async function resolveSource(source: MappingSpec['source']): Promise<unknown> {
|
||||
if (source.type === 'hard') {
|
||||
return source.value;
|
||||
}
|
||||
// source.type === 'env'
|
||||
return await getQenv().getEnvVarOnDemand(source.key);
|
||||
}
|
||||
|
||||
/**
|
||||
* Apply transformations in sequence
|
||||
*/
|
||||
function applyTransforms(value: unknown, transforms: Transform[]): unknown {
|
||||
return transforms.reduce((acc, transform) => {
|
||||
const fn = transformRegistry[transform];
|
||||
return fn ? fn(acc) : acc;
|
||||
}, value);
|
||||
}
|
||||
|
||||
/**
|
||||
* Process a mapping value through the complete pipeline
|
||||
*/
|
||||
async function processMappingValue(mappingString: string): Promise<unknown> {
|
||||
const spec = parseMappingSpec(mappingString);
|
||||
const rawValue = await resolveSource(spec.source);
|
||||
|
||||
if (rawValue === undefined || rawValue === null) {
|
||||
return undefined;
|
||||
}
|
||||
|
||||
return applyTransforms(rawValue, spec.transforms);
|
||||
}
|
||||
|
||||
/**
|
||||
* Recursively evaluate mapping values (strings or nested objects)
|
||||
*/
|
||||
async function evaluateMappingValue(mappingValue: any): Promise<any> {
|
||||
if (typeof mappingValue === 'string') {
|
||||
return processMappingValue(mappingValue);
|
||||
}
|
||||
|
||||
if (mappingValue && typeof mappingValue === 'object' && !Array.isArray(mappingValue)) {
|
||||
const result: any = {};
|
||||
for (const [key, value] of Object.entries(mappingValue)) {
|
||||
result[key] = await evaluateMappingValue(value);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
return undefined;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// AppData Interface and Class
|
||||
// ============================================================================
|
||||
export interface IAppDataOptions<T = any> {
|
||||
dirPath?: string;
|
||||
requiredKeys?: Array<keyof T>;
|
||||
|
||||
/**
|
||||
* wether keys should be persisted on disk or not
|
||||
* Whether keys should be persisted on disk or not
|
||||
*/
|
||||
ephemeral?: boolean;
|
||||
|
||||
/**
|
||||
* @deprecated Use 'ephemeral' instead
|
||||
*/
|
||||
ephermal?: boolean;
|
||||
|
||||
@@ -33,6 +244,56 @@ export class AppData<T = any> {
|
||||
return appData;
|
||||
}
|
||||
|
||||
/**
|
||||
* Static helper to get an environment variable as a boolean
|
||||
* @param envVarName The name of the environment variable
|
||||
* @returns boolean value (true if env var is "true", false otherwise)
|
||||
*/
|
||||
public static async valueAsBoolean(envVarName: string): Promise<boolean> {
|
||||
const value = await getQenv().getEnvVarOnDemand(envVarName);
|
||||
return toBoolean(value);
|
||||
}
|
||||
|
||||
/**
|
||||
* Static helper to get an environment variable as parsed JSON
|
||||
* @param envVarName The name of the environment variable
|
||||
* @returns Parsed JSON object/array
|
||||
*/
|
||||
public static async valueAsJson<R = any>(envVarName: string): Promise<R | undefined> {
|
||||
const value = await getQenv().getEnvVarOnDemand(envVarName);
|
||||
return toJson<R>(value);
|
||||
}
|
||||
|
||||
/**
|
||||
* Static helper to get an environment variable as base64 decoded string
|
||||
* @param envVarName The name of the environment variable
|
||||
* @returns Decoded string
|
||||
*/
|
||||
public static async valueAsBase64(envVarName: string): Promise<string | undefined> {
|
||||
const value = await getQenv().getEnvVarOnDemand(envVarName);
|
||||
return fromBase64(value);
|
||||
}
|
||||
|
||||
/**
|
||||
* Static helper to get an environment variable as a string
|
||||
* @param envVarName The name of the environment variable
|
||||
* @returns String value
|
||||
*/
|
||||
public static async valueAsString(envVarName: string): Promise<string | undefined> {
|
||||
const value = await getQenv().getEnvVarOnDemand(envVarName);
|
||||
return toString(value);
|
||||
}
|
||||
|
||||
/**
|
||||
* Static helper to get an environment variable as a number
|
||||
* @param envVarName The name of the environment variable
|
||||
* @returns Number value
|
||||
*/
|
||||
public static async valueAsNumber(envVarName: string): Promise<number | undefined> {
|
||||
const value = await getQenv().getEnvVarOnDemand(envVarName);
|
||||
return toNumber(value);
|
||||
}
|
||||
|
||||
// instance
|
||||
public readyDeferred = plugins.smartpromise.defer<void>();
|
||||
public options: IAppDataOptions<T>;
|
||||
@@ -45,11 +306,20 @@ export class AppData<T = any> {
|
||||
|
||||
/**
|
||||
* inits app data
|
||||
* @param pathArg
|
||||
*/
|
||||
private async init(pathArg?: string) {
|
||||
if (this.options.dirPath || this.options.ephermal) {
|
||||
// ok, nothing to do here;
|
||||
private async init() {
|
||||
console.log('🚀 Initializing AppData...');
|
||||
|
||||
// Handle backward compatibility for typo
|
||||
const isEphemeral = this.options.ephemeral ?? this.options.ephermal ?? false;
|
||||
if (this.options.ephermal && !this.options.ephemeral) {
|
||||
console.warn('⚠️ Option "ephermal" is deprecated, use "ephemeral" instead.');
|
||||
}
|
||||
|
||||
if (this.options.dirPath) {
|
||||
console.log(` 📁 Using custom directory: ${this.options.dirPath}`);
|
||||
} else if (isEphemeral) {
|
||||
console.log(` 💨 Using ephemeral storage (in-memory only)`);
|
||||
} else {
|
||||
const appDataDir = '/app/data';
|
||||
const dataDir = '/data';
|
||||
@@ -58,157 +328,73 @@ export class AppData<T = any> {
|
||||
const dataExists = plugins.smartfile.fs.isDirectory(dataDir);
|
||||
if (appDataExists) {
|
||||
this.options.dirPath = appDataDir;
|
||||
console.log(` 📁 Auto-selected container directory: ${appDataDir}`);
|
||||
} else if (dataExists) {
|
||||
this.options.dirPath = dataDir;
|
||||
console.log(` 📁 Auto-selected data directory: ${dataDir}`);
|
||||
} else {
|
||||
await plugins.smartfile.fs.ensureDir(nogitAppData);
|
||||
this.options.dirPath = nogitAppData;
|
||||
console.log(` 📁 Auto-selected local directory: ${nogitAppData}`);
|
||||
}
|
||||
}
|
||||
|
||||
this.kvStore = new KeyValueStore<T>({
|
||||
typeArg: this.options.ephermal ? 'ephemeral' : 'custom',
|
||||
typeArg: isEphemeral ? 'ephemeral' : 'custom',
|
||||
identityArg: 'appkv',
|
||||
customPath: this.options.dirPath,
|
||||
mandatoryKeys: this.options.requiredKeys as Array<keyof T>,
|
||||
});
|
||||
|
||||
if (this.options.envMapping) {
|
||||
const qenvInstance = new plugins.qenv.Qenv(
|
||||
process.cwd(),
|
||||
plugins.path.join(process.cwd(), '.nogit'),
|
||||
);
|
||||
|
||||
// Recursive function to handle nested objects, now includes key parameter
|
||||
const processEnvMapping = async (
|
||||
key: keyof T,
|
||||
mappingValue: any,
|
||||
parentKey: keyof T | '' = '',
|
||||
): Promise<any> => {
|
||||
if (typeof mappingValue === 'string') {
|
||||
let envValue: string | boolean | T[keyof T];
|
||||
let convert: 'none' | 'json' | 'base64' | 'boolean' = 'none';
|
||||
switch (true) {
|
||||
case mappingValue.startsWith('hard:'):
|
||||
envValue = mappingValue.replace('hard:', '') as T[keyof T];
|
||||
break;
|
||||
case mappingValue.startsWith('hard_boolean:'):
|
||||
envValue = mappingValue.replace('hard_boolean:', '') === 'true';
|
||||
convert = 'boolean';
|
||||
break;
|
||||
case mappingValue.startsWith('hard_json:'):
|
||||
envValue = JSON.parse(
|
||||
mappingValue.replace('hard_json:', ''),
|
||||
) as T[keyof T];
|
||||
convert = 'json';
|
||||
break;
|
||||
case mappingValue.startsWith('hard_base64:'):
|
||||
envValue = Buffer.from(
|
||||
mappingValue.replace('hard_base64:', ''),
|
||||
'base64',
|
||||
).toString() as T[keyof T];
|
||||
convert = 'base64';
|
||||
break;
|
||||
case mappingValue.startsWith('boolean:'):
|
||||
envValue = (await qenvInstance.getEnvVarOnDemand(
|
||||
mappingValue.replace('boolean:', ''),
|
||||
)) as T[keyof T];
|
||||
convert = 'boolean';
|
||||
break;
|
||||
case mappingValue.startsWith('json:'):
|
||||
envValue = (await qenvInstance.getEnvVarOnDemand(
|
||||
mappingValue.replace('json:', ''),
|
||||
)) as T[keyof T];
|
||||
convert = 'json';
|
||||
break;
|
||||
case mappingValue.startsWith('base64:'):
|
||||
envValue = (await qenvInstance.getEnvVarOnDemand(
|
||||
mappingValue.replace('base64:', ''),
|
||||
)) as T[keyof T];
|
||||
convert = 'base64';
|
||||
break;
|
||||
default:
|
||||
envValue = (await qenvInstance.getEnvVarOnDemand(
|
||||
mappingValue,
|
||||
)) as T[keyof T];
|
||||
break;
|
||||
}
|
||||
|
||||
// lets format the env value
|
||||
if (envValue !== undefined && envValue !== null) {
|
||||
if (convert === 'boolean') {
|
||||
// Handle both string and boolean inputs
|
||||
if (typeof envValue === 'boolean') {
|
||||
// Already boolean, keep as-is
|
||||
envValue = envValue;
|
||||
} else if (typeof envValue === 'string') {
|
||||
// Convert string to boolean
|
||||
envValue = envValue === 'true';
|
||||
} else {
|
||||
// Any other type, convert to boolean
|
||||
envValue = Boolean(envValue);
|
||||
}
|
||||
}
|
||||
if (
|
||||
typeof envValue === 'string' &&
|
||||
(mappingValue.endsWith('_JSON') || convert === 'json')
|
||||
) {
|
||||
envValue = JSON.parse(envValue as string) as T[keyof T];
|
||||
}
|
||||
if (
|
||||
typeof envValue === 'string' &&
|
||||
(mappingValue.endsWith('_BASE64') || convert === 'base64')
|
||||
) {
|
||||
envValue = Buffer.from(envValue as string, 'base64').toString();
|
||||
}
|
||||
if (!parentKey) {
|
||||
await this.kvStore.writeKey(key, envValue as any);
|
||||
} else {
|
||||
return envValue;
|
||||
}
|
||||
} else {
|
||||
return undefined;
|
||||
}
|
||||
} else if (typeof mappingValue === 'object' && mappingValue !== null) {
|
||||
const resultObject: Partial<T> = {};
|
||||
for (const innerKey in mappingValue) {
|
||||
const nestedValue = mappingValue[innerKey];
|
||||
// For nested objects, call recursively but do not immediately write to kvStore
|
||||
const nestedResult = await processEnvMapping(
|
||||
innerKey as keyof T,
|
||||
nestedValue,
|
||||
key,
|
||||
);
|
||||
resultObject[innerKey as keyof T] = nestedResult;
|
||||
}
|
||||
if (parentKey === '') {
|
||||
// Only write to kvStore if at the top level
|
||||
await this.kvStore.writeKey(key, resultObject as T[keyof T]);
|
||||
} else {
|
||||
// For nested objects, return the constructed object instead of writing to kvStore
|
||||
return resultObject;
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
console.log(`📦 Processing envMapping for AppData...`);
|
||||
const totalKeys = Object.keys(this.options.envMapping).length;
|
||||
let processedCount = 0;
|
||||
|
||||
// Process each top-level key in envMapping
|
||||
for (const key in this.options.envMapping) {
|
||||
await processEnvMapping(key as keyof T, this.options.envMapping[key]);
|
||||
}
|
||||
|
||||
if (this.options.overwriteObject) {
|
||||
for (const key of Object.keys(this.options.overwriteObject)) {
|
||||
console.log(
|
||||
`-> heads up: overwriting key ${key} from options.overwriteObject`,
|
||||
);
|
||||
await this.kvStore.writeKey(
|
||||
key as keyof T,
|
||||
this.options.overwriteObject[key],
|
||||
);
|
||||
try {
|
||||
const mappingSpec = this.options.envMapping[key];
|
||||
console.log(` → Processing key "${key}" with spec:`, typeof mappingSpec === 'string' ? mappingSpec : 'nested object');
|
||||
|
||||
const evaluated = await evaluateMappingValue(mappingSpec);
|
||||
if (evaluated !== undefined) {
|
||||
await this.kvStore.writeKey(key as keyof T, evaluated);
|
||||
processedCount++;
|
||||
const valueType = Array.isArray(evaluated) ? 'array' : typeof evaluated;
|
||||
console.log(` ✅ Successfully processed key "${key}" (type: ${valueType})`);
|
||||
} else {
|
||||
console.log(` ⚠️ Key "${key}" evaluated to undefined, skipping`);
|
||||
}
|
||||
} catch (err) {
|
||||
console.error(` ❌ Failed to evaluate envMapping for key "${key}":`, err);
|
||||
}
|
||||
}
|
||||
|
||||
console.log(`📊 EnvMapping complete: ${processedCount}/${totalKeys} keys successfully processed`);
|
||||
}
|
||||
|
||||
// Apply overwrite object after env mapping
|
||||
if (this.options.overwriteObject) {
|
||||
const overwriteKeys = Object.keys(this.options.overwriteObject);
|
||||
console.log(`🔄 Applying overwriteObject with ${overwriteKeys.length} key(s)...`);
|
||||
|
||||
for (const key of overwriteKeys) {
|
||||
const value = this.options.overwriteObject[key];
|
||||
const valueType = Array.isArray(value) ? 'array' : typeof value;
|
||||
console.log(` 🔧 Overwriting key "${key}" with ${valueType} value`);
|
||||
|
||||
await this.kvStore.writeKey(
|
||||
key as keyof T,
|
||||
value,
|
||||
);
|
||||
}
|
||||
|
||||
console.log(`✅ OverwriteObject complete: ${overwriteKeys.length} key(s) overwritten`);
|
||||
}
|
||||
|
||||
this.readyDeferred.resolve();
|
||||
console.log('✨ AppData initialization complete!');
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
Reference in New Issue
Block a user