@catbee/utils 0.0.8-next.0 → 0.0.8-rc.1

package/build/esm/utils/request.utils.js

@@ -0,0 +1,223 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/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.
+ */
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+import { BadRequestException } from './exception.utils';
+/**
+ * Extracts pagination, sorting, and optional search params from a request.
+ *
+ * @param req - Express request
+ * @returns Object containing validated pagination, sorting, and additional query params
+ */
+export var getPaginationParams = function (req) {
+    var query = req.query;
+    // Extract page & limit
+    var _a = extractPaginationParams(query, 1, 20, 100), page = _a.page, limit = _a.limit;
+    var _b = extractSortParams(query, []), sortBy = _b.sortBy, sortOrder = _b.sortOrder;
+    // Optional search param
+    var search = typeof query.search === 'string' ? query.search : undefined;
+    return __assign(__assign({}, query), { page: page, limit: limit, sortBy: sortBy, sortOrder: sortOrder, search: search });
+};
+/**
+ * Safely parses a string parameter to a number.
+ *
+ * @param value - String value to parse
+ * @param options - Validation options
+ * @returns Validation result containing the parsed number or error
+ */
+export function parseNumberParam(value, options) {
+    if (options === void 0) { options = {}; }
+    var _a = options.throwOnError, throwOnError = _a === void 0 ? false : _a, _b = options.errorMessage, errorMessage = _b === void 0 ? 'Invalid number parameter' : _b, defaultValue = options.defaultValue, _c = options.required, required = _c === void 0 ? false : _c;
+    // Handle undefined case
+    if (value === undefined) {
+        if (required) {
+            var error = "Required number parameter is missing";
+            if (throwOnError)
+                throw new BadRequestException(error);
+            return { isValid: false, value: null, error: error };
+        }
+        return {
+            isValid: defaultValue !== undefined,
+            value: defaultValue !== undefined ? defaultValue : null,
+            error: defaultValue === undefined ? 'Missing parameter with no default' : undefined
+        };
+    }
+    // Parse and validate the number
+    var num = Number(value);
+    if (isNaN(num)) {
+        if (throwOnError)
+            throw new BadRequestException(errorMessage);
+        return { isValid: false, value: null, error: errorMessage };
+    }
+    return { isValid: true, value: num };
+}
+/**
+ * Safely parses a string parameter to a boolean.
+ *
+ * @param value - String value to parse
+ * @param options - Validation options
+ * @returns Validation result containing the parsed boolean or error
+ */
+export function parseBooleanParam(value, options) {
+    if (options === void 0) { options = {}; }
+    var _a = options.throwOnError, throwOnError = _a === void 0 ? false : _a, _b = options.errorMessage, errorMessage = _b === void 0 ? 'Invalid boolean parameter' : _b, defaultValue = options.defaultValue, _c = options.required, required = _c === void 0 ? false : _c;
+    // Handle undefined case
+    if (value === undefined) {
+        if (required) {
+            var error = "Required boolean parameter is missing";
+            if (throwOnError)
+                throw new BadRequestException(error);
+            return { isValid: false, value: null, error: error };
+        }
+        return {
+            isValid: defaultValue !== undefined,
+            value: defaultValue !== undefined ? defaultValue : null,
+            error: defaultValue === undefined ? 'Missing parameter with no default' : undefined
+        };
+    }
+    // Parse the boolean value with various allowed formats
+    var lowercaseValue = value.toLowerCase();
+    if (['true', 't', 'yes', 'y', '1'].includes(lowercaseValue)) {
+        return { isValid: true, value: true };
+    }
+    if (['false', 'f', 'no', 'n', '0'].includes(lowercaseValue)) {
+        return { isValid: true, value: false };
+    }
+    if (throwOnError)
+        throw new BadRequestException(errorMessage);
+    return { isValid: false, value: null, error: errorMessage };
+}
+/**
+ * Extracts pagination parameters from request query parameters.
+ *
+ * @param query - Query parameters object
+ * @param defaultPage - Default page number if not specified (defaults to 1)
+ * @param defaultLimit - Default per page size if not specified (defaults to 20)
+ * @param maxLimitSize - Maximum allowed per page size (defaults to 100)
+ * @returns Object containing validated page and limit
+ */
+export function extractPaginationParams(query, defaultPage, defaultLimit, maxLimitSize) {
+    if (defaultPage === void 0) { defaultPage = 1; }
+    if (defaultLimit === void 0) { defaultLimit = 20; }
+    if (maxLimitSize === void 0) { maxLimitSize = 100; }
+    // Parse page parameter
+    var pageParam = typeof query.page === 'string' ? query.page : undefined;
+    var pageResult = parseNumberParam(pageParam, { defaultValue: defaultPage });
+    // Parse limit parameter
+    var limitParam = typeof query.limit === 'string' ? query.limit : undefined;
+    var limitResult = parseNumberParam(limitParam, { defaultValue: defaultLimit });
+    // Ensure valid values (handle 0 → fallback to default)
+    var page = pageResult.value && pageResult.value > 0 ? pageResult.value : defaultPage;
+    var limit = limitResult.value && limitResult.value > 0 ? Math.min(limitResult.value, maxLimitSize) : defaultLimit;
+    return { page: page, limit: limit };
+}
+/**
+ * Extracts sorting parameters from request query parameters.
+ *
+ * @param query - Query parameters object
+ * @param allowedFields - Array of field names that are allowed to be sorted
+ * @param defaultSort - Default sort configuration if not specified
+ * @returns Object containing sort field and direction
+ */
+export function extractSortParams(query, allowedFields, defaultSort) {
+    if (defaultSort === void 0) { defaultSort = { sortBy: 'createdAt', sortOrder: 'desc' }; }
+    var sortBy = defaultSort.sortBy;
+    var sortOrder = defaultSort.sortOrder;
+    // Extract from `sortBy` or `sort`
+    if (typeof query.sortBy === 'string') {
+        sortBy = query.sortBy;
+    }
+    else if (Array.isArray(query.sortBy)) {
+        sortBy = query.sortBy[0];
+    }
+    else if (typeof query.sort === 'string') {
+        sortBy = query.sort.startsWith('-') ? query.sort.slice(1) : query.sort;
+        sortOrder = query.sort.startsWith('-') ? 'desc' : 'asc';
+    }
+    else if (Array.isArray(query.sort)) {
+        sortBy = query.sort[0].startsWith('-') ? query.sort[0].slice(1) : query.sort[0];
+        sortOrder = query.sort[0].startsWith('-') ? 'desc' : 'asc';
+    }
+    // Explicit sortOrder (overrides inferred one if valid)
+    if (typeof query.sortOrder === 'string') {
+        var order = query.sortOrder.toLowerCase();
+        if (order === 'asc' || order === 'desc') {
+            sortOrder = order;
+        }
+    }
+    // Validate field
+    if (allowedFields.length && !allowedFields.includes(sortBy)) {
+        sortBy = defaultSort.sortBy;
+    }
+    return { sortBy: sortBy, sortOrder: sortOrder };
+}
+/**
+ * Extracts filter parameters from query parameters based on allowed filter fields.
+ *
+ * @param query - Query parameters object
+ * @param allowedFilters - Array of field names that are allowed to be used as filters
+ * @returns Object containing the filters as key-value pairs
+ */
+export function extractFilterParams(query, allowedFilters) {
+    var e_1, _a;
+    var filters = {};
+    try {
+        // Find filter parameters in the query
+        for (var allowedFilters_1 = __values(allowedFilters), allowedFilters_1_1 = allowedFilters_1.next(); !allowedFilters_1_1.done; allowedFilters_1_1 = allowedFilters_1.next()) {
+            var field = allowedFilters_1_1.value;
+            if (field in query) {
+                filters[field] = query[field];
+            }
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (allowedFilters_1_1 && !allowedFilters_1_1.done && (_a = allowedFilters_1.return)) _a.call(allowedFilters_1);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    return filters;
+}
+//# sourceMappingURL=request.utils.js.map

package/build/esm/utils/request.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.utils.js","sourceRoot":"","sources":["../../../src/utils/request.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Request } from 'express';\nimport { SortDirection, WithPagination } from '../types/api-response';\nimport { BadRequestException } from './exception.utils';\n\n/**\n * Options for parsing and validating request parameters.\n */\nexport interface ValidationOptions {\n  /** Whether to throw an error on validation failure */\n  throwOnError?: boolean;\n\n  /** Custom error message for validation failures */\n  errorMessage?: string;\n\n  /** Default value to use if parameter is missing */\n  defaultValue?: any;\n\n  /** Whether the parameter is required */\n  required?: boolean;\n}\n\n/**\n * Result of a parameter validation operation.\n */\nexport interface ValidationResult<T> {\n  /** Whether validation was successful */\n  isValid: boolean;\n\n  /** The validated and potentially transformed value */\n  value: T | null;\n\n  /** Error message if validation failed */\n  error?: string;\n}\n\n/**\n * Extracts pagination, sorting, and optional search params from a request.\n *\n * @param req - Express request\n * @returns Object containing validated pagination, sorting, and additional query params\n */\nexport const getPaginationParams = <T = {}>(req: Request): WithPagination<T> => {\n  const query = req.query as Record<string, string | string[]>;\n\n  // Extract page & limit\n  const { page, limit } = extractPaginationParams(query, 1, 20, 100);\n  const { sortBy, sortOrder } = extractSortParams(query, []);\n\n  // Optional search param\n  const search = typeof query.search === 'string' ? query.search : undefined;\n\n  return {\n    ...(query as T),\n    page,\n    limit,\n    sortBy,\n    sortOrder: sortOrder as SortDirection,\n    search\n  };\n};\n\n/**\n * Safely parses a string parameter to a number.\n *\n * @param value - String value to parse\n * @param options - Validation options\n * @returns Validation result containing the parsed number or error\n */\nexport function parseNumberParam(value: string | undefined, options: ValidationOptions = {}): ValidationResult<number> {\n  const { throwOnError = false, errorMessage = 'Invalid number parameter', defaultValue, required = false } = options;\n\n  // Handle undefined case\n  if (value === undefined) {\n    if (required) {\n      const error = `Required number parameter is missing`;\n      if (throwOnError) throw new BadRequestException(error);\n      return { isValid: false, value: null, error };\n    }\n\n    return {\n      isValid: defaultValue !== undefined,\n      value: defaultValue !== undefined ? defaultValue : null,\n      error: defaultValue === undefined ? 'Missing parameter with no default' : undefined\n    };\n  }\n\n  // Parse and validate the number\n  const num = Number(value);\n  if (isNaN(num)) {\n    if (throwOnError) throw new BadRequestException(errorMessage);\n    return { isValid: false, value: null, error: errorMessage };\n  }\n\n  return { isValid: true, value: num };\n}\n\n/**\n * Safely parses a string parameter to a boolean.\n *\n * @param value - String value to parse\n * @param options - Validation options\n * @returns Validation result containing the parsed boolean or error\n */\nexport function parseBooleanParam(\n  value: string | undefined,\n  options: ValidationOptions = {}\n): ValidationResult<boolean> {\n  const { throwOnError = false, errorMessage = 'Invalid boolean parameter', defaultValue, required = false } = options;\n\n  // Handle undefined case\n  if (value === undefined) {\n    if (required) {\n      const error = `Required boolean parameter is missing`;\n      if (throwOnError) throw new BadRequestException(error);\n      return { isValid: false, value: null, error };\n    }\n\n    return {\n      isValid: defaultValue !== undefined,\n      value: defaultValue !== undefined ? defaultValue : null,\n      error: defaultValue === undefined ? 'Missing parameter with no default' : undefined\n    };\n  }\n\n  // Parse the boolean value with various allowed formats\n  const lowercaseValue = value.toLowerCase();\n  if (['true', 't', 'yes', 'y', '1'].includes(lowercaseValue)) {\n    return { isValid: true, value: true };\n  }\n\n  if (['false', 'f', 'no', 'n', '0'].includes(lowercaseValue)) {\n    return { isValid: true, value: false };\n  }\n\n  if (throwOnError) throw new BadRequestException(errorMessage);\n  return { isValid: false, value: null, error: errorMessage };\n}\n\n/**\n * Extracts pagination parameters from request query parameters.\n *\n * @param query - Query parameters object\n * @param defaultPage - Default page number if not specified (defaults to 1)\n * @param defaultLimit - Default per page size if not specified (defaults to 20)\n * @param maxLimitSize - Maximum allowed per page size (defaults to 100)\n * @returns Object containing validated page and limit\n */\nexport function extractPaginationParams(\n  query: Record<string, string | string[]>,\n  defaultPage: number = 1,\n  defaultLimit: number = 20,\n  maxLimitSize: number = 100\n): { page: number; limit: number } {\n  // Parse page parameter\n  const pageParam = typeof query.page === 'string' ? query.page : undefined;\n  const pageResult = parseNumberParam(pageParam, { defaultValue: defaultPage });\n\n  // Parse limit parameter\n  const limitParam = typeof query.limit === 'string' ? query.limit : undefined;\n  const limitResult = parseNumberParam(limitParam, { defaultValue: defaultLimit });\n\n  // Ensure valid values (handle 0 → fallback to default)\n  const page = pageResult.value && pageResult.value > 0 ? pageResult.value : defaultPage;\n\n  const limit = limitResult.value && limitResult.value > 0 ? Math.min(limitResult.value, maxLimitSize) : defaultLimit;\n\n  return { page, limit };\n}\n\n/**\n * Extracts sorting parameters from request query parameters.\n *\n * @param query - Query parameters object\n * @param allowedFields - Array of field names that are allowed to be sorted\n * @param defaultSort - Default sort configuration if not specified\n * @returns Object containing sort field and direction\n */\nexport function extractSortParams(\n  query: Record<string, string | string[]>,\n  allowedFields: string[],\n  defaultSort: { sortBy: string; sortOrder: 'asc' | 'desc' } = { sortBy: 'createdAt', sortOrder: 'desc' }\n): { sortBy: string; sortOrder: 'asc' | 'desc' } {\n  let sortBy = defaultSort.sortBy;\n  let sortOrder: 'asc' | 'desc' = defaultSort.sortOrder;\n\n  // Extract from `sortBy` or `sort`\n  if (typeof query.sortBy === 'string') {\n    sortBy = query.sortBy;\n  } else if (Array.isArray(query.sortBy)) {\n    sortBy = query.sortBy[0];\n  } else if (typeof query.sort === 'string') {\n    sortBy = query.sort.startsWith('-') ? query.sort.slice(1) : query.sort;\n    sortOrder = query.sort.startsWith('-') ? 'desc' : 'asc';\n  } else if (Array.isArray(query.sort)) {\n    sortBy = query.sort[0].startsWith('-') ? query.sort[0].slice(1) : query.sort[0];\n    sortOrder = query.sort[0].startsWith('-') ? 'desc' : 'asc';\n  }\n\n  // Explicit sortOrder (overrides inferred one if valid)\n  if (typeof query.sortOrder === 'string') {\n    const order = query.sortOrder.toLowerCase();\n    if (order === 'asc' || order === 'desc') {\n      sortOrder = order;\n    }\n  }\n\n  // Validate field\n  if (allowedFields.length && !allowedFields.includes(sortBy)) {\n    sortBy = defaultSort.sortBy;\n  }\n\n  return { sortBy, sortOrder };\n}\n\n/**\n * Extracts filter parameters from query parameters based on allowed filter fields.\n *\n * @param query - Query parameters object\n * @param allowedFilters - Array of field names that are allowed to be used as filters\n * @returns Object containing the filters as key-value pairs\n */\nexport function extractFilterParams(\n  query: Record<string, string | string[]>,\n  allowedFilters: string[]\n): Record<string, string | string[]> {\n  const filters: Record<string, string | string[]> = {};\n\n  // Find filter parameters in the query\n  for (const field of allowedFilters) {\n    if (field in query) {\n      filters[field] = query[field];\n    }\n  }\n\n  return filters;\n}\n"]}

package/build/esm/utils/response.utils.d.ts

@@ -0,0 +1,163 @@
+import { Request } from 'express';
+import { ApiErrorResponse, ApiResponse } from '../types/api-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;
+//# sourceMappingURL=response.utils.d.ts.map