@geekmidas/errors 10.0.0-alpha.12 → 10.0.0-alpha.121

package/dist/index.d.cts

@@ -12,7 +12,7 @@
  * });
  * ```
  */
-declare class HttpError extends Error {
+export 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') */
@@ -23,6 +23,13 @@ declare class HttpError extends Error {
   readonly details?: any;
   /** Application-specific error code for client-side handling */
   readonly code?: string;
+  /**
+   * Headers the response that reports this error carries — a 429's
+   * `Retry-After`, a 401's `WWW-Authenticate`. Every endpoint adaptor sets
+   * them on the error response, so the error says everything the client is
+   * told.
+   */
+  readonly headers?: Readonly<Record<string, string>>;
   /**
    * Creates a new HttpError instance.
    *
@@ -32,12 +39,14 @@ declare class HttpError extends Error {
    * @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.headers - Headers the error response carries
    * @param options.cause - The underlying error that caused this error (ES2022)
    */
   constructor(statusCode: number, message?: string, options?: {
     statusMessage?: string;
     details?: any;
     code?: string;
+    headers?: Readonly<Record<string, string>>;
     cause?: Error;
   });
   /**
@@ -82,7 +91,7 @@ declare class HttpError extends Error {
  * throw new BadRequestError('Invalid JSON', { line: 5, column: 12 });
  * ```
  */
-declare class BadRequestError extends HttpError {
+export declare class BadRequestError extends HttpError {
   constructor(message?: string, details?: any);
 }
 /**
@@ -96,7 +105,7 @@ declare class BadRequestError extends HttpError {
  * throw new UnauthorizedError('Invalid token');
  * ```
  */
-declare class UnauthorizedError extends HttpError {
+export declare class UnauthorizedError extends HttpError {
   constructor(message?: string, details?: any);
 }
 /**
@@ -110,7 +119,7 @@ declare class UnauthorizedError extends HttpError {
  * throw new ForbiddenError('Insufficient permissions', { required: 'admin' });
  * ```
  */
-declare class ForbiddenError extends HttpError {
+export declare class ForbiddenError extends HttpError {
   constructor(message?: string, details?: any);
 }
 /**
@@ -124,7 +133,7 @@ declare class ForbiddenError extends HttpError {
  * throw new NotFoundError('User not found', { userId: '123' });
  * ```
  */
-declare class NotFoundError extends HttpError {
+export declare class NotFoundError extends HttpError {
   constructor(message?: string, details?: any);
 }
 /**
@@ -138,7 +147,7 @@ declare class NotFoundError extends HttpError {
  * throw new MethodNotAllowedError('DELETE not supported', ['GET', 'POST', 'PUT']);
  * ```
  */
-declare class MethodNotAllowedError extends HttpError {
+export declare class MethodNotAllowedError extends HttpError {
   /**
    * @param message - Optional error message
    * @param allowedMethods - Array of allowed HTTP methods for this resource
@@ -156,7 +165,7 @@ declare class MethodNotAllowedError extends HttpError {
  * throw new ConflictError('Email already exists', { email: 'user@example.com' });
  * ```
  */
-declare class ConflictError extends HttpError {
+export declare class ConflictError extends HttpError {
   constructor(message?: string, details?: any);
 }
 /**
@@ -173,7 +182,7 @@ declare class ConflictError extends HttpError {
  * });
  * ```
  */
-declare class UnprocessableEntityError extends HttpError {
+export declare class UnprocessableEntityError extends HttpError {
   /**
    * @param message - Optional error message
    * @param validationErrors - Object containing field-specific validation errors
@@ -191,12 +200,19 @@ declare class UnprocessableEntityError extends HttpError {
  * throw new TooManyRequestsError('Rate limit exceeded', 60); // retry after 60 seconds
  * ```
  */
-declare class TooManyRequestsError extends HttpError {
+export declare class TooManyRequestsError extends HttpError {
+  /** Seconds the client should wait before retrying, where known. */
+  readonly retryAfter?: number;
   /**
    * @param message - Optional error message
-   * @param retryAfter - Number of seconds the client should wait before retrying
+   * @param retryAfter - Number of seconds the client should wait before
+   * retrying, sent as the `Retry-After` header
+   * @param options.headers - Further headers the response carries, such as
+   * a rate limiter's `X-RateLimit-*`
    */
-  constructor(message?: string, retryAfter?: number);
+  constructor(message?: string, retryAfter?: number, options?: {
+    headers?: Readonly<Record<string, string>>;
+  });
 }
 /**
  * Represents a 500 Internal Server Error.
@@ -209,7 +225,7 @@ declare class TooManyRequestsError extends HttpError {
  * throw new InternalServerError('Database connection failed');
  * ```
  */
-declare class InternalServerError extends HttpError {
+export declare class InternalServerError extends HttpError {
   constructor(message?: string, details?: any);
 }
 /**
@@ -223,7 +239,7 @@ declare class InternalServerError extends HttpError {
  * throw new NotImplementedError('WebSocket support not implemented');
  * ```
  */
-declare class NotImplementedError extends HttpError {
+export declare class NotImplementedError extends HttpError {
   constructor(message?: string, details?: any);
 }
 /**
@@ -237,7 +253,7 @@ declare class NotImplementedError extends HttpError {
  * throw new BadGatewayError('Upstream server error');
  * ```
  */
-declare class BadGatewayError extends HttpError {
+export declare class BadGatewayError extends HttpError {
   constructor(message?: string, details?: any);
 }
 /**
@@ -251,7 +267,7 @@ declare class BadGatewayError extends HttpError {
  * throw new ServiceUnavailableError('Maintenance in progress', 300); // retry after 5 minutes
  * ```
  */
-declare class ServiceUnavailableError extends HttpError {
+export declare class ServiceUnavailableError extends HttpError {
   /**
    * @param message - Optional error message
    * @param retryAfter - Number of seconds the client should wait before retrying
@@ -269,61 +285,61 @@ declare class ServiceUnavailableError extends HttpError {
  * throw new GatewayTimeoutError('Upstream server timeout');
  * ```
  */
-declare class GatewayTimeoutError extends HttpError {
+export 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 type: 'standard';
     readonly factory: (m: string, d: any) => BadRequestError;
   };
   readonly 401: {
-    readonly type: "standard";
+    readonly type: 'standard';
     readonly factory: (m: string, d: any) => UnauthorizedError;
   };
   readonly 403: {
-    readonly type: "standard";
+    readonly type: 'standard';
     readonly factory: (m: string, d: any) => ForbiddenError;
   };
   readonly 404: {
-    readonly type: "standard";
+    readonly type: 'standard';
     readonly factory: (m: string, d: any) => NotFoundError;
   };
   readonly 405: {
-    readonly type: "methodNotAllowed";
+    readonly type: 'methodNotAllowed';
     readonly factory: (m: string, am: string[]) => MethodNotAllowedError;
   };
   readonly 409: {
-    readonly type: "standard";
+    readonly type: 'standard';
     readonly factory: (m: string, d: any) => ConflictError;
   };
   readonly 422: {
-    readonly type: "validation";
+    readonly type: 'validation';
     readonly factory: (m: string, ve: any) => UnprocessableEntityError;
   };
   readonly 429: {
-    readonly type: "retryAfter";
+    readonly type: 'retryAfter';
     readonly factory: (m: string, ra: number) => TooManyRequestsError;
   };
   readonly 500: {
-    readonly type: "standard";
+    readonly type: 'standard';
     readonly factory: (m: string, d: any) => InternalServerError;
   };
   readonly 501: {
-    readonly type: "standard";
+    readonly type: 'standard';
     readonly factory: (m: string, d: any) => NotImplementedError;
   };
   readonly 502: {
-    readonly type: "standard";
+    readonly type: 'standard';
     readonly factory: (m: string, d: any) => BadGatewayError;
   };
   readonly 503: {
-    readonly type: "retryAfter";
+    readonly type: 'retryAfter';
     readonly factory: (m: string, ra: number) => ServiceUnavailableError;
   };
   readonly 504: {
-    readonly type: "standard";
+    readonly type: 'standard';
     readonly factory: (m: string, d: any) => GatewayTimeoutError;
   };
 };
@@ -366,8 +382,8 @@ type ErrorOptions<T extends number> = T extends 405 ? {
  * 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;
+export declare function createHttpError<T extends ValidStatusCode>(statusCode: T, message?: string, options?: ErrorOptions<T>): HttpError;
+export 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.
@@ -379,7 +395,7 @@ declare function createHttpError(statusCode: number, message?: string, options?:
  * createError.methodNotAllowed('DELETE not supported', ['GET', 'POST']);
  * ```
  */
-declare const createError: {
+export declare const createError: {
   readonly badRequest: (message?: string, details?: any) => BadRequestError;
   readonly unauthorized: (message?: string, details?: any) => UnauthorizedError;
   readonly forbidden: (message?: string, details?: any) => ForbiddenError;
@@ -412,7 +428,7 @@ declare const createError: {
  * }
  * ```
  */
-declare function isHttpError(error: unknown): error is HttpError;
+export declare function isHttpError(error: unknown): error is HttpError;
 /**
  * Type guard to check if an error is a client error (4xx status code).
  *
@@ -426,7 +442,7 @@ declare function isHttpError(error: unknown): error is HttpError;
  * }
  * ```
  */
-declare function isClientError(error: unknown): error is HttpError;
+export declare function isClientError(error: unknown): error is HttpError;
 /**
  * Type guard to check if an error is a server error (5xx status code).
  *
@@ -440,10 +456,16 @@ declare function isClientError(error: unknown): error is HttpError;
  * }
  * ```
  */
-declare function isServerError(error: unknown): error is HttpError;
+export 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.
+ *
+ * One rule: an error that is an HttpError ({@link isHttpError}) passes
+ * through unchanged, its status and headers with it; anything else — however
+ * it is shaped, a `statusCode` field included — becomes `statusCode` (500 by
+ * default). An error that should answer with its own status extends
+ * HttpError, so the decision is made where the error is defined rather than
+ * guessed from its fields here.
  *
  * @param error - The error to wrap
  * @param statusCode - The HTTP status code to use (defaults to 500)
@@ -459,26 +481,27 @@ declare function isServerError(error: unknown): error is HttpError;
  * }
  * ```
  */
-declare function wrapError(error: unknown, statusCode?: number, message?: string): HttpError;
+export declare function wrapError(error: unknown, statusCode?: number, message?: string): HttpError;
 /**
  * Options for creating an HttpError.
  */
-interface HttpErrorOptions {
+export interface HttpErrorOptions {
   statusMessage?: string;
   details?: any;
   code?: string;
+  headers?: Readonly<Record<string, string>>;
   cause?: Error;
 }
 /**
  * Constructor type for HttpError classes.
  * Useful for factory patterns and dependency injection.
  */
-type HttpErrorConstructor = new (message?: string, options?: HttpErrorOptions) => HttpError;
+export 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 {
+export declare enum HttpStatusCode {
   OK = 200,
   CREATED = 201,
   ACCEPTED = 202,
@@ -501,7 +524,7 @@ declare enum HttpStatusCode {
   NOT_IMPLEMENTED = 501,
   BAD_GATEWAY = 502,
   SERVICE_UNAVAILABLE = 503,
-  GATEWAY_TIMEOUT = 504,
+  GATEWAY_TIMEOUT = 504
 }
 /**
  * Namespace containing all HTTP error classes.
@@ -513,7 +536,7 @@ declare enum HttpStatusCode {
  * throw new HttpErrors.NotFoundError('Resource not found');
  * ```
  */
-declare const HttpErrors: {
+export declare const HttpErrors: {
   HttpError: typeof HttpError;
   BadRequestError: typeof BadRequestError;
   UnauthorizedError: typeof UnauthorizedError;
@@ -530,5 +553,4 @@ declare const HttpErrors: {
   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

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;AAeA;;;;AAAoC;AA4HpC;AAiBA;AAiBA;AAiBA;AAiBA;AAuBA;AAoBA;AAuBa,cAlQA,SAAA,SAAkB,KAAA,CAkQW;EAyB7B;EAiBA,SAAA,UAAA,EAAA,MAAoB;EAiBpB;EAiBA,SAAA,aAAA,EAAA,MAAwB;EAuBxB;EA+BP,SAAA,WAqDI,GAAA,IAAA;EAAA;EAAA,SAlDmB,OAAA,CAAA,EAAA,GAAA;EAAA;EAIA,SAIA,IAAA,CAAA,EAAA,MAAA;EAAA;;;;;;;;;;AAwCA;EAKxB,WAAA,CAAA,UAAe,EAAA,MAAgB,EAAA,OAAa,CAAb,EAAa,MAAA,EAAA,OAIW,CAJX,EAAA;IAG5C,aAAY,CAAA,EAAA,MAAA;IAAA,OAAA,CAAA,EAAA,GAAA;IAAqB,IAAA,CAAA,EAAA,MAAA;IACiB,KAAA,CAAA,EAla5C,KAka4C;EAAK,CAAA;EACxD;;;;AAI8C;AAoClD;EAA+B,IAAA,IAAA,CAAA,CAAA,EAAA,MAAA;EAAA;;;;;AAInB;AACZ;EAA+B,QAAA,uBAAA;EAAA;;AAInB;AA4BZ;;;EAC6C,MAGE,CAAA,CAAA,EAAA;IAGH,IAAA,EAAA,MAAA;IAGD,OAAA,EAAA,MAAA;IAGoB,UAAA,EAAA,MAAA;IAGpB,aAAA,EAAA,MAAA;IAGoB,IAAA,EAAA,MAAA,GAAA,SAAA;IAGP,OAAA,EAAA,GAAA;IAGF,KAAA,EAAA,MAAA,GAAA,SAAA;EAAA,CAAA;;;;AAYL;AAwBjD;AAuBA;AAmBA;AA0BA;AAuBA;AAWA;;;AAGK,cAxjBQ,eAAA,SAAwB,SAAS,CAwjBzC;EAAS,WAAA,CAAA,OAAA,CAAA,EAAA,MAAA,EAAA,OAAA,CAAA,EAAA,GAAA;AAMd;AA2CA;;;;;;;;;;;cAxlBa,iBAAA,SAA0B,SAAS;;;;;;;;;;;;;;cAiBnC,cAAA,SAAuB,SAAS;;;;;;;;;;;;;;cAiBhC,aAAA,SAAsB,SAAS;;;;;;;;;;;;;;cAiB/B,qBAAA,SAA8B,SAAS;;;;;;;;;;;;;;;;;;cAuBvC,aAAA,SAAsB,SAAS;;;;;;;;;;;;;;;;;cAoB/B,wBAAA,SAAiC,SAAS;;;;;;;;;;;;;;;;;;cAuB1C,oBAAA,SAA6B,SAAS;;;;;;;;;;;;;;;;;;cAyBtC,mBAAA,SAA4B,SAAS;;;;;;;;;;;;;;cAiBrC,mBAAA,SAA4B,SAAS;;;;;;;;;;;;;;cAiBrC,eAAA,SAAwB,SAAS;;;;;;;;;;;;;;cAiBjC,uBAAA,SAAgC,SAAS;;;;;;;;;;;;;;;;;;cAuBzC,mBAAA,SAA4B,SAAS;;;;cA+B5C;;;6CAGuB;;;;6CAIA;;;;6CAIA;;;;6CAIA;;;;mDAIM;;;;6CAIN;;;;8CAIC;;;;iDAIG;;;;6CAIJ;;;;6CAIA;;;;6CAIA;;;;iDAII;;;;6CAIJ;;;;KAKxB,eAAA,gBAA+B;;KAG/B,iCAAiC;;;UACiB;IACpD;;;UACkD;IACjD;;;UAC+C;;;;UACN;;;;;;;;;;;;;;;;;;;;;iBAoC7B,0BAA0B,6BAC7B,+BAEF,aAAa,KACrB;iBACa,eAAA,iDAGL,mBACR;;;;;;;;;;;;cA4BU;4DACgC;8DAGE;2DAGH;0DAGD;8EAGoB;0DAGpB;8EAGoB;uEAGP;qEAGF;gEAGL;4DAGJ;0EAGc;gEAGV;;;;;;;;;;;;;;;;;;;;iBAwBjC,WAAA,2BAAsC;;;;;;;;;;;;;;iBAuBtC,aAAA,2BAAwC;;;;;;;;;;;;;;iBAmBxC,aAAA,2BAAwC;;;;;;;;;;;;;;;;;;;iBA0BxC,SAAA,yDAIb;;;;UAmBc,gBAAA;;;;UAIR;;;;;;KAOG,oBAAA,oCAED,qBACN;;;;;aAMO,cAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA2CC;oBAeZ"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":"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"}