express-pro-toolkit 2.0.0

package/types/index.d.ts

@@ -0,0 +1,169 @@
+import { Request, Response, NextFunction, ErrorRequestHandler, RequestHandler } from 'express';
+
+/* ─── AppError ────────────────────────────────────────────────────── */
+
+export interface AppErrorOptions {
+  code?: string;
+  errors?: any[];
+  isOperational?: boolean;
+}
+
+export class AppError extends Error {
+  readonly name: 'AppError';
+  readonly statusCode: number;
+  readonly code?: string;
+  readonly errors: any[] | null;
+  readonly isOperational: boolean;
+  readonly timestamp: number;
+
+  constructor(message: string, statusCode?: number, options?: AppErrorOptions);
+
+  static badRequest(message?: string, options?: AppErrorOptions): AppError;
+  static unauthorized(message?: string, options?: AppErrorOptions): AppError;
+  static forbidden(message?: string, options?: AppErrorOptions): AppError;
+  static notFound(message?: string, options?: AppErrorOptions): AppError;
+  static conflict(message?: string, options?: AppErrorOptions): AppError;
+  static validation(errors: any[], message?: string): AppError;
+  static tooManyRequests(message?: string, options?: AppErrorOptions): AppError;
+  static internal(message?: string, options?: AppErrorOptions): AppError;
+
+  toJSON(): object;
+}
+
+/* ─── asyncHandler ────────────────────────────────────────────────── */
+
+export function asyncHandler<T extends (...args: any[]) => any>(fn: T): T;
+
+/* ─── errorHandler ────────────────────────────────────────────────── */
+
+export interface ErrorLogPayload {
+  err: Error;
+  statusCode: number;
+  method: string;
+  url: string;
+  requestId: string | null;
+  message: string;
+  stack: string | null;
+  timestamp: string;
+}
+
+export interface ErrorHandlerOptions {
+  includeStack?: boolean;
+  onError?: (payload: ErrorLogPayload) => void;
+  defaultStatusCode?: number;
+}
+
+export function createErrorHandler(options?: ErrorHandlerOptions): ErrorRequestHandler;
+
+export const errorHandler: ErrorRequestHandler;
+
+/* ─── requestLogger ───────────────────────────────────────────────── */
+
+export interface RequestLogInfo {
+  method: string;
+  url: string;
+  status: number;
+  duration: number;
+  timestamp: string;
+  requestId: string | null;
+}
+
+export interface RequestLoggerOptions {
+  log?: (info: RequestLogInfo) => void;
+  skip?: (req: Request, res: Response) => boolean;
+  colorize?: boolean;
+}
+
+export function createRequestLogger(options?: RequestLoggerOptions): RequestHandler;
+
+export const requestLogger: RequestHandler;
+
+/* ─── correlationId ───────────────────────────────────────────────── */
+
+export interface CorrelationIdOptions {
+  header?: string;
+  generator?: () => string;
+  setResponseHeader?: boolean;
+}
+
+export function correlationId(options?: CorrelationIdOptions): RequestHandler;
+
+/* ─── notFoundHandler ─────────────────────────────────────────────── */
+
+export interface NotFoundHandlerOptions {
+  message?: string;
+}
+
+export function notFoundHandler(options?: NotFoundHandlerOptions): RequestHandler;
+
+/* ─── responseHelpers ─────────────────────────────────────────────── */
+
+export interface PaginationMeta {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+  hasNextPage: boolean;
+  hasPrevPage: boolean;
+}
+
+export function sendSuccess(
+  res: Response,
+  data: any,
+  message?: string,
+  statusCode?: number,
+  meta?: object,
+): void;
+
+export function sendError(
+  res: Response,
+  message?: string,
+  statusCode?: number,
+  errors?: any[] | null,
+  code?: string,
+): void;
+
+export function sendPaginated(
+  res: Response,
+  items: any[],
+  pagination: { page: number; limit: number; total: number },
+  message?: string,
+): void;
+
+/* ─── httpStatus ──────────────────────────────────────────────────── */
+
+export const httpStatus: {
+  readonly OK: 200;
+  readonly CREATED: 201;
+  readonly ACCEPTED: 202;
+  readonly NO_CONTENT: 204;
+  readonly MOVED_PERMANENTLY: 301;
+  readonly FOUND: 302;
+  readonly NOT_MODIFIED: 304;
+  readonly TEMPORARY_REDIRECT: 307;
+  readonly PERMANENT_REDIRECT: 308;
+  readonly BAD_REQUEST: 400;
+  readonly UNAUTHORIZED: 401;
+  readonly FORBIDDEN: 403;
+  readonly NOT_FOUND: 404;
+  readonly METHOD_NOT_ALLOWED: 405;
+  readonly CONFLICT: 409;
+  readonly GONE: 410;
+  readonly UNPROCESSABLE_ENTITY: 422;
+  readonly TOO_MANY_REQUESTS: 429;
+  readonly INTERNAL_SERVER_ERROR: 500;
+  readonly NOT_IMPLEMENTED: 501;
+  readonly BAD_GATEWAY: 502;
+  readonly SERVICE_UNAVAILABLE: 503;
+  readonly GATEWAY_TIMEOUT: 504;
+};
+
+/* ─── Express augmentation ────────────────────────────────────────── */
+
+declare global {
+  namespace Express {
+    interface Request {
+      id?: string;
+    }
+  }
+}