xypriss 9.10.21 → 9.10.22

package/dist/cjs/src/index.js

@@ -16,6 +16,7 @@ var XyGuard = require('./server/routing/modules/XyGuard.js');
 var PluginHookIds = require('./plugins/const/PluginHookIds.js');
 var mergeWithDefaults = require('./utils/mergeWithDefaults.js');
 var getIp = require('./utils/getIp.js');
+var Send = require('./utils/Send.js');
 var ProjectDiscovery = require('./utils/ProjectDiscovery.js');
 var XemsPlugin = require('./plugins/builtin/xems/XemsPlugin.js');
 var getMime = require('./utils/getMime.js');
@@ -84,6 +85,7 @@ exports.PluginHookIds = PluginHookIds.PluginHookIds;
 exports.mergeWithDefaults = mergeWithDefaults.mergeWithDefaults;
 exports.mwdef = mergeWithDefaults.mergeWithDefaults;
 exports.getIp = getIp.getIp;
+exports.Send = Send.Send;
 exports.getCallerProjectRoot = ProjectDiscovery.getCallerProjectRoot;
 exports.identifyProjectRoot = ProjectDiscovery.identifyProjectRoot;
 exports.xems = XemsPlugin.xems;

package/dist/cjs/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/index.ts"],"sourcesContent":[null],"names":["configLoader","XyPrissRouter"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;;;;;AAsBiF;AACjF;AAEA;AACA;AAqBA;AACA,IAAI,OAAO,UAAU,KAAK,WAAW,EAAE;IACnCA,yBAAY,CAAC,qBAAqB,EAAE;AACxC;AA+BA;;AAEG;SACa,MAAM,GAAA;IAClB,OAAO,IAAIC,sBAAa,CAAC;AACrB,QAAA,aAAa,EAAE,KAAK;AACpB,QAAA,WAAW,EAAE,KAAK;AAClB,QAAA,MAAM,EAAE,KAAK;AAChB,KAAA,CAAC;AACN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":["../../../src/index.ts"],"sourcesContent":[null],"names":["configLoader","XyPrissRouter"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;;;;;AAsBiF;AACjF;AAEA;AACA;AAqBA;AACA,IAAI,OAAO,UAAU,KAAK,WAAW,EAAE;IACnCA,yBAAY,CAAC,qBAAqB,EAAE;AACxC;AA+BA;;AAEG;SACa,MAAM,GAAA;IAClB,OAAO,IAAIC,sBAAa,CAAC;AACrB,QAAA,aAAa,EAAE,KAAK;AACpB,QAAA,WAAW,EAAE,KAAK;AAClB,QAAA,MAAM,EAAE,KAAK;AAChB,KAAA,CAAC;AACN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/src/utils/Send.js

@@ -0,0 +1,170 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Derives a compact, uppercase error code from a {@link SupportedStatus} key.
+ *
+ * @example
+ * buildErrorCode("BAD_REQUEST")      // → "EBADR"
+ * buildErrorCode("INTERNAL_SERVER_ERR") // → "EINTE"
+ *
+ * @param status - The status key to convert.
+ * @returns A 5-character string starting with `"E"`.
+ */
+function buildErrorCode(status) {
+    // Remove all underscores, take first 4 chars, prepend "E"
+    return "E" + status.replace(/_/g, "").slice(0, 4).toUpperCase();
+}
+// ---------------------------------------------------------------------------
+// Default HTTP status code registry
+// ---------------------------------------------------------------------------
+const DEFAULT_CONFIGS = {
+    BAD_REQUEST: 400,
+    NOT_FOUND: 404,
+    TOO_MANY_REQUEST: 429,
+    INTERNAL_SERVER_ERR: 500,
+};
+// ---------------------------------------------------------------------------
+// Send class
+// ---------------------------------------------------------------------------
+/**
+ * A structured HTTP response helper that standardises all error responses
+ * across the application.
+ *
+ * Every method sends a JSON body conforming to {@link IResTemplate}, ensuring
+ * consistent error shapes for API consumers regardless of where the error
+ * originates.
+ *
+ * @example
+ * ```ts
+ * const send = new Send(res);
+ *
+ * // 400 – validation failure
+ * send.badRequest("The 'email' field is required.");
+ *
+ * // 404 – resource missing
+ * send.notFound("User not found.", { userId: 42 });
+ *
+ * // 429 – rate limit exceeded
+ * send.tooManyRequest("Too many requests. Please slow down.");
+ *
+ * // 500 – unexpected failure
+ * send.internalError("An unexpected error occurred.");
+ * ```
+ */
+class Send {
+    /**
+     * Creates a new `Send` instance bound to the given response object.
+     *
+     * @param res     - The active `XyPrisResponse` to write into.
+     * @param configs - Optional override for the default status-code registry.
+     *                  Useful for non-standard or custom HTTP codes.
+     */
+    constructor(res, configs = {
+        includeServerName: true,
+        statusCode: {},
+    }) {
+        // -------------------------------------------------------------------------
+        // Public methods
+        // -------------------------------------------------------------------------
+        /**
+         * Sends a **400 Bad Request** response.
+         *
+         * Use when the client submits a malformed or invalid request
+         * (e.g. missing required fields, invalid format, constraint violation).
+         *
+         * @param message - Human-readable explanation of why the request was rejected.
+         * @param data    - Optional payload (e.g. a list of validation errors per field).
+         *
+         * @example
+         * send.badRequest("The 'username' field must be at least 3 characters.");
+         * send.badRequest("Validation failed.", { fields: { email: "Invalid format" } });
+         */
+        this.badRequest = (message, data) => {
+            this.dispatch("BAD_REQUEST", "Bad Request", message, data);
+        };
+        /**
+         * Sends a **404 Not Found** response.
+         *
+         * Use when the requested resource does not exist or has been permanently removed.
+         *
+         * @param message - Human-readable explanation of what could not be found.
+         * @param data    - Optional payload (e.g. the identifier that was looked up).
+         *
+         * @example
+         * send.notFound("No user found with id '42'.");
+         * send.notFound("Resource not found.", { id: "42" });
+         */
+        this.notFound = (message, data) => {
+            this.dispatch("NOT_FOUND", "Not Found", message, data);
+        };
+        /**
+         * Sends a **429 Too Many Requests** response.
+         *
+         * Use when the client has exceeded an allowed request rate or quota.
+         * Consider pairing this with a `Retry-After` header at the middleware level.
+         *
+         * @param message - Human-readable explanation of the rate limit breach.
+         * @param data    - Optional payload (e.g. retry delay, remaining quota).
+         *
+         * @example
+         * send.tooManyRequest("Rate limit reached. Try again in 60 seconds.");
+         * send.tooManyRequest("Quota exceeded.", { retryAfter: 60 });
+         */
+        this.tooManyRequest = (message, data) => {
+            this.dispatch("TOO_MANY_REQUEST", "Too Many Requests", message, data);
+        };
+        /**
+         * Sends a **500 Internal Server Error** response.
+         *
+         * Use for unexpected, unhandled server-side failures.
+         * Avoid leaking internal stack traces or sensitive details in the message.
+         *
+         * @param message - Human-readable explanation safe to expose to the client.
+         * @param data    - Optional payload (use sparingly — never expose raw stack traces).
+         *
+         * @example
+         * send.internalError("An unexpected error occurred. Please try again later.");
+         */
+        this.internalError = (message, data) => {
+            this.dispatch("INTERNAL_SERVER_ERR", "Internal Server Error", message, data);
+        };
+        this.res = res;
+        this.configs = { ...DEFAULT_CONFIGS, ...configs.statusCode };
+        this.serverName = __sys__.vars.__name__;
+        this.includeServerName = configs?.includeServerName;
+    }
+    // -------------------------------------------------------------------------
+    // Core dispatcher
+    // -------------------------------------------------------------------------
+    /**
+     * Resolves the status code, builds the full response body, and flushes it.
+     *
+     * @param statusKey  - One of the {@link SupportedStatus} keys.
+     * @param errorLabel - Human-readable short label for the error type.
+     * @param message    - Optional caller-supplied message; falls back to `errorLabel`.
+     * @param data       - Optional payload to attach to the response body.
+     */
+    dispatch(statusKey, errorLabel, message, data) {
+        const statusCode = this.configs[statusKey];
+        const body = {
+            success: false,
+            message: message ?? errorLabel,
+            serverName: this.includeServerName
+                ? this.serverName
+                : undefined,
+            ...(data !== undefined && { data }),
+            details: {
+                error: errorLabel,
+                errorCode: buildErrorCode(statusKey),
+                statusCode,
+            },
+        };
+        this.res.status(statusCode).json(body);
+    }
+}
+
+exports.Send = Send;
+//# sourceMappingURL=Send.js.map

package/dist/cjs/src/utils/Send.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Send.js","sources":["../../../../src/utils/Send.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAsFA;AACA;AACA;AAEA;;;;;;;;;AASG;AACH,SAAS,cAAc,CAAC,MAAuB,EAAA;;IAE7C,OAAO,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE;AACjE;AAEA;AACA;AACA;AAEA,MAAM,eAAe,GAAe;AAClC,IAAA,WAAW,EAAE,GAAG;AAChB,IAAA,SAAS,EAAE,GAAG;AACd,IAAA,gBAAgB,EAAE,GAAG;AACrB,IAAA,mBAAmB,EAAE,GAAG;CACzB;AAED;AACA;AACA;AAEA;;;;;;;;;;;;;;;;;;;;;;;;AAwBG;MACU,IAAI,CAAA;AAMf;;;;;;AAMG;IACH,WAAA,CACE,GAAmB,EACnB,OAAA,GAGK;AACH,QAAA,iBAAiB,EAAE,IAAI;AACvB,QAAA,UAAU,EAAE,EAAE;AACf,KAAA,EAAA;;;;AAiDH;;;;;;;;;;;;AAYG;AACI,QAAA,IAAA,CAAA,UAAU,GAAiB,CAAC,OAAO,EAAE,IAAI,KAAI;YAClD,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,aAAa,EAAE,OAAO,EAAE,IAAI,CAAC;AAC5D,QAAA,CAAC;AAED;;;;;;;;;;;AAWG;AACI,QAAA,IAAA,CAAA,QAAQ,GAAiB,CAAC,OAAO,EAAE,IAAI,KAAI;YAChD,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC;AACxD,QAAA,CAAC;AAED;;;;;;;;;;;;AAYG;AACI,QAAA,IAAA,CAAA,cAAc,GAAiB,CAAC,OAAO,EAAE,IAAI,KAAI;YACtD,IAAI,CAAC,QAAQ,CAAC,kBAAkB,EAAE,mBAAmB,EAAE,OAAO,EAAE,IAAI,CAAC;AACvE,QAAA,CAAC;AAED;;;;;;;;;;;AAWG;AACI,QAAA,IAAA,CAAA,aAAa,GAAiB,CAAC,OAAO,EAAE,IAAI,KAAI;YACrD,IAAI,CAAC,QAAQ,CACX,qBAAqB,EACrB,uBAAuB,EACvB,OAAO,EACP,IAAI,CACL;AACH,QAAA,CAAC;AApHC,QAAA,IAAI,CAAC,GAAG,GAAG,GAAG;AACd,QAAA,IAAI,CAAC,OAAO,GAAG,EAAE,GAAG,eAAe,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE;QAC5D,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ;AACvC,QAAA,IAAI,CAAC,iBAAiB,GAAG,OAAO,EAAE,iBAAkB;IACtD;;;;AAMA;;;;;;;AAOG;AACK,IAAA,QAAQ,CACd,SAA0B,EAC1B,UAAkB,EAClB,OAAgB,EAChB,IAAc,EAAA;QAEd,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;AAE1C,QAAA,MAAM,IAAI,GAAiB;AACzB,YAAA,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,OAAO,IAAI,UAAU;YAC9B,UAAU,EAAE,IAAI,CAAC;kBACb,IAAI,CAAC;AACP,kBAAG,SAA4B;YACjC,IAAI,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC;AACnC,YAAA,OAAO,EAAE;AACP,gBAAA,KAAK,EAAE,UAAU;AACjB,gBAAA,SAAS,EAAE,cAAc,CAAC,SAAS,CAAC;gBACpC,UAAU;AACX,aAAA;SACF;AAED,QAAA,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;IACxC;AA4ED;;;;"}

package/dist/esm/src/index.js

@@ -14,6 +14,7 @@ export { XyGuard } from './server/routing/modules/XyGuard.js';
 export { PluginHookIds } from './plugins/const/PluginHookIds.js';
 export { mergeWithDefaults, mergeWithDefaults as mwdef } from './utils/mergeWithDefaults.js';
 export { getIp } from './utils/getIp.js';
+export { Send } from './utils/Send.js';
 export { getCallerProjectRoot, identifyProjectRoot } from './utils/ProjectDiscovery.js';
 export { xems } from './plugins/builtin/xems/XemsPlugin.js';
 export { getMime, getMimes } from './utils/getMime.js';

package/dist/esm/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;;;;;AAsBiF;AACjF;AAEA;AACA;AAqBA;AACA,IAAI,OAAO,UAAU,KAAK,WAAW,EAAE;IACnC,YAAY,CAAC,qBAAqB,EAAE;AACxC;AA+BA;;AAEG;SACa,MAAM,GAAA;IAClB,OAAO,IAAI,aAAa,CAAC;AACrB,QAAA,aAAa,EAAE,KAAK;AACpB,QAAA,WAAW,EAAE,KAAK;AAClB,QAAA,MAAM,EAAE,KAAK;AAChB,KAAA,CAAC;AACN;;;;"}
+{"version":3,"file":"index.js","sources":["../../../src/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;;;;;AAsBiF;AACjF;AAEA;AACA;AAqBA;AACA,IAAI,OAAO,UAAU,KAAK,WAAW,EAAE;IACnC,YAAY,CAAC,qBAAqB,EAAE;AACxC;AA+BA;;AAEG;SACa,MAAM,GAAA;IAClB,OAAO,IAAI,aAAa,CAAC;AACrB,QAAA,aAAa,EAAE,KAAK;AACpB,QAAA,WAAW,EAAE,KAAK;AAClB,QAAA,MAAM,EAAE,KAAK;AAChB,KAAA,CAAC;AACN;;;;"}

package/dist/esm/src/utils/Send.js

@@ -0,0 +1,168 @@
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Derives a compact, uppercase error code from a {@link SupportedStatus} key.
+ *
+ * @example
+ * buildErrorCode("BAD_REQUEST")      // → "EBADR"
+ * buildErrorCode("INTERNAL_SERVER_ERR") // → "EINTE"
+ *
+ * @param status - The status key to convert.
+ * @returns A 5-character string starting with `"E"`.
+ */
+function buildErrorCode(status) {
+    // Remove all underscores, take first 4 chars, prepend "E"
+    return "E" + status.replace(/_/g, "").slice(0, 4).toUpperCase();
+}
+// ---------------------------------------------------------------------------
+// Default HTTP status code registry
+// ---------------------------------------------------------------------------
+const DEFAULT_CONFIGS = {
+    BAD_REQUEST: 400,
+    NOT_FOUND: 404,
+    TOO_MANY_REQUEST: 429,
+    INTERNAL_SERVER_ERR: 500,
+};
+// ---------------------------------------------------------------------------
+// Send class
+// ---------------------------------------------------------------------------
+/**
+ * A structured HTTP response helper that standardises all error responses
+ * across the application.
+ *
+ * Every method sends a JSON body conforming to {@link IResTemplate}, ensuring
+ * consistent error shapes for API consumers regardless of where the error
+ * originates.
+ *
+ * @example
+ * ```ts
+ * const send = new Send(res);
+ *
+ * // 400 – validation failure
+ * send.badRequest("The 'email' field is required.");
+ *
+ * // 404 – resource missing
+ * send.notFound("User not found.", { userId: 42 });
+ *
+ * // 429 – rate limit exceeded
+ * send.tooManyRequest("Too many requests. Please slow down.");
+ *
+ * // 500 – unexpected failure
+ * send.internalError("An unexpected error occurred.");
+ * ```
+ */
+class Send {
+    /**
+     * Creates a new `Send` instance bound to the given response object.
+     *
+     * @param res     - The active `XyPrisResponse` to write into.
+     * @param configs - Optional override for the default status-code registry.
+     *                  Useful for non-standard or custom HTTP codes.
+     */
+    constructor(res, configs = {
+        includeServerName: true,
+        statusCode: {},
+    }) {
+        // -------------------------------------------------------------------------
+        // Public methods
+        // -------------------------------------------------------------------------
+        /**
+         * Sends a **400 Bad Request** response.
+         *
+         * Use when the client submits a malformed or invalid request
+         * (e.g. missing required fields, invalid format, constraint violation).
+         *
+         * @param message - Human-readable explanation of why the request was rejected.
+         * @param data    - Optional payload (e.g. a list of validation errors per field).
+         *
+         * @example
+         * send.badRequest("The 'username' field must be at least 3 characters.");
+         * send.badRequest("Validation failed.", { fields: { email: "Invalid format" } });
+         */
+        this.badRequest = (message, data) => {
+            this.dispatch("BAD_REQUEST", "Bad Request", message, data);
+        };
+        /**
+         * Sends a **404 Not Found** response.
+         *
+         * Use when the requested resource does not exist or has been permanently removed.
+         *
+         * @param message - Human-readable explanation of what could not be found.
+         * @param data    - Optional payload (e.g. the identifier that was looked up).
+         *
+         * @example
+         * send.notFound("No user found with id '42'.");
+         * send.notFound("Resource not found.", { id: "42" });
+         */
+        this.notFound = (message, data) => {
+            this.dispatch("NOT_FOUND", "Not Found", message, data);
+        };
+        /**
+         * Sends a **429 Too Many Requests** response.
+         *
+         * Use when the client has exceeded an allowed request rate or quota.
+         * Consider pairing this with a `Retry-After` header at the middleware level.
+         *
+         * @param message - Human-readable explanation of the rate limit breach.
+         * @param data    - Optional payload (e.g. retry delay, remaining quota).
+         *
+         * @example
+         * send.tooManyRequest("Rate limit reached. Try again in 60 seconds.");
+         * send.tooManyRequest("Quota exceeded.", { retryAfter: 60 });
+         */
+        this.tooManyRequest = (message, data) => {
+            this.dispatch("TOO_MANY_REQUEST", "Too Many Requests", message, data);
+        };
+        /**
+         * Sends a **500 Internal Server Error** response.
+         *
+         * Use for unexpected, unhandled server-side failures.
+         * Avoid leaking internal stack traces or sensitive details in the message.
+         *
+         * @param message - Human-readable explanation safe to expose to the client.
+         * @param data    - Optional payload (use sparingly — never expose raw stack traces).
+         *
+         * @example
+         * send.internalError("An unexpected error occurred. Please try again later.");
+         */
+        this.internalError = (message, data) => {
+            this.dispatch("INTERNAL_SERVER_ERR", "Internal Server Error", message, data);
+        };
+        this.res = res;
+        this.configs = { ...DEFAULT_CONFIGS, ...configs.statusCode };
+        this.serverName = __sys__.vars.__name__;
+        this.includeServerName = configs?.includeServerName;
+    }
+    // -------------------------------------------------------------------------
+    // Core dispatcher
+    // -------------------------------------------------------------------------
+    /**
+     * Resolves the status code, builds the full response body, and flushes it.
+     *
+     * @param statusKey  - One of the {@link SupportedStatus} keys.
+     * @param errorLabel - Human-readable short label for the error type.
+     * @param message    - Optional caller-supplied message; falls back to `errorLabel`.
+     * @param data       - Optional payload to attach to the response body.
+     */
+    dispatch(statusKey, errorLabel, message, data) {
+        const statusCode = this.configs[statusKey];
+        const body = {
+            success: false,
+            message: message ?? errorLabel,
+            serverName: this.includeServerName
+                ? this.serverName
+                : undefined,
+            ...(data !== undefined && { data }),
+            details: {
+                error: errorLabel,
+                errorCode: buildErrorCode(statusKey),
+                statusCode,
+            },
+        };
+        this.res.status(statusCode).json(body);
+    }
+}
+
+export { Send };
+//# sourceMappingURL=Send.js.map

package/dist/esm/src/utils/Send.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Send.js","sources":["../../../../src/utils/Send.ts"],"sourcesContent":[null],"names":[],"mappings":"AAsFA;AACA;AACA;AAEA;;;;;;;;;AASG;AACH,SAAS,cAAc,CAAC,MAAuB,EAAA;;IAE7C,OAAO,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE;AACjE;AAEA;AACA;AACA;AAEA,MAAM,eAAe,GAAe;AAClC,IAAA,WAAW,EAAE,GAAG;AAChB,IAAA,SAAS,EAAE,GAAG;AACd,IAAA,gBAAgB,EAAE,GAAG;AACrB,IAAA,mBAAmB,EAAE,GAAG;CACzB;AAED;AACA;AACA;AAEA;;;;;;;;;;;;;;;;;;;;;;;;AAwBG;MACU,IAAI,CAAA;AAMf;;;;;;AAMG;IACH,WAAA,CACE,GAAmB,EACnB,OAAA,GAGK;AACH,QAAA,iBAAiB,EAAE,IAAI;AACvB,QAAA,UAAU,EAAE,EAAE;AACf,KAAA,EAAA;;;;AAiDH;;;;;;;;;;;;AAYG;AACI,QAAA,IAAA,CAAA,UAAU,GAAiB,CAAC,OAAO,EAAE,IAAI,KAAI;YAClD,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,aAAa,EAAE,OAAO,EAAE,IAAI,CAAC;AAC5D,QAAA,CAAC;AAED;;;;;;;;;;;AAWG;AACI,QAAA,IAAA,CAAA,QAAQ,GAAiB,CAAC,OAAO,EAAE,IAAI,KAAI;YAChD,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC;AACxD,QAAA,CAAC;AAED;;;;;;;;;;;;AAYG;AACI,QAAA,IAAA,CAAA,cAAc,GAAiB,CAAC,OAAO,EAAE,IAAI,KAAI;YACtD,IAAI,CAAC,QAAQ,CAAC,kBAAkB,EAAE,mBAAmB,EAAE,OAAO,EAAE,IAAI,CAAC;AACvE,QAAA,CAAC;AAED;;;;;;;;;;;AAWG;AACI,QAAA,IAAA,CAAA,aAAa,GAAiB,CAAC,OAAO,EAAE,IAAI,KAAI;YACrD,IAAI,CAAC,QAAQ,CACX,qBAAqB,EACrB,uBAAuB,EACvB,OAAO,EACP,IAAI,CACL;AACH,QAAA,CAAC;AApHC,QAAA,IAAI,CAAC,GAAG,GAAG,GAAG;AACd,QAAA,IAAI,CAAC,OAAO,GAAG,EAAE,GAAG,eAAe,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE;QAC5D,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ;AACvC,QAAA,IAAI,CAAC,iBAAiB,GAAG,OAAO,EAAE,iBAAkB;IACtD;;;;AAMA;;;;;;;AAOG;AACK,IAAA,QAAQ,CACd,SAA0B,EAC1B,UAAkB,EAClB,OAAgB,EAChB,IAAc,EAAA;QAEd,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;AAE1C,QAAA,MAAM,IAAI,GAAiB;AACzB,YAAA,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,OAAO,IAAI,UAAU;YAC9B,UAAU,EAAE,IAAI,CAAC;kBACb,IAAI,CAAC;AACP,kBAAG,SAA4B;YACjC,IAAI,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC;AACnC,YAAA,OAAO,EAAE;AACP,gBAAA,KAAK,EAAE,UAAU;AACjB,gBAAA,SAAS,EAAE,cAAc,CAAC,SAAS,CAAC;gBACpC,UAAU;AACX,aAAA;SACF;AAED,QAAA,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;IACxC;AA4ED;;;;"}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { Server, IncomingMessage, ServerResponse } from 'http';
 import { SecureCacheAdapter } from 'xypriss-security';
 import * as reliant_type from 'reliant-type';
 import { Readable, Writable } from 'node:stream';
+import { XyPrisResponse as XyPrisResponse$2 } from 'xypriss';
 
 declare const LOG_LEVELS: readonly ["silent", "error", "warn", "info", "debug", "verbose"];
 type LogLevel = (typeof LOG_LEVELS)[number];
@@ -11142,6 +11143,176 @@ type IpSource = "cf-connecting-ip" | "true-client-ip" | "x-real-ip" | "x-forward
 declare function getIp(req: XyPrisRequest): string;
 declare function getIp(req: XyPrisRequest, enriched: true): GetIpResult;
 
+/**
+ * @file Send.ts
+ * @description Structured HTTP error response helper for the XyPriss framework.
+ *
+ * @copyright Copyright © 2025–2026 NEHONIX. All Rights Reserved.
+ * @license NEHONIX Open Source License v2.0 (NOSL v2)
+ *          https://dll.nehonix.com/licenses/NOSL/v2
+ *
+ * This file is part of a NEHONIX open source project.
+ * You may use, modify, and redistribute it freely — including for commercial
+ * purposes — provided that NEHONIX is always credited as the original author.
+ *
+ * @author NEHONIX
+ */
+
+/**
+ * All HTTP status keys supported by the `Send` helper.
+ * Each key maps to a standard HTTP status code.
+ */
+type SupportedStatus = "BAD_REQUEST" | "NOT_FOUND" | "TOO_MANY_REQUEST" | "INTERNAL_SERVER_ERR";
+/**
+ * Maps every {@link SupportedStatus} key to its corresponding HTTP status code.
+ */
+type ISeConfigs = Record<SupportedStatus, number>;
+/**
+ * Signature shared by all public error-dispatch methods.
+ *
+ * @param message - Human-readable description of the error shown to the API consumer.
+ * @param data    - Optional payload to attach to the response body (e.g. validation details).
+ */
+type TSendPropsFn = (message?: string, data?: unknown) => void;
+/**
+ * Contract that the {@link Send} class must satisfy.
+ * Ensures every supported error type exposes a consistent public API.
+ */
+interface ISeResponder {
+    badRequest: TSendPropsFn;
+    notFound: TSendPropsFn;
+    tooManyRequest: TSendPropsFn;
+    internalError: TSendPropsFn;
+}
+/**
+ * Shape of every JSON response body produced by this helper.
+ *
+ * @property success    - Always `false` for error responses.
+ * @property message    - Human-readable summary of the error.
+ * @property serverName - Identifier of the server that handled the request.
+ * @property data       - Optional payload (echoed from the caller when relevant).
+ * @property details    - Machine-readable error metadata.
+ */
+interface IResTemplate {
+    success: false;
+    message: string;
+    serverName: string;
+    data?: unknown;
+    details: {
+        /** Short error label (e.g. `"Bad Request"`). */
+        error: string;
+        /** Compact error code derived from the status key (e.g. `"EBADR"`). */
+        errorCode: string;
+        /** The HTTP status code that was sent. */
+        statusCode: number;
+    };
+}
+/**
+ * A structured HTTP response helper that standardises all error responses
+ * across the application.
+ *
+ * Every method sends a JSON body conforming to {@link IResTemplate}, ensuring
+ * consistent error shapes for API consumers regardless of where the error
+ * originates.
+ *
+ * @example
+ * ```ts
+ * const send = new Send(res);
+ *
+ * // 400 – validation failure
+ * send.badRequest("The 'email' field is required.");
+ *
+ * // 404 – resource missing
+ * send.notFound("User not found.", { userId: 42 });
+ *
+ * // 429 – rate limit exceeded
+ * send.tooManyRequest("Too many requests. Please slow down.");
+ *
+ * // 500 – unexpected failure
+ * send.internalError("An unexpected error occurred.");
+ * ```
+ */
+declare class Send implements ISeResponder {
+    private readonly res;
+    private readonly configs;
+    private readonly serverName;
+    private readonly includeServerName;
+    /**
+     * Creates a new `Send` instance bound to the given response object.
+     *
+     * @param res     - The active `XyPrisResponse` to write into.
+     * @param configs - Optional override for the default status-code registry.
+     *                  Useful for non-standard or custom HTTP codes.
+     */
+    constructor(res: XyPrisResponse$2, configs?: Partial<{
+        statusCode: Partial<ISeConfigs>;
+        includeServerName: boolean;
+    }>);
+    /**
+     * Resolves the status code, builds the full response body, and flushes it.
+     *
+     * @param statusKey  - One of the {@link SupportedStatus} keys.
+     * @param errorLabel - Human-readable short label for the error type.
+     * @param message    - Optional caller-supplied message; falls back to `errorLabel`.
+     * @param data       - Optional payload to attach to the response body.
+     */
+    private dispatch;
+    /**
+     * Sends a **400 Bad Request** response.
+     *
+     * Use when the client submits a malformed or invalid request
+     * (e.g. missing required fields, invalid format, constraint violation).
+     *
+     * @param message - Human-readable explanation of why the request was rejected.
+     * @param data    - Optional payload (e.g. a list of validation errors per field).
+     *
+     * @example
+     * send.badRequest("The 'username' field must be at least 3 characters.");
+     * send.badRequest("Validation failed.", { fields: { email: "Invalid format" } });
+     */
+    badRequest: TSendPropsFn;
+    /**
+     * Sends a **404 Not Found** response.
+     *
+     * Use when the requested resource does not exist or has been permanently removed.
+     *
+     * @param message - Human-readable explanation of what could not be found.
+     * @param data    - Optional payload (e.g. the identifier that was looked up).
+     *
+     * @example
+     * send.notFound("No user found with id '42'.");
+     * send.notFound("Resource not found.", { id: "42" });
+     */
+    notFound: TSendPropsFn;
+    /**
+     * Sends a **429 Too Many Requests** response.
+     *
+     * Use when the client has exceeded an allowed request rate or quota.
+     * Consider pairing this with a `Retry-After` header at the middleware level.
+     *
+     * @param message - Human-readable explanation of the rate limit breach.
+     * @param data    - Optional payload (e.g. retry delay, remaining quota).
+     *
+     * @example
+     * send.tooManyRequest("Rate limit reached. Try again in 60 seconds.");
+     * send.tooManyRequest("Quota exceeded.", { retryAfter: 60 });
+     */
+    tooManyRequest: TSendPropsFn;
+    /**
+     * Sends a **500 Internal Server Error** response.
+     *
+     * Use for unexpected, unhandled server-side failures.
+     * Avoid leaking internal stack traces or sensitive details in the message.
+     *
+     * @param message - Human-readable explanation safe to expose to the client.
+     * @param data    - Optional payload (use sparingly — never expose raw stack traces).
+     *
+     * @example
+     * send.internalError("An unexpected error occurred. Please try again later.");
+     */
+    internalError: TSendPropsFn;
+}
+
 /**
  * Identifies the project root for a given caller path by traversing up the filesystem.
  */
@@ -11447,5 +11618,5 @@ declare class XStatic {
  */
 declare function Router(): XyPrissRouter;
 
-export { ConfigurationManager as CM, ConfigurationManager as Configs, FileUploadAPI as FLA, FileUploadAPI, Plugin, PluginHookIds, Router, SecurityMiddleware, Upload, XJsonResponseHandler, XStatic, XyGuard, MultiServerApp as XyPMS, XyPrissRouter, XyPrissXHSC, __cfg__, __const__, __sys__, createOptimalCache, createServer, getCallerProjectRoot, getIp, getMime, getMimes, identifyProjectRoot, initializeFileUpload, mergeWithDefaults, mergeWithDefaults as mwdef, quickServer, uploadAny, uploadArray, uploadFields, uploadSingle, xems };
-export type { ArchiveOptions, BatchRenameChange, CacheConfig, FileUploadConfig as FiUpConfig, FileUploadConfig, GetIpResult, IpSource, MonitorSnapshot, MultiServerConfig, NetworkStats, NextFunction, PerformanceConfig, PluginCreator, PluginServer, ProcessInfo, ProcessMonitorSnapshot, XyPrisRequest as Request, RequestHandler, XyPrisResponse as Response, RoutRateLimit, RouteConfig, RouteGuard, RouteMeta, RouteOptions, ParamType as RouteParamType, SecurityConfig, ServerOptions$1 as ServerOptions, XyPrisRequest$1 as XRequest, XyPrisResponse$1 as XResponse, XemsTypes, XyPrisRequest$1 as XyPrisRequest, XyPrisResponse$1 as XyPrisResponse, XyPrissApp, XyPrissPlugin };
+export { ConfigurationManager as CM, ConfigurationManager as Configs, FileUploadAPI as FLA, FileUploadAPI, Plugin, PluginHookIds, Router, SecurityMiddleware, Send, Upload, XJsonResponseHandler, XStatic, XyGuard, MultiServerApp as XyPMS, XyPrissRouter, XyPrissXHSC, __cfg__, __const__, __sys__, createOptimalCache, createServer, getCallerProjectRoot, getIp, getMime, getMimes, identifyProjectRoot, initializeFileUpload, mergeWithDefaults, mergeWithDefaults as mwdef, quickServer, uploadAny, uploadArray, uploadFields, uploadSingle, xems };
+export type { ArchiveOptions, BatchRenameChange, CacheConfig, FileUploadConfig as FiUpConfig, FileUploadConfig, GetIpResult, IResTemplate, ISeConfigs, ISeResponder, IpSource, MonitorSnapshot, MultiServerConfig, NetworkStats, NextFunction, PerformanceConfig, PluginCreator, PluginServer, ProcessInfo, ProcessMonitorSnapshot, XyPrisRequest as Request, RequestHandler, XyPrisResponse as Response, RoutRateLimit, RouteConfig, RouteGuard, RouteMeta, RouteOptions, ParamType as RouteParamType, SecurityConfig, ServerOptions$1 as ServerOptions, SupportedStatus, TSendPropsFn, XyPrisRequest$1 as XRequest, XyPrisResponse$1 as XResponse, XemsTypes, XyPrisRequest$1 as XyPrisRequest, XyPrisResponse$1 as XyPrisResponse, XyPrissApp, XyPrissPlugin };

package/package.json

@@ -68,6 +68,6 @@
     },
     "type": "module",
     "types": "./dist/index.d.ts",
-    "version": "9.10.21"
+    "version": "9.10.22"
 }