@pawells/config 2.3.1 → 3.0.0

package/README.md

@@ -1,206 +1,309 @@
 # @pawells/config
 
-[![CI](https://github.com/PhillipAWells/common/actions/workflows/ci.yml/badge.svg)](https://github.com/PhillipAWells/common/actions/workflows/ci.yml)
+[![CI](https://github.com/PhillipAWells/config/actions/workflows/ci.yml/badge.svg)](https://github.com/PhillipAWells/config/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@pawells/config)](https://www.npmjs.com/package/@pawells/config)
 [![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)
+[![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.
+`@pawells/config` is the core package of the `@pawells/config-workspace` suite. It provides:
+
+- A **global singleton** (`ConfigManager`) and an **instance-based** (`ScopedConfigManager`) configuration manager, both backed by [Zod](https://zod.dev) schema validation.
+- A **schema factory** (`RegisterConfigSchema`) that derives typed, namespaced accessor objects from a Zod object schema, eliminating the need to call `ConfigManager.Register` for every key individually.
+- A **`Secret()` wrapper** that marks Zod field schemas as sensitive — secret values are automatically redacted in templates and error messages.
+- An **abstract base class** (`ConfigProvider`) and two interfaces (`IConfigProvider`, `ISyncConfigProvider`) for building custom providers.
+- A structured **error hierarchy** rooted at `ConfigError`.
+
+Values are resolved through a three-tier precedence model:
+
+```
+Registered defaults  <  Provider values  <  Runtime overrides (Set)
+```
+
+See the [workspace README](../../README.md) for an end-to-end quick start. See [CHANGELOG.md](../../CHANGELOG.md) for version history.
 
 ## Requirements
 
-- **Node.js**: 22.0.0 or later
-- **TypeScript**: 6.0.0 or later (if consuming from source)
-- **zod**: ^4.4.3 (peer dependency, required at runtime for schema validation)
+- Node.js `>=22.0.0`
+- `zod` `^4.4.3` (peer dependency, installed automatically)
 
 ## Installation
 
-Install from npm:
+```sh
+yarn add @pawells/config
+```
+
+## Quick Start
 
-```bash
-npm install @pawells/config
+```typescript
+import { z } from 'zod';
+import { ConfigManager, RegisterConfigSchema, Secret } from '@pawells/config';
+import { ConfigEnvironmentProvider } from '@pawells/config-provider-env';
+
+// 1. Register providers BEFORE importing schema modules.
+//    Provider values are merged into schemas at registration time.
+await ConfigEnvironmentProvider.Register({ path: '.env' });
+
+// 2. Define and register a schema.
+//    The prefix 'DATABASE_' is derived from the name 'Database'.
+const DatabaseConfig = RegisterConfigSchema('Database', z.object({
+    HOST: z.string().min(1).default('localhost'),
+    PORT: z.coerce.number().int().positive().default(5432),
+    PASSWORD: Secret(z.string().min(1)).default(''),
+}));
+
+// 3. Retrieve validated, typed values.
+const host = DatabaseConfig.Get('HOST');  // string
+const port = DatabaseConfig.Get('PORT');  // number
+
+// 4. Redact secrets for safe logging.
+console.log(DatabaseConfig.Redact());
+// → { HOST: 'localhost', PORT: 5432, PASSWORD: '***' }
 ```
 
-Or with yarn:
+## API Reference
 
-```bash
-yarn add @pawells/config
+### `RegisterConfigSchema(name, schema)`
+
+Registers all fields of a Zod object schema with `ConfigManager` and returns a typed accessor object.
+
+```typescript
+function RegisterConfigSchema<TSchema extends z.ZodRawShape>(
+    name: string,
+    schema: z.ZodObject<TSchema>
+): IConfigSchemaObject<z.infer<typeof schema>>
 ```
 
-## Quick Start
+- `name` — Human-readable namespace. The env-var prefix is derived as `name.toUpperCase() + '_'` (e.g. `'Database'` → `DATABASE_`).
+- `schema` — A `z.object(...)` schema. Every field should declare a `.default(...)` value.
 
-### Using CreateConfigSchema (Recommended)
+**Returns** an `IConfigSchemaObject` with the following members:
 
-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.
+| Member | Signature | Description |
+|---|---|---|
+| `name` | `string` | The namespace name passed to `RegisterConfigSchema`. |
+| `Get` | `Get<K>(key: K): TConfig[K]` | Retrieve the typed, validated value for `key`. Resolves DEFAULT → providers → OVERRIDE. |
+| `Set` | `Set<K>(key: K, value: TConfig[K], source?: TConfigSource): void` | Set a value. Target is `'OVERRIDE'` by default. |
+| `Validate` | `Validate<K>(key: K, value: unknown): boolean` | Check whether a value satisfies the field schema without setting it. |
+| `IsSecret` | `IsSecret(key: TKeys): boolean` | Returns `true` if the field was wrapped with `Secret()`. |
+| `GetSecretKeys` | `GetSecretKeys(): Array<TKeys>` | Returns all keys marked with `Secret()` in schema insertion order. |
+| `Redact` | `Redact(): Record<string, unknown>` | Returns all resolved values; secret fields are replaced with `'***'`. Unset/unregistered keys are omitted. |
+
+**Important:** Call `ConfigManager.RegisterProvider` for all providers before any module that calls `RegisterConfigSchema` is imported. Provider values are captured when schemas are registered.
+
+---
+
+### `Secret(schema)`
+
+Marks a Zod field schema as secret using Zod v4's `globalRegistry` metadata. The TypeScript inferred type of the schema is unchanged.
 
 ```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),
+function Secret<T extends z.ZodTypeAny>(schema: T): T
+```
+
+```typescript
+import { Secret } from '@pawells/config';
+import { z } from 'zod';
+
+// In a schema definition:
+const schema = z.object({
+    API_KEY: Secret(z.string().min(32)).default(''),
 });
+```
 
-// Create a typed config object with 'SERVICE_' prefix
-export const ServiceConfig = CreateConfigSchema(SERVICE_CONFIG_SCHEMA, 'SERVICE_');
+Secret fields are:
+- Blanked (empty value) in `.env` template output (`ConfigEnvironmentProvider.Save` in template mode).
+- Written as `null` in JSON template output (`ConfigJSONProvider.Save` in template mode).
+- Replaced with `'***'` by `IConfigSchemaObject.Redact()`.
+- Sanitized from `ConfigValidationError` messages and causes on validation failure.
 
-// Register all schemas
-ServiceConfig.Register();
+---
 
-// Parse environment variables (SERVICE_PORT, SERVICE_HOST, SERVICE_DEBUG, etc.)
-ServiceConfig.ParseENV();
+### `ConfigManager`
 
-// Get typed values
-const port = ServiceConfig.Get('PORT'); // number, typed
-const host = ServiceConfig.Get('HOST'); // string, typed
-const debug = ServiceConfig.Get('DEBUG'); // boolean, typed
+A static singleton configuration manager. All state is shared across the process for the lifetime of the module.
 
-console.log(`Server running on ${host}:${port}`);
+```typescript
+class ConfigManager {
+    static Register(key: string, schema: z.ZodTypeAny, defaultValue: unknown): void
+    static Get(key: string, source?: TConfigSource): TConfigValueTypes
+    static Set<T extends TConfigValueTypes>(key: string, value: T, target?: TConfigSource): void
+    static GetSchema(key: string): z.ZodTypeAny
+    static async RegisterProvider(provider: IConfigProvider): Promise<void>
+    static RegisterSyncProvider(provider: ISyncConfigProvider): void
+    static async Save(provider: IConfigProvider, options: SaveOptions): Promise<void>
+    static RegisterNamespace(name: string, prefix: string): void
+    static SetValidationWarningHandler(handler: ((key: string, providerName: string) => void) | undefined): void
+    static Reset(): void
+}
 ```
 
-### Retrieving and Validating Values
+| Method | Description |
+|---|---|
+| `Register(key, schema, defaultValue)` | Register a key with its Zod schema and initial default. Throws `ConfigRegistrationError` if re-registered with a different schema. Throws `ConfigValidationError` if `defaultValue` fails. |
+| `Get(key, source?)` | Retrieve the resolved value for `key`. Pass `'DEFAULT'` or `'OVERRIDE'` to read a specific tier only. Throws `ConfigNotRegisteredError` or `ConfigNotSetError` if unavailable. |
+| `Set(key, value, target?)` | Set a value on the `'OVERRIDE'` tier (default) or `'DEFAULT'` tier. Throws `ConfigNotRegisteredError` or `ConfigValidationError`. |
+| `GetSchema(key)` | Return the registered Zod schema for `key`. Throws `ConfigNotRegisteredError`. |
+| `RegisterProvider(provider)` | Async. Register an `IConfigProvider`; calls `provider.Load()` immediately. Provider values are the middle tier. Last-registered wins for duplicate keys. |
+| `RegisterSyncProvider(provider)` | Register an `ISyncConfigProvider`; calls `provider.LoadSync()` immediately. Use only when `await` is not available. |
+| `Save(provider, options)` | Async. Build a `ConfigSaveEntry[]` for every registered key and delegate to `provider.Save()`. |
+| `RegisterNamespace(name, prefix)` | Record a `prefix → sectionName` mapping used by `Save()` to split keys into section/field components. Called automatically by `RegisterConfigSchema`. |
+| `SetValidationWarningHandler(handler)` | Set a callback invoked when a provider value fails schema validation. Silent by default. Pass `undefined` to clear. |
+| `Reset()` | Clear all state. Intended for test isolation only. |
 
-```typescript
-// Get a typed configuration value (guaranteed type-safe)
-const timeout = ServiceConfig.Get('API_TIMEOUT'); // number
+**`TConfigSource`** — `'DEFAULT' | 'OVERRIDE'`
+
+**`TConfigValueTypes`** — the full union accepted by all schemas:
+`string | number | boolean | Date | string[] | number[] | boolean[] | undefined | null`
 
-// Validate a value before setting it
-const isValid = ServiceConfig.Validate('PORT', '8080'); // true if valid
+**`TConfig`** — `Map<string, TConfigValueTypes>`
 
-// Set configuration values at runtime
-ServiceConfig.Set('DEBUG', true, 'OVERRIDE');
+---
+
+### `ScopedConfigManager`
+
+An instance-based configuration manager. Each instance maintains fully independent state, making it suitable for test isolation and multi-tenant scenarios. The public API mirrors `ConfigManager` exactly as instance methods.
+
+```typescript
+const config = new ScopedConfigManager();
+config.Register('PORT', z.coerce.number(), 3000);
+await config.RegisterProvider(myProvider);
+const port = config.Get('PORT'); // 3000
 ```
 
-### Advanced: Using ConfigManager Directly
+`ScopedConfigManager` exposes: `Register`, `Get`, `Set`, `GetSchema`, `RegisterProvider`, `RegisterSyncProvider`, `Save`, `RegisterNamespace`, `SetValidationWarningHandler`, `Reset`.
 
-For advanced scenarios where you need direct schema control or custom management, use `ConfigManager`:
+---
+
+### `ConfigProvider` (abstract base class)
+
+Extend this class to build a custom provider. Both `Load` and `Save` are abstract and must be implemented.
 
 ```typescript
-import { ConfigManager } from '@pawells/config';
-import { z } from 'zod/v4';
+abstract class ConfigProvider<
+    TOptions extends TConfigProviderOptions = TConfigProviderOptions,
+    TLoadOptions = unknown,
+    TSaveOptions extends TConfigProviderSaveOptions = TConfigProviderSaveOptions
+> {
+    readonly Name: string
+    abstract Load(options?: TLoadOptions): Promise<Record<string, unknown>>
+    abstract Save(entries: readonly ConfigSaveEntry[], options?: TSaveOptions): Promise<void>
+}
+```
 
-// Register individual schemas
-ConfigManager.Register('DATABASE_URL', z.string().url(), 'postgresql://localhost/mydb');
-ConfigManager.Register('API_KEY', z.string().min(32), 'default-key');
+```typescript
+import { ConfigProvider, type TConfigProviderOptions, type ConfigSaveEntry } from '@pawells/config';
 
-// Set and retrieve values
-ConfigManager.Set('DATABASE_URL', process.env.DATABASE_URL);
-const dbUrl = ConfigManager.Get('DATABASE_URL');
+class RedisProvider extends ConfigProvider {
+    async Load(): Promise<Record<string, unknown>> {
+        // Return a flat key-value record; keys must be fully qualified.
+        return { APP_HOST: 'redis-host' };
+    }
+
+    async Save(_entries: readonly ConfigSaveEntry[]): Promise<void> {
+        // Implement if this provider supports writes.
+    }
+}
 ```
 
-### Error Handling
+---
+
+### Provider interfaces
+
+**`IConfigProvider`** — async providers (preferred):
 
 ```typescript
-import {
-  ConfigurationNotRegisteredError,
-  ConfigurationNotSetError,
-  ConfigurationError,
-} from '@pawells/config';
+interface IConfigProvider {
+    readonly Name: string
+    Load(): Promise<Record<string, unknown>>
+    Save(entries: readonly ConfigSaveEntry[], options?: SaveOptions): Promise<void>
+}
+```
 
-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);
-  }
+**`ISyncConfigProvider`** — synchronous read-only providers (escape hatch):
+
+```typescript
+interface ISyncConfigProvider {
+    readonly Name: string
+    LoadSync(): Record<string, unknown>
 }
 ```
 
-## API Reference
+---
 
-### CreateConfigSchema Factory (Recommended)
+### `SaveOptions`
 
-The `CreateConfigSchema` factory is the primary recommended API for most use cases. It creates a strongly-typed configuration schema object from a Zod schema.
+Passed to `ConfigManager.Save` and `IConfigProvider.Save`:
 
-**Signature:**
 ```typescript
-CreateConfigSchema<TSchema extends z.ZodRawShape>(
-  schema: z.ZodObject<TSchema>,
-  prefix: string
-): IConfigSchemaObject<z.infer<typeof schema>>
+interface SaveOptions {
+    path: string              // Destination file path
+    useCurrentValues?: boolean // false (default) = registered defaults; true = live resolved values
+}
 ```
 
-**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. |
-
-### Utility Functions
-
-| Export | Purpose |
-|--------|---------|
-| `Secret<T>(value: T)` | Mark a configuration value as sensitive (secrets are redacted in GetSchema().Redact()) |
-
-> **⚠️ 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');
-> ```
+---
+
+### `ConfigSaveEntry` / `IConfigSaveEntry`
+
+One entry per registered key, built by `ConfigManager.Save` and passed to `provider.Save`:
+
+| Field | Type | Description |
+|---|---|---|
+| `key` | `string` | Fully-qualified key (e.g. `DATABASE_HOST`) |
+| `section` | `string` | Namespace section (e.g. `DATABASE`); empty string if no namespace |
+| `field` | `string` | Field within the section (e.g. `HOST`); equals `key` when section is empty |
+| `value` | `unknown` | Default or live value, depending on `useCurrentValues` |
+| `isSecret` | `boolean` | `true` if the field was wrapped with `Secret()` |
+| `description` | `string \| undefined` | From Zod `.describe()` annotation |
+
+---
+
+### Error classes
+
+All errors extend `ConfigError`, which in turn extends `BaseError` from `@pawells/typescript-common`.
+
+| Class | Error code | Thrown when |
+|---|---|---|
+| `ConfigError` | `CONFIG_ERROR` | General configuration error; base class for all others |
+| `ConfigRegistrationError` | `CONFIG_REGISTRATION_ERROR` | A key is registered a second time with a different schema |
+| `ConfigNotSetError` | `CONFIG_NOT_SET_ERROR` | `Get()` is called for a key with no value in the requested tier |
+| `ConfigNotRegisteredError` | `CONFIG_NOT_REGISTERED` | `Get()`, `Set()`, or `GetSchema()` is called for an unregistered key |
+| `ConfigValidationError` | `CONFIG_VALIDATION_ERROR` | A value fails its Zod schema at `Register()`, `Set()`, or `Get()` time |
+
+```typescript
+import { ConfigError, ConfigNotRegisteredError, ConfigNotSetError, ConfigValidationError } from '@pawells/config';
+
+try {
+    const value = ConfigManager.Get('MISSING_KEY');
+} catch (error) {
+    if (error instanceof ConfigNotRegisteredError) {
+        // Key was never registered
+    } else if (error instanceof ConfigNotSetError) {
+        // Key is registered but has no value in the requested tier
+    } else if (error instanceof ConfigValidationError) {
+        // Value failed schema validation; check error.cause for Zod details
+    } else if (error instanceof ConfigError) {
+        // Any other configuration error
+    }
+}
+```
+
+---
+
+### Schema constants and utilities
+
+| Export | Description |
+|---|---|
+| `CONFIG_VALUES_TYPES_SCHEMA` | Zod union schema accepting all supported config value types |
+| `AssertConfigValueType(value)` | Asserts that `value` is a `TConfigValueTypes`; throws `ZodError` otherwise |
+| `CONFIG_PROVIDER_OPTIONS_SCHEMA` | Zod schema for `{ name: string }` base provider options |
+| `TConfigProviderOptions` | Inferred type of `CONFIG_PROVIDER_OPTIONS_SCHEMA` |
+| `AssertConfigProviderOptions(options)` | Asserts conformance; throws `ZodError` otherwise |
+| `ValidateConfigProviderOptions(options)` | Returns `true` if options conform; `false` otherwise |
+| `CONFIG_PROVIDER_SAVE_OPTIONS_SCHEMA` | Zod schema for `{ useCurrentValues?: boolean }` |
+| `TConfigProviderSaveOptions` | Inferred type of `CONFIG_PROVIDER_SAVE_OPTIONS_SCHEMA` |
 
 ## License
 

package/dist/errors.d.ts

@@ -1,16 +1,16 @@
 /**
  * Custom error classes for configuration management.
  *
- * Exports: {@link ConfigurationAlreadyRegisteredError}, {@link ConfigurationNotRegisteredError},
- * {@link ConfigurationError}, and {@link ConfigurationNotSetError}.
+ * Exports: {@link ConfigRegistrationError}, {@link ConfigNotRegisteredError},
+ * {@link ConfigError}, and {@link ConfigNotSetError}.
  */
+import { BaseError, type TErrorMetadata } from '@pawells/typescript-common';
 /**
  * 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);
+export declare class ConfigError extends BaseError {
+    constructor(message: string, metadata?: TErrorMetadata);
 }
 /**
  * Error thrown when attempting to register a configuration key that already exists.
@@ -18,51 +18,43 @@ declare abstract class ConfigurationBaseError extends Error {
  * @param key - The configuration key that was already registered
  *
  * @example
- * throw new ConfigurationAlreadyRegisteredError('DATABASE_URL');
+ * throw new ConfigRegistrationError('DATABASE_URL');
  */
-export declare class ConfigurationAlreadyRegisteredError extends ConfigurationBaseError {
-    readonly Code = "CONFIGURATION_ALREADY_REGISTERED";
-    constructor(key: string);
+export declare class ConfigRegistrationError extends ConfigError {
+    constructor(key: string, metadata?: TErrorMetadata);
 }
 /**
- * Error thrown when attempting to access a configuration key that was not registered.
+ * Error thrown when a required configuration value is not set.
  *
- * @param key - The configuration key that is not registered
+ * @param key - The configuration key that is not set
  *
  * @example
- * throw new ConfigurationNotRegisteredError('UNKNOWN_KEY');
+ * throw new ConfigNotSetError('DATABASE_URL');
  */
-export declare class ConfigurationNotRegisteredError extends ConfigurationBaseError {
-    readonly Code = "CONFIGURATION_NOT_REGISTERED";
-    constructor(key: string);
+export declare class ConfigNotSetError extends ConfigError {
+    constructor(key: string, metadata?: TErrorMetadata);
 }
 /**
- * Error thrown when configuration validation fails.
+ * Error thrown when a configuration key is not registered.
  *
- * @param key - The configuration key that failed validation
- * @param message - Detailed error message about the validation failure
- * @param options - Optional options object with cause
+ * @param key - The configuration key that is not registered
  *
  * @example
- * throw new ConfigurationError('PORT', 'Must be a positive number');
+ * throw new ConfigNotRegisteredError('DATABASE_URL');
  */
-export declare class ConfigurationError extends ConfigurationBaseError {
-    readonly Code = "CONFIGURATION_ERROR";
-    constructor(key: string, message: string, options?: {
-        cause?: Error;
-    });
+export declare class ConfigNotRegisteredError extends ConfigError {
+    constructor(key: string, metadata?: TErrorMetadata);
 }
 /**
- * Error thrown when a required configuration value is not set.
+ * Error thrown when a configuration value fails schema validation.
  *
- * @param key - The configuration key that is not set
+ * @param key - The configuration key that failed validation
+ * @param validationMessage - The validation error message describing why the value is invalid
  *
  * @example
- * throw new ConfigurationNotSetError('DATABASE_URL');
+ * throw new ConfigValidationError('PORT', 'Expected a number between 1 and 65535');
  */
-export declare class ConfigurationNotSetError extends ConfigurationBaseError {
-    readonly Code = "CONFIGURATION_NOT_SET";
-    constructor(key: string);
+export declare class ConfigValidationError extends ConfigError {
+    constructor(key: string, validationMessage: string, metadata?: TErrorMetadata);
 }
-export {};
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5E;;;GAGG;AACH,qBAAa,WAAY,SAAQ,SAAS;gBAC7B,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,cAAmB;CAI1D;AAED;;;;;;;GAOG;AACH,qBAAa,uBAAwB,SAAQ,WAAW;gBAC3C,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,cAAmB;CAItD;AAED;;;;;;;GAOG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;gBACrC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,cAAmB;CAItD;AAED;;;;;;;GAOG;AACH,qBAAa,wBAAyB,SAAQ,WAAW;gBAC5C,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,cAAmB;CAItD;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,SAAQ,WAAW;gBACzC,GAAG,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,QAAQ,GAAE,cAAmB;CAIjF"}