@zudojs/core 0.1.0 → 1.1.0

package/dist/application/createApplication.js

@@ -0,0 +1,109 @@
+import { Application } from "./application.js";
+import { ApplicationContext } from "./applicationContext.context.js";
+import { Container } from "../container/container.js";
+import { ConfigurationManager, ConfigurationManagerState, createConfigurationManager, } from "../configuration/configurationManager.manager.js";
+import { ConsoleLogger } from "../logging/console/consoleLogger.logger.js";
+import { Lifecycle } from "../lifecycle/core/lifecycle.js";
+import { createModuleRegistry } from "../modules/moduleRegistry/moduleRegistry.registry.js";
+import { createModuleLoader } from "../modules/moduleLoader/moduleLoader.loader.js";
+import { createModuleLifecycleManager } from "../modules/moduleLifecycle/moduleLifecycle.lifecycle.js";
+import { createRuntime } from "../runtime/runtime.js";
+import { resolveRuntimeOptions } from "../runtime/runtimeOptions/runtimeOptions.resolver.js";
+import { getDefaultContextStorage } from "../context/provider/defaultContextStorage.storage.js";
+function isLogger(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.info === "function" &&
+        typeof value.error === "function");
+}
+/**
+ * Wires the standard application graph — container, configuration,
+ * logger, module registry/loader/lifecycle, runtime, and application
+ * lifecycle — and returns an initialized Application. One
+ * ContextStorage is threaded through every piece, so the runtime's
+ * execution context is visible from module hooks, container
+ * factories, lifecycle participants, and log entries.
+ *
+ * The runtime is created through a factory, so the application can be
+ * restarted (stop() then start()) with a fresh runtime each time.
+ */
+export async function createApplication(options = {}) {
+    const contextStorage = options.contextStorage ?? getDefaultContextStorage();
+    const logger = isLogger(options.logger)
+        ? options.logger
+        : new ConsoleLogger({ contextStorage, ...options.logger });
+    const configuration = options.configuration ?? createConfigurationManager();
+    if (configuration.getState() === ConfigurationManagerState.CREATED) {
+        await configuration.initialize();
+    }
+    const container = options.container ??
+        new Container({ currentScope: () => contextStorage.get() });
+    const moduleRegistry = options.moduleRegistry ?? createModuleRegistry();
+    if (options.modules && options.modules.length > 0) {
+        moduleRegistry.registerMany(options.modules);
+    }
+    const context = new ApplicationContext({
+        container,
+        /*
+         * An accessor rather than a snapshot: after
+         * `configuration.reload()` the application context must hand
+         * out the reloaded configuration, not the one captured here.
+         */
+        configuration: () => configuration.getConfiguration(),
+        modules: moduleRegistry,
+        logger,
+        contextStorage,
+    });
+    const runtimeOptions = options.runtime ?? {};
+    const resolved = resolveRuntimeOptions(runtimeOptions);
+    let previousLoader;
+    const createApplicationRuntime = () => {
+        /*
+         * A restart gets fresh module instances: the previous runtime has
+         * already stopped and destroyed them, so forget the instances and
+         * contexts before the new loader re-creates them.
+         */
+        if (previousLoader) {
+            for (const registration of moduleRegistry.getAll()) {
+                previousLoader.unload(registration.definition.id);
+            }
+        }
+        const moduleLoader = createModuleLoader(moduleRegistry, {
+            application: context,
+            configuration,
+            logger,
+        });
+        previousLoader = moduleLoader;
+        const moduleLifecycle = createModuleLifecycleManager(moduleRegistry, moduleLoader, {
+            continueOnInitializeError: resolved.startup.continueOnInitializeError,
+            continueOnStartError: resolved.startup.continueOnStartError,
+            continueOnStopError: resolved.shutdown.continueOnStopError,
+            continueOnDestroyError: resolved.shutdown.continueOnDestroyError,
+            contextStorage,
+        });
+        return createRuntime({
+            application: context,
+            configuration,
+            logger,
+            moduleRegistry,
+            moduleLoader,
+            moduleLifecycle,
+            signalTarget: options.signalTarget,
+            contextStorage,
+        }, runtimeOptions);
+    };
+    const lifecycle = new Lifecycle({ logger });
+    for (const participant of options.participants ?? []) {
+        lifecycle.register(participant);
+    }
+    const application = await Application.create({
+        context,
+        lifecycle,
+        runtime: createApplicationRuntime,
+    });
+    if (options.autoStart) {
+        await application.start();
+    }
+    return application;
+}
+//# sourceMappingURL=createApplication.js.map

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,51 @@ 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 inFlightReload;
     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>;
+    /**
+     * Reloads configuration from the registered sources.
+     *
+     * Overlapping calls are serialised: a reload requested while one
+     * is already in progress shares that in-flight reload instead of
+     * failing with InvalidStateError. A manager that is not ready yet
+     * is initialized instead.
+     */
     reload(): Promise<ConfigurationManagerResult>;
+    private performReload;
     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 +102,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,13 @@ export class ConfigurationManager {
     schemas;
     redactor;
     validationOptions;
+    listeners = new Map();
+    listenerErrors = [];
     configuration;
     loadResult;
     validationReport;
+    missingSetConfigurationWarned = false;
+    inFlightReload;
     stateValue = ConfigurationManagerState.CREATED;
     constructor(options = {}) {
         this.loader =
@@ -37,23 +43,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,19 +101,38 @@ export class ConfigurationManager {
         }
         catch (error) {
             this.stateValue = ConfigurationManagerState.FAILED;
+            this.emit(createConfigurationFailedEvent(this.stateValue, error));
             throw error;
         }
     }
+    /**
+     * Reloads configuration from the registered sources.
+     *
+     * Overlapping calls are serialised: a reload requested while one
+     * is already in progress shares that in-flight reload instead of
+     * failing with InvalidStateError. A manager that is not ready yet
+     * is initialized instead.
+     */
     async reload() {
+        if (this.inFlightReload)
+            return this.inFlightReload;
         if (this.stateValue !== ConfigurationManagerState.READY)
             return this.initialize();
+        const reload = this.performReload().finally(() => {
+            this.inFlightReload = undefined;
+        });
+        this.inFlightReload = reload;
+        return reload;
+    }
+    async performReload() {
         const previousConfiguration = this.configuration;
         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 +141,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 +156,7 @@ export class ConfigurationManager {
             this.stateValue = previousConfiguration
                 ? ConfigurationManagerState.READY
                 : ConfigurationManagerState.FAILED;
+            this.emit(createConfigurationFailedEvent(this.stateValue, error, previousConfiguration));
             throw error;
         }
     }
@@ -112,6 +173,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 +205,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