@setu-ts/exceptions 0.0.0-stage → 0.10.0

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"}

package/dist/errors/http-error.js

@@ -0,0 +1,81 @@
+/**
+ * `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
+ */
+/**
+ * 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 class HttpError extends Error {
+    /** The HTTP status code this error maps to. */
+    statusCode;
+    /**
+     * 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, message, details, cause) {
+        // Forward `cause` to the ES2022 Error cause chain when present. Under
+        // `exactOptionalPropertyTypes`, passing `{ cause: undefined }` would
+        // violate the option, so the options object is built conditionally.
+        super(message, cause !== undefined ? { cause } : undefined);
+        this.name = 'HttpError';
+        this.statusCode = statusCode;
+        if (details !== undefined) {
+            this.details = details;
+        }
+    }
+    /**
+     * 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) {
+        return new HttpError(init.statusCode, init.message, init.details, init.cause);
+    }
+}
+//# sourceMappingURL=http-error.js.map

package/dist/errors/http-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-error.js","sourceRoot":"","sources":["../../src/errors/http-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAqCH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,+CAA+C;IACtC,UAAU,CAAS;IAW5B;;;;;;;;;;;;;;;;;OAiBG;IACH,YACE,UAAkB,EAClB,OAAe,EACf,OAA2C,EAC3C,KAAa;QAEb,sEAAsE;QACtE,qEAAqE;QACrE,oEAAoE;QACpE,KAAK,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACzB,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAI,CAAC,IAAmB;QAC7B,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAChF,CAAC;CACF"}

package/dist/formatters/error-formatter.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Error format selector — resolves the configured error format to a concrete
+ * formatter function.
+ *
+ * Supported formats:
+ * - `'default'` — Framework-standard error shape (`statusCode`, `message`,
+ *   optional `details`).
+ * - `'rfc9457'` — RFC 9457 Problem Details (see `rfc9457-formatter.ts`).
+ * - `'rfc7807'` — deprecated; RFC 7807 Problem Details (see
+ *   `rfc7807-formatter.ts`). RFC 7807 was obsoleted by RFC 9457.
+ * - A custom function — used as-is.
+ *
+ * @module
+ */
+import type { IRequestContext } from '@setu-ts/common';
+/**
+ * A function that formats a thrown error into a serializable error body.
+ *
+ * @param error - The thrown error (an `HttpError` or a generic `Error`)
+ * @param ctx - Optional request context (used for `instance`, logging, etc.)
+ * @returns The formatted error body
+ * @since 0.1.0
+ */
+export type ErrorHandlerFormatter = (error: Error, ctx?: IRequestContext) => Record<string, unknown>;
+/**
+ * The built-in error format identifiers for `@setu-ts/exceptions`.
+ *
+ * `'rfc7807'` is retained for backward compatibility and resolves to the
+ * deprecated {@linkcode rfc7807Formatter}; prefer `'rfc9457'`.
+ *
+ * @since 0.1.0
+ */
+export type ErrorFormat = 'default' | 'rfc9457' | 'rfc7807';
+/**
+ * The framework-standard error body shape.
+ *
+ * @since 0.1.0
+ */
+export interface DefaultErrorBody {
+    /** The HTTP status code. */
+    readonly statusCode: number;
+    /** Human-readable error message. */
+    readonly message: string;
+    /** Optional structured details (present when the error carries any). */
+    readonly details?: Readonly<Record<string, unknown>>;
+    /** Optional stack trace (present only when `includeStackTrace` is on). */
+    readonly stack?: string;
+    /** Allow callers to attach further members. */
+    readonly [key: string]: unknown;
+}
+/**
+ * Framework-standard error formatter.
+ *
+ * Returns a body shaped as:
+ *
+ * ```json
+ * { "statusCode": 404, "message": "User not found", "details": { ... } }
+ * ```
+ *
+ * Generic (non-`HttpError`) errors map to `500`.
+ *
+ * @param error - The thrown error to format
+ * @returns The default formatted error body
+ * @since 0.1.0
+ */
+export declare const defaultFormatter: ErrorHandlerFormatter;
+/**
+ * Resolve the error format configuration to a concrete formatter function.
+ *
+ * - When `format` is `'default'`, `'rfc9457'`, or the deprecated `'rfc7807'`,
+ *   the corresponding built-in formatter is returned.
+ * - When `format` is already a function, it is returned as-is.
+ * - Otherwise a `TypeError` is thrown.
+ *
+ * @param format - The error format identifier or custom formatter function
+ * @returns The resolved formatter function
+ * @throws {TypeError} When an unknown format string is provided
+ * @since 0.1.0
+ */
+export declare function selectFormatter(format?: ErrorFormat | ErrorHandlerFormatter): ErrorHandlerFormatter;
+//# sourceMappingURL=error-formatter.d.ts.map

package/dist/formatters/error-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-formatter.d.ts","sourceRoot":"","sources":["../../src/formatters/error-formatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAUvD;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,KAAK,EAAE,KAAK,EACZ,GAAG,CAAC,EAAE,eAAe,KAClB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE7B;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAM5D;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4BAA4B;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,EAAE,qBAO9B,CAAC;AAMF;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,MAAM,GAAE,WAAW,GAAG,qBAAiC,GACtD,qBAAqB,CAcvB"}

package/dist/formatters/error-formatter.js

@@ -0,0 +1,58 @@
+import { rfc9457Formatter } from "./rfc9457-formatter.js";
+import { rfc7807Formatter } from "./rfc7807-formatter.js";
+import { HttpError } from "../errors/http-error.js";
+/**
+ * Framework-standard error formatter.
+ *
+ * Returns a body shaped as:
+ *
+ * ```json
+ * { "statusCode": 404, "message": "User not found", "details": { ... } }
+ * ```
+ *
+ * Generic (non-`HttpError`) errors map to `500`.
+ *
+ * @param error - The thrown error to format
+ * @returns The default formatted error body
+ * @since 0.1.0
+ */
+export const defaultFormatter = (error) => {
+    const isHttp = error instanceof HttpError;
+    return {
+        statusCode: isHttp ? error.statusCode : 500,
+        message: error.message,
+        ...(isHttp && error.details !== undefined && { details: error.details }),
+    };
+};
+// ---------------------------------------------------------------------------
+// Selector
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the error format configuration to a concrete formatter function.
+ *
+ * - When `format` is `'default'`, `'rfc9457'`, or the deprecated `'rfc7807'`,
+ *   the corresponding built-in formatter is returned.
+ * - When `format` is already a function, it is returned as-is.
+ * - Otherwise a `TypeError` is thrown.
+ *
+ * @param format - The error format identifier or custom formatter function
+ * @returns The resolved formatter function
+ * @throws {TypeError} When an unknown format string is provided
+ * @since 0.1.0
+ */
+export function selectFormatter(format = 'default') {
+    if (typeof format === 'function') {
+        return format;
+    }
+    switch (format) {
+        case 'default':
+            return defaultFormatter;
+        case 'rfc9457':
+            return rfc9457Formatter;
+        case 'rfc7807':
+            return rfc7807Formatter;
+        default:
+            throw new TypeError(`Unknown error format: "${format}"`);
+    }
+}
+//# sourceMappingURL=error-formatter.js.map

package/dist/formatters/error-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-formatter.js","sourceRoot":"","sources":["../../src/formatters/error-formatter.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAmDpD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA0B,CAAC,KAAY,EAAoB,EAAE;IACxF,MAAM,MAAM,GAAG,KAAK,YAAY,SAAS,CAAC;IAC1C,OAAO;QACL,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG;QAC3C,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,GAAG,CAAC,MAAM,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;KACzE,CAAC;AACJ,CAAC,CAAC;AAEF,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAC7B,SAA8C,SAAS;IAEvD,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,SAAS;YACZ,OAAO,gBAAgB,CAAC;QAC1B,KAAK,SAAS;YACZ,OAAO,gBAAgB,CAAC;QAC1B,KAAK,SAAS;YACZ,OAAO,gBAAgB,CAAC;QAC1B;YACE,MAAM,IAAI,SAAS,CAAC,0BAA0B,MAAM,GAAG,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC"}

package/dist/formatters/problem-details.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Shared Problem Details assembly.
+ *
+ * Both the RFC 9457 formatter and the deprecated RFC 7807 one produce the same
+ * body apart from the `type` member, so the assembly lives here once and each
+ * formatter supplies only its own {@linkcode ProblemTypeResolver}
+ * (AI_GUIDELINES §11.1).
+ *
+ * This module is internal: `buildProblemDetails` and `ProblemTypeResolver` are
+ * not exported from `src/index.ts`. `ERROR_TYPE_BASE` and `ProblemDetails` are
+ * re-exported publicly by `rfc9457-formatter.ts`.
+ *
+ * @module
+ */
+import type { IRequestContext } from '@setu-ts/common';
+/**
+ * The canonical base URI for framework-produced problem type identifiers.
+ *
+ * @since 0.1.0
+ */
+export declare const ERROR_TYPE_BASE = "https://setu-ts.dev/errors";
+/**
+ * The problem type URI identifying a validation failure.
+ *
+ * Spelled to match the literal `@setu-ts/validation-plugin` emits, so both
+ * packages identify the same problem type with the same URI. The two cannot
+ * share a constant — a package may not import another package's internals
+ * (AI_GUIDELINES §2.2) — so the agreement is pinned by a test in each.
+ *
+ * @since 0.1.0
+ */
+export declare const VALIDATION_TYPE: string;
+/**
+ * The RFC 9457 default problem type, meaning "no semantics beyond the HTTP
+ * status code" (RFC 9457 §4.2).
+ *
+ * @since 0.1.0
+ */
+export declare const ABOUT_BLANK = "about:blank";
+/**
+ * A Problem Details object as defined by
+ * [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html).
+ *
+ * Extension members beyond the five core fields are allowed (RFC 9457 §3.2),
+ * so `errors` and `stack` may be present.
+ *
+ * @since 0.1.0
+ */
+export interface ProblemDetails {
+    /** A URI reference identifying the problem type. */
+    readonly type: string;
+    /** A short, human-readable summary of the problem type. */
+    readonly title: string;
+    /** The HTTP status code generated for this occurrence. */
+    readonly status: number;
+    /** A human-readable explanation specific to this occurrence. */
+    readonly detail: string;
+    /** A URI reference identifying the specific occurrence (request path). */
+    readonly instance?: string;
+    /** Optional validation failures extension (present for `422` errors). */
+    readonly errors?: ReadonlyArray<{
+        field: string;
+        message: string;
+        code?: string;
+    }>;
+    /** Optional stack trace (present only when `includeStackTrace` is on). */
+    readonly stack?: string;
+    /** Allow callers to attach further extension members. */
+    readonly [key: string]: unknown;
+}
+/**
+ * Marks an {@linkcode HttpError} as one the M70f error responder built, and
+ * carries the calling site's disclosure.
+ *
+ * The responder must hand the disclosure to the Problem Details formatters as
+ * the `detail` member while leaving the site's title as the error `message`
+ * (which the `default` formatter emits verbatim). It cannot use
+ * `HttpError.details` alone as that channel: `details` is a free-form bag an
+ * application writes into too, so promoting any `details.detail` would change
+ * the body of a thrown error that merely uses the same key name.
+ *
+ * This marker is a module-private `Symbol` — not `Symbol.for` — because both
+ * writer ({@linkcode ../middleware/error-responder-impl.ts}) and reader
+ * ({@linkcode buildProblemDetails}) live in this package and import it
+ * directly; a global registry key would expose an internal channel that a
+ * third party could forge.
+ *
+ * @internal
+ */
+export declare const RESPONDER_DETAIL: unique symbol;
+/**
+ * Resolves the `type` member of a Problem Details body.
+ *
+ * @param statusCode - The HTTP status code of the occurrence
+ * @param hasErrors - Whether the error carries a validation `errors` extension
+ * @returns The problem type URI
+ * @since 0.1.0
+ */
+export type ProblemTypeResolver = (statusCode: number, hasErrors: boolean) => string;
+/**
+ * Assembles a Problem Details body from a thrown error.
+ *
+ * - `status` and `detail` come from the {@linkcode HttpError} (or default to
+ *   `500` / the error message for generic `Error`s).
+ * - `title` is derived from the status code via the shared status-title map.
+ * - `instance` is the request path when a context is supplied.
+ * - `errors` is included when the error carries validation details.
+ * - `type` is delegated to `resolveType`, the only member the two supported
+ *   specification versions disagree on.
+ *
+ * @param error - The thrown error to format
+ * @param ctx - Optional request context (used for `instance`)
+ * @param resolveType - Strategy supplying the `type` member
+ * @returns A Problem Details body
+ * @since 0.1.0
+ */
+export declare function buildProblemDetails(error: Error, ctx: IRequestContext | undefined, resolveType: ProblemTypeResolver): ProblemDetails;
+//# sourceMappingURL=problem-details.d.ts.map

package/dist/formatters/problem-details.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"problem-details.d.ts","sourceRoot":"","sources":["../../src/formatters/problem-details.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAKvD;;;;GAIG;AACH,eAAO,MAAM,eAAe,+BAA+B,CAAC;AAE5D;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,MAAwC,CAAC;AAEvE;;;;;GAKG;AACH,eAAO,MAAM,WAAW,gBAAgB,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;QAC9B,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;IACH,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAmD,CAAC;AAE1F;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,KAAK,MAAM,CAAC;AAgBrF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,eAAe,GAAG,SAAS,EAChC,WAAW,EAAE,mBAAmB,GAC/B,cAAc,CAgChB"}

package/dist/formatters/problem-details.js

@@ -0,0 +1,108 @@
+import { statusTitle } from "../errors/exceptions.js";
+import { HttpError } from "../errors/http-error.js";
+/**
+ * The canonical base URI for framework-produced problem type identifiers.
+ *
+ * @since 0.1.0
+ */
+export const ERROR_TYPE_BASE = 'https://setu-ts.dev/errors';
+/**
+ * The problem type URI identifying a validation failure.
+ *
+ * Spelled to match the literal `@setu-ts/validation-plugin` emits, so both
+ * packages identify the same problem type with the same URI. The two cannot
+ * share a constant — a package may not import another package's internals
+ * (AI_GUIDELINES §2.2) — so the agreement is pinned by a test in each.
+ *
+ * @since 0.1.0
+ */
+export const VALIDATION_TYPE = `${ERROR_TYPE_BASE}/validation`;
+/**
+ * The RFC 9457 default problem type, meaning "no semantics beyond the HTTP
+ * status code" (RFC 9457 §4.2).
+ *
+ * @since 0.1.0
+ */
+export const ABOUT_BLANK = 'about:blank';
+/**
+ * Marks an {@linkcode HttpError} as one the M70f error responder built, and
+ * carries the calling site's disclosure.
+ *
+ * The responder must hand the disclosure to the Problem Details formatters as
+ * the `detail` member while leaving the site's title as the error `message`
+ * (which the `default` formatter emits verbatim). It cannot use
+ * `HttpError.details` alone as that channel: `details` is a free-form bag an
+ * application writes into too, so promoting any `details.detail` would change
+ * the body of a thrown error that merely uses the same key name.
+ *
+ * This marker is a module-private `Symbol` — not `Symbol.for` — because both
+ * writer ({@linkcode ../middleware/error-responder-impl.ts}) and reader
+ * ({@linkcode buildProblemDetails}) live in this package and import it
+ * directly; a global registry key would expose an internal channel that a
+ * third party could forge.
+ *
+ * @internal
+ */
+export const RESPONDER_DETAIL = Symbol('setu.exceptions.responder-detail');
+/**
+ * Extracts the validation `errors` extension from an error's `details`, if any.
+ *
+ * @param error - The HTTP error to read
+ * @returns The validation failures, or `undefined` when the error carries none
+ */
+function extractErrors(error) {
+    const details = error.details;
+    if (details === undefined || !('errors' in details)) {
+        return undefined;
+    }
+    return details.errors;
+}
+/**
+ * Assembles a Problem Details body from a thrown error.
+ *
+ * - `status` and `detail` come from the {@linkcode HttpError} (or default to
+ *   `500` / the error message for generic `Error`s).
+ * - `title` is derived from the status code via the shared status-title map.
+ * - `instance` is the request path when a context is supplied.
+ * - `errors` is included when the error carries validation details.
+ * - `type` is delegated to `resolveType`, the only member the two supported
+ *   specification versions disagree on.
+ *
+ * @param error - The thrown error to format
+ * @param ctx - Optional request context (used for `instance`)
+ * @param resolveType - Strategy supplying the `type` member
+ * @returns A Problem Details body
+ * @since 0.1.0
+ */
+export function buildProblemDetails(error, ctx, resolveType) {
+    const isHttp = error instanceof HttpError;
+    const statusCode = isHttp ? error.statusCode : 500;
+    const errors = isHttp ? extractErrors(error) : undefined;
+    // A responder-built error carries the site's disclosure in its structured
+    // details under a `detail` key (M70f); the Problem Details `detail` member
+    // is that disclosure, falling back to the error message (the title) when a
+    // site supplied none.
+    //
+    // The promotion is gated on {@linkcode RESPONDER_DETAIL}, NOT on the mere
+    // presence of a `detail` key, because `HttpError.details` is a free-form bag
+    // an application also writes into: reading any `details.detail` would
+    // silently change the `detail` member of a thrown
+    // `new HttpError(400, 'Invalid payload', { detail: 'code-7' })` from its
+    // message to `'code-7'` — a released-behaviour change to every application
+    // that happens to use that key name (M70f code review, finding 4). Only an
+    // error the responder built carries the marker, so a thrown error keeps the
+    // pre-M70f shape: `detail` is the message.
+    const carriedDetail = isHttp && RESPONDER_DETAIL in error
+        ? error[RESPONDER_DETAIL]
+        : undefined;
+    const detail = typeof carriedDetail === 'string' ? carriedDetail : error.message;
+    return {
+        type: resolveType(statusCode, errors !== undefined),
+        title: statusTitle(statusCode),
+        status: statusCode,
+        detail,
+        ...(ctx !== undefined && { instance: ctx.request.path }),
+        ...(errors !== undefined && { errors }),
+    };
+}
+//# sourceMappingURL=problem-details.js.map

package/dist/formatters/problem-details.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"problem-details.js","sourceRoot":"","sources":["../../src/formatters/problem-details.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,4BAA4B,CAAC;AAE5D;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,eAAe,GAAW,GAAG,eAAe,aAAa,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC;AAkCzC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAkB,MAAM,CAAC,kCAAkC,CAAC,CAAC;AAY1F;;;;;GAKG;AACH,SAAS,aAAa,CAAC,KAAgB;IACrC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,IAAI,OAAO,CAAC,EAAE,CAAC;QACpD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,OAAO,CAAC,MAAkC,CAAC;AACpD,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAY,EACZ,GAAgC,EAChC,WAAgC;IAEhC,MAAM,MAAM,GAAG,KAAK,YAAY,SAAS,CAAC;IAC1C,MAAM,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC;IACnD,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACzD,0EAA0E;IAC1E,2EAA2E;IAC3E,2EAA2E;IAC3E,sBAAsB;IACtB,EAAE;IACF,0EAA0E;IAC1E,6EAA6E;IAC7E,sEAAsE;IACtE,kDAAkD;IAClD,yEAAyE;IACzE,2EAA2E;IAC3E,2EAA2E;IAC3E,4EAA4E;IAC5E,2CAA2C;IAC3C,MAAM,aAAa,GACjB,MAAM,IAAI,gBAAgB,IAAI,KAAK;QACjC,CAAC,CAAE,KAAsD,CAAC,gBAAgB,CAAC;QAC3E,CAAC,CAAC,SAAS,CAAC;IAChB,MAAM,MAAM,GAAG,OAAO,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;IAEjF,OAAO;QACL,IAAI,EAAE,WAAW,CAAC,UAAU,EAAE,MAAM,KAAK,SAAS,CAAC;QACnD,KAAK,EAAE,WAAW,CAAC,UAAU,CAAC;QAC9B,MAAM,EAAE,UAAU;QAClB,MAAM;QACN,GAAG,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QACxD,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,CAAC;KACxC,CAAC;AACJ,CAAC"}

package/dist/formatters/rfc7807-formatter.d.ts

@@ -0,0 +1,20 @@
+import type { ErrorHandlerFormatter } from './error-formatter.ts';
+/**
+ * Format an error as RFC 7807 Problem Details.
+ *
+ * @param error - The thrown error to format
+ * @param ctx - Optional request context (used for `instance`)
+ * @returns An RFC 7807 Problem Details body
+ * @deprecated RFC 7807 was obsoleted by RFC 9457. Use `rfc9457Formatter`
+ * instead, or the `'rfc9457'` format alias. Will be removed in v1.0.0.
+ * @example
+ * ```typescript
+ * // Before
+ * app.middleware.add(errorHandler({ format: 'rfc7807' }));
+ * // After — `type` becomes 'about:blank' for status-only problems
+ * app.middleware.add(errorHandler({ format: 'rfc9457' }));
+ * ```
+ * @since 0.1.0
+ */
+export declare const rfc7807Formatter: ErrorHandlerFormatter;
+//# sourceMappingURL=rfc7807-formatter.d.ts.map

package/dist/formatters/rfc7807-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rfc7807-formatter.d.ts","sourceRoot":"","sources":["../../src/formatters/rfc7807-formatter.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAWlE;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB,EAAE,qBAGyC,CAAC"}

package/dist/formatters/rfc7807-formatter.js

@@ -0,0 +1,27 @@
+import { buildProblemDetails, ERROR_TYPE_BASE } from "./problem-details.js";
+/**
+ * Resolves the RFC 7807 `type` member: a URI minted from the status code.
+ *
+ * @param statusCode - The HTTP status code of the occurrence
+ * @returns The status-derived problem type URI
+ */
+const resolveRfc7807Type = (statusCode) => `${ERROR_TYPE_BASE}/${statusCode}`;
+/**
+ * Format an error as RFC 7807 Problem Details.
+ *
+ * @param error - The thrown error to format
+ * @param ctx - Optional request context (used for `instance`)
+ * @returns An RFC 7807 Problem Details body
+ * @deprecated RFC 7807 was obsoleted by RFC 9457. Use `rfc9457Formatter`
+ * instead, or the `'rfc9457'` format alias. Will be removed in v1.0.0.
+ * @example
+ * ```typescript
+ * // Before
+ * app.middleware.add(errorHandler({ format: 'rfc7807' }));
+ * // After — `type` becomes 'about:blank' for status-only problems
+ * app.middleware.add(errorHandler({ format: 'rfc9457' }));
+ * ```
+ * @since 0.1.0
+ */
+export const rfc7807Formatter = (error, ctx) => buildProblemDetails(error, ctx, resolveRfc7807Type);
+//# sourceMappingURL=rfc7807-formatter.js.map

package/dist/formatters/rfc7807-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rfc7807-formatter.js","sourceRoot":"","sources":["../../src/formatters/rfc7807-formatter.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAuB,MAAM,sBAAsB,CAAC;AAEjG;;;;;GAKG;AACH,MAAM,kBAAkB,GAAG,CAAC,UAAkB,EAAU,EAAE,CAAC,GAAG,eAAe,IAAI,UAAU,EAAE,CAAC;AAE9F;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA0B,CACrD,KAAY,EACZ,GAAqB,EACL,EAAE,CAAC,mBAAmB,CAAC,KAAK,EAAE,GAAG,EAAE,kBAAkB,CAAC,CAAC"}