@digital-alchemy/core 26.2.17 → 26.5.1

package/dist/helpers/wiring.mjs

@@ -1,9 +1,62 @@
+/**
+ * @file helpers/wiring.mts — types and pure functions for the DI wiring engine.
+ *
+ * @remarks
+ * This file is the **type backbone** of `@digital-alchemy/core`. It owns
+ * `TServiceParams`, `CreateLibrary`, `buildSortOrder`, `wireOrder`, and the
+ * two wiring-boundary symbols (`COERCE_CONTEXT`, `WIRE_PROJECT`). Every
+ * downstream `@digital-alchemy` library depends on these types.
+ *
+ * **Split rationale.** This file was deliberately separated from
+ * `services/wiring.service.mts` to break a circular module reference that
+ * would form if types and the runtime bootstrap logic lived together. Do not
+ * merge them. Runtime orchestration (`CreateApplication`, `bootstrap`,
+ * `wireService`, `teardown`) lives in `services/wiring.service.mts`; pure
+ * types and pure functions live here.
+ *
+ * **Downstream impact.** Changes to `TServiceParams` shape or to any exported
+ * type here ripple into every library. Treat all public exports as breaking
+ * surface.
+ */
 import { is, LOAD_PROJECT } from "../index.mjs";
 import { eachSeries } from "./async.mjs";
 import { BootstrapException } from "./errors.mjs";
+// --- Wiring boundary symbols --------------------------------------------------
+/**
+ * Symbol used as the key for the `[WIRE_PROJECT]` method on library and
+ * application definitions.
+ *
+ * @remarks
+ * This symbol is the wiring boundary between a module definition and the
+ * bootstrap engine. `wiring.service.mts` calls `[WIRE_PROJECT]` on each
+ * module to initialise its lifecycle, load its configuration, and wire each
+ * service in priority order. Do not call `[WIRE_PROJECT]` outside of the
+ * bootstrap process.
+ *
+ * @internal
+ */
 export const WIRE_PROJECT = Symbol.for("wire-project");
 // #MARK: buildSortOrder
+/**
+ * Topologically sort the libraries declared by an application so that each
+ * library's dependencies are wired before it.
+ *
+ * @remarks
+ * Uses a simple iterative approach: on each pass, pick the first library whose
+ * required dependencies have all already been placed in `out`, then remove it
+ * from the working set. Optional dependencies that are not present in the
+ * application's library list are skipped rather than causing a failure.
+ *
+ * Version mismatches (same name, different object reference) emit a warning
+ * but do not block boot — the application-declared version wins.
+ *
+ * @throws {BootstrapException} `MISSING_DEPENDENCY` when a required dependency
+ * is not listed in the application's `libraries` array.
+ * @throws {BootstrapException} `BAD_SORT` when no progress can be made —
+ * usually indicates a circular dependency.
+ */
 export function buildSortOrder(app, logger) {
+    // fast path — nothing to sort when no libraries are declared
     if (is.empty(app.libraries)) {
         return [];
     }
@@ -41,6 +94,7 @@ export function buildSortOrder(app, logger) {
                 ...(library?.depends ?? []),
                 ...(library?.optionalDepends?.filter(i => app.libraries.some(index => i.name === index.name)) ?? []),
             ];
+            // a library with no remaining unsatisfied dependencies can go next
             if (is.empty(depends)) {
                 return true;
             }
@@ -55,9 +109,40 @@ export function buildSortOrder(app, logger) {
     }
     return out;
 }
+/**
+ * Cast a plain string to the branded `TContext` type.
+ *
+ * @remarks
+ * Used at the wiring boundary to produce context strings without importing the
+ * `TContext` brand into every caller. Prefer descriptive names like
+ * `"boilerplate:wiring"` over opaque identifiers so logs are readable.
+ *
+ * @internal
+ */
 export const COERCE_CONTEXT = (context) => context;
+/**
+ * Fixed context string used for all errors and log messages emitted during the
+ * wiring phase itself.
+ *
+ * @internal
+ */
 export const WIRING_CONTEXT = COERCE_CONTEXT("boilerplate:wiring");
 // #MARK: validateLibrary
+/**
+ * Assert that a library name and service map meet the minimum requirements to
+ * be wired.
+ *
+ * @remarks
+ * Called by `CreateLibrary` before any other work. Throws immediately if the
+ * name is empty or if any entry in `serviceList` is not a function, so
+ * misconfiguration surfaces at library-construction time rather than at wire
+ * time.
+ *
+ * @throws {BootstrapException} `MISSING_LIBRARY_NAME` when `project` is empty.
+ * @throws {BootstrapException} `INVALID_SERVICE_DEFINITION` when any service is not a function.
+ *
+ * @internal
+ */
 export function validateLibrary(project, serviceList) {
     if (is.empty(project)) {
         throw new BootstrapException(COERCE_CONTEXT("CreateLibrary"), "MISSING_LIBRARY_NAME", "Library name is required");
@@ -71,10 +156,23 @@ export function validateLibrary(project, serviceList) {
     }
 }
 // #MARK: wireOrder
+/**
+ * Produce a wiring order for a service list, hoisting `priority` items to the
+ * front and appending the remainder in their original order.
+ *
+ * @remarks
+ * Validates that `priority` contains no duplicates before merging, since a
+ * service wired twice would produce subtle bugs that are hard to diagnose at
+ * runtime.
+ *
+ * @throws {BootstrapException} `DOUBLE_PRIORITY` when `priority` contains
+ * duplicate service names.
+ */
 export function wireOrder(priority, list) {
     const out = [...(priority || [])];
     if (!is.empty(priority)) {
         const check = is.unique(priority);
+        // duplicate entries in priorityInit would wire the same service twice
         if (check.length !== out.length) {
             throw new BootstrapException(WIRING_CONTEXT, "DOUBLE_PRIORITY", "There are duplicate items in the priority load list");
         }
@@ -83,12 +181,34 @@ export function wireOrder(priority, list) {
     return temporary;
 }
 // #MARK: CreateLibrary
+/**
+ * Construct a `LibraryDefinition` from a configuration options object.
+ *
+ * @remarks
+ * `CreateLibrary` is the public factory for all non-application modules. It
+ * validates the name and service map, then builds the `[WIRE_PROJECT]`
+ * implementation that the bootstrap engine calls to wire each service in order.
+ *
+ * **Lifecycle hook timing.** Services should attach all lifecycle hooks at the
+ * top level of their factory function. Hooks attached after the
+ * `[WIRE_PROJECT]` call completes will be silently lost (worst case) or cause
+ * a fatal error (best case).
+ *
+ * **Priority init.** `priorityInit` services are wired before all others in
+ * declaration order. The remaining services wire in no guaranteed order.
+ *
+ * @throws {BootstrapException} `MISSING_LIBRARY_NAME` — via `validateLibrary`.
+ * @throws {BootstrapException} `INVALID_SERVICE_DEFINITION` — via `validateLibrary`.
+ * @throws {BootstrapException} `MISSING_PRIORITY_SERVICE` when a name listed in
+ * `priorityInit` does not correspond to a service in the `services` map.
+ */
 export function CreateLibrary({ name: libraryName, configuration = {}, priorityInit, services, depends, optionalDepends, ...extra }) {
     validateLibrary(libraryName, services);
     const serviceApis = {};
     if (!is.empty(priorityInit)) {
         priorityInit.forEach(name => {
             if (!is.function(services[name])) {
+                // fail fast at library-construction time; catching this at wire time is much harder to debug
                 throw new BootstrapException(WIRING_CONTEXT, "MISSING_PRIORITY_SERVICE", `${name} was listed as priority init, but was not found in services`);
             }
         });

package/dist/helpers/wiring.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"wiring.mjs","sourceRoot":"","sources":["../../src/helpers/wiring.mts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wiring.mjs","sourceRoot":"","sources":["../../src/helpers/wiring.mts"],"names":[],"mappings":"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"}

package/dist/services/als.service.d.mts

@@ -1,2 +1,12 @@
 import type { AlsExtension } from "../index.mts";
+/**
+ * AsyncLocalStorage wrapper for request-scoped context propagation.
+ *
+ * @remarks
+ * Creates and owns a single AsyncLocalStorage instance that holds
+ * request-scoped data across async boundaries. Provides methods to enter
+ * context, retrieve store, and run callbacks within a specific data context.
+ * The logger uses this to merge per-request fields into every log line
+ * without explicit parameter passing through the call chain.
+ */
 export declare function ALS(): AlsExtension;

package/dist/services/als.service.mjs

@@ -1,14 +1,63 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * AsyncLocalStorage wrapper for request-scoped context propagation.
+ *
+ * @remarks
+ * Creates and owns a single AsyncLocalStorage instance that holds
+ * request-scoped data across async boundaries. Provides methods to enter
+ * context, retrieve store, and run callbacks within a specific data context.
+ * The logger uses this to merge per-request fields into every log line
+ * without explicit parameter passing through the call chain.
+ */
 export function ALS() {
     const storage = new AsyncLocalStorage();
     return {
+        /**
+         * Retrieve the internal AsyncLocalStorage instance.
+         */
         asyncStorage: () => storage,
+        /**
+         * Enter context with data; data persists for synchronously-executed callbacks.
+         *
+         * @remarks
+         * Sets the async local context to the provided data object. All code running
+         * on the same async task will see this data when calling `getStore()`.
+         * Unlike `run()`, this does not execute a callback; the context persists
+         * until changed by another `enterWith()` or cleared by the async context.
+         */
         enterWith(data) {
+            // establish context for the current async task
             storage.enterWith(data);
         },
+        /**
+         * Extract log-scoped fields from current context.
+         *
+         * @remarks
+         * Retrieves the `logs` sub-object from the async local store, defaulting to
+         * an empty object if no context is set. Used by logger to inject context
+         * fields into every log entry automatically without requiring per-call passing.
+         */
         getLogData: () => storage.getStore()?.logs ?? {},
+        /**
+         * Retrieve the full async local store.
+         *
+         * @remarks
+         * Returns the complete data object set by `enterWith()` or `run()`, or
+         * undefined if no context is active. The returned object is read-only to
+         * callers; mutation must go through `enterWith()` or `run()`.
+         */
         getStore: () => storage.getStore(),
+        /**
+         * Execute a callback within a specific data context.
+         *
+         * @remarks
+         * Runs the callback with the provided data visible to `getStore()` for the
+         * duration of the callback and all async operations it spawns. The context
+         * is automatically cleared when the callback completes (or earlier if an
+         * async boundary is crossed outside the callback).
+         */
         run(data, callback) {
+            // wrap the callback to establish and maintain context for its duration
             storage.run(data, () => {
                 callback();
             });

package/dist/services/als.service.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"als.service.mjs","sourceRoot":"","sources":["../../src/services/als.service.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAIrD,MAAM,UAAU,GAAG;IACjB,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAkB,CAAC;IACxD,OAAO;QACL,YAAY,EAAE,GAAG,EAAE,CAAC,OAAO;QAC3B,SAAS,CAAC,IAAI;YACZ,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD,UAAU,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,IAAI,IAAK,EAAmB;QAClE,QAAQ,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE;QAClC,GAAG,CAAC,IAAoB,EAAE,QAA0B;YAClD,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE;gBACrB,QAAQ,EAAE,CAAC;YACb,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"als.service.mjs","sourceRoot":"","sources":["../../src/services/als.service.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAIrD;;;;;;;;;GASG;AACH,MAAM,UAAU,GAAG;IACjB,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAkB,CAAC;IACxD,OAAO;QACL;;WAEG;QACH,YAAY,EAAE,GAAG,EAAE,CAAC,OAAO;QAC3B;;;;;;;;WAQG;QACH,SAAS,CAAC,IAAI;YACZ,+CAA+C;YAC/C,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD;;;;;;;WAOG;QACH,UAAU,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,IAAI,IAAK,EAAmB;QAClE;;;;;;;WAOG;QACH,QAAQ,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE;QAClC;;;;;;;;WAQG;QACH,GAAG,CAAC,IAAoB,EAAE,QAA0B;YAClD,uEAAuE;YACvE,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE;gBACrB,QAAQ,EAAE,CAAC;YACb,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/services/configuration.service.d.mts

@@ -4,4 +4,26 @@ export declare const LOAD_PROJECT: unique symbol;
 export declare const EVENT_CONFIGURATION_UPDATED = "event_configuration_updated";
 export declare const INJECTED_DEFINITIONS: unique symbol;
 export type ConfigManager = ReturnType<typeof Configuration>;
+/**
+ * Central configuration state manager for the entire application.
+ *
+ * @remarks
+ * Owns two things: the `configuration` plain-object store (all live config
+ * values keyed by `module.key`) and the `configDefinitions` map (the schema
+ * metadata declared by each library/application via `CreateLibrary`).
+ *
+ * Exposed to other services through the `config` proxy injected into every
+ * `TServiceParams`. The proxy makes `config.boilerplate.LOG_LEVEL` feel like
+ * a plain property read but actually calls `object.get(configuration, path)`
+ * on each access so reads always reflect the current value.
+ *
+ * The initialization sequence (`INITIALIZE`) is called once during bootstrap,
+ * between `PreInit` and `PostConfig`, and runs all registered config loaders
+ * in priority order: env/argv first, then file (if enabled), then any
+ * custom loaders registered via `registerLoader`.
+ *
+ * Config values can be updated at runtime via `setConfig` or `merge`; any
+ * update emits `EVENT_CONFIGURATION_UPDATED` so downstream code (e.g. the
+ * logger's level filter) can react via `onUpdate` subscriptions.
+ */
 export declare function Configuration({ context, event, lifecycle, internal, }: TServiceParams): DigitalAlchemyConfiguration;

package/dist/services/configuration.service.mjs

@@ -4,19 +4,46 @@ export const LOAD_PROJECT = Symbol.for("load-project");
 export const EVENT_CONFIGURATION_UPDATED = "event_configuration_updated";
 export const INJECTED_DEFINITIONS = Symbol.for("injected-config");
 const DECIMALS = 2;
+/**
+ * Central configuration state manager for the entire application.
+ *
+ * @remarks
+ * Owns two things: the `configuration` plain-object store (all live config
+ * values keyed by `module.key`) and the `configDefinitions` map (the schema
+ * metadata declared by each library/application via `CreateLibrary`).
+ *
+ * Exposed to other services through the `config` proxy injected into every
+ * `TServiceParams`. The proxy makes `config.boilerplate.LOG_LEVEL` feel like
+ * a plain property read but actually calls `object.get(configuration, path)`
+ * on each access so reads always reflect the current value.
+ *
+ * The initialization sequence (`INITIALIZE`) is called once during bootstrap,
+ * between `PreInit` and `PostConfig`, and runs all registered config loaders
+ * in priority order: env/argv first, then file (if enabled), then any
+ * custom loaders registered via `registerLoader`.
+ *
+ * Config values can be updated at runtime via `setConfig` or `merge`; any
+ * update emits `EVENT_CONFIGURATION_UPDATED` so downstream code (e.g. the
+ * logger's level filter) can react via `onUpdate` subscriptions.
+ */
 export function Configuration({ context, event, lifecycle, internal, }) {
     const { is } = internal.utils;
-    // modern problems require modern solutions
+    // logger is not yet available at construction time (chicken-and-egg with
+    // boilerplate wiring order), so we grab it on the first lifecycle hook
     let logger;
     lifecycle.onPreInit(() => (logger = internal.boilerplate.logger.context(context)));
     const configDefinitions = new Map();
     const configuration = {};
     const loaded = new Set();
     const loaders = new Map([]);
-    // #MARK:
+    // #MARK: configValueProxy
+    // proxyData exists only to satisfy Proxy's ownKeys/has contract which requires
+    // the target object to have enumerable keys for spread operations to work;
+    // actual reads are always routed through object.get(configuration, path)
     const proxyData = {};
     const configValueProxy = new Proxy(proxyData, {
         get(_, project) {
+            // always read live from configuration so callers see post-load values
             return { ...internal.utils.object.get(configuration, project) };
         },
         has(_, key) {
@@ -28,37 +55,73 @@ export function Configuration({ context, event, lifecycle, internal, }) {
             return Object.keys(configuration);
         },
         set() {
+            // configuration is read-only via the proxy; use setConfig() to mutate
             return false;
         },
     });
     // #MARK: setConfig
+    /**
+     * Set a single config property and emit an update event.
+     *
+     * @remarks
+     * Writes directly into the live `configuration` store and fires
+     * `EVENT_CONFIGURATION_UPDATED` so any `onUpdate` listeners react
+     * immediately. Prefer `merge` for bulk updates.
+     */
     function setConfig(project, property, value) {
+        // logger may not be available if called during early wiring (before onPreInit)
+        logger?.trace({ name: setConfig, property: String(property), project }, "setting config");
         internal.utils.object.set(configuration, [project, property].join("."), value);
-        // in case anyone needs a hook
+        // notify any onUpdate listeners so they can react to the changed value
         event.emit(EVENT_CONFIGURATION_UPDATED, project, property);
+        logger?.debug({ name: setConfig, property: String(property), project }, "config set");
     }
     // #MARK: validateConfig
+    /**
+     * Assert that every `required: true` config property has been given a value.
+     *
+     * @throws {BootstrapException} `REQUIRED_CONFIGURATION_MISSING` if any
+     *   required property is still `undefined` after all loaders have run.
+     */
     function validateConfig() {
-        // * validate
-        // - ensure all required properties have been defined
         configDefinitions.forEach((definitions, project) => {
             Object.keys(definitions).forEach(key => {
                 const config = [project, key].join(".");
                 if (definitions[key].required &&
                     is.undefined(internal.utils.object.get(configuration, config))) {
-                    // ruh roh
+                    // required property was never populated by any loader or bootstrap config;
+                    // treat as a fatal wiring error so the app does not silently start broken
                     throw new BootstrapException(context, "REQUIRED_CONFIGURATION_MISSING", `Configuration property ${config} is not defined`);
                 }
             });
         });
     }
     // #MARK: registerLoader
+    /**
+     * Register a custom config loader for a given `DataTypes` key.
+     *
+     * @remarks
+     * Loaders run during `initialize`, after the built-in env/file loaders,
+     * in the order they were registered. Only one loader per `DataTypes` key
+     * is retained — registering twice replaces the first.
+     */
     function registerLoader(loader, name) {
+        // logger may not be available if called during early wiring (before onPreInit)
+        logger?.trace({ name: registerLoader, type: name }, "registering config loader");
         loaders.set(name, loader);
     }
     // #MARK: mergeConfig
+    /**
+     * Merge raw loader output into the live config store, respecting source restrictions.
+     *
+     * @remarks
+     * Each config property can declare a `source` allow-list (e.g. `["argv"]`).
+     * Properties whose source list does not include any of the `type` values
+     * passed here are silently skipped, preventing e.g. a file loader from
+     * overwriting an argv-only value.
+     */
     function mergeConfig(data, type) {
-        // * prevents loaders from setting properties that they aren't supposed to
+        // skip properties whose declared source list excludes every type in this batch
         configDefinitions.forEach((project, name) => {
             const keys = Object.keys(project);
             keys.forEach(key => {
@@ -74,9 +137,21 @@ export function Configuration({ context, event, lifecycle, internal, }) {
         });
     }
     // #MARK: initialize
+    /**
+     * Run all config loaders and validate required properties.
+     *
+     * @remarks
+     * Called exactly once by `wiring.service.mts` between `PreInit` and
+     * `PostConfig`. Order: env/argv → file (if `configSources.file` is truthy)
+     * → any custom loaders registered via `registerLoader`. Returns a formatted
+     * duration string that is included in bootstrap timing stats.
+     *
+     * @internal
+     */
     async function initialize(application) {
         const start = performance.now();
         const configTimings = {};
+        logger.trace({ name: initialize }, "loading configuration");
         // ConfigLoaderEnvironment handles both env and argv and tracks timings internally
         mergeConfig(await ConfigLoaderEnvironment({
             application,
@@ -86,7 +161,9 @@ export function Configuration({ context, event, lifecycle, internal, }) {
             timings: configTimings,
         }), ["env", "argv"]);
         const canFile = internal.boot.options?.configSources?.file ?? false;
+        // file loading is opt-in; default-off avoids unexpected file reads in tests
         if (canFile) {
+            logger.trace({ name: initialize }, "loading file config");
             const fileStart = performance.now();
             mergeConfig(await configLoaderFile({
                 application,
@@ -96,12 +173,15 @@ export function Configuration({ context, event, lifecycle, internal, }) {
             }), ["file"]);
             configTimings.file = `${(performance.now() - fileStart).toFixed(DECIMALS)}ms`;
         }
-        // * load!
+        // run any additional loaders registered by library code
         const configSources = internal.boot.options.configSources ?? {};
         await eachSeries([...loaders.entries()], async ([type, loader]) => {
+            // configSources[type] === false is an explicit opt-out; absence defaults to enabled
             if (configSources[type] === false) {
+                logger.trace({ name: initialize, type }, "loader disabled via configSources, skipping");
                 return;
             }
+            logger.trace({ name: initialize, type }, "running loader");
             const loaderStart = performance.now();
             mergeConfig(await loader({ application, configs: configDefinitions, internal, logger }), [
                 type,
@@ -110,14 +190,37 @@ export function Configuration({ context, event, lifecycle, internal, }) {
         });
         validateConfig();
         internal.boot.configTimings = configTimings;
-        return `${(performance.now() - start).toFixed(DECIMALS)}ms`;
+        const total = `${(performance.now() - start).toFixed(DECIMALS)}ms`;
+        logger.debug({ name: initialize, timings: configTimings, total }, "configuration loaded");
+        return total;
     }
     // #MARK: merge
+    /**
+     * Deep-merge a partial configuration object into the live store.
+     *
+     * @remarks
+     * Does not emit `EVENT_CONFIGURATION_UPDATED`; intended for bulk
+     * pre-boot merges (e.g. bootstrap `options.configuration`).
+     * Use `setConfig` for individual runtime updates that need listeners notified.
+     */
     function merge(merge) {
         return deepExtend(configuration, merge);
     }
     // #MARK: loadProject
+    /**
+     * Register a module's config schema and populate default values.
+     *
+     * @remarks
+     * Called once per library/application during wiring. Idempotent — a second
+     * call for the same library name is silently ignored to prevent re-initialisation
+     * during test re-runs. After registering defaults, any values already present
+     * in `options.configuration` for this project are applied immediately so they
+     * take effect before any loader runs.
+     *
+     * @internal
+     */
     function loadProject(library, definitions) {
+        // guard against double-registration (e.g. test re-runs, appendLibrary replacing)
         if (loaded.has(library)) {
             return;
         }
@@ -127,6 +230,8 @@ export function Configuration({ context, event, lifecycle, internal, }) {
             internal.utils.object.set(configuration, [library, key].join("."), definitions[key].default);
         });
         configDefinitions.set(library, definitions);
+        // apply any values that were baked into bootstrap options for this project;
+        // these take priority over schema defaults but lose to loader-sourced values
         const bootConfig = internal.boot.options?.configuration ?? {};
         if (library in bootConfig) {
             const project = library;
@@ -137,8 +242,18 @@ export function Configuration({ context, event, lifecycle, internal, }) {
         }
     }
     // #MARK: onUpdate
+    /**
+     * Subscribe to configuration change events.
+     *
+     * @remarks
+     * When `project` and/or `property` are provided the callback is only
+     * invoked for changes to that specific path. Omitting both subscribes to
+     * all configuration changes. The callback receives `(project, property)`
+     * matching the changed key.
+     */
     function onUpdate(callback, project, property) {
         event.on(EVENT_CONFIGURATION_UPDATED, (updatedProject, updatedProperty) => {
+            // filter to the specific project/property if the caller narrowed the subscription
             if (!is.empty(project) && project !== updatedProject) {
                 return;
             }
@@ -163,17 +278,30 @@ export function Configuration({ context, event, lifecycle, internal, }) {
          */
         [LOAD_PROJECT]: loadProject,
         /**
-         * retrieve the metadata that was originally used to define the configs
+         * Retrieve the metadata that was originally used to define the configs.
          */
         getDefinitions: () => configDefinitions,
         /**
-         * take a configuration object, and deep merge values
+         * Deep-merge a partial configuration object into the live store.
          *
-         * intended for initial loading workflows
+         * @remarks
+         * Intended for initial loading workflows. Does not fire `EVENT_CONFIGURATION_UPDATED`.
          */
         merge,
+        /**
+         * Subscribe to configuration change events.
+         *
+         * @remarks
+         * Narrow to a specific project and/or property, or omit both to receive all updates.
+         */
         onUpdate,
+        /**
+         * Register a custom config loader for a given `DataTypes` key.
+         */
         registerLoader,
+        /**
+         * Set a single config property and notify all `onUpdate` subscribers.
+         */
         set: setConfig,
     };
 }

package/dist/services/configuration.service.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"configuration.service.mjs","sourceRoot":"","sources":["../../src/services/configuration.service.mts"],"names":[],"mappings":"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"}
+{"version":3,"file":"configuration.service.mjs","sourceRoot":"","sources":["../../src/services/configuration.service.mts"],"names":[],"mappings":"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"}

package/dist/services/index.d.mts

@@ -1,3 +1,11 @@
+/**
+ * Service factories and utilities for @digital-alchemy/core.
+ *
+ * @remarks
+ * Exports all service-level APIs: lifecycle event registry, async local storage
+ * wrapper, type guards, configuration, logger, scheduler, wiring, and internal utilities.
+ * Each service is a factory function that receives TServiceParams and returns its API.
+ */
 export * from "./als.service.mts";
 export * from "./configuration.service.mts";
 export * from "./internal.service.mts";

package/dist/services/index.mjs

@@ -1,3 +1,11 @@
+/**
+ * Service factories and utilities for @digital-alchemy/core.
+ *
+ * @remarks
+ * Exports all service-level APIs: lifecycle event registry, async local storage
+ * wrapper, type guards, configuration, logger, scheduler, wiring, and internal utilities.
+ * Each service is a factory function that receives TServiceParams and returns its API.
+ */
 export * from "./als.service.mjs";
 export * from "./configuration.service.mjs";
 export * from "./internal.service.mjs";

package/dist/services/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../src/services/index.mts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../src/services/index.mts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,mBAAmB,CAAC;AAClC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC"}