@decaf-ts/for-nest 0.6.0 → 0.7.0

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

@@ -0,0 +1,9 @@
+import { DecafApiProperty } from "./types.js";
+/**
+ * @description A higher-level decorator factory that leverages `OrderedParams` to extract route parameters in a specific order derived from a list of `ApiParam` definitions.
+ * @summary `DecafParams` computes the order of route parameters based on the provided `ApiParam[]` specification (using each element’s `name`), then applies `OrderedParams(order)` as a parameter decorator. This enables parameter-level binding that remains consistent with the documented API parameter metadata.
+ * @param {ApiParam[]} [props=[]] Array of `ApiParam` definitions whose `name` fields determine the parameter extraction order.
+ * @return {ParameterDecorator} A NestJS parameter decorator that injects an ordered list of parameters and metadata into the controller method argument.
+ */
+export declare function DecafParams(props?: DecafApiProperty[]): ParameterDecorator;
+export declare const DecafQuery: (...dataOrPipes: unknown[]) => ParameterDecorator;

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

@@ -0,0 +1,29 @@
+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;

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

@@ -0,0 +1,29 @@
+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;

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

@@ -0,0 +1,7 @@
+export * from "./types.cjs";
+export * from "./ApiOperationFromModel.cjs";
+export * from "./ApiParamsFromModel.cjs";
+export * from "./DecafBody.cjs";
+export * from "./DecafParams.cjs";
+export * from "./utils.cjs";
+export * from "./decorators.cjs";

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

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./ApiOperationFromModel.js";
+export * from "./ApiParamsFromModel.js";
+export * from "./DecafBody.js";
+export * from "./DecafParams.js";
+export * from "./utils.js";
+export * from "./decorators.js";

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

@@ -0,0 +1,23 @@
+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>;
+};
+export interface DecafRouteDecOptions {
+    path: string;
+    httpMethod: HttpVerbs;
+    handler: PropertyDescriptor;
+}

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

@@ -0,0 +1,23 @@
+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>;
+};
+export interface DecafRouteDecOptions {
+    path: string;
+    httpMethod: HttpVerbs;
+    handler: PropertyDescriptor;
+}

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

@@ -0,0 +1,11 @@
+import { HttpVerbs } from "./types.cjs";
+/**
+ * Maps an HTTP verb to its corresponding NestJS method decorator.
+ *
+ * @param verb - HTTP verb to be converted (e.g. GET, POST, PUT, PATCH, DELETE).
+ * @returns A NestJS method decorator matching the provided HTTP verb.
+ *
+ * @throws {Error} If the provided HTTP verb is not supported or not mapped
+ * to a NestJS decorator.
+ */
+export declare function HttpVerbToDecorator(verb: HttpVerbs): (path?: string) => MethodDecorator;

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

@@ -0,0 +1,11 @@
+import { HttpVerbs } from "./types.js";
+/**
+ * Maps an HTTP verb to its corresponding NestJS method decorator.
+ *
+ * @param verb - HTTP verb to be converted (e.g. GET, POST, PUT, PATCH, DELETE).
+ * @returns A NestJS method decorator matching the provided HTTP verb.
+ *
+ * @throws {Error} If the provided HTTP verb is not supported or not mapped
+ * to a NestJS decorator.
+ */
+export declare function HttpVerbToDecorator(verb: HttpVerbs): (path?: string) => MethodDecorator;

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

@@ -0,0 +1,3 @@
+export * from "./decorators/index.cjs";
+export * from "./DecafModelModule.cjs";
+export * from "./FromModelController.cjs";

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

@@ -0,0 +1,3 @@
+export * from "./decorators/index.js";
+export * from "./DecafModelModule.js";
+export * from "./FromModelController.js";

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

@@ -0,0 +1,7 @@
+import { DecafModelController } from "../controllers.cjs";
+import { Model } from "@decaf-ts/decorator-validation";
+export type ControllerConstructor<T extends Model<boolean>> = new (...args: any[]) => DecafModelController<T>;
+export type DecoratorBundle = {
+    method: MethodDecorator[];
+    params?: ParameterDecorator[];
+};

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

@@ -0,0 +1,7 @@
+import { DecafModelController } from "../controllers.js";
+import { Model } from "@decaf-ts/decorator-validation";
+export type ControllerConstructor<T extends Model<boolean>> = new (...args: any[]) => DecafModelController<T>;
+export type DecoratorBundle = {
+    method: MethodDecorator[];
+    params?: ParameterDecorator[];
+};

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

@@ -0,0 +1,10 @@
+import { type DecoratorBundle } from "./types.cjs";
+import { type DecafParamProps, HttpVerbs } from "./decorators/index.cjs";
+import { DirectionLimitOffset, ModelService, Repo } from "@decaf-ts/core";
+import { Model } from "@decaf-ts/decorator-validation";
+import { DecafModelController } from "../controllers.cjs";
+export declare function getApiDecorators(methodName: string, routePath: string, httpVerb: HttpVerbs, includeQueryParams?: boolean): DecoratorBundle;
+export declare function applyApiDecorators(target: any, methodName: string, descriptor: PropertyDescriptor, decorators: DecoratorBundle): void;
+export declare function resolvePersistenceMethod<T extends Model<boolean>>(persistence: Repo<T> | ModelService<T>, methodName: string, ...args: any[]): any;
+export declare function createRouteHandler<T>(methodName: string): (this: DecafModelController<any>, pathParams: DecafParamProps, queryParams: DirectionLimitOffset) => Promise<T>;
+export declare function defineRouteMethod(ControllerClass: new (...args: any[]) => any, methodName: string, handler: (...args: any[]) => any): PropertyDescriptor | undefined;

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

@@ -0,0 +1,10 @@
+import { type DecoratorBundle } from "./types.js";
+import { type DecafParamProps, HttpVerbs } from "./decorators/index.js";
+import { DirectionLimitOffset, ModelService, Repo } from "@decaf-ts/core";
+import { Model } from "@decaf-ts/decorator-validation";
+import { DecafModelController } from "../controllers.js";
+export declare function getApiDecorators(methodName: string, routePath: string, httpVerb: HttpVerbs, includeQueryParams?: boolean): DecoratorBundle;
+export declare function applyApiDecorators(target: any, methodName: string, descriptor: PropertyDescriptor, decorators: DecoratorBundle): void;
+export declare function resolvePersistenceMethod<T extends Model<boolean>>(persistence: Repo<T> | ModelService<T>, methodName: string, ...args: any[]): any;
+export declare function createRouteHandler<T>(methodName: string): (this: DecafModelController<any>, pathParams: DecafParamProps, queryParams: DirectionLimitOffset) => Promise<T>;
+export declare function defineRouteMethod(ControllerClass: new (...args: any[]) => any, methodName: string, handler: (...args: any[]) => any): PropertyDescriptor | undefined;

package/lib/types/decoration.d.cts

@@ -0,0 +1 @@
+export {};

package/lib/types/decoration.d.mts

@@ -0,0 +1 @@
+export {};

package/lib/types/events-module/DecafStreamModule.d.cts

@@ -0,0 +1,4 @@
+import { DynamicModule } from "@nestjs/common";
+export declare class DecafStreamModule {
+    static forFlavours(flavours: string[], path?: string): DynamicModule;
+}

package/lib/types/events-module/DecafStreamModule.d.mts

@@ -0,0 +1,4 @@
+import { DynamicModule } from "@nestjs/common";
+export declare class DecafStreamModule {
+    static forFlavours(flavours: string[], path?: string): DynamicModule;
+}

package/lib/types/events-module/EventsController.d.cts

@@ -0,0 +1,11 @@
+import { DecafController } from "../controllers.cjs";
+import { DecafRequestContext } from "../request/index.cjs";
+import { MessageEvent } from "@nestjs/common";
+import { Observable } from "rxjs";
+import { DecafServerCtx } from "../constants.cjs";
+export declare class EventsController extends DecafController<DecafServerCtx> {
+    private readonly adapters;
+    constructor(clientContext: DecafRequestContext, flavours: string[]);
+    listen(): Observable<MessageEvent>;
+    listenForModel(model: string): Observable<MessageEvent>;
+}

package/lib/types/events-module/EventsController.d.mts

@@ -0,0 +1,11 @@
+import { DecafController } from "../controllers.js";
+import { DecafRequestContext } from "../request/index.js";
+import { MessageEvent } from "@nestjs/common";
+import { Observable } from "rxjs";
+import { DecafServerCtx } from "../constants.js";
+export declare class EventsController extends DecafController<DecafServerCtx> {
+    private readonly adapters;
+    constructor(clientContext: DecafRequestContext, flavours: string[]);
+    listen(): Observable<MessageEvent>;
+    listenForModel(model: string): Observable<MessageEvent>;
+}

package/lib/types/events-module/constant.d.cts

@@ -0,0 +1 @@
+export declare const LISTENING_ADAPTERS_FLAVOURS: unique symbol;

package/lib/types/events-module/constant.d.mts

@@ -0,0 +1 @@
+export declare const LISTENING_ADAPTERS_FLAVOURS: unique symbol;

package/lib/types/events-module/index.d.cts

@@ -0,0 +1,2 @@
+export * from "./EventsController.cjs";
+export * from "./DecafStreamModule.cjs";

package/lib/types/events-module/index.d.mts

@@ -0,0 +1,2 @@
+export * from "./EventsController.js";
+export * from "./DecafStreamModule.js";

package/lib/types/events-module/utils.d.cts

@@ -0,0 +1 @@
+export declare function normalizeEventResponse(args: any[]): unknown[];

package/lib/types/events-module/utils.d.mts

@@ -0,0 +1 @@
+export declare function normalizeEventResponse(args: any[]): unknown[];

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

@@ -0,0 +1,224 @@
+import { INestApplication, Logger, NestInterceptor, PipeTransform } from "@nestjs/common";
+/**
+ * @description
+ * Defines all customizable parameters for Swagger setup.
+ *
+ * @summary
+ * This interface allows developers to customize how Swagger UI is configured
+ * within the NestJS application. It includes parameters for titles, paths,
+ * color schemes, and asset paths to tailor the API documentation experience.
+ *
+ * @param {string} title - Title displayed in Swagger UI.
+ * @param {string} description - Description shown below the title.
+ * @param {string} version - API version displayed in the documentation.
+ * @param {string} [path] - Optional path where Swagger will be available.
+ * @param {boolean} [persistAuthorization] - Whether authorization tokens persist across reloads.
+ * @param {string} [assetsPath] - Path to custom assets for Swagger UI.
+ * @param {string} [topbarBgColor] - Custom background color for the Swagger top bar.
+ * @param {string} [topbarIconPath] - Path to a custom icon displayed in the top bar.
+ * @param {string} [faviconPath] - Path to a custom favicon.
+ */
+export interface SwaggerSetupOptions {
+    title: string;
+    description: string;
+    version: string;
+    path?: string;
+    persistAuthorization?: boolean;
+    assetsPath?: string;
+    topbarBgColor?: string;
+    topbarIconPath?: string;
+    faviconPath?: string;
+    /**
+     * Path to expose the OpenAPI specification in JSON format.
+     * Example: /api/openapi.json
+     */
+    openApiJsonPath?: string;
+    /**
+     * Path to expose the OpenAPI specification in YAML format.
+     * Requires 'yaml' package as peer dependency.
+     * Example: /api/openapi.yaml
+     */
+    openApiYamlPath?: string;
+}
+/**
+ * @description
+ * A fluent, static bootstrap class for initializing and configuring a NestJS application.
+ *
+ * @summary
+ * The `NestBootstraper` class provides a chainable API for configuring
+ * a NestJS application instance. It includes built-in methods for enabling
+ * CORS, Helmet security, Swagger documentation, global pipes, filters,
+ * interceptors, and starting the server.
+ *
+ * This class promotes consistency and reduces repetitive setup code
+ * across multiple NestJS projects.
+ *
+ * @example
+ * ```ts
+ * import { NestFactory } from "@nestjs/core";
+ * import { AppModule } from "./app.module.cjs";
+ * import { MyLogger } from "./MyLogger.cjs";
+ * import { NestBootstraper } from "@decaf-ts/for-nest";
+ *
+ * async function bootstrap() {
+ *   const app = await NestFactory.create(AppModule);
+ *
+ *   await NestBootstraper
+ *     .initialize(app)
+ *     .enableLogger(new MyLogger())
+ *     .enableCors(["http://localhost:4200"])
+ *     .useHelmet()
+ *     .setupSwagger({
+ *       title: "OpenAPI by TradeMark™",
+ *       description: "TradeMark™ API documentation",
+ *       version: "1.0.0",
+ *       path: "api",
+ *       persistAuthorization: true,
+ *       topbarBgColor: "#2C3E50",
+ *       topbarIconPath: "/assets/logo.svg",
+ *       faviconPath: "/assets/favicon.ico"
+ *     })
+ *     .useGlobalFilters()
+ *     .useGlobalPipes(...)
+ *     .useGlobalInterceptors(...)
+ *     .start(3000);
+ * }
+ *
+ * bootstrap();
+ * ```
+ * @class
+ */
+export declare class NestBootstraper {
+    private static app;
+    private static _logger;
+    /**
+     * @description
+     * Returns the current logger instance, creating a default one if not set.
+     *
+     * @summary
+     * Ensures that a valid `Logger` instance is always available
+     * for logging bootstrap-related messages.
+     *
+     * @return {Logger} The active logger instance.
+     */
+    private static get logger();
+    /**
+     * @description
+     * Initializes the bootstrapper with a given NestJS application.
+     *
+     * @summary
+     * Binds the provided NestJS app instance to the bootstrapper, enabling
+     * chained configuration methods.
+     *
+     * @param {INestApplication} app - The NestJS application instance to initialize.
+     * @return {NestBootstraper} Returns the class for chaining configuration methods.
+     */
+    static initialize(app: INestApplication): typeof NestBootstraper;
+    /**
+     * @description
+     * Enables or replaces the global logger for the NestJS application.
+     *
+     * @summary
+     * If a custom logger is provided, it replaces the default logger. Otherwise,
+     * a new logger named `"NestBootstrap"` is used. This logger is also registered
+     * with the NestJS application.
+     *
+     * @param {Logger} [customLogger] - Optional custom logger instance.
+     * @return {NestBootstraper} Returns the class for chaining.
+     */
+    static enableLogger(customLogger?: Logger): typeof NestBootstraper;
+    /**
+     * @description
+     * Enables Cross-Origin Resource Sharing (CORS) for the application.
+     *
+     * @summary
+     * Allows defining either a wildcard origin (`"*"`) or a list of allowed origins.
+     * Automatically accepts local development requests and those without origin headers.
+     * Throws a `CorsError` for unauthorized origins.
+     *
+     * @param {'*' | string[]} [origins=[]] - List of allowed origins or `"*"` to allow all.
+     * @param {string[]} [allowMethods=['GET', 'POST', 'PUT', 'DELETE']] - Allowed HTTP methods.
+     * @return {NestBootstraper} Returns the class for chaining configuration.
+     *
+     */
+    static enableCors(origins?: "*" | string[], allowMethods?: string[]): typeof NestBootstraper;
+    /**
+     * @description
+     * Applies the Helmet middleware for enhanced security.
+     *
+     * @summary
+     * Dynamically loads the `helmet` package if available and registers it
+     * as middleware to improve HTTP header security. If not installed, logs a warning
+     * and continues execution without throwing errors.
+     *
+     * @param {Record<string, any>} [options] - Optional configuration passed to Helmet.
+     * @return {NestBootstraper} Returns the class for chaining configuration.
+     */
+    static useHelmet(options?: Record<string, any>): typeof NestBootstraper;
+    /**
+     * @description
+     * Configures and initializes Swagger UI for API documentation.
+     *
+     * @summary
+     * Uses the `SwaggerBuilder` utility to configure API documentation
+     * with detailed customization for title, version, paths, and colors.
+     * Swagger is automatically exposed at the configured path.
+     *
+     * @param {SwaggerSetupOptions} options - Swagger configuration options.
+     * @return {NestBootstraper} Returns the class for chaining configuration.
+     */
+    static setupSwagger(options: SwaggerSetupOptions): typeof NestBootstraper;
+    /**
+     * @description
+     * Registers one or more global validation pipes.
+     *
+     * @summary
+     * Enables request payload validation and transformation globally across
+     * the entire NestJS application. Multiple pipes can be chained together
+     * for modular input validation.
+     *
+     * @param {...PipeTransform[]} pipes - Pipe instances to register globally.
+     * @return {NestBootstraper} Returns the class for chaining.
+     */
+    static useGlobalPipes(...pipes: PipeTransform[]): typeof NestBootstraper;
+    /**
+     * @description
+     * Registers one or more global exception filters.
+     *
+     * @summary
+     * If no filters are provided, it automatically registers a default
+     * set of standard exception filters for common error types like
+     * `HttpException`, `ValidationException`, `ConflictException`, and others.
+     *
+     * @param {...ExceptionFilter[]} filters - Optional filters to apply globally.
+     */
+    static useGlobalFilters(...filters: any[]): typeof NestBootstraper;
+    /**
+     * @description
+     * Registers global interceptors for request and response transformation.
+     *
+     * @summary
+     * Interceptors allow advanced request/response manipulation such as
+     * serialization, logging, or transformation. Multiple interceptors
+     * can be added for modular configuration.
+     *
+     * @param {...NestInterceptor[]} interceptors - Interceptor instances to register.
+     * @return {NestBootstraper} Returns the class for chaining configuration.
+     */
+    static useGlobalInterceptors(...interceptors: NestInterceptor[]): typeof NestBootstraper;
+    /**
+     * @description
+     * Starts the NestJS application and binds it to the given port and host.
+     *
+     * @summary
+     * Listens on the specified port and optionally a host. Once started,
+     * logs the application URL for easy access. The startup process resolves
+     * once the application is successfully running.
+     *
+     * @param {number} [port=3000] - Port number to listen on.
+     * @param {string} [host] - Optional host or IP address to bind to.
+     * @param {boolean} [log=true] - Whether to log the application URL upon startup.
+     * @return {Promise<void>} Resolves once the application starts successfully.
+     */
+    static start(port?: number, host?: string | undefined, log?: boolean): Promise<void>;
+}