@zudojs/core 0.0.1

package/dist/configuration/core/configuration.js

@@ -0,0 +1,206 @@
+/** Immutable configuration container. */
+export class Configuration {
+    values;
+    source;
+    namespace;
+    constructor(options = {}) {
+        this.source = options.source ?? "runtime";
+        this.namespace = options.namespace;
+        this.values = Object.freeze({ ...(options.values ?? {}) });
+    }
+    getNamespace() {
+        return this.namespace;
+    }
+    getSource() {
+        return this.source;
+    }
+    get(path) {
+        const normalizedPath = this.normalizePath(path);
+        if (!normalizedPath)
+            return undefined;
+        const parts = normalizedPath.split(".");
+        let current = this.values;
+        for (const part of parts) {
+            if (typeof current !== "object" || current === null || !(part in current))
+                return undefined;
+            current = current[part];
+        }
+        return current;
+    }
+    require(path) {
+        const value = this.get(path);
+        if (value === undefined)
+            throw new Error(`Required configuration "${path}" is not defined.`);
+        return value;
+    }
+    getByKey(key) {
+        return this.get(key.path);
+    }
+    requireByKey(key) {
+        const value = this.getByKey(key);
+        if (value === undefined)
+            throw new Error(`Required configuration "${key.path}" is not defined.`);
+        return value;
+    }
+    has(path) {
+        return this.get(path) !== undefined;
+    }
+    getBoolean(path, defaultValue) {
+        const value = this.get(path);
+        if (value === undefined)
+            return defaultValue;
+        if (typeof value === "boolean")
+            return value;
+        if (typeof value === "string") {
+            const normalized = value.trim().toLowerCase();
+            if (normalized === "true" || normalized === "1" || normalized === "yes")
+                return true;
+            if (normalized === "false" || normalized === "0" || normalized === "no")
+                return false;
+        }
+        throw new TypeError(`Configuration "${path}" is not a valid boolean.`);
+    }
+    getNumber(path, defaultValue) {
+        const value = this.get(path);
+        if (value === undefined)
+            return defaultValue;
+        if (typeof value === "number") {
+            if (Number.isFinite(value))
+                return value;
+            throw new TypeError(`Configuration "${path}" must be a finite number.`);
+        }
+        if (typeof value === "string") {
+            const parsed = Number(value.trim());
+            if (Number.isFinite(parsed))
+                return parsed;
+        }
+        throw new TypeError(`Configuration "${path}" is not a valid number.`);
+    }
+    getString(path, defaultValue) {
+        const value = this.get(path);
+        if (value === undefined)
+            return defaultValue;
+        if (typeof value === "string")
+            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) });
+    }
+    scope(namespace) {
+        const normalizedNamespace = this.normalizePath(namespace);
+        if (!normalizedNamespace)
+            throw new Error("Configuration scope cannot be empty.");
+        const scopedValues = this.get(normalizedNamespace);
+        if (scopedValues === undefined ||
+            typeof scopedValues !== "object" ||
+            scopedValues === null ||
+            Array.isArray(scopedValues)) {
+            return new Configuration({
+                values: {},
+                source: this.source,
+                namespace: normalizedNamespace,
+            });
+        }
+        return new Configuration({
+            values: scopedValues,
+            source: this.source,
+            namespace: normalizedNamespace,
+        });
+    }
+    entries() {
+        return Object.entries(this.values).map(([path, value]) => ({
+            path,
+            value,
+            source: this.source,
+        }));
+    }
+    toObject() {
+        return this.values;
+    }
+    merge(other) {
+        return new Configuration({
+            values: { ...this.values, ...other.toObject() },
+            source: other.source,
+            namespace: other.namespace ?? this.namespace,
+        });
+    }
+    with(path, value, source = "runtime") {
+        const normalizedPath = this.normalizePath(path);
+        if (!normalizedPath)
+            throw new Error("Configuration path cannot be empty.");
+        const values = this.setNestedValue(this.values, normalizedPath, value);
+        return new Configuration({ values, source, namespace: this.namespace });
+    }
+    without(path) {
+        const normalizedPath = this.normalizePath(path);
+        if (!normalizedPath)
+            return this;
+        const values = this.deleteNestedValue(this.values, normalizedPath);
+        return new Configuration({
+            values,
+            source: this.source,
+            namespace: this.namespace,
+        });
+    }
+    normalizePath(path) {
+        return path.trim().replace(/\s+/g, "");
+    }
+    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}"`);
+        }
+        const result = { ...source };
+        let current = result;
+        for (let index = 0; index < parts.length - 1; index++) {
+            const part = parts[index];
+            const existing = current[part];
+            const nested = existing !== null &&
+                typeof existing === "object" &&
+                !Array.isArray(existing)
+                ? { ...existing }
+                : {};
+            current[part] = nested;
+            current = nested;
+        }
+        current[parts[parts.length - 1]] = value;
+        return result;
+    }
+    deleteNestedValue(source, path) {
+        const parts = path.split(".");
+        if (parts.some((p) => p === "__proto__" || p === "constructor" || p === "prototype")) {
+            throw new TypeError(`Invalid configuration path: "${path}"`);
+        }
+        const result = structuredClone(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];
+        return result;
+    }
+}
+/** Creates an empty Configuration instance. */
+export function createConfiguration(options = {}) {
+    return new Configuration(options);
+}
+//# sourceMappingURL=configuration.js.map

package/dist/configuration/core/configuration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.js","sourceRoot":"","sources":["../../../src/configuration/core/configuration.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,43 @@
+/**
+ * A strongly typed key used to access a configuration value.
+ *
+ * The generic type T represents the expected value associated
+ * with the configuration key.
+ *
+ * Example:
+ *
+ * const portKey =
+ *   createConfigurationKey<number>("app.port");
+ *
+ * const port =
+ *   configuration.requireByKey(portKey);
+ */
+export interface ConfigurationKey<T> {
+    /**
+     * Dot separated configuration path.
+     *
+     * Examples:
+     *
+     * app.name
+     * app.port
+     * database.host
+     * auth.jwt.secret
+     */
+    readonly path: string;
+    /**
+     * Unique identifier for this configuration key.
+     *
+     * Symbols prevent accidental collisions between keys that
+     * happen to use the same path.
+     */
+    readonly id: symbol;
+}
+/**
+ * Creates a strongly typed configuration key.
+ *
+ * The key itself does not contain the configuration value.
+ * It only describes where that value can be found and what
+ * type the caller expects it to have.
+ */
+export declare function createConfigurationKey<T>(path: string): ConfigurationKey<T>;
+//# sourceMappingURL=configurationKey.key.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"configurationKey.key.d.ts","sourceRoot":"","sources":["../../../src/configuration/core/configurationKey.key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAW3E"}

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

@@ -0,0 +1,27 @@
+/**
+ * Creates a strongly typed configuration key.
+ *
+ * The key itself does not contain the configuration value.
+ * It only describes where that value can be found and what
+ * 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.");
+    }
+    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/configurationKey.key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configurationKey.key.js","sourceRoot":"","sources":["../../../src/configuration/core/configurationKey.key.ts"],"names":[],"mappings":"AAoCA;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAI,IAAY;IACpD,MAAM,cAAc,GAAG,0BAA0B,CAAC,IAAI,CAAC,CAAC;IAExD,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI,EAAE,cAAc;QACpB,EAAE,EAAE,MAAM,CAAC,cAAc,CAAC;KAC3B,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAS,0BAA0B,CAAC,IAAY;IAC9C,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,IAAI,SAAS,CAAC,0CAA0C,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACzC,CAAC"}

package/dist/configuration/core/configurationSource.source.d.ts

@@ -0,0 +1,114 @@
+import type { ConfigurationValue } from "./configuration.js";
+/**
+ * Well-known configuration source types.
+ *
+ * These describe where configuration values originate.
+ */
+export type ConfigurationSourceType = "default" | "environment" | "file" | "secret" | "remote" | "runtime" | "custom";
+/**
+ * A single configuration value supplied by a source.
+ */
+export interface ConfigurationSourceEntry {
+    /**
+     * Dot-separated configuration path.
+     *
+     * Example:
+     *
+     * database.host
+     */
+    readonly path: string;
+    /**
+     * Configuration value.
+     */
+    readonly value: ConfigurationValue;
+    /**
+     * Optional source-specific metadata.
+     */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Represents a source of configuration values.
+ *
+ * Sources are intentionally asynchronous because a source
+ * may eventually retrieve values from:
+ *
+ * a file
+ * a remote configuration service
+ * a secrets manager
+ * a database
+ * an external provider
+ */
+export interface ConfigurationSource {
+    /**
+     * Unique name of this configuration source.
+     */
+    readonly name: string;
+    /**
+     * Type of configuration source.
+     */
+    readonly type: ConfigurationSourceType;
+    /**
+     * Priority used when multiple sources provide the same
+     * configuration value.
+     *
+     * Higher priority values override lower priority values.
+     */
+    readonly priority: number;
+    /**
+     * Loads configuration entries from the source.
+     */
+    load(): Promise<readonly ConfigurationSourceEntry[]>;
+}
+/**
+ * Options used to create a configuration source.
+ */
+export interface ConfigurationSourceOptions {
+    /**
+     * Human-readable source name.
+     */
+    readonly name: string;
+    /**
+     * Source type.
+     */
+    readonly type: ConfigurationSourceType;
+    /**
+     * Source priority.
+     *
+     * Defaults to 0.
+     */
+    readonly priority?: number;
+}
+/**
+ * Base implementation for configuration sources.
+ *
+ * Concrete sources can extend this class and implement
+ * the load() method.
+ */
+export declare abstract class BaseConfigurationSource implements ConfigurationSource {
+    readonly name: string;
+    readonly type: ConfigurationSourceType;
+    readonly priority: number;
+    protected constructor(options: ConfigurationSourceOptions);
+    /**
+     * Loads configuration entries.
+     */
+    abstract load(): Promise<readonly ConfigurationSourceEntry[]>;
+}
+/**
+ * Creates a configuration source from a loader function.
+ *
+ * Useful for simple custom configuration sources without
+ * creating a complete class.
+ */
+export declare function createConfigurationSource(options: ConfigurationSourceOptions & {
+    readonly load: () => Promise<readonly ConfigurationSourceEntry[]>;
+}): ConfigurationSource;
+/**
+ * Sorts configuration sources according to their priority.
+ *
+ * Lower priority sources are loaded first.
+ * Higher priority sources are loaded last and therefore
+ * take precedence when values are merged.
+ */
+export declare function sortConfigurationSources(sources: readonly ConfigurationSource[]): ConfigurationSource[];
+//# sourceMappingURL=configurationSource.source.d.ts.map

package/dist/configuration/core/configurationSource.source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configurationSource.source.d.ts","sourceRoot":"","sources":["../../../src/configuration/core/configurationSource.source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAC/B,SAAS,GACT,aAAa,GACb,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,QAAQ,CAAC;AAEb;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IAEvC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,IAAI,IAAI,OAAO,CAAC,SAAS,wBAAwB,EAAE,CAAC,CAAC;CACtD;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IAEvC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,8BAAsB,uBAAwB,YAAW,mBAAmB;IAC1E,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,SAAgB,IAAI,EAAE,uBAAuB,CAAC;IAE9C,SAAgB,QAAQ,EAAE,MAAM,CAAC;IAEjC,SAAS,aAAa,OAAO,EAAE,0BAA0B,EAgBxD;IAED;;OAEG;IACH,SAAgB,IAAI,IAAI,OAAO,CAAC,SAAS,wBAAwB,EAAE,CAAC,CAAC;CACtE;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,0BAA0B,GAAG;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,SAAS,wBAAwB,EAAE,CAAC,CAAC;CACnE,GACA,mBAAmB,CAmBrB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,SAAS,mBAAmB,EAAE,GACtC,mBAAmB,EAAE,CAEvB"}

package/dist/configuration/core/configurationSource.source.js

@@ -0,0 +1,55 @@
+/**
+ * Base implementation for configuration sources.
+ *
+ * Concrete sources can extend this class and implement
+ * the load() method.
+ */
+export class BaseConfigurationSource {
+    name;
+    type;
+    priority;
+    constructor(options) {
+        const name = options.name.trim();
+        if (!name) {
+            throw new Error("Configuration source name cannot be empty.");
+        }
+        if (!Number.isFinite(options.priority ?? 0)) {
+            throw new TypeError("Configuration source priority must be a finite number.");
+        }
+        this.name = name;
+        this.type = options.type;
+        this.priority = options.priority ?? 0;
+    }
+}
+/**
+ * Creates a configuration source from a loader function.
+ *
+ * Useful for simple custom configuration sources without
+ * creating a complete class.
+ */
+export function createConfigurationSource(options) {
+    const name = options.name.trim();
+    if (!name) {
+        throw new Error("Configuration source name cannot be empty.");
+    }
+    if (!Number.isFinite(options.priority ?? 0)) {
+        throw new TypeError("Configuration source priority must be a finite number.");
+    }
+    return Object.freeze({
+        name,
+        type: options.type,
+        priority: options.priority ?? 0,
+        load: options.load,
+    });
+}
+/**
+ * Sorts configuration sources according to their priority.
+ *
+ * Lower priority sources are loaded first.
+ * Higher priority sources are loaded last and therefore
+ * take precedence when values are merged.
+ */
+export function sortConfigurationSources(sources) {
+    return [...sources].sort((a, b) => a.priority - b.priority);
+}
+//# sourceMappingURL=configurationSource.source.js.map

package/dist/configuration/core/configurationSource.source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configurationSource.source.js","sourceRoot":"","sources":["../../../src/configuration/core/configurationSource.source.ts"],"names":[],"mappings":"AAmGA;;;;;GAKG;AACH,MAAM,OAAgB,uBAAuB;IAC3B,IAAI,CAAS;IAEb,IAAI,CAA0B;IAE9B,QAAQ,CAAS;IAEjC,YAAsB,OAAmC;QACvD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAEjC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;QAChE,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,EAAE,CAAC;YAC5C,MAAM,IAAI,SAAS,CACjB,wDAAwD,CACzD,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC;IACxC,CAAC;CAMF;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAEC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IAEjC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,SAAS,CACjB,wDAAwD,CACzD,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI;QACJ,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,CAAC;QAC/B,IAAI,EAAE,OAAO,CAAC,IAAI;KACnB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAuC;IAEvC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;AAC9D,CAAC"}

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

@@ -0,0 +1,12 @@
+/**
+ * @zudojs/core/configuration/core
+ *
+ * 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 { createConfigurationKey } from "./configurationKey.key.js";
+export type { ConfigurationKey } from "./configurationKey.key.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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/configuration/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAExE,YAAY,EACV,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,IAAI,wBAAwB,EAC/C,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAEnE,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,iCAAiC,CAAC"}

package/dist/configuration/core/index.js

@@ -0,0 +1,9 @@
+/**
+ * @zudojs/core/configuration/core
+ *
+ * Core configuration types, keys, and source abstractions.
+ */
+export { Configuration, createConfiguration } from "./configuration.js";
+export { createConfigurationKey } from "./configurationKey.key.js";
+export { BaseConfigurationSource, createConfigurationSource, sortConfigurationSources, } from "./configurationSource.source.js";
+//# sourceMappingURL=index.js.map

package/dist/configuration/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/configuration/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AASxE,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAInE,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,iCAAiC,CAAC"}

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

@@ -0,0 +1,108 @@
+import { FrameworkError } from "../../errors/frameworkError.error.js";
+import { ErrorCode } from "../../errors/errorCode.code.js";
+/**
+ * Base error for all configuration related failures.
+ *
+ * This gives the configuration subsystem a common error type
+ * while still allowing callers to handle more specific errors.
+ */
+export declare class ConfigurationError extends FrameworkError {
+    /**
+     * Configuration path associated with the error.
+     */
+    readonly path?: string;
+    /**
+     * Original error that caused this failure.
+     */
+    name: string;
+    constructor(code: ErrorCode, message: string, options?: {
+        readonly path?: string;
+        readonly cause?: unknown;
+        readonly details?: Readonly<Record<string, unknown>>;
+    });
+}
+/**
+ * Thrown when configuration loading fails.
+ */
+export declare class ConfigurationSourceError extends ConfigurationError {
+    /**
+     * Name of the configuration source that failed.
+     */
+    readonly sourceName: string;
+    /**
+     * Type of configuration source.
+     */
+    readonly sourceType: string;
+    constructor(sourceName: string, sourceType: string, cause: unknown);
+}
+/**
+ * Thrown when a required configuration value is missing.
+ */
+export declare class ConfigurationMissingError extends ConfigurationError {
+    constructor(path: string);
+}
+/**
+ * Thrown when a configuration value has an invalid type
+ * or otherwise cannot be interpreted correctly.
+ */
+export declare class ConfigurationTypeError extends ConfigurationError {
+    /**
+     * Expected configuration type.
+     */
+    readonly expectedType: string;
+    /**
+     * Actual configuration type.
+     */
+    readonly actualType: string;
+    constructor(path: string, expectedType: string, value: unknown);
+}
+/**
+ * Thrown when a configuration value fails schema validation.
+ */
+export declare class ConfigurationSchemaError extends ConfigurationError {
+    /**
+     * Validation issues associated with the schema.
+     */
+    readonly issues: readonly ConfigurationErrorIssue[];
+    constructor(path: string, issues: readonly ConfigurationErrorIssue[]);
+}
+/**
+ * Represents a configuration-specific validation issue.
+ */
+export interface ConfigurationErrorIssue {
+    /**
+     * Configuration path.
+     */
+    readonly path: string;
+    /**
+     * Human-readable error message.
+     */
+    readonly message: string;
+    /**
+     * Optional validation code.
+     */
+    readonly code?: string;
+    /**
+     * Optional value that failed validation.
+     *
+     * Be careful not to include secrets here.
+     */
+    readonly value?: unknown;
+}
+/**
+ * Thrown when a configuration source contains
+ * duplicate or conflicting definitions that cannot
+ * be resolved.
+ */
+export declare class ConfigurationConflictError extends ConfigurationError {
+    /**
+     * Configuration path where the conflict occurred.
+     */
+    readonly conflictingPath: string;
+    /**
+     * Names of the conflicting sources.
+     */
+    readonly sources: readonly string[];
+    constructor(path: string, sources: readonly string[]);
+}
+//# sourceMappingURL=configurationError.error.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"configurationError.error.d.ts","sourceRoot":"","sources":["../../../src/configuration/error/configurationError.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AAEtE,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAE3D;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,cAAc;IACpD;;OAEG;IACH,SAAgB,IAAI,CAAC,EAAE,MAAM,CAAC;IAE9B;;OAEG;IAEa,IAAI,EAAE,MAAM,CAAwB;IAEpD,YACE,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;KACjD,EAkBP;CACF;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,kBAAkB;IAC9D;;OAEG;IACH,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC;;OAEG;IACH,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC,YAAmB,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAoBxE;CACF;AAED;;GAEG;AACH,qBAAa,yBAA0B,SAAQ,kBAAkB;IAC/D,YAAmB,IAAI,EAAE,MAAM,EAU9B;CACF;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,kBAAkB;IAC5D;;OAEG;IACH,SAAgB,YAAY,EAAE,MAAM,CAAC;IAErC;;OAEG;IACH,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC,YAAmB,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAoBpE;CACF;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,kBAAkB;IAC9D;;OAEG;IACH,SAAgB,MAAM,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAE3D,YAAmB,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,uBAAuB,EAAE,EAe1E;CACF;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,kBAAkB;IAChE;;OAEG;IACH,SAAgB,eAAe,EAAE,MAAM,CAAC;IAExC;;OAEG;IACH,SAAgB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAE3C,YAAmB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,EAmB1D;CACF"}