@devopsplaybook.io/common-utils 1.2.0-beta.7.84f3f67 → 1.2.0

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

@@ -40,6 +40,48 @@ exports.ConfigBase = void 0;
 const fse = __importStar(require("fs-extra"));
 const uuid_1 = require("uuid");
 const path_1 = __importDefault(require("path"));
+/**
+ * Coerce a string value read from an environment variable to match the
+ * type of the default value (number → parseFloat, boolean → "true"/"1",
+ * array → JSON.parse, etc.).  When the default is already a string or
+ * there is no default, the original string is returned as-is.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function coerceValue(value, defaultValue) {
+    if (defaultValue === undefined || defaultValue === null) {
+        return value;
+    }
+    switch (typeof defaultValue) {
+        case "number": {
+            const parsed = Number(value);
+            return Number.isNaN(parsed) ? value : parsed;
+        }
+        case "boolean": {
+            return value === "true" || value === "1" || value === "yes";
+        }
+        case "object": {
+            if (Array.isArray(defaultValue)) {
+                try {
+                    return JSON.parse(value);
+                }
+                catch {
+                    return value;
+                }
+            }
+            if (defaultValue !== null) {
+                try {
+                    return JSON.parse(value);
+                }
+                catch {
+                    return value;
+                }
+            }
+            return value;
+        }
+        default:
+            return value;
+    }
+}
 /**
  * Abstract base class for project configuration.
  *
@@ -94,7 +136,6 @@ class ConfigBase {
          * Fields registered by subclasses (or the base) that {@link reload}
          * should process.  Common / DB / OTel fields are pre-registered.
          */
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this._fields = [];
         this.SERVICE_ID = serviceId;
         this.CONFIG_FILE = configFile || process.env.CONFIG_FILE || "config.json";
@@ -117,11 +158,15 @@ 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 +191,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 +221,35 @@ 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, defaultValue } 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,
+            //    coercing strings to match the default value type
+            if (foundValue !== undefined) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                this[field] = coerceValue(foundValue, defaultValue);
+            }
+            // 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 +260,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devopsplaybook.io/common-utils",
-  "version": "1.2.0-beta.7.84f3f67",
+  "version": "1.2.0",
   "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[];
 }
 
 /**
@@ -40,6 +53,48 @@ export interface ConfigCommonInterface
   LOG_LEVEL: string;
 }
 
+/**
+ * Coerce a string value read from an environment variable to match the
+ * type of the default value (number → parseFloat, boolean → "true"/"1",
+ * array → JSON.parse, etc.).  When the default is already a string or
+ * there is no default, the original string is returned as-is.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function coerceValue(value: string, defaultValue: any): any {
+  if (defaultValue === undefined || defaultValue === null) {
+    return value;
+  }
+
+  switch (typeof defaultValue) {
+    case "number": {
+      const parsed = Number(value);
+      return Number.isNaN(parsed) ? value : parsed;
+    }
+    case "boolean": {
+      return value === "true" || value === "1" || value === "yes";
+    }
+    case "object": {
+      if (Array.isArray(defaultValue)) {
+        try {
+          return JSON.parse(value);
+        } catch {
+          return value;
+        }
+      }
+      if (defaultValue !== null) {
+        try {
+          return JSON.parse(value);
+        } catch {
+          return value;
+        }
+      }
+      return value;
+    }
+    default:
+      return value;
+  }
+}
+
 /**
  * Abstract base class for project configuration.
  *
@@ -96,9 +151,13 @@ export abstract class ConfigBase implements ConfigCommonInterface {
    * Fields registered by subclasses (or the base) that {@link reload}
    * 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[];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    defaultValue: any;
+  }[] = [];
 
   /**
    * @param serviceId  Unique service identifier (e.g. `"cryptotrader-server"`).
@@ -127,11 +186,15 @@ 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 +223,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 +251,44 @@ 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, defaultValue } 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,
+      //    coercing strings to match the default value type
+      if (foundValue !== undefined) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (this as any)[field] = coerceValue(foundValue, defaultValue);
+      }
+
+      // 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 +296,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` : ""})`,
         );
       }
     }