@zudojs/core 0.1.0 → 1.0.0

package/dist/application/index.d.ts

@@ -2,9 +2,10 @@
  * Application bootstrap and context management.
  *
  * Provides the main Application class, its context,
- * and application state types.
+ * application state types, and the createApplication factory.
  */
 export * from "./application.js";
 export * from "./applicationContext.context.js";
 export * from "./applicationState.state.js";
+export * from "./createApplication.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/application/index.js

@@ -2,9 +2,10 @@
  * Application bootstrap and context management.
  *
  * Provides the main Application class, its context,
- * and application state types.
+ * application state types, and the createApplication factory.
  */
 export * from "./application.js";
 export * from "./applicationContext.context.js";
 export * from "./applicationState.state.js";
+export * from "./createApplication.js";
 //# sourceMappingURL=index.js.map

package/dist/configuration/configurationManager.manager.d.ts

@@ -7,6 +7,7 @@ import { ConfigurationSchemaRegistry } from "./schema/configurationSchema.schema
 import type { ConfigurationValidationOptions, ConfigurationValidationReport } from "./schema/configurationValidation.validator.js";
 import { ConfigurationRedactor } from "./error/configurationRedactor.redactor.js";
 import type { ConfigurationRedactorOptions, RedactedConfiguration } from "./error/configurationRedactor.redactor.js";
+import type { ConfigurationEventListener, ConfigurationEventTypeValue } from "./events/configurationEvents.events.js";
 /** Lifecycle state of the configuration manager. */
 export declare enum ConfigurationManagerState {
     CREATED = "created",
@@ -32,6 +33,12 @@ export interface ConfigurationManagerResult {
     readonly load: ConfigurationLoadResult;
     readonly validation: ConfigurationValidationReport;
 }
+/**
+ * Event type accepted when subscribing to the manager.
+ *
+ * "*" subscribes to every configuration lifecycle event.
+ */
+export type ConfigurationEventSubscription = ConfigurationEventTypeValue | "*";
 /** Coordinates the complete configuration lifecycle. */
 export declare class ConfigurationManager {
     private readonly loader;
@@ -40,17 +47,41 @@ export declare class ConfigurationManager {
     private readonly schemas;
     private readonly redactor;
     private readonly validationOptions;
+    private readonly listeners;
+    private readonly listenerErrors;
     private configuration;
     private loadResult;
     private validationReport;
+    private missingSetConfigurationWarned;
     private stateValue;
     constructor(options?: ConfigurationManagerOptions);
+    /**
+     * Subscribes to configuration lifecycle events.
+     *
+     * Pass "*" to receive every event. Returns an unsubscribe
+     * function.
+     */
+    on(type: ConfigurationEventSubscription, listener: ConfigurationEventListener): () => void;
+    /** Removes a previously registered event listener. */
+    off(type: ConfigurationEventSubscription, listener: ConfigurationEventListener): boolean;
+    /**
+     * Returns errors thrown by event listeners.
+     *
+     * Listener failures never interrupt configuration loading;
+     * they are collected here for diagnostics.
+     */
+    getListenerErrors(): readonly unknown[];
     initialize(): Promise<ConfigurationManagerResult>;
     reload(): Promise<ConfigurationManagerResult>;
     getConfiguration(): Configuration;
     getProvider(): ConfigurationProvider;
     getRegistry(): ConfigurationRegistry;
     getSchemaRegistry(): ConfigurationSchemaRegistry;
+    /**
+     * Returns the active configuration scoped to a section
+     * registered with the manager's registry.
+     */
+    getSection(name: string): Configuration;
     getLoader(): ConfigurationLoader;
     getRedactor(): ConfigurationRedactor;
     getState(): ConfigurationManagerState;
@@ -61,6 +92,7 @@ export declare class ConfigurationManager {
     get<T = unknown>(path: string): T | undefined;
     require<T = unknown>(path: string): T;
     private providerConfiguration;
+    private emit;
     private ensureReady;
 }
 /** Creates a ConfigurationManager. */

package/dist/configuration/configurationManager.manager.js

@@ -2,10 +2,12 @@ import { Configuration } from "./core/configuration.js";
 import { ConfigurationLoader } from "./loader/configurationLoader.loader.js";
 import { DefaultConfigurationProvider } from "./registry/configurationProvider.provider.js";
 import { ConfigurationRegistry } from "./registry/configurationRegistry.registry.js";
+import { InvalidStateError } from "../errors/exceptions.js";
 import { ConfigurationSchemaRegistry } from "./schema/configurationSchema.schema.js";
-import { validateConfiguration } from "./schema/configurationValidation.validator.js";
+import { applyConfigurationSchemaDefaults, validateConfiguration, } from "./schema/configurationValidation.validator.js";
 import { ConfigurationValidationError } from "./schema/configurationValidation.validator.js";
 import { ConfigurationRedactor } from "./error/configurationRedactor.redactor.js";
+import { createConfigurationFailedEvent, createConfigurationInitializingEvent, createConfigurationLoadedEvent, createConfigurationReadyEvent, createConfigurationReloadedEvent, createConfigurationReloadingEvent, createConfigurationValidatedEvent, } from "./events/configurationEvents.events.js";
 /** Lifecycle state of the configuration manager. */
 export var ConfigurationManagerState;
 (function (ConfigurationManagerState) {
@@ -23,9 +25,12 @@ export class ConfigurationManager {
     schemas;
     redactor;
     validationOptions;
+    listeners = new Map();
+    listenerErrors = [];
     configuration;
     loadResult;
     validationReport;
+    missingSetConfigurationWarned = false;
     stateValue = ConfigurationManagerState.CREATED;
     constructor(options = {}) {
         this.loader =
@@ -37,23 +42,56 @@ export class ConfigurationManager {
             options.redactor ?? new ConfigurationRedactor(options.redactorOptions);
         this.validationOptions = options.validationOptions ?? {};
     }
+    /**
+     * Subscribes to configuration lifecycle events.
+     *
+     * Pass "*" to receive every event. Returns an unsubscribe
+     * function.
+     */
+    on(type, listener) {
+        let listeners = this.listeners.get(type);
+        if (!listeners) {
+            listeners = new Set();
+            this.listeners.set(type, listeners);
+        }
+        listeners.add(listener);
+        return () => this.off(type, listener);
+    }
+    /** Removes a previously registered event listener. */
+    off(type, listener) {
+        return this.listeners.get(type)?.delete(listener) ?? false;
+    }
+    /**
+     * Returns errors thrown by event listeners.
+     *
+     * Listener failures never interrupt configuration loading;
+     * they are collected here for diagnostics.
+     */
+    getListenerErrors() {
+        return [...this.listenerErrors];
+    }
     async initialize() {
         if (this.stateValue === ConfigurationManagerState.LOADING)
-            throw new Error("Configuration initialization is already in progress.");
+            throw new InvalidStateError("Configuration initialization is already in progress.", { state: this.stateValue });
         this.stateValue = ConfigurationManagerState.LOADING;
+        this.emit(createConfigurationInitializingEvent(this.stateValue));
         try {
-            const loadResult = await this.loader.load();
+            const loadResult = await this.loader.load(this.registry.getSources());
             this.loadResult = loadResult;
             this.configuration = loadResult.configuration;
             this.stateValue = ConfigurationManagerState.LOADED;
+            this.emit(createConfigurationLoadedEvent(this.stateValue, loadResult));
             const validation = await validateConfiguration(this.configuration, this.schemas, this.validationOptions);
             this.validationReport = validation;
             if (!validation.valid) {
                 this.stateValue = ConfigurationManagerState.FAILED;
                 throw new ConfigurationValidationError(validation.issues, validation.schemaCount, validation.invalidSchemaCount);
             }
+            this.configuration = applyConfigurationSchemaDefaults(this.configuration, this.schemas);
+            this.emit(createConfigurationValidatedEvent(this.stateValue, this.configuration, validation));
             this.providerConfiguration(this.configuration);
             this.stateValue = ConfigurationManagerState.READY;
+            this.emit(createConfigurationReadyEvent(this.stateValue, this.configuration, validation));
             return {
                 configuration: this.configuration,
                 load: loadResult,
@@ -62,6 +100,7 @@ export class ConfigurationManager {
         }
         catch (error) {
             this.stateValue = ConfigurationManagerState.FAILED;
+            this.emit(createConfigurationFailedEvent(this.stateValue, error));
             throw error;
         }
     }
@@ -72,9 +111,10 @@ export class ConfigurationManager {
         const previousLoadResult = this.loadResult;
         const previousValidation = this.validationReport;
         this.stateValue = ConfigurationManagerState.LOADING;
+        this.emit(createConfigurationReloadingEvent(this.stateValue, previousConfiguration));
         try {
-            const loadResult = await this.loader.load();
-            const configuration = loadResult.configuration;
+            const loadResult = await this.loader.load(this.registry.getSources());
+            let configuration = loadResult.configuration;
             const validation = await validateConfiguration(configuration, this.schemas, this.validationOptions);
             if (!validation.valid) {
                 this.configuration = previousConfiguration;
@@ -83,11 +123,13 @@ export class ConfigurationManager {
                 this.stateValue = ConfigurationManagerState.READY;
                 throw new ConfigurationValidationError(validation.issues, validation.schemaCount, validation.invalidSchemaCount);
             }
+            configuration = applyConfigurationSchemaDefaults(configuration, this.schemas);
             this.configuration = configuration;
             this.loadResult = loadResult;
             this.validationReport = validation;
             this.providerConfiguration(configuration);
             this.stateValue = ConfigurationManagerState.READY;
+            this.emit(createConfigurationReloadedEvent(this.stateValue, previousConfiguration, configuration, loadResult, validation));
             return { configuration, load: loadResult, validation };
         }
         catch (error) {
@@ -96,6 +138,7 @@ export class ConfigurationManager {
             this.stateValue = previousConfiguration
                 ? ConfigurationManagerState.READY
                 : ConfigurationManagerState.FAILED;
+            this.emit(createConfigurationFailedEvent(this.stateValue, error, previousConfiguration));
             throw error;
         }
     }
@@ -112,6 +155,14 @@ export class ConfigurationManager {
     getSchemaRegistry() {
         return this.schemas;
     }
+    /**
+     * Returns the active configuration scoped to a section
+     * registered with the manager's registry.
+     */
+    getSection(name) {
+        this.ensureReady();
+        return this.registry.getConfigurationSection(this.configuration, name);
+    }
     getLoader() {
         return this.loader;
     }
@@ -136,18 +187,46 @@ export class ConfigurationManager {
             : undefined;
     }
     get(path) {
+        this.ensureReady();
         return this.getProvider().get(path);
     }
     require(path) {
+        this.ensureReady();
         return this.getProvider().require(path);
     }
     providerConfiguration(configuration) {
-        if (this.provider instanceof DefaultConfigurationProvider)
+        if (typeof this.provider.setConfiguration === "function") {
             this.provider.setConfiguration(configuration);
+            return;
+        }
+        if (!this.missingSetConfigurationWarned) {
+            this.missingSetConfigurationWarned = true;
+            console.warn("ConfigurationManager: the configured ConfigurationProvider does not implement setConfiguration(); loaded configuration will not be pushed into the provider.");
+        }
+    }
+    emit(event) {
+        const listeners = [
+            ...(this.listeners.get(event.type) ?? []),
+            ...(this.listeners.get("*") ?? []),
+        ];
+        for (const listener of listeners) {
+            try {
+                const result = listener(event);
+                if (result instanceof Promise) {
+                    void result.catch((error) => {
+                        this.listenerErrors.push(error);
+                    });
+                }
+            }
+            catch (error) {
+                /* Listener failures must never break configuration loading. */
+                this.listenerErrors.push(error);
+            }
+        }
     }
     ensureReady() {
         if (this.stateValue !== ConfigurationManagerState.READY)
-            throw new Error(`Configuration is not ready. Current state: ${this.stateValue}.`);
+            throw new InvalidStateError(`Configuration is not ready. Current state: ${this.stateValue}.`, { state: this.stateValue });
     }
 }
 /** Creates a ConfigurationManager. */

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

@@ -1,34 +1,58 @@
-/** Represents a configuration source. */
-export type ConfigurationSource = "default" | "environment" | "file" | "secret" | "remote" | "runtime" | "custom";
+import type { ConfigurationSourceType } from "./configurationSource.source.js";
+import type { ConfigurationKey } from "./configurationKey.key.js";
 /** Configuration value types supported by the core configuration system. */
 export type ConfigurationValue = string | number | boolean | null | undefined | ConfigurationValue[] | {
     readonly [key: string]: ConfigurationValue;
 };
+/**
+ * Source attribution for a configuration entry.
+ *
+ * "mixed" is reported when the values under a path originate
+ * from more than one source type.
+ */
+export type ConfigurationEntrySource = ConfigurationSourceType | "mixed";
 /** Options used to create a Configuration instance. */
 export interface ConfigurationOptions {
     readonly values?: Record<string, ConfigurationValue>;
-    readonly source?: ConfigurationSource;
+    readonly source?: ConfigurationSourceType;
     readonly namespace?: string;
-}
-/** Typed configuration key. */
-export interface ConfigurationKey<T> {
-    readonly path: string;
-    readonly id: symbol;
+    /**
+     * Per-path source attribution.
+     *
+     * Used internally when deriving configurations so entry-level
+     * source information survives `with()`, `merge()`, and `scope()`.
+     */
+    readonly sources?: ReadonlyMap<string, ConfigurationSourceType>;
 }
 /** Represents a configuration entry. */
 export interface ConfigurationEntry<T = ConfigurationValue> {
     readonly path: string;
     readonly value: T;
-    readonly source: ConfigurationSource;
+    readonly source: ConfigurationEntrySource;
 }
-/** Immutable configuration container. */
+/**
+ * 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 declare class Configuration {
     private readonly values;
     private readonly source;
     private readonly namespace?;
+    private readonly pathSources;
     constructor(options?: ConfigurationOptions);
     getNamespace(): string | undefined;
-    getSource(): ConfigurationSource;
+    /**
+     * 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?: string): ConfigurationEntrySource;
     get<T = ConfigurationValue>(path: string): T | undefined;
     require<T = ConfigurationValue>(path: string): T;
     getByKey<T>(key: ConfigurationKey<T>): T | undefined;
@@ -37,17 +61,38 @@ export declare class Configuration {
     getBoolean(path: string, defaultValue?: boolean): boolean | undefined;
     getNumber(path: string, defaultValue?: number): number | undefined;
     getString(path: string, defaultValue?: string): string | undefined;
-    createKey<T>(path: string): ConfigurationKey<T>;
     scope(namespace: string): Configuration;
     entries(): readonly ConfigurationEntry[];
-    toObject(): Readonly<Record<string, ConfigurationValue>>;
+    /**
+     * 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(): Record<string, ConfigurationValue>;
+    /**
+     * 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: Configuration): Configuration;
-    with<T extends ConfigurationValue>(path: string, value: T, source?: ConfigurationSource): Configuration;
+    with<T extends ConfigurationValue>(path: string, value: T, source?: ConfigurationSourceType): Configuration;
     without(path: string): Configuration;
     private normalizePath;
+    private hasSourceRecordFor;
+    private resolveAncestorSource;
+    private resolvePathSource;
+    private deepMergeValues;
     private setNestedValue;
+    /**
+     * Removes a nested value by shallow-cloning only the objects
+     * along the path, mirroring the strategy used by setNestedValue.
+     */
     private deleteNestedValue;
 }
-/** Creates an empty Configuration instance. */
+/** Creates a Configuration instance. */
 export declare function createConfiguration(options?: ConfigurationOptions): Configuration;
 //# sourceMappingURL=configuration.d.ts.map