@digital-alchemy/core 26.2.17 → 26.5.28

package/dist/helpers/config.mjs

@@ -3,6 +3,16 @@ import path from "node:path";
 import { cwd } from "node:process";
 import dotenv from "@dotenvx/dotenvx";
 import { is } from "../index.mjs";
+/**
+ * Coerce a raw string (or boolean/array from argv parsing) to the target type.
+ *
+ * @remarks
+ * Called by env/argv loaders after key lookup to normalise the raw value before
+ * it is stored in the config map. `boolean` coercion is intentionally lenient:
+ * `"true"`, `"y"`, and `"1"` all produce `true`. `string[]` handles the
+ * minimist edge case where a single flag value arrives as a plain string rather
+ * than a one-element array.
+ */
 export function cast(data, type) {
     switch (type) {
         case "boolean": {
@@ -27,6 +37,19 @@ export function cast(data, type) {
     }
     return data;
 }
+/**
+ * Find the first key in `source` that also appears in `find`, using a
+ * case-insensitive fuzzy match that treats `-` and `_` as interchangeable.
+ *
+ * @remarks
+ * The search runs in two passes:
+ * 1. Exact match — fast path for the common case where cases and separators align.
+ * 2. Regex match — builds a pattern from `source[i]` that allows `-` or `_`
+ *    between each word boundary, then tests every element of `find`.
+ *
+ * This is the canonical key-resolution routine called by the env and argv
+ * loaders before falling back to unqualified key search.
+ */
 export function findKey(source, find) {
     return (
     // Find an exact match (if available) first
@@ -37,11 +60,34 @@ export function findKey(source, find) {
             return find.some(item => item.match(match));
         }));
 }
+/**
+ * Search `source` for the first key that case-insensitively matches `target`,
+ * treating `-` and `_` as interchangeable separators.
+ *
+ * @remarks
+ * Builds a single regex from `target` and tests it against every element of
+ * `source`. Unlike {@link findKey}, this function operates in one direction
+ * only (target → source) and is used for direct key lookups rather than
+ * cross-set intersection.
+ */
 export function iSearchKey(target, source) {
     const regex = new RegExp(`^${target.replaceAll(new RegExp("[-_]", "gi"), "[-_]?")}$`, "gi");
     return source.find(key => regex.exec(key) !== null);
 }
 /**
+ * Load a `.env` file into `process.env`, respecting the configured priority
+ * order.
+ *
+ * @remarks
+ * Priority (highest to lowest):
+ * 1. `--env-file` CLI switch
+ * 2. `BootstrapOptions.envFile`
+ * 3. `.env` in the current working directory (silent fallback)
+ *
+ * If the resolved path does not exist, a warning is emitted and loading is
+ * skipped rather than throwing. This keeps the application bootable in
+ * environments that intentionally have no `.env` file.
+ *
  * priorities:
  * - --env-file
  * - bootstrap envFile
@@ -66,6 +112,7 @@ export function loadDotenv(internal, CLI_SWITCHES, logger) {
             file = checkFile;
         }
         else {
+            // path was explicitly provided but does not exist; warn so operators notice the misconfiguration
             logger.warn({ checkFile, envFile, name: loadDotenv }, "invalid target for dotenv file");
         }
     }
@@ -85,6 +132,18 @@ export function loadDotenv(internal, CLI_SWITCHES, logger) {
         dotenv.config({ override: true, path: file, quiet: true });
     }
 }
+/**
+ * Coerce `value` to the concrete type described by `config`.
+ *
+ * @remarks
+ * Called after a raw value has been retrieved from a loader to normalise it
+ * before storage. Each branch matches a `ProjectConfigTypes` discriminant:
+ * - `"string"` — `String(value)`
+ * - `"number"` — `Number(value)`
+ * - `"string[]"` — splits on commas, or parses JSON arrays starting with `[`
+ * - `"record"` / `"internal"` — passes objects through; parses strings as JSON
+ * - `"boolean"` — accepts boolean literals and the strings `"y"` / `"true"`
+ */
 export function parseConfig(config, value) {
     switch (config.type) {
         case "string": {
@@ -98,6 +157,7 @@ export function parseConfig(config, value) {
                 return value;
             }
             if (is.string(value)) {
+                // leading "[" signals a JSON-serialised array; otherwise treat as CSV
                 return value.startsWith("[") ? JSON.parse(value) : value.split(",");
             }
             return [];

package/dist/helpers/config.mjs.map

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

package/dist/helpers/context.d.mts

@@ -1,7 +1,18 @@
 /**
- * Simple branded type
+ * Request context — a branded string type that enables per-request logging and state isolation.
+ *
+ * @remarks
+ * `TContext` is used throughout the framework to tag operations with a unique request
+ * identifier, enabling AsyncLocalStorage to associate logs and state changes with the
+ * calling context. It is passed to error constructors and used as a key in per-request
+ * data structures.
  */
 export type TContext = string & IContextBrand;
+/**
+ * Phantom brand to enforce type safety on context identifiers.
+ *
+ * @internal
+ */
 export interface IContextBrand {
     _context: symbol;
 }

package/dist/helpers/cron.d.mts

@@ -1,9 +1,33 @@
+/**
+ * Scheduler types and cron expression constants.
+ *
+ * @remarks
+ * Provides a comprehensive set of cron expressions for common scheduling patterns
+ * (second, minute, hour, day, week, month, year), three scheduler options types
+ * (cron, interval, sliding), and type definitions for time offsets and the
+ * scheduler service interface.
+ */
 import type { Dayjs } from "dayjs";
 import type { Duration, DurationUnitsObjectType, DurationUnitType } from "dayjs/plugin/duration.js";
 import type { RemoveCallback } from "../index.mts";
 import type { TContext } from "./context.mts";
 import type { SleepReturn, TBlackHole } from "./utilities.mts";
 import type { Schedule, SchedulerOptions } from "./wiring.mts";
+/**
+ * Predefined cron expressions for common scheduling patterns.
+ *
+ * @remarks
+ * Each constant is a cron expression string (6-field format: second minute hour
+ * dayOfMonth month dayOfWeek) that can be passed to `scheduler.cron(...)`.
+ * Expressions range from sub-second (EVERY_SECOND) to yearly (EVERY_YEAR),
+ * with specific business hours and weekday patterns included.
+ *
+ * @example
+ * ```typescript
+ * scheduler.cron({ exec: dailyTask, schedule: CronExpression.EVERY_DAY_AT_NOON });
+ * scheduler.cron({ exec: weeklyTask, schedule: CronExpression.EVERY_WEEKDAY });
+ * ```
+ */
 export declare enum CronExpression {
     EVERY_SECOND = "* * * * * *",
     EVERY_5_SECONDS = "*/5 * * * * *",
@@ -14,7 +38,9 @@ export declare enum CronExpression {
     EVERY_10_MINUTES = "0 */10 * * * *",
     EVERY_30_MINUTES = "0 */30 * * * *",
     EVERY_HOUR = "0 0-23/1 * * *",
-    EVERY_2_HOURS = "0 0-23/2 * * *",
+    EVERY_2_HOURS = "0 */2 * * *",
+    EVERY_2ND_HOUR = "0 */2 * * *",
+    EVERY_2ND_HOUR_FROM_1AM_THROUGH_11PM = "0 1-23/2 * * *",
     EVERY_3_HOURS = "0 0-23/3 * * *",
     EVERY_4_HOURS = "0 0-23/4 * * *",
     EVERY_5_HOURS = "0 0-23/5 * * *",
@@ -54,12 +80,9 @@ export declare enum CronExpression {
     EVERY_WEEKEND = "0 0 * * 6,0",
     EVERY_1ST_DAY_OF_MONTH_AT_MIDNIGHT = "0 0 1 * *",
     EVERY_1ST_DAY_OF_MONTH_AT_NOON = "0 12 1 * *",
-    EVERY_2ND_HOUR = "0 */2 * * *",
-    EVERY_2ND_HOUR_FROM_1AM_THROUGH_11PM = "0 1-23/2 * * *",
     EVERY_2ND_MONTH = "0 0 1 */2 *",
     EVERY_QUARTER = "0 0 1 */3 *",
     EVERY_6_MONTHS = "0 0 1 */6 *",
-    EVERY_YEAR = "0 0 1 1 *",
     EVERY_30_MINUTES_BETWEEN_9AM_AND_5PM = "0 */30 9-17 * * *",
     EVERY_30_MINUTES_BETWEEN_9AM_AND_6PM = "0 */30 9-18 * * *",
     EVERY_30_MINUTES_BETWEEN_10AM_AND_7PM = "0 */30 10-19 * * *",
@@ -87,36 +110,160 @@ export declare enum CronExpression {
     MONDAY_TO_FRIDAY_AT_8PM = "0 0 20 * * 1-5",
     MONDAY_TO_FRIDAY_AT_9PM = "0 0 21 * * 1-5",
     MONDAY_TO_FRIDAY_AT_10PM = "0 0 22 * * 1-5",
-    MONDAY_TO_FRIDAY_AT_11PM = "0 0 23 * * 1-5"
+    MONDAY_TO_FRIDAY_AT_11PM = "0 0 23 * * 1-5",
+    EVERY_YEAR = "0 0 1 1 *"
 }
+/**
+ * Schedule type identifier for cron-based schedules.
+ *
+ * @internal
+ */
 export declare const CRON_SCHEDULE = "CRON_SCHEDULE";
+/**
+ * Schedule type identifier for interval-based schedules.
+ *
+ * @internal
+ */
 export declare const INTERVAL_SCHEDULE = "INTERVAL_SCHEDULE";
+/**
+ * Options for a cron-based scheduled task.
+ *
+ * @remarks
+ * Extends `SchedulerOptions` with a `schedule` field that accepts one or more
+ * cron expressions (or `CronExpression` enum values). Multiple schedules will
+ * trigger the callback at the union of all specified times.
+ */
 export type SchedulerCronOptions = SchedulerOptions & {
+    /** Cron expression(s) — single or array — determining execution times. */
     schedule: Schedule | Schedule[];
 };
+/**
+ * Options for an interval-based scheduled task.
+ *
+ * @remarks
+ * Extends `SchedulerOptions` with an `interval` field specifying the time
+ * between executions (in milliseconds or a `TOffset` specification).
+ */
 export type SchedulerIntervalOptions = SchedulerOptions & {
+    /** Time between executions, in milliseconds. */
     interval: number;
 };
+/**
+ * Options for a sliding-window scheduled task.
+ *
+ * @remarks
+ * Executes on a computed schedule: the `reset` cron determines how often to
+ * call the `next()` function to retrieve the next execution time. If `next()`
+ * returns a valid time (Dayjs, Date, number, or string), a timeout is set for
+ * that time; undefined means skip this iteration. Useful for event-driven or
+ * data-dependent scheduling.
+ */
 export type SchedulerSlidingOptions = SchedulerOptions & {
     /**
-     * How often to run the `next` method, to retrieve the next scheduled execution time
+     * Cron expression determining how often to recompute the next execution time.
+     *
+     * @remarks
+     * The `next()` callback is invoked on this schedule; its return value is
+     * used to compute the actual execution time.
      */
     reset: Schedule;
     /**
-     * Return something time like. undefined = skip next
+     * Compute the next execution time.
+     *
+     * @remarks
+     * Called on the `reset` schedule; return a time-like value to execute,
+     * or undefined to skip this iteration.
      */
     next: () => Dayjs | string | number | Date | undefined;
 };
+/**
+ * Scheduler service interface — methods to schedule and execute tasks.
+ *
+ * @remarks
+ * Returned by the scheduler service factory after context binding. Provides
+ * four primary scheduling methods (cron, interval, sliding, setTimeout/setInterval)
+ * and a sleep utility. All methods return a `RemoveCallback` to cancel the
+ * scheduled task.
+ */
 export type DigitalAlchemyScheduler = {
+    /**
+     * Schedule a task on a cron expression.
+     *
+     * @remarks
+     * Accepts one or more cron schedules (or `CronExpression` constants) and
+     * executes the callback at matching times. Returns a function to remove
+     * the scheduled task.
+     */
     cron: (options: SchedulerCronOptions) => RemoveCallback;
+    /**
+     * Schedule a task with a dynamically computed execution time.
+     *
+     * @remarks
+     * On the `reset` schedule, calls the `next()` function to determine the next
+     * execution time. If `next()` returns a valid time, schedules execution; if
+     * undefined, skips. Useful for event-triggered or data-dependent scheduling.
+     */
     sliding: (options: SchedulerSlidingOptions) => RemoveCallback;
+    /**
+     * Schedule a task to run repeatedly at a fixed interval.
+     *
+     * @remarks
+     * Executes the callback after the first interval, then repeats. Useful for
+     * background polling or periodic maintenance tasks.
+     */
     setInterval: (callback: () => TBlackHole, target: TOffset) => RemoveCallback;
+    /**
+     * Schedule a task to run once after a delay.
+     *
+     * @remarks
+     * Executes the callback once after the specified time offset has elapsed.
+     * Useful for deferred operations or delayed initialization.
+     */
     setTimeout: (callback: () => TBlackHole, target: TOffset) => RemoveCallback;
+    /**
+     * Create a promise that resolves after a delay.
+     *
+     * @remarks
+     * Useful for awaiting a time offset in async code, or for testing. The
+     * returned promise is cancellable via its `cancel()` method.
+     */
     sleep: (target: TOffset | Date | Dayjs) => SleepReturn;
 };
+/**
+ * Scheduler factory function — binds context and returns the scheduler API.
+ *
+ * @remarks
+ * Called by the wiring engine with the request context; returns an object
+ * with all scheduling methods. This pattern allows per-request context
+ * binding without polluting the DI injection signature.
+ */
 export type SchedulerBuilder = (context: TContext) => DigitalAlchemyScheduler;
+/**
+ * ISO 8601 partial duration string type for flexible time offset specification.
+ *
+ * @remarks
+ * Examples: "1h", "30m", "45s", "1h30m45s". Used alongside `DurationUnitsObjectType`
+ * and numeric offsets to specify time values in scheduler methods.
+ *
+ * @internal
+ */
 type Part<CHAR extends string> = `${number}${CHAR}` | "";
 type ISO_8601_PARTIAL = Exclude<`${Part<"H" | "h">}${Part<"M" | "m">}${Part<"S" | "s">}`, "">;
+/**
+ * Union of supported time offset representations.
+ *
+ * @remarks
+ * Can be a dayjs Duration, milliseconds (number), an object with duration units,
+ * an ISO 8601 partial string, or a tuple of [quantity, unit]. Scheduler methods
+ * accept any of these formats and normalize them internally.
+ */
 export type OffsetTypes = Duration | number | DurationUnitsObjectType | ISO_8601_PARTIAL | [quantity: number, unit: DurationUnitType];
+/**
+ * Time offset — either a static value or a function that returns one.
+ *
+ * @remarks
+ * Allows dynamic offset computation at execution time. Useful for tests or
+ * when the delay depends on runtime state.
+ */
 export type TOffset = OffsetTypes | (() => OffsetTypes);
 export {};

package/dist/helpers/cron.mjs

@@ -1,18 +1,47 @@
+/**
+ * Scheduler types and cron expression constants.
+ *
+ * @remarks
+ * Provides a comprehensive set of cron expressions for common scheduling patterns
+ * (second, minute, hour, day, week, month, year), three scheduler options types
+ * (cron, interval, sliding), and type definitions for time offsets and the
+ * scheduler service interface.
+ */
 import dayjs from "dayjs";
 import duration from "dayjs/plugin/duration.js";
 dayjs.extend(duration);
+/**
+ * Predefined cron expressions for common scheduling patterns.
+ *
+ * @remarks
+ * Each constant is a cron expression string (6-field format: second minute hour
+ * dayOfMonth month dayOfWeek) that can be passed to `scheduler.cron(...)`.
+ * Expressions range from sub-second (EVERY_SECOND) to yearly (EVERY_YEAR),
+ * with specific business hours and weekday patterns included.
+ *
+ * @example
+ * ```typescript
+ * scheduler.cron({ exec: dailyTask, schedule: CronExpression.EVERY_DAY_AT_NOON });
+ * scheduler.cron({ exec: weeklyTask, schedule: CronExpression.EVERY_WEEKDAY });
+ * ```
+ */
 export var CronExpression;
 (function (CronExpression) {
+    // sub-minute
     CronExpression["EVERY_SECOND"] = "* * * * * *";
     CronExpression["EVERY_5_SECONDS"] = "*/5 * * * * *";
     CronExpression["EVERY_10_SECONDS"] = "*/10 * * * * *";
     CronExpression["EVERY_30_SECONDS"] = "*/30 * * * * *";
+    // minute
     CronExpression["EVERY_MINUTE"] = "*/1 * * * *";
     CronExpression["EVERY_5_MINUTES"] = "0 */5 * * * *";
     CronExpression["EVERY_10_MINUTES"] = "0 */10 * * * *";
     CronExpression["EVERY_30_MINUTES"] = "0 */30 * * * *";
+    // hour
     CronExpression["EVERY_HOUR"] = "0 0-23/1 * * *";
-    CronExpression["EVERY_2_HOURS"] = "0 0-23/2 * * *";
+    CronExpression["EVERY_2_HOURS"] = "0 */2 * * *";
+    CronExpression["EVERY_2ND_HOUR"] = "0 */2 * * *";
+    CronExpression["EVERY_2ND_HOUR_FROM_1AM_THROUGH_11PM"] = "0 1-23/2 * * *";
     CronExpression["EVERY_3_HOURS"] = "0 0-23/3 * * *";
     CronExpression["EVERY_4_HOURS"] = "0 0-23/4 * * *";
     CronExpression["EVERY_5_HOURS"] = "0 0-23/5 * * *";
@@ -23,6 +52,7 @@ export var CronExpression;
     CronExpression["EVERY_10_HOURS"] = "0 0-23/10 * * *";
     CronExpression["EVERY_11_HOURS"] = "0 0-23/11 * * *";
     CronExpression["EVERY_12_HOURS"] = "0 0-23/12 * * *";
+    // day (specific times)
     CronExpression["EVERY_DAY_AT_1AM"] = "0 01 * * *";
     CronExpression["EVERY_DAY_AT_2AM"] = "0 02 * * *";
     CronExpression["EVERY_DAY_AT_3AM"] = "0 03 * * *";
@@ -47,20 +77,21 @@ export var CronExpression;
     CronExpression["EVERY_DAY_AT_10PM"] = "0 22 * * *";
     CronExpression["EVERY_DAY_AT_11PM"] = "0 23 * * *";
     CronExpression["EVERY_DAY_AT_MIDNIGHT"] = "0 0 * * *";
+    // week
     CronExpression["EVERY_WEEK"] = "0 0 * * 0";
     CronExpression["EVERY_WEEKDAY"] = "0 0 * * 1-5";
     CronExpression["EVERY_WEEKEND"] = "0 0 * * 6,0";
+    // month
     CronExpression["EVERY_1ST_DAY_OF_MONTH_AT_MIDNIGHT"] = "0 0 1 * *";
     CronExpression["EVERY_1ST_DAY_OF_MONTH_AT_NOON"] = "0 12 1 * *";
-    CronExpression["EVERY_2ND_HOUR"] = "0 */2 * * *";
-    CronExpression["EVERY_2ND_HOUR_FROM_1AM_THROUGH_11PM"] = "0 1-23/2 * * *";
     CronExpression["EVERY_2ND_MONTH"] = "0 0 1 */2 *";
     CronExpression["EVERY_QUARTER"] = "0 0 1 */3 *";
     CronExpression["EVERY_6_MONTHS"] = "0 0 1 */6 *";
-    CronExpression["EVERY_YEAR"] = "0 0 1 1 *";
+    // business hours
     CronExpression["EVERY_30_MINUTES_BETWEEN_9AM_AND_5PM"] = "0 */30 9-17 * * *";
     CronExpression["EVERY_30_MINUTES_BETWEEN_9AM_AND_6PM"] = "0 */30 9-18 * * *";
     CronExpression["EVERY_30_MINUTES_BETWEEN_10AM_AND_7PM"] = "0 */30 10-19 * * *";
+    // weekday-specific times
     CronExpression["MONDAY_TO_FRIDAY_AT_1AM"] = "0 0 01 * * 1-5";
     CronExpression["MONDAY_TO_FRIDAY_AT_2AM"] = "0 0 02 * * 1-5";
     CronExpression["MONDAY_TO_FRIDAY_AT_3AM"] = "0 0 03 * * 1-5";
@@ -86,7 +117,19 @@ export var CronExpression;
     CronExpression["MONDAY_TO_FRIDAY_AT_9PM"] = "0 0 21 * * 1-5";
     CronExpression["MONDAY_TO_FRIDAY_AT_10PM"] = "0 0 22 * * 1-5";
     CronExpression["MONDAY_TO_FRIDAY_AT_11PM"] = "0 0 23 * * 1-5";
+    // year
+    CronExpression["EVERY_YEAR"] = "0 0 1 1 *";
 })(CronExpression || (CronExpression = {}));
+/**
+ * Schedule type identifier for cron-based schedules.
+ *
+ * @internal
+ */
 export const CRON_SCHEDULE = "CRON_SCHEDULE";
+/**
+ * Schedule type identifier for interval-based schedules.
+ *
+ * @internal
+ */
 export const INTERVAL_SCHEDULE = "INTERVAL_SCHEDULE";
 //# sourceMappingURL=cron.mjs.map

package/dist/helpers/cron.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cron.mjs","sourceRoot":"","sources":["../../src/helpers/cron.mts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,QAAQ,MAAM,0BAA0B,CAAC;AAMhD,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAEvB,MAAM,CAAN,IAAY,cAoFX;AApFD,WAAY,cAAc;IACxB,8CAA4B,CAAA;IAC5B,mDAAiC,CAAA;IACjC,qDAAmC,CAAA;IACnC,qDAAmC,CAAA;IACnC,8CAA4B,CAAA;IAC5B,mDAAiC,CAAA;IACjC,qDAAmC,CAAA;IACnC,qDAAmC,CAAA;IACnC,+CAA6B,CAAA;IAC7B,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,oDAAkC,CAAA;IAClC,oDAAkC,CAAA;IAClC,oDAAkC,CAAA;IAClC,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,qDAAmC,CAAA;IACnC,0CAAwB,CAAA;IACxB,+CAA6B,CAAA;IAC7B,+CAA6B,CAAA;IAC7B,kEAAgD,CAAA;IAChD,+DAA6C,CAAA;IAC7C,gDAA8B,CAAA;IAC9B,yEAAuD,CAAA;IACvD,iDAA+B,CAAA;IAC/B,+CAA6B,CAAA;IAC7B,gDAA8B,CAAA;IAC9B,0CAAwB,CAAA;IACxB,4EAA0D,CAAA;IAC1D,4EAA0D,CAAA;IAC1D,8EAA4D,CAAA;IAC5D,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,iEAA+C,CAAA;IAC/C,6DAA2C,CAAA;IAC3C,6DAA2C,CAAA;IAC3C,iEAA+C,CAAA;IAC/C,6DAA2C,CAAA;IAC3C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,6DAA2C,CAAA;IAC3C,6DAA2C,CAAA;AAC7C,CAAC,EApFW,cAAc,KAAd,cAAc,QAoFzB;AACD,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAC7C,MAAM,CAAC,MAAM,iBAAiB,GAAG,mBAAmB,CAAC"}
+{"version":3,"file":"cron.mjs","sourceRoot":"","sources":["../../src/helpers/cron.mts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,QAAQ,MAAM,0BAA0B,CAAC;AAMhD,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAEvB;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAN,IAAY,cA6FX;AA7FD,WAAY,cAAc;IACxB,aAAa;IACb,8CAA4B,CAAA;IAC5B,mDAAiC,CAAA;IACjC,qDAAmC,CAAA;IACnC,qDAAmC,CAAA;IACnC,SAAS;IACT,8CAA4B,CAAA;IAC5B,mDAAiC,CAAA;IACjC,qDAAmC,CAAA;IACnC,qDAAmC,CAAA;IACnC,OAAO;IACP,+CAA6B,CAAA;IAC7B,+CAA6B,CAAA;IAC7B,gDAA8B,CAAA;IAC9B,yEAAuD,CAAA;IACvD,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,oDAAkC,CAAA;IAClC,oDAAkC,CAAA;IAClC,oDAAkC,CAAA;IAClC,uBAAuB;IACvB,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,iDAA+B,CAAA;IAC/B,kDAAgC,CAAA;IAChC,kDAAgC,CAAA;IAChC,qDAAmC,CAAA;IACnC,OAAO;IACP,0CAAwB,CAAA;IACxB,+CAA6B,CAAA;IAC7B,+CAA6B,CAAA;IAC7B,QAAQ;IACR,kEAAgD,CAAA;IAChD,+DAA6C,CAAA;IAC7C,iDAA+B,CAAA;IAC/B,+CAA6B,CAAA;IAC7B,gDAA8B,CAAA;IAC9B,iBAAiB;IACjB,4EAA0D,CAAA;IAC1D,4EAA0D,CAAA;IAC1D,8EAA4D,CAAA;IAC5D,yBAAyB;IACzB,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,iEAA+C,CAAA;IAC/C,6DAA2C,CAAA;IAC3C,6DAA2C,CAAA;IAC3C,iEAA+C,CAAA;IAC/C,6DAA2C,CAAA;IAC3C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,4DAA0C,CAAA;IAC1C,6DAA2C,CAAA;IAC3C,6DAA2C,CAAA;IAC3C,OAAO;IACP,0CAAwB,CAAA;AAC1B,CAAC,EA7FW,cAAc,KAAd,cAAc,QA6FzB;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAE7C;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,mBAAmB,CAAC"}

package/dist/helpers/errors.d.mts

@@ -1,13 +1,58 @@
+/**
+ * Framework exception types for structured error handling and lifecycle management.
+ *
+ * @remarks
+ * The framework uses two canonical exception classes: `BootstrapException` for
+ * wiring-time errors (configuration, module loading, dependency resolution) and
+ * `InternalError` for runtime logic errors after bootstrap. Both carry `context`,
+ * `cause` (error code), and `timestamp` to support observability and debugging.
+ */
 import type { TContext } from "./context.mts";
+/**
+ * Exception thrown during application bootstrap or module wiring.
+ *
+ * @remarks
+ * Indicates failures during dependency graph construction, configuration parsing,
+ * or module initialization. These errors should prevent the application from
+ * starting. The `cause` field carries a `SCREAMING_SNAKE_CODE` for programmatic
+ * handling; the `message` field is the human-readable description.
+ */
 export declare class BootstrapException extends Error {
+    /** Request context under which the exception occurred. */
     context: TContext;
+    /**
+     * Machine-readable error code (e.g., `MISSING_CONFIG`, `UNKNOWN_MODULE`).
+     *
+     * @remarks
+     * Overrides the inherited `Error.cause` to ensure consistency with the
+     * framework's error classification scheme.
+     */
     cause: string;
+    /** Timestamp when the exception was created. */
     timestamp: Date;
     constructor(context: TContext, cause: string, message: string);
 }
+/**
+ * Exception thrown during runtime operation after bootstrap.
+ *
+ * @remarks
+ * Indicates logic errors, invalid state transitions, or failed assertions that
+ * occur after the application is fully initialized and running. These are
+ * typically unexpected but non-fatal; the `cause` field carries an error code
+ * for observability and alerting.
+ */
 export declare class InternalError extends Error {
+    /** Request context under which the error occurred. */
     context: TContext;
+    /**
+     * Machine-readable error code (e.g., `NOT_FOUND`, `INVALID_STATE`).
+     *
+     * @remarks
+     * Overrides the inherited `Error.cause` to ensure consistency with the
+     * framework's error classification scheme.
+     */
     cause: string;
+    /** Timestamp when the error was created. */
     timestamp: Date;
     constructor(context: TContext, cause: string, message: string);
 }

package/dist/helpers/errors.mjs

@@ -1,6 +1,33 @@
+/**
+ * Framework exception types for structured error handling and lifecycle management.
+ *
+ * @remarks
+ * The framework uses two canonical exception classes: `BootstrapException` for
+ * wiring-time errors (configuration, module loading, dependency resolution) and
+ * `InternalError` for runtime logic errors after bootstrap. Both carry `context`,
+ * `cause` (error code), and `timestamp` to support observability and debugging.
+ */
+/**
+ * Exception thrown during application bootstrap or module wiring.
+ *
+ * @remarks
+ * Indicates failures during dependency graph construction, configuration parsing,
+ * or module initialization. These errors should prevent the application from
+ * starting. The `cause` field carries a `SCREAMING_SNAKE_CODE` for programmatic
+ * handling; the `message` field is the human-readable description.
+ */
 export class BootstrapException extends Error {
+    /** Request context under which the exception occurred. */
     context;
+    /**
+     * Machine-readable error code (e.g., `MISSING_CONFIG`, `UNKNOWN_MODULE`).
+     *
+     * @remarks
+     * Overrides the inherited `Error.cause` to ensure consistency with the
+     * framework's error classification scheme.
+     */
     cause;
+    /** Timestamp when the exception was created. */
     timestamp;
     constructor(context, cause, message) {
         super();
@@ -11,9 +38,27 @@ export class BootstrapException extends Error {
         this.timestamp = new Date();
     }
 }
+/**
+ * Exception thrown during runtime operation after bootstrap.
+ *
+ * @remarks
+ * Indicates logic errors, invalid state transitions, or failed assertions that
+ * occur after the application is fully initialized and running. These are
+ * typically unexpected but non-fatal; the `cause` field carries an error code
+ * for observability and alerting.
+ */
 export class InternalError extends Error {
+    /** Request context under which the error occurred. */
     context;
+    /**
+     * Machine-readable error code (e.g., `NOT_FOUND`, `INVALID_STATE`).
+     *
+     * @remarks
+     * Overrides the inherited `Error.cause` to ensure consistency with the
+     * framework's error classification scheme.
+     */
     cause;
+    /** Timestamp when the error was created. */
     timestamp;
     constructor(context, cause, message) {
         super();

package/dist/helpers/errors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","sourceRoot":"","sources":["../../src/helpers/errors.mts"],"names":[],"mappings":"AAEA,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,OAAO,CAAW;IACT,KAAK,CAAS;IACvB,SAAS,CAAO;IAEhB,YAAY,OAAiB,EAAE,KAAa,EAAE,OAAe;QAC3D,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC,OAAO,CAAW;IACT,KAAK,CAAS;IACvB,SAAS,CAAO;IAEhB,YAAY,OAAiB,EAAE,KAAa,EAAE,OAAe;QAC3D,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;IAC9B,CAAC;CACF"}
+{"version":3,"file":"errors.mjs","sourceRoot":"","sources":["../../src/helpers/errors.mts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;GAQG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,0DAA0D;IAC1D,OAAO,CAAW;IAElB;;;;;;OAMG;IACM,KAAK,CAAS;IAEvB,gDAAgD;IAChD,SAAS,CAAO;IAEhB,YAAY,OAAiB,EAAE,KAAa,EAAE,OAAe;QAC3D,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;IAC9B,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC,sDAAsD;IACtD,OAAO,CAAW;IAElB;;;;;;OAMG;IACM,KAAK,CAAS;IAEvB,4CAA4C;IAC5C,SAAS,CAAO;IAEhB,YAAY,OAAiB,EAAE,KAAa,EAAE,OAAe;QAC3D,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;IAC9B,CAAC;CACF"}

package/dist/helpers/events.d.mts

@@ -1,3 +1,26 @@
+/**
+ * Global error event names and factory functions for event bus routing.
+ *
+ * @remarks
+ * These constants are emitted as Node.js uncaught exception events and allow
+ * applications to attach listeners that distinguish framework-level errors
+ * (global, application, or library-scoped) from other process events.
+ */
+/**
+ * Event name for uncaught errors at the Node.js process level.
+ */
 export declare const DIGITAL_ALCHEMY_NODE_GLOBAL_ERROR = "DIGITAL_ALCHEMY_NODE_GLOBAL_ERROR";
+/**
+ * Event name for errors thrown during application bootstrap or operation.
+ */
 export declare const DIGITAL_ALCHEMY_APPLICATION_ERROR = "DIGITAL_ALCHEMY_APPLICATION_ERROR";
+/**
+ * Factory for library-scoped error event names.
+ *
+ * @remarks
+ * When `library` is provided, returns a namespaced event name
+ * (`DIGITAL_ALCHEMY_LIBRARY_ERROR:${library}`) to allow listening for errors
+ * from a specific library. When not provided or empty, returns the base
+ * `DIGITAL_ALCHEMY_LIBRARY_ERROR` constant.
+ */
 export declare const DIGITAL_ALCHEMY_LIBRARY_ERROR: (library?: string) => string;

package/dist/helpers/events.mjs

@@ -1,5 +1,28 @@
+/**
+ * Global error event names and factory functions for event bus routing.
+ *
+ * @remarks
+ * These constants are emitted as Node.js uncaught exception events and allow
+ * applications to attach listeners that distinguish framework-level errors
+ * (global, application, or library-scoped) from other process events.
+ */
 import { is } from "../index.mjs";
+/**
+ * Event name for uncaught errors at the Node.js process level.
+ */
 export const DIGITAL_ALCHEMY_NODE_GLOBAL_ERROR = "DIGITAL_ALCHEMY_NODE_GLOBAL_ERROR";
+/**
+ * Event name for errors thrown during application bootstrap or operation.
+ */
 export const DIGITAL_ALCHEMY_APPLICATION_ERROR = "DIGITAL_ALCHEMY_APPLICATION_ERROR";
+/**
+ * Factory for library-scoped error event names.
+ *
+ * @remarks
+ * When `library` is provided, returns a namespaced event name
+ * (`DIGITAL_ALCHEMY_LIBRARY_ERROR:${library}`) to allow listening for errors
+ * from a specific library. When not provided or empty, returns the base
+ * `DIGITAL_ALCHEMY_LIBRARY_ERROR` constant.
+ */
 export const DIGITAL_ALCHEMY_LIBRARY_ERROR = (library) => is.empty(library) ? "DIGITAL_ALCHEMY_LIBRARY_ERROR" : `DIGITAL_ALCHEMY_LIBRARY_ERROR:${library}`;
 //# sourceMappingURL=events.mjs.map