@zudojs/core 0.0.1 → 1.0.0

package/dist/configuration/core/configuration.js

@@ -1,18 +1,100 @@
-/** Immutable configuration container. */
+import { normalizeConfigurationPath, requireConfigurationPath, } from "./configurationPath.path.js";
+import { ConfigurationMissingError, ConfigurationPathError, ConfigurationTypeError, } from "../error/configurationError.error.js";
+const FORBIDDEN_PATH_SEGMENTS = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+/**
+ * Recursively freezes a configuration value tree.
+ *
+ * Nodes that are already frozen are assumed to be deep-frozen
+ * (which holds for all trees produced by this module) and are
+ * skipped.
+ */
+function deepFreezeConfigurationValue(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Object.isFrozen(value))
+        return value;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            deepFreezeConfigurationValue(item);
+        return Object.freeze(value);
+    }
+    for (const child of Object.values(value)) {
+        deepFreezeConfigurationValue(child);
+    }
+    return Object.freeze(value);
+}
+/**
+ * Deep-copies a configuration value tree.
+ *
+ * Plain objects and arrays are cloned recursively; primitives are
+ * returned as-is. Used so accessors that hand out whole subtrees
+ * never expose internal references.
+ */
+function cloneConfigurationValue(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value)) {
+        return value.map((item) => cloneConfigurationValue(item));
+    }
+    const result = {};
+    for (const [key, child] of Object.entries(value)) {
+        result[key] = cloneConfigurationValue(child);
+    }
+    return result;
+}
+const STRICT_DECIMAL_PATTERN = /^[+-]?(?:\d+(?:\.\d+)?|\.\d+)$/;
+/**
+ * Immutable configuration container.
+ *
+ * The values tree is deep-frozen at construction, so accessors can
+ * safely hand out internal references. Callers should treat any
+ * object passed into the constructor (or `with()`) as owned by the
+ * configuration afterwards: it becomes frozen.
+ */
 export class Configuration {
     values;
     source;
     namespace;
+    pathSources;
     constructor(options = {}) {
         this.source = options.source ?? "runtime";
         this.namespace = options.namespace;
-        this.values = Object.freeze({ ...(options.values ?? {}) });
+        this.values = deepFreezeConfigurationValue((options.values ?? {}));
+        this.pathSources = new Map(options.sources ?? []);
     }
     getNamespace() {
         return this.namespace;
     }
-    getSource() {
-        return this.source;
+    /**
+     * Returns the source of a configuration path, or of the whole
+     * configuration when no path is supplied.
+     *
+     * When entries originate from multiple source types, "mixed"
+     * is returned.
+     */
+    getSource(path) {
+        if (path === undefined) {
+            const distinct = new Set(this.pathSources.values());
+            if (distinct.size === 0)
+                return this.source;
+            for (const key of Object.keys(this.values)) {
+                if (!this.hasSourceRecordFor(key)) {
+                    distinct.add(this.source);
+                    break;
+                }
+            }
+            if (distinct.size === 1)
+                return [...distinct][0];
+            return "mixed";
+        }
+        const normalizedPath = this.normalizePath(path);
+        if (!normalizedPath)
+            return this.source;
+        return this.resolvePathSource(normalizedPath);
     }
     get(path) {
         const normalizedPath = this.normalizePath(path);
@@ -21,7 +103,9 @@ export class Configuration {
         const parts = normalizedPath.split(".");
         let current = this.values;
         for (const part of parts) {
-            if (typeof current !== "object" || current === null || !(part in current))
+            if (typeof current !== "object" ||
+                current === null ||
+                !Object.hasOwn(current, part))
                 return undefined;
             current = current[part];
         }
@@ -30,7 +114,7 @@ export class Configuration {
     require(path) {
         const value = this.get(path);
         if (value === undefined)
-            throw new Error(`Required configuration "${path}" is not defined.`);
+            throw new ConfigurationMissingError(path);
         return value;
     }
     getByKey(key) {
@@ -39,7 +123,7 @@ export class Configuration {
     requireByKey(key) {
         const value = this.getByKey(key);
         if (value === undefined)
-            throw new Error(`Required configuration "${key.path}" is not defined.`);
+            throw new ConfigurationMissingError(key.path);
         return value;
     }
     has(path) {
@@ -58,7 +142,7 @@ export class Configuration {
             if (normalized === "false" || normalized === "0" || normalized === "no")
                 return false;
         }
-        throw new TypeError(`Configuration "${path}" is not a valid boolean.`);
+        throw new ConfigurationTypeError(path, "boolean", value);
     }
     getNumber(path, defaultValue) {
         const value = this.get(path);
@@ -67,14 +151,26 @@ export class Configuration {
         if (typeof value === "number") {
             if (Number.isFinite(value))
                 return value;
-            throw new TypeError(`Configuration "${path}" must be a finite number.`);
+            throw new ConfigurationTypeError(path, "number", value);
         }
         if (typeof value === "string") {
-            const parsed = Number(value.trim());
-            if (Number.isFinite(parsed))
-                return parsed;
+            const trimmed = value.trim();
+            if (trimmed === "") {
+                /*
+                 * Empty and whitespace-only strings are treated as
+                 * "value not provided" rather than silently coerced to 0.
+                 */
+                if (defaultValue !== undefined)
+                    return defaultValue;
+                throw new ConfigurationTypeError(path, "number", value);
+            }
+            if (STRICT_DECIMAL_PATTERN.test(trimmed)) {
+                const parsed = Number(trimmed);
+                if (Number.isFinite(parsed))
+                    return parsed;
+            }
         }
-        throw new TypeError(`Configuration "${path}" is not a valid number.`);
+        throw new ConfigurationTypeError(path, "number", value);
     }
     getString(path, defaultValue) {
         const value = this.get(path);
@@ -84,18 +180,21 @@ export class Configuration {
             return value;
         if (typeof value === "number" || typeof value === "boolean")
             return String(value);
-        throw new TypeError(`Configuration "${path}" is not a valid string.`);
-    }
-    createKey(path) {
-        const normalizedPath = this.normalizePath(path);
-        if (!normalizedPath)
-            throw new Error("Configuration key path cannot be empty.");
-        return Object.freeze({ path: normalizedPath, id: Symbol(normalizedPath) });
+        throw new ConfigurationTypeError(path, "string", value);
     }
     scope(namespace) {
-        const normalizedNamespace = this.normalizePath(namespace);
-        if (!normalizedNamespace)
-            throw new Error("Configuration scope cannot be empty.");
+        const normalizedNamespace = requireConfigurationPath(namespace);
+        const exactSource = this.pathSources.get(normalizedNamespace);
+        const scopedSource = exactSource ??
+            this.resolveAncestorSource(normalizedNamespace) ??
+            this.source;
+        const scopedSources = new Map();
+        const prefix = `${normalizedNamespace}.`;
+        for (const [recordedPath, source] of this.pathSources) {
+            if (recordedPath.startsWith(prefix)) {
+                scopedSources.set(recordedPath.slice(prefix.length), source);
+            }
+        }
         const scopedValues = this.get(normalizedNamespace);
         if (scopedValues === undefined ||
             typeof scopedValues !== "object" ||
@@ -103,58 +202,159 @@ export class Configuration {
             Array.isArray(scopedValues)) {
             return new Configuration({
                 values: {},
-                source: this.source,
+                source: scopedSource,
                 namespace: normalizedNamespace,
             });
         }
         return new Configuration({
             values: scopedValues,
-            source: this.source,
+            source: scopedSource,
             namespace: normalizedNamespace,
+            sources: scopedSources,
         });
     }
     entries() {
         return Object.entries(this.values).map(([path, value]) => ({
             path,
             value,
-            source: this.source,
+            source: this.resolvePathSource(path),
         }));
     }
+    /**
+     * Returns a deep copy of the complete values tree.
+     *
+     * The copy is unfrozen and independent of the configuration, so
+     * callers may mutate it freely without affecting this instance
+     * or anything derived from it.
+     */
     toObject() {
-        return this.values;
+        return cloneConfigurationValue(this.values);
     }
+    /**
+     * Deeply merges another configuration on top of this one.
+     *
+     * Objects are merged recursively, arrays and primitives are
+     * replaced. Per-path source attribution from both configurations
+     * is preserved; the other configuration wins on conflicts.
+     */
     merge(other) {
+        const values = this.deepMergeValues(this.values, other.values);
+        const sources = new Map(this.pathSources);
+        for (const [path, source] of other.pathSources)
+            sources.set(path, source);
         return new Configuration({
-            values: { ...this.values, ...other.toObject() },
+            values,
             source: other.source,
             namespace: other.namespace ?? this.namespace,
+            sources,
         });
     }
     with(path, value, source = "runtime") {
-        const normalizedPath = this.normalizePath(path);
-        if (!normalizedPath)
-            throw new Error("Configuration path cannot be empty.");
+        const normalizedPath = requireConfigurationPath(path);
         const values = this.setNestedValue(this.values, normalizedPath, value);
-        return new Configuration({ values, source, namespace: this.namespace });
+        const sources = new Map(this.pathSources);
+        const prefix = `${normalizedPath}.`;
+        for (const recordedPath of sources.keys()) {
+            if (recordedPath.startsWith(prefix))
+                sources.delete(recordedPath);
+        }
+        sources.set(normalizedPath, source);
+        return new Configuration({
+            values,
+            source: this.source,
+            namespace: this.namespace,
+            sources,
+        });
     }
     without(path) {
         const normalizedPath = this.normalizePath(path);
         if (!normalizedPath)
             return this;
         const values = this.deleteNestedValue(this.values, normalizedPath);
+        const sources = new Map(this.pathSources);
+        const prefix = `${normalizedPath}.`;
+        sources.delete(normalizedPath);
+        for (const recordedPath of [...sources.keys()]) {
+            if (recordedPath.startsWith(prefix))
+                sources.delete(recordedPath);
+        }
         return new Configuration({
             values,
             source: this.source,
             namespace: this.namespace,
+            sources,
         });
     }
     normalizePath(path) {
-        return path.trim().replace(/\s+/g, "");
+        return normalizeConfigurationPath(path);
+    }
+    hasSourceRecordFor(topLevelKey) {
+        if (this.pathSources.has(topLevelKey))
+            return true;
+        const prefix = `${topLevelKey}.`;
+        for (const recordedPath of this.pathSources.keys()) {
+            if (recordedPath.startsWith(prefix))
+                return true;
+        }
+        return false;
+    }
+    resolveAncestorSource(path) {
+        const parts = path.split(".");
+        for (let index = parts.length - 1; index > 0; index--) {
+            const ancestor = parts.slice(0, index).join(".");
+            const source = this.pathSources.get(ancestor);
+            if (source !== undefined)
+                return source;
+        }
+        return undefined;
+    }
+    resolvePathSource(path) {
+        const exact = this.pathSources.get(path);
+        if (exact !== undefined)
+            return exact;
+        const ancestor = this.resolveAncestorSource(path);
+        if (ancestor !== undefined)
+            return ancestor;
+        const prefix = `${path}.`;
+        const descendantSources = new Set();
+        for (const [recordedPath, source] of this.pathSources) {
+            if (recordedPath.startsWith(prefix))
+                descendantSources.add(source);
+        }
+        if (descendantSources.size === 1)
+            return [...descendantSources][0];
+        if (descendantSources.size > 1)
+            return "mixed";
+        return this.source;
+    }
+    deepMergeValues(base, override) {
+        if (base === null ||
+            override === null ||
+            typeof base !== "object" ||
+            typeof override !== "object" ||
+            Array.isArray(base) ||
+            Array.isArray(override)) {
+            return override;
+        }
+        const result = {};
+        for (const [key, value] of Object.entries(base)) {
+            if (FORBIDDEN_PATH_SEGMENTS.has(key))
+                continue;
+            result[key] = value;
+        }
+        for (const [key, value] of Object.entries(override)) {
+            if (FORBIDDEN_PATH_SEGMENTS.has(key))
+                continue;
+            const existing = result[key];
+            result[key] =
+                existing !== undefined ? this.deepMergeValues(existing, value) : value;
+        }
+        return result;
     }
     setNestedValue(source, path, value) {
         const parts = path.split(".");
-        if (parts.some((p) => p === "__proto__" || p === "constructor" || p === "prototype")) {
-            throw new TypeError(`Invalid configuration path: "${path}"`);
+        if (parts.some((p) => FORBIDDEN_PATH_SEGMENTS.has(p))) {
+            throw new ConfigurationPathError(path, "path names a forbidden segment.");
         }
         const result = { ...source };
         let current = result;
@@ -172,34 +372,31 @@ export class Configuration {
         current[parts[parts.length - 1]] = value;
         return result;
     }
+    /**
+     * Removes a nested value by shallow-cloning only the objects
+     * along the path, mirroring the strategy used by setNestedValue.
+     */
     deleteNestedValue(source, path) {
         const parts = path.split(".");
-        if (parts.some((p) => p === "__proto__" || p === "constructor" || p === "prototype")) {
-            throw new TypeError(`Invalid configuration path: "${path}"`);
+        if (parts.some((p) => FORBIDDEN_PATH_SEGMENTS.has(p))) {
+            throw new ConfigurationPathError(path, "path names a forbidden segment.");
         }
-        const result = structuredClone(source);
+        const result = { ...source };
         let current = result;
         for (let index = 0; index < parts.length - 1; index++) {
             const part = parts[index];
-            if (part === "__proto__" ||
-                part === "constructor" ||
-                part === "prototype")
-                return result;
             const next = current[part];
             if (next === null || typeof next !== "object" || Array.isArray(next))
                 return result;
-            current = next;
-        }
-        const lastPart = parts[parts.length - 1];
-        if (lastPart === "__proto__" ||
-            lastPart === "constructor" ||
-            lastPart === "prototype")
-            return result;
-        delete current[lastPart];
+            const clone = { ...next };
+            current[part] = clone;
+            current = clone;
+        }
+        delete current[parts[parts.length - 1]];
         return result;
     }
 }
-/** Creates an empty Configuration instance. */
+/** Creates a Configuration instance. */
 export function createConfiguration(options = {}) {
     return new Configuration(options);
 }

package/dist/configuration/core/configurationKey.key.d.ts

@@ -27,8 +27,10 @@ export interface ConfigurationKey<T> {
     /**
      * Unique identifier for this configuration key.
      *
-     * Symbols prevent accidental collisions between keys that
-     * happen to use the same path.
+     * Note that configuration lookups are performed by `path`,
+     * not by this symbol. The symbol only helps distinguish key
+     * instances from each other in debugging and diagnostics;
+     * two keys with the same path resolve the same value.
      */
     readonly id: symbol;
 }

package/dist/configuration/core/configurationKey.key.js

@@ -1,3 +1,4 @@
+import { requireConfigurationPath } from "./configurationPath.path.js";
 /**
  * Creates a strongly typed configuration key.
  *
@@ -6,22 +7,10 @@
  * type the caller expects it to have.
  */
 export function createConfigurationKey(path) {
-    const normalizedPath = normalizeConfigurationPath(path);
-    if (!normalizedPath) {
-        throw new Error("Configuration key path cannot be empty.");
-    }
+    const normalizedPath = requireConfigurationPath(path);
     return Object.freeze({
         path: normalizedPath,
         id: Symbol(normalizedPath),
     });
 }
-/**
- * Normalizes a configuration path.
- */
-function normalizeConfigurationPath(path) {
-    if (typeof path !== "string") {
-        throw new TypeError("Configuration key path must be a string.");
-    }
-    return path.trim().replace(/\s+/g, "");
-}
 //# sourceMappingURL=configurationKey.key.js.map

package/dist/configuration/core/configurationPath.path.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared configuration path normalization.
+ *
+ * This is the single canonical implementation used by the
+ * configuration container, keys, schemas, and registry.
+ *
+ * Paths are trimmed. Paths that still contain whitespace after
+ * trimming are rejected instead of silently rewritten, because
+ * silently stripping whitespace can turn a typo into a lookup
+ * for a completely different configuration value.
+ */
+export declare function normalizeConfigurationPath(path: string): string;
+/**
+ * Normalizes a configuration path and rejects empty results.
+ */
+export declare function requireConfigurationPath(path: string): string;
+//# sourceMappingURL=configurationPath.path.d.ts.map

package/dist/configuration/core/configurationPath.path.js

@@ -0,0 +1,33 @@
+import { ConfigurationPathError } from "../error/configurationError.error.js";
+/**
+ * Shared configuration path normalization.
+ *
+ * This is the single canonical implementation used by the
+ * configuration container, keys, schemas, and registry.
+ *
+ * Paths are trimmed. Paths that still contain whitespace after
+ * trimming are rejected instead of silently rewritten, because
+ * silently stripping whitespace can turn a typo into a lookup
+ * for a completely different configuration value.
+ */
+export function normalizeConfigurationPath(path) {
+    if (typeof path !== "string") {
+        throw new ConfigurationPathError(String(path), "path must be a string.");
+    }
+    const normalized = path.trim();
+    if (/\s/.test(normalized)) {
+        throw new ConfigurationPathError(path, "path must not contain whitespace.");
+    }
+    return normalized;
+}
+/**
+ * Normalizes a configuration path and rejects empty results.
+ */
+export function requireConfigurationPath(path) {
+    const normalized = normalizeConfigurationPath(path);
+    if (!normalized) {
+        throw new ConfigurationPathError(path, "path cannot be empty.");
+    }
+    return normalized;
+}
+//# sourceMappingURL=configurationPath.path.js.map

package/dist/configuration/core/index.d.ts

@@ -4,9 +4,15 @@
  * Core configuration types, keys, and source abstractions.
  */
 export { Configuration, createConfiguration } from "./configuration.js";
-export type { ConfigurationOptions, ConfigurationValue, ConfigurationSource as ConfigurationValueSource, ConfigurationEntry, } from "./configuration.js";
+export type { ConfigurationOptions, ConfigurationValue, ConfigurationEntry, ConfigurationEntrySource, } from "./configuration.js";
+/**
+ * Compatibility alias. The string-union source type now lives in
+ * configurationSource.source.ts as ConfigurationSourceType.
+ */
+export type { ConfigurationSourceType as ConfigurationValueSource } from "./configurationSource.source.js";
 export { createConfigurationKey } from "./configurationKey.key.js";
 export type { ConfigurationKey } from "./configurationKey.key.js";
+export { normalizeConfigurationPath, requireConfigurationPath, } from "./configurationPath.path.js";
 export { BaseConfigurationSource, createConfigurationSource, sortConfigurationSources, } from "./configurationSource.source.js";
 export type { ConfigurationSource, ConfigurationSourceType, ConfigurationSourceEntry, ConfigurationSourceOptions, } from "./configurationSource.source.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/configuration/core/index.js

@@ -5,5 +5,6 @@
  */
 export { Configuration, createConfiguration } from "./configuration.js";
 export { createConfigurationKey } from "./configurationKey.key.js";
+export { normalizeConfigurationPath, requireConfigurationPath, } from "./configurationPath.path.js";
 export { BaseConfigurationSource, createConfigurationSource, sortConfigurationSources, } from "./configurationSource.source.js";
 //# sourceMappingURL=index.js.map

package/dist/configuration/error/configurationError.error.d.ts

@@ -1,5 +1,9 @@
 import { FrameworkError } from "../../errors/frameworkError.error.js";
 import { ErrorCode } from "../../errors/errorCode.code.js";
+/**
+ * Produces a redacted message from an unknown cause.
+ */
+export declare function describeConfigurationCause(cause: unknown): string;
 /**
  * Base error for all configuration related failures.
  *
@@ -41,6 +45,13 @@ export declare class ConfigurationSourceError extends ConfigurationError {
 export declare class ConfigurationMissingError extends ConfigurationError {
     constructor(path: string);
 }
+/**
+ * Thrown when a configuration path is malformed: empty, containing
+ * whitespace, or naming a forbidden segment such as "__proto__".
+ */
+export declare class ConfigurationPathError extends ConfigurationError {
+    constructor(path: string, reason: string);
+}
 /**
  * Thrown when a configuration value has an invalid type
  * or otherwise cannot be interpreted correctly.

package/dist/configuration/error/configurationError.error.js

@@ -1,5 +1,18 @@
 import { FrameworkError } from "../../errors/frameworkError.error.js";
 import { ErrorCode } from "../../errors/errorCode.code.js";
+import { ConfigurationRedactor } from "./configurationRedactor.redactor.js";
+/**
+ * Default redactor used to scrub raw cause text before it is
+ * embedded in configuration error messages.
+ */
+const defaultErrorRedactor = new ConfigurationRedactor();
+/**
+ * Produces a redacted message from an unknown cause.
+ */
+export function describeConfigurationCause(cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return defaultErrorRedactor.redactText(message);
+}
 /**
  * Base error for all configuration related failures.
  *
@@ -45,7 +58,7 @@ export class ConfigurationSourceError extends ConfigurationError {
      */
     sourceType;
     constructor(sourceName, sourceType, cause) {
-        const causeMessage = cause instanceof Error ? cause.message : String(cause);
+        const causeMessage = describeConfigurationCause(cause);
         super(ErrorCode.CONFIGURATION_LOAD_FAILED, `Failed to load configuration source "${sourceName}": ${causeMessage}`, {
             cause,
             details: {
@@ -69,6 +82,21 @@ export class ConfigurationMissingError extends ConfigurationError {
         this.name = "ConfigurationMissingError";
     }
 }
+/**
+ * Thrown when a configuration path is malformed: empty, containing
+ * whitespace, or naming a forbidden segment such as "__proto__".
+ */
+export class ConfigurationPathError extends ConfigurationError {
+    constructor(path, reason) {
+        super(ErrorCode.CONFIGURATION_INVALID, `Invalid configuration path "${path}": ${reason}`, {
+            path,
+            details: {
+                reason,
+            },
+        });
+        this.name = "ConfigurationPathError";
+    }
+}
 /**
  * Thrown when a configuration value has an invalid type
  * or otherwise cannot be interpreted correctly.

package/dist/configuration/error/configurationRedactor.redactor.d.ts

@@ -97,8 +97,24 @@ export declare class ConfigurationRedactor {
     /**
      * Checks whether a path segment matches one of the
      * configured sensitive patterns.
+     *
+     * Matching is word-boundary aware: the segment is split into
+     * words on separators and camelCase transitions, and a pattern
+     * matches only when a consecutive run of words spells it out.
+     * This means "apiToken" and "access_token" match "token", but
+     * "tokenizer" and "secretary" do not match "token"/"secret".
      */
     private matchesSensitivePattern;
+    /**
+     * Redacts sensitive-looking fragments from free-form text such
+     * as error messages.
+     *
+     * Occurrences of "<sensitive>=value", "<sensitive>: value", and
+     * "<sensitive> value" have their value replaced. This is a
+     * best-effort scrub for diagnostics; it does not guarantee that
+     * arbitrary text contains no secrets.
+     */
+    redactText(text: string): string;
 }
 /**
  * Creates a ConfigurationRedactor.