@geekmidas/errors 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,534 @@
+//#region src/index.d.ts
+/**
+ * Base HTTP Error class that extends the native Error.
+ * Provides a foundation for all HTTP-specific errors with status codes and structured error responses.
+ *
+ * @extends Error
+ *
+ * @example
+ * ```typescript
+ * throw new HttpError(400, 'Bad Request', {
+ *   details: { field: 'email', message: 'Invalid format' }
+ * });
+ * ```
+ */
+declare class HttpError extends Error {
+  /** The HTTP status code (e.g., 400, 404, 500) */
+  readonly statusCode: number;
+  /** The standard HTTP status message (e.g., 'Bad Request', 'Not Found') */
+  readonly statusMessage: string;
+  /** Type discriminator for runtime type checking */
+  readonly isHttpError = true;
+  /** Additional error details for debugging or client information */
+  readonly details?: any;
+  /** Application-specific error code for client-side handling */
+  readonly code?: string;
+  /**
+   * Creates a new HttpError instance.
+   *
+   * @param statusCode - The HTTP status code
+   * @param message - Optional error message for the client
+   * @param options - Optional configuration object
+   * @param options.statusMessage - Override the default status message
+   * @param options.details - Additional error details or context
+   * @param options.code - Application-specific error code
+   * @param options.cause - The underlying error that caused this error (ES2022)
+   */
+  constructor(statusCode: number, message?: string, options?: {
+    statusMessage?: string;
+    details?: any;
+    code?: string;
+    cause?: Error;
+  });
+  /**
+   * Gets the error response body as a JSON string.
+   * Used for sending the error response to clients.
+   *
+   * @returns JSON string containing message, code, and error details
+   */
+  get body(): string;
+  /**
+   * Gets the default HTTP status message for a given status code.
+   *
+   * @param statusCode - The HTTP status code
+   * @returns The standard HTTP status message or 'Unknown Error' if not found
+   * @private
+   */
+  private getDefaultStatusMessage;
+  /**
+   * Serializes the error to a JSON-compatible object.
+   * Useful for logging and debugging purposes.
+   *
+   * @returns Object representation of the error including stack trace
+   */
+  toJSON(): {
+    name: string;
+    message: string;
+    statusCode: number;
+    statusMessage: string;
+    code: string | undefined;
+    details: any;
+    stack: string | undefined;
+  };
+}
+/**
+ * Represents a 400 Bad Request error.
+ * Used when the client sends a malformed or invalid request.
+ *
+ * @extends HttpError
+ *
+ * @example
+ * ```typescript
+ * throw new BadRequestError('Invalid JSON', { line: 5, column: 12 });
+ * ```
+ */
+declare class BadRequestError extends HttpError {
+  constructor(message?: string, details?: any);
+}
+/**
+ * Represents a 401 Unauthorized error.
+ * Used when authentication is required but not provided or invalid.
+ *
+ * @extends HttpError
+ *
+ * @example
+ * ```typescript
+ * throw new UnauthorizedError('Invalid token');
+ * ```
+ */
+declare class UnauthorizedError extends HttpError {
+  constructor(message?: string, details?: any);
+}
+/**
+ * Represents a 403 Forbidden error.
+ * Used when the client is authenticated but lacks permission for the resource.
+ *
+ * @extends HttpError
+ *
+ * @example
+ * ```typescript
+ * throw new ForbiddenError('Insufficient permissions', { required: 'admin' });
+ * ```
+ */
+declare class ForbiddenError extends HttpError {
+  constructor(message?: string, details?: any);
+}
+/**
+ * Represents a 404 Not Found error.
+ * Used when the requested resource doesn't exist.
+ *
+ * @extends HttpError
+ *
+ * @example
+ * ```typescript
+ * throw new NotFoundError('User not found', { userId: '123' });
+ * ```
+ */
+declare class NotFoundError extends HttpError {
+  constructor(message?: string, details?: any);
+}
+/**
+ * Represents a 405 Method Not Allowed error.
+ * Used when the HTTP method is not supported for the requested resource.
+ *
+ * @extends HttpError
+ *
+ * @example
+ * ```typescript
+ * throw new MethodNotAllowedError('DELETE not supported', ['GET', 'POST', 'PUT']);
+ * ```
+ */
+declare class MethodNotAllowedError extends HttpError {
+  /**
+   * @param message - Optional error message
+   * @param allowedMethods - Array of allowed HTTP methods for this resource
+   */
+  constructor(message?: string, allowedMethods?: string[]);
+}
+/**
+ * Represents a 409 Conflict error.
+ * Used when the request conflicts with the current state of the resource.
+ *
+ * @extends HttpError
+ *
+ * @example
+ * ```typescript
+ * throw new ConflictError('Email already exists', { email: 'user@example.com' });
+ * ```
+ */
+declare class ConflictError extends HttpError {
+  constructor(message?: string, details?: any);
+}
+/**
+ * Represents a 422 Unprocessable Entity error.
+ * Used when the request is well-formed but contains semantic errors.
+ *
+ * @extends HttpError
+ *
+ * @example
+ * ```typescript
+ * throw new UnprocessableEntityError('Validation failed', {
+ *   email: 'Invalid format',
+ *   age: 'Must be 18 or older'
+ * });
+ * ```
+ */
+declare class UnprocessableEntityError extends HttpError {
+  /**
+   * @param message - Optional error message
+   * @param validationErrors - Object containing field-specific validation errors
+   */
+  constructor(message?: string, validationErrors?: any);
+}
+/**
+ * Represents a 429 Too Many Requests error.
+ * Used when the client has exceeded rate limits.
+ *
+ * @extends HttpError
+ *
+ * @example
+ * ```typescript
+ * throw new TooManyRequestsError('Rate limit exceeded', 60); // retry after 60 seconds
+ * ```
+ */
+declare class TooManyRequestsError extends HttpError {
+  /**
+   * @param message - Optional error message
+   * @param retryAfter - Number of seconds the client should wait before retrying
+   */
+  constructor(message?: string, retryAfter?: number);
+}
+/**
+ * Represents a 500 Internal Server Error.
+ * Used for unexpected server-side errors.
+ *
+ * @extends HttpError
+ *
+ * @example
+ * ```typescript
+ * throw new InternalServerError('Database connection failed');
+ * ```
+ */
+declare class InternalServerError extends HttpError {
+  constructor(message?: string, details?: any);
+}
+/**
+ * Represents a 501 Not Implemented error.
+ * Used when the server doesn't support the requested functionality.
+ *
+ * @extends HttpError
+ *
+ * @example
+ * ```typescript
+ * throw new NotImplementedError('WebSocket support not implemented');
+ * ```
+ */
+declare class NotImplementedError extends HttpError {
+  constructor(message?: string, details?: any);
+}
+/**
+ * Represents a 502 Bad Gateway error.
+ * Used when the server receives an invalid response from an upstream server.
+ *
+ * @extends HttpError
+ *
+ * @example
+ * ```typescript
+ * throw new BadGatewayError('Upstream server error');
+ * ```
+ */
+declare class BadGatewayError extends HttpError {
+  constructor(message?: string, details?: any);
+}
+/**
+ * Represents a 503 Service Unavailable error.
+ * Used when the server is temporarily unable to handle requests.
+ *
+ * @extends HttpError
+ *
+ * @example
+ * ```typescript
+ * throw new ServiceUnavailableError('Maintenance in progress', 300); // retry after 5 minutes
+ * ```
+ */
+declare class ServiceUnavailableError extends HttpError {
+  /**
+   * @param message - Optional error message
+   * @param retryAfter - Number of seconds the client should wait before retrying
+   */
+  constructor(message?: string, retryAfter?: number);
+}
+/**
+ * Represents a 504 Gateway Timeout error.
+ * Used when the server doesn't receive a timely response from an upstream server.
+ *
+ * @extends HttpError
+ *
+ * @example
+ * ```typescript
+ * throw new GatewayTimeoutError('Upstream server timeout');
+ * ```
+ */
+declare class GatewayTimeoutError extends HttpError {
+  constructor(message?: string, details?: any);
+}
+/** Type-safe error registry mapping status codes to their factory functions */
+declare const errorRegistry: {
+  readonly 400: {
+    readonly type: "standard";
+    readonly factory: (m: string, d: any) => BadRequestError;
+  };
+  readonly 401: {
+    readonly type: "standard";
+    readonly factory: (m: string, d: any) => UnauthorizedError;
+  };
+  readonly 403: {
+    readonly type: "standard";
+    readonly factory: (m: string, d: any) => ForbiddenError;
+  };
+  readonly 404: {
+    readonly type: "standard";
+    readonly factory: (m: string, d: any) => NotFoundError;
+  };
+  readonly 405: {
+    readonly type: "methodNotAllowed";
+    readonly factory: (m: string, am: string[]) => MethodNotAllowedError;
+  };
+  readonly 409: {
+    readonly type: "standard";
+    readonly factory: (m: string, d: any) => ConflictError;
+  };
+  readonly 422: {
+    readonly type: "validation";
+    readonly factory: (m: string, ve: any) => UnprocessableEntityError;
+  };
+  readonly 429: {
+    readonly type: "retryAfter";
+    readonly factory: (m: string, ra: number) => TooManyRequestsError;
+  };
+  readonly 500: {
+    readonly type: "standard";
+    readonly factory: (m: string, d: any) => InternalServerError;
+  };
+  readonly 501: {
+    readonly type: "standard";
+    readonly factory: (m: string, d: any) => NotImplementedError;
+  };
+  readonly 502: {
+    readonly type: "standard";
+    readonly factory: (m: string, d: any) => BadGatewayError;
+  };
+  readonly 503: {
+    readonly type: "retryAfter";
+    readonly factory: (m: string, ra: number) => ServiceUnavailableError;
+  };
+  readonly 504: {
+    readonly type: "standard";
+    readonly factory: (m: string, d: any) => GatewayTimeoutError;
+  };
+};
+/** Valid status codes that have registered error factories */
+type ValidStatusCode = keyof typeof errorRegistry;
+/** Type-safe options based on status code, ensuring correct parameters for each error type */
+type ErrorOptions<T extends number> = T extends 405 ? {
+  allowedMethods?: string[];
+  code?: string;
+  cause?: Error;
+} : T extends 422 ? {
+  validationErrors?: any;
+  code?: string;
+  cause?: Error;
+} : T extends 429 | 503 ? {
+  retryAfter?: number;
+  code?: string;
+  cause?: Error;
+} : {
+  details?: any;
+  code?: string;
+  cause?: Error;
+};
+/**
+ * Creates an HTTP error with type-safe options based on the status code.
+ * Provides IntelliSense support for status-code-specific options.
+ *
+ * @overload For known status codes with specific options
+ * @param statusCode - A valid HTTP status code from the registry
+ * @param message - Optional error message
+ * @param options - Status-code-specific options
+ * @returns The appropriate HttpError subclass
+ *
+ * @example
+ * ```typescript
+ * // TypeScript knows allowedMethods is valid for 405
+ * createHttpError(405, 'Method not allowed', { allowedMethods: ['GET', 'POST'] });
+ *
+ * // TypeScript knows retryAfter is valid for 429
+ * createHttpError(429, 'Rate limited', { retryAfter: 60 });
+ * ```
+ */
+declare function createHttpError<T extends ValidStatusCode>(statusCode: T, message?: string, options?: ErrorOptions<T>): HttpError;
+declare function createHttpError(statusCode: number, message?: string, options?: HttpErrorOptions): HttpError;
+/**
+ * Type-safe error creation utilities with descriptive method names.
+ * Provides a fluent API for creating specific HTTP errors.
+ *
+ * @example
+ * ```typescript
+ * createError.notFound('User not found');
+ * createError.badRequest('Invalid input', { field: 'email' });
+ * createError.methodNotAllowed('DELETE not supported', ['GET', 'POST']);
+ * ```
+ */
+declare const createError: {
+  readonly badRequest: (message?: string, details?: any) => BadRequestError;
+  readonly unauthorized: (message?: string, details?: any) => UnauthorizedError;
+  readonly forbidden: (message?: string, details?: any) => ForbiddenError;
+  readonly notFound: (message?: string, details?: any) => NotFoundError;
+  readonly methodNotAllowed: (message?: string, allowedMethods?: string[]) => MethodNotAllowedError;
+  readonly conflict: (message?: string, details?: any) => ConflictError;
+  readonly unprocessableEntity: (message?: string, validationErrors?: any) => UnprocessableEntityError;
+  readonly tooManyRequests: (message?: string, retryAfter?: number) => TooManyRequestsError;
+  readonly internalServerError: (message?: string, details?: any) => InternalServerError;
+  readonly notImplemented: (message?: string, details?: any) => NotImplementedError;
+  readonly badGateway: (message?: string, details?: any) => BadGatewayError;
+  readonly serviceUnavailable: (message?: string, retryAfter?: number) => ServiceUnavailableError;
+  readonly gatewayTimeout: (message?: string, details?: any) => GatewayTimeoutError;
+};
+/**
+ * Type guard to check if an error is an HttpError.
+ * Works with both instanceof checks and duck typing.
+ *
+ * @param error - The error to check
+ * @returns True if the error is an HttpError
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // some code
+ * } catch (error) {
+ *   if (isHttpError(error)) {
+ *     console.log(`HTTP ${error.statusCode}: ${error.message}`);
+ *   }
+ * }
+ * ```
+ */
+declare function isHttpError(error: unknown): error is HttpError;
+/**
+ * Type guard to check if an error is a client error (4xx status code).
+ *
+ * @param error - The error to check
+ * @returns True if the error is an HttpError with a 4xx status code
+ *
+ * @example
+ * ```typescript
+ * if (isClientError(error)) {
+ *   // Log client error metrics
+ * }
+ * ```
+ */
+declare function isClientError(error: unknown): error is HttpError;
+/**
+ * Type guard to check if an error is a server error (5xx status code).
+ *
+ * @param error - The error to check
+ * @returns True if the error is an HttpError with a 5xx status code
+ *
+ * @example
+ * ```typescript
+ * if (isServerError(error)) {
+ *   // Trigger alerts for server errors
+ * }
+ * ```
+ */
+declare function isServerError(error: unknown): error is HttpError;
+/**
+ * Wraps an unknown error into an HttpError.
+ * If the error is already an HttpError, returns it unchanged.
+ *
+ * @param error - The error to wrap
+ * @param statusCode - The HTTP status code to use (defaults to 500)
+ * @param message - Optional message to override the original error message
+ * @returns An HttpError instance
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await someOperation();
+ * } catch (error) {
+ *   throw wrapError(error, 503, 'Service temporarily unavailable');
+ * }
+ * ```
+ */
+declare function wrapError(error: unknown, statusCode?: number, message?: string): HttpError;
+/**
+ * Options for creating an HttpError.
+ */
+interface HttpErrorOptions {
+  statusMessage?: string;
+  details?: any;
+  code?: string;
+  cause?: Error;
+}
+/**
+ * Constructor type for HttpError classes.
+ * Useful for factory patterns and dependency injection.
+ */
+type HttpErrorConstructor = new (message?: string, options?: HttpErrorOptions) => HttpError;
+/**
+ * HTTP status code enum for type-safe status code usage.
+ * Includes common 2xx, 3xx, 4xx, and 5xx status codes.
+ */
+declare enum HttpStatusCode {
+  OK = 200,
+  CREATED = 201,
+  ACCEPTED = 202,
+  NO_CONTENT = 204,
+  MOVED_PERMANENTLY = 301,
+  FOUND = 302,
+  NOT_MODIFIED = 304,
+  BAD_REQUEST = 400,
+  UNAUTHORIZED = 401,
+  FORBIDDEN = 403,
+  NOT_FOUND = 404,
+  METHOD_NOT_ALLOWED = 405,
+  NOT_ACCEPTABLE = 406,
+  REQUEST_TIMEOUT = 408,
+  CONFLICT = 409,
+  GONE = 410,
+  UNPROCESSABLE_ENTITY = 422,
+  TOO_MANY_REQUESTS = 429,
+  INTERNAL_SERVER_ERROR = 500,
+  NOT_IMPLEMENTED = 501,
+  BAD_GATEWAY = 502,
+  SERVICE_UNAVAILABLE = 503,
+  GATEWAY_TIMEOUT = 504,
+}
+/**
+ * Namespace containing all HTTP error classes.
+ * Useful for importing all error types at once.
+ *
+ * @example
+ * ```typescript
+ * import { HttpErrors } from '@geekmidas/errors';
+ * throw new HttpErrors.NotFoundError('Resource not found');
+ * ```
+ */
+declare const HttpErrors: {
+  HttpError: typeof HttpError;
+  BadRequestError: typeof BadRequestError;
+  UnauthorizedError: typeof UnauthorizedError;
+  ForbiddenError: typeof ForbiddenError;
+  NotFoundError: typeof NotFoundError;
+  MethodNotAllowedError: typeof MethodNotAllowedError;
+  ConflictError: typeof ConflictError;
+  UnprocessableEntityError: typeof UnprocessableEntityError;
+  TooManyRequestsError: typeof TooManyRequestsError;
+  InternalServerError: typeof InternalServerError;
+  NotImplementedError: typeof NotImplementedError;
+  BadGatewayError: typeof BadGatewayError;
+  ServiceUnavailableError: typeof ServiceUnavailableError;
+  GatewayTimeoutError: typeof GatewayTimeoutError;
+};
+//#endregion
+export { BadGatewayError, BadRequestError, ConflictError, ForbiddenError, GatewayTimeoutError, HttpError, HttpErrorConstructor, HttpErrorOptions, HttpErrors, HttpStatusCode, InternalServerError, MethodNotAllowedError, NotFoundError, NotImplementedError, ServiceUnavailableError, TooManyRequestsError, UnauthorizedError, UnprocessableEntityError, createError, createHttpError, isClientError, isHttpError, isServerError, wrapError };
+//# sourceMappingURL=index.d.cts.map