@digital-alchemy/core 26.1.9 → 26.5.1

package/CLAUDE.md

@@ -0,0 +1,302 @@
+# CLAUDE.md — @digital-alchemy/core
+
+## 1. What core is
+
+`@digital-alchemy/core` is a zero-magic dependency-injection framework for TypeScript. There is no reflection, no decorators, no class hierarchy. Every service is a plain function that receives its dependencies through a single destructured parameter — `TServiceParams`.
+
+```typescript
+export function MyService({ logger, lifecycle, config }: TServiceParams) {
+  lifecycle.onReady(() => {
+    logger.info("ready");
+  });
+  return { doThing };
+}
+```
+
+The framework wires up all declared services at bootstrap time, building a dependency graph from the `libraries` and `services` fields of each `CreateApplication` / `CreateLibrary` call. Once wired, every service receives its full `TServiceParams` synchronously (with async factories awaited).
+
+This repo is the foundation every other `@digital-alchemy` library depends on. Changes to exports, lifecycle semantics, or `TServiceParams` shape ripple downstream into every consumer. Treat public API surface changes as breaking.
+
+---
+
+## 2. Repo orientation
+
+### `src/services/*.mts` — stateful service factories
+
+| File | Owns / responsibility | Read by |
+|---|---|---|
+| `als.service.mts` | `AsyncLocalStorage` wrapper; `enterWith`, `run`, `getStore`, `getLogData` | Logger (ALS log merging), any code needing per-request context |
+| `configuration.service.mts` | Config state map, loader orchestration, proxy for `config.*`, `setConfig`, `mergeConfig`, `validateConfig`, `onUpdate` | `wiring.service.mts` at bootstrap; every service via `config` injection |
+| `internal.service.mts` | `InternalDefinition` class (boot state, module maps, lifecycle ref); `InternalUtils` (object path get/set/del, `is`, `relativeDate`, `titleCase`); `safeExec` | All services — injected as `internal` |
+| `is.service.mts` | `IsIt` class — type guards and small utilities (`array`, `boolean`, `empty`, `equal`, `function`, `object`, `string`, etc.); exports singleton `is` | Imported directly by `lifecycle.service.mts` and `wiring.service.mts` to break circular deps; everywhere else reached as `internal.utils.is` |
+| `lifecycle.service.mts` | `CreateLifecycle` — per-bootstrap lifecycle event registry; priority-sorted callback execution across all seven stages | `wiring.service.mts` owns the lifecycle instance; services attach via `lifecycle.*` injection |
+| `logger.service.mts` | `Logger` factory — chalk/stdout formatter, `context(ctx)` builder, level filtering, `addTarget`, `updateShouldLog`, ALS integration, `systemLogger` | Every service via `logger` injection; `internal.boilerplate.logger` |
+| `scheduler.service.mts` | `Scheduler` factory — cron, interval, sliding, `setTimeout`, `setInterval`, `sleep`; registers stop callbacks for clean shutdown; returns a builder called with `(context: TContext)` | Every service via `scheduler` injection |
+| `wiring.service.mts` | Bootstrap orchestration — `CreateApplication`, `wireService`, `CreateBoilerplate`, `teardown`, SIGINT/SIGTERM handling; owns `LIB_BOILERPLATE` | Entry point for all apps; do not call `wireService` directly |
+| `index.mts` | Re-exports all service exports | Everything in `src/` imports from `../index.mts` |
+
+### `src/helpers/*.mts` — pure logic, types, and utilities
+
+**What distinguishes helpers from services:** helpers are side-effect-free modules containing types, utility functions, constants, and small classes. They do not receive `TServiceParams`. Services are factories that receive DI params and return an API object.
+
+| File | Owns |
+|---|---|
+| `async.mts` | `each`, `eachSeries`, `eachLimit` — async iteration helpers that replace inconsistent `async` library behavior |
+| `config-environment-loader.mts` | `ConfigLoaderEnvironment` — reads env vars and CLI switches; search order is `MODULE__KEY` (double-underscore) → `MODULE_KEY` (single-underscore) → `KEY` |
+| `config-file-loader.mts` | `configLoaderFile`, `configFilePaths`, `loadConfigFromFile`, `withExtensions` — file-based config loading (JSON, YAML, INI, auto-detect) |
+| `config.mts` | All config types (`AnyConfig`, `StringConfig`, `BooleanConfig`, etc.), `ConfigLoaderParams`, `ConfigLoaderReturn`, `findKey`, `iSearchKey`, `loadDotenv`, `parseConfig`, `KnownConfigs` |
+| `context.mts` | `TContext` branded string type; `IContextBrand` |
+| `cron.mts` | `CronExpression` enum, `TOffset`, `SchedulerCronOptions`, `SchedulerIntervalOptions`, `SchedulerSlidingOptions`, `DigitalAlchemyScheduler`, `SchedulerBuilder` |
+| `errors.mts` | `BootstrapException` (wiring-time errors), `InternalError` (runtime errors) — both carry `context`, `cause`, `timestamp` |
+| `events.mts` | Global error event name constants (`DIGITAL_ALCHEMY_NODE_GLOBAL_ERROR`, etc.) |
+| `extend.mts` | `deepExtend`, `deepCloneArray`, `cloneSpecificValue` — deep merge utilities |
+| `index.mts` | Re-exports all helper exports; new public helpers thread through here |
+| `lifecycle.mts` | `TLifecycleBase`, `TLifeCycleRegister`, `LIFECYCLE_STAGES` array, `LifecycleStages` type, `LifecycleCallback` |
+| `logger.mts` | `ILogger`, `TLoggerFunction`, `DigitalAlchemyLogger`, `GetLogger`, `METHOD_COLORS`, `fatalLog`, `EVENT_UPDATE_LOG_LEVELS` |
+| `module.mts` | `createModule`, `DigitalAlchemyModule`, `ModuleExtension` — chainable module builder that can export to application, library, or test runner |
+| `service-runner.mts` | `ServiceRunner` — minimal one-service bootstrap helper for scripts |
+| `utilities.mts` | Numeric constants (`START`, `NONE`, `EMPTY`, `FIRST`, `ARRAY_OFFSET`, `SINGLE`, `UP`, `DOWN`, `MINUTE`, `HOUR`, `DAY`, `SECOND`, `YEAR`, etc.); `sleep`, `debounce`, `toOffsetMs`, `toOffsetDuration`, `SleepReturn`, `TBlackHole` |
+| `wiring.mts` | `TServiceParams`, `ServiceFunction`, `ServiceMap`, `ApplicationDefinition`, `LibraryDefinition`, `BootstrapOptions`, `TInjectedConfig`, `LoadedModules`, `buildSortOrder`, `CreateLibrary`, `wireOrder`, `COERCE_CONTEXT`, `WIRE_PROJECT` |
+
+### `src/testing/*.mts` — test infrastructure (not test cases)
+
+| File | Owns |
+|---|---|
+| `mock-logger.mts` | `createMockLogger()` — returns a no-op `ILogger`; import in specs to suppress output |
+| `test-module.mts` | `TestRunner` factory + `iTestRunner` interface — boots a real DI graph scoped to a test; chainable API: `.configure`, `.setOptions`, `.run`, `.serviceParams`, `.setup`, `.appendLibrary`, `.appendService`, `.replaceLibrary`, `.teardown` |
+| `index.mts` | Re-exports `mock-logger` and `test-module` |
+
+### `testing/` (sibling of `src/`, not inside it)
+
+All `.spec.mts` files live here. Each spec file maps to a service or helper:
+`als.spec.mts`, `configuration.spec.mts`, `internal.spec.mts`, `is.spec.mts`, `logger.spec.mts`, `scheduler.spec.mts`, `testing.spec.mts`, `utilities.spec.mts`, `wiring.spec.mts`. A `setup.mts` file and `pipelines/` subdirectory handle vitest global setup.
+
+---
+
+## 3. The TServiceParams pattern in core specifically
+
+### Reaching `is`
+
+**Inside core services and helpers**, use `internal.utils.is` — do not `import { is }` from the index:
+
+```typescript
+// correct inside a service factory
+export function MyService({ internal }: TServiceParams) {
+  const { is } = internal.utils;
+  if (is.empty(value)) { ... }
+}
+```
+
+**The one exception:** `is.service.mts` is imported directly in `lifecycle.service.mts` and `wiring.service.mts` to break a circular dependency that would form if they went through `../index.mts`. This is intentional — leave it.
+
+### Dual-arity logger with `{ name: fnRef }` tagging
+
+Every function entry logs with its own function reference as the `name` field. This appears in the rendered output as the function name, enabling precise call-site identification without string literals.
+
+```typescript
+function loadThing(id: string) {
+  logger.trace({ name: loadThing, id }, "loading");
+  // ...
+  logger.debug({ name: loadThing }, "loaded");
+}
+```
+
+Pass the function reference directly (not `loadThing.name`). The logger extracts `.name` from the object or function automatically.
+
+### Lifecycle hook order
+
+Hooks are attached in service constructors but executed by the wiring engine in strict order:
+
+```
+onPreInit → onPostConfig → onBootstrap → onReady
+→ onPreShutdown → onShutdownStart → onShutdownComplete
+```
+
+- `onPreInit`: safe for attaching state; config is not yet loaded — do not read `config.*`
+- `onPostConfig`: config values are available from this point forward
+- `onBootstrap`: all modules are wired; safe to call other services
+- `onReady`: app is fully running; schedulers start here
+- `onPreShutdown` / `onShutdownStart` / `onShutdownComplete`: teardown in order
+
+Each hook accepts an optional `priority` number. Positive priorities run first (high → low), un-prioritized callbacks run in parallel, negative priorities run last.
+
+### No `metrics` injection
+
+`TServiceParams` in this repo does not include `metrics`. Do not write `metrics.perf()`, `metrics.histogram(...)`, or any metrics-instrumentation patterns. Those patterns exist in sibling repos (e.g., vault-ts) that build on top of core. Core itself has no metrics service.
+
+### `context: TContext` for builder-style services
+
+`scheduler` is a builder: it returns a function that accepts `context: TContext` and returns the actual scheduler API. This is the pattern for any service that needs to bind per-caller context at use time:
+
+```typescript
+// wiring.service.mts — how scheduler is injected
+scheduler: boilerplate?.scheduler?.(context),
+```
+
+Services that need to pass context down into callbacks capture the context injected into their own factory:
+
+```typescript
+export function MyService({ context, scheduler }: TServiceParams) {
+  scheduler.cron({ exec: doWork, schedule: CronExpression.EVERY_MINUTE });
+}
+```
+
+---
+
+## 4. Style rules
+
+### TSDoc
+
+- Every exported factory function gets a TSDoc comment with at minimum a one-line summary.
+- Every method on the returned object gets a one-line summary.
+- Use `@remarks` for non-obvious behavior (e.g., "only valid after `onPostConfig`").
+- Use `@throws` when the function throws a documented exception.
+- `@internal` on symbols not intended for downstream consumers.
+
+### Inline comments
+
+Write `// why`, never `// what`. The code describes what. The comment explains the reason:
+
+```typescript
+// only read config after PostConfig fires; value is undefined before that
+lifecycle.onPostConfig(() => {
+  CURRENT_LOG_LEVEL = config.boilerplate.LOG_LEVEL;
+});
+```
+
+### Logging conventions
+
+```typescript
+// entry — always trace with name + relevant inputs
+logger.trace({ name: fnRef, ...inputs }, "brief description");
+
+// decision points — trace
+logger.trace({ name: fnRef, chosen }, "selected path");
+
+// successful completion — debug
+logger.debug({ name: fnRef }, "operation complete");
+
+// expected-but-notable — info
+// unexpected non-fatal — warn
+// errors — error or fatal
+```
+
+### Error types
+
+- `BootstrapException(context, "SCREAMING_SNAKE_CODE", "human message")` — for wiring failures, misconfiguration, or anything that should prevent boot.
+- `InternalError(context, "CODE", "message")` — for runtime logic errors after boot.
+- No bare `new Error(...)` in service or helper code.
+
+### Hard prohibitions
+
+- No `console.*` — use `logger.*` or `fatalLog` for last-resort stderr writes.
+- No `process.stdout` writes.
+- No `process.env.*` access outside of `config-environment-loader.mts` and `wiring.service.mts` (where `IS_TEST` / `NODE_ENV` defaults are set).
+- No module-level side effects beyond constant declarations and `dayjs.extend(...)`.
+- No `.catch()` — use `internal.safeExec` for wrapped async execution, or handle errors explicitly.
+- No classic `for` / `for...of` loops — use `each`, `eachSeries`, `eachLimit`, `.forEach`, `.map`, `.filter`, `.some`, `.find`.
+- No `ts-ignore` on new code; `ts-expect-error` is acceptable only with a comment explaining why.
+
+### Cast restrictions
+
+Follow the existing eslint config. In particular: `@typescript-eslint/no-magic-numbers` is enforced — declare named constants for non-obvious numeric literals.
+
+---
+
+## 5. Validation
+
+All commands run from the repo root (`/home/zoe/Repos/DigitalAlchemyTS/core`).
+
+### `yarn lint`
+
+Runs eslint over `src/` and `testing/`. Must pass with zero errors and zero warnings. A clean run exits 0 with no output.
+
+```bash
+yarn lint
+```
+
+### `yarn test`
+
+Runs vitest. All specs in `testing/` must pass. A clean run shows all tests green with no skipped specs (unless the test is explicitly marked `.skip` for a documented reason).
+
+```bash
+yarn test
+```
+
+### Type check the publish surface
+
+```bash
+tsc -p tsconfig.lib.json --noEmit
+```
+
+This checks only the files that end up in `dist/`. Errors here are publish-blocking.
+
+### `yarn build`
+
+Produces `dist/` cleanly. Use to verify the publish output compiles.
+
+```bash
+yarn build
+```
+
+### Do not touch
+
+- `coverage/` — generated artifact, gitignored
+- `node_modules/` — managed by yarn
+- `yarn.lock` — only update deliberately with `yarn add` / `yarn remove`
+- `dist/` — gitignored; never commit it
+
+---
+
+## 6. Footguns specific to core
+
+### `wiring.mts` and `wiring.service.mts` — the engine was deliberately split
+
+`helpers/wiring.mts` contains all the types and pure functions (`CreateLibrary`, `buildSortOrder`, `TServiceParams`, etc.). `services/wiring.service.mts` contains the runtime bootstrap logic (`CreateApplication`, `bootstrap`, `wireService`, `teardown`).
+
+This split exists to break a circular reference that would form if types and the bootstrap runtime lived in the same file. **Do not merge them.** Read both before touching either. Changes to `TServiceParams` shape in `helpers/wiring.mts` affect every downstream library.
+
+### `index.mts` is the re-export hub
+
+`src/index.mts` re-exports everything. New public symbols thread through either `src/helpers/index.mts` or `src/services/index.mts` (whichever is appropriate), not directly into `src/index.mts`.
+
+### Services import from `../index.mts`, not from siblings
+
+Services import from `../index.mts` rather than directly from sibling files:
+
+```typescript
+// correct
+import { deepExtend, eachSeries } from "../index.mts";
+
+// wrong — breaks the circular-ref mitigation
+import { deepExtend } from "./extend.mts";
+```
+
+The only exceptions are the deliberate direct imports in `lifecycle.service.mts` and `wiring.service.mts` of `is.service.mts`.
+
+### `lifecycle.service.mts` imports `is` directly
+
+`lifecycle.service.mts` and `wiring.service.mts` both `import { is } from "./is.service.mts"` instead of going through `../index.mts`. This breaks the circular dep that would form at module init time. Leave this pattern intact.
+
+### `TestRunner` boots a real DI graph
+
+`TestRunner` in `src/testing/test-module.mts` bootstraps a full application with real lifecycle execution. It is not a mock framework. This means:
+
+- Lifecycle hooks fire in real order.
+- Assertions inside `lifecycle.onPostConfig(...)` only see post-config values.
+- Services passed to `.appendLibrary` / `.appendService` execute normally.
+- Always call `.teardown()` in `afterEach` — open handles will keep vitest hanging.
+
+Mocking depth matters: spying on a method only replaces that method, not the service it belongs to. When in doubt, use `.replaceLibrary` or inject a stub via `.appendService`.
+
+### `configSources` controls loader activation
+
+By default, `TestRunner` does not load env vars or config files (this is the safe default for tests). To test env-var resolution, pass `loadConfigs: true` or `setOptions({ configSources: { env: true } })`. To assert that env loading is disabled, pass `configSources: { env: false }`.
+
+---
+
+## 7. Where to find more
+
+Long-form learning material — architecture overviews, declaration merging docs, advanced recipes — exists in a sibling documentation repository. Refer to that repo abstractly; its path and URL are out of scope here.
+
+This `CLAUDE.md` is the canonical working reference for the `core` repo itself. When this file and external docs disagree about what to do *in this repo*, this file wins.

package/README.md

@@ -17,11 +17,27 @@ yarn add @digital-alchemy/core
 
 ## Introduction
 
-The Digital Alchemy core utilities are a set of dependency-light tools for building backend applications with **TypeScript**. It targets the latest **ESModule** syntax and language standards, and it's compatible with Bun, Deno, and modern versions of NodeJS.
+`@digital-alchemy/core` is a dependency-injection framework for TypeScript — no decorators, no reflection, no class hierarchy. Services are plain functions that receive their dependencies through a single typed parameter. The framework wires everything at boot time, with full type safety across your entire service graph.
 
-Modules leverage advanced TypeScript features to easily combine services and configurations into type-safe applications. This makes it friendly to a variety of use cases, from complex functional programming logic to usage as a smaller utility in an existing codebase.
+Targets the latest ESModule syntax and runs on Bun, Deno, and modern Node.
+
+## At a glance
+
+```typescript
+import { CreateApplication, TServiceParams } from "@digital-alchemy/core";
+
+function HelloService({ logger, lifecycle }: TServiceParams) {
+  lifecycle.onReady(() => logger.info("hello world"));
+}
+
+const app = CreateApplication({
+  name: "hello",
+  services: { hello: HelloService },
+});
+
+await app.bootstrap();
+```
 
-The framework adds minimal overhead to boot times, making it well-suited for a wide range of applications, such as web servers, serverless functions, automation tools, and long-running background scripts.
 ## What it does
 
 - **Service wiring** - Automatic dependency injection with full type safety

package/dist/helpers/async.d.mts

@@ -1,3 +1,40 @@
+/**
+ * Async iteration helpers — drop-in replacements for the `async` library with
+ * more predictable behavior.
+ *
+ * @remarks
+ * Provides `each`, `eachSeries`, and `eachLimit` functions that mirror common
+ * async iteration patterns but with consistent semantics. All functions accept
+ * either an array or a Set as input and execute a callback on each item,
+ * returning a promise that resolves when all iterations complete.
+ */
+/**
+ * Execute an async callback in parallel on each item in a collection.
+ *
+ * @remarks
+ * Invokes all callbacks concurrently using `Promise.all`. Accepts either an
+ * array or a Set; Sets are converted to arrays before processing. If `callback`
+ * throws or rejects, the entire operation fails with that error.
+ */
 export declare function each<T = unknown>(item: T[] | Set<T>, callback: (item: T) => Promise<void | unknown>): Promise<void>;
+/**
+ * Execute an async callback serially on each item in a collection.
+ *
+ * @remarks
+ * Invokes callbacks one after the other, waiting for each to complete before
+ * starting the next. Accepts either an array or a Set; Sets are converted to
+ * arrays. Throws if the input is not a Set or array after conversion.
+ *
+ * @throws {TypeError} when the input is neither an array nor a Set.
+ */
 export declare function eachSeries<T = void>(item: T[] | Set<T>, callback: (item: T) => Promise<void | unknown>): Promise<void>;
+/**
+ * Execute an async callback on each item in an array while limiting concurrency.
+ *
+ * @remarks
+ * Respects a maximum number of concurrent callbacks by tracking active promises
+ * and awaiting one to resolve before starting a new one. Processes the first
+ * `limit` items immediately, then maintains the limit as remaining items are
+ * queued. Resolves only when all callbacks complete.
+ */
 export declare function eachLimit<T = unknown>(items: T[], limit: number, callback: (item: T) => Promise<void | unknown>): Promise<void>;

package/dist/helpers/async.mjs

@@ -1,21 +1,46 @@
+/**
+ * Async iteration helpers — drop-in replacements for the `async` library with
+ * more predictable behavior.
+ *
+ * @remarks
+ * Provides `each`, `eachSeries`, and `eachLimit` functions that mirror common
+ * async iteration patterns but with consistent semantics. All functions accept
+ * either an array or a Set as input and execute a callback on each item,
+ * returning a promise that resolves when all iterations complete.
+ */
 import { is } from "../index.mjs";
 import { ARRAY_OFFSET, SINGLE, START } from "./utilities.mjs";
-// ? Functions written to be similar to the offerings from the async library
-// That library gave me oddly inconsistent results,
-//     so these exist to replace those doing exactly what I expect
-//
-// #MARK: each
+/**
+ * Execute an async callback in parallel on each item in a collection.
+ *
+ * @remarks
+ * Invokes all callbacks concurrently using `Promise.all`. Accepts either an
+ * array or a Set; Sets are converted to arrays before processing. If `callback`
+ * throws or rejects, the entire operation fails with that error.
+ */
 export async function each(item, callback) {
+    // convert Set to array for uniform handling
     if (item instanceof Set) {
         item = [...item.values()];
     }
     await Promise.all(item.map(async (i) => await callback(i)));
 }
-// #MARK: eachSeries
+/**
+ * Execute an async callback serially on each item in a collection.
+ *
+ * @remarks
+ * Invokes callbacks one after the other, waiting for each to complete before
+ * starting the next. Accepts either an array or a Set; Sets are converted to
+ * arrays. Throws if the input is not a Set or array after conversion.
+ *
+ * @throws {TypeError} when the input is neither an array nor a Set.
+ */
 export async function eachSeries(item, callback) {
+    // convert Set to array for uniform handling
     if (item instanceof Set) {
         item = [...item.values()];
     }
+    // ensure we have an array; failing fast helps catch misuse early
     if (!is.array(item)) {
         throw new TypeError(`not provided an array`);
     }
@@ -23,29 +48,39 @@ export async function eachSeries(item, callback) {
         await callback(item[i]);
     }
 }
-// #MARK: eachLimit
+/**
+ * Execute an async callback on each item in an array while limiting concurrency.
+ *
+ * @remarks
+ * Respects a maximum number of concurrent callbacks by tracking active promises
+ * and awaiting one to resolve before starting a new one. Processes the first
+ * `limit` items immediately, then maintains the limit as remaining items are
+ * queued. Resolves only when all callbacks complete.
+ */
 export async function eachLimit(items, limit, callback) {
-    // Track active promises to ensure we don't exceed the limit
+    // track promises to enforce the concurrency limit
     const activePromises = new Set();
-    // A helper function to add a new task
+    // queue a new callback and manage the promise lifecycle
     async function addTask(item) {
         const promise = callback(item).then(() => {
-            activePromises.delete(promise); // Remove the promise from the set once it's resolved
+            // clean up completed promise so we can detect when to start new ones
+            activePromises.delete(promise);
         });
         activePromises.add(promise);
+        // if at or over limit, block until at least one promise resolves
         if (activePromises.size >= limit) {
-            await Promise.race(activePromises); // Wait for one of the active promises to resolve
+            await Promise.race(activePromises);
         }
     }
-    // Add initial tasks up to the limit
+    // seed the concurrency pool with the first `limit` items
     const initialTasks = items.slice(SINGLE, limit).map(item => addTask(item));
-    // Wait for the initial set of tasks to start processing
+    // wait for all initial tasks to be queued (not necessarily complete)
     await Promise.all(initialTasks);
-    // Process the remaining items, ensuring the limit is respected
+    // process remaining items while respecting the limit
     for (let i = limit - ARRAY_OFFSET; i < items.length; i++) {
         await addTask(items[i]);
     }
-    // Wait for all remaining tasks to complete
+    // wait for all in-flight operations to finish
     await Promise.all(activePromises);
 }
 //# sourceMappingURL=async.mjs.map

package/dist/helpers/async.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"async.mjs","sourceRoot":"","sources":["../../src/helpers/async.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAE9D,4EAA4E;AAC5E,mDAAmD;AACnD,kEAAkE;AAClE,EAAE;AAEF,cAAc;AACd,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,IAAkB,EAClB,QAA8C;IAE9C,IAAI,IAAI,YAAY,GAAG,EAAE,CAAC;QACxB,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5B,CAAC;IACD,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAC,CAAC,EAAC,EAAE,CAAC,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED,oBAAoB;AACpB,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,IAAkB,EAClB,QAA8C;IAE9C,IAAI,IAAI,YAAY,GAAG,EAAE,CAAC;QACxB,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5B,CAAC;IACD,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,SAAS,CAAC,uBAAuB,CAAC,CAAC;IAC/C,CAAC;IACD,KAAK,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC,EAAE,EAAE,CAAC;QACzD,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC;AAED,mBAAmB;AACnB,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,KAAU,EACV,KAAa,EACb,QAA8C;IAE9C,4DAA4D;IAC5D,MAAM,cAAc,GAAiC,IAAI,GAAG,EAAE,CAAC;IAE/D,sCAAsC;IACtC,KAAK,UAAU,OAAO,CAAC,IAAO;QAC5B,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;YACvC,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,qDAAqD;QACvF,CAAC,CAAC,CAAC;QACH,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC5B,IAAI,cAAc,CAAC,IAAI,IAAI,KAAK,EAAE,CAAC;YACjC,MAAM,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,iDAAiD;QACvF,CAAC;IACH,CAAC;IAED,oCAAoC;IACpC,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAE3E,wDAAwD;IACxD,MAAM,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAEhC,+DAA+D;IAC/D,KAAK,IAAI,CAAC,GAAG,KAAK,GAAG,YAAY,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzD,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IAED,2CAA2C;IAC3C,MAAM,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AACpC,CAAC"}
+{"version":3,"file":"async.mjs","sourceRoot":"","sources":["../../src/helpers/async.mts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,IAAkB,EAClB,QAA8C;IAE9C,4CAA4C;IAC5C,IAAI,IAAI,YAAY,GAAG,EAAE,CAAC;QACxB,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5B,CAAC;IACD,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAC,CAAC,EAAC,EAAE,CAAC,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,IAAkB,EAClB,QAA8C;IAE9C,4CAA4C;IAC5C,IAAI,IAAI,YAAY,GAAG,EAAE,CAAC;QACxB,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5B,CAAC;IACD,iEAAiE;IACjE,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,SAAS,CAAC,uBAAuB,CAAC,CAAC;IAC/C,CAAC;IACD,KAAK,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC,EAAE,EAAE,CAAC;QACzD,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,KAAU,EACV,KAAa,EACb,QAA8C;IAE9C,kDAAkD;IAClD,MAAM,cAAc,GAAiC,IAAI,GAAG,EAAE,CAAC;IAE/D,wDAAwD;IACxD,KAAK,UAAU,OAAO,CAAC,IAAO;QAC5B,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;YACvC,qEAAqE;YACrE,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC,CAAC,CAAC;QACH,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC5B,iEAAiE;QACjE,IAAI,cAAc,CAAC,IAAI,IAAI,KAAK,EAAE,CAAC;YACjC,MAAM,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IAED,yDAAyD;IACzD,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAE3E,qEAAqE;IACrE,MAAM,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAEhC,qDAAqD;IACrD,KAAK,IAAI,CAAC,GAAG,KAAK,GAAG,YAAY,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzD,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IAED,8CAA8C;IAC9C,MAAM,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AACpC,CAAC"}

package/dist/helpers/config-environment-loader.d.mts

@@ -1,5 +1,44 @@
+/**
+ * Environment variable and CLI switch config loader.
+ *
+ * @remarks
+ * Reads config from Node.js env vars and command-line arguments. For each config
+ * key, searches using a three-tier precedence: CLI switches (highest), then env
+ * vars (middle), then defaults (lowest). Both argv and env sources support a
+ * double-underscore variant (`MODULE__KEY`) in addition to single-underscore,
+ * enabling env vars with embedded dots/slashes that would be shell-escaped.
+ * Timing information is captured and returned for observability.
+ */
 import type { ConfigLoaderParams, ConfigLoaderReturn, ModuleConfiguration } from "./config.mts";
 import type { ServiceMap } from "./wiring.mts";
+/**
+ * Load configuration from environment variables and CLI switches.
+ *
+ * @remarks
+ * Merges CLI arguments and environment variables into the config tree, respecting
+ * the configured sources (argv, env) and individual config key source restrictions.
+ * Searches for each key in three forms (in order):
+ * 1. `MODULE__KEY` (double underscore) — preferred, allows shell-escaped env vars
+ * 2. `MODULE_KEY` (single underscore) — classic format
+ * 3. `KEY` (bare key) — fallback for globals
+ *
+ * CLI arguments are checked first (highest precedence); env vars are checked second.
+ * Both are optional and controlled by `internal.boot.options.configSources`.
+ *
+ * Timing data is collected for argv and env separately and returned if the
+ * optional `timings` object is provided.
+ *
+ * @example
+ * ```
+ * // Search order for app.NODE_ENV config key:
+ * // 1. --app__NODE_ENV cli switch
+ * // 2. APP__NODE_ENV env var
+ * // 3. --app_NODE_ENV cli switch
+ * // 4. APP_NODE_ENV env var
+ * // 5. --NODE_ENV cli switch
+ * // 6. NODE_ENV env var
+ * ```
+ */
 export declare function ConfigLoaderEnvironment<S extends ServiceMap = ServiceMap, C extends ModuleConfiguration = ModuleConfiguration>({ configs, internal, logger, timings, }: ConfigLoaderParams<S, C> & {
     timings?: Record<string, string>;
 }): ConfigLoaderReturn;

package/dist/helpers/config-environment-loader.mjs

@@ -1,7 +1,46 @@
+/**
+ * Environment variable and CLI switch config loader.
+ *
+ * @remarks
+ * Reads config from Node.js env vars and command-line arguments. For each config
+ * key, searches using a three-tier precedence: CLI switches (highest), then env
+ * vars (middle), then defaults (lowest). Both argv and env sources support a
+ * double-underscore variant (`MODULE__KEY`) in addition to single-underscore,
+ * enabling env vars with embedded dots/slashes that would be shell-escaped.
+ * Timing information is captured and returned for observability.
+ */
 import { env } from "node:process";
 import minimist from "minimist";
 import { is, NONE } from "../index.mjs";
 import { findKey, iSearchKey, loadDotenv, parseConfig } from "./config.mjs";
+/**
+ * Load configuration from environment variables and CLI switches.
+ *
+ * @remarks
+ * Merges CLI arguments and environment variables into the config tree, respecting
+ * the configured sources (argv, env) and individual config key source restrictions.
+ * Searches for each key in three forms (in order):
+ * 1. `MODULE__KEY` (double underscore) — preferred, allows shell-escaped env vars
+ * 2. `MODULE_KEY` (single underscore) — classic format
+ * 3. `KEY` (bare key) — fallback for globals
+ *
+ * CLI arguments are checked first (highest precedence); env vars are checked second.
+ * Both are optional and controlled by `internal.boot.options.configSources`.
+ *
+ * Timing data is collected for argv and env separately and returned if the
+ * optional `timings` object is provided.
+ *
+ * @example
+ * ```
+ * // Search order for app.NODE_ENV config key:
+ * // 1. --app__NODE_ENV cli switch
+ * // 2. APP__NODE_ENV env var
+ * // 3. --app_NODE_ENV cli switch
+ * // 4. APP_NODE_ENV env var
+ * // 5. --NODE_ENV cli switch
+ * // 6. NODE_ENV env var
+ * ```
+ */
 export async function ConfigLoaderEnvironment({ configs, internal, logger, timings, }) {
     const DECIMALS = 2;
     const CLI_SWITCHES = minimist(process.argv);
@@ -11,27 +50,26 @@ export async function ConfigLoaderEnvironment({ configs, internal, logger, timin
     const canArgv = internal.boot.options?.configSources?.argv ?? true;
     const shouldArgv = (source) => canArgv && (!is.array(source) || source.includes("argv"));
     const shouldEnv = (source) => canEnvironment && (!is.array(source) || source.includes("env"));
-    // * merge dotenv into local vars
-    // accounts for `--env-file` switches, and whatever is passed in via bootstrap
+    // merge dotenv files and env-file switches into process.env
     loadDotenv(internal, CLI_SWITCHES, logger);
     const environmentKeys = Object.keys(env);
-    // Track timing for argv and env separately
+    // track timing for argv and env separately
     let argvTime = NONE;
     let envTime = NONE;
-    // * go through all module
+    // iterate through all module configurations
     configs.forEach((configuration, project) => {
         const cleanedProject = project.replaceAll("-", "_");
-        // * run through each config for module
+        // iterate through each config key within the module
         Object.keys(configuration).forEach(key => {
             const { source } = configs.get(project)[key];
-            // > things to search for
-            // - MODULE_NAME_CONFIG_KEY (module + key, ex: app_NODE_ENV)
-            // - CONFIG_KEY (only key, ex: NODE_ENV)
+            // search keys in order: double-underscore (preferred), single-underscore, bare key
+            // double-underscore allows env var names with embedded special chars (dots, slashes)
             const noAppPath = `${cleanedProject}_${key}`;
-            const search = [noAppPath, key];
+            const noAppPathDouble = `${cleanedProject}__${key}`;
+            const search = [noAppPathDouble, noAppPath, key];
             const configPath = `${project}.${key}`;
             if (canArgv) {
-                // * (preferred) Find an applicable cli switch
+                // CLI switches take precedence; find a matching flag in the argv
                 const argvStart = performance.now();
                 const flag = findKey(search, switchKeys);
                 if (flag && shouldArgv(source)) {
@@ -47,12 +85,13 @@ export async function ConfigLoaderEnvironment({ configs, internal, logger, timin
                 }
                 argvTime += performance.now() - argvStart;
             }
-            // * (fallback) Find an environment variable
+            // fallback to environment variable if no CLI switch was found
             if (canEnvironment) {
                 const envStart = performance.now();
                 const environment = findKey(search, environmentKeys);
                 if (!is.empty(environment) && shouldEnv(source)) {
                     const environmentName = iSearchKey(environment, environmentKeys);
+                    // only set if the env var is defined and non-empty
                     if (!is.string(env[environmentName]) || !is.empty(env[environmentName])) {
                         internal.utils.object.set(out, configPath, parseConfig(configuration[key], env[environmentName]));
                     }
@@ -69,6 +108,7 @@ export async function ConfigLoaderEnvironment({ configs, internal, logger, timin
             }
         });
     });
+    // record timing if provided
     if (timings) {
         if (argvTime) {
             timings.argv = `${argvTime.toFixed(DECIMALS)}ms`;