@catbee/utils 1.1.0 → 2.0.0-next.0

package/response/index.cjs

@@ -0,0 +1,234 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * 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.
+ */
+
+'use strict';
+
+var contextStore = require('@catbee/utils/context-store');
+var env = require('@catbee/utils/env');
+var id = require('@catbee/utils/id');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var SuccessResponse = class {
+  static {
+    __name(this, "SuccessResponse");
+  }
+  /** Message describing the result of the operation. */
+  message = "Success";
+  /** Whether the response is an error. Always false in success responses. */
+  error = false;
+  /** The payload returned from the API. */
+  data = null;
+  /** Timestamp when the response was generated, in ISO format. */
+  timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  /** Unique identifier for this response, useful for request tracing. */
+  requestId = contextStore.getRequestId() ?? id.uuid();
+  /**
+  * Constructs a new success response.
+  *
+  * @param {string} message - Optional message to override the default.
+  * @param {T} [data] - Optional data payload.
+  */
+  constructor(message, data) {
+    if (message) this.message = message;
+    this.data = data ?? null;
+  }
+};
+var ErrorResponse = class extends Error {
+  static {
+    __name(this, "ErrorResponse");
+  }
+  /** HTTP status code associated with the error (e.g., 404, 500). */
+  status;
+  /** Indicates that this is an error. Always true. */
+  error = true;
+  /** Timestamp when the error occurred, in ISO format. */
+  timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  /** Unique identifier for this error instance. */
+  requestId = contextStore.getRequestId() ?? id.uuid();
+  /**
+  * Constructs a new error response.
+  *
+  * @param {string} message - The error message to display or log.
+  * @param {number} [status=500] - Optional HTTP status code (defaults to 500).
+  */
+  constructor(message, status = 500) {
+    super(message);
+    this.status = status;
+    this.name = this.constructor.name;
+    Error.captureStackTrace(this, this.constructor);
+  }
+};
+var PaginatedResponse = class extends SuccessResponse {
+  static {
+    __name(this, "PaginatedResponse");
+  }
+  /** Total number of items across all pages */
+  total;
+  /** Current page number (1-based) */
+  page;
+  /** Number of items per page */
+  pageSize;
+  /** Total number of pages */
+  totalPages;
+  /** Whether there's a next page available */
+  hasNext;
+  /** Whether there's a previous page available */
+  hasPrevious;
+  /**
+  * Constructs a new paginated response.
+  *
+  * @param {T[]} items - The current page of items.
+  * @param {Object} pagination - Pagination information.
+  * @param {number} pagination.total - Total number of items across all pages.
+  * @param {number} pagination.page - Current page number (1-based).
+  * @param {number} pagination.pageSize - Number of items per page.
+  * @param {string} [message="Success"] - Optional custom message.
+  */
+  constructor(items, pagination, message = "Success") {
+    super(message, items);
+    this.total = pagination.total;
+    this.page = pagination.page;
+    this.pageSize = pagination.pageSize;
+    this.totalPages = Math.ceil(this.total / this.pageSize);
+    this.hasNext = this.page < this.totalPages;
+    this.hasPrevious = this.page > 1;
+  }
+};
+var NoContentResponse = class extends SuccessResponse {
+  static {
+    __name(this, "NoContentResponse");
+  }
+  /**
+  * Constructs a new no-content response.
+  *
+  * @param {string} [message="Operation completed successfully"] - Optional custom message.
+  */
+  constructor(message = "Operation completed successfully") {
+    super(message, null);
+  }
+};
+var RedirectResponse = class {
+  static {
+    __name(this, "RedirectResponse");
+  }
+  /** The URL to redirect to */
+  redirectUrl;
+  /** HTTP status code for the redirect (301, 302, 303, 307, 308) */
+  statusCode;
+  /** Whether the response is a redirect */
+  isRedirect = true;
+  /** Unique identifier for this response */
+  requestId = contextStore.getRequestId() ?? id.uuid();
+  /**
+  * Constructs a new redirect response.
+  *
+  * @param {string} url - The URL to redirect to.
+  * @param {number} [statusCode=302] - HTTP status code for the redirect.
+  */
+  constructor(url, statusCode = 302) {
+    this.redirectUrl = url;
+    this.statusCode = statusCode;
+  }
+};
+function createSuccessResponse(data, message = "Success") {
+  return new SuccessResponse(message, data);
+}
+__name(createSuccessResponse, "createSuccessResponse");
+function createErrorResponse(message, statusCode = 500) {
+  return new ErrorResponse(message, statusCode);
+}
+__name(createErrorResponse, "createErrorResponse");
+function createFinalErrorResponse(req, status, message, error, options) {
+  const isDev = env.Env.isDev();
+  const includeDetails = options?.includeDetails && isDev;
+  const response = {
+    error: true,
+    message,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    requestId: error?.requestId || req?.id || id.uuid(),
+    status,
+    path: req.originalUrl || req.url
+  };
+  if (includeDetails && error?.stack) {
+    response.stack = error.stack.split("\n").map((line) => line.trim());
+  }
+  return response;
+}
+__name(createFinalErrorResponse, "createFinalErrorResponse");
+function createPaginatedResponse(allItems, page, pageSize, message = "Success") {
+  const validPage = Math.max(1, page);
+  const validPageSize = Math.max(1, pageSize);
+  const startIndex = (validPage - 1) * validPageSize;
+  const endIndex = startIndex + validPageSize;
+  const pageItems = allItems.slice(startIndex, endIndex);
+  return new PaginatedResponse(pageItems, {
+    total: allItems.length,
+    page: validPage,
+    pageSize: validPageSize
+  }, message);
+}
+__name(createPaginatedResponse, "createPaginatedResponse");
+function sendResponse(res, apiResponse) {
+  if ("redirectUrl" in apiResponse) {
+    res.redirect(apiResponse.statusCode, apiResponse.redirectUrl);
+    return;
+  }
+  if ("error" in apiResponse && apiResponse.error) {
+    const errorResponse = apiResponse;
+    res.status(errorResponse.status).json({
+      error: true,
+      message: errorResponse.message,
+      timestamp: errorResponse.timestamp,
+      requestId: errorResponse.requestId
+    });
+    return;
+  }
+  const successResponse = apiResponse;
+  if (successResponse instanceof NoContentResponse) {
+    res.status(204).end();
+    return;
+  }
+  res.status(200).json(successResponse);
+}
+__name(sendResponse, "sendResponse");
+
+// src/types/api-response.ts
+var SortDirection = /* @__PURE__ */ (function(SortDirection2) {
+  SortDirection2["ASC"] = "asc";
+  SortDirection2["DESC"] = "desc";
+  return SortDirection2;
+})({});
+
+exports.ErrorResponse = ErrorResponse;
+exports.NoContentResponse = NoContentResponse;
+exports.PaginatedResponse = PaginatedResponse;
+exports.RedirectResponse = RedirectResponse;
+exports.SortDirection = SortDirection;
+exports.SuccessResponse = SuccessResponse;
+exports.createErrorResponse = createErrorResponse;
+exports.createFinalErrorResponse = createFinalErrorResponse;
+exports.createPaginatedResponse = createPaginatedResponse;
+exports.createSuccessResponse = createSuccessResponse;
+exports.sendResponse = sendResponse;

package/response/index.d.ts

@@ -0,0 +1,26 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * 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.
+ */
+
+export * from './response.utils';
+export * from '../types/api-response';

package/response/index.mjs

@@ -0,0 +1,222 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * 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.
+ */
+
+import { getRequestId } from '@catbee/utils/context-store';
+import { Env } from '@catbee/utils/env';
+import { uuid } from '@catbee/utils/id';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var SuccessResponse = class {
+  static {
+    __name(this, "SuccessResponse");
+  }
+  /** Message describing the result of the operation. */
+  message = "Success";
+  /** Whether the response is an error. Always false in success responses. */
+  error = false;
+  /** The payload returned from the API. */
+  data = null;
+  /** Timestamp when the response was generated, in ISO format. */
+  timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  /** Unique identifier for this response, useful for request tracing. */
+  requestId = getRequestId() ?? uuid();
+  /**
+  * Constructs a new success response.
+  *
+  * @param {string} message - Optional message to override the default.
+  * @param {T} [data] - Optional data payload.
+  */
+  constructor(message, data) {
+    if (message) this.message = message;
+    this.data = data ?? null;
+  }
+};
+var ErrorResponse = class extends Error {
+  static {
+    __name(this, "ErrorResponse");
+  }
+  /** HTTP status code associated with the error (e.g., 404, 500). */
+  status;
+  /** Indicates that this is an error. Always true. */
+  error = true;
+  /** Timestamp when the error occurred, in ISO format. */
+  timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  /** Unique identifier for this error instance. */
+  requestId = getRequestId() ?? uuid();
+  /**
+  * Constructs a new error response.
+  *
+  * @param {string} message - The error message to display or log.
+  * @param {number} [status=500] - Optional HTTP status code (defaults to 500).
+  */
+  constructor(message, status = 500) {
+    super(message);
+    this.status = status;
+    this.name = this.constructor.name;
+    Error.captureStackTrace(this, this.constructor);
+  }
+};
+var PaginatedResponse = class extends SuccessResponse {
+  static {
+    __name(this, "PaginatedResponse");
+  }
+  /** Total number of items across all pages */
+  total;
+  /** Current page number (1-based) */
+  page;
+  /** Number of items per page */
+  pageSize;
+  /** Total number of pages */
+  totalPages;
+  /** Whether there's a next page available */
+  hasNext;
+  /** Whether there's a previous page available */
+  hasPrevious;
+  /**
+  * Constructs a new paginated response.
+  *
+  * @param {T[]} items - The current page of items.
+  * @param {Object} pagination - Pagination information.
+  * @param {number} pagination.total - Total number of items across all pages.
+  * @param {number} pagination.page - Current page number (1-based).
+  * @param {number} pagination.pageSize - Number of items per page.
+  * @param {string} [message="Success"] - Optional custom message.
+  */
+  constructor(items, pagination, message = "Success") {
+    super(message, items);
+    this.total = pagination.total;
+    this.page = pagination.page;
+    this.pageSize = pagination.pageSize;
+    this.totalPages = Math.ceil(this.total / this.pageSize);
+    this.hasNext = this.page < this.totalPages;
+    this.hasPrevious = this.page > 1;
+  }
+};
+var NoContentResponse = class extends SuccessResponse {
+  static {
+    __name(this, "NoContentResponse");
+  }
+  /**
+  * Constructs a new no-content response.
+  *
+  * @param {string} [message="Operation completed successfully"] - Optional custom message.
+  */
+  constructor(message = "Operation completed successfully") {
+    super(message, null);
+  }
+};
+var RedirectResponse = class {
+  static {
+    __name(this, "RedirectResponse");
+  }
+  /** The URL to redirect to */
+  redirectUrl;
+  /** HTTP status code for the redirect (301, 302, 303, 307, 308) */
+  statusCode;
+  /** Whether the response is a redirect */
+  isRedirect = true;
+  /** Unique identifier for this response */
+  requestId = getRequestId() ?? uuid();
+  /**
+  * Constructs a new redirect response.
+  *
+  * @param {string} url - The URL to redirect to.
+  * @param {number} [statusCode=302] - HTTP status code for the redirect.
+  */
+  constructor(url, statusCode = 302) {
+    this.redirectUrl = url;
+    this.statusCode = statusCode;
+  }
+};
+function createSuccessResponse(data, message = "Success") {
+  return new SuccessResponse(message, data);
+}
+__name(createSuccessResponse, "createSuccessResponse");
+function createErrorResponse(message, statusCode = 500) {
+  return new ErrorResponse(message, statusCode);
+}
+__name(createErrorResponse, "createErrorResponse");
+function createFinalErrorResponse(req, status, message, error, options) {
+  const isDev = Env.isDev();
+  const includeDetails = options?.includeDetails && isDev;
+  const response = {
+    error: true,
+    message,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    requestId: error?.requestId || req?.id || uuid(),
+    status,
+    path: req.originalUrl || req.url
+  };
+  if (includeDetails && error?.stack) {
+    response.stack = error.stack.split("\n").map((line) => line.trim());
+  }
+  return response;
+}
+__name(createFinalErrorResponse, "createFinalErrorResponse");
+function createPaginatedResponse(allItems, page, pageSize, message = "Success") {
+  const validPage = Math.max(1, page);
+  const validPageSize = Math.max(1, pageSize);
+  const startIndex = (validPage - 1) * validPageSize;
+  const endIndex = startIndex + validPageSize;
+  const pageItems = allItems.slice(startIndex, endIndex);
+  return new PaginatedResponse(pageItems, {
+    total: allItems.length,
+    page: validPage,
+    pageSize: validPageSize
+  }, message);
+}
+__name(createPaginatedResponse, "createPaginatedResponse");
+function sendResponse(res, apiResponse) {
+  if ("redirectUrl" in apiResponse) {
+    res.redirect(apiResponse.statusCode, apiResponse.redirectUrl);
+    return;
+  }
+  if ("error" in apiResponse && apiResponse.error) {
+    const errorResponse = apiResponse;
+    res.status(errorResponse.status).json({
+      error: true,
+      message: errorResponse.message,
+      timestamp: errorResponse.timestamp,
+      requestId: errorResponse.requestId
+    });
+    return;
+  }
+  const successResponse = apiResponse;
+  if (successResponse instanceof NoContentResponse) {
+    res.status(204).end();
+    return;
+  }
+  res.status(200).json(successResponse);
+}
+__name(sendResponse, "sendResponse");
+
+// src/types/api-response.ts
+var SortDirection = /* @__PURE__ */ (function(SortDirection2) {
+  SortDirection2["ASC"] = "asc";
+  SortDirection2["DESC"] = "desc";
+  return SortDirection2;
+})({});
+
+export { ErrorResponse, NoContentResponse, PaginatedResponse, RedirectResponse, SortDirection, SuccessResponse, createErrorResponse, createFinalErrorResponse, createPaginatedResponse, createSuccessResponse, sendResponse };

package/response/response.utils.d.ts

@@ -0,0 +1,186 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * 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.
+ */
+
+import type { Request } from 'express';
+import { ApiErrorResponse, ApiResponse } from '@catbee/utils/response';
+/**
+ * Standard HTTP response wrapper for successful responses.
+ * Implements the `ApiResponse<T>` interface and sets default values.
+ *
+ * @typeParam T - The shape of the data returned in the response.
+ */
+export declare class SuccessResponse<T> implements ApiResponse<T> {
+    /** Message describing the result of the operation. */
+    message: string;
+    /** Whether the response is an error. Always false in success responses. */
+    error: boolean;
+    /** The payload returned from the API. */
+    data: T | null;
+    /** Timestamp when the response was generated, in ISO format. */
+    timestamp: string;
+    /** Unique identifier for this response, useful for request tracing. */
+    requestId: string;
+    /**
+     * Constructs a new success response.
+     *
+     * @param {string} message - Optional message to override the default.
+     * @param {T} [data] - Optional data payload.
+     */
+    constructor(message: string, data?: T);
+}
+/**
+ * Wrapper for error responses that extends the native `Error` object.
+ * Implements `ApiResponse` but omits the `data` field (which should not be present in errors).
+ */
+export declare class ErrorResponse extends Error implements Omit<ApiResponse<never>, 'data'> {
+    /** HTTP status code associated with the error (e.g., 404, 500). */
+    status: number;
+    /** Indicates that this is an error. Always true. */
+    error: boolean;
+    /** Timestamp when the error occurred, in ISO format. */
+    timestamp: string;
+    /** Unique identifier for this error instance. */
+    requestId: string;
+    /**
+     * Constructs a new error response.
+     *
+     * @param {string} message - The error message to display or log.
+     * @param {number} [status=500] - Optional HTTP status code (defaults to 500).
+     */
+    constructor(message: string, status?: number);
+}
+/**
+ * Response with paginated data extending the standard success response.
+ * Useful for APIs that return large collections of data.
+ *
+ * @typeParam T - The shape of each item in the paginated collection.
+ */
+export declare class PaginatedResponse<T> extends SuccessResponse<T[]> {
+    /** Total number of items across all pages */
+    total: number;
+    /** Current page number (1-based) */
+    page: number;
+    /** Number of items per page */
+    pageSize: number;
+    /** Total number of pages */
+    totalPages: number;
+    /** Whether there's a next page available */
+    hasNext: boolean;
+    /** Whether there's a previous page available */
+    hasPrevious: boolean;
+    /**
+     * Constructs a new paginated response.
+     *
+     * @param {T[]} items - The current page of items.
+     * @param {Object} pagination - Pagination information.
+     * @param {number} pagination.total - Total number of items across all pages.
+     * @param {number} pagination.page - Current page number (1-based).
+     * @param {number} pagination.pageSize - Number of items per page.
+     * @param {string} [message="Success"] - Optional custom message.
+     */
+    constructor(items: T[], pagination: {
+        total: number;
+        page: number;
+        pageSize: number;
+    }, message?: string);
+}
+/**
+ * Specialized response for operations that don't return data (HTTP 204).
+ */
+export declare class NoContentResponse extends SuccessResponse<null> {
+    /**
+     * Constructs a new no-content response.
+     *
+     * @param {string} [message="Operation completed successfully"] - Optional custom message.
+     */
+    constructor(message?: string);
+}
+/**
+ * Specialized response for redirects.
+ */
+export declare class RedirectResponse {
+    /** The URL to redirect to */
+    redirectUrl: string;
+    /** HTTP status code for the redirect (301, 302, 303, 307, 308) */
+    statusCode: number;
+    /** Whether the response is a redirect */
+    isRedirect: boolean;
+    /** Unique identifier for this response */
+    requestId: string;
+    /**
+     * Constructs a new redirect response.
+     *
+     * @param {string} url - The URL to redirect to.
+     * @param {number} [statusCode=302] - HTTP status code for the redirect.
+     */
+    constructor(url: string, statusCode?: number);
+}
+/**
+ * Creates a standard success response.
+ *
+ * @typeParam T - The shape of the data returned in the response.
+ * @param {T} data - The data to include in the response.
+ * @param {string} [message="Success"] - Optional custom message.
+ * @returns {SuccessResponse<T>} A properly formatted success response.
+ */
+export declare function createSuccessResponse<T>(data: T, message?: string): SuccessResponse<T>;
+/**
+ * Creates a standard error response.
+ *
+ * @param {string} message - The error message.
+ * @param {number} [statusCode=500] - HTTP status code for the error.
+ * @returns {ErrorResponse} A properly formatted error response.
+ */
+export declare function createErrorResponse(message: string, statusCode?: number): ErrorResponse;
+/**
+ * Creates a final error response with request information.
+ *
+ * @param req - The original request object.
+ * @param status - The HTTP status code.
+ * @param message - The error message.
+ * @param error - The original error object (optional).
+ * @param options - Additional options for the response (optional).
+ * @returns A properly formatted final error response.
+ */
+export declare function createFinalErrorResponse(req: Request, status: number, message: string, error?: any, options?: {
+    includeDetails?: boolean;
+}): ApiErrorResponse;
+/**
+ * Creates a paginated response from array data.
+ *
+ * @typeParam T - The shape of each item in the collection.
+ * @param {T[]} allItems - The complete array of items to paginate.
+ * @param {number} page - The requested page (1-based).
+ * @param {number} pageSize - The number of items per page.
+ * @param {string} [message="Success"] - Optional custom message.
+ * @returns {PaginatedResponse<T>} A properly formatted paginated response.
+ */
+export declare function createPaginatedResponse<T>(allItems: T[], page: number, pageSize: number, message?: string): PaginatedResponse<T>;
+/**
+ * Adapter to convert API responses to Express.js response format.
+ *
+ * @param {any} res - Express response object.
+ * @param {SuccessResponse<any> | ErrorResponse | RedirectResponse} apiResponse - API response instance.
+ */
+export declare function sendResponse(res: any, apiResponse: SuccessResponse<any> | ErrorResponse | RedirectResponse): void;