@digital-alchemy/core 26.1.9 → 26.5.1

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

@@ -11,27 +11,82 @@ export type RemoveCallback = {
     remove: () => void;
     (): void;
 };
+/**
+ * Stateless utility bag attached to every `InternalDefinition` instance.
+ *
+ * @remarks
+ * Holds the global `EventEmitter`, the `is` type-guard singleton, and helpers
+ * for date math, object path operations, and string formatting.
+ * Constructed once per bootstrap cycle; replaced on teardown via a fresh
+ * `InternalDefinition`.
+ */
 export declare class InternalUtils {
     /**
-     * The global eventemitter. All of `@digital-alchemy` will be wired through this
+     * The global eventemitter. All of `@digital-alchemy` will be wired through this.
      *
-     * **NOTE:** bootstrapping process will initialize this at boot, and cleanup at teardown.
-     * Making listener changes should only be done from within the context of service functions
+     * @remarks
+     * Bootstrapping process will initialize this at boot and clean it up at
+     * teardown. Making listener changes should only be done from within the
+     * context of service functions.
      */
     event: EventEmitter;
     /**
-     * reference to `is` instance that's importable from `core`
+     * Reference to the `is` type-guard singleton importable from `core`.
      */
     is: IsIt;
     constructor();
+    /**
+     * Convert a `camelCase`, `snake_case`, or `kebab-case` string to `Title Case`.
+     */
     titleCase(input: string): string;
+    /**
+     * Compute the target `Dayjs` moment when an offset will elapse.
+     */
     getIntervalTarget(offset: TOffset): Dayjs;
+    /**
+     * Resolve a `TOffset` value to milliseconds.
+     */
     getIntervalMs(offset: TOffset): number;
+    /**
+     * Format the elapsed time between two dates as a human-readable relative string.
+     *
+     * @remarks
+     * Iterates unit buckets from largest (year) to smallest (second) and returns
+     * the first unit whose cutoff is exceeded. Falls back to "second" when the
+     * difference is less than one minute so there is always a non-empty result.
+     *
+     * @throws {Error} if either date argument cannot be parsed by `dayjs`.
+     */
     relativeDate(pastDate: inputFormats, futureDate?: inputFormats): string;
+    /**
+     * Dot-path object utilities: `get`, `set`, `del`, and `deepExtend`.
+     *
+     * @remarks
+     * Used throughout core to read and write nested configuration paths like
+     * `"boilerplate.LOG_LEVEL"` without assuming the intermediate objects exist.
+     */
     object: {
         deepExtend: typeof deepExtend;
+        /**
+         * Delete the value at `path` within `object`. Silently no-ops if any
+         * intermediate key does not exist.
+         */
         del<T>(object: T, path: string): void;
+        /**
+         * Read the value at `path` within `object`. Returns `undefined` if any
+         * intermediate key is missing.
+         */
         get<T, P extends string>(object: T, path: P): Get<T, P>;
+        /**
+         * Write `value` at `path` within `object`, creating intermediate objects
+         * as needed.
+         *
+         * @remarks
+         * When `doNotReplace` is true the write is skipped if the key already
+         * has a value — useful for applying defaults without overwriting explicit config.
+         *
+         * @throws {Error} if an intermediate path segment resolves to a non-object.
+         */
         set<T>(object: T, path: string, value: unknown, doNotReplace?: boolean): void;
     };
 }
@@ -40,51 +95,64 @@ type SafeExecOptions = {
     exec: () => TBlackHole;
 };
 type Phase = "bootstrap" | "teardown" | "running";
+/**
+ * Bootstrap-scoped state container passed as `internal` into every service.
+ *
+ * @remarks
+ * Created fresh on each `bootstrap()` call and torn down with the application.
+ * Holds the boot-time module registry (`loadedModules`, `moduleMappings`),
+ * the lifecycle event bus, references to boilerplate service APIs, and the
+ * `InternalUtils` helper bag.
+ *
+ * Downstream code should treat `internal` as read-only except for the
+ * documented mutation points (`safeExec`, `removeFn`, explicit setters on
+ * `boot.*`).
+ */
 export declare class InternalDefinition {
     /**
-     * Utility methods provided by boilerplate
+     * Utility methods provided by boilerplate.
      */
     boilerplate: Pick<GetApis<typeof LIB_BOILERPLATE>, "configuration" | "logger">;
     /**
-     * alias for `internal.boilerplate.configuration`
+     * Alias for `internal.boilerplate.configuration`.
      */
     config: GetApis<typeof LIB_BOILERPLATE>["configuration"];
     boot: {
         /**
-         * Options that were passed into bootstrap
+         * Options that were passed into bootstrap.
          */
         options: BootstrapOptions;
         /**
-         * Application that was bootstrapped
+         * Application that was bootstrapped.
          */
         application: ApplicationDefinition<ServiceMap, OptionalModuleConfiguration>;
         /**
-         * Lifecycle events that have completed
+         * Lifecycle events that have completed.
          */
         completedLifecycleEvents: Set<LifecycleStages>;
         /**
-         * for internal operations
+         * Internal lifecycle event bus; services attach hooks via the injected `lifecycle` param.
          */
         lifecycle: ReturnType<typeof CreateLifecycle>;
         /**
-         * Roughly speaking, what's the application doing? Mostly useful for debugging
+         * Roughly speaking, what is the application doing? Mostly useful for debugging.
          */
         phase: Phase;
         /**
-         * association of projects to { service : Declaration Function }
+         * Association of project names to `{ service: DeclarationFunction }`.
          */
         moduleMappings: Map<string, TModuleMappings>;
         /**
-         * association of projects to { service : Initialized Service }
+         * Association of project names to `{ service: InitializedService }`.
          */
         loadedModules: Map<string, TResolvedModuleMappings>;
         /**
-         * simple list of modules that have their construction phase complete
+         * Simple list of modules that have their construction phase complete.
          */
         constructComplete: Set<string>;
         startup: Date;
         /**
-         * Service construction times in order
+         * Service construction times in order.
          */
         serviceConstructionTimes: Array<{
             module: string;
@@ -92,23 +160,34 @@ export declare class InternalDefinition {
             duration: string;
         }>;
         /**
-         * Config loader execution times
+         * Config loader execution times.
          */
         configTimings?: Record<string, string>;
     };
     utils: InternalUtils;
     /**
+     * Wrap a remove callback so it can be called directly or via `{ remove }` destructuring.
      *
+     * @remarks
+     * Accommodates callers that prefer either:
      * ```typescript
-     * // Is it
      * const remove = doThing();
      * // or
      * const { remove } = doThing();
      * ```
-     *
-     * Now it's both! Inconsistency is the now supported
+     * Both styles are now supported; inconsistency between APIs is intentional.
      */
     removeFn(remove: () => TBlackHole): RemoveCallback;
+    /**
+     * Execute a callback, swallowing and logging any thrown error.
+     *
+     * @remarks
+     * Used throughout scheduler and lifecycle code to ensure that a misbehaving
+     * user callback cannot crash the entire wiring engine. Errors are logged at
+     * `error` level with full context so they remain visible without being fatal.
+     * Returns `undefined` on any error path so callers can treat the return type
+     * as optional without extra null-checks.
+     */
     safeExec<T>(options: (() => TBlackHole) | SafeExecOptions): Promise<T>;
 }
 export {};

package/dist/services/internal.service.mjs

@@ -18,22 +18,38 @@ const formatter = new Intl.RelativeTimeFormat("en", {
     style: "short",
 });
 // #MARK: misc
+/**
+ * Stateless utility bag attached to every `InternalDefinition` instance.
+ *
+ * @remarks
+ * Holds the global `EventEmitter`, the `is` type-guard singleton, and helpers
+ * for date math, object path operations, and string formatting.
+ * Constructed once per bootstrap cycle; replaced on teardown via a fresh
+ * `InternalDefinition`.
+ */
 export class InternalUtils {
     /**
-     * The global eventemitter. All of `@digital-alchemy` will be wired through this
+     * The global eventemitter. All of `@digital-alchemy` will be wired through this.
      *
-     * **NOTE:** bootstrapping process will initialize this at boot, and cleanup at teardown.
-     * Making listener changes should only be done from within the context of service functions
+     * @remarks
+     * Bootstrapping process will initialize this at boot and clean it up at
+     * teardown. Making listener changes should only be done from within the
+     * context of service functions.
      */
     event;
     /**
-     * reference to `is` instance that's importable from `core`
+     * Reference to the `is` type-guard singleton importable from `core`.
      */
     is;
     constructor() {
+        // unlimited listeners because every service may register lifecycle callbacks,
+        // and the default of 10 would fire spurious MaxListenersExceededWarnings
         this.event = new EventEmitter();
         this.event.setMaxListeners(NONE);
     }
+    /**
+     * Convert a `camelCase`, `snake_case`, or `kebab-case` string to `Title Case`.
+     */
     titleCase(input) {
         const matches = input.match(new RegExp("[a-z][A-Z]", "g"));
         if (matches) {
@@ -44,14 +60,30 @@ export class InternalUtils {
             .map(word => `${word.charAt(FIRST).toUpperCase()}${word.slice(EVERYTHING_ELSE)}`)
             .join(" ");
     }
+    /**
+     * Compute the target `Dayjs` moment when an offset will elapse.
+     */
     getIntervalTarget(offset) {
         const duration = toOffsetDuration(offset);
         const now = dayjs();
         return duration ? now.add(duration) : now;
     }
+    /**
+     * Resolve a `TOffset` value to milliseconds.
+     */
     getIntervalMs(offset) {
         return toOffsetMs(offset);
     }
+    /**
+     * Format the elapsed time between two dates as a human-readable relative string.
+     *
+     * @remarks
+     * Iterates unit buckets from largest (year) to smallest (second) and returns
+     * the first unit whose cutoff is exceeded. Falls back to "second" when the
+     * difference is less than one minute so there is always a non-empty result.
+     *
+     * @throws {Error} if either date argument cannot be parsed by `dayjs`.
+     */
     relativeDate(pastDate, futureDate = new Date().toISOString()) {
         const past = dayjs(pastDate);
         if (!past.isValid()) {
@@ -74,8 +106,19 @@ export class InternalUtils {
         return out;
     }
     // #region .object
+    /**
+     * Dot-path object utilities: `get`, `set`, `del`, and `deepExtend`.
+     *
+     * @remarks
+     * Used throughout core to read and write nested configuration paths like
+     * `"boilerplate.LOG_LEVEL"` without assuming the intermediate objects exist.
+     */
     object = {
         deepExtend,
+        /**
+         * Delete the value at `path` within `object`. Silently no-ops if any
+         * intermediate key does not exist.
+         */
         del(object, path) {
             const keys = path.split(".");
             let current = object; // Starting with the object as an unknown type
@@ -101,6 +144,10 @@ export class InternalUtils {
                 }
             }
         },
+        /**
+         * Read the value at `path` within `object`. Returns `undefined` if any
+         * intermediate key is missing.
+         */
         get(object, path) {
             const keys = path.split(".");
             let current = object;
@@ -112,6 +159,16 @@ export class InternalUtils {
             }
             return current;
         },
+        /**
+         * Write `value` at `path` within `object`, creating intermediate objects
+         * as needed.
+         *
+         * @remarks
+         * When `doNotReplace` is true the write is skipped if the key already
+         * has a value — useful for applying defaults without overwriting explicit config.
+         *
+         * @throws {Error} if an intermediate path segment resolves to a non-object.
+         */
         set(object, path, value, doNotReplace = false) {
             const keys = path.split(".");
             let current = object; // Starting with the object as an unknown type
@@ -144,27 +201,41 @@ export class InternalUtils {
     };
 }
 // #region Base definition
+/**
+ * Bootstrap-scoped state container passed as `internal` into every service.
+ *
+ * @remarks
+ * Created fresh on each `bootstrap()` call and torn down with the application.
+ * Holds the boot-time module registry (`loadedModules`, `moduleMappings`),
+ * the lifecycle event bus, references to boilerplate service APIs, and the
+ * `InternalUtils` helper bag.
+ *
+ * Downstream code should treat `internal` as read-only except for the
+ * documented mutation points (`safeExec`, `removeFn`, explicit setters on
+ * `boot.*`).
+ */
 export class InternalDefinition {
     /**
-     * Utility methods provided by boilerplate
+     * Utility methods provided by boilerplate.
      */
     boilerplate;
     /**
-     * alias for `internal.boilerplate.configuration`
+     * Alias for `internal.boilerplate.configuration`.
      */
     config;
     boot;
     utils = new InternalUtils();
     /**
+     * Wrap a remove callback so it can be called directly or via `{ remove }` destructuring.
      *
+     * @remarks
+     * Accommodates callers that prefer either:
      * ```typescript
-     * // Is it
      * const remove = doThing();
      * // or
      * const { remove } = doThing();
      * ```
-     *
-     * Now it's both! Inconsistency is the now supported
+     * Both styles are now supported; inconsistency between APIs is intentional.
      */
     removeFn(remove) {
         const out = remove;
@@ -172,10 +243,21 @@ export class InternalDefinition {
         return out;
     }
     // #MARK: safeExec
+    /**
+     * Execute a callback, swallowing and logging any thrown error.
+     *
+     * @remarks
+     * Used throughout scheduler and lifecycle code to ensure that a misbehaving
+     * user callback cannot crash the entire wiring engine. Errors are logged at
+     * `error` level with full context so they remain visible without being fatal.
+     * Returns `undefined` on any error path so callers can treat the return type
+     * as optional without extra null-checks.
+     */
     async safeExec(options) {
         const logger = this.boilerplate.logger.systemLogger;
         const context = is.function(options) ? undefined : options?.context;
         const exec = is.function(options) ? options : options?.exec;
+        // a non-function exec is a programming error, not a runtime error; log and bail
         if (!is.function(exec)) {
             logger.error({ context }, `received non-function callback to [safeExec]`);
             return undefined;

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

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

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

@@ -3,33 +3,93 @@ import type { TBlackHole, TContext } from "../index.mts";
 type MaybeEmptyTypes = string | undefined | Array<unknown> | number | Set<unknown> | Map<unknown, unknown> | object;
 type MaybeFunction = (...parameters: unknown[]) => TBlackHole;
 /**
- * type testing and basic conversion tools
+ * Type guard and basic utility class for runtime type testing.
+ *
+ * @remarks
+ * Provides a unified API for type narrowing, equality, emptiness checks, and
+ * basic conversions. All methods are designed as type guards where applicable
+ * (e.g., `array()`, `string()` narrow their arguments) and simple predicates
+ * elsewhere (e.g., `even()`, `empty()`). The singleton `is` instance is
+ * imported directly in lifecycle and wiring services to avoid circular
+ * dependencies; everywhere else it is accessed via `internal.utils.is`.
  */
 export declare class IsIt {
-    array(test: unknown): test is Array<unknown>;
+    /**
+     * Test whether a value is an array.
+     */
+    array<T>(test: unknown): test is Array<T>;
+    /**
+     * Test whether a value is a boolean.
+     */
     boolean(test: unknown): test is boolean;
     /**
-     * The internals of this test may get more creative as context evolves
+     * Test whether a value is a valid context (branded string).
+     *
+     * @remarks
+     * The internals of this test may get more creative as context evolves;
+     * currently a simple string type guard.
      */
     context(test: unknown): test is TContext;
     /**
-     * test is valid date
+     * Test whether a value is a valid Date object.
+     *
+     * @remarks
+     * Checks both that the value is a Date and that its time is a valid number;
+     * this filters out invalid Date instances like `new Date(NaN)`.
      */
     date(test: unknown): test is Date;
+    /**
+     * Test whether a value is a valid dayjs instance.
+     */
     dayjs(test: unknown): test is Dayjs;
+    /**
+     * Test whether a value is empty: undefined, zero-length, zero size, or empty object.
+     *
+     * @throws When the input type is not recognized (string, array, Map, Set, object, number, undefined).
+     */
     empty(test: MaybeEmptyTypes): boolean;
     /**
      * #MARK: Deep equality test
      */
+    /**
+     * Test whether two values are deeply equal using strict comparison.
+     */
     equal<T extends unknown>(a: T, b: T): boolean;
+    /**
+     * Test whether a number is even.
+     */
     even(test: number): boolean;
+    /**
+     * Test whether a value is a function.
+     */
     function<T extends MaybeFunction>(test: unknown): test is T;
+    /**
+     * Test whether a value is a valid number (not NaN).
+     */
     number(test: unknown): test is number;
+    /**
+     * Test whether a value is a plain object (not an array or null).
+     */
     object(test: unknown): test is object;
+    /**
+     * Return a random element from the provided list.
+     */
     random<T>(list: T[]): T;
+    /**
+     * Test whether a value is a string.
+     */
     string(test: unknown): test is string;
+    /**
+     * Test whether a value is a symbol.
+     */
     symbol(test: unknown): test is symbol;
+    /**
+     * Test whether a value is undefined.
+     */
     undefined(test: unknown): test is undefined;
+    /**
+     * Return a new array containing unique items from the input (deduplication).
+     */
     unique<T>(items: T[]): T[];
 }
 export declare const is: IsIt;

package/dist/services/is.service.mjs

@@ -3,32 +3,63 @@ import { isDeepStrictEqual, types } from "node:util";
 import dayjs from "dayjs";
 import { EMPTY, EVEN } from "../index.mjs";
 /**
- * type testing and basic conversion tools
+ * Type guard and basic utility class for runtime type testing.
+ *
+ * @remarks
+ * Provides a unified API for type narrowing, equality, emptiness checks, and
+ * basic conversions. All methods are designed as type guards where applicable
+ * (e.g., `array()`, `string()` narrow their arguments) and simple predicates
+ * elsewhere (e.g., `even()`, `empty()`). The singleton `is` instance is
+ * imported directly in lifecycle and wiring services to avoid circular
+ * dependencies; everywhere else it is accessed via `internal.utils.is`.
  */
 export class IsIt {
+    /**
+     * Test whether a value is an array.
+     */
     array(test) {
         return Array.isArray(test);
     }
+    /**
+     * Test whether a value is a boolean.
+     */
     boolean(test) {
         return typeof test === "boolean";
     }
     /**
-     * The internals of this test may get more creative as context evolves
+     * Test whether a value is a valid context (branded string).
+     *
+     * @remarks
+     * The internals of this test may get more creative as context evolves;
+     * currently a simple string type guard.
      */
     context(test) {
         return typeof test === "string";
     }
     /**
-     * test is valid date
+     * Test whether a value is a valid Date object.
+     *
+     * @remarks
+     * Checks both that the value is a Date and that its time is a valid number;
+     * this filters out invalid Date instances like `new Date(NaN)`.
      */
     date(test) {
         return types.isDate(test) && is.number(test.getTime());
     }
+    /**
+     * Test whether a value is a valid dayjs instance.
+     */
     dayjs(test) {
         return test instanceof dayjs && test.isValid();
     }
+    /**
+     * Test whether a value is empty: undefined, zero-length, zero size, or empty object.
+     *
+     * @throws When the input type is not recognized (string, array, Map, Set, object, number, undefined).
+     */
     empty(test) {
         if (test === undefined) {
+            // undefined is always empty
             return true;
         }
         if (typeof test === "string" || Array.isArray(test)) {
@@ -38,6 +69,7 @@ export class IsIt {
             return test.size === EMPTY;
         }
         if (typeof test === "object") {
+            // walk the object to detect whether any own properties exist
             for (const key in test) {
                 if (Object.prototype.hasOwnProperty.call(test, key)) {
                     return false;
@@ -46,42 +78,73 @@ export class IsIt {
             return true;
         }
         if (typeof test === "number") {
+            // NaN is the only number that is empty
             return Number.isNaN(test);
         }
-        // Optional: Throw an error or return a default value for unsupported types
+        // unsupported type — reject rather than silently pass
         throw new Error("Unsupported type " + typeof test);
     }
     /**
      * #MARK: Deep equality test
      */
+    /**
+     * Test whether two values are deeply equal using strict comparison.
+     */
     equal(a, b) {
         return isDeepStrictEqual(a, b);
     }
+    /**
+     * Test whether a number is even.
+     */
     even(test) {
         return test % EVEN === EMPTY;
     }
+    /**
+     * Test whether a value is a function.
+     */
     function(test) {
         return typeof test === "function";
     }
+    /**
+     * Test whether a value is a valid number (not NaN).
+     */
     number(test) {
         return typeof test === "number" && !Number.isNaN(test);
     }
+    /**
+     * Test whether a value is a plain object (not an array or null).
+     */
     object(test) {
         return typeof test === "object" && test !== null && !Array.isArray(test);
     }
+    /**
+     * Return a random element from the provided list.
+     */
     random(list) {
         // eslint-disable-next-line @typescript-eslint/no-magic-numbers
         return list[Math.floor(randomBytes(1)[0] % list.length)];
     }
+    /**
+     * Test whether a value is a string.
+     */
     string(test) {
         return typeof test === "string";
     }
+    /**
+     * Test whether a value is a symbol.
+     */
     symbol(test) {
         return typeof test === "symbol";
     }
+    /**
+     * Test whether a value is undefined.
+     */
     undefined(test) {
         return test === undefined;
     }
+    /**
+     * Return a new array containing unique items from the input (deduplication).
+     */
     unique(items) {
         return [...new Set(items)];
     }