@decaf-ts/integrations 0.10.8 → 0.11.0

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;
+}

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

@@ -0,0 +1,84 @@
+import { ObjectLoader } from "./ObjectLoader.d.mts";
+import type { ObjectLoaderLoadOptions, ObjectLoaderOptions, ObjectLoaderSource } from "./types.d.mts";
+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;
+}

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

@@ -1,8 +1,20 @@
+import type { Constructor } from "@decaf-ts/decoration";
 import { ObjectLoader } from "./ObjectLoader.d.cts";
-import type { ObjectLoaderLoadOptions, ObjectLoaderOptions, ObjectLoaderSource } from "./types.d.cts";
+import type { ObjectLoaderFamily, ObjectLoaderLoadOptions, ObjectLoaderOptions, ObjectLoaderSource } from "./types.d.cts";
+/**
+ * @summary Assert a loaded export is a constructor.
+ * @description Concrete class loaders (models, services, Nest controllers) only
+ * make sense for constructor exports. Throwing a decaf {@link ValidationError}
+ * keeps the failure inside the decaf error hierarchy instead of a raw `Error`.
+ */
+export declare function assertConstructor<T extends Constructor = Constructor>(value: unknown, family: ObjectLoaderFamily, source: string, exportName: string): T;
+/**
+ * Concrete model loader. Resolves a model constructor from a module source and
+ * runs the shared hook pipeline before returning it.
+ */
 export declare class ModelObjectLoader extends ObjectLoader {
     constructor(options?: ObjectLoaderOptions);
-    loadModel<T = unknown>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
+    loadModel<T extends Constructor = Constructor>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
 }
 export declare class AdapterObjectLoader extends ObjectLoader {
     constructor(options?: ObjectLoaderOptions);
@@ -12,9 +24,13 @@ export declare class RepositoryObjectLoader extends ObjectLoader {
     constructor(options?: ObjectLoaderOptions);
     loadRepository<T = unknown>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
 }
+/**
+ * Concrete service loader. Resolves a service constructor from a module source and
+ * runs the shared hook pipeline before returning it.
+ */
 export declare class ServiceObjectLoader extends ObjectLoader {
     constructor(options?: ObjectLoaderOptions);
-    loadService<T = unknown>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
+    loadService<T extends Constructor = Constructor>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
 }
 export declare class ControllerObjectLoader extends ObjectLoader {
     constructor(options?: ObjectLoaderOptions);
@@ -28,7 +44,3 @@ export declare class AngularComponentObjectLoader extends ObjectLoader {
     constructor(options?: ObjectLoaderOptions);
     loadComponent<T = unknown>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
 }
-export declare class GraphNodeObjectLoader extends ObjectLoader {
-    constructor(options?: ObjectLoaderOptions);
-    loadNode<T = unknown>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
-}

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

@@ -1,8 +1,20 @@
+import type { Constructor } from "@decaf-ts/decoration";
 import { ObjectLoader } from "./ObjectLoader.d.mts";
-import type { ObjectLoaderLoadOptions, ObjectLoaderOptions, ObjectLoaderSource } from "./types.d.mts";
+import type { ObjectLoaderFamily, ObjectLoaderLoadOptions, ObjectLoaderOptions, ObjectLoaderSource } from "./types.d.mts";
+/**
+ * @summary Assert a loaded export is a constructor.
+ * @description Concrete class loaders (models, services, Nest controllers) only
+ * make sense for constructor exports. Throwing a decaf {@link ValidationError}
+ * keeps the failure inside the decaf error hierarchy instead of a raw `Error`.
+ */
+export declare function assertConstructor<T extends Constructor = Constructor>(value: unknown, family: ObjectLoaderFamily, source: string, exportName: string): T;
+/**
+ * Concrete model loader. Resolves a model constructor from a module source and
+ * runs the shared hook pipeline before returning it.
+ */
 export declare class ModelObjectLoader extends ObjectLoader {
     constructor(options?: ObjectLoaderOptions);
-    loadModel<T = unknown>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
+    loadModel<T extends Constructor = Constructor>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
 }
 export declare class AdapterObjectLoader extends ObjectLoader {
     constructor(options?: ObjectLoaderOptions);
@@ -12,9 +24,13 @@ export declare class RepositoryObjectLoader extends ObjectLoader {
     constructor(options?: ObjectLoaderOptions);
     loadRepository<T = unknown>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
 }
+/**
+ * Concrete service loader. Resolves a service constructor from a module source and
+ * runs the shared hook pipeline before returning it.
+ */
 export declare class ServiceObjectLoader extends ObjectLoader {
     constructor(options?: ObjectLoaderOptions);
-    loadService<T = unknown>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
+    loadService<T extends Constructor = Constructor>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
 }
 export declare class ControllerObjectLoader extends ObjectLoader {
     constructor(options?: ObjectLoaderOptions);
@@ -28,7 +44,3 @@ export declare class AngularComponentObjectLoader extends ObjectLoader {
     constructor(options?: ObjectLoaderOptions);
     loadComponent<T = unknown>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
 }
-export declare class GraphNodeObjectLoader extends ObjectLoader {
-    constructor(options?: ObjectLoaderOptions);
-    loadNode<T = unknown>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
-}

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

@@ -8,3 +8,6 @@
 export * from "./types.d.cts";
 export * from "./ObjectLoader.d.cts";
 export * from "./families.d.cts";
+export * from "./assets.d.cts";
+export * from "./nest.d.cts";
+export * from "./config.d.cts";

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

@@ -8,3 +8,6 @@
 export * from "./types.d.mts";
 export * from "./ObjectLoader.d.mts";
 export * from "./families.d.mts";
+export * from "./assets.d.mts";
+export * from "./nest.d.mts";
+export * from "./config.d.mts";

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

@@ -0,0 +1,102 @@
+import type { Constructor } from "@decaf-ts/decoration";
+import { ObjectLoader } from "./ObjectLoader.d.cts";
+import type { ObjectLoaderLoadOptions, ObjectLoaderOptions, ObjectLoaderSource } from "./types.d.cts";
+/**
+ * @module integrations/loader/nest
+ * @summary Lazy NestJS loaders.
+ * @description Resolves NestJS controller classes and their route definitions
+ * from dynamically loaded modules. `@nestjs/common` and `reflect-metadata` are
+ * optional at runtime: both are dynamically imported/checked and the loaders
+ * degrade with a decaf {@link UnsupportedError} when they are unavailable.
+ *
+ * ## Tree-shaking
+ * The NestJS runtime is imported through a non-literal specifier so bundlers keep
+ * it as a runtime import and never inline it into the loader chunk. Nest
+ * applications already keep `@nestjs/common` in their entry graph, so the loader
+ * does not need a static reference of its own.
+ */
+/**
+ * Stable NestJS metadata keys. Declared as literals so this module never
+ * hard-depends on `@nestjs/common/constants` (a CommonJS-only subpath).
+ */
+export declare const NEST_PATH_METADATA = "path";
+export declare const NEST_METHOD_METADATA = "method";
+export declare const NEST_CONTROLLER_WATERMARK = "__controller__";
+export declare const NEST_MODULE_CONTROLLERS = "controllers";
+export declare const NEST_MODULE_IMPORTS = "imports";
+/**
+ * @summary Lazily resolve the NestJS runtime.
+ * @description Uses a non-literal dynamic import so bundlers do not inline or
+ * drop `@nestjs/common`. Throws a decaf {@link UnsupportedError} when the
+ * package cannot be resolved.
+ */
+export declare function loadNestCommon(): Promise<Readonly<Record<string, unknown>>>;
+/**
+ * A route definition resolved from a NestJS controller.
+ */
+export interface NestRouteDefinition {
+    /** Controller class that owns the handler. */
+    readonly controller: Constructor;
+    readonly controllerName: string;
+    readonly controllerPath?: string;
+    readonly propertyKey: string | symbol;
+    readonly handler: (...args: unknown[]) => unknown;
+    /** Numeric NestJS `RequestMethod` value. */
+    readonly method: number;
+    /** Human readable HTTP method name. */
+    readonly methodName: string;
+    /** Route path relative to the controller path. */
+    readonly path: string;
+    /** Controller path joined with the route path. */
+    readonly fullPath: string;
+}
+export interface NestControllerLoadOptions extends ObjectLoaderLoadOptions {
+    /** When true, `loadControllers` scans the module namespace recursively. */
+    readonly recursive?: boolean;
+}
+/**
+ * @summary Resolve NestJS controller classes from dynamically loaded modules.
+ * @description Extends the generic controller family with NestJS metadata
+ * awareness. Requires `@nestjs/common` and `reflect-metadata` at runtime.
+ */
+export declare class NestControllerObjectLoader extends ObjectLoader {
+    constructor(options?: ObjectLoaderOptions);
+    loadController<T extends Constructor = Constructor>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
+    /**
+     * @summary Load every controller exported by a module.
+     */
+    loadControllers<T extends Constructor = Constructor>(source: ObjectLoaderSource, options?: NestControllerLoadOptions): Promise<T[]>;
+    /**
+     * @summary Scan a NestJS module (or namespace) for controller classes.
+     * @description Synchronous metadata scan. Requires `reflect-metadata` but not
+     * `@nestjs/common`; call {@link loadNestCommon} first when the module must be
+     * imported.
+     */
+    collectControllers<T extends Constructor = Constructor>(value: unknown, recursive?: boolean): T[];
+    isController(value: unknown): value is Constructor;
+    getControllerPath(controller: Constructor): string | undefined;
+    protected assertController<T extends Constructor = Constructor>(value: unknown, source: string, exportName: string): T;
+    protected scanControllers<T extends Constructor = Constructor>(value: unknown, result: T[], seen: Set<unknown>, recursive: boolean): void;
+}
+/**
+ * @summary Resolve route definitions from dynamically loaded NestJS modules.
+ */
+export declare class NestRouteObjectLoader extends ObjectLoader {
+    constructor(options?: ObjectLoaderOptions);
+    /**
+     * @summary Load every route declared by a controller exported from a module.
+     */
+    loadControllerRoutes(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<NestRouteDefinition[]>;
+    /**
+     * @summary Load every route declared by every controller in a module.
+     */
+    loadRoutes(source: ObjectLoaderSource, options?: ObjectLoaderLoadOptions): Promise<NestRouteDefinition[]>;
+    /**
+     * @summary Extract route definitions from a controller class.
+     * @description Synchronous metadata scan. Requires `reflect-metadata`.
+     */
+    getRoutes(controller: Constructor, controllerPath?: string): NestRouteDefinition[];
+    isController(value: unknown): value is Constructor;
+    getControllerPath(controller: Constructor): string | undefined;
+    protected assertController(value: unknown, source: string, exportName: string): Constructor;
+}

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

@@ -0,0 +1,102 @@
+import type { Constructor } from "@decaf-ts/decoration";
+import { ObjectLoader } from "./ObjectLoader.d.mts";
+import type { ObjectLoaderLoadOptions, ObjectLoaderOptions, ObjectLoaderSource } from "./types.d.mts";
+/**
+ * @module integrations/loader/nest
+ * @summary Lazy NestJS loaders.
+ * @description Resolves NestJS controller classes and their route definitions
+ * from dynamically loaded modules. `@nestjs/common` and `reflect-metadata` are
+ * optional at runtime: both are dynamically imported/checked and the loaders
+ * degrade with a decaf {@link UnsupportedError} when they are unavailable.
+ *
+ * ## Tree-shaking
+ * The NestJS runtime is imported through a non-literal specifier so bundlers keep
+ * it as a runtime import and never inline it into the loader chunk. Nest
+ * applications already keep `@nestjs/common` in their entry graph, so the loader
+ * does not need a static reference of its own.
+ */
+/**
+ * Stable NestJS metadata keys. Declared as literals so this module never
+ * hard-depends on `@nestjs/common/constants` (a CommonJS-only subpath).
+ */
+export declare const NEST_PATH_METADATA = "path";
+export declare const NEST_METHOD_METADATA = "method";
+export declare const NEST_CONTROLLER_WATERMARK = "__controller__";
+export declare const NEST_MODULE_CONTROLLERS = "controllers";
+export declare const NEST_MODULE_IMPORTS = "imports";
+/**
+ * @summary Lazily resolve the NestJS runtime.
+ * @description Uses a non-literal dynamic import so bundlers do not inline or
+ * drop `@nestjs/common`. Throws a decaf {@link UnsupportedError} when the
+ * package cannot be resolved.
+ */
+export declare function loadNestCommon(): Promise<Readonly<Record<string, unknown>>>;
+/**
+ * A route definition resolved from a NestJS controller.
+ */
+export interface NestRouteDefinition {
+    /** Controller class that owns the handler. */
+    readonly controller: Constructor;
+    readonly controllerName: string;
+    readonly controllerPath?: string;
+    readonly propertyKey: string | symbol;
+    readonly handler: (...args: unknown[]) => unknown;
+    /** Numeric NestJS `RequestMethod` value. */
+    readonly method: number;
+    /** Human readable HTTP method name. */
+    readonly methodName: string;
+    /** Route path relative to the controller path. */
+    readonly path: string;
+    /** Controller path joined with the route path. */
+    readonly fullPath: string;
+}
+export interface NestControllerLoadOptions extends ObjectLoaderLoadOptions {
+    /** When true, `loadControllers` scans the module namespace recursively. */
+    readonly recursive?: boolean;
+}
+/**
+ * @summary Resolve NestJS controller classes from dynamically loaded modules.
+ * @description Extends the generic controller family with NestJS metadata
+ * awareness. Requires `@nestjs/common` and `reflect-metadata` at runtime.
+ */
+export declare class NestControllerObjectLoader extends ObjectLoader {
+    constructor(options?: ObjectLoaderOptions);
+    loadController<T extends Constructor = Constructor>(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<T>;
+    /**
+     * @summary Load every controller exported by a module.
+     */
+    loadControllers<T extends Constructor = Constructor>(source: ObjectLoaderSource, options?: NestControllerLoadOptions): Promise<T[]>;
+    /**
+     * @summary Scan a NestJS module (or namespace) for controller classes.
+     * @description Synchronous metadata scan. Requires `reflect-metadata` but not
+     * `@nestjs/common`; call {@link loadNestCommon} first when the module must be
+     * imported.
+     */
+    collectControllers<T extends Constructor = Constructor>(value: unknown, recursive?: boolean): T[];
+    isController(value: unknown): value is Constructor;
+    getControllerPath(controller: Constructor): string | undefined;
+    protected assertController<T extends Constructor = Constructor>(value: unknown, source: string, exportName: string): T;
+    protected scanControllers<T extends Constructor = Constructor>(value: unknown, result: T[], seen: Set<unknown>, recursive: boolean): void;
+}
+/**
+ * @summary Resolve route definitions from dynamically loaded NestJS modules.
+ */
+export declare class NestRouteObjectLoader extends ObjectLoader {
+    constructor(options?: ObjectLoaderOptions);
+    /**
+     * @summary Load every route declared by a controller exported from a module.
+     */
+    loadControllerRoutes(source: ObjectLoaderSource, exportName?: string, options?: ObjectLoaderLoadOptions): Promise<NestRouteDefinition[]>;
+    /**
+     * @summary Load every route declared by every controller in a module.
+     */
+    loadRoutes(source: ObjectLoaderSource, options?: ObjectLoaderLoadOptions): Promise<NestRouteDefinition[]>;
+    /**
+     * @summary Extract route definitions from a controller class.
+     * @description Synchronous metadata scan. Requires `reflect-metadata`.
+     */
+    getRoutes(controller: Constructor, controllerPath?: string): NestRouteDefinition[];
+    isController(value: unknown): value is Constructor;
+    getControllerPath(controller: Constructor): string | undefined;
+    protected assertController(value: unknown, source: string, exportName: string): Constructor;
+}