@divine-lab/request 1.0.1

package/LICENSE

@@ -0,0 +1,10 @@
+All Rights Reserved
+
+Copyright (c) 2026 Divine Lab
+
+Permission to view and use this software for personal,
+non-commercial purposes is granted.
+
+Any commercial use, redistribution, modification,
+sublicensing, or publication requires explicit written
+permission from the author.

package/dist/errors/APIError.d.ts

@@ -0,0 +1,26 @@
+import { type ServerErrorOptions, type ServerErrorKey } from "../errors/BackendErrors";
+/** Custom API Error class for standardized error handling
+ * @extends Error
+ * @example
+ * ```ts
+ * throw new APIError("NOT_FOUND", { title: "Resource Not Found", detail: "The requested resource was not found." });
+ * ```
+ */
+export declare class APIError extends Error {
+    readonly error: ServerErrorKey;
+    readonly status: number;
+    readonly title: string;
+    readonly detail: string;
+    readonly type: string;
+    readonly data: any;
+    /**
+     * Creates an instance of APIError.
+     * @param error - error code or identifier from SERVER_ERRORS
+     * @param options - additional error details (title, detail, type, data)
+     * @example
+     * ```ts
+     * throw new APIError("NOT_FOUND", { title: "Resource Not Found", detail: "The requested resource was not found." });
+     * ```
+     */
+    constructor(error: ServerErrorKey, { title, detail, type, data, status }?: ServerErrorOptions);
+}

package/dist/errors/APIError.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIError = void 0;
+const BackendErrors_1 = require("../errors/BackendErrors");
+/** Custom API Error class for standardized error handling
+ * @extends Error
+ * @example
+ * ```ts
+ * throw new APIError("NOT_FOUND", { title: "Resource Not Found", detail: "The requested resource was not found." });
+ * ```
+ */
+class APIError extends Error {
+    error;
+    status;
+    title;
+    detail;
+    type;
+    data;
+    /**
+     * Creates an instance of APIError.
+     * @param error - error code or identifier from SERVER_ERRORS
+     * @param options - additional error details (title, detail, type, data)
+     * @example
+     * ```ts
+     * throw new APIError("NOT_FOUND", { title: "Resource Not Found", detail: "The requested resource was not found." });
+     * ```
+     */
+    constructor(error, { title, detail, type, data, status } = {}) {
+        const errorDef = BackendErrors_1.SERVER_ERRORS[error];
+        super(title);
+        this.error = error;
+        this.status = status || errorDef.status;
+        this.title = title || errorDef.title;
+        this.detail = detail || errorDef.detail;
+        this.type = type || errorDef.type;
+        this.data = data || null;
+        Object.setPrototypeOf(this, APIError.prototype);
+    }
+}
+exports.APIError = APIError;

package/dist/errors/BackendErrors.d.ts

@@ -0,0 +1,63 @@
+/** Defines standardized server error responses based on RFC 9457.
+ * Each error includes a status code, type, title, and detail message.
+ * These can be used throughout the application for consistent error handling and responses.
+ * Additional errors can be added to the SERVER_ERRORS object as needed.
+ */
+export declare const SERVER_ERRORS: {
+    readonly INTERNAL_SERVER_ERROR: {
+        readonly status: 500;
+        readonly type: "about:blank";
+        readonly title: "Internal Server Error";
+        readonly detail: "An unexpected error occurred on the server.";
+    };
+    readonly SERVICE_UNAVAILABLE: {
+        readonly status: 503;
+        readonly type: "about:blank";
+        readonly title: "Service Unavailable";
+        readonly detail: "The server is currently unable to handle the request due to temporary overload or maintenance.";
+    };
+    readonly UNKNOWN_ERROR: {
+        readonly status: 520;
+        readonly type: "about:blank";
+        readonly title: "Unknown Error";
+        readonly detail: "An unknown error occurred.";
+    };
+    readonly BAD_REQUEST: {
+        readonly status: 400;
+        readonly type: "about:blank";
+        readonly title: "Bad Request";
+        readonly detail: "The server could not understand the request due to invalid syntax.";
+    };
+    readonly UNAUTHORIZED: {
+        readonly status: 401;
+        readonly type: "about:blank";
+        readonly title: "Unauthorized";
+        readonly detail: "The client must authenticate itself to get the requested response.";
+    };
+    readonly FORBIDDEN: {
+        readonly status: 403;
+        readonly type: "about:blank";
+        readonly title: "Forbidden";
+        readonly detail: "The client does not have access rights to the content.";
+    };
+    readonly NOT_FOUND: {
+        readonly status: 404;
+        readonly type: "about:blank";
+        readonly title: "Not Found";
+        readonly detail: "The server can not find the requested resource.";
+    };
+    readonly CONFLICT: {
+        readonly status: 409;
+        readonly type: "about:blank";
+        readonly title: "Conflict";
+        readonly detail: "The request conflicts with the current state of the server.";
+    };
+};
+export type ServerErrorKey = keyof typeof SERVER_ERRORS;
+export type ServerErrorOptions = {
+    status?: number;
+    title?: string;
+    detail?: string;
+    type?: string;
+    data?: any;
+};

package/dist/errors/BackendErrors.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVER_ERRORS = void 0;
+/** Defines standardized server error responses based on RFC 9457.
+ * Each error includes a status code, type, title, and detail message.
+ * These can be used throughout the application for consistent error handling and responses.
+ * Additional errors can be added to the SERVER_ERRORS object as needed.
+ */
+exports.SERVER_ERRORS = {
+    INTERNAL_SERVER_ERROR: {
+        status: 500,
+        type: "about:blank",
+        title: "Internal Server Error",
+        detail: "An unexpected error occurred on the server.",
+    },
+    SERVICE_UNAVAILABLE: {
+        status: 503,
+        type: "about:blank",
+        title: "Service Unavailable",
+        detail: "The server is currently unable to handle the request due to temporary overload or maintenance.",
+    },
+    UNKNOWN_ERROR: {
+        status: 520,
+        type: "about:blank",
+        title: "Unknown Error",
+        detail: "An unknown error occurred.",
+    },
+    BAD_REQUEST: {
+        status: 400,
+        type: "about:blank",
+        title: "Bad Request",
+        detail: "The server could not understand the request due to invalid syntax.",
+    },
+    UNAUTHORIZED: {
+        status: 401,
+        type: "about:blank",
+        title: "Unauthorized",
+        detail: "The client must authenticate itself to get the requested response.",
+    },
+    FORBIDDEN: {
+        status: 403,
+        type: "about:blank",
+        title: "Forbidden",
+        detail: "The client does not have access rights to the content.",
+    },
+    NOT_FOUND: {
+        status: 404,
+        type: "about:blank",
+        title: "Not Found",
+        detail: "The server can not find the requested resource.",
+    },
+    CONFLICT: {
+        status: 409,
+        type: "about:blank",
+        title: "Conflict",
+        detail: "The request conflicts with the current state of the server.",
+    },
+};

package/dist/errors/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./APIError";
+export * from "./BackendErrors";

package/dist/errors/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./APIError"), exports);
+__exportStar(require("./BackendErrors"), exports);

package/dist/fastify-helpers/index.d.ts

@@ -0,0 +1,90 @@
+import { type ServerErrorOptions, type ServerErrorKey } from "../errors/BackendErrors";
+import { type Static, type TObject } from "@sinclair/typebox";
+import { type FastifyRequest } from "fastify/types/request";
+import { type FastifyReply } from "fastify/types/reply";
+import { type FastifyInstance } from "fastify";
+type httpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+/** Type definition for the success response payload.
+ * @property {string} title - short, human-readable summary of the response
+ * @property {string} detail - detailed description of the response
+ * @property {any} data - any additional data to include in the response
+ */
+type SuccessResponse = {
+    title: string;
+    detail: string;
+    data: any;
+};
+/** Sends a standardized error response.
+ * Uses the RFC 9457 Format.
+ * @param res - Fastify reply object
+ * @param error - error code or identifier
+ * @param options - additional error details (title, detail, type, data)
+ * @returns {void}
+ * @example
+ * ```ts
+ * return errorResponse(res, "NOT_FOUND", { title: "Resource Not Found", detail: "The requested resource was not found." });
+ * ```
+ */
+export declare function errorResponse(res: FastifyReply, error: ServerErrorKey, { title, detail, type, data, status }?: ServerErrorOptions): void;
+/** Sends a standardized success response.
+ * @param res - Fastify reply object
+ * @param status - HTTP status code
+ * @param title - short, human-readable summary of the response
+ * @param detail - detailed description of the response
+ * @param data - any additional data to include in the response
+ * @returns {void}
+ * @example
+ * ```ts
+ * return successResponse(res, 200, "User Created", "The user was created successfully, you should recieve an email in a short while.", { id: 1, name: "Example" });
+ * ```
+ */
+export declare function successResponse(res: FastifyReply, status: number | undefined, { title, detail, data }: SuccessResponse): void;
+/** Utility function to register a route with standardized request typing and optional schema validation.
+ * @param fastify - The Fastify instance to register the route on
+ * @param method - HTTP method (e.g., "get", "post")
+ * @param path - Route path (e.g., "/users/:id")
+ * @param handler - Route handler function with typed request and reply
+ * @param options - Optional route options, including schema for validation and pre-handlers
+ * @returns void
+ * @example
+ * ```ts
+ * REGISTER_ROUTE(fastify, "post", "/users", async (req, res) => {
+ *     const { name, email } = req.body;
+ *     // Handle user creation logic here
+ *     return successResponse(res, 201, "User created successfully", { id: newUserId });
+ * }, {
+ *     schema: {
+ *         body: Type.Object({
+ *             name: Type.String(),
+ *             email: Type.String({ format: "email" }),
+ *         }),
+ *     }, preHandler: async (req, res) => {
+ *         // Optional pre-handler logic (e.g., authentication)
+ *     }
+ * });
+ * ```
+ */
+export declare function REGISTER_ROUTE<BodyType extends TObject, QueryType extends TObject, ParamsType extends TObject>(fastify: FastifyInstance, method: httpMethod, path: string, handler: (req: FastifyRequest<{
+    Body: Static<BodyType>;
+    Querystring: Static<QueryType>;
+    Params: Static<ParamsType>;
+}>, reply: any) => void, options?: {
+    schema?: {
+        body?: BodyType;
+        querystring?: QueryType;
+        params?: ParamsType;
+    };
+    preHandler?: Array<(req: FastifyRequest, reply: any) => void> | ((req: FastifyRequest, reply: any) => void);
+}): void;
+/** Centralized error handler for Fastify.
+ * @param error - The error object caught by Fastify
+ * @param request - The incoming request object
+ * @param reply - The Fastify reply object used to send the response
+ * @returns {Promise<void>}
+ * @example
+ * ```ts
+ * fastify.setErrorHandler(globalErrorHandler);
+ * ```
+ */
+export declare function globalErrorHandler(error: any, _request: FastifyRequest, reply: FastifyReply): Promise<void>;
+export {};

package/dist/fastify-helpers/index.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.errorResponse = errorResponse;
+exports.successResponse = successResponse;
+exports.REGISTER_ROUTE = REGISTER_ROUTE;
+exports.globalErrorHandler = globalErrorHandler;
+const BackendErrors_1 = require("../errors/BackendErrors");
+const colors_1 = require("@divine-lab/logger/colors");
+const APIError_1 = require("../errors/APIError");
+const logger_1 = __importDefault(require("@divine-lab/logger"));
+const API_LOG = process.env.DIVINE_LAB_REQUEST_API_LOG === "true";
+logger_1.default.raw(`${(0, colors_1.colorize)("blue", "[API]")} - API logging is ${API_LOG ? (0, colors_1.colorize)("green", "enabled") : (0, colors_1.colorize)("red", "disabled")} - ${API_LOG ? "API requests and responses will be logged." : "to enable, set API_LOG=true in environment variables"}`);
+/** Sends a standardized error response.
+ * Uses the RFC 9457 Format.
+ * @param res - Fastify reply object
+ * @param error - error code or identifier
+ * @param options - additional error details (title, detail, type, data)
+ * @returns {void}
+ * @example
+ * ```ts
+ * return errorResponse(res, "NOT_FOUND", { title: "Resource Not Found", detail: "The requested resource was not found." });
+ * ```
+ */
+function errorResponse(res, error, { title, detail, type, data, status } = {}) {
+    const errorDef = BackendErrors_1.SERVER_ERRORS[error];
+    if (API_LOG)
+        logger_1.default.raw(`${new Date().toISOString()} ${(0, colors_1.colorize)("red", "[API]")} - ${(0, colors_1.colorize)("red", (status || errorDef.status))} - ${res.request.url} : ${(0, colors_1.colorize)("gray", `${title || errorDef.title} - ${detail || errorDef.detail}`)}`);
+    res.code(status || errorDef.status).send({
+        status: status || errorDef.status,
+        instance: res.request.url,
+        title: title || errorDef.title,
+        detail: detail || errorDef.detail,
+        type: type || errorDef.type,
+        data: data || null,
+    });
+}
+/** Sends a standardized success response.
+ * @param res - Fastify reply object
+ * @param status - HTTP status code
+ * @param title - short, human-readable summary of the response
+ * @param detail - detailed description of the response
+ * @param data - any additional data to include in the response
+ * @returns {void}
+ * @example
+ * ```ts
+ * return successResponse(res, 200, "User Created", "The user was created successfully, you should recieve an email in a short while.", { id: 1, name: "Example" });
+ * ```
+ */
+function successResponse(res, status = 200, { title = "Success", detail = "Success", data = "Success" }) {
+    if (API_LOG)
+        logger_1.default.raw(`${new Date().toISOString()} ${(0, colors_1.colorize)("green", "[API]")} - ${(0, colors_1.colorize)("green", status)} - ${res.request.url} : ${(0, colors_1.colorize)("gray", title)}`);
+    res.code(status).send({
+        success: true,
+        title,
+        detail,
+        data,
+    });
+}
+/** Utility function to register a route with standardized request typing and optional schema validation.
+ * @param fastify - The Fastify instance to register the route on
+ * @param method - HTTP method (e.g., "get", "post")
+ * @param path - Route path (e.g., "/users/:id")
+ * @param handler - Route handler function with typed request and reply
+ * @param options - Optional route options, including schema for validation and pre-handlers
+ * @returns void
+ * @example
+ * ```ts
+ * REGISTER_ROUTE(fastify, "post", "/users", async (req, res) => {
+ *     const { name, email } = req.body;
+ *     // Handle user creation logic here
+ *     return successResponse(res, 201, "User created successfully", { id: newUserId });
+ * }, {
+ *     schema: {
+ *         body: Type.Object({
+ *             name: Type.String(),
+ *             email: Type.String({ format: "email" }),
+ *         }),
+ *     }, preHandler: async (req, res) => {
+ *         // Optional pre-handler logic (e.g., authentication)
+ *     }
+ * });
+ * ```
+ */
+function REGISTER_ROUTE(fastify, method, path, handler, options) {
+    fastify[method.toLowerCase()](path, options || {}, handler);
+}
+/** Centralized error handler for Fastify.
+ * @param error - The error object caught by Fastify
+ * @param request - The incoming request object
+ * @param reply - The Fastify reply object used to send the response
+ * @returns {Promise<void>}
+ * @example
+ * ```ts
+ * fastify.setErrorHandler(globalErrorHandler);
+ * ```
+ */
+async function globalErrorHandler(error, _request, reply) {
+    if (error instanceof APIError_1.APIError)
+        return errorResponse(reply, error.error, { title: error.title, detail: error.detail, type: error.type, data: error.data, status: error.status });
+    if (error.validation)
+        return errorResponse(reply, "BAD_REQUEST", { detail: error.message, data: null });
+    logger_1.default.error(`Error processing request: ${error.message}`);
+    return errorResponse(reply, "INTERNAL_SERVER_ERROR", { title: "Internal Server Error", detail: "An unexpected error occurred", type: "about:blank", data: null, status: 500 });
+}

package/dist/request.d.ts

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

package/dist/request.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,46 @@
+{
+    "name": "@divine-lab/request",
+    "version": "1.0.1",
+    "description": "Simple utility for standardizing request and response objects.",
+    "author": {
+        "name": "Ishpreet Singh",
+        "email": "ishpreet7521@gmail.com",
+        "github": "https://github.com/Ishpreet-Singh-Channa",
+        "linkedin": "https://www.linkedin.com/in/ishpreet-singh-5860ab257"
+    },
+    "license": "SEE LICENSE IN LICENSE",
+    "keywords": [
+        "request",
+        "response",
+        "request utility",
+        "response utility"
+    ],
+    "main": "dist/request.js",
+    "types": "dist/request.d.ts",
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        "./errors": {
+            "default": "./dist/errors/index.js",
+            "types": "./dist/errors/index.d.ts"
+        },
+        "./fastify-helpers": {
+            "default": "./dist/fastify-helpers/index.js",
+            "types": "./dist/fastify-helpers/index.d.ts"
+        }
+    },
+    "scripts": {
+        "prepublishOnly": "tsc",
+        "build": "tsc"
+    },
+    "devDependencies": {
+        "@sinclair/typebox": "^0.34.49",
+        "@types/node": "^25.6.2",
+        "fastify": "^5.8.5",
+        "typescript": "^6.0.3"
+    },
+    "dependencies": {
+        "@divine-lab/logger": "^1.0.2"
+    }
+}

package/readme.md

@@ -0,0 +1,118 @@
+# @divine-lab/request
+
+Simple http request formatting utility for backends.
+Works with <a href="https://fastify.dev/">fastify</a>
+
+### Request Formating
+
+Provides 2 functions for request formating.
+
+1. `successResponse`: for successs responses.
+2. `errorResponse`: for error responses.
+
+success response and error response both follow a defined standard.
+These functions are defined to be used with fastify for now.
+
+```ts
+import { successResponse } from "@divine-lab/request/fastify-helpers"
+
+// Mock type
+type SuccessResponse = {
+    success: boolean;
+    title: string;
+    detail: string;
+    data: any;
+}
+
+// Example of a success response:
+const userCreatedResponse: SuccessResponse = {
+    success: true,
+    title: "Account created successfully",
+    detail: "You will recieve a email confirming the account creation in a 5-10 minutes."
+    data: { id: 1, name: "user", age: 21 }
+}
+
+// Example success response
+successResponse(res, 200, userCreatedResponse)
+```
+
+```ts
+import { errorResponse } from "@divine-lab/request/fastify-helpers"
+
+// Mock type
+type ErrorResponse = {
+    status: number;
+    title: string;
+    detail: string;
+    type: string;
+    instance: string;
+    data: any;
+}
+
+// Example of Error Response
+const userNotFoundError: ErrorResponse = {
+    status: 404,
+    title: "User Not Found",
+    detail: "The User with the user id '1' not found in our database, please contact customer support if this is a mistake.",
+    type: "http://example-errors.com/404/user-not-found",
+    instance: "/users/1"
+    data: null
+}
+
+// example error response
+errorResponse(res, "UNKNOWN", userNotFoundError)
+```
+
+Note: RFC9457 requires error responses to contain `instance` in the response. Right now all error responses automatically attach the request url as the instance.
+
+### Errors
+
+Provides an APIError class which can be used to throw standardized Errors.
+Uses the defined `ServerErrors` to provide template for errors.
+
+```ts
+import APIError from "@divine-lab/request/erros";
+
+async function reqHandler(req, res) {
+    // ...
+    if (!user) throw new APIError("UNAUTHORIZED");
+    // ...
+}
+```
+
+Note: If a type of error is not defined, You can request for it to be added. Or you can use the `unknown` error and define the options.
+
+```ts
+import APIError from "@divine-lab/request/erros";
+
+async function reqHandler(req, res) {
+    // ...
+    if (unknown) throw new APIError("UNKNOWN", { status: 500, title: "Error", details: "This error was not defined", type: "", data: "" });
+    // ...
+}
+```
+
+### Global Error Handler
+
+In Fastify, you can attach a global error handler to make sure that any error can be caught in it.
+To always send standardized error responses, It is recommended to register the global error handler in fastify.
+
+```ts
+import { globalErrorHandler } from "@divine-lab/request/fastify-helpers";
+
+// ...
+fastify.setErrorHandler(globalErrorHandler);
+// ...
+```
+
+It automatically formats unknown error into `Internal Server Error`.
+Additionally if a `400 Bad request` is made, then this handler should handle it as well.
+
+### Environment Variables
+
+Supports API response logging via <a>`@divine-lab/logger`</a>.
+Enable by setting ENV Variable `DIVINE_LAB_REQUEST_API_LOG` to `true`.
+
+#### Contact:
+
+- mail: <a href="mailto:ishpreet7521@gmail.com">ishpreet7521@gmail.com<a>