@zudojs/config 0.0.1 → 1.0.0

package/dist/configManager/configManager.core.js

@@ -1,5 +1,5 @@
 import { cloneConfigValue } from "../configValue/configValue.core.js";
-import { ConfigValueType, validateConfigObject, } from "../configSchema/configSchema.core.js";
+import { ConfigValueType, validateConfigObject, } from "../configSchema/index.js";
 import { createConfigSource } from "../configSource/configSource.core.js";
 import { createConfigLoader } from "../configLoader/configLoader.core.js";
 import { createConfigStore } from "../configStore/configStore.factory.js";
@@ -13,6 +13,12 @@ import { ConfigManagerValidationError } from "./configManager.error.js";
  * keeping their responsibilities separate.
  */
 export class ConfigManager {
+    /**
+     * Human-readable name for this manager, surfaced in status
+     * snapshots so applications running several managers can tell
+     * their diagnostics apart.
+     */
+    name;
     store;
     loader;
     resolver;
@@ -21,26 +27,52 @@ export class ConfigManager {
     lastLoadedAt;
     lastError;
     disposed = false;
+    loadPromise;
     constructor(options = {}) {
+        // When a caller supplies a loader (and no explicit store), the
+        // manager must resolve values from the SAME store that loader
+        // writes to.
+        const providedLoader = options.loader;
+        const suppliedStore = options.store ?? providedLoader?.getStore();
         this.store =
-            options.store ??
+            suppliedStore ??
                 createConfigStore({
                     initialValues: options.initialValues,
                     freeze: options.freeze ?? true,
                 });
+        // initialValues used to be wired ONLY into a store the manager
+        // created itself: passing `store` or `loader` silently discarded
+        // them. Seed a supplied store explicitly instead.
+        if (suppliedStore && options.initialValues) {
+            for (const [key, value] of Object.entries(options.initialValues)) {
+                suppliedStore.set(key, value, { source: "initialValues" });
+            }
+        }
+        this.name = options.name ?? "config";
         this.loader =
-            options.loader ??
+            providedLoader ??
                 createConfigLoader({
                     sources: options.sources,
                     context: options.context,
                     store: this.store,
                     freeze: options.freeze ?? true,
+                    // The manager seeds its store with initialValues and accepts
+                    // runtime set() writes; loading must layer sources on top of
+                    // those (by priority) instead of wiping them.
+                    clearStore: false,
                 });
         this.resolver = createConfigResolver(this.store, {
             strict: options.strict ?? true,
             allowUndefined: options.allowUndefined ?? true,
             clone: options.clone ?? false,
         });
+        if (options.autoLoad) {
+            // Kick off the initial load immediately; ready() (or load())
+            // exposes the in-flight promise. The catch handler prevents an
+            // unhandled rejection when nobody awaits ready(): the failure
+            // is still recorded in the FAILED state and lastError.
+            this.load().catch(() => { });
+        }
     }
     /**
      * Returns the current lifecycle state.
@@ -91,25 +123,40 @@ export class ConfigManager {
     }
     /**
      * Loads configuration.
+     *
+     * Calling load() while a load is already in flight returns the
+     * in-flight promise instead of starting a second load.
      */
     async load() {
         this.assertActive();
         if (this.isLoading) {
+            if (this.loadPromise) {
+                return this.loadPromise;
+            }
             throw new Error("Configuration manager is already loading.");
         }
         this.setState(ConfigManagerState.LOADING);
-        try {
-            const result = await this.loader.load();
-            this.lastLoadedAt = result.loadedAt;
-            this.lastError = undefined;
-            this.setState(ConfigManagerState.READY);
-            return result;
+        const promise = this.performLoad(false);
+        this.loadPromise = promise;
+        return promise;
+    }
+    /**
+     * 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.
+     */
+    async ready() {
+        this.assertActive();
+        if (this.loadPromise) {
+            await this.loadPromise;
+            return;
         }
-        catch (error) {
-            this.lastError = error;
-            this.setState(ConfigManagerState.FAILED);
-            throw error;
+        if (this.isReady) {
+            return;
         }
+        await this.load();
     }
     /**
      * Reloads configuration.
@@ -120,16 +167,34 @@ export class ConfigManager {
             throw new Error("Configuration manager is already loading.");
         }
         this.setState(ConfigManagerState.RELOADING);
+        const promise = this.performLoad(true);
+        this.loadPromise = promise;
+        return promise;
+    }
+    /**
+     * 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.
+     */
+    async performLoad(reload) {
         try {
-            const result = await this.loader.reload();
+            const result = reload
+                ? await this.loader.reload()
+                : await this.loader.load();
+            if (this.disposed) {
+                return result;
+            }
             this.lastLoadedAt = result.loadedAt;
             this.lastError = undefined;
             this.setState(ConfigManagerState.READY);
             return result;
         }
         catch (error) {
-            this.lastError = error;
-            this.setState(ConfigManagerState.FAILED);
+            if (!this.disposed) {
+                this.lastError = error;
+                this.setState(ConfigManagerState.FAILED);
+            }
             throw error;
         }
     }
@@ -146,6 +211,23 @@ export class ConfigManager {
         if (!result.valid) {
             throw new ConfigManagerValidationError(result.issues);
         }
+        // Property schemas flagged `secret` mark the corresponding store
+        // entries as sensitive so safe serialization redacts them.
+        for (const [key, propertySchema] of Object.entries(schema.properties)) {
+            if (!propertySchema.secret) {
+                continue;
+            }
+            const entry = this.store.getEntry(key);
+            if (entry && !entry.sensitive) {
+                this.store.set(key, entry.value, {
+                    source: entry.source,
+                    sourceType: entry.sourceType,
+                    priority: entry.priority,
+                    sensitive: true,
+                    resolved: entry.resolved,
+                });
+            }
+        }
         return cloneConfigValue(result.value);
     }
     /**
@@ -238,16 +320,27 @@ export class ConfigManager {
     }
     /**
      * Returns the complete configuration object.
+     *
+     * WARNING: values are returned RAW — sensitive entries are NOT
+     * redacted. Use toSafeObject() for logging or diagnostics.
      */
     toObject() {
         this.assertActive();
         return this.store.toObject();
     }
+    /**
+     * Returns the configuration object with sensitive values redacted.
+     */
+    toSafeObject() {
+        this.assertActive();
+        return this.store.toSafeObject();
+    }
     /**
      * Returns a manager status snapshot.
      */
     getStatus() {
         return {
+            name: this.name,
             state: this.state,
             loaded: this.isReady,
             loading: this.isLoading,

package/dist/configManager/configManager.type.d.ts

@@ -18,11 +18,22 @@ export declare enum ConfigManagerState {
  * Configuration manager options.
  */
 export interface ConfigManagerOptions extends ConfigResolverOptions {
+    /**
+     * Human-readable name for the manager. Surfaced by
+     * `manager.name` and in `getStatus()`.
+     */
+    readonly name?: string;
     readonly sources?: readonly ConfigSource[];
     readonly initialValues?: Readonly<Record<string, ConfigValue>>;
     readonly store?: ConfigStore;
     readonly loader?: ConfigLoader;
     readonly freeze?: boolean;
+    /**
+     * When true, the manager starts loading configuration immediately
+     * on construction. Await `manager.ready()` to wait for (and surface
+     * errors from) that initial load; `load()` called while the initial
+     * load is in flight reuses the same promise.
+     */
     readonly autoLoad?: boolean;
     readonly context?: {
         readonly environment?: string;
@@ -34,6 +45,7 @@ export interface ConfigManagerOptions extends ConfigResolverOptions {
  * Configuration manager status.
  */
 export interface ConfigManagerStatus {
+    readonly name: string;
     readonly state: ConfigManagerState;
     readonly loaded: boolean;
     readonly loading: boolean;

package/dist/configResolver/accessors/configResolver.scoped.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 } from "../../configSchema/index.js";
 import type { ConfigResolver } from "../core/configResolver.core.js";
 /**
  * Resolver scoped to a configuration key prefix.

package/dist/configResolver/accessors/index.d.ts

@@ -1,8 +1,7 @@
 /**
  * @zudojs/config/configResolver/accessors
  *
- * Configuration accessors and scoped resolver.
+ * Scoped configuration resolver.
  */
-export * from "./configResolver.accessors.js";
 export * from "./configResolver.scoped.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/configResolver/accessors/index.js

@@ -1,8 +1,7 @@
 /**
  * @zudojs/config/configResolver/accessors
  *
- * Configuration accessors and scoped resolver.
+ * Scoped configuration resolver.
  */
-export * from "./configResolver.accessors.js";
 export * from "./configResolver.scoped.js";
 //# sourceMappingURL=index.js.map

package/dist/configResolver/core/configResolver.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 } from "../../configSchema/index.js";
 import type { ConfigStore } from "../../configStore/configStore.core.js";
 import type { ConfigResolverOptions, ConfigResolutionResult } from "./configResolver.type.js";
 import { ScopedConfigResolver } from "../accessors/configResolver.scoped.js";

package/dist/configResolver/core/configResolver.core.js

@@ -1,5 +1,5 @@
-import { parseConfigBigInt, parseConfigBoolean, parseConfigDate, parseConfigNumber, } from "../../configValue/configValue.core.js";
-import { validateConfigValue } from "../../configSchema/configSchema.core.js";
+import { defineConfigProperty, parseConfigBigInt, parseConfigBoolean, parseConfigDate, parseConfigNumber, } from "../../configValue/configValue.core.js";
+import { validateConfigValue } from "../../configSchema/index.js";
 import { ScopedConfigResolver } from "../accessors/configResolver.scoped.js";
 /**
  * Resolves typed configuration values from a ConfigStore.
@@ -34,8 +34,19 @@ export class ConfigResolver {
             path: key,
             root: value,
         });
-        if (!result.valid && this.options.strict) {
-            throw new ConfigResolutionError(key, result.issues);
+        if (!result.valid) {
+            if (this.options.strict) {
+                throw new ConfigResolutionError(key, result.issues);
+            }
+            // Non-strict mode: never return an invalid value. Fall back to
+            // the schema default when present, otherwise undefined.
+            const fallback = typeof schema.default === "function"
+                ? schema.default()
+                : schema.default;
+            if (fallback === undefined && !this.options.allowUndefined) {
+                throw new ConfigResolutionError(key, result.issues);
+            }
+            return this.prepareValue(fallback);
         }
         if (result.value === undefined && !this.options.allowUndefined) {
             throw new ConfigResolutionError(key, [
@@ -211,7 +222,13 @@ export class ConfigResolver {
             return fallback;
         }
         if (value instanceof Date) {
-            return parseConfigDate(value);
+            const parsed = parseConfigDate(value);
+            if (parsed !== undefined) {
+                return parsed;
+            }
+            // Invalid Date instances route through the same strict/fallback
+            // handling as any other invalid type.
+            return this.invalidType(key, "date", value, fallback);
         }
         if (typeof value === "string") {
             const parsed = parseConfigDate(value);
@@ -274,7 +291,7 @@ export class ConfigResolver {
         for (const key of keys) {
             const value = this.get(key);
             if (value !== undefined) {
-                result[key] = value;
+                defineConfigProperty(result, key, value);
             }
         }
         return Object.freeze(result);
@@ -309,7 +326,7 @@ export class ConfigResolver {
         }
         const result = {};
         for (const [key, child] of Object.entries(value)) {
-            result[key] = this.prepareValue(child);
+            defineConfigProperty(result, key, this.prepareValue(child));
         }
         return result;
     }

package/dist/configSchema/configSchema.type.d.ts

@@ -57,24 +57,65 @@ export interface ConfigSchema<T extends ConfigValue = ConfigValue> {
     readonly nullable?: boolean;
     readonly default?: T | (() => T);
     readonly description?: string;
+    /**
+     * Marks the value as secret. When a ConfigManager validates its
+     * configuration, store entries whose property schema is flagged
+     * `secret` are marked sensitive, so toSafeObject() and safe entry
+     * serialization redact them.
+     */
     readonly secret?: boolean;
     readonly validate?: (value: T, context: ConfigValidationContext) => boolean | string | ConfigValidationIssue | readonly ConfigValidationIssue[];
     readonly transform?: (value: ConfigValue, context: ConfigValidationContext) => T;
 }
+/**
+ * A schema for a nested value whose value type the container does not
+ * know.
+ *
+ * `ConfigSchema<T>` is contravariant in `T` through `validate(value: T,
+ * ...)` and `transform`, so a `ConfigStringSchema` (which extends
+ * `ConfigSchema<string>`) is NOT assignable to `ConfigSchema<ConfigValue>`:
+ * a validator that accepts only `string` cannot stand in for one that must
+ * accept any `ConfigValue`.
+ *
+ * That made typed object schemas inexpressible. Declaring `properties` as
+ * `Record<string, ConfigSchema>` rejected every specific variant, including
+ * through a typed intermediate constant, so there was no user-side
+ * workaround short of a cast:
+ *
+ * ```ts
+ * const schema: ConfigObjectSchema = {
+ *   type: ConfigValueType.OBJECT,
+ *   // previously: not assignable to ConfigSchema<ConfigValue>
+ *   properties: { port: { type: ConfigValueType.NUMBER, min: 1 } },
+ * };
+ * ```
+ *
+ * A container of schemas over differing value types is an existential
+ * type, which TypeScript cannot express. `ConfigSchema<any>` is the
+ * deliberate encoding of that: `any` is assignable in both directions, so
+ * every variant is accepted and the validator can still invoke `validate`
+ * on what it reads back out.
+ *
+ * The named variants are unioned in as well so an inline literal may carry
+ * variant-specific fields (`minLength`, `min`, `max`, `enum`). Excess
+ * property checking against a union admits any property declared by some
+ * member, which a bare `ConfigSchema<any>` would reject.
+ */
+export type AnyConfigSchema = ConfigSchema<any> | ConfigStringSchema | ConfigNumberSchema | ConfigBooleanSchema | ConfigObjectSchema | ConfigArraySchema;
 /**
  * Object configuration schema.
  */
 export interface ConfigObjectSchema<T extends ConfigValue = ConfigValue> extends ConfigSchema<T> {
     readonly type: ConfigValueType.OBJECT;
-    readonly properties: Readonly<Record<string, ConfigSchema>>;
-    readonly additionalProperties?: boolean | ConfigSchema;
+    readonly properties: Readonly<Record<string, AnyConfigSchema>>;
+    readonly additionalProperties?: boolean | AnyConfigSchema;
 }
 /**
  * Array configuration schema.
  */
 export interface ConfigArraySchema<T extends ConfigValue = ConfigValue> extends ConfigSchema<T> {
     readonly type: ConfigValueType.ARRAY;
-    readonly items?: ConfigSchema;
+    readonly items?: AnyConfigSchema;
     readonly minItems?: number;
     readonly maxItems?: number;
 }
@@ -104,12 +145,4 @@ export interface ConfigNumberSchema extends ConfigSchema<number> {
 export interface ConfigBooleanSchema extends ConfigSchema<boolean> {
     readonly type: ConfigValueType.BOOLEAN;
 }
-/**
- * Schema definition shorthand.
- */
-export type ConfigSchemaDefinition = ConfigSchema | ConfigSchemaDefinition[] | ConfigSchemaBuilder;
-/**
- * Schema builder function.
- */
-export type ConfigSchemaBuilder = () => ConfigSchema;
 //# sourceMappingURL=configSchema.type.d.ts.map

package/dist/configSchema/configSchema.validator.d.ts

@@ -1,5 +1,5 @@
 import type { ConfigValue } from "../configValue/configValue.core.js";
-import type { ConfigSchema, ConfigValidationContext, ConfigValidationIssue, ConfigValidationResult } from "./configSchema.type.js";
+import type { AnyConfigSchema, ConfigValidationContext, ConfigValidationIssue, ConfigValidationResult } from "./configSchema.type.js";
 import { ConfigValueType } from "./configSchema.type.js";
 import type { ConfigObjectSchema } from "./configSchema.type.js";
 /**
@@ -17,7 +17,7 @@ export declare function createConfigValidationIssue(path: string, message: strin
 /**
  * Validates a value against a schema.
  */
-export declare function validateConfigValue(value: unknown, schema: ConfigSchema, context?: Partial<ConfigValidationContext>): ConfigValidationResult;
+export declare function validateConfigValue(value: unknown, schema: AnyConfigSchema, context?: Partial<ConfigValidationContext>): ConfigValidationResult;
 /**
  * Validates an entire configuration object.
  */
@@ -25,7 +25,7 @@ export declare function validateConfigObject(value: Readonly<Record<string, unkn
 /**
  * Validates an object against a schema and throws when invalid.
  */
-export declare function assertValidConfig(value: unknown, schema: ConfigSchema): ConfigValue;
+export declare function assertValidConfig(value: unknown, schema: AnyConfigSchema): ConfigValue;
 import { ConfigurationError } from "@zudojs/errors";
 /**
  * Error thrown when schema validation fails.

package/dist/configSchema/configSchema.validator.js

@@ -1,3 +1,4 @@
+import { defineConfigProperty, readOwnConfigProperty, } from "../configValue/configValue.core.js";
 import { ConfigValidationSeverity, ConfigValueType, } from "./configSchema.type.js";
 /**
  * Returns the runtime configuration value type.
@@ -121,7 +122,7 @@ function appendCustomValidationResult(result, path, issues) {
         issues.push(...result);
         return;
     }
-    issues.push(...(Array.isArray(result) ? result : [result]));
+    issues.push(result);
 }
 /**
  * Built-in schema validation rules.
@@ -209,11 +210,17 @@ export function validateConfigValue(value, schema, context) {
                 issues,
             };
         }
-        return {
-            valid: true,
-            value: resolveDefaultValue(schema),
-            issues,
-        };
+        const defaultValue = resolveDefaultValue(schema);
+        if (defaultValue === undefined) {
+            return {
+                valid: true,
+                issues,
+            };
+        }
+        // Applied defaults run through the same validation and transform
+        // pipeline as supplied values (defaultValue is defined here, so
+        // this recursion terminates immediately).
+        return validateConfigValue(defaultValue, schema, context);
     }
     if (value === null && schema.nullable) {
         return {
@@ -233,22 +240,49 @@ export function validateConfigValue(value, schema, context) {
         };
     }
     validateBuiltInRules(value, schema, validationContext, issues);
+    // An object schema carries `properties` / `additionalProperties`.
+    // Those were declared on ConfigObjectSchema but read nowhere in this
+    // function, so every nested object schema — including the ones used
+    // by ConfigResolver.resolve() and ConfigManager.resolve() — passed
+    // validation unconditionally. Delegate to validateConfigObject so
+    // nested constraints are actually enforced.
+    const objectSchema = schema;
+    let base = value;
+    if (matchesConfigType(value, ConfigValueType.OBJECT) &&
+        (objectSchema.properties !== undefined ||
+            objectSchema.additionalProperties !== undefined)) {
+        const nested = validateConfigObject(value, {
+            type: ConfigValueType.OBJECT,
+            properties: objectSchema.properties ?? {},
+            additionalProperties: objectSchema.additionalProperties,
+        }, path);
+        issues.push(...nested.issues);
+        if (nested.value !== undefined) {
+            base = nested.value;
+        }
+    }
     if (schema.validate) {
-        const result = schema.validate(value, validationContext);
+        const result = schema.validate(base, validationContext);
         appendCustomValidationResult(result, path, issues);
     }
-    let transformed = value;
-    if (schema.transform) {
+    let transformed = base;
+    const hasErrors = () => issues.some((issue) => issue.severity === ConfigValidationSeverity.ERROR);
+    // Transforms only run on values that passed validation; running
+    // them on invalid input would surface invalid values to callers.
+    if (schema.transform && !hasErrors()) {
         try {
-            transformed = schema.transform(value, validationContext);
+            transformed = schema.transform(base, validationContext);
         }
         catch (error) {
             issues.push(createConfigValidationIssue(path, error instanceof Error ? error.message : String(error), "TRANSFORM_FAILED"));
         }
     }
+    const valid = !hasErrors();
     return {
-        valid: !issues.some((issue) => issue.severity === ConfigValidationSeverity.ERROR),
-        value: transformed,
+        valid,
+        // Invalid values are never returned; callers fall back to the
+        // schema default or undefined instead.
+        value: valid ? transformed : undefined,
         issues,
     };
 }
@@ -271,7 +305,11 @@ export function validateConfigObject(value, schema, path = "$") {
     const result = {};
     for (const [key, propertySchema] of Object.entries(schema.properties)) {
         const propertyPath = `${path}.${key}`;
-        const propertyResult = validateConfigValue(value[key], propertySchema, {
+        // Own-property read only: bracket access would walk the prototype
+        // chain, so a schema property named "constructor" or "toString"
+        // would validate an inherited function instead of reporting a
+        // missing value.
+        const propertyResult = validateConfigValue(readOwnConfigProperty(value, key), propertySchema, {
             path: propertyPath,
             root: value,
             parent: value,
@@ -279,7 +317,7 @@ export function validateConfigObject(value, schema, path = "$") {
         });
         issues.push(...propertyResult.issues);
         if (propertyResult.value !== undefined) {
-            result[key] = propertyResult.value;
+            defineConfigProperty(result, key, propertyResult.value);
         }
     }
     for (const [key, child] of Object.entries(value)) {
@@ -300,11 +338,15 @@ export function validateConfigObject(value, schema, path = "$") {
             });
             issues.push(...propertyResult.issues);
             if (propertyResult.value !== undefined) {
-                result[key] = propertyResult.value;
+                defineConfigProperty(result, key, propertyResult.value);
             }
         }
         else {
-            result[key] = child;
+            // Own "__proto__"/"constructor"/"prototype" keys (e.g. from
+            // JSON.parse of untrusted input) are kept as own data
+            // properties: plain assignment would reach the inherited
+            // "__proto__" setter and mutate the result's prototype.
+            defineConfigProperty(result, key, child);
         }
     }
     return {

package/dist/configSchema/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @zudojs/config/configSchema
  *
- * Configuration schema validation with Zod.
+ * Dependency-free configuration schema validation.
  */
 export * from "./configSchema.type.js";
 export * from "./configSchema.validator.js";

package/dist/configSchema/index.js

@@ -1,7 +1,7 @@
 /**
  * @zudojs/config/configSchema
  *
- * Configuration schema validation with Zod.
+ * Dependency-free configuration schema validation.
  */
 export * from "./configSchema.type.js";
 export * from "./configSchema.validator.js";