@pawells/config 2.1.7 → 2.3.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# 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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phillip Aaron Wells
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/errors.d.ts

@@ -1,10 +1,8 @@
 /**
  * Custom error classes for configuration management.
  *
- * @throws {ConfigurationAlreadyRegisteredError} When a configuration key is registered twice
- * @throws {ConfigurationNotRegisteredError} When accessing an unregistered configuration key
- * @throws {ConfigurationError} When configuration validation fails
- * @throws {ConfigurationNotSetError} When a required configuration value is not set
+ * Exports: {@link ConfigurationAlreadyRegisteredError}, {@link ConfigurationNotRegisteredError},
+ * {@link ConfigurationError}, and {@link ConfigurationNotSetError}.
  */
 /**
  * Abstract base class for configuration errors.

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;GAGG;AACH,uBAAe,sBAAuB,SAAQ,KAAK;IAClD,kBAAyB,IAAI,EAAE,MAAM,CAAC;gBAE1B,OAAO,EAAE,MAAM;CAI3B;AAED;;;;;;;GAOG;AACH,qBAAa,mCAAoC,SAAQ,sBAAsB;IAC9E,SAAgB,IAAI,sCAAsC;gBAE9C,GAAG,EAAE,MAAM;CAGvB;AAED;;;;;;;GAOG;AACH,qBAAa,+BAAgC,SAAQ,sBAAsB;IAC1E,SAAgB,IAAI,kCAAkC;gBAE1C,GAAG,EAAE,MAAM;CAGvB;AAED;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,SAAQ,sBAAsB;IAC7D,SAAgB,IAAI,yBAAyB;gBAEjC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAMrE;AAED;;;;;;;GAOG;AACH,qBAAa,wBAAyB,SAAQ,sBAAsB;IACnE,SAAgB,IAAI,2BAA2B;gBAEnC,GAAG,EAAE,MAAM;CAGvB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,uBAAe,sBAAuB,SAAQ,KAAK;IAClD,kBAAyB,IAAI,EAAE,MAAM,CAAC;gBAE1B,OAAO,EAAE,MAAM;CAI3B;AAED;;;;;;;GAOG;AACH,qBAAa,mCAAoC,SAAQ,sBAAsB;IAC9E,SAAgB,IAAI,sCAAsC;gBAE9C,GAAG,EAAE,MAAM;CAGvB;AAED;;;;;;;GAOG;AACH,qBAAa,+BAAgC,SAAQ,sBAAsB;IAC1E,SAAgB,IAAI,kCAAkC;gBAE1C,GAAG,EAAE,MAAM;CAGvB;AAED;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,SAAQ,sBAAsB;IAC7D,SAAgB,IAAI,yBAAyB;gBAEjC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAMrE;AAED;;;;;;;GAOG;AACH,qBAAa,wBAAyB,SAAQ,sBAAsB;IACnE,SAAgB,IAAI,2BAA2B;gBAEnC,GAAG,EAAE,MAAM;CAGvB"}

package/dist/errors.js

@@ -1,10 +1,8 @@
 /**
  * Custom error classes for configuration management.
  *
- * @throws {ConfigurationAlreadyRegisteredError} When a configuration key is registered twice
- * @throws {ConfigurationNotRegisteredError} When accessing an unregistered configuration key
- * @throws {ConfigurationError} When configuration validation fails
- * @throws {ConfigurationNotSetError} When a required configuration value is not set
+ * Exports: {@link ConfigurationAlreadyRegisteredError}, {@link ConfigurationNotRegisteredError},
+ * {@link ConfigurationError}, and {@link ConfigurationNotSetError}.
  */
 /**
  * Abstract base class for configuration errors.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './errors.js';
 export * from './manager.js';
 export * from './schema.factory.js';
+export { Secret } from './secret.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from './errors.js';
 export * from './manager.js';
 export * from './schema.factory.js';
+export { Secret } from './secret.js';

package/dist/manager.d.ts

@@ -1,8 +1,25 @@
 import { z } from 'zod/v4';
+/**
+ * Zod schema for all supported configuration value types.
+ * Accepts string, number, boolean, Date, string[], number[], boolean[], and undefined — nullable and optional.
+ */
 export declare const CONFIG_VALUES_TYPES_SCHEMA: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodDate, z.ZodArray<z.ZodString>, z.ZodArray<z.ZodNumber>, z.ZodArray<z.ZodBoolean>, z.ZodUndefined]>>>;
+/**
+ * Asserts that a value conforms to the supported configuration value types.
+ *
+ * @param value - The value to assert
+ * @throws {ZodError} If the value does not match any supported type
+ * @example
+ * AssertConfigValueType('hello'); // passes
+ * AssertConfigValueType(42);      // passes
+ * AssertConfigValueType({});      // throws ZodError
+ */
 export declare function AssertConfigValueType(value: unknown): asserts value is TConfigValueTypes;
+/** Union of all supported configuration value types. */
 export type TConfigValueTypes = z.infer<typeof CONFIG_VALUES_TYPES_SCHEMA>;
+/** Map of configuration keys to their typed values. */
 export type TConfig = Map<string, TConfigValueTypes>;
+/** Identifies whether a configuration value comes from the registered default or a runtime override. */
 export type TConfigSource = 'DEFAULT' | 'OVERRIDE';
 /**
  * Runtime configuration manager with Zod schema validation.
@@ -31,14 +48,15 @@ export declare class ConfigManager {
      * @param defaultValue - Initial value for the configuration key, must satisfy the schema
      * @throws {ConfigurationAlreadyRegisteredError} If key is already registered
      * @example
-     * manager.register('PORT', z.coerce.number().positive());
-     * manager.register('JWT_SECRET', z.string().min(32));
+     * ConfigManager.Register('PORT', z.coerce.number().positive(), 3000);
+     * ConfigManager.Register('JWT_SECRET', z.string().min(32), 'default-secret');
      */
     static Register(key: string, schema: z.ZodType<TConfigValueTypes>, defaultValue: unknown): void;
     /**
      * Set a configuration value and validate against its schema.
      * @param key - Configuration key
      * @param value - Value to set and validate
+     * @param target - Whether to set the default store or the override store; defaults to `'OVERRIDE'`
      * @throws {ConfigurationNotRegisteredError} If schema is not registered for key
      * @throws {ConfigurationError} If validation fails
      * @example
@@ -50,6 +68,7 @@ export declare class ConfigManager {
      * Retrieve a configuration value by key.
      * Returns the value parsed by its registered schema.
      * @param key - Configuration key
+     * @param source - Optional — filter to a specific store (`'DEFAULT'` or `'OVERRIDE'`); omit to return the resolved value (overrides take precedence over defaults)
      * @returns The typed configuration value
      * @throws {ConfigurationNotSetError} If value was not set
      * @throws {ConfigurationNotRegisteredError} If schema is not registered
@@ -69,5 +88,40 @@ export declare class ConfigManager {
      * const parsed = schema.safeParse(value);
      */
     static GetSchema(key: string): z.ZodTypeAny;
+    /**
+     * Generates a `.env` file string from all currently registered configuration keys.
+     *
+     * In template mode (default), each key is emitted with its registered default value.
+     * Secret fields (marked with `Secret()`) are always emitted with a blank value in template
+     * mode, regardless of their registered default.
+     * In current-values mode, the live resolved value from `Get(key)` is used; keys that are
+     * unset or produce a configuration error are emitted as commented-out blank lines (`# KEY=`).
+     *
+     * If a field has a Zod `.describe()` annotation, it is emitted as a `# comment` line
+     * immediately before the key–value pair.
+     *
+     * @param options - Optional configuration for generation behavior
+     * @param options.useCurrentValues - When `true`, emit current live values from `Get(key)`.
+     *   Defaults to `false` (template mode using registered defaults).
+     * @param options.path - When provided, write the generated string to this file path in UTF-8.
+     * @returns - The generated `.env` content as a string.
+     *
+     * @example
+     * ```typescript
+     * // Template mode — defaults shown, secrets blank
+     * const template = ConfigManager.GenerateEnv();
+     * // "APP_HOST=localhost\nAPP_PORT=3000\nAPP_SECRET_KEY="
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Save current runtime settings to a file
+     * ConfigManager.GenerateEnv({ useCurrentValues: true, path: '.env.snapshot' });
+     * ```
+     */
+    static GenerateEnv(options?: {
+        useCurrentValues?: boolean;
+        path?: string;
+    }): string;
 }
 //# sourceMappingURL=manager.d.ts.map

package/dist/manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAG3B,eAAO,MAAM,0BAA0B,oMASf,CAAC;AACzB,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,iBAAiB,CAExF;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC3E,MAAM,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AACrD,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,UAAU,CAAC;AAEnD;;;;;;;;GAQG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAwC;IAGxE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAsB;IAG3D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAsB;IAG5D,OAAO,CAAC,MAAM,KAAK,KAAK,GAMvB;IAED;;;OAGG;WACW,KAAK,IAAI,IAAI;IAM3B,OAAO;IAEP;;;;;;;;;OASG;WACW,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,YAAY,EAAE,OAAO,GAAG,IAAI;IAUtG;;;;;;;;;OASG;WACW,GAAG,CAAC,CAAC,SAAS,iBAAiB,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,GAAE,aAA0B,GAAG,IAAI;IAkB/G;;;;;;;;;;;OAWG;WACW,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,iBAAiB;IAgBzE;;;;;;;;OAQG;WACW,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC,UAAU;CAKlD"}
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAI3B;;;GAGG;AACH,eAAO,MAAM,0BAA0B,oMASf,CAAC;AAEzB;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,iBAAiB,CAExF;AAED,wDAAwD;AACxD,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE3E,uDAAuD;AACvD,MAAM,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAErD,wGAAwG;AACxG,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,UAAU,CAAC;AA8CnD;;;;;;;;GAQG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAwC;IAGxE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAsB;IAG3D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAsB;IAG5D,OAAO,CAAC,MAAM,KAAK,KAAK,GAMvB;IAED;;;OAGG;WACW,KAAK,IAAI,IAAI;IAM3B,OAAO;IAEP;;;;;;;;;OASG;WACW,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,YAAY,EAAE,OAAO,GAAG,IAAI;IAUtG;;;;;;;;;;OAUG;WACW,GAAG,CAAC,CAAC,SAAS,iBAAiB,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,GAAE,aAA0B,GAAG,IAAI;IAkB/G;;;;;;;;;;;;OAYG;WACW,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,iBAAiB;IAgBzE;;;;;;;;OAQG;WACW,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC,UAAU;IAMlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;WACW,WAAW,CAAC,OAAO,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM;CA6C1F"}

package/dist/manager.js

@@ -1,5 +1,11 @@
+import { writeFileSync } from 'node:fs';
 import { z } from 'zod/v4';
 import { ConfigurationAlreadyRegisteredError, ConfigurationNotRegisteredError, ConfigurationError, ConfigurationNotSetError } from './errors.js';
+import { IsMarkedSecret } from './secret.js';
+/**
+ * Zod schema for all supported configuration value types.
+ * Accepts string, number, boolean, Date, string[], number[], boolean[], and undefined — nullable and optional.
+ */
 export const CONFIG_VALUES_TYPES_SCHEMA = z.union([
     z.string(),
     z.number(),
@@ -10,9 +16,60 @@ export const CONFIG_VALUES_TYPES_SCHEMA = z.union([
     z.array(z.boolean()),
     z.undefined(),
 ]).nullable().optional();
+/**
+ * Asserts that a value conforms to the supported configuration value types.
+ *
+ * @param value - The value to assert
+ * @throws {ZodError} If the value does not match any supported type
+ * @example
+ * AssertConfigValueType('hello'); // passes
+ * AssertConfigValueType(42);      // passes
+ * AssertConfigValueType({});      // throws ZodError
+ */
 export function AssertConfigValueType(value) {
     CONFIG_VALUES_TYPES_SCHEMA.parse(value);
 }
+/**
+ * Traverses the Zod schema's innerType chain to find a description in globalRegistry.
+ *
+ * @param schema - Zod schema to inspect
+ * @returns - The description string if found, otherwise undefined
+ * @internal
+ */
+function GetFieldDescription(schema) {
+    let current = schema;
+    while (current != null) {
+        try {
+            const meta = z.globalRegistry.get(current);
+            if (typeof meta?.description === 'string') {
+                return meta.description;
+            }
+        }
+        catch {
+            break;
+        }
+        current = current._def?.innerType;
+    }
+    return undefined;
+}
+/**
+ * Serializes a configuration value to its .env string representation.
+ * Arrays are JSON-stringified; Dates use ISO 8601; all others use String().
+ * Returns '' for null or undefined.
+ *
+ * @param value - The configuration value to serialize
+ * @returns - Serialized string representation
+ * @internal
+ */
+function SerializeConfigValue(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (Array.isArray(value))
+        return JSON.stringify(value);
+    if (value instanceof Date)
+        return value.toISOString();
+    return String(value);
+}
 /**
  * Runtime configuration manager with Zod schema validation.
  * Provides a singleton instance to register and retrieve typed configuration values.
@@ -53,8 +110,8 @@ export class ConfigManager {
      * @param defaultValue - Initial value for the configuration key, must satisfy the schema
      * @throws {ConfigurationAlreadyRegisteredError} If key is already registered
      * @example
-     * manager.register('PORT', z.coerce.number().positive());
-     * manager.register('JWT_SECRET', z.string().min(32));
+     * ConfigManager.Register('PORT', z.coerce.number().positive(), 3000);
+     * ConfigManager.Register('JWT_SECRET', z.string().min(32), 'default-secret');
      */
     static Register(key, schema, defaultValue) {
         // Ensure key is unique, but it's fine when the schemas match.
@@ -71,6 +128,7 @@ export class ConfigManager {
      * Set a configuration value and validate against its schema.
      * @param key - Configuration key
      * @param value - Value to set and validate
+     * @param target - Whether to set the default store or the override store; defaults to `'OVERRIDE'`
      * @throws {ConfigurationNotRegisteredError} If schema is not registered for key
      * @throws {ConfigurationError} If validation fails
      * @example
@@ -99,6 +157,7 @@ export class ConfigManager {
      * Retrieve a configuration value by key.
      * Returns the value parsed by its registered schema.
      * @param key - Configuration key
+     * @param source - Optional — filter to a specific store (`'DEFAULT'` or `'OVERRIDE'`); omit to return the resolved value (overrides take precedence over defaults)
      * @returns The typed configuration value
      * @throws {ConfigurationNotSetError} If value was not set
      * @throws {ConfigurationNotRegisteredError} If schema is not registered
@@ -138,4 +197,76 @@ export class ConfigManager {
             throw new ConfigurationNotRegisteredError(key);
         return schema;
     }
+    /**
+     * Generates a `.env` file string from all currently registered configuration keys.
+     *
+     * In template mode (default), each key is emitted with its registered default value.
+     * Secret fields (marked with `Secret()`) are always emitted with a blank value in template
+     * mode, regardless of their registered default.
+     * In current-values mode, the live resolved value from `Get(key)` is used; keys that are
+     * unset or produce a configuration error are emitted as commented-out blank lines (`# KEY=`).
+     *
+     * If a field has a Zod `.describe()` annotation, it is emitted as a `# comment` line
+     * immediately before the key–value pair.
+     *
+     * @param options - Optional configuration for generation behavior
+     * @param options.useCurrentValues - When `true`, emit current live values from `Get(key)`.
+     *   Defaults to `false` (template mode using registered defaults).
+     * @param options.path - When provided, write the generated string to this file path in UTF-8.
+     * @returns - The generated `.env` content as a string.
+     *
+     * @example
+     * ```typescript
+     * // Template mode — defaults shown, secrets blank
+     * const template = ConfigManager.GenerateEnv();
+     * // "APP_HOST=localhost\nAPP_PORT=3000\nAPP_SECRET_KEY="
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Save current runtime settings to a file
+     * ConfigManager.GenerateEnv({ useCurrentValues: true, path: '.env.snapshot' });
+     * ```
+     */
+    static GenerateEnv(options) {
+        const useCurrentValues = options?.useCurrentValues ?? false;
+        const lines = [];
+        for (const [key, schema] of this._Schemas) {
+            const description = GetFieldDescription(schema);
+            const isSecret = IsMarkedSecret(schema);
+            if (description != null) {
+                lines.push(`# ${description}`);
+            }
+            if (useCurrentValues) {
+                try {
+                    const value = this.Get(key);
+                    lines.push(`${key}=${SerializeConfigValue(value)}`);
+                }
+                catch (e) {
+                    if (e instanceof ConfigurationNotSetError ||
+                        e instanceof ConfigurationNotRegisteredError ||
+                        e instanceof ConfigurationError) {
+                        lines.push(`# ${key}=`);
+                    }
+                    else {
+                        throw e;
+                    }
+                }
+            }
+            else {
+                if (isSecret) {
+                    lines.push(`${key}=`);
+                }
+                else {
+                    const defaultValue = this._DataDefaults.get(key);
+                    lines.push(`${key}=${SerializeConfigValue(defaultValue)}`);
+                }
+            }
+        }
+        const result = lines.join('\n');
+        if (options?.path != null) {
+            writeFileSync(options.path, result, 'utf8');
+        }
+        return result;
+    }
 }

package/dist/schema.factory.d.ts

@@ -56,11 +56,64 @@ export interface IConfigSchemaObject<TConfig extends Record<string, unknown>, TK
      * Parse environment variables matching the prefix and set them as overrides.
      * Logs warnings for invalid values but continues processing remaining vars.
      *
+     * @remarks
+     * The concrete implementation also accepts an optional `throwOnError` boolean parameter
+     * (defaulting to `false`) that is not exposed in this interface.
+     *
      * @example
      * MongoDBConfig.ParseENV();
      * // Reads MONGODB_HOST, MONGODB_PORT, etc. from process.env
      */
     ParseENV(): void;
+    /**
+     * Returns whether the given key was marked as a secret field using Secret().
+     *
+     * @param key - The configuration key to check
+     * @returns true if the key was marked with Secret() at schema construction time
+     */
+    IsSecret(key: TKeys): boolean;
+    /**
+     * Returns an array of all keys that were marked as secret using Secret(),
+     * in schema shape insertion order.
+     *
+     * @returns Array of secret key names
+     */
+    GetSecretKeys(): Array<TKeys>;
+    /**
+     * Returns a snapshot of all currently resolved config values where secret
+     * fields are replaced with '***'. Keys that have not been registered yet
+     * are omitted from the result.
+     *
+     * @returns Record of config values with secrets redacted
+     */
+    Redact(): Record<string, unknown>;
 }
+/**
+ * Creates a configuration schema object from a Zod schema and prefix.
+ *
+ * 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.
+ *
+ * @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
+ *
+ * @example
+ * ```typescript
+ * const MONGODB_SCHEMA = z.object({
+ *   HOST: z.string().default('localhost'),
+ *   PORT: z.number().default(27017),
+ * });
+ *
+ * export const MongoDBConfig = createConfigSchema(MONGODB_SCHEMA, 'MONGODB_');
+ * // Usage:
+ * // MongoDBConfig.Register();
+ * // const host = MongoDBConfig.Get('HOST');
+ * // MongoDBConfig.Set('PORT', 27018);
+ * // MongoDBConfig.ParseENV();
+ * ```
+ */
 export declare function CreateConfigSchema<TSchema extends z.ZodRawShape>(schema: z.ZodObject<TSchema>, prefix: string): IConfigSchemaObject<z.infer<typeof schema>>;
 //# sourceMappingURL=schema.factory.d.ts.map

package/dist/schema.factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.factory.d.ts","sourceRoot":"","sources":["../src/schema.factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AA0BjE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB,CACnC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,KAAK,SAAS,MAAM,OAAO,GAAG,MAAM,OAAO;IAE3C;;;OAGG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB;;;;;;;;;;OAUG;IACH,GAAG,CAAC,CAAC,SAAS,KAAK,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAEzC;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,CAAC,SAAS,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IAE9E;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,CAAC,SAAS,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAE3D;;;;;;;OAOG;IACH,QAAQ,IAAI,IAAI,CAAC;CACjB;AA+CD,wBAAgB,kBAAkB,CAAC,OAAO,SAAS,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,mBAAmB,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC,CAkE3J"}
+{"version":3,"file":"schema.factory.d.ts","sourceRoot":"","sources":["../src/schema.factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AA4BjE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB,CACnC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,KAAK,SAAS,MAAM,OAAO,GAAG,MAAM,OAAO;IAE3C;;;OAGG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB;;;;;;;;;;OAUG;IACH,GAAG,CAAC,CAAC,SAAS,KAAK,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAEzC;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,CAAC,SAAS,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IAE9E;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,CAAC,SAAS,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAE3D;;;;;;;;;;;OAWG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,KAAK,GAAG,OAAO,CAAC;IAE9B;;;;;OAKG;IACH,aAAa,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC;IAE9B;;;;;;OAMG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,SAAS,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,mBAAmB,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC,CAqG3J"}

package/dist/schema.factory.js

@@ -1,4 +1,6 @@
 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).
@@ -22,6 +24,23 @@ function ParseEnvVarValue(envVarValue) {
         return envVarValue;
     }
 }
+/**
+ * Safely extracts the default value from a Zod schema, handling both
+ * lazy defaults (functions) and eager defaults (plain values).
+ *
+ * @param schema - The field schema to extract the default from
+ * @returns The evaluated default value, or undefined if not present
+ */
+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;
+}
 /**
  * Creates a configuration schema object from a Zod schema and prefix.
  *
@@ -49,23 +68,6 @@ function ParseEnvVarValue(envVarValue) {
  * // MongoDBConfig.ParseENV();
  * ```
  */
-/**
- * Safely extracts the default value from a Zod schema, handling both
- * lazy defaults (functions) and eager defaults (plain values).
- *
- * @param schema - The field schema to extract the default from
- * @returns The evaluated default value, or undefined if not present
- */
-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;
-}
 export function CreateConfigSchema(schema, prefix) {
     // Build a map of key -> prefixed name
     const prefixedNames = {};
@@ -74,6 +76,8 @@ export function CreateConfigSchema(schema, prefix) {
             prefixedNames[key] = `${prefix}${key}`;
         }
     }
+    // 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) {
@@ -124,5 +128,29 @@ export function CreateConfigSchema(schema, prefix) {
                 }
             }
         },
+        IsSecret(key) {
+            return secretKeys.has(key);
+        },
+        GetSecretKeys() {
+            return Array.from(secretKeys);
+        },
+        Redact() {
+            const result = {};
+            for (const key of Object.keys(schema.shape)) {
+                try {
+                    const value = this.Get(key);
+                    result[key] = secretKeys.has(key) ? '***' : value;
+                }
+                catch (error) {
+                    if (error instanceof ConfigurationNotSetError ||
+                        error instanceof ConfigurationNotRegisteredError) {
+                        // omit unregistered/unset keys
+                        continue;
+                    }
+                    throw error;
+                }
+            }
+            return result;
+        },
     };
 }

package/dist/secret.d.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod/v4';
+/**
+ * Marks a Zod schema as secret using Zod v4's globalRegistry metadata system.
+ * This allows configuration to automatically detect sensitive fields that should
+ * not be logged or exposed in output.
+ *
+ * The inferred TypeScript type of the schema is unchanged by this operation.
+ * The metadata is stored in Zod's global registry for retrieval by validation logic.
+ *
+ * @param schema - The Zod schema to mark as secret
+ * @returns The same schema type with secret metadata registered
+ *
+ * @remarks
+ * The inferred TypeScript type is unchanged and will not affect type inference
+ * for values validated by this schema. CreateConfigSchema automatically detects
+ * this marker via the IsMarkedSecret helper to handle sensitive fields specially.
+ *
+ * @example
+ * ```typescript
+ * // Mark a simple string as secret
+ * const secretToken = Secret(z.string());
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Mark a chained schema with constraints
+ * const apiKey = Secret(z.string().min(32)).default('');
+ * ```
+ */
+export declare function Secret<T extends z.ZodTypeAny>(schema: T): T;
+/**
+ * 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,
+ * ZodOptional) and checks each level's metadata in the global registry.
+ *
+ * @param schema - The Zod schema to check for secret metadata
+ * @returns true if the schema or any of its inner schemas has secret=true metadata
+ * @internal
+ */
+declare function IsMarkedSecret(schema: z.ZodTypeAny): boolean;
+export { IsMarkedSecret };
+//# sourceMappingURL=secret.d.ts.map

package/dist/secret.d.ts.map

@@ -0,0 +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"}

package/dist/secret.js

@@ -0,0 +1,65 @@
+import { z } from 'zod/v4';
+/**
+ * Marks a Zod schema as secret using Zod v4's globalRegistry metadata system.
+ * This allows configuration to automatically detect sensitive fields that should
+ * not be logged or exposed in output.
+ *
+ * The inferred TypeScript type of the schema is unchanged by this operation.
+ * The metadata is stored in Zod's global registry for retrieval by validation logic.
+ *
+ * @param schema - The Zod schema to mark as secret
+ * @returns The same schema type with secret metadata registered
+ *
+ * @remarks
+ * The inferred TypeScript type is unchanged and will not affect type inference
+ * for values validated by this schema. CreateConfigSchema automatically detects
+ * this marker via the IsMarkedSecret helper to handle sensitive fields specially.
+ *
+ * @example
+ * ```typescript
+ * // Mark a simple string as secret
+ * const secretToken = Secret(z.string());
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Mark a chained schema with constraints
+ * const apiKey = Secret(z.string().min(32)).default('');
+ * ```
+ */
+export function Secret(schema) {
+    const existingMeta = z.globalRegistry.get(schema) ?? {};
+    return schema.meta({ ...existingMeta, secret: true });
+}
+/**
+ * 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,
+ * ZodOptional) and checks each level's metadata in the global registry.
+ *
+ * @param schema - The Zod schema to check for secret metadata
+ * @returns true if the schema or any of its inner schemas has secret=true metadata
+ * @internal
+ */
+function IsMarkedSecret(schema) {
+    let current = schema;
+    while (current != null) {
+        try {
+            const meta = z.globalRegistry.get(current);
+            if (meta?.secret === true) {
+                return true;
+            }
+        }
+        catch {
+            // Schema does not support registry lookup (e.g. mock/partial schema objects).
+            // 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;
+}
+// Export for testing and advanced use cases (though marked as internal)
+export { IsMarkedSecret };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pawells/config",
-  "version": "2.1.7",
+  "version": "2.3.0",
   "license": "MIT",
   "author": {
     "name": "Phillip Aaron Wells",
@@ -29,10 +29,36 @@
   },
   "files": [
     "dist",
+    "CHANGELOG.md",
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "tslib": "^2.3.0",
+    "tslib": "^2.8.1",
     "zod": "^4.4.3"
+  },
+  "nx": {
+    "name": "@pawells/config",
+    "tags": [
+      "npm:public"
+    ],
+    "targets": {
+      "publish": {
+        "executor": "nx:run-commands",
+        "options": {
+          "command": "npm publish --provenance --access public",
+          "cwd": "{projectRoot}"
+        },
+        "dependsOn": [
+          "build"
+        ]
+      },
+      "clean": {
+        "executor": "nx:run-commands",
+        "options": {
+          "command": "rm -rf dist tsconfig.*.tsbuildinfo",
+          "cwd": "packages/typescript-common"
+        }
+      }
+    }
   }
 }