@decaf-ts/integrations 0.10.8 → 0.12.0

package/lib/types/io/spreadsheet/SpreadsheetService.d.cts

@@ -0,0 +1,144 @@
+/**
+ * @module integrations/io/spreadsheet/service
+ * @summary Delimiter-agnostic spreadsheet parsing and serialization service.
+ * @description Parses and serializes CSV, TSV, and JSON tabular content
+ * without external dependencies: a hand-written RFC 4180-style parser (quoted
+ * fields, escaped quotes, CRLF handling) and a quoting serializer. Unlike the
+ * other io services it is not HTTP-backed and requires no configuration — it
+ * operates purely on in-memory strings and arrays.
+ */
+/**
+ * @description The tabular content formats the spreadsheet service handles
+ * @summary `"csv"` (comma-delimited), `"tsv"` (tab-delimited), and `"json"`
+ * (an array of rows or of records keyed by column name).
+ * @category IO
+ * @memberOf module:integrations/io/spreadsheet/service
+ */
+export type SpreadsheetFormat = "csv" | "tsv" | "json";
+/**
+ * @description Options controlling how spreadsheet content is parsed
+ * @summary Selects the `format` (inferred from the `delimiter` when omitted:
+ * `"\t"` implies `"tsv"`, otherwise `"csv"`) and whether the first parsed row
+ * is treated as a header (`true` by default; set `header: false` to keep it
+ * in `rows` and receive an empty `header`).
+ * @category IO
+ * @memberOf module:integrations/io/spreadsheet/service
+ */
+export interface SpreadsheetParseOptions {
+    /**
+     * @description Explicit content format; inferred from `delimiter` when omitted
+     */
+    format?: SpreadsheetFormat;
+    /**
+     * @description Delimiter for delimited formats; defaults to `","` for CSV and `"\t"` for TSV
+     */
+    delimiter?: string;
+    /**
+     * @description Whether the first row is a header; defaults to `true`
+     */
+    header?: boolean;
+}
+/**
+ * @description Result of parsing spreadsheet content
+ * @summary Carries the resolved `format`, the `header` row (empty when
+ * `header: false` was requested), and the remaining data `rows`.
+ * @category IO
+ * @memberOf module:integrations/io/spreadsheet/service
+ */
+export interface SpreadsheetParseResult {
+    format: SpreadsheetFormat;
+    header: string[];
+    rows: string[][];
+}
+/**
+ * @description Options controlling how rows are serialized to spreadsheet content
+ * @summary Selects the `format` (inferred from the `delimiter` when omitted),
+ * the `delimiter` for delimited formats, and an optional `header` row written
+ * before the data. For `"json"`, the `header` values become the record keys
+ * (falling back to the first data row as keys).
+ * @category IO
+ * @memberOf module:integrations/io/spreadsheet/service
+ */
+export interface SpreadsheetWriteOptions {
+    /**
+     * @description Explicit output format; inferred from `delimiter` when omitted
+     */
+    format?: SpreadsheetFormat;
+    /**
+     * @description Delimiter for delimited formats; defaults to `","` for CSV and `"\t"` for TSV
+     */
+    delimiter?: string;
+    /**
+     * @description Header row written before the data (or used as record keys for JSON)
+     */
+    header?: string[];
+}
+/**
+ * @description Dependency-free spreadsheet parsing and serialization service
+ * @summary A stateless (no configuration, no HTTP client) service that
+ * converts between tabular strings and row arrays. `parse` handles CSV and
+ * TSV with a quoted-field parser (double-quote escaping, CRLF stripping,
+ * blank-row filtering) and JSON arrays of rows or records; `serialize`
+ * writes CSV/TSV with RFC 4180-style quoting of fields containing the
+ * delimiter, quotes, or line breaks, or pretty-printed JSON records. Values
+ * are stringified with `null`/`undefined` as empty cells and objects as JSON.
+ * @class SpreadsheetService
+ * @category IO
+ * @example
+ * ```ts
+ * import { SpreadsheetService } from "@decaf-ts/integrations/io/spreadsheet";
+ *
+ * const spreadsheets = new SpreadsheetService();
+ * const parsed = spreadsheets.parse("name,count\nalpha,1\nbeta,2", {
+ *   format: "csv",
+ * });
+ * // parsed.header === ["name", "count"], parsed.rows === [["alpha", "1"], ["beta", "2"]]
+ * ```
+ * @memberOf module:integrations/io/spreadsheet/service
+ */
+export declare class SpreadsheetService {
+    /**
+     * @description Parses spreadsheet text into a header and data rows
+     * @summary Dispatches on the resolved format. `"json"` content must be an
+     * array: either an array of arrays (the first row becomes the header unless
+     * `header: false`) or an array of records (the union of the first record's
+     * keys becomes the header). CSV/TSV content is parsed with a quoted-field
+     * parser honoring `""` escapes and CR/LF line endings, dropping blank rows;
+     * the first row becomes the header unless `header: false`.
+     * @param {string} content - The spreadsheet text content to parse.
+     * @param {SpreadsheetParseOptions} [options] - Format, delimiter, and header options.
+     * @returns {SpreadsheetParseResult} The resolved format, header row, and data rows.
+     * @throws {InternalError} When the content is not a string, the JSON payload is invalid, or the JSON payload is not an array.
+     * @example
+     * ```ts
+     * // TSV with an explicit delimiter and no header row
+     * const tsv = spreadsheets.parse("alpha\t1\nbeta\t2", { delimiter: "\t", header: false });
+     * // JSON records infer the header from the first record's keys
+     * const json = spreadsheets.parse('[{"name":"alpha","count":1}]', { format: "json" });
+     * ```
+     */
+    parse(content: string, options?: SpreadsheetParseOptions): SpreadsheetParseResult;
+    /**
+     * @description Serializes rows into spreadsheet text
+     * @summary Stringifies each cell (objects become JSON, `null`/`undefined`
+     * become empty cells) and dispatches on the resolved format. For `"json"`,
+     * the optional `header` values (or the first data row) become the record
+     * keys and the output is pretty-printed JSON records. For `"csv"`/`"tsv"`,
+     * fields containing the delimiter, quotes, or line breaks are wrapped in
+     * double quotes with inner quotes escaped, and the optional `header` row is
+     * written first. Non-array rows are treated as single-cell rows.
+     * @param {unknown[][]} rows - The data rows to serialize.
+     * @param {SpreadsheetWriteOptions} [options] - Format, delimiter, and header options.
+     * @returns {string} The serialized spreadsheet content.
+     * @throws {InternalError} When `rows` is not an array.
+     * @example
+     * ```ts
+     * const csv = spreadsheets.serialize(
+     *   [["alpha", 1], ["beta, gamma", 2]],
+     *   { format: "csv", header: ["name", "count"] }
+     * );
+     * // "name,count\nalpha,1\n\"beta, gamma\",2"
+     * ```
+     */
+    serialize(rows: unknown[][], options?: SpreadsheetWriteOptions): string;
+}

package/lib/types/io/spreadsheet/SpreadsheetService.d.mts

@@ -0,0 +1,144 @@
+/**
+ * @module integrations/io/spreadsheet/service
+ * @summary Delimiter-agnostic spreadsheet parsing and serialization service.
+ * @description Parses and serializes CSV, TSV, and JSON tabular content
+ * without external dependencies: a hand-written RFC 4180-style parser (quoted
+ * fields, escaped quotes, CRLF handling) and a quoting serializer. Unlike the
+ * other io services it is not HTTP-backed and requires no configuration — it
+ * operates purely on in-memory strings and arrays.
+ */
+/**
+ * @description The tabular content formats the spreadsheet service handles
+ * @summary `"csv"` (comma-delimited), `"tsv"` (tab-delimited), and `"json"`
+ * (an array of rows or of records keyed by column name).
+ * @category IO
+ * @memberOf module:integrations/io/spreadsheet/service
+ */
+export type SpreadsheetFormat = "csv" | "tsv" | "json";
+/**
+ * @description Options controlling how spreadsheet content is parsed
+ * @summary Selects the `format` (inferred from the `delimiter` when omitted:
+ * `"\t"` implies `"tsv"`, otherwise `"csv"`) and whether the first parsed row
+ * is treated as a header (`true` by default; set `header: false` to keep it
+ * in `rows` and receive an empty `header`).
+ * @category IO
+ * @memberOf module:integrations/io/spreadsheet/service
+ */
+export interface SpreadsheetParseOptions {
+    /**
+     * @description Explicit content format; inferred from `delimiter` when omitted
+     */
+    format?: SpreadsheetFormat;
+    /**
+     * @description Delimiter for delimited formats; defaults to `","` for CSV and `"\t"` for TSV
+     */
+    delimiter?: string;
+    /**
+     * @description Whether the first row is a header; defaults to `true`
+     */
+    header?: boolean;
+}
+/**
+ * @description Result of parsing spreadsheet content
+ * @summary Carries the resolved `format`, the `header` row (empty when
+ * `header: false` was requested), and the remaining data `rows`.
+ * @category IO
+ * @memberOf module:integrations/io/spreadsheet/service
+ */
+export interface SpreadsheetParseResult {
+    format: SpreadsheetFormat;
+    header: string[];
+    rows: string[][];
+}
+/**
+ * @description Options controlling how rows are serialized to spreadsheet content
+ * @summary Selects the `format` (inferred from the `delimiter` when omitted),
+ * the `delimiter` for delimited formats, and an optional `header` row written
+ * before the data. For `"json"`, the `header` values become the record keys
+ * (falling back to the first data row as keys).
+ * @category IO
+ * @memberOf module:integrations/io/spreadsheet/service
+ */
+export interface SpreadsheetWriteOptions {
+    /**
+     * @description Explicit output format; inferred from `delimiter` when omitted
+     */
+    format?: SpreadsheetFormat;
+    /**
+     * @description Delimiter for delimited formats; defaults to `","` for CSV and `"\t"` for TSV
+     */
+    delimiter?: string;
+    /**
+     * @description Header row written before the data (or used as record keys for JSON)
+     */
+    header?: string[];
+}
+/**
+ * @description Dependency-free spreadsheet parsing and serialization service
+ * @summary A stateless (no configuration, no HTTP client) service that
+ * converts between tabular strings and row arrays. `parse` handles CSV and
+ * TSV with a quoted-field parser (double-quote escaping, CRLF stripping,
+ * blank-row filtering) and JSON arrays of rows or records; `serialize`
+ * writes CSV/TSV with RFC 4180-style quoting of fields containing the
+ * delimiter, quotes, or line breaks, or pretty-printed JSON records. Values
+ * are stringified with `null`/`undefined` as empty cells and objects as JSON.
+ * @class SpreadsheetService
+ * @category IO
+ * @example
+ * ```ts
+ * import { SpreadsheetService } from "@decaf-ts/integrations/io/spreadsheet";
+ *
+ * const spreadsheets = new SpreadsheetService();
+ * const parsed = spreadsheets.parse("name,count\nalpha,1\nbeta,2", {
+ *   format: "csv",
+ * });
+ * // parsed.header === ["name", "count"], parsed.rows === [["alpha", "1"], ["beta", "2"]]
+ * ```
+ * @memberOf module:integrations/io/spreadsheet/service
+ */
+export declare class SpreadsheetService {
+    /**
+     * @description Parses spreadsheet text into a header and data rows
+     * @summary Dispatches on the resolved format. `"json"` content must be an
+     * array: either an array of arrays (the first row becomes the header unless
+     * `header: false`) or an array of records (the union of the first record's
+     * keys becomes the header). CSV/TSV content is parsed with a quoted-field
+     * parser honoring `""` escapes and CR/LF line endings, dropping blank rows;
+     * the first row becomes the header unless `header: false`.
+     * @param {string} content - The spreadsheet text content to parse.
+     * @param {SpreadsheetParseOptions} [options] - Format, delimiter, and header options.
+     * @returns {SpreadsheetParseResult} The resolved format, header row, and data rows.
+     * @throws {InternalError} When the content is not a string, the JSON payload is invalid, or the JSON payload is not an array.
+     * @example
+     * ```ts
+     * // TSV with an explicit delimiter and no header row
+     * const tsv = spreadsheets.parse("alpha\t1\nbeta\t2", { delimiter: "\t", header: false });
+     * // JSON records infer the header from the first record's keys
+     * const json = spreadsheets.parse('[{"name":"alpha","count":1}]', { format: "json" });
+     * ```
+     */
+    parse(content: string, options?: SpreadsheetParseOptions): SpreadsheetParseResult;
+    /**
+     * @description Serializes rows into spreadsheet text
+     * @summary Stringifies each cell (objects become JSON, `null`/`undefined`
+     * become empty cells) and dispatches on the resolved format. For `"json"`,
+     * the optional `header` values (or the first data row) become the record
+     * keys and the output is pretty-printed JSON records. For `"csv"`/`"tsv"`,
+     * fields containing the delimiter, quotes, or line breaks are wrapped in
+     * double quotes with inner quotes escaped, and the optional `header` row is
+     * written first. Non-array rows are treated as single-cell rows.
+     * @param {unknown[][]} rows - The data rows to serialize.
+     * @param {SpreadsheetWriteOptions} [options] - Format, delimiter, and header options.
+     * @returns {string} The serialized spreadsheet content.
+     * @throws {InternalError} When `rows` is not an array.
+     * @example
+     * ```ts
+     * const csv = spreadsheets.serialize(
+     *   [["alpha", 1], ["beta, gamma", 2]],
+     *   { format: "csv", header: ["name", "count"] }
+     * );
+     * // "name,count\nalpha,1\n\"beta, gamma\",2"
+     * ```
+     */
+    serialize(rows: unknown[][], options?: SpreadsheetWriteOptions): string;
+}

package/lib/types/io/spreadsheet/index.d.cts

@@ -0,0 +1,7 @@
+/**
+ * @module integrations/io/spreadsheet
+ * @summary Tabular text parse/serialize service (CSV, TSV, JSON lines).
+ * @description Re-exports the offline spreadsheet service and its types; no
+ * network or credentials are involved.
+ */
+export * from "./SpreadsheetService.d.cts";

package/lib/types/io/spreadsheet/index.d.mts

@@ -0,0 +1,7 @@
+/**
+ * @module integrations/io/spreadsheet
+ * @summary Tabular text parse/serialize service (CSV, TSV, JSON lines).
+ * @description Re-exports the offline spreadsheet service and its types; no
+ * network or credentials are involved.
+ */
+export * from "./SpreadsheetService.d.mts";

package/lib/types/loader/ObjectLoader.d.cts

@@ -1,27 +1,71 @@
-import type { ObjectLoaderExportSelection, ObjectLoaderFamily, ObjectLoaderHook, ObjectLoaderHookContext, ObjectLoaderLoadOptions, ObjectLoaderOptions, ObjectLoaderSource } from "./types.d.cts";
+import type { ObjectLoaderExportSelection, ObjectLoaderFamily, ObjectLoaderHook, ObjectLoaderHookContext, ObjectLoaderHookPhase, ObjectLoaderLoadOptions, ObjectLoaderOptions, ObjectLoaderSource } from "./types.d.cts";
 /**
  * @module integrations/loader
  * @summary Dynamic TypeScript object loader utilities.
  * @description Base loader and concrete family loaders for dynamically
  * resolving Decaf integration objects without forcing callers to duplicate
  * import, selection, or post-load hook logic.
+ *
+ * ## Tree-shaking / build-time references
+ *
+ * Dynamic imports are resolved at runtime, so a bundler cannot see which modules
+ * are actually reachable and may drop them from the output. To keep a module
+ * available, keep a *static* reference to it somewhere in the entry graph (for
+ * example a `loaderManifest` object or a side-effect import) while the runtime
+ * lookup still goes through {@link ObjectLoader.loadModule}. Prefer passing the
+ * specifier as a variable (`import(specifier)`) instead of a string literal:
+ * bundlers leave non-literal dynamic imports untouched, which preserves the
+ * lazy/runtime semantics. See {@link moduleReference} for a small helper that
+ * encodes this pattern.
  */
 export declare class ObjectLoader {
     readonly family: ObjectLoaderFamily;
     readonly defaultExportName: string;
     protected readonly hooks: readonly ObjectLoaderHook[];
+    protected readonly beforeResolveHooks: readonly ObjectLoaderHook[];
+    protected readonly metadata: Readonly<Record<string, unknown>>;
     constructor(options?: ObjectLoaderOptions);
     protected normalizeSource(source: ObjectLoaderSource): string;
     protected importModule(source: ObjectLoaderSource): Promise<Readonly<Record<string, unknown>>>;
     protected resolveExport(module: Readonly<Record<string, unknown>>, exportName: string, source: string): unknown;
     protected applyHooks<T>(value: T, context: ObjectLoaderHookContext, hooks: readonly ObjectLoaderHook[]): Promise<T>;
+    /**
+     * @summary Build the hook context for a load operation.
+     * @description Concrete loaders call this to build a context that carries the
+     * load phase and any loader-specific metadata into hooks.
+     */
+    protected createContext(source: string, exportName: string, module: Readonly<Record<string, unknown>>, phase: ObjectLoaderHookPhase, metadata?: Readonly<Record<string, unknown>>): ObjectLoaderHookContext;
+    /**
+     * @summary Run the configured export hooks against a value.
+     * @description Exposed to concrete loaders that load content (assets, configs)
+     * instead of importing a module, so they can reuse the same hook pipeline.
+     */
+    protected runHooks<T>(value: T, context: ObjectLoaderHookContext, options?: ObjectLoaderLoadOptions): Promise<T>;
+    /**
+     * @summary Run the configured pre-resolve hooks against a module namespace.
+     */
+    protected runBeforeResolveHooks(module: Readonly<Record<string, unknown>>, context: ObjectLoaderHookContext, options?: ObjectLoaderLoadOptions): Promise<Readonly<Record<string, unknown>>>;
     protected createInstance(options: ObjectLoaderOptions): this;
     loadModule(source: ObjectLoaderSource): Promise<Readonly<Record<string, unknown>>>;
     loadExport<T = unknown>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
     loadDefault<T = unknown>(source: ObjectLoaderSource, options?: ObjectLoaderLoadOptions): Promise<T>;
     load<T = unknown>(source: ObjectLoaderSource, options?: ObjectLoaderLoadOptions): Promise<T>;
     withHooks(...hooks: ObjectLoaderHook[]): this;
+    withBeforeResolveHooks(...hooks: ObjectLoaderHook[]): this;
     withOptions(options: Partial<ObjectLoaderOptions>): this;
 }
-export declare function createLoaderHookContext(loader: ObjectLoader, module: Readonly<Record<string, unknown>>, source: string, exportName: string): ObjectLoaderHookContext;
+export declare function createLoaderHookContext(loader: ObjectLoader, module: Readonly<Record<string, unknown>>, source: string, exportName: string, phase?: ObjectLoaderHookPhase, metadata?: Readonly<Record<string, unknown>>): ObjectLoaderHookContext;
+/**
+ * @summary Build a lazy module reference that survives bundling.
+ * @description Pass a *variable* specifier to `import()` so bundlers do not
+ * statically inline or drop the target. Pair it with a static reference in your
+ * entry graph when the module must be retained:
+ *
+ * ```ts
+ * export const loaderManifest = { feature: "./feature/index.js" } as const;
+ * const reference = moduleReference(loaderManifest.feature);
+ * const module = await reference();
+ * ```
+ */
+export declare function moduleReference(specifier: string): () => Promise<Readonly<Record<string, unknown>>>;
 export type { ObjectLoaderExportSelection };

package/lib/types/loader/ObjectLoader.d.mts

@@ -1,27 +1,71 @@
-import type { ObjectLoaderExportSelection, ObjectLoaderFamily, ObjectLoaderHook, ObjectLoaderHookContext, ObjectLoaderLoadOptions, ObjectLoaderOptions, ObjectLoaderSource } from "./types.d.mts";
+import type { ObjectLoaderExportSelection, ObjectLoaderFamily, ObjectLoaderHook, ObjectLoaderHookContext, ObjectLoaderHookPhase, ObjectLoaderLoadOptions, ObjectLoaderOptions, ObjectLoaderSource } from "./types.d.mts";
 /**
  * @module integrations/loader
  * @summary Dynamic TypeScript object loader utilities.
  * @description Base loader and concrete family loaders for dynamically
  * resolving Decaf integration objects without forcing callers to duplicate
  * import, selection, or post-load hook logic.
+ *
+ * ## Tree-shaking / build-time references
+ *
+ * Dynamic imports are resolved at runtime, so a bundler cannot see which modules
+ * are actually reachable and may drop them from the output. To keep a module
+ * available, keep a *static* reference to it somewhere in the entry graph (for
+ * example a `loaderManifest` object or a side-effect import) while the runtime
+ * lookup still goes through {@link ObjectLoader.loadModule}. Prefer passing the
+ * specifier as a variable (`import(specifier)`) instead of a string literal:
+ * bundlers leave non-literal dynamic imports untouched, which preserves the
+ * lazy/runtime semantics. See {@link moduleReference} for a small helper that
+ * encodes this pattern.
  */
 export declare class ObjectLoader {
     readonly family: ObjectLoaderFamily;
     readonly defaultExportName: string;
     protected readonly hooks: readonly ObjectLoaderHook[];
+    protected readonly beforeResolveHooks: readonly ObjectLoaderHook[];
+    protected readonly metadata: Readonly<Record<string, unknown>>;
     constructor(options?: ObjectLoaderOptions);
     protected normalizeSource(source: ObjectLoaderSource): string;
     protected importModule(source: ObjectLoaderSource): Promise<Readonly<Record<string, unknown>>>;
     protected resolveExport(module: Readonly<Record<string, unknown>>, exportName: string, source: string): unknown;
     protected applyHooks<T>(value: T, context: ObjectLoaderHookContext, hooks: readonly ObjectLoaderHook[]): Promise<T>;
+    /**
+     * @summary Build the hook context for a load operation.
+     * @description Concrete loaders call this to build a context that carries the
+     * load phase and any loader-specific metadata into hooks.
+     */
+    protected createContext(source: string, exportName: string, module: Readonly<Record<string, unknown>>, phase: ObjectLoaderHookPhase, metadata?: Readonly<Record<string, unknown>>): ObjectLoaderHookContext;
+    /**
+     * @summary Run the configured export hooks against a value.
+     * @description Exposed to concrete loaders that load content (assets, configs)
+     * instead of importing a module, so they can reuse the same hook pipeline.
+     */
+    protected runHooks<T>(value: T, context: ObjectLoaderHookContext, options?: ObjectLoaderLoadOptions): Promise<T>;
+    /**
+     * @summary Run the configured pre-resolve hooks against a module namespace.
+     */
+    protected runBeforeResolveHooks(module: Readonly<Record<string, unknown>>, context: ObjectLoaderHookContext, options?: ObjectLoaderLoadOptions): Promise<Readonly<Record<string, unknown>>>;
     protected createInstance(options: ObjectLoaderOptions): this;
     loadModule(source: ObjectLoaderSource): Promise<Readonly<Record<string, unknown>>>;
     loadExport<T = unknown>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
     loadDefault<T = unknown>(source: ObjectLoaderSource, options?: ObjectLoaderLoadOptions): Promise<T>;
     load<T = unknown>(source: ObjectLoaderSource, options?: ObjectLoaderLoadOptions): Promise<T>;
     withHooks(...hooks: ObjectLoaderHook[]): this;
+    withBeforeResolveHooks(...hooks: ObjectLoaderHook[]): this;
     withOptions(options: Partial<ObjectLoaderOptions>): this;
 }
-export declare function createLoaderHookContext(loader: ObjectLoader, module: Readonly<Record<string, unknown>>, source: string, exportName: string): ObjectLoaderHookContext;
+export declare function createLoaderHookContext(loader: ObjectLoader, module: Readonly<Record<string, unknown>>, source: string, exportName: string, phase?: ObjectLoaderHookPhase, metadata?: Readonly<Record<string, unknown>>): ObjectLoaderHookContext;
+/**
+ * @summary Build a lazy module reference that survives bundling.
+ * @description Pass a *variable* specifier to `import()` so bundlers do not
+ * statically inline or drop the target. Pair it with a static reference in your
+ * entry graph when the module must be retained:
+ *
+ * ```ts
+ * export const loaderManifest = { feature: "./feature/index.js" } as const;
+ * const reference = moduleReference(loaderManifest.feature);
+ * const module = await reference();
+ * ```
+ */
+export declare function moduleReference(specifier: string): () => Promise<Readonly<Record<string, unknown>>>;
 export type { ObjectLoaderExportSelection };

package/lib/types/loader/assets.d.cts

@@ -0,0 +1,43 @@
+import { ObjectLoader } from "./ObjectLoader.d.cts";
+import type { ObjectLoaderLoadOptions, ObjectLoaderOptions, ObjectLoaderSource } from "./types.d.cts";
+export type AssetEncoding = "utf8" | "binary" | "base64" | "json" | "auto";
+export interface LoadedAsset<T = unknown> {
+    /** Normalized source used to locate the asset. */
+    readonly source: string;
+    /** Resolved filesystem path. */
+    readonly path: string;
+    /** File name including extension. */
+    readonly name: string;
+    /** Lower-cased file extension (e.g. `.json`). */
+    readonly extension: string;
+    /** Encoding used to decode the content. */
+    readonly encoding: Exclude<AssetEncoding, "auto">;
+    /** Best-effort content type derived from the extension. */
+    readonly contentType: string;
+    /** Decoded content. */
+    readonly content: T;
+}
+export interface AssetLoadOptions extends ObjectLoaderLoadOptions {
+    readonly encoding?: AssetEncoding;
+}
+/**
+ * @summary Load asset files as content instead of importing a class.
+ * @description Assets (locale files, images, templates, ...) are *not* modules;
+ * they are read from disk and decoded. Hooks run on the {@link LoadedAsset}
+ * record so callers can inspect or replace content before it enters the system.
+ *
+ * A `"json"` encoding parses the file content, `"utf8"` returns text,
+ * `"base64"` returns a base64 string, and `"binary"` returns the raw
+ * `Buffer`. `"auto"` picks `json` for `.json`, `utf8` for known text
+ * extensions, and `binary` otherwise.
+ */
+export declare class AssetObjectLoader extends ObjectLoader {
+    constructor(options?: ObjectLoaderOptions);
+    loadAsset<T = unknown>(source: ObjectLoaderSource, options?: AssetLoadOptions): Promise<LoadedAsset<T>>;
+    loadText(source: ObjectLoaderSource, options?: AssetLoadOptions): Promise<string>;
+    loadJson<T = unknown>(source: ObjectLoaderSource, options?: AssetLoadOptions): Promise<T>;
+    loadBinary(source: ObjectLoaderSource, options?: AssetLoadOptions): Promise<Buffer>;
+    protected resolveEncoding(extension: string, requested: AssetEncoding): Exclude<AssetEncoding, "auto">;
+    protected decode<T>(buffer: Buffer, encoding: Exclude<AssetEncoding, "auto">): T;
+    protected toFilePath(source: ObjectLoaderSource): string;
+}

package/lib/types/loader/assets.d.mts

@@ -0,0 +1,43 @@
+import { ObjectLoader } from "./ObjectLoader.d.mts";
+import type { ObjectLoaderLoadOptions, ObjectLoaderOptions, ObjectLoaderSource } from "./types.d.mts";
+export type AssetEncoding = "utf8" | "binary" | "base64" | "json" | "auto";
+export interface LoadedAsset<T = unknown> {
+    /** Normalized source used to locate the asset. */
+    readonly source: string;
+    /** Resolved filesystem path. */
+    readonly path: string;
+    /** File name including extension. */
+    readonly name: string;
+    /** Lower-cased file extension (e.g. `.json`). */
+    readonly extension: string;
+    /** Encoding used to decode the content. */
+    readonly encoding: Exclude<AssetEncoding, "auto">;
+    /** Best-effort content type derived from the extension. */
+    readonly contentType: string;
+    /** Decoded content. */
+    readonly content: T;
+}
+export interface AssetLoadOptions extends ObjectLoaderLoadOptions {
+    readonly encoding?: AssetEncoding;
+}
+/**
+ * @summary Load asset files as content instead of importing a class.
+ * @description Assets (locale files, images, templates, ...) are *not* modules;
+ * they are read from disk and decoded. Hooks run on the {@link LoadedAsset}
+ * record so callers can inspect or replace content before it enters the system.
+ *
+ * A `"json"` encoding parses the file content, `"utf8"` returns text,
+ * `"base64"` returns a base64 string, and `"binary"` returns the raw
+ * `Buffer`. `"auto"` picks `json` for `.json`, `utf8` for known text
+ * extensions, and `binary` otherwise.
+ */
+export declare class AssetObjectLoader extends ObjectLoader {
+    constructor(options?: ObjectLoaderOptions);
+    loadAsset<T = unknown>(source: ObjectLoaderSource, options?: AssetLoadOptions): Promise<LoadedAsset<T>>;
+    loadText(source: ObjectLoaderSource, options?: AssetLoadOptions): Promise<string>;
+    loadJson<T = unknown>(source: ObjectLoaderSource, options?: AssetLoadOptions): Promise<T>;
+    loadBinary(source: ObjectLoaderSource, options?: AssetLoadOptions): Promise<Buffer>;
+    protected resolveEncoding(extension: string, requested: AssetEncoding): Exclude<AssetEncoding, "auto">;
+    protected decode<T>(buffer: Buffer, encoding: Exclude<AssetEncoding, "auto">): T;
+    protected toFilePath(source: ObjectLoaderSource): string;
+}

package/lib/types/loader/config.d.cts

@@ -0,0 +1,84 @@
+import { ObjectLoader } from "./ObjectLoader.d.cts";
+import type { ObjectLoaderLoadOptions, ObjectLoaderOptions, ObjectLoaderSource } from "./types.d.cts";
+export type ConfigFormat = "auto" | "json" | "yaml" | "module";
+export type ConfigSource = ObjectLoaderSource | Readonly<Record<string, unknown>>;
+/**
+ * @summary Minimal global config registry.
+ * @description A process-wide key/value store that concrete loaders register
+ * loaded configuration into. It is intentionally small: register a value under a
+ * key, read it back, list it, snapshot it, and optionally freeze it once boot
+ * configuration is complete.
+ *
+ * `GlobalConfigRegistry.reset()` clears the contents but keeps the singleton
+ * instance, so a `globalConfig` reference captured at import time stays valid.
+ */
+export declare class GlobalConfigRegistry {
+    private static current;
+    private readonly store;
+    private frozen;
+    static get instance(): GlobalConfigRegistry;
+    static reset(): void;
+    register(key: string, value: unknown, options?: {
+        override?: boolean;
+    }): this;
+    get<T = unknown>(key: string): T | undefined;
+    require<T = unknown>(key: string): T;
+    has(key: string): boolean;
+    keys(): string[];
+    entries(): [string, unknown][];
+    snapshot(): Readonly<Record<string, unknown>>;
+    clear(): void;
+    freeze(): this;
+    get isFrozen(): boolean;
+}
+/** Process-wide config registry used by default. */
+export declare const globalConfig: GlobalConfigRegistry;
+export interface ConfigObjectLoaderOptions extends ObjectLoaderOptions {
+    /** Registry to register into. Defaults to {@link globalConfig}. */
+    readonly registry?: GlobalConfigRegistry;
+}
+export interface ConfigLoadOptions extends ObjectLoaderLoadOptions {
+    /** Explicit registry key. Defaults to the derived source name. */
+    readonly key?: string;
+    /** Optional namespace prefix for the derived registry key. */
+    readonly namespace?: string;
+    /** Replace an existing key instead of failing with a conflict. */
+    readonly override?: boolean;
+    /** Source format. `"auto"` detects from the source extension. */
+    readonly format?: ConfigFormat;
+    /** Registry to register into. Defaults to the loader registry. */
+    readonly registry?: GlobalConfigRegistry;
+}
+/**
+ * @summary Load config sources into the global config registry.
+ * @description Supports inline objects, `.json` files, optional `.yaml`/`.yml`
+ * files, and JS/TS modules. Loaded configs run through the shared hook
+ * pipeline, then register under a key so the rest of the system can read them
+ * from {@link globalConfig}.
+ */
+export declare class ConfigObjectLoader extends ObjectLoader {
+    readonly registry: GlobalConfigRegistry;
+    constructor(options?: ConfigObjectLoaderOptions);
+    protected createInstance(options: ObjectLoaderOptions): this;
+    /**
+     * @summary Load a config source, run hooks, and register it globally.
+     */
+    loadConfig<T = Readonly<Record<string, unknown>>>(source: ConfigSource, options?: ConfigLoadOptions): Promise<T>;
+    /**
+     * @summary Alias for {@link ConfigObjectLoader.loadConfig}.
+     */
+    loadAndRegister<T = Readonly<Record<string, unknown>>>(source: ConfigSource, options?: ConfigLoadOptions): Promise<T>;
+    register(key: string, value: unknown, options?: {
+        override?: boolean;
+        registry?: GlobalConfigRegistry;
+    }): this;
+    get<T = unknown>(key: string): T | undefined;
+    protected readConfig<T>(source: ConfigSource, format: ConfigFormat): Promise<T>;
+    protected detectFormat(source: string): Exclude<ConfigFormat, "auto">;
+    protected readText(source: string): Promise<string>;
+    protected loadYaml(): Promise<{
+        parse(input: string): unknown;
+    }>;
+    protected deriveKey(source: ConfigSource, namespace?: string): string;
+    protected describeSource(source: ConfigSource): string;
+}