@setu-ts/exceptions 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Setu-TS Contributors
+
+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

@@ -1,3 +1,181 @@
-# Temporary Holding Version
+# @setu-ts/exceptions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Exception hierarchy, factory functions, error formatters, and the global error-handler middleware.
+
+This is a **plain package, not a plugin** — it depends on `@setu-ts/common` only and registers no
+capability. You wire the middleware into the application pipeline yourself.
+
+## Installation
+
+```typescript
+import { errorHandler, notFound } from '@setu-ts/exceptions';
+```
+
+## Usage
+
+```typescript
+import { badRequest, errorHandler, HttpError, notFound } from '@setu-ts/exceptions';
+
+app.middleware.add(errorHandler({ format: 'rfc9457' }), {
+  priority: 0,
+  name: 'error-handler',
+});
+
+app.router.get('/users/:id', async (ctx) => {
+  const user = await users.find(ctx.params.id);
+  if (!user) throw notFound('User not found');
+  return ctx.response.json(user);
+});
+```
+
+## Options
+
+`errorHandler(options?)` takes:
+
+| Option               | Type                                                                                                            | Default     | Description                                                                                                              |
+| -------------------- | --------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `format`             | `ErrorFormat \| ErrorHandlerFormatter`                                                                          | `'default'` | Body shape, or a formatter function.                                                                                     |
+| `includeStackTrace`  | `boolean`                                                                                                       | `false`     | Add the stack to the body. Development only.                                                                             |
+| `maskInternalErrors` | `boolean`                                                                                                       | `true`      | Replace unhandled non-`HttpError` 5xx diagnostics with their status title before serving the response.                   |
+| `logErrors`          | `boolean`                                                                                                       | `true`      | Report handled errors to the resolved `ILogger`.                                                                         |
+| `respond`            | `(error: HttpError, ctx: IRequestContext) => HandlerResult \| undefined \| Promise<HandlerResult \| undefined>` | —           | Write an application-owned caught-error response; return or resolve `undefined` to use the configured formatter instead. |
+
+`format` accepts `'default'`, `'rfc9457'`, the deprecated `'rfc7807'`, or a function. Passing a
+formatter directly is equivalent to naming it — both paths select the same
+`application/problem+json` content type for Problem Details bodies.
+
+`respond` is called after error normalization, masking, and status resolution. It can return or
+resolve an HTML (or another application-owned) result through `ctx.response`; the callback owns that
+result's status, headers, and body. The log retains the unmasked diagnostic and records the status
+that result serves. It applies only to errors caught by `errorHandler`, not responder-based
+terminals such as an unmatched-path `404`.
+
+The natural spelling of the hook omits the one statement that matters and serves `200` for every
+branded error: `renderView(ctx, Component, props)` takes no status, and nothing else sets it. The
+callback owns the status, so the example carries that line on its own:
+
+```tsx
+import { errorHandler, statusTitle } from '@setu-ts/exceptions';
+import type { HandlerResult, IRequestContext } from '@setu-ts/common';
+import { renderView } from '@setu-ts/view-plugin';
+
+interface ErrorPageProps {
+  readonly status: number;
+  readonly title: string;
+}
+
+const ErrorPage = (props: ErrorPageProps) => (
+  <main>
+    <h1>{props.status}</h1>
+    <p>{props.title}</p>
+  </main>
+);
+
+function wantsHtml(ctx: IRequestContext): boolean {
+  // Deliberately simple — the point here is that the callback owns the status,
+  // not content negotiation. This does NOT honour `q` values, so a client
+  // sending `text/html;q=0` (a refusal) still gets HTML; parse the media
+  // ranges if your callers send them.
+  return (ctx.request.headers.get('accept') ?? '').includes('text/html');
+}
+
+app.middleware.add(
+  errorHandler({
+    format: 'rfc9457',
+    async respond(error, ctx): Promise<HandlerResult | undefined> {
+      if (!wantsHtml(ctx)) return undefined; // API clients keep Problem Details
+      // The callback owns the result's status, and renderView takes none —
+      // without this line every branded error answers 200.
+      ctx.response.status(error.statusCode);
+      return await renderView(ctx, ErrorPage, {
+        status: error.statusCode,
+        title: statusTitle(error.statusCode),
+      });
+    },
+  }),
+  { priority: 0, name: 'error-handler' },
+);
+```
+
+What the hook does NOT cover is stated by the rule in
+[docs/mvc.md](https://github.com/setu-ts/setu-ts/blob/main/docs/mvc.md#error-pages): every responder
+terminal — an unmatched-path `404`, a guard's `401`, the rate limiter's `429` — is emitted outside
+`errorHandler`, so each keeps its formatter's JSON no matter what this callback renders.
+
+## What it exports
+
+- **`HttpError`** — the error type, carrying a status, a title, and optional validation details.
+- **Factories** — `badRequest`, `unauthorized`, `forbidden`, `notFound`, `conflict`,
+  `tooManyRequests`, `internalServerError`, `notImplemented`, `serviceUnavailable`,
+  `validationError`, plus `statusTitle` / `STATUS_TITLES`.
+- **Formatters** — `defaultFormatter` and `rfc9457Formatter` ([RFC 9457][rfc9457] Problem Details),
+  plus a deprecated `rfc7807Formatter`, selected by `selectFormatter`. A Problem Details body
+  carries `detail`, never `message`.
+- **Middleware** — `errorHandler(options)`.
+
+## Problem Details and `about:blank`
+
+The `'rfc9457'` format emits `type: "about:blank"` for any error whose only semantics are its status
+code — which is every factory in this package except `validationError()`. [RFC 9457][rfc9457] §4.2
+registers `about:blank` for exactly that case, because a URI minted from the status code identifies
+nothing the `status` member does not already carry. Read `status` to distinguish errors.
+
+`validationError()` is the exception: it defines an `errors` extension member, so it is a distinct
+problem type identified by `https://setu-ts.dev/errors/validation` — the same URI
+`@setu-ts/validation-plugin` uses.
+
+```json
+{
+  "type": "about:blank",
+  "title": "Not Found",
+  "status": 404,
+  "detail": "User 42 does not exist",
+  "instance": "/users/42"
+}
+```
+
+> **`'rfc7807'` is deprecated.** RFC 7807 was obsoleted by RFC 9457 in July 2023. The `'rfc7807'`
+> alias and `rfc7807Formatter` still emit the status-derived `type`
+> (`https://setu-ts.dev/errors/404`) they always did — a deprecated symbol must not silently change
+> behavior — so upgrading is a deliberate one-word edit. Removal is scheduled for v1.0.0.
+
+## Exports
+
+| Export                  | Kind      |
+| ----------------------- | --------- |
+| `badRequest`            | function  |
+| `conflict`              | function  |
+| `defaultFormatter`      | function  |
+| `errorHandler`          | function  |
+| `forbidden`             | function  |
+| `internalServerError`   | function  |
+| `notFound`              | function  |
+| `notImplemented`        | function  |
+| `rfc7807Formatter`      | function  |
+| `rfc9457Formatter`      | function  |
+| `selectFormatter`       | function  |
+| `serviceUnavailable`    | function  |
+| `statusTitle`           | function  |
+| `tooManyRequests`       | function  |
+| `unauthorized`          | function  |
+| `validationError`       | function  |
+| `HttpError`             | class     |
+| `ERROR_TYPE_BASE`       | const     |
+| `STATUS_TITLES`         | const     |
+| `DefaultErrorBody`      | interface |
+| `ErrorHandlerOptions`   | interface |
+| `HttpErrorInit`         | interface |
+| `ProblemDetails`        | interface |
+| `ValidationError`       | interface |
+| `ErrorFormat`           | type      |
+| `ErrorHandlerFormatter` | type      |
+
+Generated from the package barrel by `deno task docs:exports`; `deno task check:docs` fails when it
+drifts.
+
+## Full API
+
+Every export, its signature, and the exact response shapes are documented in
+[PUBLIC_API.md](https://github.com/setu-ts/setu-ts/blob/main/PUBLIC_API.md#api-reference-setu-tsexceptions).
+
+[rfc9457]: https://www.rfc-editor.org/rfc/rfc9457.html

package/dist/errors/exceptions.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Exception factory functions.
+ *
+ * Each factory returns a {@linkcode HttpError} with a fixed `statusCode`,
+ * embodying **composition over inheritance** (AI_GUIDELINES §1.4,
+ * ARCHITECTURE.md §13). Throw one in a route handler or service and the
+ * error-handler middleware will format and send it with the right status.
+ *
+ * @example
+ * ```typescript
+ * import { notFound, badRequest } from '@setu-ts/exceptions';
+ *
+ * function getUser(id: string) {
+ *   if (!id) throw badRequest('id is required');
+ *   const user = db.find(id);
+ *   if (!user) throw notFound(`User ${id} not found`);
+ *   return user;
+ * }
+ * ```
+ *
+ * @module
+ */
+import { HttpError } from './http-error.ts';
+import type { ValidationError } from './http-error.ts';
+/**
+ * A human-readable title for a given HTTP status code. This is the single
+ * source of truth used by both the factory functions and the Problem Details
+ * formatters so the `title` field never drifts from the produced `statusCode`.
+ *
+ * Keys are every status the framework itself produces — the ones the factories
+ * below return AND the ones first-party code brands onto an error with
+ * `withHttpStatusHint` from `@setu-ts/common`, which reaches this table through
+ * the responder seam without passing a factory (`413` from the request-size and
+ * body-cap refusals, `415` from the form accessor, `501`/`503`/`504` from the
+ * database, secrets and resilience refusals). A branded status with no row here
+ * is served the generic `'Error'` title, so `test/status-title-coverage.test.ts`
+ * enumerates the branded statuses from source and fails when one is missing —
+ * `415` reached a client as `"title": "Error"` under `'rfc9457'` while the same
+ * error read `"message": "Unsupported Media Type"` under `'default'`, because
+ * every test asserted the brand on the error object and none read the served
+ * body.
+ *
+ * @since 0.1.0
+ */
+export declare const STATUS_TITLES: Readonly<Record<number, string>>;
+/**
+ * Resolves the human-readable title for a status code, falling back to a
+ * generic title for codes outside the well-known set.
+ *
+ * @param statusCode - The HTTP status code
+ * @returns A human-readable title
+ * @since 0.1.0
+ */
+export declare function statusTitle(statusCode: number): string;
+/**
+ * Creates a `400 Bad Request` error.
+ *
+ * @param message - Human-readable error message
+ * @param details - Optional structured details appended to the error body
+ * @returns A `400` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export declare function badRequest(message: string, details?: Readonly<Record<string, unknown>>): HttpError;
+/**
+ * Creates a `401 Unauthorized` error.
+ *
+ * @param message - Human-readable error message
+ * @returns A `401` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export declare function unauthorized(message: string): HttpError;
+/**
+ * Creates a `403 Forbidden` error.
+ *
+ * @param message - Human-readable error message
+ * @returns A `403` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export declare function forbidden(message: string): HttpError;
+/**
+ * Creates a `404 Not Found` error.
+ *
+ * @param message - Human-readable error message
+ * @returns A `404` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export declare function notFound(message: string): HttpError;
+/**
+ * Creates a `409 Conflict` error.
+ *
+ * @param message - Human-readable error message
+ * @returns A `409` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export declare function conflict(message: string): HttpError;
+/**
+ * Creates a `422 Unprocessable Entity` error wrapping a list of validation
+ * failures.
+ *
+ * The `errors` array is stored in the error's `details.errors` so it survives
+ * serialization into both the default and RFC 7807 error bodies.
+ *
+ * @param errors - The validation failures that caused this error
+ * @param message - Optional custom message (defaults to a count-based summary)
+ * @returns A `422` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export declare function validationError(errors: readonly ValidationError[], message?: string): HttpError;
+/**
+ * Creates a `429 Too Many Requests` error.
+ *
+ * @param message - Human-readable error message
+ * @param details - Optional structured details (e.g. `retryAfter`)
+ * @returns A `429` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export declare function tooManyRequests(message: string, details?: Readonly<Record<string, unknown>>): HttpError;
+/**
+ * Creates a `500 Internal Server Error` error.
+ *
+ * Pass the original error as `cause` so the root cause is preserved in the
+ * ES2022 error chain for logging and debugging.
+ *
+ * @param message - Human-readable error message
+ * @param cause - Optional underlying error forwarded to the cause chain
+ * @returns A `500` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export declare function internalServerError(message: string, cause?: Error): HttpError;
+/**
+ * Creates a `501 Not Implemented` error.
+ *
+ * @param message - Human-readable error message
+ * @returns A `501` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export declare function notImplemented(message: string): HttpError;
+/**
+ * Creates a `503 Service Unavailable` error.
+ *
+ * @param message - Human-readable error message
+ * @returns A `503` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export declare function serviceUnavailable(message: string): HttpError;
+//# sourceMappingURL=exceptions.d.ts.map

package/dist/errors/exceptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.d.ts","sourceRoot":"","sources":["../../src/errors/exceptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAMvD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAe1D,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEtD;AAMD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC1C,SAAS,CAEX;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAEnD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAEnD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,OAAO,CAAC,EAAE,MAAM,GACf,SAAS,CAGX;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC1C,SAAS,CAEX;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAE7E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAEzD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAE7D"}

package/dist/errors/exceptions.js

@@ -0,0 +1,189 @@
+/**
+ * Exception factory functions.
+ *
+ * Each factory returns a {@linkcode HttpError} with a fixed `statusCode`,
+ * embodying **composition over inheritance** (AI_GUIDELINES §1.4,
+ * ARCHITECTURE.md §13). Throw one in a route handler or service and the
+ * error-handler middleware will format and send it with the right status.
+ *
+ * @example
+ * ```typescript
+ * import { notFound, badRequest } from '@setu-ts/exceptions';
+ *
+ * function getUser(id: string) {
+ *   if (!id) throw badRequest('id is required');
+ *   const user = db.find(id);
+ *   if (!user) throw notFound(`User ${id} not found`);
+ *   return user;
+ * }
+ * ```
+ *
+ * @module
+ */
+import { HttpError } from "./http-error.js";
+// ---------------------------------------------------------------------------
+// Status-code → human title (single source of truth, shared with formatters)
+// ---------------------------------------------------------------------------
+/**
+ * A human-readable title for a given HTTP status code. This is the single
+ * source of truth used by both the factory functions and the Problem Details
+ * formatters so the `title` field never drifts from the produced `statusCode`.
+ *
+ * Keys are every status the framework itself produces — the ones the factories
+ * below return AND the ones first-party code brands onto an error with
+ * `withHttpStatusHint` from `@setu-ts/common`, which reaches this table through
+ * the responder seam without passing a factory (`413` from the request-size and
+ * body-cap refusals, `415` from the form accessor, `501`/`503`/`504` from the
+ * database, secrets and resilience refusals). A branded status with no row here
+ * is served the generic `'Error'` title, so `test/status-title-coverage.test.ts`
+ * enumerates the branded statuses from source and fails when one is missing —
+ * `415` reached a client as `"title": "Error"` under `'rfc9457'` while the same
+ * error read `"message": "Unsupported Media Type"` under `'default'`, because
+ * every test asserted the brand on the error object and none read the served
+ * body.
+ *
+ * @since 0.1.0
+ */
+export const STATUS_TITLES = {
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    409: 'Conflict',
+    413: 'Payload Too Large',
+    415: 'Unsupported Media Type',
+    422: 'Unprocessable Entity',
+    429: 'Too Many Requests',
+    500: 'Internal Server Error',
+    501: 'Not Implemented',
+    502: 'Bad Gateway',
+    503: 'Service Unavailable',
+    504: 'Gateway Timeout',
+};
+/**
+ * Resolves the human-readable title for a status code, falling back to a
+ * generic title for codes outside the well-known set.
+ *
+ * @param statusCode - The HTTP status code
+ * @returns A human-readable title
+ * @since 0.1.0
+ */
+export function statusTitle(statusCode) {
+    return STATUS_TITLES[statusCode] ?? 'Error';
+}
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+/**
+ * Creates a `400 Bad Request` error.
+ *
+ * @param message - Human-readable error message
+ * @param details - Optional structured details appended to the error body
+ * @returns A `400` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export function badRequest(message, details) {
+    return new HttpError(400, message, details);
+}
+/**
+ * Creates a `401 Unauthorized` error.
+ *
+ * @param message - Human-readable error message
+ * @returns A `401` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export function unauthorized(message) {
+    return new HttpError(401, message);
+}
+/**
+ * Creates a `403 Forbidden` error.
+ *
+ * @param message - Human-readable error message
+ * @returns A `403` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export function forbidden(message) {
+    return new HttpError(403, message);
+}
+/**
+ * Creates a `404 Not Found` error.
+ *
+ * @param message - Human-readable error message
+ * @returns A `404` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export function notFound(message) {
+    return new HttpError(404, message);
+}
+/**
+ * Creates a `409 Conflict` error.
+ *
+ * @param message - Human-readable error message
+ * @returns A `409` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export function conflict(message) {
+    return new HttpError(409, message);
+}
+/**
+ * Creates a `422 Unprocessable Entity` error wrapping a list of validation
+ * failures.
+ *
+ * The `errors` array is stored in the error's `details.errors` so it survives
+ * serialization into both the default and RFC 7807 error bodies.
+ *
+ * @param errors - The validation failures that caused this error
+ * @param message - Optional custom message (defaults to a count-based summary)
+ * @returns A `422` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export function validationError(errors, message) {
+    const summary = message ?? `Validation failed with ${errors.length} error(s).`;
+    return new HttpError(422, summary, { errors });
+}
+/**
+ * Creates a `429 Too Many Requests` error.
+ *
+ * @param message - Human-readable error message
+ * @param details - Optional structured details (e.g. `retryAfter`)
+ * @returns A `429` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export function tooManyRequests(message, details) {
+    return new HttpError(429, message, details);
+}
+/**
+ * Creates a `500 Internal Server Error` error.
+ *
+ * Pass the original error as `cause` so the root cause is preserved in the
+ * ES2022 error chain for logging and debugging.
+ *
+ * @param message - Human-readable error message
+ * @param cause - Optional underlying error forwarded to the cause chain
+ * @returns A `500` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export function internalServerError(message, cause) {
+    return new HttpError(500, message, undefined, cause);
+}
+/**
+ * Creates a `501 Not Implemented` error.
+ *
+ * @param message - Human-readable error message
+ * @returns A `501` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export function notImplemented(message) {
+    return new HttpError(501, message);
+}
+/**
+ * Creates a `503 Service Unavailable` error.
+ *
+ * @param message - Human-readable error message
+ * @returns A `503` {@linkcode HttpError}
+ * @since 0.1.0
+ */
+export function serviceUnavailable(message) {
+    return new HttpError(503, message);
+}
+//# sourceMappingURL=exceptions.js.map

package/dist/errors/exceptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.js","sourceRoot":"","sources":["../../src/errors/exceptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,8EAA8E;AAC9E,6EAA6E;AAC7E,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAqC;IAC7D,GAAG,EAAE,aAAa;IAClB,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,UAAU;IACf,GAAG,EAAE,mBAAmB;IACxB,GAAG,EAAE,wBAAwB;IAC7B,GAAG,EAAE,sBAAsB;IAC3B,GAAG,EAAE,mBAAmB;IACxB,GAAG,EAAE,uBAAuB;IAC5B,GAAG,EAAE,iBAAiB;IACtB,GAAG,EAAE,aAAa;IAClB,GAAG,EAAE,qBAAqB;IAC1B,GAAG,EAAE,iBAAiB;CACvB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,UAAkB;IAC5C,OAAO,aAAa,CAAC,UAAU,CAAC,IAAI,OAAO,CAAC;AAC9C,CAAC;AAED,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CACxB,OAAe,EACf,OAA2C;IAE3C,OAAO,IAAI,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,IAAI,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO,IAAI,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAe;IACtC,OAAO,IAAI,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAe;IACtC,OAAO,IAAI,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAkC,EAClC,OAAgB;IAEhB,MAAM,OAAO,GAAG,OAAO,IAAI,0BAA0B,MAAM,CAAC,MAAM,YAAY,CAAC;IAC/E,OAAO,IAAI,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAe,EACf,OAA2C;IAE3C,OAAO,IAAI,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe,EAAE,KAAa;IAChE,OAAO,IAAI,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,OAAO,IAAI,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,OAAO,IAAI,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AACrC,CAAC"}

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

@@ -0,0 +1,111 @@
+/**
+ * `HttpError` — the framework's single concrete HTTP error type.
+ *
+ * Rather than a deep class hierarchy (`BadRequestError extends HttpError`,
+ * `NotFoundError extends HttpError`, …), the framework uses **composition via
+ * factory functions** (AI_GUIDELINES §1.4, ARCHITECTURE.md §13). Every HTTP
+ * error is an instance of this one class with a `statusCode` set at
+ * construction time by a factory. This keeps the hierarchy flat, makes errors
+ * trivially serializable, and allows runtime composition of properties.
+ *
+ * `cause` is forwarded to the ES2022 `Error` cause chain — pass the original
+ * error so callers can inspect the root cause without losing the stack.
+ *
+ * @module
+ */
+/**
+ * A single validation failure carried by a `422` error.
+ *
+ * Mirrors the shape used by `@setu-ts/validation-plugin` so error
+ * payloads are consistent across the validation and exceptions packages.
+ *
+ * @since 0.1.0
+ */
+export interface ValidationError {
+    /** Dot-path of the offending field (e.g. `"address.zip"`). */
+    readonly field: string;
+    /** Human-readable description of the failure. */
+    readonly message: string;
+    /** Optional machine-readable failure code. */
+    readonly code?: string;
+}
+/**
+ * Options accepted by the {@linkcode HttpError} constructor.
+ *
+ * Extracted as a type so factory functions can accept a consistent object.
+ *
+ * @since 0.1.0
+ */
+export interface HttpErrorInit {
+    /** HTTP status code (e.g. `404`). */
+    readonly statusCode: number;
+    /** Human-readable error message. */
+    readonly message: string;
+    /** Optional structured details attached to the error body. */
+    readonly details?: Readonly<Record<string, unknown>>;
+    /** Optional underlying cause (forwarded to the ES2022 `Error` cause chain). */
+    readonly cause?: Error;
+}
+/**
+ * The framework's HTTP error type.
+ *
+ * Throw an instance directly, or — preferably — construct one via a factory
+ * function from {@linkcode ./exceptions.ts} so the status code is correct by
+ * construction:
+ *
+ * @example
+ * ```typescript
+ * import { notFound } from '@setu-ts/exceptions';
+ *
+ * throw notFound(`User ${id} not found`);
+ * ```
+ *
+ * The error handler middleware inspects the `statusCode` to set the response
+ * status, and serializes `message` and `details` into the error body.
+ *
+ * @since 0.1.0
+ */
+export declare class HttpError extends Error {
+    /** The HTTP status code this error maps to. */
+    readonly statusCode: number;
+    /**
+     * Structured details appended to the error body. Omitted entirely when not
+     * supplied (never `undefined`) so serialization stays clean.
+     *
+     * `declare` suppresses the ES2022 class-field initialization that would
+     * otherwise set this to `undefined` on every instance — it only exists on
+     * the object when actually assigned by the constructor.
+     */
+    readonly details?: Readonly<Record<string, unknown>>;
+    /**
+     * Creates a new `HttpError`.
+     *
+     * Prefer the factory functions in `exceptions.ts` over calling this
+     * constructor directly — they guarantee a correct status code.
+     *
+     * @param statusCode - HTTP status code (e.g. `404`)
+     * @param message - Human-readable error message
+     * @param details - Optional structured details; omitted when absent
+     * @param cause - Optional underlying error; forwarded to the ES2022 cause chain
+     *
+     * @example
+     * ```typescript
+     * const err = new HttpError(404, 'User not found');
+     * console.log(err.statusCode); // 404
+     * ```
+     * @since 0.1.0
+     */
+    constructor(statusCode: number, message: string, details?: Readonly<Record<string, unknown>>, cause?: Error);
+    /**
+     * Creates an `HttpError` from an {@linkcode HttpErrorInit} object.
+     *
+     * Convenience overload used by factory functions so they can branch on
+     * optional `details`/`cause` once.
+     *
+     * @param init - The error options
+     * @returns A new `HttpError`
+     * @since 0.1.0
+     */
+    static from(init: HttpErrorInit): HttpError;
+}
+//# sourceMappingURL=http-error.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http-error.d.ts","sourceRoot":"","sources":["../../src/errors/http-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;;;OAOG;IACH,SAAiB,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAE7D;;;;;;;;;;;;;;;;;OAiBG;gBAED,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC3C,KAAK,CAAC,EAAE,KAAK;IAaf;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS;CAG5C"}