@setu-ts/exceptions 0.0.0-stage → 0.10.0

package/src/formatters/error-formatter.ts

@@ -0,0 +1,127 @@
+/**
+ * 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';
+
+import { rfc9457Formatter } from './rfc9457-formatter.ts';
+import { rfc7807Formatter } from './rfc7807-formatter.ts';
+import { HttpError } from '../errors/http-error.ts';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * 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';
+
+// ---------------------------------------------------------------------------
+// Built-in default formatter
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 const defaultFormatter: ErrorHandlerFormatter = (error: Error): DefaultErrorBody => {
+  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: ErrorFormat | ErrorHandlerFormatter = 'default',
+): ErrorHandlerFormatter {
+  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}"`);
+  }
+}

package/src/formatters/problem-details.ts

@@ -0,0 +1,177 @@
+/**
+ * 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';
+
+import { statusTitle } from '../errors/exceptions.ts';
+import { HttpError } from '../errors/http-error.ts';
+
+/**
+ * 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: string = `${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';
+
+/**
+ * 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 const RESPONDER_DETAIL: unique symbol = Symbol('setu.exceptions.responder-detail');
+
+/**
+ * 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;
+
+/**
+ * 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: HttpError): ProblemDetails['errors'] {
+  const details = error.details;
+  if (details === undefined || !('errors' in details)) {
+    return undefined;
+  }
+  return details.errors as ProblemDetails['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: Error,
+  ctx: IRequestContext | undefined,
+  resolveType: ProblemTypeResolver,
+): ProblemDetails {
+  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 as HttpError & { [RESPONDER_DETAIL]?: unknown })[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 }),
+  };
+}

package/src/formatters/rfc7807-formatter.ts

@@ -0,0 +1,48 @@
+/**
+ * RFC 7807 Problem Details error formatter (deprecated).
+ *
+ * RFC 7807 was obsoleted by [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html)
+ * in July 2023. This formatter is retained unchanged so existing callers keep
+ * their exact body shape through a deprecation period (AI_GUIDELINES §9.2); new
+ * code should use `rfc9457-formatter.ts`.
+ *
+ * It differs from the RFC 9457 formatter in the `type` member alone: this one
+ * mints a URI from the status code for every error, which RFC 9457 §4.2 replaces
+ * with `about:blank` for problems carrying no semantics beyond that status.
+ *
+ * @module
+ */
+import type { IRequestContext } from '@setu-ts/common';
+
+import type { ErrorHandlerFormatter } from './error-formatter.ts';
+import { buildProblemDetails, ERROR_TYPE_BASE, type ProblemDetails } from './problem-details.ts';
+
+/**
+ * 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: number): string => `${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: ErrorHandlerFormatter = (
+  error: Error,
+  ctx?: IRequestContext,
+): ProblemDetails => buildProblemDetails(error, ctx, resolveRfc7807Type);

package/src/formatters/rfc9457-formatter.ts

@@ -0,0 +1,69 @@
+/**
+ * RFC 9457 Problem Details error formatter.
+ *
+ * Produces a JSON body conforming to
+ * [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html) Problem Details for
+ * HTTP APIs, which obsoletes RFC 7807. The body carries `type`, `title`,
+ * `status`, and `detail`, with `instance` derived from the request path and an
+ * optional `errors` extension for validation failures.
+ *
+ * @module
+ */
+import type { IRequestContext } from '@setu-ts/common';
+
+import type { ErrorHandlerFormatter } from './error-formatter.ts';
+import {
+  ABOUT_BLANK,
+  buildProblemDetails,
+  type ProblemDetails,
+  VALIDATION_TYPE,
+} from './problem-details.ts';
+
+export { ERROR_TYPE_BASE } from './problem-details.ts';
+export type { ProblemDetails } from './problem-details.ts';
+
+/**
+ * Resolves the RFC 9457 `type` member.
+ *
+ * An {@linkcode HttpError} carries no problem-type identity beyond its status
+ * code, so a URI minted from that status would identify nothing the `status`
+ * member does not already convey — which is exactly the case RFC 9457 §4.2
+ * registers `about:blank` for. The one exception is the body produced by
+ * `validationError()`, which defines an `errors` extension member and is
+ * therefore a distinct problem type deserving its own URI.
+ *
+ * @param _statusCode - The HTTP status code (not used; the status member carries it)
+ * @param hasErrors - Whether the error carries a validation `errors` extension
+ * @returns `about:blank`, or the validation problem type URI
+ */
+const resolveRfc9457Type = (_statusCode: number, hasErrors: boolean): string =>
+  hasErrors ? VALIDATION_TYPE : ABOUT_BLANK;
+
+/**
+ * Format an error as RFC 9457 Problem Details.
+ *
+ * `type` is `about:blank` for problems whose only semantics are their status
+ * code, and the framework validation problem type when the error carries an
+ * `errors` extension. Every other member is assembled identically to the
+ * deprecated RFC 7807 formatter.
+ *
+ * @param error - The thrown error to format
+ * @param ctx - Optional request context (used for `instance`)
+ * @returns An RFC 9457 Problem Details body
+ * @example
+ * ```typescript
+ * rfc9457Formatter(notFound('User 42 does not exist'), ctx);
+ * // {
+ * //   type: 'about:blank',
+ * //   title: 'Not Found',
+ * //   status: 404,
+ * //   detail: 'User 42 does not exist',
+ * //   instance: '/users/42',
+ * // }
+ * ```
+ * @since 0.1.0
+ */
+export const rfc9457Formatter: ErrorHandlerFormatter = (
+  error: Error,
+  ctx?: IRequestContext,
+): ProblemDetails => buildProblemDetails(error, ctx, resolveRfc9457Type);

package/src/index.ts

@@ -0,0 +1,57 @@
+/**
+ * @module
+ *
+ * Exception factory functions, `HttpError`, error formatters, and the global
+ * error handler middleware.
+ *
+ * This is a **plain package** (not a plugin) — it depends on
+ * `@setu-ts/common` only and exposes types, factories, and a
+ * middleware factory. Register the middleware via the application's pipeline:
+ *
+ * ```typescript
+ * import { errorHandler } from '@setu-ts/exceptions';
+ *
+ * app.middleware.add(errorHandler({ format: 'rfc9457' }), {
+ *   priority: 0,
+ *   name: 'error-handler',
+ * });
+ * ```
+ *
+ * Every export here is public API and documented in PUBLIC_API.md
+ * (AI_GUIDELINES §10).
+ */
+
+// Error type
+export { HttpError } from './errors/http-error.ts';
+export type { HttpErrorInit, ValidationError } from './errors/http-error.ts';
+
+// Exception factories
+export {
+  badRequest,
+  conflict,
+  forbidden,
+  internalServerError,
+  notFound,
+  notImplemented,
+  serviceUnavailable,
+  STATUS_TITLES,
+  statusTitle,
+  tooManyRequests,
+  unauthorized,
+  validationError,
+} from './errors/exceptions.ts';
+
+// Formatters
+export { defaultFormatter, selectFormatter } from './formatters/error-formatter.ts';
+export type {
+  DefaultErrorBody,
+  ErrorFormat,
+  ErrorHandlerFormatter,
+} from './formatters/error-formatter.ts';
+export { ERROR_TYPE_BASE, rfc9457Formatter } from './formatters/rfc9457-formatter.ts';
+export type { ProblemDetails } from './formatters/rfc9457-formatter.ts';
+export { rfc7807Formatter } from './formatters/rfc7807-formatter.ts';
+
+// Middleware
+export { errorHandler } from './middleware/error-handler.ts';
+export type { ErrorHandlerOptions } from './middleware/error-handler.ts';