@digital-alchemy/core 26.1.9 → 26.5.1

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

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

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

@@ -1,7 +1,72 @@
+/**
+ * File-based configuration loader — reads JSON, YAML, and INI config files.
+ *
+ * @remarks
+ * Supports four formats (JSON, YAML, INI, and auto-detect) and searches standard
+ * config paths: `/etc/{app}`, `./{app}` (walking up the directory tree),
+ * `~/.config/{app}`, and explicit `--config` flag overrides. Files are detected
+ * by extension and parsed accordingly; if extension is ambiguous, format detection
+ * occurs in order: JSON-like start, YAML parse, INI fallback. Multiple files are
+ * merged using `deepExtend`, with earlier files providing defaults.
+ */
 import type { ConfigLoaderParams, ConfigLoaderReturn, ModuleConfiguration } from "./config.mts";
 import type { PartialConfiguration, ServiceMap } from "./wiring.mts";
+/**
+ * Supported config file extensions.
+ */
 export declare const SUPPORTED_CONFIG_EXTENSIONS: string[];
+/**
+ * Generate potential file paths for a given base path.
+ *
+ * @remarks
+ * Returns an array of paths including the base, a "config" subdirectory variant,
+ * and all supported extensions of each. This is used to generate candidates
+ * without checking filesystem; callers filter to existing files.
+ *
+ * @example
+ * ```
+ * withExtensions("myapp") returns:
+ * ["myapp", "myapp.json", "myapp.ini", "myapp.yaml", "myapp.yml",
+ *  "myapp/config", "myapp/config.json", ...]
+ * ```
+ */
 export declare function withExtensions(path: string): string[];
+/**
+ * Resolve all existing config files for an application.
+ *
+ * @remarks
+ * Searches in order: `/etc/{name}` (Unix only), `./.{name}` (walking up the
+ * directory tree), and `~/.config/{name}` (home directory). Returns only paths
+ * that exist and are regular files. Used as the default search order when no
+ * explicit `--config` flag is provided.
+ */
 export declare function configFilePaths(name: string): string[];
-export declare function configLoaderFile<S extends ServiceMap = ServiceMap, C extends ModuleConfiguration = ModuleConfiguration>({ application, logger }: ConfigLoaderParams<S, C>): ConfigLoaderReturn;
+/**
+ * Load configuration from file(s).
+ *
+ * @remarks
+ * Checks for an explicit `--config` CLI flag or `CONFIG` config value; if
+ * provided and the file does not exist, exits fatally. Otherwise, searches
+ * standard paths using `configFilePaths`. Merges all found files using
+ * `deepExtend`, with earlier files as defaults.
+ *
+ * @throws {Error} (via process.exit) when `--config` points to a non-existent file
+ * or when argv parsing fails.
+ */
+export declare function configLoaderFile<S extends ServiceMap = ServiceMap, C extends ModuleConfiguration = ModuleConfiguration>({ application, logger, internal }: ConfigLoaderParams<S, C>): ConfigLoaderReturn;
+/**
+ * Parse and merge a single config file into the output object.
+ *
+ * @remarks
+ * Detects format by extension first; if ambiguous or no extension matches,
+ * uses heuristics: if content starts with `{`, tries JSON; then YAML; finally
+ * falls back to INI. File is merged into `out` using `deepExtend`.
+ *
+ * @example
+ * ```
+ * const config: PartialConfiguration = {};
+ * loadConfigFromFile(config, "/etc/myapp.yaml");
+ * // config is now merged with the file contents
+ * ```
+ */
 export declare function loadConfigFromFile(out: PartialConfiguration, filePath: string): void;

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

@@ -1,3 +1,14 @@
+/**
+ * File-based configuration loader — reads JSON, YAML, and INI config files.
+ *
+ * @remarks
+ * Supports four formats (JSON, YAML, INI, and auto-detect) and searches standard
+ * config paths: `/etc/{app}`, `./{app}` (walking up the directory tree),
+ * `~/.config/{app}`, and explicit `--config` flag overrides. Files are detected
+ * by extension and parsed accordingly; if extension is ambiguous, format detection
+ * occurs in order: JSON-like start, YAML parse, INI fallback. Multiple files are
+ * merged using `deepExtend`, with earlier files providing defaults.
+ */
 import fs from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -9,44 +20,91 @@ import { is } from "../index.mjs";
 import { deepExtend } from "./extend.mjs";
 import { INVERT_VALUE, START } from "./utilities.mjs";
 const isWindows = platform === "win32";
+/**
+ * Supported config file extensions.
+ */
 export const SUPPORTED_CONFIG_EXTENSIONS = ["json", "ini", "yaml", "yml"];
+/**
+ * Generate potential file paths for a given base path.
+ *
+ * @remarks
+ * Returns an array of paths including the base, a "config" subdirectory variant,
+ * and all supported extensions of each. This is used to generate candidates
+ * without checking filesystem; callers filter to existing files.
+ *
+ * @example
+ * ```
+ * withExtensions("myapp") returns:
+ * ["myapp", "myapp.json", "myapp.ini", "myapp.yaml", "myapp.yml",
+ *  "myapp/config", "myapp/config.json", ...]
+ * ```
+ */
 export function withExtensions(path) {
     return [path, join(path, "config")].flatMap(path => [
         path,
         ...SUPPORTED_CONFIG_EXTENSIONS.map(i => `${path}.${i}`),
     ]);
 }
+/**
+ * Resolve all existing config files for an application.
+ *
+ * @remarks
+ * Searches in order: `/etc/{name}` (Unix only), `./.{name}` (walking up the
+ * directory tree), and `~/.config/{name}` (home directory). Returns only paths
+ * that exist and are regular files. Used as the default search order when no
+ * explicit `--config` flag is provided.
+ */
 export function configFilePaths(name) {
     const out = [];
+    // system-wide config (Unix only)
     if (!isWindows) {
         out.push(...withExtensions(join(`/etc`, `${name}`)));
     }
+    // search up the directory tree from cwd
     let current = cwd();
     let next;
     while (!is.empty(current)) {
         out.push(...withExtensions(join(current, `.${name}`)));
         next = join(current, "..");
+        // stop at filesystem root
         if (next === current) {
             break;
         }
         current = next;
     }
+    // user-local config
     out.push(...withExtensions(join(homedir(), ".config", name)));
+    // filter to existing regular files
     return out.filter(filePath => fs.existsSync(filePath) && fs.statSync(filePath).isFile());
 }
-export async function configLoaderFile({ application, logger }) {
+/**
+ * Load configuration from file(s).
+ *
+ * @remarks
+ * Checks for an explicit `--config` CLI flag or `CONFIG` config value; if
+ * provided and the file does not exist, exits fatally. Otherwise, searches
+ * standard paths using `configFilePaths`. Merges all found files using
+ * `deepExtend`, with earlier files as defaults.
+ *
+ * @throws {Error} (via process.exit) when `--config` points to a non-existent file
+ * or when argv parsing fails.
+ */
+export async function configLoaderFile({ application, logger, internal }) {
     const CLI_SWITCHES = minimist(process.argv);
-    const configFile = CLI_SWITCHES.config;
+    const configFile = CLI_SWITCHES.config ?? internal?.boot?.options?.configuration?.boilerplate?.CONFIG;
     let files;
+    // argv parsing errors result in a boolean instead of a string
     if (is.boolean(configFile)) {
         logger.fatal({ argv: process.argv }, "system failed to parse argv");
         process.exit();
     }
     else if (is.empty(configFile)) {
+        // no explicit config; search standard paths
         files = configFilePaths(application.name);
         logger.trace({ files, name: configLoaderFile }, `identified config files`);
     }
     else {
+        // explicit config file provided; must exist
         if (!fs.existsSync(configFile)) {
             logger.fatal({ configFile, name: configLoaderFile }, `used {--config} to specify path that does not exist`);
             process.exit();
@@ -62,8 +120,24 @@ export async function configLoaderFile({ application, logger }) {
     files.forEach(file => loadConfigFromFile(out, file));
     return out;
 }
+/**
+ * Parse and merge a single config file into the output object.
+ *
+ * @remarks
+ * Detects format by extension first; if ambiguous or no extension matches,
+ * uses heuristics: if content starts with `{`, tries JSON; then YAML; finally
+ * falls back to INI. File is merged into `out` using `deepExtend`.
+ *
+ * @example
+ * ```
+ * const config: PartialConfiguration = {};
+ * loadConfigFromFile(config, "/etc/myapp.yaml");
+ * // config is now merged with the file contents
+ * ```
+ */
 export function loadConfigFromFile(out, filePath) {
     const fileContent = fs.readFileSync(filePath, "utf8").trim();
+    // check if filename has a recognized extension and parse accordingly
     const hasExtension = SUPPORTED_CONFIG_EXTENSIONS.some(extension => {
         if (filePath.slice(extension.length * INVERT_VALUE).toLowerCase() === extension) {
             switch (extension) {
@@ -81,15 +155,17 @@ export function loadConfigFromFile(out, filePath) {
         }
         return false;
     });
+    // extension was recognized and parsed
     if (hasExtension) {
         return;
     }
-    // Guessing JSON
+    // no extension; try to detect format heuristically
+    // JSON objects start with `{`
     if (fileContent[START] === "{") {
         deepExtend(out, JSON.parse(fileContent));
         return;
     }
-    // Guessing yaml
+    // try YAML (will throw if malformed)
     try {
         const content = yaml.load(fileContent);
         if (is.object(content)) {
@@ -98,9 +174,9 @@ export function loadConfigFromFile(out, filePath) {
         }
     }
     catch {
-        // Is not a yaml file
+        // not valid YAML; continue to INI fallback
     }
-    // Final fallback: INI
+    // final fallback: treat as INI
     deepExtend(out, ini.decode(fileContent));
 }
 //# sourceMappingURL=config-file-loader.mjs.map

package/dist/helpers/config-file-loader.mjs.map

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

package/dist/helpers/config.d.mts

@@ -3,6 +3,14 @@ import type { INITIALIZE, INJECTED_DEFINITIONS, InternalDefinition, LOAD_PROJECT
 import type { ILogger } from "./logger.mts";
 import type { TBlackHole } from "./utilities.mts";
 import type { ApplicationDefinition, PartialConfiguration, ServiceMap, TInjectedConfig } from "./wiring.mts";
+/**
+ * Describes the three built-in configuration source channels.
+ *
+ * @remarks
+ * Used as the key set for {@link DataTypes} and for the `source` field on
+ * individual config definitions. Each channel can be opted in/out independently
+ * via `BootstrapOptions.configSources`.
+ */
 export interface ConfigLoaderSource {
     /**
      * will be checked for values unless `sources` is defined without argv
@@ -17,9 +25,33 @@ export interface ConfigLoaderSource {
      */
     file: true;
 }
+/** A record of config-key → config-definition for a single module. */
 export type CodeConfigDefinition = Record<string, AnyConfig>;
+/**
+ * All supported primitive config types.
+ *
+ * @remarks
+ * Each value maps to a concrete config interface (`StringConfig`,
+ * `BooleanConfig`, etc.) and determines how the raw string from env/argv/file
+ * is coerced before injection.
+ */
 export type ProjectConfigTypes = "string" | "boolean" | "internal" | "number" | "record" | "string[]";
+/**
+ * Union of all supported config definition shapes.
+ *
+ * @remarks
+ * Narrowing on the `type` discriminant gives access to the specific fields
+ * (e.g., `enum` for `StringConfig`, `default` for every typed config).
+ */
 export type AnyConfig = StringConfig<string> | BooleanConfig | InternalConfig<object> | NumberConfig | RecordConfig | StringArrayConfig;
+/**
+ * Fields shared by every config definition.
+ *
+ * @remarks
+ * The `type` discriminant drives coercion in {@link parseConfig}.
+ * `source` narrows which loaders are allowed to supply this key — omit it to
+ * allow all loaders.
+ */
 export interface BaseConfig {
     /**
      * If no other values are provided, what value should be injected?
@@ -40,7 +72,32 @@ export interface BaseConfig {
      */
     source?: (keyof ConfigLoaderSource)[];
 }
+/**
+ * Map of module-name → config-definition record for all known modules.
+ *
+ * @remarks
+ * Populated incrementally during bootstrap as each library calls
+ * `configuration.[LOAD_PROJECT]`. Used by all config loaders to know which
+ * keys to look up.
+ */
 export type KnownConfigs = Map<string, CodeConfigDefinition>;
+/**
+ * Config definition for a typed string value.
+ *
+ * @remarks
+ * The generic parameter `STRING` lets callers constrain the injected value to a
+ * specific string literal union. When `enum` is provided the framework refuses
+ * to boot if the resolved value is not in the list.
+ *
+ * @example Enum-constrained string
+ * ```typescript
+ * const LOG_LEVEL: StringConfig<"debug" | "info" | "warn"> = {
+ *   default: "info",
+ *   enum: ["debug", "info", "warn"],
+ *   type: "string",
+ * };
+ * ```
+ */
 export interface StringConfig<STRING extends string> extends BaseConfig {
     default?: STRING;
     /**
@@ -49,38 +106,58 @@ export interface StringConfig<STRING extends string> extends BaseConfig {
     enum?: STRING[];
     type: "string";
 }
+/** Config definition for a boolean value. */
 export interface BooleanConfig extends BaseConfig {
     default?: boolean;
     type: "boolean";
 }
 /**
- * For configurations that just can't be expressed any other way.
- * Make sure to add a helpful description on how to format the value,
- * because `config-builder` won't be able to help.
+ * Escape hatch for configurations that can't be expressed as a primitive.
+ *
+ * @remarks
+ * Accepts a JSON-serialisable object as its default; at runtime the raw string
+ * value from env/file is passed through `JSON.parse`. Use the `description`
+ * field to explain the expected structure, because `config-builder` cannot
+ * introspect complex shapes.
  *
  * This can be used to take in a complex json object, and forward the information to another library.
  *
  * TODO: JSON schema magic for validation / maybe config builder help
+ *
+ * For configurations that just can't be expressed any other way.
+ * Make sure to add a helpful description on how to format the value,
+ * because `config-builder` won't be able to help.
  */
 export type InternalConfig<VALUE extends object> = BaseConfig & {
     default: VALUE;
     type: "internal";
 };
+/** Config definition for a numeric value. */
 export interface NumberConfig extends BaseConfig {
     default?: number;
     type: "number";
 }
 /**
+ * Config definition for an arbitrary key/value record.
+ *
+ * @remarks
+ * Injected as a plain object; the raw value is parsed via `JSON.parse` when it
+ * arrives as a string.
+ *
  * key/value pairs
  */
 export interface RecordConfig extends BaseConfig {
     type: "record";
 }
+/** Config definition for a string-array value. */
 export interface StringArrayConfig extends BaseConfig {
     default?: string[];
     type: "string[]";
 }
 /**
+ * Serialisable representation of a module's full config for use by external
+ * tooling (e.g. the `config-builder` CLI scanner).
+ *
  * Used with config scanner
  */
 export interface ConfigDefinitionDTO {
@@ -88,6 +165,7 @@ export interface ConfigDefinitionDTO {
     bootstrapOverrides?: AbstractConfig;
     config: ConfigTypeDTO[];
 }
+/** Single config-item descriptor emitted by the scanner. */
 export interface ConfigTypeDTO<METADATA extends AnyConfig = AnyConfig> {
     /**
      * Name of project
@@ -103,36 +181,133 @@ export interface ConfigTypeDTO<METADATA extends AnyConfig = AnyConfig> {
     property: string;
 }
 /**
- * Top level configuration object
+ * Top level configuration object.
+ *
+ * @remarks
+ * Downstream libraries extend this interface via declaration merging to add
+ * their own config sections. See the architecture docs for the merging pattern.
  *
  * Extends the global common config, adding a section for the top level application to chuck in data without affecting things
  * Also provides dedicated sections for libraries to store their own configuration options
  */
 export interface AbstractConfig {
 }
+/**
+ * Return type of a config loader — a partial snapshot of the global config
+ * hierarchy.
+ */
 export type ConfigLoaderReturn = Promise<Partial<AbstractConfig>>;
+/**
+ * Parameters passed to every config loader at bootstrap time.
+ *
+ * @remarks
+ * Loaders receive the full application definition, the accumulated
+ * `KnownConfigs` map, the internal definition for accessing boot state, and a
+ * logger for diagnostics. Loaders must not throw; they should return an empty
+ * object when they find nothing.
+ */
 export type ConfigLoaderParams<S extends ServiceMap = ServiceMap, C extends OptionalModuleConfiguration = OptionalModuleConfiguration> = {
     application: ApplicationDefinition<S, C>;
     configs: KnownConfigs;
     internal: InternalDefinition;
     logger: ILogger;
 };
+/**
+ * Contract that all config loaders must satisfy.
+ *
+ * @remarks
+ * Each loader is registered for a specific {@link DataTypes} channel via
+ * `DigitalAlchemyConfiguration.registerLoader`. The framework calls all
+ * registered loaders during `onPostConfig` and deep-merges their results.
+ */
 export type ConfigLoader = <S extends ServiceMap, C extends OptionalModuleConfiguration>(params: ConfigLoaderParams<S, C>) => ConfigLoaderReturn;
+/**
+ * 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 declare function cast<T = unknown>(data: boolean | number[] | string | string[], type: string): T;
+/** A record that maps config-key names to their config definitions. */
 export type ModuleConfiguration = {
     [key: string]: AnyConfig;
 };
+/** A module's config block, or `undefined` when the module declares none. */
 export type OptionalModuleConfiguration = ModuleConfiguration | undefined;
+/**
+ * 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 declare function findKey<T extends string>(source: T[], find: T[]): T;
+/**
+ * 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 declare function iSearchKey(target: string, source: string[]): string;
 /**
+ * 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
  * - cwd/.env (default file)
  */
 export declare function loadDotenv(internal: InternalDefinition, CLI_SWITCHES: ParsedArgs, logger: ILogger): void;
+/**
+ * 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 declare function parseConfig(config: AnyConfig, value: unknown): any;
+/**
+ * Internal shape of the configuration service — the object attached to
+ * `internal.boilerplate.configuration`.
+ *
+ * @remarks
+ * Symbol-keyed methods (`[INITIALIZE]`, `[INJECTED_DEFINITIONS]`,
+ * `[LOAD_PROJECT]`) are bootstrap-internal surface and should not be called by
+ * application code. Use the named methods (`getDefinitions`, `registerLoader`,
+ * `merge`, `onUpdate`, `set`) for runtime configuration interaction.
+ *
+ * @internal
+ */
 export type DigitalAlchemyConfiguration = {
     [INITIALIZE]: <S extends ServiceMap, C extends OptionalModuleConfiguration>(application: ApplicationDefinition<S, C>) => Promise<string>;
     [INJECTED_DEFINITIONS]: TInjectedConfig;
@@ -141,9 +316,13 @@ export type DigitalAlchemyConfiguration = {
     registerLoader: (loader: ConfigLoader, type: DataTypes) => void;
     merge: (incoming: Partial<PartialConfiguration>) => PartialConfiguration;
     /**
+     * Subscribe to runtime config changes made via `config.set`.
+     *
+     * @remarks
      * Not a replacement for `onPostConfig`
      *
-     * Only receives updates from `config.set` calls
+     * Only receives updates from `config.set` calls — initial load values do not
+     * trigger this callback.
      */
     onUpdate: <Project extends keyof TInjectedConfig, Property extends Extract<keyof TInjectedConfig[Project], string>>(callback: OnConfigUpdateCallback<Project, Property>, project?: Project, property?: Property) => void;
     /**
@@ -153,6 +332,24 @@ export type DigitalAlchemyConfiguration = {
      */
     set: TSetConfig;
 };
+/**
+ * Type-safe setter for a single config value.
+ *
+ * @remarks
+ * The generic parameters are inferred from the call site — TypeScript enforces
+ * that `property` is a valid key of the chosen `project` section and that
+ * `value` matches the declared type.
+ */
 export type TSetConfig = <Project extends keyof TInjectedConfig, Property extends keyof TInjectedConfig[Project]>(project: Project, property: Property, value: TInjectedConfig[Project][Property]) => void;
+/**
+ * Callback signature for config-update subscriptions.
+ *
+ * @remarks
+ * Receives the `project` and `property` names that changed; callers read the
+ * new value directly from `config[project][property]` rather than receiving it
+ * as a parameter, which keeps the callback signature stable regardless of the
+ * value type.
+ */
 export type OnConfigUpdateCallback<Project extends keyof TInjectedConfig, Property extends keyof TInjectedConfig[Project]> = (project: Project, property: Property) => TBlackHole;
+/** Union of the three supported config source channel names. */
 export type DataTypes = keyof ConfigLoaderSource;