@decaf-ts/integrations 0.10.8 → 0.12.0

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

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

@@ -1,22 +1,48 @@
 import type { Constructor } from "@decaf-ts/decoration";
-export type ObjectLoaderFamily = "generic" | "model" | "adapter" | "repository" | "service" | "controller" | "environment" | "component" | "node";
+export type ObjectLoaderFamily = "generic" | "model" | "adapter" | "repository" | "service" | "controller" | "environment" | "component" | "node" | "asset" | "route" | "config";
 export type ObjectLoaderSource = string | URL;
 export type MaybePromise<T> = T | Promise<T>;
+/**
+ * @summary Load lifecycle phase a hook is invoked in.
+ * @description The base loader runs `beforeResolve` hooks against the imported
+ * module namespace and `afterResolve` hooks against the selected export. The phase
+ * is optional on the context for backward compatibility, but the base loader always
+ * populates it.
+ */
+export type ObjectLoaderHookPhase = "beforeResolve" | "afterResolve";
 export interface ObjectLoaderHookContext {
     readonly family: ObjectLoaderFamily;
     readonly source: string;
     readonly exportName: string;
     readonly module: Readonly<Record<string, unknown>>;
     readonly loaderName: string;
+    /**
+     * The phase this hook runs in. `beforeResolve` hooks receive the imported
+     * module namespace, `afterResolve` hooks receive the resolved export.
+     */
+    readonly phase?: ObjectLoaderHookPhase;
+    /**
+     * Free-form metadata a concrete loader attaches for its hooks (asset format,
+     * config key, controller count, ...).
+     */
+    readonly metadata?: Readonly<Record<string, unknown>>;
 }
 export type ObjectLoaderHook = (value: unknown, context: ObjectLoaderHookContext) => MaybePromise<unknown | void>;
 export interface ObjectLoaderOptions {
     readonly family?: ObjectLoaderFamily;
+    /** Hooks run against the resolved export (backward compatible default). */
     readonly hooks?: readonly ObjectLoaderHook[];
+    /** Hooks run against the imported module namespace before export selection. */
+    readonly beforeResolveHooks?: readonly ObjectLoaderHook[];
     readonly defaultExportName?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
 }
 export interface ObjectLoaderLoadOptions {
+    /** Per-call hooks run against the resolved export. */
     readonly hooks?: readonly ObjectLoaderHook[];
+    /** Per-call hooks run against the imported module namespace. */
+    readonly beforeResolveHooks?: readonly ObjectLoaderHook[];
+    readonly metadata?: Readonly<Record<string, unknown>>;
 }
 export interface ObjectLoaderExportSelection {
     readonly exportName?: string;

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

@@ -1,22 +1,48 @@
 import type { Constructor } from "@decaf-ts/decoration";
-export type ObjectLoaderFamily = "generic" | "model" | "adapter" | "repository" | "service" | "controller" | "environment" | "component" | "node";
+export type ObjectLoaderFamily = "generic" | "model" | "adapter" | "repository" | "service" | "controller" | "environment" | "component" | "node" | "asset" | "route" | "config";
 export type ObjectLoaderSource = string | URL;
 export type MaybePromise<T> = T | Promise<T>;
+/**
+ * @summary Load lifecycle phase a hook is invoked in.
+ * @description The base loader runs `beforeResolve` hooks against the imported
+ * module namespace and `afterResolve` hooks against the selected export. The phase
+ * is optional on the context for backward compatibility, but the base loader always
+ * populates it.
+ */
+export type ObjectLoaderHookPhase = "beforeResolve" | "afterResolve";
 export interface ObjectLoaderHookContext {
     readonly family: ObjectLoaderFamily;
     readonly source: string;
     readonly exportName: string;
     readonly module: Readonly<Record<string, unknown>>;
     readonly loaderName: string;
+    /**
+     * The phase this hook runs in. `beforeResolve` hooks receive the imported
+     * module namespace, `afterResolve` hooks receive the resolved export.
+     */
+    readonly phase?: ObjectLoaderHookPhase;
+    /**
+     * Free-form metadata a concrete loader attaches for its hooks (asset format,
+     * config key, controller count, ...).
+     */
+    readonly metadata?: Readonly<Record<string, unknown>>;
 }
 export type ObjectLoaderHook = (value: unknown, context: ObjectLoaderHookContext) => MaybePromise<unknown | void>;
 export interface ObjectLoaderOptions {
     readonly family?: ObjectLoaderFamily;
+    /** Hooks run against the resolved export (backward compatible default). */
     readonly hooks?: readonly ObjectLoaderHook[];
+    /** Hooks run against the imported module namespace before export selection. */
+    readonly beforeResolveHooks?: readonly ObjectLoaderHook[];
     readonly defaultExportName?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
 }
 export interface ObjectLoaderLoadOptions {
+    /** Per-call hooks run against the resolved export. */
     readonly hooks?: readonly ObjectLoaderHook[];
+    /** Per-call hooks run against the imported module namespace. */
+    readonly beforeResolveHooks?: readonly ObjectLoaderHook[];
+    readonly metadata?: Readonly<Record<string, unknown>>;
 }
 export interface ObjectLoaderExportSelection {
     readonly exportName?: string;

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

@@ -6,3 +6,4 @@ export * from "./types.d.cts";
 export * from "./utils.d.cts";
 export * from "./models/index.d.cts";
 export * from "./services/index.d.cts";
+export * from "./rls/index.d.cts";

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

@@ -6,3 +6,4 @@ export * from "./types.d.mts";
 export * from "./utils.d.mts";
 export * from "./models/index.d.mts";
 export * from "./services/index.d.mts";
+export * from "./rls/index.d.mts";

package/lib/types/namespaces/models/credential.model.d.cts

@@ -0,0 +1,23 @@
+import { CredentialProvider } from "../types.d.cts";
+import { AuthorizationModel } from "./authorization-model.d.cts";
+import { Tenant } from "./tenant.model.d.cts";
+import { OrgUnit } from "./org-unit.model.d.cts";
+import { Principal } from "./principal.model.d.cts";
+export declare class Credential extends AuthorizationModel {
+    id: string;
+    tenant: Tenant | string;
+    orgUnit?: OrgUnit | string;
+    owner?: Principal | string;
+    name: string;
+    credentialType: string;
+    secretName: string;
+    provider: CredentialProvider;
+    description?: string;
+    enabled: boolean;
+    metadata?: Record<string, unknown>;
+    expiresAt?: Date;
+    lastUsedAt?: Date;
+    createdAt: Date;
+    updatedAt: Date;
+    constructor(data?: unknown);
+}

package/lib/types/namespaces/models/credential.model.d.mts

@@ -0,0 +1,23 @@
+import { CredentialProvider } from "../types.d.mts";
+import { AuthorizationModel } from "./authorization-model.d.mts";
+import { Tenant } from "./tenant.model.d.mts";
+import { OrgUnit } from "./org-unit.model.d.mts";
+import { Principal } from "./principal.model.d.mts";
+export declare class Credential extends AuthorizationModel {
+    id: string;
+    tenant: Tenant | string;
+    orgUnit?: OrgUnit | string;
+    owner?: Principal | string;
+    name: string;
+    credentialType: string;
+    secretName: string;
+    provider: CredentialProvider;
+    description?: string;
+    enabled: boolean;
+    metadata?: Record<string, unknown>;
+    expiresAt?: Date;
+    lastUsedAt?: Date;
+    createdAt: Date;
+    updatedAt: Date;
+    constructor(data?: unknown);
+}

package/lib/types/namespaces/models/index.d.cts

@@ -19,3 +19,4 @@ export * from "./protected-resource.model.d.cts";
 export * from "./resource-grant.model.d.cts";
 export * from "./effective-permission.model.d.cts";
 export * from "./storage-binding.model.d.cts";
+export * from "./credential.model.d.cts";

package/lib/types/namespaces/models/index.d.mts

@@ -19,3 +19,4 @@ export * from "./protected-resource.model.d.mts";
 export * from "./resource-grant.model.d.mts";
 export * from "./effective-permission.model.d.mts";
 export * from "./storage-binding.model.d.mts";
+export * from "./credential.model.d.mts";

package/lib/types/namespaces/rls/index.d.cts

@@ -0,0 +1,10 @@
+/**
+ * @module integrations/namespaces/rls
+ * @summary Namespace row-level-security template, bootstrap service, and session helpers.
+ */
+export * from "./rls.constants.d.cts";
+export * from "./rls.types.d.cts";
+export * from "./rls.template.d.cts";
+export * from "./rls-bootstrap.service.d.cts";
+export * from "./principal-resolver.d.cts";
+export * from "./session-binding.d.cts";

package/lib/types/namespaces/rls/index.d.mts

@@ -0,0 +1,10 @@
+/**
+ * @module integrations/namespaces/rls
+ * @summary Namespace row-level-security template, bootstrap service, and session helpers.
+ */
+export * from "./rls.constants.d.mts";
+export * from "./rls.types.d.mts";
+export * from "./rls.template.d.mts";
+export * from "./rls-bootstrap.service.d.mts";
+export * from "./principal-resolver.d.mts";
+export * from "./session-binding.d.mts";

package/lib/types/namespaces/rls/principal-resolver.d.cts

@@ -0,0 +1,47 @@
+/**
+ * @description Minimal SQL client contract for the principal-subject resolver
+ * @summary Structural subset consumed by `resolvePrincipalForSubject`; any
+ * privileged client able to run parameterized queries (for example a `pg`
+ * `Client` or a TypeORM `QueryRunner`) satisfies it. The resolver requires a
+ * privileged auth-prime/service-role client because the helper function is
+ * `REVOKE`d from `PUBLIC`.
+ * @interface PrincipalSubjectQueryClient
+ */
+export interface PrincipalSubjectQueryClient {
+    /**
+     * @description Executes a parameterized SQL statement
+     * @param {string} sql - The SQL text with positional parameters.
+     * @param {any[]} [values] - Positional parameter values.
+     * @returns {Promise<unknown>} The raw driver result (a rows array or an object with a `rows` array).
+     */
+    query(sql: string, values?: any[]): Promise<unknown>;
+}
+/**
+ * @description Pattern enforcing UUID shape on resolved principals and tenant ids
+ * @summary Used to validate the optional `tenantId` argument and to fail
+ * closed on driver results that are not UUID-shaped strings.
+ * @const PRINCIPAL_UUID_PATTERN
+ */
+export declare const PRINCIPAL_UUID_PATTERN: RegExp;
+/**
+ * @description Resolves the principal UUID for an authenticated subject
+ * @summary Calls the `SECURITY DEFINER` helper
+ * `app_rls_principal_for_subject(text, uuid)` through the given privileged
+ * client with fully parameterized SQL. Fails closed: an empty subject, an
+ * ambiguous subject (the helper returns `NULL` unless exactly one principal
+ * matches), and driver results that are not UUID-shaped strings all resolve to
+ * `undefined` rather than throwing, so callers handle "no principal" uniformly
+ * by denying. Requires a privileged auth-prime/service-role client; this
+ * resolver must never be invoked with an application session client.
+ * @function resolvePrincipalForSubject
+ * @param {PrincipalSubjectQueryClient} client - Privileged client used to run the helper query.
+ * @param {string} subject - The authenticated subject id (`principals.subject_id`).
+ * @param {string} [tenantId] - Optional tenant UUID scoping the lookup.
+ * @returns {Promise<string | undefined>} The principal UUID, or `undefined` when none can be resolved.
+ * @throws {ValidationError} When the client is not query-capable, or `tenantId` is provided but not a UUID.
+ * @example
+ * const principalId = await resolvePrincipalForSubject(pgClient, authSubject, tenantId);
+ * if (!principalId)
+ *   throw new Error("No principal for subject"); // fail closed
+ */
+export declare function resolvePrincipalForSubject(client: PrincipalSubjectQueryClient, subject: string, tenantId?: string): Promise<string | undefined>;