@pawells/config 2.3.1 → 3.0.1

package/dist/errors.js

@@ -1,17 +1,18 @@
 /**
  * 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 } from '@pawells/typescript-common';
 /**
  * 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;
+export class ConfigError extends BaseError {
+    constructor(message, metadata = {}) {
+        metadata.code ??= 'CONFIG_ERROR';
+        super(message, metadata);
     }
 }
 /**
@@ -20,59 +21,55 @@ 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 class ConfigurationAlreadyRegisteredError extends ConfigurationBaseError {
-    Code = 'CONFIGURATION_ALREADY_REGISTERED';
-    constructor(key) {
-        super(`Configuration key "${key}" is already registered with a different schema.`);
+export class ConfigRegistrationError extends ConfigError {
+    constructor(key, metadata = {}) {
+        metadata.code ??= 'CONFIG_REGISTRATION_ERROR';
+        super(`Configuration key "${key}" is already registered with a different schema.`, metadata);
     }
 }
 /**
- * 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 class ConfigurationNotRegisteredError extends ConfigurationBaseError {
-    Code = 'CONFIGURATION_NOT_REGISTERED';
-    constructor(key) {
-        super(`Configuration key "${key}" is not registered.`);
+export class ConfigNotSetError extends ConfigError {
+    constructor(key, metadata = {}) {
+        metadata.code ??= 'CONFIG_NOT_SET_ERROR';
+        super(`Configuration key "${key}" is not set.`, metadata);
     }
 }
 /**
- * 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 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;
-        }
+export class ConfigNotRegisteredError extends ConfigError {
+    constructor(key, metadata = {}) {
+        metadata.code ??= 'CONFIG_NOT_REGISTERED';
+        super(`Configuration key "${key}" is not registered.`, metadata);
     }
 }
 /**
- * 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 class ConfigurationNotSetError extends ConfigurationBaseError {
-    Code = 'CONFIGURATION_NOT_SET';
-    constructor(key) {
-        super(`Configuration key "${key}" is not set.`);
+export class ConfigValidationError extends ConfigError {
+    constructor(key, validationMessage, metadata = {}) {
+        metadata.code ??= 'CONFIG_VALIDATION_ERROR';
+        super(`Validation Failed for Configuration "${key}": ${validationMessage}`, metadata);
     }
 }
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAe,sBAAuB,SAAQ,KAAK;IAGlD,YAAY,OAAe;QAC1B,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;IACnC,CAAC;CACD;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,mCAAoC,SAAQ,sBAAsB;IAC9D,IAAI,GAAG,kCAAkC,CAAC;IAE1D,YAAY,GAAW;QACtB,KAAK,CAAC,sBAAsB,GAAG,kDAAkD,CAAC,CAAC;IACpF,CAAC;CACD;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,+BAAgC,SAAQ,sBAAsB;IAC1D,IAAI,GAAG,8BAA8B,CAAC;IAEtD,YAAY,GAAW;QACtB,KAAK,CAAC,sBAAsB,GAAG,sBAAsB,CAAC,CAAC;IACxD,CAAC;CACD;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,kBAAmB,SAAQ,sBAAsB;IAC7C,IAAI,GAAG,qBAAqB,CAAC;IAE7C,YAAY,GAAW,EAAE,OAAe,EAAE,OAA2B;QACpE,KAAK,CAAC,wCAAwC,GAAG,MAAM,OAAO,EAAE,CAAC,CAAC;QAClE,IAAI,OAAO,EAAE,KAAK,EAAE,CAAC;YACpB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC5B,CAAC;IACF,CAAC;CACD;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,wBAAyB,SAAQ,sBAAsB;IACnD,IAAI,GAAG,uBAAuB,CAAC;IAE/C,YAAY,GAAW;QACtB,KAAK,CAAC,sBAAsB,GAAG,eAAe,CAAC,CAAC;IACjD,CAAC;CACD"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAuB,MAAM,4BAA4B,CAAC;AAE5E;;;GAGG;AACH,MAAM,OAAO,WAAY,SAAQ,SAAS;IACzC,YAAY,OAAe,EAAE,WAA2B,EAAE;QACzD,QAAQ,CAAC,IAAI,KAAK,cAAc,CAAC;QACjC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC1B,CAAC;CACD;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,uBAAwB,SAAQ,WAAW;IACvD,YAAY,GAAW,EAAE,WAA2B,EAAE;QACrD,QAAQ,CAAC,IAAI,KAAK,2BAA2B,CAAC;QAC9C,KAAK,CAAC,sBAAsB,GAAG,kDAAkD,EAAE,QAAQ,CAAC,CAAC;IAC9F,CAAC;CACD;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAkB,SAAQ,WAAW;IACjD,YAAY,GAAW,EAAE,WAA2B,EAAE;QACrD,QAAQ,CAAC,IAAI,KAAK,sBAAsB,CAAC;QACzC,KAAK,CAAC,sBAAsB,GAAG,eAAe,EAAE,QAAQ,CAAC,CAAC;IAC3D,CAAC;CACD;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,wBAAyB,SAAQ,WAAW;IACxD,YAAY,GAAW,EAAE,WAA2B,EAAE;QACrD,QAAQ,CAAC,IAAI,KAAK,uBAAuB,CAAC;QAC1C,KAAK,CAAC,sBAAsB,GAAG,sBAAsB,EAAE,QAAQ,CAAC,CAAC;IAClE,CAAC;CACD;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,qBAAsB,SAAQ,WAAW;IACrD,YAAY,GAAW,EAAE,iBAAyB,EAAE,WAA2B,EAAE;QAChF,QAAQ,CAAC,IAAI,KAAK,yBAAyB,CAAC;QAC5C,KAAK,CAAC,wCAAwC,GAAG,MAAM,iBAAiB,EAAE,EAAE,QAAQ,CAAC,CAAC;IACvF,CAAC;CACD"}

package/dist/index.d.ts

@@ -1,5 +1,13 @@
-export * from './errors.js';
-export * from './manager.js';
-export * from './schema.factory.js';
+export { ConfigError, ConfigRegistrationError, ConfigNotSetError, ConfigNotRegisteredError, ConfigValidationError } from './errors.js';
+export { ConfigManager, ScopedConfigManager } from './manager.js';
+export type { TConfigSource, TConfigValueTypes, TConfig } from './manager.js';
+export { CONFIG_VALUES_TYPES_SCHEMA, AssertConfigValueType } from './manager.js';
+export { ConfigProvider } from './provider.js';
+export type { IConfigProvider, ISyncConfigProvider, SaveOptions, ConfigSaveEntry, IConfigSaveEntry } from './provider.js';
+export { CONFIG_PROVIDER_OPTIONS_SCHEMA, CONFIG_PROVIDER_SAVE_OPTIONS_SCHEMA } from './provider.js';
+export type { TConfigProviderOptions, TConfigProviderSaveOptions } from './provider.js';
+export { AssertConfigProviderOptions, ValidateConfigProviderOptions } from './provider.js';
+export { RegisterConfigSchema } from './schema.factory.js';
+export type { IConfigSchemaObject } from './schema.factory.js';
 export { Secret } from './secret.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGvI,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAClE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAGjF,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,WAAW,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC1H,OAAO,EAAE,8BAA8B,EAAE,mCAAmC,EAAE,MAAM,eAAe,CAAC;AACpG,YAAY,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AACxF,OAAO,EAAE,2BAA2B,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AAG3F,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAG/D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,5 +1,14 @@
-export * from './errors.js';
-export * from './manager.js';
-export * from './schema.factory.js';
+// Errors
+export { ConfigError, ConfigRegistrationError, ConfigNotSetError, ConfigNotRegisteredError, ConfigValidationError } from './errors.js';
+// Manager (static singleton)
+export { ConfigManager, ScopedConfigManager } from './manager.js';
+export { CONFIG_VALUES_TYPES_SCHEMA, AssertConfigValueType } from './manager.js';
+// Provider abstractions and schemas
+export { ConfigProvider } from './provider.js';
+export { CONFIG_PROVIDER_OPTIONS_SCHEMA, CONFIG_PROVIDER_SAVE_OPTIONS_SCHEMA } from './provider.js';
+export { AssertConfigProviderOptions, ValidateConfigProviderOptions } from './provider.js';
+// Schema factory
+export { RegisterConfigSchema } from './schema.factory.js';
+// Secret utility
 export { Secret } from './secret.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,SAAS;AACT,OAAO,EAAE,WAAW,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEvI,6BAA6B;AAC7B,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAElE,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAEjF,oCAAoC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,8BAA8B,EAAE,mCAAmC,EAAE,MAAM,eAAe,CAAC;AAEpG,OAAO,EAAE,2BAA2B,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AAE3F,iBAAiB;AACjB,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAG3D,iBAAiB;AACjB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/manager.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod/v4';
+import type { IConfigProvider, ISyncConfigProvider, SaveOptions } from './provider.js';
 /**
  * Zod schema for all supported configuration value types.
  * Accepts string, number, boolean, Date, string[], number[], boolean[], and undefined — nullable and optional.
@@ -26,102 +27,320 @@ export type TConfigSource = 'DEFAULT' | 'OVERRIDE';
  * 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('DEFAULT', 'DATABASE_URL', 'postgresql://localhost/mydb');
+ * ConfigManager.Set('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();
+    private static readonly _state;
     /**
      * Reset the singleton instance (for testing).
+     *
      * @internal
      */
     static Reset(): void;
+    /**
+     * 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
+     * @example
+     * ```typescript
+     * ConfigManager.SetValidationWarningHandler((key, providerName) => {
+     *   console.warn(`Provider ${providerName} failed for key ${key}`);
+     * });
+     * ```
+     */
+    static SetValidationWarningHandler(handler: ((key: string, providerName: string) => void) | undefined): void;
+    /**
+     * 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`).
+     *
+     * 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
+     * ConfigManager.RegisterNamespace('Keycloak', 'KEYCLOAK_');
+     * // KEYCLOAK_HOST → section='KEYCLOAK', field='HOST'
+     * ```
+     */
+    static RegisterNamespace(name: string, prefix: string): void;
+    /**
+     * 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
+     * // 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 Save(provider: IConfigProvider, options: SaveOptions): Promise<void>;
+    /**
+     * 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 RegisterProvider(provider: IConfigProvider): Promise<void>;
+    /**
+     * 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: ISyncConfigProvider): 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
+     * @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: string, schema: z.ZodType<TConfigValueTypes>, defaultValue: unknown): void;
+    static Register(key: string, schema: z.ZodTypeAny, defaultValue: unknown): void;
     /**
      * Set a configuration value and validate against its schema.
+     *
      * @param key - Configuration key
      * @param value - Value to set and validate
      * @param target - Whether to set the default store or the override store; defaults to `'OVERRIDE'`
-     * @throws {ConfigurationNotRegisteredError} If schema is not registered for key
-     * @throws {ConfigurationError} If validation fails
+     * @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
-     * manager.set('PORT', 3000);
-     * manager.set('JWT_SECRET', process.env.SECRET);
+     * ```typescript
+     * ConfigManager.Set('PORT', 3000);
+     * ConfigManager.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
      * @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
+     * @throws {ConfigNotSetError} If value was not set
+     * @throws {ConfigNotRegisteredError} If schema is not registered
+     * @throws {ConfigValidationError} If validation fails on retrieval
      * @example
-     * const port = manager.get('PORT'); // Returns number, guaranteed by schema
-     * const secret = manager.get('JWT_SECRET'); // Returns string
+     * ```typescript
+     * const port = ConfigManager.Get('PORT'); // Returns number, guaranteed by schema
+     * const secret = ConfigManager.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
+     * @throws {ConfigNotRegisteredError} If schema is not registered for key
      * @example
-     * const schema = manager.getSchema('PORT');
+     * ```typescript
+     * const schema = ConfigManager.GetSchema('PORT');
      * const parsed = schema.safeParse(value);
+     * ```
      */
     static GetSchema(key: string): z.ZodTypeAny;
+}
+/**
+ * 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 declare class ScopedConfigManager {
+    private readonly _state;
+    constructor();
     /**
-     * Generates a `.env` file string from all currently registered configuration keys.
+     * Reset this instance (for testing).
+     */
+    Reset(): void;
+    /**
+     * 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
+     */
+    SetValidationWarningHandler(handler: ((key: string, providerName: string) => void) | undefined): void;
+    /**
+     * 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`).
      *
-     * @example
-     * ```typescript
-     * // Template mode — defaults shown, secrets blank
-     * const template = ConfigManager.GenerateEnv();
-     * // "APP_HOST=localhost\nAPP_PORT=3000\nAPP_SECRET_KEY="
-     * ```
+     * @param name - Human-readable namespace name (e.g. `'Keycloak'`)
+     * @param prefix - Derived environment variable prefix (e.g. `'KEYCLOAK_'`)
+     */
+    RegisterNamespace(name: string, prefix: string): void;
+    /**
+     * Save all registered configuration values via a provider.
      *
-     * @example
-     * ```typescript
-     * // Save current runtime settings to a file
-     * ConfigManager.GenerateEnv({ useCurrentValues: true, path: '.env.snapshot' });
-     * ```
+     * 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
+     */
+    Save(provider: IConfigProvider, options: SaveOptions): Promise<void>;
+    /**
+     * Register a configuration value provider with this instance.
+     *
+     * @param provider - An {@link IConfigProvider} implementation to register
+     * @returns - A promise that resolves when registration completes
+     */
+    RegisterProvider(provider: IConfigProvider): Promise<void>;
+    /**
+     * 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: ISyncConfigProvider): void;
+    /**
+     * 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: string, schema: z.ZodTypeAny, defaultValue: unknown): void;
+    /**
+     * Set a configuration value and validate against its schema.
+     *
+     * @param key - Configuration key
+     * @param value - Value to set and validate
+     * @param target - Whether to set the default store or the override store; defaults to `'OVERRIDE'`
+     * @throws {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<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
+     * @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: string, source?: TConfigSource): TConfigValueTypes;
+    /**
+     * 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
      */
-    static GenerateEnv(options?: {
-        useCurrentValues?: boolean;
-        path?: string;
-    }): string;
+    GetSchema(key: string): z.ZodTypeAny;
 }
 //# sourceMappingURL=manager.d.ts.map

package/dist/manager.d.ts.map

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