@pawells/config 2.1.6-rc1

package/README.md

@@ -0,0 +1,200 @@
+# @pawells/config
+
+[![CI](https://github.com/PhillipAWells/common/actions/workflows/ci.yml/badge.svg)](https://github.com/PhillipAWells/common/actions/workflows/ci.yml)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
+[![npm version](https://img.shields.io/npm/v/@pawells/config.svg)](https://www.npmjs.com/package/@pawells/config)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+## Description
+
+Runtime configuration manager with Zod schema validation. Provides a singleton `ConfigManager` class for registering typed configuration schemas, setting values from multiple sources (defaults and runtime overrides), and retrieving strongly-typed configuration values with automatic validation. Supports environment variables, CLI arguments, and programmatic configuration.
+
+## Requirements
+
+- **Node.js**: 22.0.0 or later
+- **TypeScript**: 6.0.0 or later (if consuming from source)
+
+## Installation
+
+Install from npm:
+
+```bash
+npm install @pawells/config
+```
+
+Or with yarn:
+
+```bash
+yarn add @pawells/config
+```
+
+## Quick Start
+
+### Using CreateConfigSchema (Recommended)
+
+The `CreateConfigSchema` factory is the recommended pattern for most use cases. It provides automatic environment variable parsing with a prefix and strongly-typed access to configuration values.
+
+```typescript
+import { z } from 'zod/v4';
+import { CreateConfigSchema } from '@pawells/config';
+
+// Define your configuration schema
+const SERVICE_CONFIG_SCHEMA = z.object({
+  PORT: z.coerce.number().int().positive().default(3000),
+  HOST: z.string().default('localhost'),
+  DEBUG: z.boolean().default(false),
+  DATABASE_URL: z.string().url(),
+  API_TIMEOUT: z.coerce.number().int().positive().default(30000),
+});
+
+// Create a typed config object with 'SERVICE_' prefix
+export const ServiceConfig = CreateConfigSchema(SERVICE_CONFIG_SCHEMA, 'SERVICE_');
+
+// Register all schemas
+ServiceConfig.Register();
+
+// Parse environment variables (SERVICE_PORT, SERVICE_HOST, SERVICE_DEBUG, etc.)
+ServiceConfig.ParseENV();
+
+// Get typed values
+const port = ServiceConfig.Get('PORT'); // number, typed
+const host = ServiceConfig.Get('HOST'); // string, typed
+const debug = ServiceConfig.Get('DEBUG'); // boolean, typed
+
+console.log(`Server running on ${host}:${port}`);
+```
+
+### Retrieving and Validating Values
+
+```typescript
+// Get a typed configuration value (guaranteed type-safe)
+const timeout = ServiceConfig.Get('API_TIMEOUT'); // number
+
+// Validate a value before setting it
+const isValid = ServiceConfig.Validate('PORT', '8080'); // true if valid
+
+// Set configuration values at runtime
+ServiceConfig.Set('DEBUG', true, 'OVERRIDE');
+```
+
+### Advanced: Using ConfigManager Directly
+
+For advanced scenarios where you need direct schema control or custom management, use `ConfigManager`:
+
+```typescript
+import { ConfigManager } from '@pawells/config';
+import { z } from 'zod/v4';
+
+// Register individual schemas
+ConfigManager.Register('DATABASE_URL', z.string().url(), 'postgresql://localhost/mydb');
+ConfigManager.Register('API_KEY', z.string().min(32), 'default-key');
+
+// Set and retrieve values
+ConfigManager.Set('DATABASE_URL', process.env.DATABASE_URL);
+const dbUrl = ConfigManager.Get('DATABASE_URL');
+```
+
+### Error Handling
+
+```typescript
+import {
+  ConfigurationNotRegisteredError,
+  ConfigurationNotSetError,
+  ConfigurationError,
+} from '@pawells/config';
+
+try {
+  // Attempt to retrieve a value
+  const value = ServiceConfig.Get('UNKNOWN_KEY');
+} catch (error) {
+  if (error instanceof ConfigurationNotRegisteredError) {
+    console.error('Configuration key not registered:', error.message);
+  }
+  if (error instanceof ConfigurationNotSetError) {
+    console.error('Configuration value not set:', error.message);
+  }
+  if (error instanceof ConfigurationError) {
+    console.error('Validation failed:', error.message);
+  }
+}
+```
+
+## API Reference
+
+### CreateConfigSchema Factory (Recommended)
+
+The `CreateConfigSchema` factory is the primary recommended API for most use cases. It creates a strongly-typed configuration schema object from a Zod schema.
+
+**Signature:**
+```typescript
+CreateConfigSchema<TSchema extends z.ZodRawShape>(
+  schema: z.ZodObject<TSchema>,
+  prefix: string
+): IConfigSchemaObject<z.infer<typeof schema>>
+```
+
+**Parameters:**
+- `schema` — A Zod object schema defining your configuration structure
+- `prefix` — Environment variable prefix (e.g., `'SERVICE_'` for `SERVICE_PORT`, `SERVICE_HOST`)
+
+**Returns:** An `IConfigSchemaObject` with strongly-typed methods for configuration management.
+
+### IConfigSchemaObject Methods
+
+These methods are returned by `CreateConfigSchema` and provide a strongly-typed interface to your configuration.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `Register` | `Register(): void` | Register all schema fields with `ConfigManager`, extracting default values from the schema. Call once at application startup. |
+| `Get` | `Get<K extends TKeys>(key: K): TConfig[K]` | Retrieve a typed configuration value by key. The return type is automatically inferred from your schema. |
+| `Set` | `Set<K extends TKeys>(key: K, value: TConfig[K], source?: TConfigSource): void` | Set a configuration value with optional source (`'DEFAULT'` or `'OVERRIDE'`, defaults to `'OVERRIDE'`). Validates the value against the schema. |
+| `Validate` | `Validate<K extends TKeys>(key: K, value: unknown): boolean` | Validate a value against its schema without setting it. Returns `true` if valid, `false` otherwise. |
+| `ParseENV` | `ParseENV(): void` | Parse environment variables matching the configured prefix and set them as overrides. Prefixed variables are automatically discovered and parsed according to the schema. |
+
+### ConfigManager (Advanced)
+
+For advanced scenarios requiring direct schema control or custom configuration management, use `ConfigManager` directly:
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `Register` | `Register(key: string, schema: ZodType, defaultValue: unknown): void` | Register a configuration key with a Zod schema and default value. Validates the default value against the schema. |
+| `Set` | `Set<T>(key: string, value: T, target?: 'DEFAULT' \| 'OVERRIDE'): void` | Set a configuration value and validate against its schema. Default target is 'OVERRIDE'. |
+| `Get` | `Get(key: string, source?: 'DEFAULT' \| 'OVERRIDE'): TConfigValueTypes` | Retrieve a configuration value by key, validated against its schema. Returns resolved value merging defaults and overrides. |
+| `GetSchema` | `GetSchema(key: string): ZodTypeAny` | Retrieve the Zod schema for a configuration key for custom validation. |
+| `Reset` | `Reset(): void` | Clear all registered schemas and values (for testing). Internal API. |
+
+### Error Types
+
+| Error | Description |
+|-------|-------------|
+| `ConfigurationAlreadyRegisteredError` | Thrown when attempting to register a key that already exists with a different schema. |
+| `ConfigurationNotRegisteredError` | Thrown when accessing or setting a key that was not registered with a schema. |
+| `ConfigurationError` | Thrown when configuration validation fails during registration, set, or get operations. Includes cause chain from Zod validation errors. |
+| `ConfigurationNotSetError` | Thrown when retrieving a configuration value that was never set. |
+
+### Type Exports
+
+| Type | Description |
+|------|-------------|
+| `TConfigValueTypes` | Union type of all supported configuration value types: `string`, `number`, `boolean`, `Date`, `string[]`, `number[]`, `boolean[]`, `undefined`, or `null`. |
+| `TConfig` | Internal map type: `Map<string, TConfigValueTypes>`. |
+| `TConfigSource` | Literal union type: `'DEFAULT'` or `'OVERRIDE'`. Controls which source layer a value is stored in or retrieved from. |
+
+> **⚠️ Security Warning**
+>
+> Do not store sensitive values (API keys, database passwords, tokens, PII) directly as string literals in your code. Always load sensitive configuration from environment variables or secure vaults at startup.
+>
+> When storing environment variable overrides, ensure the process environment itself is protected from inspection (e.g., via debugger or memory dumps).
+>
+> Example:
+> ```typescript
+> // ✓ Good: Load from environment at startup
+> ConfigManager.Set('DATABASE_PASSWORD', process.env.DB_PASSWORD);
+>
+> // ✗ Bad: Hardcoded secrets
+> ConfigManager.Register('DATABASE_PASSWORD', z.string(), 'hardcoded-password');
+> ```
+
+## License
+
+MIT — See [LICENSE](../../LICENSE) for details.

package/dist/errors.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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
+ */
+/**
+ * Abstract base class for configuration errors.
+ * Automatically sets the error name to the class constructor name.
+ */
+declare abstract class ConfigurationBaseError extends Error {
+    abstract readonly Code: string;
+    constructor(message: string);
+}
+/**
+ * Error thrown when attempting to register a configuration key that already exists.
+ *
+ * @param key - The configuration key that was already registered
+ *
+ * @example
+ * throw new ConfigurationAlreadyRegisteredError('DATABASE_URL');
+ */
+export declare class ConfigurationAlreadyRegisteredError extends ConfigurationBaseError {
+    readonly Code = "CONFIGURATION_ALREADY_REGISTERED";
+    constructor(key: string);
+}
+/**
+ * Error thrown when attempting to access a configuration key that was not registered.
+ *
+ * @param key - The configuration key that is not registered
+ *
+ * @example
+ * throw new ConfigurationNotRegisteredError('UNKNOWN_KEY');
+ */
+export declare class ConfigurationNotRegisteredError extends ConfigurationBaseError {
+    readonly Code = "CONFIGURATION_NOT_REGISTERED";
+    constructor(key: string);
+}
+/**
+ * Error thrown when configuration validation fails.
+ *
+ * @param key - The configuration key that failed validation
+ * @param message - Detailed error message about the validation failure
+ * @param options - Optional options object with cause
+ *
+ * @example
+ * throw new ConfigurationError('PORT', 'Must be a positive number');
+ */
+export declare class ConfigurationError extends ConfigurationBaseError {
+    readonly Code = "CONFIGURATION_ERROR";
+    constructor(key: string, message: string, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * Error thrown when a required configuration value is not set.
+ *
+ * @param key - The configuration key that is not set
+ *
+ * @example
+ * throw new ConfigurationNotSetError('DATABASE_URL');
+ */
+export declare class ConfigurationNotSetError extends ConfigurationBaseError {
+    readonly Code = "CONFIGURATION_NOT_SET";
+    constructor(key: string);
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

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

package/dist/errors.js

@@ -0,0 +1,79 @@
+/**
+ * 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
+ */
+/**
+ * Abstract base class for configuration errors.
+ * Automatically sets the error name to the class constructor name.
+ */
+class ConfigurationBaseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+    }
+}
+/**
+ * Error thrown when attempting to register a configuration key that already exists.
+ *
+ * @param key - The configuration key that was already registered
+ *
+ * @example
+ * throw new ConfigurationAlreadyRegisteredError('DATABASE_URL');
+ */
+export class ConfigurationAlreadyRegisteredError extends ConfigurationBaseError {
+    Code = 'CONFIGURATION_ALREADY_REGISTERED';
+    constructor(key) {
+        super(`Configuration key "${key}" is already registered with a different schema.`);
+    }
+}
+/**
+ * Error thrown when attempting to access a configuration key that was not registered.
+ *
+ * @param key - The configuration key that is not registered
+ *
+ * @example
+ * throw new ConfigurationNotRegisteredError('UNKNOWN_KEY');
+ */
+export class ConfigurationNotRegisteredError extends ConfigurationBaseError {
+    Code = 'CONFIGURATION_NOT_REGISTERED';
+    constructor(key) {
+        super(`Configuration key "${key}" is not registered.`);
+    }
+}
+/**
+ * Error thrown when configuration validation fails.
+ *
+ * @param key - The configuration key that failed validation
+ * @param message - Detailed error message about the validation failure
+ * @param options - Optional options object with cause
+ *
+ * @example
+ * throw new ConfigurationError('PORT', 'Must be a positive number');
+ */
+export class ConfigurationError extends ConfigurationBaseError {
+    Code = 'CONFIGURATION_ERROR';
+    constructor(key, message, options) {
+        super(`Validation failed for configuration "${key}": ${message}`);
+        if (options?.cause) {
+            this.cause = options.cause;
+        }
+    }
+}
+/**
+ * Error thrown when a required configuration value is not set.
+ *
+ * @param key - The configuration key that is not set
+ *
+ * @example
+ * throw new ConfigurationNotSetError('DATABASE_URL');
+ */
+export class ConfigurationNotSetError extends ConfigurationBaseError {
+    Code = 'CONFIGURATION_NOT_SET';
+    constructor(key) {
+        super(`Configuration key "${key}" is not set.`);
+    }
+}

package/dist/index.d.ts

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

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './errors.js';
+export * from './manager.js';
+export * from './schema.factory.js';

package/dist/manager.d.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod/v4';
+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]>>>;
+export declare function AssertConfigValueType(value: unknown): asserts value is TConfigValueTypes;
+export type TConfigValueTypes = z.infer<typeof CONFIG_VALUES_TYPES_SCHEMA>;
+export type TConfig = Map<string, TConfigValueTypes>;
+export type TConfigSource = 'DEFAULT' | 'OVERRIDE';
+/**
+ * Runtime configuration manager with Zod schema validation.
+ * Provides a singleton instance to register and retrieve typed configuration values.
+ *
+ * @example
+ * ConfigManager.Register('DATABASE_URL', z.string().url(), 'postgresql://localhost/mydb');
+ * ConfigManager.Set('DEFAULT', 'DATABASE_URL', 'postgresql://localhost/mydb');
+ * const url = ConfigManager.Get('DATABASE_URL');
+ */
+export declare class ConfigManager {
+    private static readonly _Schemas;
+    private static readonly _DataDefaults;
+    private static readonly _DataOverrides;
+    private static get _Data();
+    /**
+     * Reset the singleton instance (for testing).
+     * @internal
+     */
+    static Reset(): void;
+    private constructor();
+    /**
+     * Register a configuration schema.
+     * @param key - Unique configuration key
+     * @param schema - Zod schema for runtime validation
+     * @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));
+     */
+    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
+     * @throws {ConfigurationNotRegisteredError} If schema is not registered for key
+     * @throws {ConfigurationError} If validation fails
+     * @example
+     * manager.set('PORT', 3000);
+     * manager.set('JWT_SECRET', process.env.SECRET);
+     */
+    static Set<T extends TConfigValueTypes>(key: string, value: T, target?: TConfigSource): void;
+    /**
+     * Retrieve a configuration value by key.
+     * Returns the value parsed by its registered schema.
+     * @param key - Configuration key
+     * @returns The typed configuration value
+     * @throws {ConfigurationNotSetError} If value was not set
+     * @throws {ConfigurationNotRegisteredError} If schema is not registered
+     * @throws {ConfigurationError} If validation fails on retrieval
+     * @example
+     * const port = manager.get('PORT'); // Returns number, guaranteed by schema
+     * const secret = manager.get('JWT_SECRET'); // Returns string
+     */
+    static Get(key: string, source?: TConfigSource): TConfigValueTypes;
+    /**
+     * Retrieve the schema for a configuration key.
+     * @param key - Configuration key
+     * @returns The Zod schema for this configuration
+     * @throws {ConfigurationNotRegisteredError} If schema is not registered for key
+     * @example
+     * const schema = manager.getSchema('PORT');
+     * const parsed = schema.safeParse(value);
+     */
+    static GetSchema(key: string): z.ZodTypeAny;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/manager.d.ts.map

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

package/dist/manager.js

@@ -0,0 +1,141 @@
+import { z } from 'zod/v4';
+import { ConfigurationAlreadyRegisteredError, ConfigurationNotRegisteredError, ConfigurationError, ConfigurationNotSetError } from './errors.js';
+export const CONFIG_VALUES_TYPES_SCHEMA = z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.date(),
+    z.array(z.string()),
+    z.array(z.number()),
+    z.array(z.boolean()),
+    z.undefined(),
+]).nullable().optional();
+export function AssertConfigValueType(value) {
+    CONFIG_VALUES_TYPES_SCHEMA.parse(value);
+}
+/**
+ * Runtime configuration manager with Zod schema validation.
+ * Provides a singleton instance to register and retrieve typed configuration values.
+ *
+ * @example
+ * ConfigManager.Register('DATABASE_URL', z.string().url(), 'postgresql://localhost/mydb');
+ * ConfigManager.Set('DEFAULT', 'DATABASE_URL', 'postgresql://localhost/mydb');
+ * const url = ConfigManager.Get('DATABASE_URL');
+ */
+export class ConfigManager {
+    static _Schemas = new Map();
+    // Populated at Registration
+    static _DataDefaults = new Map();
+    // Overriden at Runtime from various sources
+    static _DataOverrides = new Map();
+    // Resolved Data
+    static get _Data() {
+        const resolved = new Map(this._DataDefaults);
+        for (const [key, value] of this._DataOverrides) {
+            resolved.set(key, value);
+        }
+        return resolved;
+    }
+    /**
+     * Reset the singleton instance (for testing).
+     * @internal
+     */
+    static Reset() {
+        this._Schemas.clear();
+        this._DataDefaults.clear();
+        this._DataOverrides.clear();
+    }
+    constructor() { }
+    /**
+     * Register a configuration schema.
+     * @param key - Unique configuration key
+     * @param schema - Zod schema for runtime validation
+     * @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));
+     */
+    static Register(key, schema, defaultValue) {
+        // Ensure key is unique, but it's fine when the schemas match.
+        if (this._Schemas.has(key) && this._Schemas.get(key) !== schema)
+            throw new ConfigurationAlreadyRegisteredError(key);
+        const result = schema.safeParse(defaultValue);
+        if (!result.success)
+            throw new ConfigurationError('Registration', `Default value for configuration "${key}" does not match the provided schema.`, { cause: result.error });
+        const parsed = result.data;
+        this._Schemas.set(key, schema);
+        this.Set(key, parsed, 'DEFAULT');
+    }
+    /**
+     * Set a configuration value and validate against its schema.
+     * @param key - Configuration key
+     * @param value - Value to set and validate
+     * @throws {ConfigurationNotRegisteredError} If schema is not registered for key
+     * @throws {ConfigurationError} If validation fails
+     * @example
+     * manager.set('PORT', 3000);
+     * manager.set('JWT_SECRET', process.env.SECRET);
+     */
+    static Set(key, value, target = 'OVERRIDE') {
+        const schema = this._Schemas.get(key);
+        if (!schema)
+            throw new ConfigurationNotRegisteredError(key);
+        try {
+            const parsed = schema.parse(value);
+            AssertConfigValueType(parsed);
+            if (target === 'DEFAULT') {
+                this._DataDefaults.set(key, parsed);
+            }
+            else {
+                this._DataOverrides.set(key, parsed);
+            }
+        }
+        catch (cause) {
+            throw new ConfigurationError(key, cause instanceof Error ? cause.message : String(cause), { cause: cause instanceof Error ? cause : undefined });
+        }
+    }
+    /**
+     * Retrieve a configuration value by key.
+     * Returns the value parsed by its registered schema.
+     * @param key - Configuration key
+     * @returns The typed configuration value
+     * @throws {ConfigurationNotSetError} If value was not set
+     * @throws {ConfigurationNotRegisteredError} If schema is not registered
+     * @throws {ConfigurationError} If validation fails on retrieval
+     * @example
+     * const port = manager.get('PORT'); // Returns number, guaranteed by schema
+     * const secret = manager.get('JWT_SECRET'); // Returns string
+     */
+    static Get(key, source) {
+        const value = source === 'DEFAULT' ? this._DataDefaults.get(key) : source === 'OVERRIDE' ? this._DataOverrides.get(key) : this._Data.get(key);
+        if (value === undefined)
+            throw new ConfigurationNotSetError(key);
+        const schema = this.GetSchema(key);
+        try {
+            // TODO: This will re-parse the value on every retrieval, which may have performance implications. Consider caching parsed values if this becomes an issue.
+            // TODO: Also consider how to handle complex types that may not be easily represented as strings in ENV or CLI (e.g. arrays, objects). We may need to support custom parsing logic or conventions for these cases.
+            const rvalue = schema.parse(value);
+            AssertConfigValueType(rvalue);
+            return rvalue;
+        }
+        catch (cause) {
+            throw new ConfigurationError(key, cause instanceof Error ? cause.message : String(cause), { cause: cause instanceof Error ? cause : undefined });
+        }
+    }
+    /**
+     * Retrieve the schema for a configuration key.
+     * @param key - Configuration key
+     * @returns The Zod schema for this configuration
+     * @throws {ConfigurationNotRegisteredError} If schema is not registered for key
+     * @example
+     * const schema = manager.getSchema('PORT');
+     * const parsed = schema.safeParse(value);
+     */
+    static GetSchema(key) {
+        const schema = this._Schemas.get(key);
+        if (!schema)
+            throw new ConfigurationNotRegisteredError(key);
+        return schema;
+    }
+}

package/dist/schema.factory.d.ts

@@ -0,0 +1,66 @@
+import type { z } from 'zod';
+import { type TConfigSource } from './manager.js';
+/**
+ * Configuration schema object with static-like methods for managing config values.
+ * Provides Register, Get, Set, Validate, and ParseENV methods for a specific config namespace.
+ *
+ * @template TConfig - The inferred type of the Zod schema
+ * @template TKeys - Union of config keys from the schema shape
+ */
+export interface IConfigSchemaObject<TConfig extends Record<string, unknown>, TKeys extends keyof TConfig = keyof TConfig> {
+    /**
+     * Register all schema fields with ConfigManager.
+     * Extracts default values and registers each field as a schema.
+     */
+    Register(): void;
+    /**
+     * Get a typed config value by key.
+     *
+     * @param key - Configuration key to retrieve
+     * @returns The typed config value
+     * @template K - Specific config key type
+     *
+     * @example
+     * const host = MongoDBConfig.Get('HOST');
+     * // host is typed as string
+     */
+    Get<K extends TKeys>(key: K): TConfig[K];
+    /**
+     * Set a config value with optional source.
+     *
+     * @param key - Configuration key to set
+     * @param value - Typed value matching the key
+     * @param source - Override source ('DEFAULT' or 'OVERRIDE'), defaults to 'OVERRIDE'
+     * @template K - Specific config key type
+     * @throws Error if the value fails validation
+     *
+     * @example
+     * MongoDBConfig.Set('HOST', 'localhost:27017', 'OVERRIDE');
+     */
+    Set<K extends TKeys>(key: K, value: TConfig[K], source?: TConfigSource): void;
+    /**
+     * Validate a value against its schema without setting it.
+     *
+     * @param key - Configuration key whose schema is used for validation
+     * @param value - Unknown value to validate
+     * @returns true if the value is valid for this key, false otherwise
+     * @template K - Specific config key type
+     *
+     * @example
+     * if (MongoDBConfig.Validate('PORT', '27017')) {
+     *   // value is valid for PORT
+     * }
+     */
+    Validate<K extends TKeys>(key: K, value: unknown): boolean;
+    /**
+     * Parse environment variables matching the prefix and set them as overrides.
+     * Logs warnings for invalid values but continues processing remaining vars.
+     *
+     * @example
+     * MongoDBConfig.ParseENV();
+     * // Reads MONGODB_HOST, MONGODB_PORT, etc. from process.env
+     */
+    ParseENV(): void;
+}
+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

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

package/dist/schema.factory.js

@@ -0,0 +1,128 @@
+import { ConfigManager } from './manager.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;
+    }
+}
+/**
+ * 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();
+ * ```
+ */
+/**
+ * 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 = {};
+    for (const key in schema.shape) {
+        if (Object.prototype.hasOwnProperty.call(schema.shape, key)) {
+            prefixedNames[key] = `${prefix}${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);
+                }
+            }
+        },
+        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
+            ConfigManager.Set(prefixedNames[key], value, source);
+        },
+        Validate(key, value) {
+            const fieldSchema = schema.shape[key];
+            try {
+                fieldSchema.parse(value);
+                return true;
+            }
+            catch {
+                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;
+                        }
+                    }
+                }
+            }
+        },
+    };
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@pawells/config",
+	"version": "2.1.6-rc1",
+	"license": "MIT",
+	"author": {
+		"name": "Phillip Aaron Wells",
+		"email": "phillip.aaron.wells@gmail.com"
+	},
+	"homepage": "https://github.com/PhillipAWells/common",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/PhillipAWells/common.git"
+	},
+	"funding": {
+		"type": "github",
+		"url": "https://github.com/sponsors/PhillipAWells"
+	},
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		"./package.json": "./package.json",
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"!**/*.tsbuildinfo"
+	],
+	"dependencies": {
+		"tslib": "^2.3.0",
+		"zod": "^4.4.3"
+	}
+}