@decaf-ts/for-nest 0.11.2 → 0.12.0

package/lib/types/decaf-model/FromModelController.d.mts

@@ -1,61 +1,41 @@
 import { ModelService, type Repo } from "@decaf-ts/core";
 import { Model, ModelConstructor } from "@decaf-ts/decorator-validation";
-import { type DecafModelRoute } from "./decorators/index.d.mts";
+import { type DecafApiProperty } from "./decorators/index.d.mts";
 import { ControllerConstructor } from "./types.d.mts";
 import "../overrides";
-/**
- * @description
- * Factory and utilities for generating dynamic NestJS controllers from Decaf {@link Model} definitions.
- *
- * @summary
- * The `FromModelController` class provides the infrastructure necessary to automatically generate
- * strongly-typed CRUD controllers based on a given {@link ModelConstructor}. It inspects metadata from
- * the model, derives route paths, parameters, and generates a dynamic controller class at runtime with
- * full support for querying, creation, update, and deletion of model entities through a {@link Repo}.
- *
- * @template T The {@link Model} type associated with the generated controller.
- *
- * @param ModelClazz The model class to generate the controller from.
- *
- * @class FromModelController
- *
- * @example
- * ```ts
- * // Given a Decaf Model:
- * class User extends Model<User> {
- *   id!: string;
- *   name!: string;
- * }
- *
- * // Register controller:
- * const UserController = FromModelController.create(User);
- *
- * // NestJS will expose:
- * // POST   /user
- * // GET    /user/:id
- * // GET    /user/query/:method
- * // PUT    /user/:id
- * // DELETE /user/:id
- * ```
- *
- * @mermaid
- * sequenceDiagram
- *     participant Client
- *     participant Controller
- *     participant Repo
- *     participant DB
- *
- *     Client->>Controller: HTTP Request
- *     Controller->>Repo: Resolve repository for Model
- *     Repo->>DB: Execute DB operation
- *     DB-->>Repo: DB Result
- *     Repo-->>Controller: Model Instance(s)
- *     Controller-->>Client: JSON Response
- */
+import { type ModelControllerFactoryConfig } from "@decaf-ts/for-http/server";
 export declare class FromModelController {
     private static readonly log;
+    private static toDecafError;
     static getPersistence<T extends Model<boolean>>(ModelClazz: ModelConstructor<T>): Repo<T> | ModelService<T>;
     static createQueryRoutesFromRepository<T extends Model<boolean>>(persistence: Repo<T> | ModelService<T>, prefix?: string): ControllerConstructor<T>;
-    static create<T extends Model<any>>(ModelConstr: ModelConstructor<T>): any;
-    static getRouteParametersFromModel<T extends Model<any>>(ModelClazz: ModelConstructor<T>): DecafModelRoute;
+    static create<T extends Model<any>>(ModelConstr: ModelConstructor<T>, moduleConfigOverrides?: Record<string, ModelControllerFactoryConfig>, globalDefaults?: Partial<ModelControllerFactoryConfig>): ControllerConstructor<T>;
+    static getRouteParametersFromModel<T extends Model<any>>(ModelClazz: ModelConstructor<T>): {
+        path: string;
+        description: string;
+        apiProperties: DecafApiProperty[];
+        getPK: (...params: Array<string | number>) => string;
+    };
+    private static routeParamDecorators;
+    private static defineMethod;
+    private static applyDecorators;
+    private static matchRoute;
+    private static createRegistration;
+    private static statementMethodName;
+    private static statementShortcutParams;
+    private static complexQueryParams;
+    private static createComplexQueryHandler;
+    private static extractQueryArgs;
+    private static normalizeQueryArgs;
+    private static createCreateDecorators;
+    private static bulkCreateDecorators;
+    private static bulkReadDecorators;
+    private static bulkUpdateDecorators;
+    private static bulkDeleteDecorators;
+    private static readDecorators;
+    private static updateDecorators;
+    private static deleteDecorators;
+    private static statementDecorators;
+    private static statementShortcutDecorators;
+    private static getQueryDecorators;
 }

package/lib/types/decaf-model/decorators/ApiOperationFromModel.d.cts

@@ -1,4 +1,3 @@
-import { CrudOperations } from "@decaf-ts/db-decorators";
 import { ModelConstructor } from "@decaf-ts/decorator-validation";
 import { HttpVerbs } from "./types.d.cts";
 /**
@@ -9,7 +8,6 @@ import { HttpVerbs } from "./types.d.cts";
  * @return {boolean} `true` when the operation is explicitly blocked by the model's handler; otherwise `false`.
  * @function isOperationBlocked
  */
-export declare function isOperationBlocked(ModelConstructor: ModelConstructor<any>, op: CrudOperations): boolean;
 /**
  * @description Conditionally applies an HTTP method decorator for a given model and verb, hiding the endpoint in Swagger (and not registering the route) when the model blocks that CRUD operation.
  * @summary Maps an HTTP verb to its corresponding `CrudOperations` key and Nest HTTP decorator (`@Get`, `@Post`, etc.). It checks `isOperationBlocked(ModelConstructor, crudOp)` and, if blocked, applies only `@ApiExcludeEndpoint()` (Swagger-hidden, no Nest route). If permitted, it applies the appropriate HTTP decorator with the optional `path`.

package/lib/types/decaf-model/decorators/ApiOperationFromModel.d.mts

@@ -1,4 +1,3 @@
-import { CrudOperations } from "@decaf-ts/db-decorators";
 import { ModelConstructor } from "@decaf-ts/decorator-validation";
 import { HttpVerbs } from "./types.d.mts";
 /**
@@ -9,7 +8,6 @@ import { HttpVerbs } from "./types.d.mts";
  * @return {boolean} `true` when the operation is explicitly blocked by the model's handler; otherwise `false`.
  * @function isOperationBlocked
  */
-export declare function isOperationBlocked(ModelConstructor: ModelConstructor<any>, op: CrudOperations): boolean;
 /**
  * @description Conditionally applies an HTTP method decorator for a given model and verb, hiding the endpoint in Swagger (and not registering the route) when the model blocks that CRUD operation.
  * @summary Maps an HTTP verb to its corresponding `CrudOperations` key and Nest HTTP decorator (`@Get`, `@Post`, etc.). It checks `isOperationBlocked(ModelConstructor, crudOp)` and, if blocked, applies only `@ApiExcludeEndpoint()` (Swagger-hidden, no Nest route). If permitted, it applies the appropriate HTTP decorator with the optional `path`.

package/lib/types/decaf-model/decorators/controller-config.d.cts

@@ -0,0 +1,18 @@
+import type { ModelControllerFactoryConfig } from "@decaf-ts/for-http/server";
+/**
+ * Class decorator that attaches a {@link ModelControllerFactoryConfig} to a Model,
+ * so `FromModelController.create()` can pass it to `ModelControllerFactory.create()`.
+ *
+ * The per-model config can be overridden by the module-level `controllerConfig`
+ * option in `DecafModuleOptions`.
+ *
+ * @example
+ * ```ts
+ * @controllerConfig({ allowGroupingQueries: true, allowBulkStatement: { create: true, read: true, update: false, delete: true } })
+ * @model()
+ * class Order extends Model<Order> { ... }
+ * ```
+ *
+ * @param config - Factory configuration knobs (allowStatementlessQuery, allowGroupingQueries, allowBulkStatement).
+ */
+export declare function controllerConfig(config: ModelControllerFactoryConfig): (target: any) => any;

package/lib/types/decaf-model/decorators/controller-config.d.mts

@@ -0,0 +1,18 @@
+import type { ModelControllerFactoryConfig } from "@decaf-ts/for-http/server";
+/**
+ * Class decorator that attaches a {@link ModelControllerFactoryConfig} to a Model,
+ * so `FromModelController.create()` can pass it to `ModelControllerFactory.create()`.
+ *
+ * The per-model config can be overridden by the module-level `controllerConfig`
+ * option in `DecafModuleOptions`.
+ *
+ * @example
+ * ```ts
+ * @controllerConfig({ allowGroupingQueries: true, allowBulkStatement: { create: true, read: true, update: false, delete: true } })
+ * @model()
+ * class Order extends Model<Order> { ... }
+ * ```
+ *
+ * @param config - Factory configuration knobs (allowStatementlessQuery, allowGroupingQueries, allowBulkStatement).
+ */
+export declare function controllerConfig(config: ModelControllerFactoryConfig): (target: any) => any;

package/lib/types/decaf-model/decorators/decorators.d.cts

@@ -1,29 +1 @@
-import { Constructor } from "@decaf-ts/decoration";
-/**
- * A decorator function that applies authentication and authorization metadata to a NestJS controller or method.
- *
- * @param model - The model name or constructor function for the resource being accessed.
- * If a string is provided, it is used as the resource name.
- * If a constructor function is provided, its name is used as the resource name.
- *
- * @returns - A function that applies the authentication and authorization decorators to the target.
- *
- * @example
- * ```typescript
- * @Controller('users')
- * @Auth('User')
- * export class UsersController {
- *   // ...
- * }
- * ```
- *
- * @example
- * ```typescript
- * @Controller('users')
- * @Auth(User)
- * export class UsersController {
- *   // ...
- * }
- * ```
- */
-export declare function Auth(model?: string | Constructor): <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+export { Auth } from "../../auth/decorators.d.cts";

package/lib/types/decaf-model/decorators/decorators.d.mts

@@ -1,29 +1 @@
-import { Constructor } from "@decaf-ts/decoration";
-/**
- * A decorator function that applies authentication and authorization metadata to a NestJS controller or method.
- *
- * @param model - The model name or constructor function for the resource being accessed.
- * If a string is provided, it is used as the resource name.
- * If a constructor function is provided, its name is used as the resource name.
- *
- * @returns - A function that applies the authentication and authorization decorators to the target.
- *
- * @example
- * ```typescript
- * @Controller('users')
- * @Auth('User')
- * export class UsersController {
- *   // ...
- * }
- * ```
- *
- * @example
- * ```typescript
- * @Controller('users')
- * @Auth(User)
- * export class UsersController {
- *   // ...
- * }
- * ```
- */
-export declare function Auth(model?: string | Constructor): <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+export { Auth } from "../../auth/decorators.d.mts";

package/lib/types/decaf-model/decorators/expose.d.cts

@@ -0,0 +1 @@
+export declare function expose(...flavours: string[]): (target: any) => any;

package/lib/types/decaf-model/decorators/expose.d.mts

@@ -0,0 +1 @@
+export declare function expose(...flavours: string[]): (target: any) => any;

package/lib/types/decaf-model/decorators/index.d.cts

@@ -5,3 +5,4 @@ export * from "./DecafBody.d.cts";
 export * from "./DecafParams.d.cts";
 export * from "./utils.d.cts";
 export * from "./decorators.d.cts";
+export * from "./controller-config.d.cts";

package/lib/types/decaf-model/decorators/index.d.mts

@@ -5,3 +5,4 @@ export * from "./DecafBody.d.mts";
 export * from "./DecafParams.d.mts";
 export * from "./utils.d.mts";
 export * from "./decorators.d.mts";
+export * from "./controller-config.d.mts";

package/lib/types/decaf-model/decorators/types.d.cts

@@ -1,23 +1,10 @@
-export type HttpVerbs = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-export type DecafApiProperty = {
-    name: string;
-    description?: string;
-    required?: boolean;
-    type?: any;
-};
-export type DecafModelRoute = {
-    path: string;
-    description?: string;
-    apiProperties: DecafApiProperty[];
-    getPK: (...args: Array<string | number>) => string;
-};
-export type DecafParamProps = {
-    raw: Record<string, string | number>;
-    keysInOrder: Array<string>;
-    valuesInOrder: Array<string | number>;
-};
+import type { HttpVerbs as ServerHttpVerbs, ServerApiProperty, ServerModelRoute, ServerParamProps, ServerRouteDecOptions } from "@decaf-ts/for-http/server";
+export type HttpVerbs = ServerHttpVerbs;
+export type DecafApiProperty = ServerApiProperty;
+export type DecafModelRoute = ServerModelRoute;
+export type DecafParamProps = ServerParamProps;
 export interface DecafRouteDecOptions {
-    path: string;
-    httpMethod: HttpVerbs;
-    handler: PropertyDescriptor;
+    path: ServerRouteDecOptions["path"];
+    httpMethod: ServerRouteDecOptions["httpMethod"];
+    handler: ServerRouteDecOptions["handler"];
 }

package/lib/types/decaf-model/decorators/types.d.mts

@@ -1,23 +1,10 @@
-export type HttpVerbs = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-export type DecafApiProperty = {
-    name: string;
-    description?: string;
-    required?: boolean;
-    type?: any;
-};
-export type DecafModelRoute = {
-    path: string;
-    description?: string;
-    apiProperties: DecafApiProperty[];
-    getPK: (...args: Array<string | number>) => string;
-};
-export type DecafParamProps = {
-    raw: Record<string, string | number>;
-    keysInOrder: Array<string>;
-    valuesInOrder: Array<string | number>;
-};
+import type { HttpVerbs as ServerHttpVerbs, ServerApiProperty, ServerModelRoute, ServerParamProps, ServerRouteDecOptions } from "@decaf-ts/for-http/server";
+export type HttpVerbs = ServerHttpVerbs;
+export type DecafApiProperty = ServerApiProperty;
+export type DecafModelRoute = ServerModelRoute;
+export type DecafParamProps = ServerParamProps;
 export interface DecafRouteDecOptions {
-    path: string;
-    httpMethod: HttpVerbs;
-    handler: PropertyDescriptor;
+    path: ServerRouteDecOptions["path"];
+    httpMethod: ServerRouteDecOptions["httpMethod"];
+    handler: ServerRouteDecOptions["handler"];
 }

package/lib/types/decaf-model/index.d.cts

@@ -1,3 +1,11 @@
-export * from "./decorators/index.d.cts";
-export * from "./DecafModelModule.d.cts";
-export * from "./FromModelController.d.cts";
+export { ApiOperationFromModel, BulkApiOperationFromModel, } from "./decorators/ApiOperationFromModel.d.cts";
+export { ApiParamsFromModel } from "./decorators/ApiParamsFromModel.d.cts";
+export { DecafBody } from "./decorators/DecafBody.d.cts";
+export { DecafParams } from "./decorators/DecafParams.d.cts";
+export type { DecafParamProps } from "./decorators/types.d.cts";
+export { expose } from "./decorators/expose.d.cts";
+export { controllerConfig } from "./decorators/controller-config.d.cts";
+export { Auth } from "./decorators/decorators.d.cts";
+export { applyApiDecorators, createRouteHandler, defineRouteMethod, getApiDecorators, resolvePersistenceMethod, } from "./utils.d.cts";
+export { getModuleFor } from "./DecafModelModule.d.cts";
+export { FromModelController } from "./FromModelController.d.cts";

package/lib/types/decaf-model/index.d.mts

@@ -1,3 +1,11 @@
-export * from "./decorators/index.d.mts";
-export * from "./DecafModelModule.d.mts";
-export * from "./FromModelController.d.mts";
+export { ApiOperationFromModel, BulkApiOperationFromModel, } from "./decorators/ApiOperationFromModel.d.mts";
+export { ApiParamsFromModel } from "./decorators/ApiParamsFromModel.d.mts";
+export { DecafBody } from "./decorators/DecafBody.d.mts";
+export { DecafParams } from "./decorators/DecafParams.d.mts";
+export type { DecafParamProps } from "./decorators/types.d.mts";
+export { expose } from "./decorators/expose.d.mts";
+export { controllerConfig } from "./decorators/controller-config.d.mts";
+export { Auth } from "./decorators/decorators.d.mts";
+export { applyApiDecorators, createRouteHandler, defineRouteMethod, getApiDecorators, resolvePersistenceMethod, } from "./utils.d.mts";
+export { getModuleFor } from "./DecafModelModule.d.mts";
+export { FromModelController } from "./FromModelController.d.mts";

package/lib/types/decaf-model/utils.d.cts

@@ -1,5 +1,6 @@
 import { type DecoratorBundle } from "./types.d.cts";
-import { type DecafParamProps, HttpVerbs } from "./decorators/index.d.cts";
+import { type DecafParamProps } from "./decorators/index.d.cts";
+import type { HttpVerbs } from "./decorators/types.d.cts";
 import { DirectionLimitOffset, ModelService, Repo } from "@decaf-ts/core";
 import { Model } from "@decaf-ts/decorator-validation";
 import { DecafModelController } from "../controllers.d.cts";

package/lib/types/decaf-model/utils.d.mts

@@ -1,5 +1,6 @@
 import { type DecoratorBundle } from "./types.d.mts";
-import { type DecafParamProps, HttpVerbs } from "./decorators/index.d.mts";
+import { type DecafParamProps } from "./decorators/index.d.mts";
+import type { HttpVerbs } from "./decorators/types.d.mts";
 import { DirectionLimitOffset, ModelService, Repo } from "@decaf-ts/core";
 import { Model } from "@decaf-ts/decorator-validation";
 import { DecafModelController } from "../controllers.d.mts";

package/lib/types/decorators.d.cts

@@ -0,0 +1,35 @@
+import { Constructor } from "@decaf-ts/decoration";
+export type DecafFactoryProvider = {
+    provide: string;
+    useFactory: () => unknown;
+};
+/**
+ * @description Drains the providers registered by {@link Service}/{@link Repository} usages.
+ * @summary Consumed by {@link DecafCoreModule.forRoot} to wire the tokens that those parameter
+ * decorators reference back into Nest's DI container, since a parameter decorator alone cannot
+ * supply a provider.
+ */
+export declare function getRegisteredDecafProviders(): DecafFactoryProvider[];
+/**
+ * @description Constructor parameter decorator that injects a decaf service.
+ * @summary Translates decaf's service resolution APIs into a Nest `@Inject()` call:
+ * - `@Service(SomeModel)` injects the matching `@service(SomeModel)` decaf service when one is
+ *   registered; otherwise it falls back to the `ModelService<SomeModel>` singleton
+ *   (via {@link ModelService.forModel}).
+ * - `@Service(SomeServiceClass)` or `@Service("alias")` injects the matching `@service()`-decorated
+ *   decaf {@link CoreService} (via {@link CoreService.get}).
+ * - `@Service()` infers the parameter's type from emitted constructor metadata and resolves it the
+ *   same way, provided the parameter is typed as a concrete class (generics like `ModelService<X>`
+ *   are erased at runtime, so the model-service form always requires an explicit argument).
+ * @param key the model class, service class, or alias to resolve. Omit to infer from the parameter type.
+ */
+export declare function Service(key?: string | Constructor<any>): ParameterDecorator;
+/**
+ * @description Constructor parameter decorator that injects a decaf {@link CoreRepository} for `model`.
+ * @summary Unlike {@link Service}, `model` is always treated as a Model class: the same class passed
+ * to `@Service(model)` and `@Repository(model)` resolves to two different injected objects (a
+ * `ModelService<M>` vs a `Repository<M>` respectively), via {@link CoreRepository.forModel}.
+ * @param model the model class to resolve a repository for.
+ * @param flavour optional adapter flavour/alias, forwarded to {@link CoreRepository.forModel}.
+ */
+export declare function Repository(model: Constructor<any>, flavour?: string): ParameterDecorator;

package/lib/types/decorators.d.mts

@@ -0,0 +1,35 @@
+import { Constructor } from "@decaf-ts/decoration";
+export type DecafFactoryProvider = {
+    provide: string;
+    useFactory: () => unknown;
+};
+/**
+ * @description Drains the providers registered by {@link Service}/{@link Repository} usages.
+ * @summary Consumed by {@link DecafCoreModule.forRoot} to wire the tokens that those parameter
+ * decorators reference back into Nest's DI container, since a parameter decorator alone cannot
+ * supply a provider.
+ */
+export declare function getRegisteredDecafProviders(): DecafFactoryProvider[];
+/**
+ * @description Constructor parameter decorator that injects a decaf service.
+ * @summary Translates decaf's service resolution APIs into a Nest `@Inject()` call:
+ * - `@Service(SomeModel)` injects the matching `@service(SomeModel)` decaf service when one is
+ *   registered; otherwise it falls back to the `ModelService<SomeModel>` singleton
+ *   (via {@link ModelService.forModel}).
+ * - `@Service(SomeServiceClass)` or `@Service("alias")` injects the matching `@service()`-decorated
+ *   decaf {@link CoreService} (via {@link CoreService.get}).
+ * - `@Service()` infers the parameter's type from emitted constructor metadata and resolves it the
+ *   same way, provided the parameter is typed as a concrete class (generics like `ModelService<X>`
+ *   are erased at runtime, so the model-service form always requires an explicit argument).
+ * @param key the model class, service class, or alias to resolve. Omit to infer from the parameter type.
+ */
+export declare function Service(key?: string | Constructor<any>): ParameterDecorator;
+/**
+ * @description Constructor parameter decorator that injects a decaf {@link CoreRepository} for `model`.
+ * @summary Unlike {@link Service}, `model` is always treated as a Model class: the same class passed
+ * to `@Service(model)` and `@Repository(model)` resolves to two different injected objects (a
+ * `ModelService<M>` vs a `Repository<M>` respectively), via {@link CoreRepository.forModel}.
+ * @param model the model class to resolve a repository for.
+ * @param flavour optional adapter flavour/alias, forwarded to {@link CoreRepository.forModel}.
+ */
+export declare function Repository(model: Constructor<any>, flavour?: string): ParameterDecorator;

package/lib/types/factory/NestBootstraper.d.cts

@@ -190,6 +190,11 @@ export declare class NestBootstraper {
      * set of standard exception filters for common error types like
      * `HttpException`, `ValidationException`, `ConflictException`, and others.
      *
+     * The default `DecafExceptionFilter` is constructed with the application's
+     * `ModuleRef` so it can resolve the request-scoped `DecafRequestContext` (and
+     * its client-bound logger) for the request that threw, instead of logging
+     * through the generic global logger.
+     *
      * @param {...ExceptionFilter[]} filters - Optional filters to apply globally.
      */
     static useGlobalFilters(...filters: any[]): typeof NestBootstraper;

package/lib/types/factory/NestBootstraper.d.mts

@@ -190,6 +190,11 @@ export declare class NestBootstraper {
      * set of standard exception filters for common error types like
      * `HttpException`, `ValidationException`, `ConflictException`, and others.
      *
+     * The default `DecafExceptionFilter` is constructed with the application's
+     * `ModuleRef` so it can resolve the request-scoped `DecafRequestContext` (and
+     * its client-bound logger) for the request that threw, instead of logging
+     * through the generic global logger.
+     *
      * @param {...ExceptionFilter[]} filters - Optional filters to apply globally.
      */
     static useGlobalFilters(...filters: any[]): typeof NestBootstraper;

package/lib/types/factory/exceptions/DecafErrorFilter.d.cts

@@ -1,4 +1,36 @@
 import { ArgumentsHost, ExceptionFilter } from "@nestjs/common";
+import { ModuleRef } from "@nestjs/core";
+import { BaseError } from "@decaf-ts/db-decorators";
+import type { RequestLogger } from "@decaf-ts/for-http/server";
 export declare class DecafExceptionFilter implements ExceptionFilter {
-    catch(exception: Error, host: ArgumentsHost): void;
+    protected readonly moduleRef?: ModuleRef | undefined;
+    constructor(moduleRef?: ModuleRef | undefined);
+    catch(exception: Error, host: ArgumentsHost): Promise<void>;
+    /**
+     * @description Finds the decaf-ts `BaseError` constructor mapped to this exception's type, if any.
+     * @summary Walks `HTTP_EXCEPTION_TO_DECAF_ERROR` with `instanceof` (rather than a straight
+     * `Map.get`) so subclasses of a mapped exception are matched too.
+     */
+    protected decafErrorFor(exception: Error): ((msg: string) => BaseError) | undefined;
+    /**
+     * @description Logs the exception without ever letting logging failures block the response.
+     * @summary A guard (or middleware/CORS check) can throw before any decaf-aware provider ran,
+     * so the request-bound Context may not exist yet — or the resolved logger's `.error()` itself
+     * could throw (broken transport, formatter bug, etc.). Either way the client-facing error
+     * response below must still go out, so every failure mode here is swallowed, falling back to
+     * the plain `Logging.get()` logger and, as a last resort, doing nothing at all.
+     */
+    protected logError(request: Record<string, any>, exception: Error): Promise<void>;
+    /**
+     * @description Resolves the logger bound to the originating request's decaf-ts Context.
+     * @summary Global filters are singletons, so the request-scoped {@link DecafRequestContext}
+     * (and the client/user-bound logger it carries) can't be constructor-injected. Instead, this
+     * looks up the same request's context id and re-resolves the already-accumulated instance
+     * through `ModuleRef`. Falls back to the generic `Logging.get()` logger when the filter wasn't
+     * constructed with a `ModuleRef` (e.g. manually `new`'d) or no request-scoped context exists
+     * for this request (e.g. the error happened before any decaf-aware provider ran, as is the
+     * case when a guard rejects the request before interceptors get to bind the client-scoped
+     * logger onto the Context).
+     */
+    protected resolveLogger(request: Record<string, any>): Promise<RequestLogger>;
 }

package/lib/types/factory/exceptions/DecafErrorFilter.d.mts

@@ -1,4 +1,36 @@
 import { ArgumentsHost, ExceptionFilter } from "@nestjs/common";
+import { ModuleRef } from "@nestjs/core";
+import { BaseError } from "@decaf-ts/db-decorators";
+import type { RequestLogger } from "@decaf-ts/for-http/server";
 export declare class DecafExceptionFilter implements ExceptionFilter {
-    catch(exception: Error, host: ArgumentsHost): void;
+    protected readonly moduleRef?: ModuleRef | undefined;
+    constructor(moduleRef?: ModuleRef | undefined);
+    catch(exception: Error, host: ArgumentsHost): Promise<void>;
+    /**
+     * @description Finds the decaf-ts `BaseError` constructor mapped to this exception's type, if any.
+     * @summary Walks `HTTP_EXCEPTION_TO_DECAF_ERROR` with `instanceof` (rather than a straight
+     * `Map.get`) so subclasses of a mapped exception are matched too.
+     */
+    protected decafErrorFor(exception: Error): ((msg: string) => BaseError) | undefined;
+    /**
+     * @description Logs the exception without ever letting logging failures block the response.
+     * @summary A guard (or middleware/CORS check) can throw before any decaf-aware provider ran,
+     * so the request-bound Context may not exist yet — or the resolved logger's `.error()` itself
+     * could throw (broken transport, formatter bug, etc.). Either way the client-facing error
+     * response below must still go out, so every failure mode here is swallowed, falling back to
+     * the plain `Logging.get()` logger and, as a last resort, doing nothing at all.
+     */
+    protected logError(request: Record<string, any>, exception: Error): Promise<void>;
+    /**
+     * @description Resolves the logger bound to the originating request's decaf-ts Context.
+     * @summary Global filters are singletons, so the request-scoped {@link DecafRequestContext}
+     * (and the client/user-bound logger it carries) can't be constructor-injected. Instead, this
+     * looks up the same request's context id and re-resolves the already-accumulated instance
+     * through `ModuleRef`. Falls back to the generic `Logging.get()` logger when the filter wasn't
+     * constructed with a `ModuleRef` (e.g. manually `new`'d) or no request-scoped context exists
+     * for this request (e.g. the error happened before any decaf-aware provider ran, as is the
+     * case when a guard rejects the request before interceptors get to bind the client-scoped
+     * logger onto the Context).
+     */
+    protected resolveLogger(request: Record<string, any>): Promise<RequestLogger>;
 }

package/lib/types/factory/openapi/DtoBuilder.d.cts

@@ -14,12 +14,16 @@ import { Model } from "@decaf-ts/decorator-validation";
  *      • CREATE  – included only when the pk is NOT auto-generated
  *                  (checked via Model.pkProps().generated AND Model.generated()).
  *  - Relation properties (@oneToOne, @oneToMany, …):
- *      • CREATE  – nested as DtoFor(CREATE, RelatedModel).
+ *      • CREATE  – nested as DtoFor(CREATE, RelatedModel). When the relation
+ *                  creates a circular reference (model A → model B → model A),
+ *                  the back-reference uses the related model's PK type
+ *                  (string/integer) instead of the full DTO to break the cycle.
  *      • UPDATE  – union of DtoFor(UPDATE, RelatedModel) **or** the
  *                  related model's primary-key type (string / integer),
- *                  expressed as a Swagger oneOf.
+ *                  expressed as a Swagger oneOf. Circular back-references
+ *                  omit the DTO $ref and only include the PK type.
  *
  * Metadata.properties() now returns ALL properties across the prototype chain,
  * so DTO inheritance is no longer needed; every DTO is a flat class.
  */
-export declare function DtoFor<M extends Model>(op: OperationKeys, model: Constructor<M>): Constructor<any>;
+export declare function DtoFor<M extends Model>(op: OperationKeys, model: Constructor<M>, stack?: Set<Constructor<any>>): Constructor<any>;

package/lib/types/factory/openapi/DtoBuilder.d.mts

@@ -14,12 +14,16 @@ import { Model } from "@decaf-ts/decorator-validation";
  *      • CREATE  – included only when the pk is NOT auto-generated
  *                  (checked via Model.pkProps().generated AND Model.generated()).
  *  - Relation properties (@oneToOne, @oneToMany, …):
- *      • CREATE  – nested as DtoFor(CREATE, RelatedModel).
+ *      • CREATE  – nested as DtoFor(CREATE, RelatedModel). When the relation
+ *                  creates a circular reference (model A → model B → model A),
+ *                  the back-reference uses the related model's PK type
+ *                  (string/integer) instead of the full DTO to break the cycle.
  *      • UPDATE  – union of DtoFor(UPDATE, RelatedModel) **or** the
  *                  related model's primary-key type (string / integer),
- *                  expressed as a Swagger oneOf.
+ *                  expressed as a Swagger oneOf. Circular back-references
+ *                  omit the DTO $ref and only include the PK type.
  *
  * Metadata.properties() now returns ALL properties across the prototype chain,
  * so DTO inheritance is no longer needed; every DTO is a flat class.
  */
-export declare function DtoFor<M extends Model>(op: OperationKeys, model: Constructor<M>): Constructor<any>;
+export declare function DtoFor<M extends Model>(op: OperationKeys, model: Constructor<M>, stack?: Set<Constructor<any>>): Constructor<any>;

package/lib/types/index.d.cts

@@ -22,6 +22,7 @@
 import "./decoration";
 export * from "./decoration.d.cts";
 export * from "./decaf-model/index.d.cts";
+export * from "./auth/index.d.cts";
 export * from "./factory/index.d.cts";
 export * from "./interceptors/index.d.cts";
 export * from "./overrides/index.d.cts";
@@ -30,8 +31,8 @@ export * from "./constants.d.cts";
 export * from "./controllers.d.cts";
 export * from "./module.d.cts";
 export * from "./core-module.d.cts";
-export * from "./migrations/index.d.cts";
 export * from "./types.d.cts";
+export * from "./decorators.d.cts";
 export * from "./utils.d.cts";
 export * from "./events-module/index.d.cts";
 /**
@@ -40,19 +41,19 @@ export * from "./events-module/index.d.cts";
  * @constant
  * @type {string}
  */
-export declare const VERSION = "0.11.1";
+export declare const VERSION = "0.11.2-refactor.9";
 /**
  * @description Represents the current commit hash of the module build.
  * @summary Stores the current git commit hash for the package. The build replaces
  * the placeholder with the actual commit hash at publish time.
  * @const COMMIT
  */
-export declare const COMMIT = "4deec24";
+export declare const COMMIT = "00a7d73";
 /**
  * @description Represents the full version string of the module.
  * @summary Stores the semver version and commit hash for the package.
  * The build replaces the placeholder with the actual `<version>-<commit>` value at publish time.
  * @const FULL_VERSION
  */
-export declare const FULL_VERSION = "0.11.1-4deec24";
+export declare const FULL_VERSION = "0.11.2-refactor.9-00a7d73";
 export declare const PACKAGE_NAME = "@decaf-ts/for-nest";