@zudojs/config 0.1.0 → 1.0.0

package/LICENSE

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

package/README.md

@@ -1,6 +1,7 @@
 # @zudojs/config
 
-Layered configuration management with multiple sources, validation, and environment-specific overrides.
+Layered configuration management with multiple sources, priority-based
+merging, schema validation, and sensitive-value redaction.
 
 ## Installation
 
@@ -11,31 +12,142 @@ npm install @zudojs/config
 ## Quick Start
 
 ```typescript
-import { createConfig } from "@zudojs/config";
+import {
+  createConfigManager,
+  createDefaultsConfigSource,
+  createMemoryConfigSource,
+} from "@zudojs/config";
 
-const config = await createConfig({
+const manager = createConfigManager({
   sources: [
-    env({ prefix: "APP_" }),
-    file("./config.json"),
-    defaults({ port: 3000 }),
+    createDefaultsConfigSource({ "app.port": 3000, "app.name": "demo" }),
+    createMemoryConfigSource(
+      { "app.port": 8080 },
+      { name: "overrides", priority: 100 },
+    ),
   ],
 });
 
-const port = config.get("port");
+await manager.load();
+
+manager.number("app.port"); // 8080 (higher priority wins)
+manager.string("app.name"); // "demo"
+```
+
+Or create and load in one step:
+
+```typescript
+import { initializeConfigManager } from "@zudojs/config";
+
+const manager = await initializeConfigManager({
+  initialValues: { "app.env": "development" },
+});
+```
+
+With `autoLoad: true` the manager starts loading on construction;
+await `manager.ready()` before reading values.
+
+## Sources
+
+A source provides values plus a priority. Higher priority wins; equal
+priorities are applied in registration order (last registered wins).
+
+- `createDefaultsConfigSource(values, name?)` — low-priority defaults.
+- `createMemoryConfigSource(values, { name, priority?, optional? })` —
+  in-memory values.
+- `createEnvironmentConfigSource({ prefix, env?, priority?, keyMapper?, isSensitive? })`
+  — reads environment variables. Values stay RAW STRINGS (use the typed
+  accessors to coerce, so `"false"` becomes `false` instead of a truthy
+  string). Names matching a password/token/secret/API-key pattern are
+  reported as sensitive and therefore redacted by `toSafeObject()`.
+- `createCustomConfigSource(name, loader, options?)` — async loader
+  function returning `{ values, source, type }`. Include
+  `sensitiveKeys: ["some.key"]` in the result to mark values as
+  sensitive so they are redacted by safe serialization.
+
+```typescript
+import {
+  createEnvironmentConfigSource,
+  createCustomConfigSource,
+  ConfigSourceType,
+} from "@zudojs/config";
+
+// APP__DB__HOST=localhost -> "db.host"
+const env = createEnvironmentConfigSource({ prefix: "APP__" });
+
+const remote = createCustomConfigSource("vault", async () => ({
+  values: { "db.password": "s3cret" },
+  sensitiveKeys: ["db.password"],
+  source: "vault",
+  type: ConfigSourceType.CUSTOM,
+}));
+```
+
+## Typed access
+
+`ConfigManager` (and the underlying `ConfigResolver`) offer typed
+getters: `string()`, `number()`, `boolean()`, `bigint()`, `date()`,
+`object()`, `array()`, `get()`, `required()`, and `scoped(prefix)` for
+prefix-scoped access.
+
+```typescript
+const db = manager.scoped("db");
+db.string("host", "localhost");
 ```
 
-## Features
+## Schema validation
+
+Schemas are plain objects validated by this package (no external
+validation library is used):
+
+```typescript
+import { ConfigValueType } from "@zudojs/config";
+
+const config = manager.validate({
+  properties: {
+    "app.port": { type: ConfigValueType.NUMBER, required: true },
+    "db.password": { type: ConfigValueType.STRING, secret: true },
+  },
+  additionalProperties: true,
+});
+```
+
+Object schemas nest: a property schema of type `OBJECT` that declares
+its own `properties` / `additionalProperties` is validated recursively,
+so nested constraints are enforced by `validate()`, `resolve()` and the
+standalone `validateConfigValue`.
+
+`validate()` throws on failure and marks entries whose schema has
+`secret: true` as sensitive. Individual values can be validated with
+`manager.resolve(key, schema)` or the standalone
+`validateConfigValue` / `validateConfigObject` functions.
+
+## Redaction
+
+- `manager.toObject()` / `store.toObject()` return RAW values,
+  including secrets.
+- `manager.toSafeObject()` / `store.toSafeObject()` replace sensitive
+  values with `"[REDACTED]"` — use these for logging and diagnostics.
+
+## Reloading
+
+`manager.reload()` re-runs all sources. Values set at runtime via
+`manager.set()` and `initialValues` survive loads; sources only
+overwrite entries at equal or higher priority.
+
+## Untrusted input
 
-- Layered source pattern with priority ordering
-- Environment variable support with prefix matching
-- JSON, YAML, and TOML file sources
-- Schema validation with Zod
-- Sensitive value auto-redaction
-- Hot reload support
+Configuration frequently originates from files, environment variables
+or remote services. Keys such as `__proto__`, `constructor` and
+`prototype` are copied with `Object.defineProperty`, never plain
+assignment, so a hostile key becomes an ordinary own property and can
+never replace an object's prototype. Schema properties are read as OWN
+properties, so a schema property named `constructor` is reported as
+missing rather than matching an inherited function.
 
 ## Use Cases
 
 - Application configuration
 - Environment-specific settings (dev, staging, prod)
 - Feature flags and toggles
-- Secrets management integration
+- Secrets handling with redacted diagnostics

package/dist/configEntry/configEntry.type.d.ts

@@ -45,8 +45,12 @@ export declare function updateConfigEntry<T extends ConfigValue>(entry: ConfigEn
 export declare function isConfigEntry(value: unknown): value is ConfigEntry;
 /**
  * Masks a sensitive configuration value.
+ *
+ * The entire value — including arrays and objects — collapses to a
+ * single replacement token so that no structural information (such
+ * as an array's length) leaks about the sensitive value.
  */
-export declare function redactConfigValue(value: ConfigValue, replacement?: string): ConfigValue;
+export declare function redactConfigValue(_value: ConfigValue, replacement?: string): ConfigValue;
 /**
  * Creates a safe representation of an entry for logging or
  * diagnostics.

package/dist/configEntry/configEntry.type.js

@@ -52,17 +52,12 @@ export function isConfigEntry(value) {
 }
 /**
  * Masks a sensitive configuration value.
+ *
+ * The entire value — including arrays and objects — collapses to a
+ * single replacement token so that no structural information (such
+ * as an array's length) leaks about the sensitive value.
  */
-export function redactConfigValue(value, replacement = "[REDACTED]") {
-    if (value === undefined || value === null || typeof value !== "object") {
-        return replacement;
-    }
-    if (value instanceof Date) {
-        return replacement;
-    }
-    if (Array.isArray(value)) {
-        return value.map(() => replacement);
-    }
+export function redactConfigValue(_value, replacement = "[REDACTED]") {
     return replacement;
 }
 /**

package/dist/configFactory/configFactory.core.d.ts

@@ -1,5 +1,5 @@
 import type { ConfigValue } from "../configValue/configValue.core.js";
-import type { ConfigSchema } from "../configSchema/configSchema.type.js";
+import type { AnyConfigSchema } from "../configSchema/configSchema.type.js";
 import type { ConfigSource } from "../configSource/configSource.core.js";
 import type { ConfigStore } from "../configStore/configStore.core.js";
 import type { ConfigManagerOptions } from "../configManager/configManager.type.js";
@@ -7,9 +7,7 @@ import type { ConfigManager } from "../configManager/configManager.core.js";
 /**
  * Factory options for creating a configuration manager.
  */
-export interface ConfigFactoryOptions extends ConfigManagerOptions {
-    readonly name?: string;
-}
+export type ConfigFactoryOptions = ConfigManagerOptions;
 /**
  * Creates a configuration manager without loading it.
  */
@@ -34,8 +32,8 @@ export declare function createConfigurationFromStore(store: ConfigStore, options
  * Creates a configuration manager and validates it against a schema.
  */
 export declare function createValidatedConfiguration<T extends ConfigValue = ConfigValue>(schema: {
-    readonly properties: Readonly<Record<string, ConfigSchema>>;
-    readonly additionalProperties?: boolean | ConfigSchema;
+    readonly properties: Readonly<Record<string, AnyConfigSchema>>;
+    readonly additionalProperties?: boolean | AnyConfigSchema;
 }, options?: ConfigFactoryOptions): Promise<{
     readonly manager: ConfigManager;
     readonly config: T;

package/dist/configLoader/configLoader.core.d.ts

@@ -8,9 +8,30 @@ export interface ConfigLoaderOptions {
     readonly sources?: readonly ConfigSource[];
     readonly context?: ConfigSourceContext;
     readonly store?: ConfigStore;
+    /**
+     * Whether a store created by the loader deep-clones and freezes
+     * stored values. When false, the store shares REFERENCES with the
+     * values that sources returned — mutating them later mutates the
+     * store's view as well. Ignored when an existing `store` is given.
+     */
     readonly freeze?: boolean;
     readonly clearStore?: boolean;
+    /**
+     * Called after each source loads successfully.
+     *
+     * Receives the source itself and that source's result, in that order,
+     * as two separate arguments. Awaited, so a slow hook delays the rest of
+     * the load.
+     */
     readonly onSourceLoaded?: (source: ConfigSource, result: ConfigSourceResult) => void | Promise<void>;
+    /**
+     * Called when a source fails to load.
+     *
+     * Receives the source first and the thrown value second. The thrown
+     * value is `unknown` because a source may reject with anything, so
+     * narrow it before use. Awaited, and returning normally does not
+     * suppress the failure.
+     */
     readonly onSourceError?: (source: ConfigSource, error: unknown) => void | Promise<void>;
 }
 /**
@@ -35,6 +56,7 @@ export declare class ConfigLoader {
     private readonly onSourceLoaded?;
     private readonly onSourceError?;
     private readonly clearStore;
+    private readonly freeze;
     private loading;
     private loaded;
     private disposed;
@@ -62,6 +84,11 @@ export declare class ConfigLoader {
     get lastLoadResult(): ConfigLoadResult | undefined;
     /**
      * Loads all configured sources.
+     *
+     * When the loader context carries an AbortSignal, the signal is
+     * checked between sources: once aborted, loading stops early and
+     * this method throws the signal's abort reason. Values applied by
+     * sources that completed before the abort remain in the store.
      */
     load(): Promise<ConfigLoadResult>;
     /**
@@ -72,6 +99,10 @@ export declare class ConfigLoader {
     reload(): Promise<ConfigLoadResult>;
     /**
      * Loads only selected sources.
+     *
+     * The shared store is never cleared: values loaded previously are
+     * retained and only the given sources are (re)applied. Source
+     * callbacks configured on this loader are invoked as usual.
      */
     loadSources(sources: readonly ConfigSource[]): Promise<ConfigLoadResult>;
     /**
@@ -87,9 +118,14 @@ export declare class ConfigLoader {
      */
     getSource(name: string): ConfigSource | undefined;
     /**
-     * Disposes the loader and its source resources.
+     * Disposes the loader and, by default, its source resources.
+     *
+     * Pass `closeSources: false` when the sources are owned by the
+     * caller and must outlive this loader.
      */
-    dispose(): Promise<void>;
+    dispose(options?: {
+        readonly closeSources?: boolean;
+    }): Promise<void>;
     /**
      * Detaches this loader from its source lifecycle.
      *
@@ -100,8 +136,13 @@ export declare class ConfigLoader {
      * Applies one source to the configuration store.
      *
      * Sources are processed from highest to lowest priority. Existing
-     * values are therefore retained when a lower-priority source
-     * attempts to replace them.
+     * strictly-higher-priority values are retained; an EQUAL-priority
+     * source overwrites, so among equal priorities the last-applied
+     * (last-registered) source wins.
+     *
+     * Keys listed in the result's `sensitiveKeys` are marked sensitive.
+     * Once an entry is sensitive it stays sensitive even when a later
+     * source overwrites its value.
      */
     private applySource;
     private assertActive;
@@ -112,6 +153,9 @@ export declare class ConfigLoader {
 export declare function createConfigLoader(options?: ConfigLoaderOptions): ConfigLoader;
 /**
  * Loads configuration directly from a collection of sources.
+ *
+ * The temporary loader is disposed afterwards WITHOUT closing the
+ * given sources — they are owned by the caller and remain usable.
  */
 export declare function loadConfiguration(sources: readonly ConfigSource[], options?: Omit<ConfigLoaderOptions, "sources">): Promise<ConfigLoadResult>;
 /**

package/dist/configLoader/configLoader.core.js

@@ -1,6 +1,6 @@
 import { cloneConfigValue } from "../configValue/configValue.core.js";
 import { createConfigEntry } from "../configEntry/configEntry.type.js";
-import { loadConfigSources, sortConfigSources, } from "../configSource/configSource.core.js";
+import { loadConfigSourceStrict, sortConfigSources, } from "../configSource/configSource.core.js";
 import { createConfigStore } from "../configStore/configStore.factory.js";
 /**
  * Configuration loader.
@@ -15,6 +15,7 @@ export class ConfigLoader {
     onSourceLoaded;
     onSourceError;
     clearStore;
+    freeze;
     loading = false;
     loaded = false;
     disposed = false;
@@ -30,6 +31,7 @@ export class ConfigLoader {
         this.onSourceLoaded = options.onSourceLoaded;
         this.onSourceError = options.onSourceError;
         this.clearStore = options.clearStore ?? true;
+        this.freeze = options.freeze ?? true;
     }
     /**
      * Returns the underlying configuration store.
@@ -65,6 +67,11 @@ export class ConfigLoader {
     }
     /**
      * Loads all configured sources.
+     *
+     * When the loader context carries an AbortSignal, the signal is
+     * checked between sources: once aborted, loading stops early and
+     * this method throws the signal's abort reason. Values applied by
+     * sources that completed before the abort remain in the store.
      */
     async load() {
         this.assertActive();
@@ -78,9 +85,14 @@ export class ConfigLoader {
             }
             const sortedSources = sortConfigSources(this.sources);
             const results = [];
+            const signal = this.context.signal;
             for (const source of sortedSources) {
+                if (signal?.aborted) {
+                    throw (signal.reason ??
+                        new Error("Configuration loading was aborted."));
+                }
                 try {
-                    const result = await loadSingleSource(source, this.context);
+                    const result = await loadConfigSourceStrict(source, this.context);
                     if (!result) {
                         continue;
                     }
@@ -125,6 +137,10 @@ export class ConfigLoader {
     }
     /**
      * Loads only selected sources.
+     *
+     * The shared store is never cleared: values loaded previously are
+     * retained and only the given sources are (re)applied. Source
+     * callbacks configured on this loader are invoked as usual.
      */
     async loadSources(sources) {
         this.assertActive();
@@ -132,7 +148,10 @@ export class ConfigLoader {
             sources,
             context: this.context,
             store: this.store,
-            clearStore: this.clearStore,
+            clearStore: false,
+            freeze: this.freeze,
+            onSourceLoaded: this.onSourceLoaded,
+            onSourceError: this.onSourceError,
         });
         const result = await temporaryLoader.load();
         temporaryLoader.detach();
@@ -168,23 +187,28 @@ export class ConfigLoader {
         return this.sources.find((source) => source.name === name);
     }
     /**
-     * Disposes the loader and its source resources.
+     * Disposes the loader and, by default, its source resources.
+     *
+     * Pass `closeSources: false` when the sources are owned by the
+     * caller and must outlive this loader.
      */
-    async dispose() {
+    async dispose(options = {}) {
         if (this.disposed) {
             return;
         }
         this.disposed = true;
         this.loaded = false;
-        for (const source of this.sources) {
-            if (!source.close) {
-                continue;
-            }
-            try {
-                await source.close();
-            }
-            catch {
-                // Continue closing remaining sources.
+        if (options.closeSources ?? true) {
+            for (const source of this.sources) {
+                if (!source.close) {
+                    continue;
+                }
+                try {
+                    await source.close();
+                }
+                catch {
+                    // Continue closing remaining sources.
+                }
             }
         }
         this.sources.length = 0;
@@ -204,11 +228,17 @@ export class ConfigLoader {
      * Applies one source to the configuration store.
      *
      * Sources are processed from highest to lowest priority. Existing
-     * values are therefore retained when a lower-priority source
-     * attempts to replace them.
+     * strictly-higher-priority values are retained; an EQUAL-priority
+     * source overwrites, so among equal priorities the last-applied
+     * (last-registered) source wins.
+     *
+     * Keys listed in the result's `sensitiveKeys` are marked sensitive.
+     * Once an entry is sensitive it stays sensitive even when a later
+     * source overwrites its value.
      */
     applySource(source, result) {
         const priority = source.priority;
+        const sensitiveKeys = new Set(result.sensitiveKeys ?? []);
         for (const [key, value] of Object.entries(result.values)) {
             const existing = this.store.getEntry(key);
             if (existing && existing.priority > priority) {
@@ -218,7 +248,7 @@ export class ConfigLoader {
                 source: source.name,
                 sourceType: source.type,
                 priority,
-                sensitive: existing?.sensitive ?? false,
+                sensitive: sensitiveKeys.has(key) || (existing?.sensitive ?? false),
                 resolved: true,
             });
         }
@@ -229,25 +259,6 @@ export class ConfigLoader {
         }
     }
 }
-/**
- * Loads one source while preserving the source lifecycle contract.
- */
-async function loadSingleSource(source, context) {
-    if (source.isAvailable) {
-        const available = await source.isAvailable(context);
-        if (!available) {
-            if (source.optional) {
-                return undefined;
-            }
-            throw new Error(`Configuration source "${source.name}" is unavailable.`);
-        }
-    }
-    const result = await source.load(context);
-    if (!result || typeof result !== "object") {
-        throw new Error(`Configuration source "${source.name}" returned an invalid result.`);
-    }
-    return result;
-}
 /**
  * Creates a configuration loader.
  */
@@ -256,6 +267,9 @@ export function createConfigLoader(options = {}) {
 }
 /**
  * Loads configuration directly from a collection of sources.
+ *
+ * The temporary loader is disposed afterwards WITHOUT closing the
+ * given sources — they are owned by the caller and remain usable.
  */
 export async function loadConfiguration(sources, options = {}) {
     const loader = createConfigLoader({
@@ -266,7 +280,7 @@ export async function loadConfiguration(sources, options = {}) {
         return await loader.load();
     }
     finally {
-        await loader.dispose();
+        await loader.dispose({ closeSources: false });
     }
 }
 /**
@@ -277,6 +291,10 @@ export function sourceResultsToEntries(results, sources) {
     const entries = [];
     for (const result of results) {
         const source = sourceMap.get(result.source);
+        // A source result's `sensitiveKeys` must survive the conversion:
+        // dropping it here produced entries with `sensitive: false` for
+        // credentials, which toSafeConfigEntry() then printed in clear.
+        const sensitiveKeys = new Set(result.sensitiveKeys ?? []);
         for (const [key, value] of Object.entries(result.values)) {
             entries.push(createConfigEntry({
                 key,
@@ -284,6 +302,7 @@ export function sourceResultsToEntries(results, sources) {
                 source: result.source,
                 sourceType: result.type,
                 priority: source?.priority ?? 0,
+                sensitive: sensitiveKeys.has(key),
             }));
         }
     }

package/dist/configManager/configManager.core.d.ts

@@ -1,5 +1,5 @@
 import type { ConfigValue } from "../configValue/configValue.core.js";
-import type { ConfigSchema } from "../configSchema/configSchema.core.js";
+import type { ConfigSchema, AnyConfigSchema } from "../configSchema/index.js";
 import type { ConfigSource } from "../configSource/configSource.core.js";
 import type { ConfigEntry } from "../configEntry/configEntry.type.js";
 import type { ConfigLoader, ConfigLoadResult } from "../configLoader/configLoader.core.js";
@@ -15,6 +15,12 @@ import { ConfigManagerState } from "./configManager.type.js";
  * keeping their responsibilities separate.
  */
 export declare class ConfigManager {
+    /**
+     * Human-readable name for this manager, surfaced in status
+     * snapshots so applications running several managers can tell
+     * their diagnostics apart.
+     */
+    readonly name: string;
     private readonly store;
     private readonly loader;
     private readonly resolver;
@@ -23,6 +29,7 @@ export declare class ConfigManager {
     private lastLoadedAt?;
     private lastError?;
     private disposed;
+    private loadPromise?;
     constructor(options?: ConfigManagerOptions);
     /**
      * Returns the current lifecycle state.
@@ -54,18 +61,36 @@ export declare class ConfigManager {
     scoped(prefix: string): ScopedConfigResolver;
     /**
      * Loads configuration.
+     *
+     * Calling load() while a load is already in flight returns the
+     * in-flight promise instead of starting a second load.
      */
     load(): Promise<ConfigLoadResult>;
+    /**
+     * Waits until the initial configuration load has completed.
+     *
+     * With `autoLoad: true` this awaits the load started by the
+     * constructor (rethrowing its failure). Otherwise it starts a load
+     * when none has happened yet.
+     */
+    ready(): Promise<void>;
     /**
      * Reloads configuration.
      */
     reload(): Promise<ConfigLoadResult>;
+    /**
+     * Executes a load or reload while keeping lifecycle state safe.
+     *
+     * If the manager is disposed while the load is in flight, no state
+     * transition happens afterwards: a disposed manager stays DISPOSED.
+     */
+    private performLoad;
     /**
      * Loads a schema and validates the complete configuration.
      */
     validate<T extends ConfigValue>(schema: {
-        readonly properties: Readonly<Record<string, ConfigSchema>>;
-        readonly additionalProperties?: boolean | ConfigSchema;
+        readonly properties: Readonly<Record<string, AnyConfigSchema>>;
+        readonly additionalProperties?: boolean | AnyConfigSchema;
     }): T;
     /**
      * Gets a raw configuration value.
@@ -121,8 +146,15 @@ export declare class ConfigManager {
     delete(key: string): boolean;
     /**
      * Returns the complete configuration object.
+     *
+     * WARNING: values are returned RAW — sensitive entries are NOT
+     * redacted. Use toSafeObject() for logging or diagnostics.
      */
     toObject(): Readonly<Record<string, ConfigValue>>;
+    /**
+     * Returns the configuration object with sensitive values redacted.
+     */
+    toSafeObject(): Readonly<Record<string, ConfigValue>>;
     /**
      * Returns a manager status snapshot.
      */