express-resforge 1.0.0

package/dist/core/pluginManager.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.globalPluginManager = exports.PluginManager = void 0;
+/**
+ * Orchestration engine managing registration and execution lifecycle of custom plugins.
+ */
+class PluginManager {
+    plugins = [];
+    /**
+     * Registers a global plugin hook into the internal pipeline.
+     * @param plugin The execution interceptor function block.
+     */
+    use(plugin) {
+        if (typeof plugin === 'function') {
+            this.plugins.push(plugin);
+        }
+    }
+    /**
+     * Executes all registered plugins sequentially over the payload using a flat loop
+     * to guarantee zero-allocation performance overhead.
+     *
+     * @param payload The generated standard API response object.
+     * @param req The raw incoming Express request context.
+     * @param res The raw active Express response context.
+     * @returns The fully decorated or mutated API payload structure.
+     */
+    execute(payload, req, res) {
+        let activePayload = payload;
+        const length = this.plugins.length;
+        for (let i = 0; i < length; i++) {
+            activePayload = this.plugins[i](activePayload, req, res) || activePayload;
+        }
+        return activePayload;
+    }
+}
+exports.PluginManager = PluginManager;
+exports.globalPluginManager = new PluginManager();

package/dist/core/responseBuilder.d.ts

@@ -0,0 +1,32 @@
+import { Response } from 'express';
+import { ApiResponsePagination, ValidationErrorItem } from '../types/responses';
+/**
+ * High-performance fluent response orchestrator supporting dynamic chained configurations.
+ * @template T Type of the payload data data-set container.
+ */
+export declare class ResponseBuilder<T = unknown> {
+    private readonly _res;
+    private readonly _statusCode;
+    private readonly _success;
+    private readonly _data;
+    private _message;
+    private _responseCode;
+    private _meta;
+    private _pagination?;
+    private _errors?;
+    private readonly _headers;
+    private readonly _cookies;
+    constructor(_res: Response, _statusCode: number, _success: boolean, _data?: T | null);
+    message(msg: string): this;
+    code(code: string): this;
+    meta(metadata: Record<string, unknown>): this;
+    pagination(pag: ApiResponsePagination): this;
+    errors(errs: ValidationErrorItem[] | unknown): this;
+    header(name: string, value: string): this;
+    cookie(name: string, value: string, options?: any): this;
+    /**
+     * Finalizes the response envelope, triggers cookie/header updates,
+     * applies external plugins, and flushes the data down the Express HTTP channel.
+     */
+    send(): Response;
+}

package/dist/core/responseBuilder.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResponseBuilder = void 0;
+const context_1 = require("./context");
+const cleanObject_1 = require("../utils/cleanObject");
+const deepMerge_1 = require("../utils/deepMerge");
+const pluginManager_1 = require("./pluginManager");
+/**
+ * High-performance fluent response orchestrator supporting dynamic chained configurations.
+ * @template T Type of the payload data data-set container.
+ */
+class ResponseBuilder {
+    _res;
+    _statusCode;
+    _success;
+    _data;
+    _message = '';
+    _responseCode = 'SUCCESS';
+    _meta = {};
+    _pagination;
+    _errors;
+    _headers = {};
+    _cookies = [];
+    constructor(_res, _statusCode, _success, _data = null) {
+        this._res = _res;
+        this._statusCode = _statusCode;
+        this._success = _success;
+        this._data = _data;
+    }
+    message(msg) {
+        this._message = msg;
+        return this;
+    }
+    code(code) {
+        this._responseCode = code;
+        return this;
+    }
+    meta(metadata) {
+        this._meta = (0, deepMerge_1.deepMerge)(this._meta, metadata);
+        return this;
+    }
+    pagination(pag) {
+        this._pagination = pag;
+        return this;
+    }
+    errors(errs) {
+        this._errors = errs;
+        return this;
+    }
+    header(name, value) {
+        this._headers[name] = value;
+        return this;
+    }
+    cookie(name, value, options) {
+        this._cookies.push({ name, value, options });
+        return this;
+    }
+    /**
+     * Finalizes the response envelope, triggers cookie/header updates,
+     * applies external plugins, and flushes the data down the Express HTTP channel.
+     */
+    send() {
+        // 1. Process custom headers smoothly
+        const headerKeys = Object.keys(this._headers);
+        for (let i = 0; i < headerKeys.length; i++) {
+            this._res.setHeader(headerKeys[i], this._headers[headerKeys[i]]);
+        }
+        // 2. Inject pending cookies
+        const cookieLength = this._cookies.length;
+        for (let i = 0; i < cookieLength; i++) {
+            const c = this._cookies[i];
+            this._res.cookie(c.name, c.value, c.options);
+        }
+        // 3. Resolve request context variables out-of-band safely
+        const reqId = context_1.requestContext.getRequestId();
+        const execTime = context_1.requestContext.getExecutionTimeMs();
+        const config = this._res.__apiKitConfig;
+        // 4. Construct the standard enterprise envelope skeleton
+        let payload = {
+            success: this._success,
+            statusCode: this._statusCode,
+            responseCode: this._responseCode,
+            message: this._message || (this._res.__apiKitDefaultMessage ?? ''),
+            data: this._data,
+            meta: (0, cleanObject_1.cleanObject)({
+                requestId: reqId,
+                timestamp: context_1.requestContext.getStore()?.timestamp ?? new Date().toISOString(),
+                executionTimeMs: execTime,
+                apiVersion: config?.apiVersion,
+                ...this._meta
+            })
+        };
+        if (this._pagination)
+            payload.pagination = this._pagination;
+        if (this._errors)
+            payload.errors = this._errors;
+        // 5. Execute internal pipeline filters and global plugins
+        if (config?.plugins && Array.isArray(config.plugins)) {
+            for (let i = 0; i < config.plugins.length; i++) {
+                payload = config.plugins[i](payload, this._res.req, this._res) || payload;
+            }
+        }
+        payload = pluginManager_1.globalPluginManager.execute(payload, this._res.req, this._res);
+        return this._res.status(this._statusCode).json(payload);
+    }
+}
+exports.ResponseBuilder = ResponseBuilder;

package/dist/core/responseFactory.d.ts

@@ -0,0 +1,12 @@
+import { Response } from 'express';
+import { ResponseBuilder } from './responseBuilder';
+import { ResponseOptions } from '../types/responses';
+/**
+ * Core engine constructing finalized structural responses across all standard HTTP states.
+ */
+export declare class ResponseFactory {
+    /**
+     * Generates a fully configured, fluent ResponseBuilder wrapper instance.
+     */
+    static create<T>(res: Response, statusCode: number, success: boolean, defaultCode: string, arg1?: unknown, arg2?: ResponseOptions): ResponseBuilder<T>;
+}

package/dist/core/responseFactory.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResponseFactory = void 0;
+const defaultMessages_1 = require("../constants/defaultMessages");
+const responseBuilder_1 = require("./responseBuilder");
+/**
+ * Normalizes polymorphic arguments passed to factory response helpers.
+ * Bypasses intensive allocation patterns to extract data and options efficiently.
+ */
+function parseArgs(arg1, arg2) {
+    if (arg1 === undefined && arg2 === undefined) {
+        return { data: null, options: {} };
+    }
+    // If the first argument matches an explicit options block layout, process as options override
+    if (arg1 && typeof arg1 === 'object' && !Array.isArray(arg1) && ('message' in arg1 || 'responseCode' in arg1 || 'meta' in arg1 || 'errors' in arg1 || 'pagination' in arg1)) {
+        return { data: null, options: arg1 };
+    }
+    return { data: arg1, options: arg2 || {} };
+}
+/**
+ * Core engine constructing finalized structural responses across all standard HTTP states.
+ */
+class ResponseFactory {
+    /**
+     * Generates a fully configured, fluent ResponseBuilder wrapper instance.
+     */
+    static create(res, statusCode, success, defaultCode, arg1, arg2) {
+        const { data, options } = parseArgs(arg1, arg2);
+        // Inject fallback localization message tags directly into the response instance
+        res.__apiKitDefaultMessage = options.message || defaultMessages_1.DefaultMessages[statusCode] || '';
+        const builder = new responseBuilder_1.ResponseBuilder(res, statusCode, success, data);
+        builder.code(options.responseCode || defaultCode);
+        if (options.meta)
+            builder.meta(options.meta);
+        if (options.errors)
+            builder.errors(options.errors);
+        if (options.pagination) {
+            const { page, limit, total } = options.pagination;
+            const totalPages = Math.ceil(total / limit) || 1;
+            builder.pagination({
+                page,
+                limit,
+                totalElements: total,
+                totalPages,
+                hasNextPage: page < totalPages,
+                hasPrevPage: page > 1,
+            });
+        }
+        return builder;
+    }
+}
+exports.ResponseFactory = ResponseFactory;

package/dist/formatter/axiosFormatter.d.ts

@@ -0,0 +1,8 @@
+export interface SafeAxiosErrorSummary {
+    message: string;
+    url?: string;
+    method?: string;
+    status?: number;
+    data?: unknown;
+}
+export declare function formatAxiosError(err: any): SafeAxiosErrorSummary;

package/dist/formatter/axiosFormatter.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatAxiosError = formatAxiosError;
+function formatAxiosError(err) {
+    return {
+        message: err.message || 'Upstream network request execution failed.',
+        url: err.config?.url,
+        method: err.config?.method?.toUpperCase(),
+        status: err.response?.status,
+        data: err.response?.data,
+    };
+}

package/dist/formatter/firebaseFormatter.d.ts

@@ -0,0 +1,6 @@
+import { ValidationErrorItem } from '../types/responses';
+export declare function formatFirebaseError(err: any): {
+    statusCode: number;
+    message: string;
+    errors?: ValidationErrorItem[];
+};

package/dist/formatter/firebaseFormatter.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatFirebaseError = formatFirebaseError;
+function formatFirebaseError(err) {
+    const code = err?.code || 'auth/unknown';
+    switch (code) {
+        case 'auth/user-not-found':
+        case 'auth/wrong-password':
+            return { statusCode: 401, message: 'Invalid authentication credentials provided.' };
+        case 'auth/email-already-in-use':
+            return {
+                statusCode: 409,
+                message: 'The email address provided is already registered.',
+                errors: [{ field: 'email', message: 'Email address already in use.', rule: 'unique' }]
+            };
+        default:
+            return { statusCode: 400, message: err.message || 'A cloud platform authentication error occurred.' };
+    }
+}

package/dist/formatter/joiFormatter.d.ts

@@ -0,0 +1,8 @@
+import { ValidationErrorItem } from '../types/responses';
+/**
+ * Normalizes Joi validation error structures into the enterprise standard format.
+ *
+ * @param joiError The raw validation error object returned by Joi.
+ * @returns {ValidationErrorItem[]} Standardized validation error array.
+ */
+export declare function formatJoiError(joiError: any): ValidationErrorItem[];

package/dist/formatter/joiFormatter.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatJoiError = formatJoiError;
+/**
+ * Normalizes Joi validation error structures into the enterprise standard format.
+ *
+ * @param joiError The raw validation error object returned by Joi.
+ * @returns {ValidationErrorItem[]} Standardized validation error array.
+ */
+function formatJoiError(joiError) {
+    if (!joiError || !Array.isArray(joiError.details)) {
+        return [];
+    }
+    const details = joiError.details;
+    const length = details.length;
+    const result = new Array(length);
+    for (let i = 0; i < length; i++) {
+        const detail = details[i];
+        result[i] = {
+            field: detail.path.join('.') || 'root',
+            message: detail.message.replace(/['"]/g, ''), // Cleans up awkward string escape notation from message text
+            rule: detail.type,
+        };
+    }
+    return result;
+}

package/dist/formatter/mongooseFormatter.d.ts

@@ -0,0 +1,2 @@
+import { ValidationErrorItem } from '../types/responses';
+export declare function formatMongooseError(err: any): ValidationErrorItem[];

package/dist/formatter/mongooseFormatter.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatMongooseError = formatMongooseError;
+function formatMongooseError(err) {
+    if (!err || !err.errors)
+        return [];
+    const keys = Object.keys(err.errors);
+    const length = keys.length;
+    const result = new Array(length);
+    for (let i = 0; i < length; i++) {
+        const key = keys[i];
+        const errorItem = err.errors[key];
+        result[i] = {
+            field: key,
+            message: errorItem.message || 'Field validation failed.',
+            rule: errorItem.kind || 'mongoose_validation',
+        };
+    }
+    return result;
+}

package/dist/formatter/prismaFormatter.d.ts

@@ -0,0 +1,15 @@
+import { ValidationErrorItem } from '../types/responses';
+interface PrismaErrorResponse {
+    statusCode: number;
+    message: string;
+    errors?: ValidationErrorItem[];
+}
+/**
+ * Formats Prisma ORM KnownRequestErrors into clean, client-ready responses.
+ * Maps cryptic database engine codes into clean HTTP state specifications.
+ *
+ * @param prismaError The raw exception caught from the Prisma database client layer.
+ * @returns {PrismaErrorResponse} Mapped status and safe, sanitized error tracking data.
+ */
+export declare function formatPrismaError(prismaError: any): PrismaErrorResponse;
+export {};

package/dist/formatter/prismaFormatter.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatPrismaError = formatPrismaError;
+/**
+ * Formats Prisma ORM KnownRequestErrors into clean, client-ready responses.
+ * Maps cryptic database engine codes into clean HTTP state specifications.
+ *
+ * @param prismaError The raw exception caught from the Prisma database client layer.
+ * @returns {PrismaErrorResponse} Mapped status and safe, sanitized error tracking data.
+ */
+function formatPrismaError(prismaError) {
+    const code = prismaError?.code;
+    const meta = prismaError?.meta;
+    switch (code) {
+        case 'P2002': {
+            // Unique constraint violation (e.g., trying to re-register an existing email)
+            const fields = Array.isArray(meta?.target) ? meta.target.join(', ') : 'field';
+            return {
+                statusCode: 409, // Conflict
+                message: `A resource with this unique value already exists.`,
+                errors: [{
+                        field: fields,
+                        message: `The value provided for ${fields} conflicts with an existing record.`,
+                        rule: 'unique_constraint',
+                    }],
+            };
+        }
+        case 'P2025': // Record to update or delete not found
+            return {
+                statusCode: 404, // Not Found
+                message: meta?.cause || 'The requested database record could not be located.',
+            };
+        case 'P2003': // Foreign key constraint failed
+            return {
+                statusCode: 400, // Bad Request
+                message: `Database relational integrity check failed.`,
+                errors: [{
+                        field: meta?.field || 'foreign_key',
+                        message: `Provided foreign key reference does not map to a valid record.`,
+                        rule: 'foreign_key_constraint',
+                    }],
+            };
+        default:
+            return {
+                statusCode: 500, // Internal Server Error fallback
+                message: 'A database processing failure occurred.',
+            };
+    }
+}

package/dist/formatter/zodFormatter.d.ts

@@ -0,0 +1,9 @@
+import { ValidationErrorItem } from '../types/responses';
+/**
+ * Transforms native Zod errors into a unified ValidationErrorItem payload format.
+ * Optimized via a single flat loop to prevent unnecessary object mapping allocations.
+ *
+ * @param zodError The raw error instance caught from Zod validation.
+ * @returns {ValidationErrorItem[]} Standardized validation error item collection.
+ */
+export declare function formatZodError(zodError: any): ValidationErrorItem[];

package/dist/formatter/zodFormatter.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatZodError = formatZodError;
+/**
+ * Transforms native Zod errors into a unified ValidationErrorItem payload format.
+ * Optimized via a single flat loop to prevent unnecessary object mapping allocations.
+ *
+ * @param zodError The raw error instance caught from Zod validation.
+ * @returns {ValidationErrorItem[]} Standardized validation error item collection.
+ */
+function formatZodError(zodError) {
+    if (!zodError || !Array.isArray(zodError.issues)) {
+        return [];
+    }
+    const issues = zodError.issues;
+    const length = issues.length;
+    const result = new Array(length);
+    for (let i = 0; i < length; i++) {
+        const issue = issues[i];
+        result[i] = {
+            field: issue.path.join('.') || 'root',
+            message: issue.message,
+            rule: issue.code,
+        };
+    }
+    return result;
+}

package/dist/helpers/cache.d.ts

@@ -0,0 +1,2 @@
+import { Response } from 'express';
+export declare function setCacheHeaders(res: Response, seconds: number): void;

package/dist/helpers/cache.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setCacheHeaders = setCacheHeaders;
+function setCacheHeaders(res, seconds) {
+    res.setHeader('Cache-Control', `public, max-age=${seconds}`);
+}

package/dist/helpers/cookies.d.ts

@@ -0,0 +1,2 @@
+import { Response } from 'express';
+export declare function appendSecureCookie(res: Response, name: string, value: string, maxAgeMs?: number): void;

package/dist/helpers/cookies.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendSecureCookie = appendSecureCookie;
+function appendSecureCookie(res, name, value, maxAgeMs = 3600000) {
+    res.cookie(name, value, { httpOnly: true, secure: true, sameSite: 'strict', maxAge: maxAgeMs });
+}

package/dist/helpers/download.d.ts

@@ -0,0 +1,2 @@
+import { Response } from 'express';
+export declare function streamDownload(res: Response, filePath: string, filename?: string): void;

package/dist/helpers/download.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.streamDownload = streamDownload;
+function streamDownload(res, filePath, filename) {
+    res.download(filePath, filename || 'download');
+}

package/dist/helpers/errors.d.ts

@@ -0,0 +1,10 @@
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+/**
+ * Higher-order async handler wrapper for Express routes.
+ * Eliminates the requirement for manual try/catch blocks across controllers.
+ * Fully compatible with Express v4 and Express v5 runtime paradigms.
+ *
+ * @param fn The asynchronous or synchronous target route handler function.
+ * @returns An optimized, safe Express RequestHandler.
+ */
+export declare function asyncWrapper(fn: (req: Request, res: Response, next: NextFunction) => Promise<unknown> | unknown): RequestHandler;

package/dist/helpers/errors.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asyncWrapper = asyncWrapper;
+/**
+ * Higher-order async handler wrapper for Express routes.
+ * Eliminates the requirement for manual try/catch blocks across controllers.
+ * Fully compatible with Express v4 and Express v5 runtime paradigms.
+ *
+ * @param fn The asynchronous or synchronous target route handler function.
+ * @returns An optimized, safe Express RequestHandler.
+ */
+function asyncWrapper(fn) {
+    return (req, res, next) => {
+        // Resolve the handler function call instantly
+        const result = fn(req, res, next);
+        // Programmatically catch promise rejections without allocating extra promise chains
+        if (result && typeof result.catch === 'function') {
+            result.catch(next);
+        }
+    };
+}

package/dist/helpers/headers.d.ts

@@ -0,0 +1,2 @@
+import { Response } from 'express';
+export declare function populateSecurityHeaders(res: Response): void;

package/dist/helpers/headers.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.populateSecurityHeaders = populateSecurityHeaders;
+function populateSecurityHeaders(res) {
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('X-Frame-Options', 'DENY');
+}

package/dist/helpers/health.d.ts

@@ -0,0 +1,2 @@
+import { Response } from 'express';
+export declare function systemHealthCheck(res: Response): void;

package/dist/helpers/health.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemHealthCheck = systemHealthCheck;
+function systemHealthCheck(res) {
+    res.status(200).json({
+        status: 'UP',
+        timestamp: new Date().toISOString(),
+        uptimeSec: process.uptime()
+    });
+}

package/dist/helpers/meta.d.ts

@@ -0,0 +1,2 @@
+import { ApiResponseMeta } from '../types/responses';
+export declare function constructBaseMeta(reqId: string, apiVersion?: string): ApiResponseMeta;

package/dist/helpers/meta.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.constructBaseMeta = constructBaseMeta;
+function constructBaseMeta(reqId, apiVersion) {
+    return {
+        requestId: reqId,
+        timestamp: new Date().toISOString(),
+        executionTimeMs: 0,
+        apiVersion
+    };
+}

package/dist/helpers/pagination.d.ts

@@ -0,0 +1,9 @@
+import { PaginationOptions } from '../types/responses';
+export declare function buildPaginationMeta(options: PaginationOptions): {
+    page: number;
+    limit: number;
+    totalElements: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+};

package/dist/helpers/pagination.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPaginationMeta = buildPaginationMeta;
+function buildPaginationMeta(options) {
+    const totalPages = Math.ceil(options.total / options.limit) || 1;
+    return {
+        page: options.page,
+        limit: options.limit,
+        totalElements: options.total,
+        totalPages,
+        hasNextPage: options.page < totalPages,
+        hasPrevPage: options.page > 1,
+    };
+}

package/dist/helpers/redirect.d.ts

@@ -0,0 +1,2 @@
+import { Response } from 'express';
+export declare function forceRedirect(res: Response, targetUrl: string, permanent?: boolean): void;

package/dist/helpers/redirect.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.forceRedirect = forceRedirect;
+function forceRedirect(res, targetUrl, permanent = false) {
+    res.redirect(permanent ? 301 : 302, targetUrl);
+}

package/dist/helpers/success.d.ts

@@ -0,0 +1,3 @@
+import { ResponseBuilder } from '../core/responseBuilder';
+import { Response } from 'express';
+export declare function sendSuccessResponse(res: Response, data: unknown, msg?: string): ResponseBuilder<unknown>;

package/dist/helpers/success.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendSuccessResponse = sendSuccessResponse;
+const responseFactory_1 = require("../core/responseFactory");
+function sendSuccessResponse(res, data, msg) {
+    return responseFactory_1.ResponseFactory.create(res, 200, true, 'SUCCESS', data, { message: msg });
+}

package/dist/helpers/validation.d.ts

@@ -0,0 +1,2 @@
+import { ValidationErrorItem } from '../types/responses';
+export declare function createValidationError(field: string, message: string, rule?: string): ValidationErrorItem;

package/dist/helpers/validation.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createValidationError = createValidationError;
+function createValidationError(field, message, rule) {
+    return { field, message, rule: rule || 'validation_rule' };
+}