express-resforge 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.0.0] - 2026-07-13
+
+### Added
+- **Core Orchestration:** Initialized global `apiKit` gateway tracking configuration framework supporting unified response structures.
+- **Fluent Builder System:** Added `ResponseBuilder` supporting fluent chaining methods for metadata payloads, business response codes, cookies, and HTTP headers.
+- **Asynchronous Resiliency:** Implemented `apiKit.async()` higher-order function wrappers to intercept unhandled asynchronous promise rejections across application routes.
+- **Context Isolation Engine:** Integrated low-overhead `AsyncLocalStorage` via `context.ts` to manage unique correlation transaction IDs and tracking timers across requests.
+- **Ecosystem Validation Adapters:** Added out-of-the-box data normalization error formatters for third-party libraries: `Zod`, `Joi`, `Mongoose`, `Prisma`, `Axios`, and `Firebase`.
+- **Comprehensive Testing Infrastructure:** Built out integration test runners (`tests/integration/apiKit.test.ts`) and targeted optimization paths (`tests/unit/formatters.test.ts`, `tests/unit/coverageHitter.test.ts`).
+- **SWC Compilation Pipeline:** Migrated test execution layer to `@swc/jest` to reduce runtime processing latency (~0.45s execution benchmarks).
+
+### Fixed
+- **HTTP Node Lifecycle Crash:** Patched response timing calculation bugs in `requestTimer.ts` by safely overriding the native `res.end` pointer to bind headers before network streams freeze (resolving "Cannot set headers after they are sent to the client" errors).
+- **TypeScript Type Safety Mismatch:** Resolved dynamic compiler inference properties blocks during deep objects merging by wrapping the `deepMerge` validation tests into explicit target typings.
+
+### Safety
+- **Prototype Pollution Shielding:** Hardened `deepMerge.ts` utility configurations to completely block malicious object property injections via `__proto__` and `constructor` access routes.
+- **Information Leak Sanitization:** Implemented stack trace masking filters across production execution mode states inside the global boundary error catcher framework.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dream Mythic Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,309 @@
+
+# express-resforge
+
+[![npm version](https://img.shields.io/npm/v/express-resforge.svg?style=flat-block)](https://www.npmjs.com/package/express-resforge)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-block)](https://opensource.org/licenses/MIT)
+[![Coverage Status](https://img.shields.io/badge/coverage-90%25-green.svg?style=flat-block)](https://github.com/vaibhavdhake123/express-resforge)
+
+An enterprise-quality, zero-dependency engine designed to standardize API response envelopes, orchestrate asynchronous error pipelines, format third-party library errors, and trace high-precision performance metrics across Express microservices.
+
+Compatible out-of-the-box with **Express v4**, **Express v5**, **ESM**, and **CommonJS** targets running on Node.js 18+.
+
+---
+
+## 🏗️ Core Architecture Flow
+
+When an HTTP request enters your application, `express-resforge` handles the lifecycle safely without causing memory overhead or thread-blocking issues:
+
+
+```
+
+[Incoming Request]
+│
+▼
+┌────────────────────────────────┐
+│  apiKit.requestId() & timer()  │ ──► Allocates transaction UUIDs & high-precision tracking
+└────────────────────────────────┘
+│
+▼
+┌────────────────────────────────┐
+│      apiKit.middleware()       │ ──► Dynamically injects semantic shortcuts onto `res`
+└────────────────────────────────┘
+│
+▼
+┌────────────────────────────────┐
+│    App Business Controllers    │ ──► Run workflows through fluent builders (e.g., `res.success()`)
+└────────────────────────────────┘
+│
+▼
+┌────────────────────────────────┐
+│      Plugin Interceptors       │ ──► Append global telemetry/metadata on the fly
+└────────────────────────────────┘
+│
+▼
+┌────────────────────────────────┐
+│      apiKit.errorHandler()     │ ──► Catches runtime failures & masks internal stack traces
+└────────────────────────────────┘
+│
+▼
+[Outbound Standardized JSON]
+
+```
+
+---
+
+## 🛠️ Installation
+
+Install the package via npm:
+
+```bash
+npm install express-resforge
+
+```
+
+---
+
+## 🚀 Quick Start Guide
+
+### 1. Initialize Global Middlewares
+
+Mount the `express-resforge` middleware core engine at the top of your Express application definition stack:
+
+```typescript
+import express from 'express';
+import { apiKit } from 'express-resforge';
+
+const app = express();
+app.use(express.json());
+
+// 1. Mount isolated request lifecycle tracing systems
+app.use(apiKit.requestId());
+app.use(apiKit.requestTimer());
+
+// 2. Initialize global configuration middleware
+app.use(apiKit.middleware({
+  apiVersion: 'v1.0.0',
+  errors: { 
+    exposeStack: process.env.NODE_ENV === 'development',
+    sanitizeServerErrors: true 
+  }
+}));
+
+```
+
+### 2. Implement Standard Route Handlers
+
+Eliminate boilerplate blocks using the native, higher-order asynchronous wrapper `apiKit.async()` combined with semantic response triggers:
+
+```typescript
+// Traditional clean controller pattern
+app.get('/api/users/:id', apiKit.async(async (req, res) => {
+  const user = await database.find(req.params.id);
+  
+  if (!user) {
+    return res.notFound({ message: 'Target user profile does not exist.' }).send();
+  }
+  
+  return res.success(user).message('Profile loaded successfully.').send();
+}));
+
+```
+
+### 3. Advanced Fluent Chaining Builder Mechanics
+
+You can cleanly string together custom statuses, business workflow tracking codes, HTTP headers, and secure cookie properties in a single statement:
+
+```typescript
+app.post('/api/auth/login', apiKit.async(async (req, res) => {
+  const session = await authEngine.authenticate(req.body);
+  
+  return res.created(session)
+    .message('Authentication transaction finalized.')
+    .code('AUTH_PROCESSED_SUCCESSFULLY')
+    .header('X-Auth-Token', session.token)
+    .cookie('sid', session.id, { httpOnly: true, secure: true })
+    .send();
+}));
+
+```
+
+### 4. Automatic Automated Pagination Calculation
+
+Pass raw list inputs along with pagination parameters. `express-resforge` automatically calculates bounding limits, total pages, and boolean indicators:
+
+```typescript
+app.get('/api/products', apiKit.async(async (req, res) => {
+  const products = await database.fetchBatch({ offset: 10, limit: 10 });
+  
+  // Generates complete totalPages, hasNextPage, and hasPrevPage blocks natively
+  return res.paginate(products, { page: 2, limit: 10, total: 45 })
+    .message('Paginated product inventory batch loaded.')
+    .send();
+}));
+
+```
+
+### 5. Mount the Catch-All Resilient Error Boundary
+
+Place the global exception boundary tracker at the final exit boundary of your route stack to intercept uncaught failures:
+
+```typescript
+// Always register the error orchestrator after all active operational routes
+app.use(apiKit.errorHandler());
+
+```
+
+---
+
+## 🔌 Global Plugin System Interceptors
+
+You can hook into the payload formatting engine globally to inject custom tags, regional cloud location traces, or real-time tracking hashes right before the data hits the network stream:
+
+```typescript
+import { apiKit } from 'express-resforge';
+
+apiKit.use((payload, req, res) => {
+  // Inject microservice cloud node location tags safely
+  payload.meta.serverCluster = "aws-us-east-1-prod-node";
+  return payload;
+});
+
+```
+
+---
+
+## 💎 Ecosystem Error Formatters Matrix
+
+Convert diverse validation exceptions from third-party ecosystems into uniform validation shapes. You can parse anomalies explicitly or let the error handler format them automatically:
+
+```typescript
+import { apiKit } from 'express-resforge';
+
+app.post('/api/register', (req, res) => {
+  const validation = myZodSchema.safeParse(req.body);
+  
+  if (!validation.success) {
+    // Standardizes Zod internal diagnostics into a flat ValidationErrorItem array
+    const cleanErrors = apiKit.formatters.zod(validation.error);
+    return res.unprocessable({ errors: cleanErrors }).send();
+  }
+  
+  res.created(validation.data).send();
+});
+
+```
+
+Supported out-of-the-box engines include:
+
+* `apiKit.formatters.zod(error)`
+* `apiKit.formatters.joi(error)`
+* `apiKit.formatters.prisma(error)`
+* `apiKit.formatters.mongoose(error)`
+* `apiKit.formatters.axios(error)`
+* `apiKit.formatters.firebase(error)`
+
+---
+
+## 📊 Standard Response Schema Envelope
+
+Every payload delivered down the wire matches this production schema model:
+
+### Standard Success Response Output
+
+```json
+{
+  "success": true,
+  "statusCode": 200,
+  "responseCode": "SUCCESS",
+  "message": "Profile loaded successfully.",
+  "data": {
+    "profileId": 42
+  },
+  "meta": {
+    "requestId": "e30e9d6d-2c81-4b13-be8e-73cb1a4d8d1f",
+    "timestamp": "2026-07-13T07:07:00.000Z",
+    "executionTimeMs": 1.42,
+    "apiVersion": "v1.0.0",
+    "serverCluster": "aws-us-east-1-prod-node"
+  }
+}
+
+```
+
+### Standard Paginated Response Output
+
+```json
+{
+  "success": true,
+  "statusCode": 200,
+  "responseCode": "SUCCESS",
+  "message": "Paginated product inventory batch loaded.",
+  "data": [{ "id": 101 }, { "id": 102 }],
+  "pagination": {
+    "page": 2,
+    "limit": 10,
+    "totalElements": 45,
+    "totalPages": 5,
+    "hasNextPage": true,
+    "hasPrevPage": true
+  },
+  "meta": {
+    "requestId": "fa925bc0-80d4-4ce6-a6de-12e09b30c511",
+    "timestamp": "2026-07-13T07:07:05.000Z",
+    "executionTimeMs": 2.10,
+    "apiVersion": "v1.0.0"
+  }
+}
+
+```
+
+---
+
+## 📋 API Helper Reference Matrix
+
+| Response Helper Method | Status Code | Default Internal System Code |
+| --- | --- | --- |
+| `res.success(data, options)` | `200` | `SUCCESS` |
+| `res.created(data, options)` | `201` | `CREATED` |
+| `res.accepted(data, options)` | `202` | `ACCEPTED` |
+| `res.deleted(options)` | `200` | `DELETED` |
+| `res.noContent()` | `204` | *Empty Body Response* |
+| `res.badRequest(options)` | `400` | `BAD_REQUEST` |
+| `res.unauthorized(options)` | `401` | `UNAUTHORIZED` |
+| `res.forbidden(options)` | `403` | `FORBIDDEN` |
+| `res.notFound(options)` | `404` | `RESOURCE_NOT_FOUND` |
+| `res.conflict(options)` | `409` | `RESOURCE_CONFLICT` |
+| `res.unprocessable(options)` | `422` | `VALIDATION_FAILED` |
+| `res.tooManyRequests(options)` | `429` | `RATE_LIMIT_EXCEEDED` |
+| `res.serverError(options)` | `500` | `INTERNAL_SERVER_ERROR` |
+
+---
+
+## 🛡️ Security Best Practices Enforced
+
+* **Prototype Pollution Immunity:** Internal utility methods run isolated loop boundaries that filter out malicious object injection hashes via key hooks like `__proto__` or `constructor`.
+* **Leak Protection Sanitation:** When production settings are active, system level exception dumps (database driver timeouts, runtime faults) are cleanly scrubbed out. The client gets a clear error reference code without revealing system details.
+
+---
+
+## 📄 License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+---
+
+## 👥 Maintained By
+
+**Dream Mythic Studio**  
+Founded and maintained by **Vaibhav Dhake**.
+
+- **Founder & Lead Developer:** Vaibhav Dhake
+- **Studio:** Dream Mythic Studio
+- **GitHub:** https://github.com/vaibhavdhake123
+
+For bug reports, feature requests, discussions, or contributions, please open an issue or submit a pull request on the official repository:
+
+**Repository:** https://github.com/vaibhavdhake123/express-resforge
+
+Built with ❤️ by **Dream Mythic Studio**.
+

package/dist/constants/defaultMessages.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Fallback natural language message strings tied directly to HTTP states.
+ * Sealed at runtime to protect consistency across endpoint distributions.
+ */
+export declare const DefaultMessages: Record<number, string>;

package/dist/constants/defaultMessages.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultMessages = void 0;
+const httpStatus_1 = require("./httpStatus");
+/**
+ * @fileoverview Fallback natural language message strings tied directly to HTTP states.
+ * Sealed at runtime to protect consistency across endpoint distributions.
+ */
+exports.DefaultMessages = {
+    // 2xx Success States
+    [httpStatus_1.HttpStatus.OK]: 'Operation completed successfully.',
+    [httpStatus_1.HttpStatus.CREATED]: 'Resource was successfully created.',
+    [httpStatus_1.HttpStatus.ACCEPTED]: 'Request accepted and is processing asynchronously.',
+    [httpStatus_1.HttpStatus.NO_CONTENT]: 'Request processed successfully with empty content.',
+    // 4xx Client Error States
+    [httpStatus_1.HttpStatus.BAD_REQUEST]: 'The request payload is invalid or malformed.',
+    [httpStatus_1.HttpStatus.UNAUTHORIZED]: 'Authentication is required to access this resource.',
+    [httpStatus_1.HttpStatus.FORBIDDEN]: 'You do not possess the necessary privileges for this resource.',
+    [httpStatus_1.HttpStatus.NOT_FOUND]: 'The requested resource could not be found.',
+    [httpStatus_1.HttpStatus.CONFLICT]: 'A state conflict occurred while processing the resource.',
+    [httpStatus_1.HttpStatus.UNPROCESSABLE_ENTITY]: 'Validation failed for the submitted parameters.',
+    [httpStatus_1.HttpStatus.TOO_MANY_REQUESTS]: 'Rate limit exceeded. Please try again later.',
+    // 5xx Server Error States
+    [httpStatus_1.HttpStatus.INTERNAL_SERVER_ERROR]: 'An unexpected internal server error occurred.',
+    [httpStatus_1.HttpStatus.NOT_IMPLEMENTED]: 'The requested endpoint capability is not implemented.',
+    [httpStatus_1.HttpStatus.SERVICE_UNAVAILABLE]: 'The server is temporarily down or overloaded.',
+};
+// Lock down the object at runtime to prevent accidental mutation drift
+Object.freeze(exports.DefaultMessages);

package/dist/constants/httpStatus.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview RFC-compliant HTTP Status Codes mapped as immutable constant bindings.
+ * Optimized via Object.freeze to eliminate runtime mutation risks.
+ */
+export declare const HttpStatus: {
+    readonly OK: 200;
+    readonly CREATED: 201;
+    readonly ACCEPTED: 202;
+    readonly NO_CONTENT: 204;
+    readonly MOVED_PERMANENTLY: 301;
+    readonly FOUND: 302;
+    readonly NOT_MODIFIED: 304;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly METHOD_NOT_ALLOWED: 405;
+    readonly CONFLICT: 409;
+    readonly UNPROCESSABLE_ENTITY: 422;
+    readonly TOO_MANY_REQUESTS: 429;
+    readonly INTERNAL_SERVER_ERROR: 500;
+    readonly NOT_IMPLEMENTED: 501;
+    readonly SERVICE_UNAVAILABLE: 503;
+};
+/**
+ * Type-safe representation extracted from the immutable HttpStatus dictionary.
+ */
+export type HttpStatusType = typeof HttpStatus[keyof typeof HttpStatus];

package/dist/constants/httpStatus.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * @fileoverview RFC-compliant HTTP Status Codes mapped as immutable constant bindings.
+ * Optimized via Object.freeze to eliminate runtime mutation risks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpStatus = void 0;
+exports.HttpStatus = {
+    // 2xx Success
+    OK: 200,
+    CREATED: 201,
+    ACCEPTED: 202,
+    NO_CONTENT: 204,
+    // 3xx Redirection
+    MOVED_PERMANENTLY: 301,
+    FOUND: 302,
+    NOT_MODIFIED: 304,
+    // 4xx Client Errors
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    METHOD_NOT_ALLOWED: 405,
+    CONFLICT: 409,
+    UNPROCESSABLE_ENTITY: 422,
+    TOO_MANY_REQUESTS: 429,
+    // 5xx Server Errors
+    INTERNAL_SERVER_ERROR: 500,
+    NOT_IMPLEMENTED: 501,
+    SERVICE_UNAVAILABLE: 503,
+};
+// Lock down the object at runtime to prevent accidental engineering drift or pollution
+Object.freeze(exports.HttpStatus);

package/dist/constants/responseCodes.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Unique enterprise-standard alpha string identifiers for runtime states.
+ * Sealed at compile-time and runtime to protect tracking consistency.
+ */
+export declare const ResponseCodes: {
+    readonly SUCCESS: "SUCCESS";
+    readonly CREATED: "CREATED";
+    readonly ACCEPTED: "ACCEPTED";
+    readonly DELETED: "DELETED";
+    readonly NO_CONTENT: "NO_CONTENT";
+    readonly BAD_REQUEST: "BAD_REQUEST";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly NOT_FOUND: "RESOURCE_NOT_FOUND";
+    readonly CONFLICT: "RESOURCE_CONFLICT";
+    readonly UNPROCESSABLE: "VALIDATION_FAILED";
+    readonly TOO_MANY_REQUESTS: "RATE_LIMIT_EXCEEDED";
+    readonly SERVER_ERROR: "INTERNAL_SERVER_ERROR";
+    readonly NOT_IMPLEMENTED: "NOT_IMPLEMENTED";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+};
+export type ResponseCodeType = typeof ResponseCodes[keyof typeof ResponseCodes];

package/dist/constants/responseCodes.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * @fileoverview Unique enterprise-standard alpha string identifiers for runtime states.
+ * Sealed at compile-time and runtime to protect tracking consistency.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResponseCodes = void 0;
+exports.ResponseCodes = {
+    SUCCESS: "SUCCESS",
+    CREATED: "CREATED",
+    ACCEPTED: "ACCEPTED",
+    DELETED: "DELETED",
+    NO_CONTENT: "NO_CONTENT",
+    BAD_REQUEST: "BAD_REQUEST",
+    UNAUTHORIZED: "UNAUTHORIZED",
+    FORBIDDEN: "FORBIDDEN",
+    NOT_FOUND: "RESOURCE_NOT_FOUND",
+    CONFLICT: "RESOURCE_CONFLICT",
+    UNPROCESSABLE: "VALIDATION_FAILED",
+    TOO_MANY_REQUESTS: "RATE_LIMIT_EXCEEDED",
+    SERVER_ERROR: "INTERNAL_SERVER_ERROR",
+    NOT_IMPLEMENTED: "NOT_IMPLEMENTED",
+    SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE",
+};
+Object.freeze(exports.ResponseCodes);

package/dist/core/context.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Isolation store tracking scoped transaction states using AsyncLocalStorage.
+ */
+export interface RequestStoreContext {
+    requestId: string;
+    startTime: [number, number];
+    timestamp: string;
+}
+/**
+ * Encapsulated storage wrapper enforcing strict access limits on request variables.
+ */
+declare class RequestContextManager {
+    private readonly storage;
+    /**
+     * Wraps an execution thread pipeline inside a persistent scoped contextual tracking space.
+     * @param context Pre-populated execution variables for the tracking boundary.
+     * @param next Next async execution block to process inside isolation.
+     */
+    run<R>(context: RequestStoreContext, next: () => R): R;
+    /**
+     * Fetches the current request's active execution context safely.
+     * Returns undefined if accessed outside an active express execution line.
+     */
+    getStore(): RequestStoreContext | undefined;
+    /**
+     * Programmatically retrieves the active request ID.
+     * Returns a clean empty string if no tracking frame is active.
+     */
+    getRequestId(): string;
+    /**
+     * Computes high-precision microsecond differential calculations tracking current duration bounds.
+     */
+    getExecutionTimeMs(): number;
+}
+export declare const requestContext: RequestContextManager;
+export {};

package/dist/core/context.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestContext = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+/**
+ * Encapsulated storage wrapper enforcing strict access limits on request variables.
+ */
+class RequestContextManager {
+    storage = new node_async_hooks_1.AsyncLocalStorage();
+    /**
+     * Wraps an execution thread pipeline inside a persistent scoped contextual tracking space.
+     * @param context Pre-populated execution variables for the tracking boundary.
+     * @param next Next async execution block to process inside isolation.
+     */
+    run(context, next) {
+        return this.storage.run(context, next);
+    }
+    /**
+     * Fetches the current request's active execution context safely.
+     * Returns undefined if accessed outside an active express execution line.
+     */
+    getStore() {
+        return this.storage.getStore();
+    }
+    /**
+     * Programmatically retrieves the active request ID.
+     * Returns a clean empty string if no tracking frame is active.
+     */
+    getRequestId() {
+        return this.storage.getStore()?.requestId ?? '';
+    }
+    /**
+     * Computes high-precision microsecond differential calculations tracking current duration bounds.
+     */
+    getExecutionTimeMs() {
+        const store = this.storage.getStore();
+        if (!store)
+            return 0;
+        const diff = process.hrtime(store.startTime);
+        // Convert [seconds, nanoseconds] directly to highly readable float milliseconds
+        const ms = (diff[0] * 1000) + (diff[1] / 1000000);
+        return Math.round(ms * 100) / 100; // Constrain decimal drift to two accurate fraction spaces
+    }
+}
+exports.requestContext = new RequestContextManager();

package/dist/core/formatter.d.ts

@@ -0,0 +1,7 @@
+import { ValidationErrorItem } from '../types/responses';
+export declare class CentralFormatter {
+    /**
+     * Safe execution wrapper that maps custom library errors using specified formatter rules.
+     */
+    static format(formatterFn: (err: any) => ValidationErrorItem[], error: any): ValidationErrorItem[];
+}

package/dist/core/formatter.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CentralFormatter = void 0;
+class CentralFormatter {
+    /**
+     * Safe execution wrapper that maps custom library errors using specified formatter rules.
+     */
+    static format(formatterFn, error) {
+        try {
+            return formatterFn(error);
+        }
+        catch {
+            return [{ field: 'unknown', message: 'An unparseable validation fault occurred.' }];
+        }
+    }
+}
+exports.CentralFormatter = CentralFormatter;

package/dist/core/pluginManager.d.ts

@@ -0,0 +1,27 @@
+import { StandardApiResponse } from '../types/responses';
+/**
+ * Signature function blueprint for all custom response interceptor plugins.
+ */
+export type ApiKitPlugin = (payload: StandardApiResponse<any>, req: any, res: any) => StandardApiResponse<any>;
+/**
+ * Orchestration engine managing registration and execution lifecycle of custom plugins.
+ */
+export declare class PluginManager {
+    private readonly plugins;
+    /**
+     * Registers a global plugin hook into the internal pipeline.
+     * @param plugin The execution interceptor function block.
+     */
+    use(plugin: ApiKitPlugin): void;
+    /**
+     * 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: StandardApiResponse<any>, req: any, res: any): StandardApiResponse<any>;
+}
+export declare const globalPluginManager: PluginManager;