@catbee/utils/build/src/utils/response.utils.d.ts

A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications (including Express-based services). All utilities are tree-shakable and can be imported independently.

import { 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 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