@pawells/config 2.3.1 → 3.0.0

package/dist/manager.js

@@ -1,7 +1,7 @@
-import { writeFileSync } from 'node:fs';
 import { z } from 'zod/v4';
-import { ConfigurationAlreadyRegisteredError, ConfigurationNotRegisteredError, ConfigurationError, ConfigurationNotSetError } from './errors.js';
-import { IsMarkedSecret } from './secret.js';
+import { GetErrorMessage } from '@pawells/typescript-common';
+import { ConfigRegistrationError, ConfigNotRegisteredError, ConfigNotSetError, ConfigValidationError } from './errors.js';
+import { IsMarkedSecret, traverseSchemaToBase } from './secret.js';
 /**
  * Zod schema for all supported configuration value types.
  * Accepts string, number, boolean, Date, string[], number[], boolean[], and undefined — nullable and optional.
@@ -37,8 +37,7 @@ export function AssertConfigValueType(value) {
  * @internal
  */
 function GetFieldDescription(schema) {
-    let current = schema;
-    while (current != null) {
+    for (const current of traverseSchemaToBase(schema)) {
         try {
             const meta = z.globalRegistry.get(current);
             if (typeof meta?.description === 'string') {
@@ -48,226 +47,757 @@ function GetFieldDescription(schema) {
         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.
+ * Non-exported internal state class holding all configuration data and logic.
  *
- * @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.
+ * All instance methods mirror the public ConfigManager and ScopedConfigManager APIs.
+ * This class exists to avoid code duplication between the static and instance facades.
  *
- * @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');
+ * @internal
  */
-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() {
+class CoreConfigState {
+    _Schemas = new Map();
+    _DataDefaults = new Map();
+    _DataOverrides = new Map();
+    /**
+     * Raw (unvalidated) values collected from all registered providers.
+     * Stored so that schemas registered after providers can still receive provider values.
+     * Later-registered providers overwrite earlier ones for the same key.
+     */
+    _providerRawData = new Map();
+    /**
+     * Validated provider values, ready for merging into the resolved config.
+     * Populated from _providerRawData whenever a schema is registered or a provider is added.
+     */
+    _providerValues = new Map();
+    /**
+     * Maps env-var prefix strings to their section names for save-entry construction.
+     * Example: 'KEYCLOAK_' → 'KEYCLOAK'
+     */
+    _namespaces = new Map();
+    /**
+     * Cache for the resolved _Data map to avoid rebuilding on every access.
+     * Invalidated whenever data is mutated (Set, Register, Reset, RegisterProvider).
+     */
+    _dataCache = null;
+    /**
+     * Cache for parsed configuration values, keyed by configuration key.
+     * Avoids re-parsing the same value on repeated Get() calls.
+     */
+    _parsedCache = new Map();
+    /**
+     * Cache for schema metadata (isSecret and description).
+     * Populated at Register() time to avoid traversing the schema chain on every Save() call.
+     */
+    _schemaMetaCache = new Map();
+    /**
+     * Optional handler for provider validation warnings.
+     * If set, called when a provider value fails schema validation.
+     * If not set, validation failures are silent (no-op).
+     */
+    _validationWarningHandler;
+    /**
+     * Lookup table: key → { section, field }
+     * Built at Register() time to optimize Save() performance.
+     */
+    _keyLookup = new Map();
+    /**
+     * Resolved configuration data, computed from defaults, provider values, and overrides.
+     */
+    get _Data() {
+        if (this._dataCache !== null) {
+            return this._dataCache;
+        }
         const resolved = new Map(this._DataDefaults);
+        for (const [key, value] of this._providerValues) {
+            resolved.set(key, value);
+        }
         for (const [key, value] of this._DataOverrides) {
             resolved.set(key, value);
         }
+        this._dataCache = resolved;
         return resolved;
     }
     /**
-     * Reset the singleton instance (for testing).
-     * @internal
+     * Reset this state (for testing).
      */
-    static Reset() {
+    Reset() {
         this._Schemas.clear();
         this._DataDefaults.clear();
+        this._providerRawData.clear();
+        this._providerValues.clear();
         this._DataOverrides.clear();
+        this._namespaces.clear();
+        this._dataCache = null;
+        this._parsedCache.clear();
+        this._schemaMetaCache.clear();
+        this._keyLookup.clear();
+        this._validationWarningHandler = undefined;
+    }
+    /**
+     * Set an optional handler for provider validation warnings.
+     * When a provider value fails schema validation, if a handler is set,
+     * it will be called with the key and provider name.
+     * If no handler is set, validation failures are silent.
+     *
+     * @param handler - Function to call on validation failure, or undefined to clear
+     */
+    SetValidationWarningHandler(handler) {
+        this._validationWarningHandler = handler;
+    }
+    /**
+     * Register a configuration namespace for use when building save entries.
+     *
+     * Records the mapping from `prefix` to `sectionName` so that
+     * {@link Save} can split fully-qualified keys into section and field
+     * components (e.g. `KEYCLOAK_HOST` → section `KEYCLOAK`, field `HOST`).
+     *
+     * @param name - Human-readable namespace name (e.g. `'Keycloak'`)
+     * @param prefix - Derived environment variable prefix (e.g. `'KEYCLOAK_'`)
+     */
+    RegisterNamespace(name, prefix) {
+        this._namespaces.set(prefix, name.toUpperCase());
+    }
+    /**
+     * Save all registered configuration values via a provider.
+     *
+     * Builds a {@link ConfigSaveEntry} for every registered schema key, then
+     * delegates formatting and file I/O to `provider.Save()`.
+     *
+     * In template mode (`useCurrentValues: false`, the default), each entry
+     * carries the registered default value. In current-values mode
+     * (`useCurrentValues: true`), each entry carries the fully resolved live
+     * value (DEFAULT → provider values → OVERRIDE). The `isSecret` flag is
+     * set for fields marked with {@link Secret}; providers are expected to
+     * redact those appropriately in template mode.
+     *
+     * @param provider - A {@link IConfigProvider} that handles the write
+     * @param options - Output path and save mode
+     * @returns - A promise that resolves when the save operation completes
+     * @remarks In `useCurrentValues` mode, keys that cannot be resolved (not set, not registered, or failing validation) are written as blank/undefined without throwing.
+     */
+    async Save(provider, options) {
+        const useCurrentValues = options.useCurrentValues ?? false;
+        const entries = [];
+        for (const [key] of this._Schemas) {
+            const meta = this._schemaMetaCache.get(key);
+            const isSecret = meta?.isSecret ?? false;
+            const description = meta?.description;
+            const lookup = this._keyLookup.get(key);
+            const section = lookup?.section ?? '';
+            const field = lookup?.field ?? key;
+            let value;
+            if (useCurrentValues) {
+                try {
+                    value = this.Get(key);
+                }
+                catch (e) {
+                    if (e instanceof ConfigNotSetError
+                        || e instanceof ConfigNotRegisteredError) {
+                        value = undefined;
+                    }
+                    else {
+                        throw e;
+                    }
+                }
+            }
+            else {
+                value = this._DataDefaults.get(key);
+            }
+            entries.push({ key, section, field, value, isSecret, description });
+        }
+        await provider.Save(entries, options);
+    }
+    /**
+     * Register a configuration value provider.
+     *
+     * Immediately calls `provider.Load()` to obtain all key/value pairs from the
+     * provider. All raw values are stored in the internal raw-data cache so that
+     * schemas registered after this call can still receive provider values.
+     * For any key that already has a registered schema, the raw value is validated
+     * and the validated result is stored in the provider values tier.
+     *
+     * Provider values occupy the middle precedence tier: they override registered
+     * defaults but are themselves overridden by explicit {@link Set} calls.
+     * When multiple providers supply the same key, the last-registered provider wins.
+     *
+     * @param provider - The {@link IConfigProvider} implementation to register
+     * @returns - A promise that resolves when registration completes
+     */
+    async RegisterProvider(provider) {
+        const values = await provider.Load();
+        for (const [key, rawValue] of Object.entries(values)) {
+            // Always cache raw value — needed for schemas registered after this provider
+            this._providerRawData.set(key, rawValue);
+            // If schema already registered, validate and cache the typed value now
+            const schema = this._Schemas.get(key);
+            if (schema === undefined)
+                continue;
+            const result = schema.safeParse(rawValue);
+            if (!result.success) {
+                if (this._validationWarningHandler) {
+                    this._validationWarningHandler(key, provider.Name);
+                }
+                continue;
+            }
+            // Safe: safeParse succeeds only if result.data matches schema's inferred type,
+            // which was validated at Register to be TConfigValueTypes
+            this._providerValues.set(key, result.data);
+        }
+        this._dataCache = null;
+    }
+    /**
+     * Register a synchronous configuration provider.
+     * Use this only in contexts that cannot `await`. Most code should prefer
+     * `RegisterProvider()` with an async provider.
+     *
+     * Immediately calls `provider.LoadSync()` to obtain all key/value pairs from the
+     * provider. All raw values are stored in the internal raw-data cache so that
+     * schemas registered after this call can still receive provider values.
+     * For any key that already has a registered schema, the raw value is validated
+     * and the validated result is stored in the provider values tier.
+     *
+     * @param provider - The {@link ISyncConfigProvider} implementation to register
+     */
+    RegisterSyncProvider(provider) {
+        const values = provider.LoadSync();
+        for (const [key, rawValue] of Object.entries(values)) {
+            // Always cache raw value — needed for schemas registered after this provider
+            this._providerRawData.set(key, rawValue);
+            // If schema already registered, validate and cache the typed value now
+            const schema = this._Schemas.get(key);
+            if (schema === undefined)
+                continue;
+            const result = schema.safeParse(rawValue);
+            if (!result.success) {
+                if (this._validationWarningHandler) {
+                    this._validationWarningHandler(key, provider.Name);
+                }
+                continue;
+            }
+            this._providerValues.set(key, result.data);
+        }
+        this._dataCache = null;
     }
-    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
-     * ConfigManager.Register('PORT', z.coerce.number().positive(), 3000);
-     * ConfigManager.Register('JWT_SECRET', z.string().min(32), 'default-secret');
+     * @throws {ConfigRegistrationError} If key is already registered with a different schema
+     * @throws {ConfigValidationError} If defaultValue does not match the schema
      */
-    static Register(key, schema, defaultValue) {
+    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);
+            throw new ConfigRegistrationError(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 });
+        if (!result.success) {
+            const isSecret = IsMarkedSecret(schema);
+            const message = isSecret ? 'Default value does not match the provided schema (value redacted for security).' : 'Default value does not match the provided schema.';
+            const options = isSecret ? undefined : { cause: result.error };
+            throw new ConfigValidationError(key, message, options);
+        }
         const parsed = result.data;
+        // Deep-clone mutable types to prevent caller mutation
+        const clonedDefault = structuredClone(parsed);
         this._Schemas.set(key, schema);
-        this.Set(key, parsed, 'DEFAULT');
+        // Safe: clonedDefault is the parsed result of schema.safeParse(), which succeeded
+        this._DataDefaults.set(key, clonedDefault);
+        this._dataCache = null;
+        this._parsedCache.delete(key);
+        // Cache schema metadata for use in Save()
+        this._schemaMetaCache.set(key, {
+            isSecret: IsMarkedSecret(schema),
+            description: GetFieldDescription(schema)
+        });
+        // Precompute section/field lookup for Save() optimization
+        let section = '';
+        let field = key;
+        for (const [prefix, sectionName] of this._namespaces) {
+            if (key.startsWith(prefix)) {
+                section = sectionName;
+                field = key.slice(prefix.length);
+                break;
+            }
+        }
+        this._keyLookup.set(key, { section, field });
+        // Apply any provider value already loaded for this key
+        if (this._providerRawData.has(key)) {
+            const rawProviderValue = this._providerRawData.get(key);
+            const providerResult = schema.safeParse(rawProviderValue);
+            if (providerResult.success) {
+                // Safe: safeParse succeeds only if providerResult.data matches schema's type
+                this._providerValues.set(key, providerResult.data);
+                this._dataCache = null;
+            }
+        }
     }
     /**
      * 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
-     * manager.set('PORT', 3000);
-     * manager.set('JWT_SECRET', process.env.SECRET);
+     * @throws {ConfigNotRegisteredError} If schema is not registered for key
+     * @throws {ConfigValidationError} If validation fails
+     * @remarks
+     * When validation fails for a field marked with `Secret()`, the error message and error cause are sanitized to prevent secret values from appearing in error logs or stack traces.
      */
-    static Set(key, value, target = 'OVERRIDE') {
+    Set(key, value, target = 'OVERRIDE') {
         const schema = this._Schemas.get(key);
         if (!schema)
-            throw new ConfigurationNotRegisteredError(key);
+            throw new ConfigNotRegisteredError(key);
         try {
             const parsed = schema.parse(value);
-            AssertConfigValueType(parsed);
+            // Safe: Register validates that this schema produces TConfigValueTypes at runtime
             if (target === 'DEFAULT') {
                 this._DataDefaults.set(key, parsed);
             }
             else {
                 this._DataOverrides.set(key, parsed);
             }
+            this._dataCache = null;
+            this._parsedCache.delete(key);
         }
         catch (cause) {
-            throw new ConfigurationError(key, cause instanceof Error ? cause.message : String(cause), { cause: cause instanceof Error ? cause : undefined });
+            const isSecret = this._schemaMetaCache.get(key)?.isSecret ?? false;
+            const message = isSecret ? 'value failed validation (value redacted for security)' : GetErrorMessage(cause);
+            const options = isSecret ? undefined : (cause instanceof Error ? cause : undefined);
+            throw new ConfigValidationError(key, message, options ? { cause: options } : undefined);
         }
     }
     /**
      * 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
-     * @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
+     * @throws {ConfigNotSetError} If value was not set
+     * @throws {ConfigNotRegisteredError} If schema is not registered
+     * @throws {ConfigValidationError} If validation fails on retrieval
      */
-    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);
+    Get(key, source) {
+        let dataSource;
+        switch (source) {
+            case 'DEFAULT':
+                dataSource = this._DataDefaults;
+                break;
+            case 'OVERRIDE':
+                dataSource = this._DataOverrides;
+                break;
+            default:
+                dataSource = this._Data;
+                break;
+        }
+        if (!dataSource.has(key))
+            throw new ConfigNotSetError(key);
+        // Safe: has() guard above guarantees presence; stored values match schema types
+        const value = dataSource.get(key);
+        // Only use parsed cache for resolved (non-source-filtered) values
+        if (source === undefined && this._parsedCache.has(key)) {
+            // has() guard above guarantees presence — use type assertion instead of ! (ESLint: no-non-null-assertion)
+            return this._parsedCache.get(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);
+            // Safe: Register validates that this schema produces TConfigValueTypes at runtime
+            // Cache the parsed result (only for resolved values, not source-filtered)
+            if (source === undefined) {
+                this._parsedCache.set(key, rvalue);
+            }
             return rvalue;
         }
         catch (cause) {
-            throw new ConfigurationError(key, cause instanceof Error ? cause.message : String(cause), { cause: cause instanceof Error ? cause : undefined });
+            const isSecret = this._schemaMetaCache.get(key)?.isSecret ?? false;
+            if (isSecret) {
+                throw new ConfigValidationError(key, 'value failed validation (value redacted for security)');
+            }
+            throw new ConfigValidationError(key, GetErrorMessage(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);
+     * @throws {ConfigNotRegisteredError} If schema is not registered for key
      */
-    static GetSchema(key) {
+    GetSchema(key) {
         const schema = this._Schemas.get(key);
         if (!schema)
-            throw new ConfigurationNotRegisteredError(key);
+            throw new ConfigNotRegisteredError(key);
         return schema;
     }
+}
+/**
+ * Runtime configuration manager with Zod schema validation.
+ * Provides a singleton instance to register and retrieve typed configuration values.
+ *
+ * @example
+ * ```typescript
+ * ConfigManager.Register('DATABASE_URL', z.string().url(), 'postgresql://localhost/mydb');
+ * ConfigManager.Set('DATABASE_URL', 'postgresql://localhost/mydb');
+ * const url = ConfigManager.Get('DATABASE_URL');
+ * ```
+ */
+export class ConfigManager {
+    static _state = new CoreConfigState();
+    /**
+     * Reset the singleton instance (for testing).
+     *
+     * @internal
+     */
+    static Reset() {
+        this._state.Reset();
+    }
     /**
-     * Generates a `.env` file string from all currently registered configuration keys.
+     * Set an optional handler for provider validation warnings.
      *
-     * 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=`).
+     * When a provider value fails schema validation, if a handler is set,
+     * it will be called with the key and provider name. If no handler is set,
+     * validation failures are silent (no-op).
      *
-     * If a field has a Zod `.describe()` annotation, it is emitted as a `# comment` line
-     * immediately before the key–value pair.
+     * @param handler - Function to call on validation failure, or undefined to clear
+     * @example
+     * ```typescript
+     * ConfigManager.SetValidationWarningHandler((key, providerName) => {
+     *   console.warn(`Provider ${providerName} failed for key ${key}`);
+     * });
+     * ```
+     */
+    static SetValidationWarningHandler(handler) {
+        this._state.SetValidationWarningHandler(handler);
+    }
+    /**
+     * Register a configuration namespace for use when building save entries.
      *
-     * @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.
+     * Records the mapping from `prefix` to `sectionName` so that
+     * {@link Save} can split fully-qualified keys into section and field
+     * components (e.g. `KEYCLOAK_HOST` → section `KEYCLOAK`, field `HOST`).
      *
+     * Called automatically by `RegisterConfigSchema` — applications do not
+     * normally need to call this directly.
+     *
+     * @param name - Human-readable namespace name (e.g. `'Keycloak'`)
+     * @param prefix - Derived environment variable prefix (e.g. `'KEYCLOAK_'`)
      * @example
      * ```typescript
-     * // Template mode — defaults shown, secrets blank
-     * const template = ConfigManager.GenerateEnv();
-     * // "APP_HOST=localhost\nAPP_PORT=3000\nAPP_SECRET_KEY="
+     * ConfigManager.RegisterNamespace('Keycloak', 'KEYCLOAK_');
+     * // KEYCLOAK_HOST → section='KEYCLOAK', field='HOST'
      * ```
+     */
+    static RegisterNamespace(name, prefix) {
+        this._state.RegisterNamespace(name, prefix);
+    }
+    /**
+     * Save all registered configuration values via a provider.
+     *
+     * Builds a {@link ConfigSaveEntry} for every registered schema key, then
+     * delegates formatting and file I/O to `provider.Save()`.
      *
+     * In template mode (`useCurrentValues: false`, the default), each entry
+     * carries the registered default value. In current-values mode
+     * (`useCurrentValues: true`), each entry carries the fully resolved live
+     * value (DEFAULT → provider values → OVERRIDE). The `isSecret` flag is
+     * set for fields marked with {@link Secret}; providers are expected to
+     * redact those appropriately in template mode.
+     *
+     * @param provider - An {@link IConfigProvider} that handles the write
+     * @param options - Output path and save mode
+     * @returns - A promise that resolves when the save operation completes
+     * @remarks In `useCurrentValues` mode, keys that cannot be resolved (not set, not registered, or failing validation) are written as blank/undefined without throwing.
      * @example
      * ```typescript
-     * // Save current runtime settings to a file
-     * ConfigManager.GenerateEnv({ useCurrentValues: true, path: '.env.snapshot' });
+     * // Write .env.example (template, secrets blank)
+     * await ConfigManager.Save(envProvider, { path: '.env.example' });
+     *
+     * // Snapshot current runtime values
+     * await ConfigManager.Save(envProvider, { path: '.env', useCurrentValues: true });
      * ```
      */
-    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;
+    static async Save(provider, options) {
+        await this._state.Save(provider, options);
+    }
+    /**
+     * Register a configuration value provider with the manager.
+     *
+     * Immediately calls `provider.Load()` to obtain all key/value pairs from the
+     * provider. All raw values are stored in the internal raw-data cache so that
+     * schemas registered after this call can still receive provider values.
+     * For any key that already has a registered schema, the raw value is validated
+     * and the validated result is stored in the provider values tier.
+     *
+     * Provider values occupy the middle precedence tier: they override registered
+     * defaults but are themselves overridden by explicit {@link Set} calls.
+     * When multiple providers supply the same key, the last-registered provider wins.
+     *
+     * @param provider - An {@link IConfigProvider} implementation to register
+     * @returns - A promise that resolves when registration completes
+     * @example
+     * ```typescript
+     * import { ConfigEnvironmentProvider } from '@pawells/config-provider-env';
+     * import { ConfigJSONProvider } from '@pawells/config-provider-json';
+     *
+     * // Register before importing any schema modules
+     * await ConfigManager.RegisterProvider(await ConfigEnvironmentProvider.Register({ path: '.env' }));
+     * await ConfigManager.RegisterProvider(await ConfigJSONProvider.Register({ path: './config.json' }));
+     * ```
+     */
+    static async RegisterProvider(provider) {
+        await this._state.RegisterProvider(provider);
+    }
+    /**
+     * Register a synchronous configuration provider with the manager.
+     * Use this only in contexts that cannot `await`. Most code should prefer
+     * `RegisterProvider()` with an async provider.
+     *
+     * Immediately calls `provider.LoadSync()` to obtain all key/value pairs from the
+     * provider. All raw values are stored in the internal raw-data cache so that
+     * schemas registered after this call can still receive provider values.
+     * For any key that already has a registered schema, the raw value is validated
+     * and the validated result is stored in the provider values tier.
+     *
+     * @param provider - An {@link ISyncConfigProvider} implementation to register
+     * @example
+     * ```typescript
+     * class MemoryProvider implements ISyncConfigProvider {
+     *   readonly name = 'memory';
+     *   LoadSync() {
+     *     return { MY_KEY: 'value' };
+     *   }
+     * }
+     * ConfigManager.RegisterSyncProvider(new MemoryProvider());
+     * ```
+     */
+    static RegisterSyncProvider(provider) {
+        this._state.RegisterSyncProvider(provider);
+    }
+    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 {ConfigRegistrationError} If key is already registered with a different schema
+     * @throws {ConfigValidationError} If defaultValue does not match the schema
+     * @example
+     * ```typescript
+     * ConfigManager.Register('PORT', z.coerce.number().positive(), 3000);
+     * ConfigManager.Register('JWT_SECRET', z.string().min(32), 'default-secret');
+     * ```
+     */
+    static Register(key, schema, defaultValue) {
+        this._state.Register(key, schema, defaultValue);
+    }
+    /**
+     * 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 {ConfigNotRegisteredError} If schema is not registered for key
+     * @throws {ConfigValidationError} If validation fails
+     * @remarks
+     * When validation fails for a field marked with `Secret()`, the error message and error cause are sanitized to prevent secret values from appearing in error logs or stack traces.
+     * @example
+     * ```typescript
+     * ConfigManager.Set('PORT', 3000);
+     * ConfigManager.Set('JWT_SECRET', process.env.SECRET);
+     * ```
+     */
+    static Set(key, value, target = 'OVERRIDE') {
+        this._state.Set(key, value, target);
+    }
+    /**
+     * 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 {ConfigNotSetError} If value was not set
+     * @throws {ConfigNotRegisteredError} If schema is not registered
+     * @throws {ConfigValidationError} If validation fails on retrieval
+     * @example
+     * ```typescript
+     * const port = ConfigManager.Get('PORT'); // Returns number, guaranteed by schema
+     * const secret = ConfigManager.Get('JWT_SECRET'); // Returns string
+     * ```
+     */
+    static Get(key, source) {
+        return this._state.Get(key, source);
+    }
+    /**
+     * Retrieve the schema for a configuration key.
+     *
+     * @param key - Configuration key
+     * @returns The Zod schema for this configuration
+     * @throws {ConfigNotRegisteredError} If schema is not registered for key
+     * @example
+     * ```typescript
+     * const schema = ConfigManager.GetSchema('PORT');
+     * const parsed = schema.safeParse(value);
+     * ```
+     */
+    static GetSchema(key) {
+        return this._state.GetSchema(key);
+    }
+}
+/**
+ * Instance-based configuration manager for test isolation and multi-tenant scenarios.
+ *
+ * Unlike the static singleton {@link ConfigManager}, `ScopedConfigManager` maintains
+ * independent state in instance fields. This enables isolated configuration contexts
+ * without affecting the global singleton or other instances.
+ *
+ * The public API mirrors `ConfigManager` exactly, but as instance methods instead of
+ * static methods. Use this when you need:
+ * - Test isolation: each test gets its own config instance
+ * - Multi-tenant scenarios: separate configs per tenant
+ * - Feature-gating: isolated experimental configs
+ *
+ * @example
+ * ```typescript
+ * // Two independent configurations
+ * const config1 = new ScopedConfigManager();
+ * const config2 = new ScopedConfigManager();
+ *
+ * config1.Register('PORT', z.coerce.number(), 3000);
+ * config2.Register('PORT', z.coerce.number(), 4000);
+ *
+ * config1.Get('PORT'); // 3000
+ * config2.Get('PORT'); // 4000 — independent state
+ * ```
+ */
+export class ScopedConfigManager {
+    _state;
+    constructor() {
+        this._state = new CoreConfigState();
+    }
+    /**
+     * Reset this instance (for testing).
+     */
+    Reset() {
+        this._state.Reset();
+    }
+    /**
+     * Set an optional handler for provider validation warnings.
+     *
+     * When a provider value fails schema validation, if a handler is set,
+     * it will be called with the key and provider name. If no handler is set,
+     * validation failures are silent (no-op).
+     *
+     * @param handler - Function to call on validation failure, or undefined to clear
+     */
+    SetValidationWarningHandler(handler) {
+        this._state.SetValidationWarningHandler(handler);
+    }
+    /**
+     * Register a configuration namespace for use when building save entries.
+     *
+     * Records the mapping from `prefix` to `sectionName` so that
+     * {@link Save} can split fully-qualified keys into section and field
+     * components (e.g. `KEYCLOAK_HOST` → section `KEYCLOAK`, field `HOST`).
+     *
+     * @param name - Human-readable namespace name (e.g. `'Keycloak'`)
+     * @param prefix - Derived environment variable prefix (e.g. `'KEYCLOAK_'`)
+     */
+    RegisterNamespace(name, prefix) {
+        this._state.RegisterNamespace(name, prefix);
+    }
+    /**
+     * Save all registered configuration values via a provider.
+     *
+     * Builds a {@link ConfigSaveEntry} for every registered schema key, then
+     * delegates formatting and file I/O to `provider.Save()`.
+     *
+     * @param provider - An {@link IConfigProvider} that handles the write
+     * @param options - Output path and save mode
+     * @returns - A promise that resolves when the save operation completes
+     */
+    async Save(provider, options) {
+        await this._state.Save(provider, options);
+    }
+    /**
+     * Register a configuration value provider with this instance.
+     *
+     * @param provider - An {@link IConfigProvider} implementation to register
+     * @returns - A promise that resolves when registration completes
+     */
+    async RegisterProvider(provider) {
+        await this._state.RegisterProvider(provider);
+    }
+    /**
+     * Register a synchronous configuration provider with this instance.
+     *
+     * Use this only in contexts that cannot `await`. Most code should prefer
+     * `RegisterProvider()` with an async provider.
+     *
+     * @param provider - An {@link ISyncConfigProvider} implementation to register
+     */
+    RegisterSyncProvider(provider) {
+        this._state.RegisterSyncProvider(provider);
+    }
+    /**
+     * 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 {ConfigRegistrationError} If key is already registered with a different schema
+     * @throws {ConfigValidationError} If defaultValue does not match the schema
+     */
+    Register(key, schema, defaultValue) {
+        this._state.Register(key, schema, defaultValue);
+    }
+    /**
+     * 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 {ConfigNotRegisteredError} If schema is not registered for key
+     * @throws {ConfigValidationError} If validation fails
+     * @remarks
+     * When validation fails for a field marked with `Secret()`, the error message and error cause are sanitized to prevent secret values from appearing in error logs or stack traces.
+     */
+    Set(key, value, target = 'OVERRIDE') {
+        this._state.Set(key, value, target);
+    }
+    /**
+     * 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 {ConfigNotSetError} If value was not set
+     * @throws {ConfigNotRegisteredError} If schema is not registered
+     * @throws {ConfigValidationError} If validation fails on retrieval
+     */
+    Get(key, source) {
+        return this._state.Get(key, source);
+    }
+    /**
+     * Retrieve the schema for a configuration key.
+     *
+     * @param key - Configuration key
+     * @returns The Zod schema for this configuration
+     * @throws {ConfigNotRegisteredError} If schema is not registered for key
+     */
+    GetSchema(key) {
+        return this._state.GetSchema(key);
     }
 }
 //# sourceMappingURL=manager.js.map