@maroonedsoftware/errors 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marooned Software
+
+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.

package/README.md

@@ -0,0 +1,176 @@
+# @maroonedsoftware/errors
+
+A comprehensive error handling library for HTTP APIs with built-in support for PostgreSQL error mapping and class-level error decorators.
+
+## Installation
+
+```bash
+pnpm add @maroonedsoftware/errors
+```
+
+## Features
+
+- **HttpError** — Fluent HTTP error class with support for status codes, headers, details, and error chaining
+- **OnError** — Class decorator for automatic error handling on all methods
+- **PostgresErrorHandler** — Maps PostgreSQL error codes to appropriate HTTP errors
+- **Type-safe** — Full TypeScript support with inferred status messages
+
+## Usage
+
+### HttpError
+
+Create HTTP errors with fluent method chaining:
+
+```ts
+import { HttpError, httpError, unauthorizedError } from '@maroonedsoftware/errors';
+
+// Using the factory function
+throw httpError(404);
+
+// With custom message
+throw httpError(400, 'Validation failed');
+
+// With error details (great for form validation)
+throw httpError(400).withErrors({
+  email: 'Invalid email format',
+  password: 'Must be at least 8 characters',
+});
+
+// With response headers
+throw httpError(401).withHeaders({
+  'WWW-Authenticate': 'Bearer realm="api"',
+});
+
+// Shorthand for unauthorized with WWW-Authenticate header
+throw unauthorizedError('Bearer realm="api"');
+
+// With error chaining
+throw httpError(500).withCause(originalError);
+
+// With internal details (for logging, not exposed to clients)
+throw httpError(500).withInternalDetails({
+  userId: 123,
+  requestId: 'abc-123',
+});
+
+// Combine multiple options
+throw httpError(409).withErrors({ username: 'Already taken' }).withCause(dbError).withInternalDetails({ attemptedUsername: 'john_doe' });
+```
+
+### Type Guard
+
+Check if an error is an HttpError:
+
+```ts
+import { IsHttpError } from '@maroonedsoftware/errors';
+
+try {
+  await someOperation();
+} catch (error) {
+  if (IsHttpError(error)) {
+    console.log(error.statusCode); // Typed access
+    console.log(error.details);
+  }
+}
+```
+
+### OnError Decorator
+
+Automatically wrap all class methods with error handling:
+
+```ts
+import { OnError, httpError } from '@maroonedsoftware/errors';
+
+@OnError(error => {
+  console.error('Error caught:', error);
+  throw httpError(500).withCause(error);
+})
+class MyService {
+  async doSomething() {
+    // If this throws, it will be caught and handled
+    throw new Error('Something went wrong');
+  }
+
+  get computedValue() {
+    // Getters are also wrapped
+    throw new Error('Getter failed');
+  }
+}
+```
+
+### PostgreSQL Error Handling
+
+Convert PostgreSQL errors to appropriate HTTP errors:
+
+```ts
+import { PostgresErrorHandler, OnPostgresError } from '@maroonedsoftware/errors';
+
+// Manual usage
+try {
+  await db.insert(users).values({ email: 'duplicate@example.com' });
+} catch (error) {
+  PostgresErrorHandler(error);
+  // 23505 (unique violation) → 409 Conflict
+  // 23503 (foreign key violation) → 404 Not Found
+  // 23502, 22P02, 22003, 23514 (validation) → 400 Bad Request
+  // 40000, 40001, 40002 (transaction rollback) → 500 Internal Server Error
+  // 40P01 (deadlock) → 500 Internal Server Error
+}
+
+// Using the decorator (recommended)
+@OnPostgresError()
+class UserRepository {
+  async create(data: UserData) {
+    return await db.insert(users).values(data);
+  }
+
+  async findById(id: number) {
+    return await db.select().from(users).where(eq(users.id, id));
+  }
+}
+```
+
+## Supported HTTP Status Codes
+
+All standard 4xx and 5xx status codes are supported with their default messages:
+
+| Code | Message                                   |
+| ---- | ----------------------------------------- |
+| 400  | Bad Request                               |
+| 401  | Unauthorized                              |
+| 403  | Forbidden                                 |
+| 404  | Not Found                                 |
+| 409  | Conflict                                  |
+| 422  | Unprocessable Entity                      |
+| 429  | Too Many Requests                         |
+| 500  | Internal Server Error                     |
+| 502  | Bad Gateway                               |
+| 503  | Service Unavailable                       |
+| ...  | [and more](./src/http/http.status.map.ts) |
+
+## API Reference
+
+### HttpError
+
+| Property          | Type                      | Description                               |
+| ----------------- | ------------------------- | ----------------------------------------- |
+| `statusCode`      | `HttpStatusCodes`         | The HTTP status code                      |
+| `message`         | `string`                  | Error message                             |
+| `details`         | `Record<string, unknown>` | Validation/error details for response     |
+| `headers`         | `Record<string, string>`  | HTTP headers to include in response       |
+| `cause`           | `Error`                   | Underlying error (for error chaining)     |
+| `internalDetails` | `Record<string, unknown>` | Internal debugging info (not for clients) |
+
+### Methods
+
+| Method                         | Returns     | Description                 |
+| ------------------------------ | ----------- | --------------------------- |
+| `withErrors(errors)`           | `HttpError` | Add error details           |
+| `withHeaders(headers)`         | `HttpError` | Add response headers        |
+| `addHeader(key, value)`        | `HttpError` | Add a single header         |
+| `withCause(error)`             | `HttpError` | Set the underlying cause    |
+| `withInternalDetails(details)` | `HttpError` | Add internal debugging info |
+
+## License
+
+MIT

package/dist/http/http.error.d.ts

@@ -0,0 +1,154 @@
+import { HttpStatusMap } from './http.status.map.js';
+/**
+ * Type representing valid HTTP status codes from the HttpStatusMap.
+ */
+export type HttpStatusCodes = keyof typeof HttpStatusMap;
+/**
+ * Type representing the status message for a given HTTP status code.
+ * @template T - The HTTP status code type.
+ */
+export type HttpStatusMessage<T extends HttpStatusCodes> = (typeof HttpStatusMap)[T];
+/**
+ * Custom error class for HTTP errors with support for status codes, details, headers, and error chaining.
+ * Extends the native Error class and provides a fluent API for building error responses.
+ *
+ * @example
+ * ```ts
+ * throw new HttpError(404).withErrors({ field: 'not found' });
+ * ```
+ *
+ * @example
+ * ```ts
+ * throw new HttpError(401)
+ *   .withHeaders({ 'WWW-Authenticate': 'Bearer' })
+ *   .withCause(originalError);
+ * ```
+ */
+export declare class HttpError extends Error {
+    readonly statusCode: HttpStatusCodes;
+    /**
+     * Optional validation or error details to include in the response.
+     * Typically used for 400-level errors to provide field-specific error information.
+     */
+    details?: Record<string, unknown>;
+    /**
+     * Optional HTTP headers to include in the error response.
+     * Useful for authentication errors (e.g., WWW-Authenticate header).
+     */
+    headers?: Record<string, string>;
+    /**
+     * Optional underlying error that caused this HTTP error.
+     * Follows the Error.cause pattern for error chaining.
+     */
+    cause?: Error;
+    /**
+     * Optional internal details that should not be exposed to clients.
+     * Useful for debugging and logging purposes.
+     */
+    internalDetails?: Record<string, unknown>;
+    /**
+     * Creates a new HttpError instance.
+     *
+     * @param statusCode - The HTTP status code (must be a key from HttpStatusMap).
+     * @param message - Optional custom error message. If not provided, uses the default message from HttpStatusMap.
+     */
+    constructor(statusCode: HttpStatusCodes, message?: HttpStatusMessage<HttpStatusCodes>);
+    /**
+     * Adds error details to the HTTP error and returns the instance for method chaining.
+     *
+     * @param errors - Object containing field-specific error information.
+     * @returns The HttpError instance for method chaining.
+     *
+     * @example
+     * ```ts
+     * error.withErrors({ email: 'Invalid email format', password: 'Too short' });
+     * ```
+     */
+    withErrors(errors: Record<string, unknown>): HttpError;
+    /**
+     * Adds HTTP headers to the error response and returns the instance for method chaining.
+     *
+     * @param headers - Object containing HTTP header key-value pairs.
+     * @returns The HttpError instance for method chaining.
+     *
+     * @example
+     * ```ts
+     * error.withHeaders({ 'WWW-Authenticate': 'Bearer realm="api"' });
+     * ```
+     */
+    withHeaders(headers: Record<string, string>): HttpError;
+    /**
+     * Sets the underlying cause of this error and returns the instance for method chaining.
+     *
+     * @param cause - The original error that caused this HTTP error.
+     * @returns The HttpError instance for method chaining.
+     *
+     * @example
+     * ```ts
+     * error.withCause(new Error('Database connection failed'));
+     * ```
+     */
+    withCause(cause: Error): HttpError;
+    /**
+     * Adds internal details that should not be exposed to clients and returns the instance for method chaining.
+     *
+     * @param internalDetails - Object containing internal debugging information.
+     * @returns The HttpError instance for method chaining.
+     *
+     * @example
+     * ```ts
+     * error.withInternalDetails({ userId: 123, requestId: 'abc-123' });
+     * ```
+     */
+    withInternalDetails(internalDetails: Record<string, unknown>): HttpError;
+    /**
+     * Adds a HTTP header to the error response and returns the instance for method chaining.
+     *
+     * @param key - The HTTP header key.
+     * @param value - The HTTP header value.
+     * @returns The HttpError instance for method chaining.
+     */
+    addHeader(key: string, value: string): HttpError;
+}
+/**
+ * Type guard to check if an unknown value is an HttpError instance.
+ *
+ * @param error - The value to check.
+ * @returns True if the value is an HttpError instance, false otherwise.
+ *
+ * @example
+ * ```ts
+ * if (IsHttpError(error)) {
+ *   console.log(error.statusCode);
+ * }
+ * ```
+ */
+export declare const IsHttpError: (error: unknown) => error is HttpError;
+/**
+ * Factory function to create an HttpError instance with a specific status code.
+ *
+ * @template StatusCode - The HTTP status code type.
+ * @template StatusMessage - The status message type for the given status code.
+ * @param statusCode - The HTTP status code.
+ * @param message - Optional custom error message.
+ * @returns A new HttpError instance.
+ *
+ * @example
+ * ```ts
+ * throw httpError(404);
+ * ```
+ */
+export declare const httpError: <StatusCode extends HttpStatusCodes, StatusMessage extends HttpStatusMessage<StatusCode>>(statusCode: StatusCode, message?: StatusMessage) => HttpError;
+/**
+ * Factory function to create an unauthorized HttpError instance.
+ *
+ * @param error - The error message of the WWW-Authenticate header.
+ * @returns A new HttpError instance with the WWW-Authenticate header set to the given error message.
+ *
+ * @example
+ * ```ts
+ * throw unauthorizedError('Bearer realm="api"');
+ * ```
+ */
+export declare const unauthorizedError: (error: string) => HttpError;
+//# sourceMappingURL=http.error.d.ts.map

package/dist/http/http.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.error.d.ts","sourceRoot":"","sources":["../../src/http/http.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,aAAa,CAAC;AAEzD;;;GAGG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,eAAe,IAAI,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;AAErF;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAgChC,QAAQ,CAAC,UAAU,EAAE,eAAe;IA/BtC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IAEd;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE1C;;;;;OAKG;gBAEQ,UAAU,EAAE,eAAe,EACpC,OAAO,CAAC,EAAE,iBAAiB,CAAC,eAAe,CAAC;IAW9C;;;;;;;;;;OAUG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAKtD;;;;;;;;;;OAUG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS;IAKvD;;;;;;;;;;OAUG;IACH,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS;IAKlC;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAKxE;;;;;;OAMG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS;CAKjD;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,SAErD,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,SAAS,GAAI,UAAU,SAAS,eAAe,EAAE,aAAa,SAAS,iBAAiB,CAAC,UAAU,CAAC,EAC/G,YAAY,UAAU,EACtB,UAAU,aAAa,cACc,CAAC;AAExC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,cAAwD,CAAC"}

package/dist/http/http.status.map.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Map of HTTP status codes to their default status messages.
+ * Includes both client error (4xx) and server error (5xx) status codes.
+ *
+ * @example
+ * ```ts
+ * HttpStatusMap[404] // 'Not Found'
+ * HttpStatusMap[500] // 'Internal Server Error'
+ * ```
+ */
+export declare const HttpStatusMap: {
+    readonly 400: "Bad Request";
+    readonly 401: "Unauthorized";
+    readonly 402: "Payment Required";
+    readonly 403: "Forbidden";
+    readonly 404: "Not Found";
+    readonly 405: "Method Not Allowed";
+    readonly 406: "Not Acceptable";
+    readonly 407: "Proxy Authentication Required";
+    readonly 408: "Request Timeout";
+    readonly 409: "Conflict";
+    readonly 410: "Gone";
+    readonly 411: "Length Required";
+    readonly 412: "Precondition Failed";
+    readonly 413: "Payload Too Large";
+    readonly 414: "Request-URI Too Long";
+    readonly 415: "Unsupported Media Type";
+    readonly 416: "Requested Range Not Satisfiable";
+    readonly 417: "Expectation Failed";
+    readonly 418: "I'm a teapot";
+    readonly 421: "Misdirected Request";
+    readonly 422: "Unprocessable Entity";
+    readonly 423: "Locked";
+    readonly 424: "Failed Dependency";
+    readonly 426: "Upgrade Required";
+    readonly 428: "Precondition Required";
+    readonly 429: "Too Many Requests";
+    readonly 431: "Request Header Fields Too Large";
+    readonly 444: "Connection Closed Without Response";
+    readonly 451: "Unavailable For Legal Reasons";
+    readonly 499: "Client Closed Request";
+    readonly 500: "Internal Server Error";
+    readonly 501: "Not Implemented";
+    readonly 502: "Bad Gateway";
+    readonly 503: "Service Unavailable";
+    readonly 504: "Gateway Timeout";
+    readonly 505: "HTTP Version Not Supported";
+    readonly 506: "Variant Also Negotiates";
+    readonly 507: "Insufficient Storage";
+    readonly 508: "Loop Detected";
+    readonly 510: "Not Extended";
+    readonly 511: "Network Authentication Required";
+    readonly 599: "Network Connect Timeout Error";
+};
+//# sourceMappingURL=http.status.map.d.ts.map

package/dist/http/http.status.map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.status.map.d.ts","sourceRoot":"","sources":["../../src/http/http.status.map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2ChB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './http/http.error.js';
+export { OnError } from './on.error.decorator.js';
+export { PostgresErrorHandler } from './postgres/postgres.error.handler.js';
+export { OnPostgresError } from './postgres/postgres.error.decorator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC"}

package/dist/index.js

@@ -0,0 +1,269 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/http/http.status.map.ts
+var HttpStatusMap = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  402: "Payment Required",
+  403: "Forbidden",
+  404: "Not Found",
+  405: "Method Not Allowed",
+  406: "Not Acceptable",
+  407: "Proxy Authentication Required",
+  408: "Request Timeout",
+  409: "Conflict",
+  410: "Gone",
+  411: "Length Required",
+  412: "Precondition Failed",
+  413: "Payload Too Large",
+  414: "Request-URI Too Long",
+  415: "Unsupported Media Type",
+  416: "Requested Range Not Satisfiable",
+  417: "Expectation Failed",
+  418: "I'm a teapot",
+  421: "Misdirected Request",
+  422: "Unprocessable Entity",
+  423: "Locked",
+  424: "Failed Dependency",
+  426: "Upgrade Required",
+  428: "Precondition Required",
+  429: "Too Many Requests",
+  431: "Request Header Fields Too Large",
+  444: "Connection Closed Without Response",
+  451: "Unavailable For Legal Reasons",
+  499: "Client Closed Request",
+  500: "Internal Server Error",
+  501: "Not Implemented",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout",
+  505: "HTTP Version Not Supported",
+  506: "Variant Also Negotiates",
+  507: "Insufficient Storage",
+  508: "Loop Detected",
+  510: "Not Extended",
+  511: "Network Authentication Required",
+  599: "Network Connect Timeout Error"
+};
+
+// src/http/http.error.ts
+var HttpError = class _HttpError extends Error {
+  static {
+    __name(this, "HttpError");
+  }
+  statusCode;
+  /**
+  * Optional validation or error details to include in the response.
+  * Typically used for 400-level errors to provide field-specific error information.
+  */
+  details;
+  /**
+  * Optional HTTP headers to include in the error response.
+  * Useful for authentication errors (e.g., WWW-Authenticate header).
+  */
+  headers;
+  /**
+  * Optional underlying error that caused this HTTP error.
+  * Follows the Error.cause pattern for error chaining.
+  */
+  cause;
+  /**
+  * Optional internal details that should not be exposed to clients.
+  * Useful for debugging and logging purposes.
+  */
+  internalDetails;
+  /**
+  * Creates a new HttpError instance.
+  *
+  * @param statusCode - The HTTP status code (must be a key from HttpStatusMap).
+  * @param message - Optional custom error message. If not provided, uses the default message from HttpStatusMap.
+  */
+  constructor(statusCode, message) {
+    super(message ?? HttpStatusMap[statusCode]), this.statusCode = statusCode;
+    this[Symbol.toStringTag] = "Object";
+    Object.setPrototypeOf(this, _HttpError.prototype);
+  }
+  /**
+  * Adds error details to the HTTP error and returns the instance for method chaining.
+  *
+  * @param errors - Object containing field-specific error information.
+  * @returns The HttpError instance for method chaining.
+  *
+  * @example
+  * ```ts
+  * error.withErrors({ email: 'Invalid email format', password: 'Too short' });
+  * ```
+  */
+  withErrors(errors) {
+    this.details = errors;
+    return this;
+  }
+  /**
+  * Adds HTTP headers to the error response and returns the instance for method chaining.
+  *
+  * @param headers - Object containing HTTP header key-value pairs.
+  * @returns The HttpError instance for method chaining.
+  *
+  * @example
+  * ```ts
+  * error.withHeaders({ 'WWW-Authenticate': 'Bearer realm="api"' });
+  * ```
+  */
+  withHeaders(headers) {
+    this.headers = headers;
+    return this;
+  }
+  /**
+  * Sets the underlying cause of this error and returns the instance for method chaining.
+  *
+  * @param cause - The original error that caused this HTTP error.
+  * @returns The HttpError instance for method chaining.
+  *
+  * @example
+  * ```ts
+  * error.withCause(new Error('Database connection failed'));
+  * ```
+  */
+  withCause(cause) {
+    this.cause = cause;
+    return this;
+  }
+  /**
+  * Adds internal details that should not be exposed to clients and returns the instance for method chaining.
+  *
+  * @param internalDetails - Object containing internal debugging information.
+  * @returns The HttpError instance for method chaining.
+  *
+  * @example
+  * ```ts
+  * error.withInternalDetails({ userId: 123, requestId: 'abc-123' });
+  * ```
+  */
+  withInternalDetails(internalDetails) {
+    this.internalDetails = internalDetails;
+    return this;
+  }
+  /**
+  * Adds a HTTP header to the error response and returns the instance for method chaining.
+  *
+  * @param key - The HTTP header key.
+  * @param value - The HTTP header value.
+  * @returns The HttpError instance for method chaining.
+  */
+  addHeader(key, value) {
+    this.headers ??= {};
+    this.headers[key] = value;
+    return this;
+  }
+};
+var IsHttpError = /* @__PURE__ */ __name((error) => {
+  return error instanceof HttpError;
+}, "IsHttpError");
+var httpError = /* @__PURE__ */ __name((statusCode, message) => new HttpError(statusCode, message), "httpError");
+var unauthorizedError = /* @__PURE__ */ __name((error) => httpError(401).addHeader("WWW-Authenticate", error), "unauthorizedError");
+
+// src/on.error.decorator.ts
+var generateDescriptor = /* @__PURE__ */ __name((descriptor, handler) => {
+  if (!descriptor.value) {
+    const getter = descriptor.get;
+    const setter = descriptor.set;
+    if (getter) {
+      descriptor.get = () => {
+        try {
+          return getter.apply(void 0);
+        } catch (error) {
+          handler(error);
+        }
+      };
+    }
+    if (setter) {
+      descriptor.set = (v) => {
+        try {
+          return setter.apply(void 0, [
+            v
+          ]);
+        } catch (error) {
+          handler(error);
+        }
+      };
+    }
+    return descriptor;
+  }
+  const method = descriptor.value;
+  descriptor.value = function(...args) {
+    try {
+      const result = method.apply(this, args);
+      if (result && result instanceof Promise) {
+        return result.catch((error) => {
+          handler(error);
+        });
+      }
+      return result;
+    } catch (error) {
+      handler(error);
+    }
+  };
+  return descriptor;
+}, "generateDescriptor");
+var OnError = /* @__PURE__ */ __name((handler) => {
+  return (target) => {
+    for (const propertyName of Reflect.ownKeys(target.prototype).filter((prop) => prop !== "constructor")) {
+      const desc = Object.getOwnPropertyDescriptor(target.prototype, propertyName);
+      if (desc) {
+        const isMethod = desc.value instanceof Function || desc.get instanceof Function || desc.set instanceof Function;
+        if (isMethod) {
+          Object.defineProperty(target.prototype, propertyName, generateDescriptor(desc, handler));
+        }
+      }
+    }
+    return target;
+  };
+}, "OnError");
+
+// src/postgres/postgres.error.handler.ts
+var isPostgresError = /* @__PURE__ */ __name((error) => {
+  return "code" in error;
+}, "isPostgresError");
+var PostgresErrorHandler = /* @__PURE__ */ __name((error) => {
+  if (isPostgresError(error)) {
+    switch (error.code) {
+      case "23505":
+        throw httpError(409).withCause(error);
+      case "23503":
+        throw httpError(404).withCause(error);
+      case "23502":
+      case "22P02":
+      case "22003":
+      case "23514":
+        throw httpError(400).withCause(error);
+      case "40000":
+      case "40001":
+      case "40002":
+        throw httpError(500).withCause(error).withInternalDetails({
+          msg: "Transaction rollback"
+        });
+      case "40P01":
+        throw httpError(500).withCause(error).withInternalDetails({
+          msg: "Deadlock"
+        });
+      default:
+        throw httpError(500).withCause(error);
+    }
+  } else {
+    throw error;
+  }
+}, "PostgresErrorHandler");
+
+// src/postgres/postgres.error.decorator.ts
+var OnPostgresError = /* @__PURE__ */ __name(() => OnError(PostgresErrorHandler), "OnPostgresError");
+export {
+  HttpError,
+  IsHttpError,
+  OnError,
+  OnPostgresError,
+  PostgresErrorHandler,
+  httpError,
+  unauthorizedError
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/http/http.status.map.ts","../src/http/http.error.ts","../src/on.error.decorator.ts","../src/postgres/postgres.error.handler.ts","../src/postgres/postgres.error.decorator.ts"],"sourcesContent":["/**\n * Map of HTTP status codes to their default status messages.\n * Includes both client error (4xx) and server error (5xx) status codes.\n *\n * @example\n * ```ts\n * HttpStatusMap[404] // 'Not Found'\n * HttpStatusMap[500] // 'Internal Server Error'\n * ```\n */\nexport const HttpStatusMap = {\n  400: 'Bad Request',\n  401: 'Unauthorized',\n  402: 'Payment Required',\n  403: 'Forbidden',\n  404: 'Not Found',\n  405: 'Method Not Allowed',\n  406: 'Not Acceptable',\n  407: 'Proxy Authentication Required',\n  408: 'Request Timeout',\n  409: 'Conflict',\n  410: 'Gone',\n  411: 'Length Required',\n  412: 'Precondition Failed',\n  413: 'Payload Too Large',\n  414: 'Request-URI Too Long',\n  415: 'Unsupported Media Type',\n  416: 'Requested Range Not Satisfiable',\n  417: 'Expectation Failed',\n  418: \"I'm a teapot\",\n  421: 'Misdirected Request',\n  422: 'Unprocessable Entity',\n  423: 'Locked',\n  424: 'Failed Dependency',\n  426: 'Upgrade Required',\n  428: 'Precondition Required',\n  429: 'Too Many Requests',\n  431: 'Request Header Fields Too Large',\n  444: 'Connection Closed Without Response',\n  451: 'Unavailable For Legal Reasons',\n  499: 'Client Closed Request',\n  500: 'Internal Server Error',\n  501: 'Not Implemented',\n  502: 'Bad Gateway',\n  503: 'Service Unavailable',\n  504: 'Gateway Timeout',\n  505: 'HTTP Version Not Supported',\n  506: 'Variant Also Negotiates',\n  507: 'Insufficient Storage',\n  508: 'Loop Detected',\n  510: 'Not Extended',\n  511: 'Network Authentication Required',\n  599: 'Network Connect Timeout Error',\n} as const;\n","import { HttpStatusMap } from './http.status.map.js';\n\n/**\n * Type representing valid HTTP status codes from the HttpStatusMap.\n */\nexport type HttpStatusCodes = keyof typeof HttpStatusMap;\n\n/**\n * Type representing the status message for a given HTTP status code.\n * @template T - The HTTP status code type.\n */\nexport type HttpStatusMessage<T extends HttpStatusCodes> = (typeof HttpStatusMap)[T];\n\n/**\n * Custom error class for HTTP errors with support for status codes, details, headers, and error chaining.\n * Extends the native Error class and provides a fluent API for building error responses.\n *\n * @example\n * ```ts\n * throw new HttpError(404).withErrors({ field: 'not found' });\n * ```\n *\n * @example\n * ```ts\n * throw new HttpError(401)\n *   .withHeaders({ 'WWW-Authenticate': 'Bearer' })\n *   .withCause(originalError);\n * ```\n */\nexport class HttpError extends Error {\n  /**\n   * Optional validation or error details to include in the response.\n   * Typically used for 400-level errors to provide field-specific error information.\n   */\n  details?: Record<string, unknown>;\n\n  /**\n   * Optional HTTP headers to include in the error response.\n   * Useful for authentication errors (e.g., WWW-Authenticate header).\n   */\n  headers?: Record<string, string>;\n\n  /**\n   * Optional underlying error that caused this HTTP error.\n   * Follows the Error.cause pattern for error chaining.\n   */\n  cause?: Error;\n\n  /**\n   * Optional internal details that should not be exposed to clients.\n   * Useful for debugging and logging purposes.\n   */\n  internalDetails?: Record<string, unknown>;\n\n  /**\n   * Creates a new HttpError instance.\n   *\n   * @param statusCode - The HTTP status code (must be a key from HttpStatusMap).\n   * @param message - Optional custom error message. If not provided, uses the default message from HttpStatusMap.\n   */\n  constructor(\n    readonly statusCode: HttpStatusCodes,\n    message?: HttpStatusMessage<HttpStatusCodes>,\n  ) {\n    super(message ?? HttpStatusMap[statusCode]);\n\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    (this as any)[Symbol.toStringTag] = 'Object';\n\n    // 👇️ because we are extending a built-in class\n    Object.setPrototypeOf(this, HttpError.prototype);\n  }\n\n  /**\n   * Adds error details to the HTTP error and returns the instance for method chaining.\n   *\n   * @param errors - Object containing field-specific error information.\n   * @returns The HttpError instance for method chaining.\n   *\n   * @example\n   * ```ts\n   * error.withErrors({ email: 'Invalid email format', password: 'Too short' });\n   * ```\n   */\n  withErrors(errors: Record<string, unknown>): HttpError {\n    this.details = errors;\n    return this;\n  }\n\n  /**\n   * Adds HTTP headers to the error response and returns the instance for method chaining.\n   *\n   * @param headers - Object containing HTTP header key-value pairs.\n   * @returns The HttpError instance for method chaining.\n   *\n   * @example\n   * ```ts\n   * error.withHeaders({ 'WWW-Authenticate': 'Bearer realm=\"api\"' });\n   * ```\n   */\n  withHeaders(headers: Record<string, string>): HttpError {\n    this.headers = headers;\n    return this;\n  }\n\n  /**\n   * Sets the underlying cause of this error and returns the instance for method chaining.\n   *\n   * @param cause - The original error that caused this HTTP error.\n   * @returns The HttpError instance for method chaining.\n   *\n   * @example\n   * ```ts\n   * error.withCause(new Error('Database connection failed'));\n   * ```\n   */\n  withCause(cause: Error): HttpError {\n    this.cause = cause;\n    return this;\n  }\n\n  /**\n   * Adds internal details that should not be exposed to clients and returns the instance for method chaining.\n   *\n   * @param internalDetails - Object containing internal debugging information.\n   * @returns The HttpError instance for method chaining.\n   *\n   * @example\n   * ```ts\n   * error.withInternalDetails({ userId: 123, requestId: 'abc-123' });\n   * ```\n   */\n  withInternalDetails(internalDetails: Record<string, unknown>): HttpError {\n    this.internalDetails = internalDetails;\n    return this;\n  }\n\n  /**\n   * Adds a HTTP header to the error response and returns the instance for method chaining.\n   *\n   * @param key - The HTTP header key.\n   * @param value - The HTTP header value.\n   * @returns The HttpError instance for method chaining.\n   */\n  addHeader(key: string, value: string): HttpError {\n    this.headers ??= {};\n    this.headers[key] = value;\n    return this;\n  }\n}\n\n/**\n * Type guard to check if an unknown value is an HttpError instance.\n *\n * @param error - The value to check.\n * @returns True if the value is an HttpError instance, false otherwise.\n *\n * @example\n * ```ts\n * if (IsHttpError(error)) {\n *   console.log(error.statusCode);\n * }\n * ```\n */\nexport const IsHttpError = (error: unknown): error is HttpError => {\n  return error instanceof HttpError;\n};\n\n/**\n * Factory function to create an HttpError instance with a specific status code.\n *\n * @template StatusCode - The HTTP status code type.\n * @template StatusMessage - The status message type for the given status code.\n * @param statusCode - The HTTP status code.\n * @param message - Optional custom error message.\n * @returns A new HttpError instance.\n *\n * @example\n * ```ts\n * throw httpError(404);\n * ```\n */\nexport const httpError = <StatusCode extends HttpStatusCodes, StatusMessage extends HttpStatusMessage<StatusCode>>(\n  statusCode: StatusCode,\n  message?: StatusMessage,\n) => new HttpError(statusCode, message);\n\n/**\n * Factory function to create an unauthorized HttpError instance.\n *\n * @param error - The error message of the WWW-Authenticate header.\n * @returns A new HttpError instance with the WWW-Authenticate header set to the given error message.\n *\n * @example\n * ```ts\n * throw unauthorizedError('Bearer realm=\"api\"');\n * ```\n */\nexport const unauthorizedError = (error: string) => httpError(401).addHeader('WWW-Authenticate', error);\n","/* eslint-disable @typescript-eslint/no-unsafe-function-type */\n\n/**\n * Type definition for an error handler function.\n * Called when an error is caught in a decorated method, getter, or setter.\n */\ntype ErrorHandler = (error: Error) => void;\n\n/**\n * Generates a property descriptor that wraps the original method/getter/setter with error handling.\n * For methods, handles both synchronous and asynchronous errors.\n * For getters/setters, wraps the accessor with try-catch.\n *\n * @param descriptor - The original property descriptor to wrap.\n * @param handler - The error handler function to call when an error occurs.\n * @returns A new property descriptor with error handling.\n */\nconst generateDescriptor = (descriptor: PropertyDescriptor, handler: ErrorHandler): PropertyDescriptor => {\n  if (!descriptor.value) {\n    const getter = descriptor.get;\n    const setter = descriptor.set;\n\n    if (getter) {\n      descriptor.get = () => {\n        try {\n          return getter.apply(this);\n        } catch (error) {\n          handler(error as Error);\n        }\n      };\n    }\n\n    if (setter) {\n      descriptor.set = (v: unknown) => {\n        try {\n          return setter.apply(this, [v]);\n        } catch (error) {\n          handler(error as Error);\n        }\n      };\n    }\n\n    return descriptor;\n  }\n\n  const method = descriptor.value;\n\n  descriptor.value = function (...args: unknown[]) {\n    try {\n      const result = method.apply(this, args);\n\n      if (result && result instanceof Promise) {\n        return result.catch((error: unknown) => {\n          handler(error as Error);\n        });\n      }\n\n      return result;\n    } catch (error) {\n      handler(error as Error);\n    }\n  };\n\n  return descriptor;\n};\n\n/**\n * Class decorator that automatically wraps all methods, getters, and setters in a class\n * with error handling. When any decorated method throws an error (synchronously or asynchronously),\n * the provided error handler is called.\n *\n * The decorator:\n * - Wraps all methods (including async methods) with try-catch\n * - Wraps getters and setters with try-catch\n * - Does not wrap the constructor\n * - Does not wrap non-method properties\n *\n * @param handler - The error handler function to call when an error is caught.\n * @returns A class decorator function.\n *\n * @example\n * ```ts\n * @OnError((error) => {\n *   console.error('Error caught:', error);\n *   throw new HttpError(500).withCause(error);\n * })\n * class MyService {\n *   async doSomething() {\n *     throw new Error('Something went wrong');\n *   }\n * }\n * ```\n *\n * @example\n * ```ts\n * @OnError(PostgresErrorHandler)\n * class UserRepository {\n *   async findById(id: number) {\n *     // If this throws a PostgresError, it will be handled\n *     return await db.select().from('users').where('id', id);\n *   }\n * }\n * ```\n */\nexport const OnError = (handler: ErrorHandler): ClassDecorator => {\n  return <TFunction extends Function>(target: TFunction): TFunction => {\n    for (const propertyName of Reflect.ownKeys(target.prototype).filter(prop => prop !== 'constructor')) {\n      const desc = Object.getOwnPropertyDescriptor(target.prototype, propertyName);\n      if (desc) {\n        const isMethod = desc.value instanceof Function || desc.get instanceof Function || desc.set instanceof Function;\n        if (isMethod) {\n          Object.defineProperty(target.prototype, propertyName, generateDescriptor(desc, handler));\n        }\n      }\n    }\n    return target;\n  };\n};\n","import { httpError } from '../http/http.error.js';\n\n/**\n * Interface representing a PostgreSQL error with a specific error code.\n * PostgreSQL errors include a `code` property that identifies the type of error.\n */\nexport interface PostgresError extends Error {\n  /**\n   * PostgreSQL error code (e.g., '23505' for unique constraint violation).\n   */\n  code: string;\n}\n\n/**\n * Type guard to check if an error is a PostgreSQL error with a code property.\n *\n * @param error - The error to check.\n * @returns True if the error has a `code` property, false otherwise.\n *\n * @example\n * ```ts\n * if (isPostgresError(error)) {\n *   console.log(error.code); // '23505'\n * }\n * ```\n */\nexport const isPostgresError = (error: Error): error is PostgresError => {\n  return 'code' in error;\n};\n\n/**\n * Handles PostgreSQL errors by converting them to appropriate HTTP errors.\n * Maps PostgreSQL error codes to HTTP status codes:\n * - 23505 (unique constraint violation) → 409 Conflict\n * - 23503 (foreign key violation) → 404 Not Found\n * - 23502, 22P02, 22003, 23514 (validation errors) → 400 Bad Request\n * - 40000, 40001, 40002 (transaction rollback) → 500 Internal Server Error\n * - 40P01 (deadlock) → 500 Internal Server Error\n * - Unknown codes → 500 Internal Server Error\n *\n * If the error is not a PostgreSQL error, it is re-thrown as-is.\n *\n * @param error - The error to handle.\n * @throws {HttpError} An HttpError with the appropriate status code and cause.\n * @throws {Error} The original error if it's not a PostgreSQL error.\n *\n * @example\n * ```ts\n * try {\n *   await db.insert(...);\n * } catch (error) {\n *   PostgresErrorHandler(error); // Converts to HttpError\n * }\n * ```\n */\nexport const PostgresErrorHandler = (error: Error) => {\n  if (isPostgresError(error)) {\n    switch (error.code) {\n      case '23505':\n        throw httpError(409).withCause(error);\n      case '23503':\n        throw httpError(404).withCause(error);\n      case '23502':\n      case '22P02':\n      case '22003':\n      case '23514':\n        throw httpError(400).withCause(error);\n      case '40000':\n      case '40001':\n      case '40002':\n        throw httpError(500).withCause(error).withInternalDetails({ msg: 'Transaction rollback' });\n      case '40P01':\n        throw httpError(500).withCause(error).withInternalDetails({ msg: 'Deadlock' });\n      default:\n        throw httpError(500).withCause(error);\n    }\n  } else {\n    throw error;\n  }\n};\n","import { PostgresErrorHandler } from './postgres.error.handler.js';\nimport { OnError } from '../on.error.decorator.js';\n\nexport const OnPostgresError = () => OnError(PostgresErrorHandler);\n"],"mappings":";;;;AAUO,IAAMA,gBAAgB;EAC3B,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;AACP;;;ACxBO,IAAMC,YAAN,MAAMA,mBAAkBC,MAAAA;EA7B/B,OA6B+BA;;;;;;;;EAK7BC;;;;;EAMAC;;;;;EAMAC;;;;;EAMAC;;;;;;;EAQA,YACWC,YACTC,SACA;AACA,UAAMA,WAAWC,cAAcF,UAAAA,CAAW,GAAA,KAHjCA,aAAAA;AAMR,SAAaG,OAAOC,WAAW,IAAI;AAGpCC,WAAOC,eAAe,MAAMZ,WAAUa,SAAS;EACjD;;;;;;;;;;;;EAaAC,WAAWC,QAA4C;AACrD,SAAKb,UAAUa;AACf,WAAO;EACT;;;;;;;;;;;;EAaAC,YAAYb,SAA4C;AACtD,SAAKA,UAAUA;AACf,WAAO;EACT;;;;;;;;;;;;EAaAc,UAAUb,OAAyB;AACjC,SAAKA,QAAQA;AACb,WAAO;EACT;;;;;;;;;;;;EAaAc,oBAAoBb,iBAAqD;AACvE,SAAKA,kBAAkBA;AACvB,WAAO;EACT;;;;;;;;EASAc,UAAUC,KAAaC,OAA0B;AAC/C,SAAKlB,YAAY,CAAC;AAClB,SAAKA,QAAQiB,GAAAA,IAAOC;AACpB,WAAO;EACT;AACF;AAeO,IAAMC,cAAc,wBAACC,UAAAA;AAC1B,SAAOA,iBAAiBvB;AAC1B,GAF2B;AAkBpB,IAAMwB,YAAY,wBACvBlB,YACAC,YACG,IAAIP,UAAUM,YAAYC,OAAAA,GAHN;AAgBlB,IAAMkB,oBAAoB,wBAACF,UAAkBC,UAAU,GAAA,EAAKL,UAAU,oBAAoBI,KAAAA,GAAhE;;;ACrLjC,IAAMG,qBAAqB,wBAACC,YAAgCC,YAAAA;AAC1D,MAAI,CAACD,WAAWE,OAAO;AACrB,UAAMC,SAASH,WAAWI;AAC1B,UAAMC,SAASL,WAAWM;AAE1B,QAAIH,QAAQ;AACVH,iBAAWI,MAAM,MAAA;AACf,YAAI;AACF,iBAAOD,OAAOI,MAAM,MAAI;QAC1B,SAASC,OAAO;AACdP,kBAAQO,KAAAA;QACV;MACF;IACF;AAEA,QAAIH,QAAQ;AACVL,iBAAWM,MAAM,CAACG,MAAAA;AAChB,YAAI;AACF,iBAAOJ,OAAOE,MAAM,QAAM;YAACE;WAAE;QAC/B,SAASD,OAAO;AACdP,kBAAQO,KAAAA;QACV;MACF;IACF;AAEA,WAAOR;EACT;AAEA,QAAMU,SAASV,WAAWE;AAE1BF,aAAWE,QAAQ,YAAaS,MAAe;AAC7C,QAAI;AACF,YAAMC,SAASF,OAAOH,MAAM,MAAMI,IAAAA;AAElC,UAAIC,UAAUA,kBAAkBC,SAAS;AACvC,eAAOD,OAAOE,MAAM,CAACN,UAAAA;AACnBP,kBAAQO,KAAAA;QACV,CAAA;MACF;AAEA,aAAOI;IACT,SAASJ,OAAO;AACdP,cAAQO,KAAAA;IACV;EACF;AAEA,SAAOR;AACT,GA/C2B;AAuFpB,IAAMe,UAAU,wBAACd,YAAAA;AACtB,SAAO,CAA6Be,WAAAA;AAClC,eAAWC,gBAAgBC,QAAQC,QAAQH,OAAOI,SAAS,EAAEC,OAAOC,CAAAA,SAAQA,SAAS,aAAA,GAAgB;AACnG,YAAMC,OAAOC,OAAOC,yBAAyBT,OAAOI,WAAWH,YAAAA;AAC/D,UAAIM,MAAM;AACR,cAAMG,WAAWH,KAAKrB,iBAAiByB,YAAYJ,KAAKnB,eAAeuB,YAAYJ,KAAKjB,eAAeqB;AACvG,YAAID,UAAU;AACZF,iBAAOI,eAAeZ,OAAOI,WAAWH,cAAclB,mBAAmBwB,MAAMtB,OAAAA,CAAAA;QACjF;MACF;IACF;AACA,WAAOe;EACT;AACF,GAbuB;;;AC9EhB,IAAMa,kBAAkB,wBAACC,UAAAA;AAC9B,SAAO,UAAUA;AACnB,GAF+B;AA6BxB,IAAMC,uBAAuB,wBAACD,UAAAA;AACnC,MAAID,gBAAgBC,KAAAA,GAAQ;AAC1B,YAAQA,MAAME,MAAI;MAChB,KAAK;AACH,cAAMC,UAAU,GAAA,EAAKC,UAAUJ,KAAAA;MACjC,KAAK;AACH,cAAMG,UAAU,GAAA,EAAKC,UAAUJ,KAAAA;MACjC,KAAK;MACL,KAAK;MACL,KAAK;MACL,KAAK;AACH,cAAMG,UAAU,GAAA,EAAKC,UAAUJ,KAAAA;MACjC,KAAK;MACL,KAAK;MACL,KAAK;AACH,cAAMG,UAAU,GAAA,EAAKC,UAAUJ,KAAAA,EAAOK,oBAAoB;UAAEC,KAAK;QAAuB,CAAA;MAC1F,KAAK;AACH,cAAMH,UAAU,GAAA,EAAKC,UAAUJ,KAAAA,EAAOK,oBAAoB;UAAEC,KAAK;QAAW,CAAA;MAC9E;AACE,cAAMH,UAAU,GAAA,EAAKC,UAAUJ,KAAAA;IACnC;EACF,OAAO;AACL,UAAMA;EACR;AACF,GAxBoC;;;ACpD7B,IAAMO,kBAAkB,6BAAMC,QAAQC,oBAAAA,GAAd;","names":["HttpStatusMap","HttpError","Error","details","headers","cause","internalDetails","statusCode","message","HttpStatusMap","Symbol","toStringTag","Object","setPrototypeOf","prototype","withErrors","errors","withHeaders","withCause","withInternalDetails","addHeader","key","value","IsHttpError","error","httpError","unauthorizedError","generateDescriptor","descriptor","handler","value","getter","get","setter","set","apply","error","v","method","args","result","Promise","catch","OnError","target","propertyName","Reflect","ownKeys","prototype","filter","prop","desc","Object","getOwnPropertyDescriptor","isMethod","Function","defineProperty","isPostgresError","error","PostgresErrorHandler","code","httpError","withCause","withInternalDetails","msg","OnPostgresError","OnError","PostgresErrorHandler"]}

package/dist/on.error.decorator.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Type definition for an error handler function.
+ * Called when an error is caught in a decorated method, getter, or setter.
+ */
+type ErrorHandler = (error: Error) => void;
+/**
+ * Class decorator that automatically wraps all methods, getters, and setters in a class
+ * with error handling. When any decorated method throws an error (synchronously or asynchronously),
+ * the provided error handler is called.
+ *
+ * The decorator:
+ * - Wraps all methods (including async methods) with try-catch
+ * - Wraps getters and setters with try-catch
+ * - Does not wrap the constructor
+ * - Does not wrap non-method properties
+ *
+ * @param handler - The error handler function to call when an error is caught.
+ * @returns A class decorator function.
+ *
+ * @example
+ * ```ts
+ * @OnError((error) => {
+ *   console.error('Error caught:', error);
+ *   throw new HttpError(500).withCause(error);
+ * })
+ * class MyService {
+ *   async doSomething() {
+ *     throw new Error('Something went wrong');
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * @OnError(PostgresErrorHandler)
+ * class UserRepository {
+ *   async findById(id: number) {
+ *     // If this throws a PostgresError, it will be handled
+ *     return await db.select().from('users').where('id', id);
+ *   }
+ * }
+ * ```
+ */
+export declare const OnError: (handler: ErrorHandler) => ClassDecorator;
+export {};
+//# sourceMappingURL=on.error.decorator.d.ts.map

package/dist/on.error.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"on.error.decorator.d.ts","sourceRoot":"","sources":["../src/on.error.decorator.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,KAAK,YAAY,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;AA4D3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,OAAO,GAAI,SAAS,YAAY,KAAG,cAa/C,CAAC"}

package/dist/postgres/postgres.error.decorator.d.ts

@@ -0,0 +1,2 @@
+export declare const OnPostgresError: () => ClassDecorator;
+//# sourceMappingURL=postgres.error.decorator.d.ts.map

package/dist/postgres/postgres.error.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.error.decorator.d.ts","sourceRoot":"","sources":["../../src/postgres/postgres.error.decorator.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,eAAe,sBAAsC,CAAC"}

package/dist/postgres/postgres.error.handler.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Interface representing a PostgreSQL error with a specific error code.
+ * PostgreSQL errors include a `code` property that identifies the type of error.
+ */
+export interface PostgresError extends Error {
+    /**
+     * PostgreSQL error code (e.g., '23505' for unique constraint violation).
+     */
+    code: string;
+}
+/**
+ * Type guard to check if an error is a PostgreSQL error with a code property.
+ *
+ * @param error - The error to check.
+ * @returns True if the error has a `code` property, false otherwise.
+ *
+ * @example
+ * ```ts
+ * if (isPostgresError(error)) {
+ *   console.log(error.code); // '23505'
+ * }
+ * ```
+ */
+export declare const isPostgresError: (error: Error) => error is PostgresError;
+/**
+ * Handles PostgreSQL errors by converting them to appropriate HTTP errors.
+ * Maps PostgreSQL error codes to HTTP status codes:
+ * - 23505 (unique constraint violation) → 409 Conflict
+ * - 23503 (foreign key violation) → 404 Not Found
+ * - 23502, 22P02, 22003, 23514 (validation errors) → 400 Bad Request
+ * - 40000, 40001, 40002 (transaction rollback) → 500 Internal Server Error
+ * - 40P01 (deadlock) → 500 Internal Server Error
+ * - Unknown codes → 500 Internal Server Error
+ *
+ * If the error is not a PostgreSQL error, it is re-thrown as-is.
+ *
+ * @param error - The error to handle.
+ * @throws {HttpError} An HttpError with the appropriate status code and cause.
+ * @throws {Error} The original error if it's not a PostgreSQL error.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await db.insert(...);
+ * } catch (error) {
+ *   PostgresErrorHandler(error); // Converts to HttpError
+ * }
+ * ```
+ */
+export declare const PostgresErrorHandler: (error: Error) => never;
+//# sourceMappingURL=postgres.error.handler.d.ts.map

package/dist/postgres/postgres.error.handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.error.handler.d.ts","sourceRoot":"","sources":["../../src/postgres/postgres.error.handler.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,WAAW,aAAc,SAAQ,KAAK;IAC1C;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,KAAK,KAAG,KAAK,IAAI,aAEvD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,KAAK,UAwBhD,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@maroonedsoftware/errors",
+  "version": "1.0.0",
+  "description": "A comprehensive error handling library for HTTP APIs with built-in support for PostgreSQL error mapping and class-level error decorators.",
+  "author": {
+    "name": "Marooned Software",
+    "url": "https://github.com/MaroonedSoftware/serverkit"
+  },
+  "bugs": {
+    "url": "https://github.com/MaroonedSoftware/serverkit/issues"
+  },
+  "homepage": "https://github.com/MaroonedSoftware/serverkit/packages/errors#readme",
+  "keywords": [
+    "backend",
+    "errors",
+    "http",
+    "postgresql",
+    "serverkit",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MaroonedSoftware/serverkit.git"
+  },
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "license": "MIT",
+  "files": [
+    "dist/**"
+  ],
+  "devDependencies": {
+    "@repo/config-eslint": "0.0.0",
+    "@repo/config-typescript": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --sourcemap --dts && tsc --emitDeclarationOnly --declaration",
+    "build:ci": "eslint --max-warnings=0 && pnpm run build",
+    "lint": "eslint --fix",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:ci": "vitest run --coverage"
+  }
+}