@setu-ts/exceptions 0.0.0-stage → 0.10.0

package/dist/middleware/error-responder-impl.js

@@ -0,0 +1,158 @@
+import { httpStatusHintOf, resolveResponseStatus } from '@setu-ts/common';
+import { HttpError } from "../errors/http-error.js";
+import { RESPONDER_DETAIL } from "../formatters/problem-details.js";
+/**
+ * The `application/problem+json` content type for Problem Details responses.
+ *
+ * Mirrors the constant `errorHandler` uses to decide the media type: a
+ * formatter answers Problem Details (and so derives `instance` from the
+ * request path) exactly when its resolved content type is this one.
+ */
+const PROBLEM_JSON = 'application/problem+json';
+/** The pure thrown-value rule, shared by serving and request-log prediction. */
+export function thrownErrorStatus(error) {
+    const requested = error instanceof HttpError ? error.statusCode : (httpStatusHintOf(error)?.status ?? 500);
+    // Fetch refuses informational responses and bodies on 204, 205 and 304.
+    const status = Number.isInteger(requested) &&
+        requested >= 200 &&
+        requested <= 599 &&
+        requested !== 204 &&
+        requested !== 205 &&
+        requested !== 304
+        ? requested
+        : 500;
+    return { requested, status };
+}
+/**
+ * Narrows an {@linkcode ErrorResponderTarget} to a full {@linkcode
+ * IRequestContext} when it genuinely is one.
+ *
+ * The responder is reached two ways. In-pipeline sites — the kernel's terminals
+ * and every short-circuiting middleware — pass the live `IRequestContext`,
+ * which carries `id`, `services`, and `startTime`. The kernel's PRE-pipeline
+ * sites — the shutdown-drain `503` and the malformed-request `400` — pass a
+ * bare target of just `state`, `response`, and an optional safe `request`
+ * path, because no request context exists yet. The three members checked here
+ * are present on every real context and absent from every bare target, so the
+ * test distinguishes the two without a lie.
+ *
+ * @param target - The responder target to test
+ * @returns `true` when the target is a full request context
+ */
+function isFullRequestContext(target) {
+    const ctx = target;
+    return (typeof ctx.id === 'string' &&
+        typeof ctx.services === 'object' &&
+        ctx.services !== null &&
+        typeof ctx.startTime === 'number');
+}
+/**
+ * Builds the {@linkcode HttpError} that carries one error response's status,
+ * title and disclosure.
+ *
+ * This is the single owner of that mapping, and it has **two** callers: the
+ * responder below, and `errorHandler`'s status-hint path (M89b), which answers
+ * a thrown error branded with an `HttpStatusHint` — a type that IS an
+ * `ErrorResponseInit`. Sharing it is what makes the two agree: a hinted throw
+ * and a `respondWithError` call carrying the same values produce byte-identical
+ * bodies under `default`, `rfc9457`, `rfc7807` and any custom formatter. A
+ * second hand-rolled construction would silently diverge — the `default`
+ * formatter reads `details.detail` while the Problem Details formatters read
+ * the {@linkcode RESPONDER_DETAIL} symbol, so getting either half wrong loses
+ * the disclosure in exactly one format.
+ *
+ * @param init - The status, title, disclosure and optional structured details
+ * @returns An `HttpError` every formatter renders with the disclosure intact
+ */
+export function buildErrorFromInit(init) {
+    // The title is the framework-default `error` member — the `message` of the
+    // `default` format and the `detail` fallback of the Problem Details
+    // formatters — so it stays `error.message`. The disclosure (`init.detail`)
+    // is kept verbatim by every format (the `ErrorResponseInit` contract in
+    // `@setu-ts/common`): it is carried in the error's structured `details`
+    // under a `detail` key, so the `default` format emits it as `details.detail`
+    // beside `message`, and `buildProblemDetails` promotes it to the Problem
+    // Details `detail` member (falling back to the title when a site supplies no
+    // disclosure). `init.details` (e.g. a validation `errors` array) is merged
+    // through unchanged. Carrying it this way — rather than in `error.message` —
+    // keeps the title verbatim, which a site's (non-)disclosure decision depends
+    // on.
+    const details = init.detail !== undefined ? { ...init.details, detail: init.detail } : init.details;
+    const error = new HttpError(init.status, init.title, details);
+    // Mark the error as responder-built and carry the disclosure on a
+    // module-private symbol, which is what `buildProblemDetails` promotes to the
+    // Problem Details `detail` member. The `details.detail` key above is what the
+    // `default` formatter emits (it serializes `details` verbatim); the Problem
+    // Details formatters read the symbol instead, so a THROWN error that happens
+    // to carry a `details.detail` key of its own keeps `detail: <message>` (M70f
+    // code review, finding 4). Non-enumerable so it never reaches a serialized
+    // body.
+    if (init.detail !== undefined) {
+        Object.defineProperty(error, RESPONDER_DETAIL, {
+            value: init.detail,
+            enumerable: false,
+            writable: false,
+            configurable: true,
+        });
+    }
+    return error;
+}
+/**
+ * Builds an {@linkcode IErrorResponder} from the formatter and content type
+ * that `errorHandler` has **already** resolved at factory time.
+ *
+ * The responder keeps the `HttpError` construction inside the only package that
+ * owns it: it builds an `HttpError` from the init (so `buildProblemDetails` sees
+ * a real `statusCode` and the validation `errors` extension, and
+ * `maskInternalErrors` would never mask a deliberately 4xx), runs the resolved
+ * formatter over it, and writes status, `content-type` and the serialized body
+ * — the same three-step tail `errorHandler`'s catch path performs.
+ *
+ * @param formatter - The resolved error formatter
+ * @param contentType - The resolved response content type
+ * @returns A responder publishing the application's error format
+ * @since 0.1.0
+ */
+export function createErrorResponder(formatter, contentType) {
+    return {
+        statusFor: (error) => thrownErrorStatus(error).status,
+        respond(target, init) {
+            // Sanitized before the error is built, not just before the status is
+            // written, so the formatted body's `status` member agrees with the status
+            // actually written. Idempotent, so the common path through
+            // `respondWithError` — which already sanitized — reports nothing twice.
+            const status = resolveResponseStatus(init.status, target);
+            const error = buildErrorFromInit(status === init.status ? init : { ...init, status });
+            // The formatter's `ctx` parameter is a FULL `IRequestContext` by its
+            // contract (M70f re-review round 2, finding 2). The target is a full
+            // context only at the in-pipeline sites; the kernel's pre-pipeline sites
+            // hand over a bare target whose `services`, `id`, `params`, `query`,
+            // `signal` and `startTime` do not exist. Passing that partial object
+            // would let a custom formatter read a documented member and throw
+            // `TypeError: Cannot read properties of undefined` — replacing the
+            // configured 503/400 with an unhandled exception. So the formatter
+            // receives the context only when it genuinely is one, and `undefined`
+            // otherwise — the value its optional `ctx` parameter already declares.
+            const fullContext = isFullRequestContext(target) ? target : undefined;
+            let body = formatter(error, fullContext);
+            // The Problem Details `instance` member comes from the request path. At
+            // the in-pipeline sites the formatter read it off the full context; at
+            // the pre-pipeline sites there is no context, so the responder supplies
+            // the safe path the kernel captured separately — a separate internal
+            // mechanism, since the formatter's optional `ctx` parameter is the only
+            // public channel and it must stay honest (M70f re-review round 2,
+            // finding 2). A malformed request carries no path, in which case the
+            // member is simply absent. A fresh object is composed rather than
+            // mutating the formatter's return value, which a custom formatter may
+            // share or freeze.
+            if (fullContext === undefined &&
+                contentType === PROBLEM_JSON &&
+                target.request !== undefined) {
+                body = { ...body, instance: target.request.path };
+            }
+            const bytes = new TextEncoder().encode(JSON.stringify(body));
+            target.response.status(status).header('content-type', contentType).send(bytes);
+        },
+    };
+}
+//# sourceMappingURL=error-responder-impl.js.map

package/dist/middleware/error-responder-impl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-responder-impl.js","sourceRoot":"","sources":["../../src/middleware/error-responder-impl.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@setu-ts/exceptions",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.10.0",
+  "description": "Exception hierarchy, RFC 9457 Problem Details, and the error-handler middleware",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/setu-ts/setu-ts.git",
+    "directory": "packages/exceptions"
+  },
+  "homepage": "https://github.com/setu-ts/setu-ts/tree/main/packages/exceptions",
+  "bugs": {
+    "url": "https://github.com/setu-ts/setu-ts/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": "^22.23.4 || ^24.22.1 || >=26.12.1"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "AGENT_CARD.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@setu-ts/common": "^0.10.0"
+  },
+  "devDependencies": {
+    "@setu-ts/auth-plugin": "^0.10.0",
+    "@setu-ts/feature-flags-plugin": "^0.10.0",
+    "@setu-ts/http-security-plugin": "^0.10.0",
+    "@setu-ts/logger-plugin": "^0.10.0",
+    "@setu-ts/multi-tenancy-plugin": "^0.10.0",
+    "@setu-ts/runtime": "^0.10.0",
+    "@setu-ts/session-plugin": "^0.10.0",
+    "@setu-ts/storage-plugin": "^0.10.0",
+    "@setu-ts/testing": "^0.10.0",
+    "@types/node": "^24",
+    "typescript": "6.0.3",
+    "vitest": "5.0.3"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
 }

package/src/errors/exceptions.ts

@@ -0,0 +1,209 @@
+/**
+ * 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';
+
+// ---------------------------------------------------------------------------
+// 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: Readonly<Record<number, string>> = {
+  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: number): string {
+  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: string,
+  details?: Readonly<Record<string, unknown>>,
+): HttpError {
+  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: string): HttpError {
+  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: string): HttpError {
+  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: string): HttpError {
+  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: string): HttpError {
+  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: readonly ValidationError[], message?: string): HttpError {
+  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: string,
+  details?: Readonly<Record<string, unknown>>,
+): HttpError {
+  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: string, cause?: Error): HttpError {
+  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: string): HttpError {
+  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: string): HttpError {
+  return new HttpError(503, message);
+}

package/src/errors/http-error.ts

@@ -0,0 +1,132 @@
+/**
+ * `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 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.
+   */
+  declare 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,
+  ) {
+    // 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: HttpErrorInit): HttpError {
+    return new HttpError(init.statusCode, init.message, init.details, init.cause);
+  }
+}