@devopsplaybook.io/common-utils 1.1.0-beta.6.9ec503a → 1.2.0-beta.7.3382b46

package/README.md

@@ -206,17 +206,17 @@ await AuthDb.transaction(span, async (client) => {
 await AuthDb.closeAll();
 ```
 
-| Method                                              | Description                                         |
-| --------------------------------------------------- | --------------------------------------------------- |
-| `new PostgresSchemaDbUtils(schemaName)`             | Create instance for a specific schema               |
-| `initOTel(tracer, logger)`                          | Inject OTel instances (shared across all instances) |
-| `initSchema(context, config, sqlDir)`               | Create schema pool and run migrations               |
-| `initRuntimePool(config)`                           | Create shared runtime pool                          |
-| `execSQL(context, sql, params?, useSchemaPool?)`    | Execute write, returns `Promise<number>`            |
-| `execSQLFile(context, filename, useSchemaPool?)`    | Execute an entire SQL file                          |
-| `querySQL(context, sql, params?, useSchemaPool?)`   | Execute read, returns `Promise<any[]>`              |
-| `transaction(context, callback, useSchemaPool?)`    | Run callback inside a transaction                   |
-| `closeAll()`                                        | Close all pools managed by this instance            |
+| Method                                            | Description                                         |
+| ------------------------------------------------- | --------------------------------------------------- |
+| `new PostgresSchemaDbUtils(schemaName)`           | Create instance for a specific schema               |
+| `initOTel(tracer, logger)`                        | Inject OTel instances (shared across all instances) |
+| `initSchema(context, config, sqlDir)`             | Create schema pool and run migrations               |
+| `initRuntimePool(config)`                         | Create shared runtime pool                          |
+| `execSQL(context, sql, params?, useSchemaPool?)`  | Execute write, returns `Promise<number>`            |
+| `execSQLFile(context, filename, useSchemaPool?)`  | Execute an entire SQL file                          |
+| `querySQL(context, sql, params?, useSchemaPool?)` | Execute read, returns `Promise<any[]>`              |
+| `transaction(context, callback, useSchemaPool?)`  | Run callback inside a transaction                   |
+| `closeAll()`                                      | Close all pools managed by this instance            |
 
 `useSchemaPool` (default `true`) selects between the schema-specific pool (migrations) and the shared runtime pool (application queries).
 

package/dist/src/ConfigBase.d.ts

@@ -7,6 +7,19 @@ export interface ConfigFieldDef {
     field: string;
     /** When `true` the value is masked in log output. */
     sensitive?: boolean;
+    /**
+     * Alternative environment variable names to check when the primary field
+     * name is not found in `process.env`.  Aliases are tried in order and the
+     * first match wins.  Only checked in the environment layer, never in the
+     * config-file layer.
+     *
+     * @example
+     * ```ts
+     * // Look for DATABASE_POSTGRES_HOST first, then fall back to POSTGRES_HOST
+     * { field: "DATABASE_POSTGRES_HOST", envAliases: ["POSTGRES_HOST"] }
+     * ```
+     */
+    envAliases?: string[];
 }
 /**
  * Database-specific configuration fields shared by every project that

package/dist/src/ConfigBase.js

@@ -117,11 +117,11 @@ class ConfigBase {
             { field: "JWT_KEY", sensitive: true },
             { field: "LOG_LEVEL" },
             { field: "DATABASE_TYPE" },
-            { field: "DATABASE_POSTGRES_HOST" },
-            { field: "DATABASE_POSTGRES_PORT" },
-            { field: "DATABASE_POSTGRES_USER" },
-            { field: "DATABASE_POSTGRES_PASSWORD", sensitive: true },
-            { field: "DATABASE_POSTGRES_DATABASE" },
+            { field: "DATABASE_POSTGRES_HOST", envAliases: ["POSTGRES_HOST"] },
+            { field: "DATABASE_POSTGRES_PORT", envAliases: ["POSTGRES_PORT"] },
+            { field: "DATABASE_POSTGRES_USER", envAliases: ["POSTGRES_USER"] },
+            { field: "DATABASE_POSTGRES_PASSWORD", sensitive: true, envAliases: ["POSTGRES_PASSWORD"] },
+            { field: "DATABASE_POSTGRES_DATABASE", envAliases: ["POSTGRES_DB"] },
             { field: "OPENTELEMETRY_COLLECTOR_HTTP_TRACES" },
             { field: "OPENTELEMETRY_COLLECTOR_HTTP_METRICS" },
             { field: "OPENTELEMETRY_COLLECTOR_HTTP_LOGS" },
@@ -146,10 +146,11 @@ class ConfigBase {
      * Call this in your subclass constructor for every project-specific field.
      */
     addConfigField(def) {
-        var _a;
+        var _a, _b;
         this._fields.push({
             field: def.field,
             sensitive: (_a = def.sensitive) !== null && _a !== void 0 ? _a : false,
+            envAliases: (_b = def.envAliases) !== null && _b !== void 0 ? _b : [],
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             defaultValue: this[def.field],
         });
@@ -175,14 +176,34 @@ class ConfigBase {
         log(`Configuration Value: CONFIG_FILE: ${this.CONFIG_FILE}`);
         log(`Configuration Value: SERVICE_ID: ${this.SERVICE_ID}`);
         log(`Configuration Value: VERSION: ${this.VERSION}`);
-        for (const { field, sensitive } of this._fields) {
+        for (const { field, sensitive, envAliases } of this._fields) {
             let from = "defaults";
+            let foundValue;
+            let usedAlias = false;
+            // 1. Primary environment variable name
             if (process.env[field] !== undefined) {
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                this[field] = process.env[field];
+                foundValue = process.env[field];
                 from = "environment";
             }
-            else if (content[field] !== undefined) {
+            // 2. Check aliases if primary env var was not set
+            if (foundValue === undefined && envAliases.length > 0) {
+                for (const alias of envAliases) {
+                    if (process.env[alias] !== undefined) {
+                        foundValue = process.env[alias];
+                        from = "environment";
+                        usedAlias = true;
+                        break;
+                    }
+                }
+            }
+            // 3. Apply environment value (full name or alias) if found
+            if (foundValue !== undefined) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                this[field] = foundValue;
+            }
+            // 4. Config file override (environment always wins, but if neither
+            //    environment nor alias matched, check config file)
+            if (foundValue === undefined && content[field] !== undefined) {
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 this[field] = content[field];
                 from = "config";
@@ -193,7 +214,7 @@ class ConfigBase {
             else {
                 log(
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                `Configuration Value: ${field}: ${this[field]} (from ${from})`);
+                `Configuration Value: ${field}: ${this[field]} (from ${from}${usedAlias ? ` via alias` : ""})`);
             }
         }
     }

package/dist/src/PostgresDbUtils.d.ts

@@ -24,8 +24,9 @@ export declare class PostgresSchemaDbUtils {
     private schemaPool;
     private runtimePool;
     private readonly schemaName;
-    private readonly moduleLogger;
+    private _moduleLogger;
     constructor(schemaName: string);
+    private get moduleLogger();
     /**
      * Create the schema-specific pool, ensure the schema exists, and apply
      * any pending migration files from `sqlDir`.

package/dist/src/PostgresDbUtils.js

@@ -68,8 +68,14 @@ class PostgresSchemaDbUtils {
     constructor(schemaName) {
         this.schemaPool = null;
         this.runtimePool = null;
+        this._moduleLogger = null;
         this.schemaName = schemaName;
-        this.moduleLogger = standardLogger.createModuleLogger(`PostgresSchemaDbUtils[${schemaName}]`);
+    }
+    get moduleLogger() {
+        if (!this._moduleLogger) {
+            this._moduleLogger = standardLogger.createModuleLogger(`PostgresSchemaDbUtils[${this.schemaName}]`);
+        }
+        return this._moduleLogger;
     }
     /**
      * Create the schema-specific pool, ensure the schema exists, and apply

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devopsplaybook.io/common-utils",
-  "version": "1.1.0-beta.6.9ec503a",
+  "version": "1.2.0-beta.7.3382b46",
   "description": "Shared utility modules for devopsplaybook.io projects (DB, Config, OTel context, system helpers)",
   "keywords": [
     "Open Telemetry",

package/src/ConfigBase.ts

@@ -11,6 +11,19 @@ export interface ConfigFieldDef {
   field: string;
   /** When `true` the value is masked in log output. */
   sensitive?: boolean;
+  /**
+   * Alternative environment variable names to check when the primary field
+   * name is not found in `process.env`.  Aliases are tried in order and the
+   * first match wins.  Only checked in the environment layer, never in the
+   * config-file layer.
+   *
+   * @example
+   * ```ts
+   * // Look for DATABASE_POSTGRES_HOST first, then fall back to POSTGRES_HOST
+   * { field: "DATABASE_POSTGRES_HOST", envAliases: ["POSTGRES_HOST"] }
+   * ```
+   */
+  envAliases?: string[];
 }
 
 /**
@@ -97,7 +110,7 @@ export abstract class ConfigBase implements ConfigCommonInterface {
    * should process.  Common / DB / OTel fields are pre-registered.
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private _fields: { field: string; sensitive: boolean; defaultValue: any }[] =
+  private _fields: { field: string; sensitive: boolean; envAliases: string[]; defaultValue: any }[] =
     [];
 
   /**
@@ -127,11 +140,11 @@ export abstract class ConfigBase implements ConfigCommonInterface {
       { field: "JWT_KEY", sensitive: true },
       { field: "LOG_LEVEL" },
       { field: "DATABASE_TYPE" },
-      { field: "DATABASE_POSTGRES_HOST" },
-      { field: "DATABASE_POSTGRES_PORT" },
-      { field: "DATABASE_POSTGRES_USER" },
-      { field: "DATABASE_POSTGRES_PASSWORD", sensitive: true },
-      { field: "DATABASE_POSTGRES_DATABASE" },
+      { field: "DATABASE_POSTGRES_HOST", envAliases: ["POSTGRES_HOST"] },
+      { field: "DATABASE_POSTGRES_PORT", envAliases: ["POSTGRES_PORT"] },
+      { field: "DATABASE_POSTGRES_USER", envAliases: ["POSTGRES_USER"] },
+      { field: "DATABASE_POSTGRES_PASSWORD", sensitive: true, envAliases: ["POSTGRES_PASSWORD"] },
+      { field: "DATABASE_POSTGRES_DATABASE", envAliases: ["POSTGRES_DB"] },
       { field: "OPENTELEMETRY_COLLECTOR_HTTP_TRACES" },
       { field: "OPENTELEMETRY_COLLECTOR_HTTP_METRICS" },
       { field: "OPENTELEMETRY_COLLECTOR_HTTP_LOGS" },
@@ -160,6 +173,7 @@ export abstract class ConfigBase implements ConfigCommonInterface {
     this._fields.push({
       field: def.field,
       sensitive: def.sensitive ?? false,
+      envAliases: def.envAliases ?? [],
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       defaultValue: (this as any)[def.field],
     });
@@ -187,17 +201,43 @@ export abstract class ConfigBase implements ConfigCommonInterface {
     log(`Configuration Value: SERVICE_ID: ${this.SERVICE_ID}`);
     log(`Configuration Value: VERSION: ${this.VERSION}`);
 
-    for (const { field, sensitive } of this._fields) {
+    for (const { field, sensitive, envAliases } of this._fields) {
       let from = "defaults";
+      let foundValue: string | undefined;
+      let usedAlias = false;
+
+      // 1. Primary environment variable name
       if (process.env[field] !== undefined) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        (this as any)[field] = process.env[field];
+        foundValue = process.env[field];
         from = "environment";
-      } else if (content[field] !== undefined) {
+      }
+
+      // 2. Check aliases if primary env var was not set
+      if (foundValue === undefined && envAliases.length > 0) {
+        for (const alias of envAliases) {
+          if (process.env[alias] !== undefined) {
+            foundValue = process.env[alias];
+            from = "environment";
+            usedAlias = true;
+            break;
+          }
+        }
+      }
+
+      // 3. Apply environment value (full name or alias) if found
+      if (foundValue !== undefined) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (this as any)[field] = foundValue;
+      }
+
+      // 4. Config file override (environment always wins, but if neither
+      //    environment nor alias matched, check config file)
+      if (foundValue === undefined && content[field] !== undefined) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         (this as any)[field] = content[field];
         from = "config";
       }
+
       if (sensitive) {
         log(
           `Configuration Value: ${field}: ******************** (from ${from})`,
@@ -205,7 +245,7 @@ export abstract class ConfigBase implements ConfigCommonInterface {
       } else {
         log(
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          `Configuration Value: ${field}: ${(this as any)[field]} (from ${from})`,
+          `Configuration Value: ${field}: ${(this as any)[field]} (from ${from}${usedAlias ? ` via alias` : ""})`,
         );
       }
     }

package/src/PostgresDbUtils.ts

@@ -45,13 +45,19 @@ export class PostgresSchemaDbUtils {
   private schemaPool: Pool | null = null;
   private runtimePool: Pool | null = null;
   private readonly schemaName: string;
-  private readonly moduleLogger: ModuleLogger;
+  private _moduleLogger: ModuleLogger | null = null;
 
   constructor(schemaName: string) {
     this.schemaName = schemaName;
-    this.moduleLogger = standardLogger.createModuleLogger(
-      `PostgresSchemaDbUtils[${schemaName}]`,
-    );
+  }
+
+  private get moduleLogger(): ModuleLogger {
+    if (!this._moduleLogger) {
+      this._moduleLogger = standardLogger.createModuleLogger(
+        `PostgresSchemaDbUtils[${this.schemaName}]`,
+      );
+    }
+    return this._moduleLogger;
   }
 
   /**
@@ -93,10 +99,7 @@ export class PostgresSchemaDbUtils {
       span,
       `CREATE SCHEMA IF NOT EXISTS ${this.schemaName};`,
     );
-    await this.execSQLForSchema(
-      span,
-      `SET search_path TO ${this.schemaName};`,
-    );
+    await this.execSQLForSchema(span, `SET search_path TO ${this.schemaName};`);
 
     // Run init SQL files
     await this.execSQLFileForSchema(span, `${sqlDir}/init-0000.sql`);
@@ -108,9 +111,7 @@ export class PostgresSchemaDbUtils {
         span,
         "SELECT MAX(value) as version FROM metadata WHERE type='db_version'",
       );
-      if (
-        (dbVersionQuery[0] as Record<string, unknown>).version
-      ) {
+      if ((dbVersionQuery[0] as Record<string, unknown>).version) {
         dbVersionApplied = Number(
           (dbVersionQuery[0] as Record<string, unknown>).version,
         );
@@ -223,10 +224,7 @@ export class PostgresSchemaDbUtils {
     filename: string,
     useSchemaPool = false,
   ): Promise<void> {
-    const span = tracer.startSpan(
-      "PostgresSchemaDbUtilsExecSQLFile",
-      context,
-    );
+    const span = tracer.startSpan("PostgresSchemaDbUtilsExecSQLFile", context);
     const sql = (await fs.readFile(filename)).toString();
     const pool = useSchemaPool ? this.schemaPool : this.runtimePool;
 
@@ -306,10 +304,7 @@ export class PostgresSchemaDbUtils {
     callback: (client: any) => Promise<void>,
     useSchemaPool = false,
   ): Promise<void> {
-    const span = tracer.startSpan(
-      "PostgresSchemaDbUtilsTransaction",
-      context,
-    );
+    const span = tracer.startSpan("PostgresSchemaDbUtilsTransaction", context);
     const pool = useSchemaPool ? this.schemaPool : this.runtimePool;
 
     if (!pool) {