@pawells/config 2.3.1 → 3.0.1

package/dist/schema.factory.js

@@ -1,100 +1,88 @@
 import { ConfigManager } from './manager.js';
 import { IsMarkedSecret } from './secret.js';
-import { ConfigurationNotRegisteredError, ConfigurationNotSetError } from './errors.js';
-/**
- * Intelligently parse an environment variable string to a JSON-compatible value.
- * Attempts to parse as JSON first (handles objects, arrays, booleans, null, numbers).
- * Falls back to treating as a plain string if JSON parsing fails.
- *
- * @param envVarValue - Environment variable value (always a string from process.env)
- * @returns Parsed value (JSON-parsed if applicable, otherwise the original string)
- *
- * @example
- * parseEnvVarValue('true') → true (boolean)
- * parseEnvVarValue('123') → 123 (number)
- * parseEnvVarValue('["a","b"]') → ['a', 'b'] (array)
- * parseEnvVarValue('hello') → 'hello' (string, unchanged)
- */
-function ParseEnvVarValue(envVarValue) {
-    try {
-        return JSON.parse(envVarValue);
-    }
-    catch {
-        // If JSON parsing fails, treat as a plain string
-        return envVarValue;
-    }
-}
+import { ConfigNotRegisteredError, ConfigNotSetError } from './errors.js';
 /**
  * Safely extracts the default value from a Zod schema, handling both
  * lazy defaults (functions) and eager defaults (plain values).
+ * Traverses wrapper schemas (ZodDefault, ZodOptional, ZodNullable, etc.)
+ * to find the default value.
  *
  * @param schema - The field schema to extract the default from
  * @returns The evaluated default value, or undefined if not present
+ * @remarks Returns `undefined` in two distinct cases: (1) the schema has no `ZodDefault` wrapper, and (2) the `ZodDefault` wrapper explicitly wraps `undefined` as its default value. Callers cannot distinguish these cases from the return value alone.
  */
-function extractDefaultValue(schema) {
-    const _def = schema._def;
-    if (!_def || typeof _def !== 'object')
-        return undefined;
-    const dv = _def.defaultValue;
-    if (dv === undefined)
-        return undefined;
-    // Handle both lazy (function) and eager (plain value) defaults
-    return typeof dv === 'function' ? dv() : dv;
+function ExtractDefaultValue(schema) {
+    let current = schema;
+    while (current != null) {
+        const def = current.def;
+        if (def != null && 'defaultValue' in def) {
+            return def.defaultValue;
+        }
+        const inner = current.unwrap;
+        if (typeof inner === 'function') {
+            current = inner.call(current);
+        }
+        else {
+            break;
+        }
+    }
+    return undefined;
 }
 /**
- * Creates a configuration schema object from a Zod schema and prefix.
+ * Registers a configuration schema with {@link ConfigManager} and returns a typed
+ * accessor object for the namespace.
+ *
+ * All schema fields are registered with {@link ConfigManager} immediately when this
+ * function is called. The name is used to derive the environment variable prefix:
+ * `name.toUpperCase() + '_'` (e.g. `'Keycloak'` → `KEYCLOAK_`).
  *
- * Generic factory that eliminates duplication between concrete config classes.
- * Returns an object with Register, Get, Set, Validate, and ParseENV methods
- * that manage config values for a specific namespace.
+ * **Important:** Call {@link ConfigManager.RegisterProvider} for all providers before
+ * importing any module that calls `RegisterConfigSchema` so that provider values are
+ * available when schemas are registered.
  *
- * @param schema - Zod schema defining the config shape and validation rules
- * @param prefix - Prefix for environment variable names (e.g., 'MONGODB_')
- * @returns ConfigSchemaObject with static-like methods for the config namespace
- * @template TSchema - The Zod schema shape
+ * @param name - Human-readable namespace name; used to derive the env var prefix
+ * @param schema - Zod object schema defining the config shape and validation rules
+ * @returns {@link IConfigSchemaObject} with typed accessor methods
+ * @throws {ConfigurationError} If any field's default value does not satisfy its schema
  *
  * @example
  * ```typescript
- * const MONGODB_SCHEMA = z.object({
- *   HOST: z.string().default('localhost'),
- *   PORT: z.number().default(27017),
+ * const KEYCLOAK_SCHEMA = z.object({
+ *   AUTH_SERVER_URL: z.string().url().default('http://localhost:8080/auth'),
+ *   REALM: z.string().min(1).default('master'),
  * });
  *
- * export const MongoDBConfig = createConfigSchema(MONGODB_SCHEMA, 'MONGODB_');
- * // Usage:
- * // MongoDBConfig.Register();
- * // const host = MongoDBConfig.Get('HOST');
- * // MongoDBConfig.Set('PORT', 27018);
- * // MongoDBConfig.ParseENV();
+ * export const KeycloakConfig = RegisterConfigSchema('Keycloak', KEYCLOAK_SCHEMA);
+ * // → prefix is 'KEYCLOAK_'; fields registered immediately
+ * // → KeycloakConfig.Get('AUTH_SERVER_URL') returns the resolved value
  * ```
  */
-export function CreateConfigSchema(schema, prefix) {
-    // Build a map of key -> prefixed name
+export function RegisterConfigSchema(name, schema) {
+    const prefix = `${name.toUpperCase()}_`;
+    ConfigManager.RegisterNamespace(name, prefix);
+    // Build a map of key -> prefixed name, a set of secret keys, and register all fields in a single pass
     const prefixedNames = {};
-    for (const key in schema.shape) {
-        if (Object.prototype.hasOwnProperty.call(schema.shape, key)) {
-            prefixedNames[key] = `${prefix}${key}`;
+    const secretKeys = new Set();
+    for (const key of Object.keys(schema.shape)) {
+        const prefixedKey = prefix ? `${prefix}${key}` : key;
+        prefixedNames[key] = prefixedKey;
+        const fieldSchema = schema.shape[key];
+        if (IsMarkedSecret(fieldSchema)) {
+            secretKeys.add(key);
         }
+        // Register schema field with its default value
+        const defaultValue = ExtractDefaultValue(fieldSchema);
+        // Type: Register accepts ZodTypeAny; runtime enforcement via AssertConfigValueType
+        ConfigManager.Register(prefixedKey, fieldSchema, defaultValue);
     }
-    // Build a set of secret keys by checking each field's metadata
-    const secretKeys = new Set(Object.keys(schema.shape).filter((key) => IsMarkedSecret(schema.shape[key])));
     return {
-        Register() {
-            for (const key in schema.shape) {
-                if (Object.prototype.hasOwnProperty.call(schema.shape, key)) {
-                    const fieldSchema = schema.shape[key];
-                    // Safely extract default value from Zod's internal structure
-                    const defaultValue = extractDefaultValue(fieldSchema);
-                    // @ts-expect-error Zod schema shape types don't align with ConfigManager.Register signature, but this is safe at runtime
-                    ConfigManager.Register(prefixedNames[key], fieldSchema, defaultValue);
-                }
-            }
-        },
+        name,
         Get(key) {
             return ConfigManager.Get(prefixedNames[key]);
         },
         Set(key, value, source = 'OVERRIDE') {
-            // @ts-expect-error TConfig may contain values that don't match TConfigValueTypes, but we trust the schema validation
+            // Type: TConfig[K] maps to TConfigValueTypes at runtime via Zod schema validation.
+            // The schema was validated at registration (line 190), so this cast is safe.
             ConfigManager.Set(prefixedNames[key], value, source);
         },
         Validate(key, value) {
@@ -107,27 +95,6 @@ export function CreateConfigSchema(schema, prefix) {
                 return false;
             }
         },
-        ParseENV(throwOnError = false) {
-            for (const key in schema.shape) {
-                if (Object.prototype.hasOwnProperty.call(schema.shape, key)) {
-                    const envVarName = prefixedNames[key];
-                    const envVarValue = process.env[envVarName];
-                    if (envVarValue !== undefined) {
-                        try {
-                            const fieldSchema = schema.shape[key];
-                            // Pre-process env var string: try JSON parsing first, fall back to plain string
-                            const preProcessedValue = ParseEnvVarValue(envVarValue);
-                            const parsedValue = fieldSchema.parse(preProcessedValue);
-                            this.Set(key, parsedValue, 'OVERRIDE');
-                        }
-                        catch (error) {
-                            if (throwOnError)
-                                throw error;
-                        }
-                    }
-                }
-            }
-        },
         IsSecret(key) {
             return secretKeys.has(key);
         },
@@ -142,8 +109,8 @@ export function CreateConfigSchema(schema, prefix) {
                     result[key] = secretKeys.has(key) ? '***' : value;
                 }
                 catch (error) {
-                    if (error instanceof ConfigurationNotSetError ||
-                        error instanceof ConfigurationNotRegisteredError) {
+                    if (error instanceof ConfigNotSetError
+                        || error instanceof ConfigNotRegisteredError) {
                         // omit unregistered/unset keys
                         continue;
                     }

package/dist/schema.factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.factory.js","sourceRoot":"","sources":["../src/schema.factory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema.factory.js","sourceRoot":"","sources":["../src/schema.factory.ts"],"names":[],"mappings":"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"}

package/dist/secret.d.ts

@@ -12,7 +12,7 @@ import { z } from 'zod/v4';
  *
  * @remarks
  * The inferred TypeScript type is unchanged and will not affect type inference
- * for values validated by this schema. CreateConfigSchema automatically detects
+ * for values validated by this schema. RegisterConfigSchema automatically detects
  * this marker via the IsMarkedSecret helper to handle sensitive fields specially.
  *
  * @example
@@ -28,11 +28,22 @@ import { z } from 'zod/v4';
  * ```
  */
 export declare function Secret<T extends z.ZodTypeAny>(schema: T): T;
+/**
+ * Generator function that traverses a Zod schema chain to its base type.
+ *
+ * Yields each schema in the unwrap chain, starting with the input schema.
+ * Handles both .unwrap() method (for schemas that support it) and .def.innerType fallback.
+ *
+ * @param schema - The Zod schema to traverse
+ * @yields Each schema in the chain from outermost to innermost
+ * @internal
+ */
+export declare function traverseSchemaToBase(schema: z.ZodTypeAny): Generator<z.ZodTypeAny>;
 /**
  * Internal helper function that traverses the Zod schema metadata chain
  * to determine if a schema is marked as secret.
  *
- * Walks through the innerType chain of wrapper schemas (e.g., ZodDefault,
+ * Walks through the unwrap chain of wrapper schemas (e.g., ZodDefault,
  * ZodOptional) and checks each level's metadata in the global registry.
  *
  * @param schema - The Zod schema to check for secret metadata

package/dist/secret.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secret.d.ts","sourceRoot":"","sources":["../src/secret.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAG3D;AAED;;;;;;;;;;GAUG;AACH,iBAAS,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,OAAO,CAsBrD;AAGD,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"secret.d.ts","sourceRoot":"","sources":["../src/secret.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAM3D;AAED;;;;;;;;;GASG;AACH,wBAAiB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAkBnF;AAED;;;;;;;;;;GAUG;AACH,iBAAS,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,OAAO,CAgBrD;AAGD,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/secret.js

@@ -12,7 +12,7 @@ import { z } from 'zod/v4';
  *
  * @remarks
  * The inferred TypeScript type is unchanged and will not affect type inference
- * for values validated by this schema. CreateConfigSchema automatically detects
+ * for values validated by this schema. RegisterConfigSchema automatically detects
  * this marker via the IsMarkedSecret helper to handle sensitive fields specially.
  *
  * @example
@@ -29,13 +29,41 @@ import { z } from 'zod/v4';
  */
 export function Secret(schema) {
     const existingMeta = z.globalRegistry.get(schema) ?? {};
+    if (existingMeta.secret === true) {
+        return schema; // Already marked as secret, no-op
+    }
     return schema.meta({ ...existingMeta, secret: true });
 }
+/**
+ * Generator function that traverses a Zod schema chain to its base type.
+ *
+ * Yields each schema in the unwrap chain, starting with the input schema.
+ * Handles both .unwrap() method (for schemas that support it) and .def.innerType fallback.
+ *
+ * @param schema - The Zod schema to traverse
+ * @yields Each schema in the chain from outermost to innermost
+ * @internal
+ */
+export function* traverseSchemaToBase(schema) {
+    let current = schema;
+    while (current != null) {
+        yield current;
+        // Traverse to the next level via unwrap or .def.innerType (present in wrapper schemas)
+        const unwrapFn = current.unwrap;
+        if (typeof unwrapFn === 'function') {
+            current = unwrapFn.call(current);
+        }
+        else {
+            const innerType = current.def?.innerType;
+            current = innerType;
+        }
+    }
+}
 /**
  * Internal helper function that traverses the Zod schema metadata chain
  * to determine if a schema is marked as secret.
  *
- * Walks through the innerType chain of wrapper schemas (e.g., ZodDefault,
+ * Walks through the unwrap chain of wrapper schemas (e.g., ZodDefault,
  * ZodOptional) and checks each level's metadata in the global registry.
  *
  * @param schema - The Zod schema to check for secret metadata
@@ -43,8 +71,7 @@ export function Secret(schema) {
  * @internal
  */
 function IsMarkedSecret(schema) {
-    let current = schema;
-    while (current != null) {
+    for (const current of traverseSchemaToBase(schema)) {
         try {
             const meta = z.globalRegistry.get(current);
             if (meta?.secret === true) {
@@ -56,8 +83,6 @@ function IsMarkedSecret(schema) {
             // Treat as non-secret and stop traversal.
             break;
         }
-        // Traverse to the next level via innerType (present in wrapper schemas)
-        current = current._def?.innerType;
     }
     return false;
 }

package/dist/secret.js.map

@@ -1 +1 @@
-{"version":3,"file":"secret.js","sourceRoot":"","sources":["../src/secret.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,MAAM,CAAyB,MAAS;IACvD,MAAM,YAAY,GAAG,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACxD,OAAO,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,CAAM,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,cAAc,CAAC,MAAoB;IAC3C,IAAI,OAAO,GAA6B,MAAM,CAAC;IAE/C,OAAO,OAAO,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,CAAC;YACJ,MAAM,IAAI,GAAG,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAC3C,IAAI,IAAI,EAAE,MAAM,KAAK,IAAI,EAAE,CAAC;gBAC3B,OAAO,IAAI,CAAC;YACb,CAAC;QACF,CAAC;QAAC,MAAM,CAAC;YACR,8EAA8E;YAC9E,0CAA0C;YAC1C,MAAM;QACP,CAAC;QAED,wEAAwE;QACxE,OAAO,GAAI,OAAO,CAAC,IAA2C,EAAE,SAEpD,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC;AAED,wEAAwE;AACxE,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"secret.js","sourceRoot":"","sources":["../src/secret.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,MAAM,CAAyB,MAAS;IACvD,MAAM,YAAY,GAAG,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACxD,IAAK,YAAqC,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAC5D,OAAO,MAAM,CAAC,CAAC,kCAAkC;IAClD,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,CAAM,CAAC;AAC5D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,SAAS,CAAC,CAAC,oBAAoB,CAAC,MAAoB;IACzD,IAAI,OAAO,GAA6B,MAAM,CAAC;IAE/C,OAAO,OAAO,IAAI,IAAI,EAAE,CAAC;QACxB,MAAM,OAAO,CAAC;QAEd,uFAAuF;QACvF,MAAM,QAAQ,GAAI,OAA2C,CAAC,MAAM,CAAC;QACrE,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;YACpC,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAiB,CAAC;QAClD,CAAC;aACI,CAAC;YACL,MAAM,SAAS,GAAI,OAA6C,CAAC,GAAG,EAAE,SAEzD,CAAC;YACd,OAAO,GAAG,SAAS,CAAC;QACrB,CAAC;IACF,CAAC;AACF,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,cAAc,CAAC,MAAoB;IAC3C,KAAK,MAAM,OAAO,IAAI,oBAAoB,CAAC,MAAM,CAAC,EAAE,CAAC;QACpD,IAAI,CAAC;YACJ,MAAM,IAAI,GAAG,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAC3C,IAAI,IAAI,EAAE,MAAM,KAAK,IAAI,EAAE,CAAC;gBAC3B,OAAO,IAAI,CAAC;YACb,CAAC;QACF,CAAC;QACD,MAAM,CAAC;YACN,8EAA8E;YAC9E,0CAA0C;YAC1C,MAAM;QACP,CAAC;IACF,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC;AAED,wEAAwE;AACxE,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@pawells/config",
   "displayName": "Config",
-  "version": "2.3.1",
+  "version": "3.0.1",
   "description": "Type-safe configuration management with environment variable loading and validation",
   "keywords": [
     "config",
     "configuration",
-    "environment",
+    "schema",
+    "validation",
+    "zod",
+    "secrets",
     "typescript",
     "nodejs"
   ],
@@ -15,9 +18,14 @@
     "name": "Phillip Aaron Wells",
     "email": "69355326+PhillipAWells@users.noreply.github.com"
   },
-  "homepage": "https://github.com/PhillipAWells/common",
+  "homepage": "https://github.com/PhillipAWells/config",
+  "bugs": {
+    "url": "https://github.com/PhillipAWells/config/issues"
+  },
   "repository": {
-    "url": "https://github.com/PhillipAWells/common.git"
+    "type": "git",
+    "url": "https://github.com/PhillipAWells/config.git",
+    "directory": "packages/config"
   },
   "funding": {
     "type": "github",
@@ -27,12 +35,11 @@
     "node": ">=22.0.0"
   },
   "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     "./package.json": "./package.json",
     ".": {
+      "local": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
@@ -40,12 +47,19 @@
   },
   "files": [
     "dist",
-    "CHANGELOG.md",
     "!**/*.tsbuildinfo",
     "LICENSE"
   ],
+  "sideEffects": false,
+  "scripts": {
+    "test:coverage": "yarn nx test config -- --coverage"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
+    "@pawells/typescript-common": "^3.0.5",
     "tslib": "^2.8.1",
     "zod": "^4.4.3"
   }
-}
+}

package/CHANGELOG.md

@@ -1,19 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-[Unreleased]: https://github.com/PhillipAWells/common/compare/v2.3.0...HEAD
-
-## [2.3.0] - 2026-06-01
-
-### Added
-
-- **Secret** — `Secret<T>` wrapper type for marking config values as sensitive; `IsSecret()` type guard for runtime detection; `GetSecretKeys()` for retrieving all secret field names from a config object; `Redact()` for producing a copy of a config with all secret values masked
-- **ConfigManager.GenerateEnv** — new method for serializing a registered config to `.env` file format, with options to target specific keys and to unmask secret values
-
-[2.3.0]: https://github.com/PhillipAWells/common/releases/tag/v2.3.0