@sdxc/problem 0.0.0-pre.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Xalambrí
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,244 @@
+# @sdxc/problem
+
+Build, detect and parse [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details
+(`application/problem+json`), and declare an API's problem types in one catalog.
+
+## Installation
+
+```bash
+npm add @sdxc/problem
+```
+
+Extension members are validated with [`remix/data-schema`](https://www.npmjs.com/package/remix)
+or any other [Standard Schema](https://standardschema.dev/), and results come back as
+[`@sdxc/result`](https://www.npmjs.com/package/@sdxc/result) values; both install alongside
+this package.
+
+## Usage
+
+### Answer With A Problem
+
+```typescript
+import { problem } from "@sdxc/problem";
+
+return problem({ status: 404 });
+// 404, Content-Type: application/problem+json
+// {"type":"about:blank","title":"Not Found","status":404}
+```
+
+A status alone is a complete document: `type` defaults to `about:blank` and `title` to the
+status phrase. Add `type`, `title`, `detail`, `instance` and `extensions` as needed:
+
+```typescript
+return problem(
+	{
+		status: 403,
+		type: "https://example.com/probs/out-of-credit",
+		title: "You do not have enough credit.",
+		detail: "Your current balance is 30, but that costs 50.",
+		extensions: { balance: 30 },
+	},
+	{ headers: { "Cache-Control": "no-store" } },
+);
+```
+
+Extensions are written at the document's top level, and one named like a standard member
+never replaces it.
+
+### Declare A Catalog
+
+```typescript
+import { defineProblems } from "@sdxc/problem";
+import * as s from "remix/data-schema";
+
+export const problems = defineProblems("https://docs.example.com/errors/", {
+	notFound: { slug: "not-found", status: 404, title: "The resource does not exist" },
+	outOfCredit: {
+		slug: "out-of-credit",
+		status: 403,
+		title: "You do not have enough credit",
+		extensions: s.object({ balance: s.number() }),
+	},
+});
+
+return problems.notFound({ detail: "No article has that slug." });
+return problems.outOfCredit({ extensions: { balance: 30 } });
+```
+
+Each entry becomes a builder that writes its `type` (the base URL followed by the slug),
+`status` and `title`, so a call site supplies only `detail`, `instance` and the extensions
+its schema types. The base URL must end in `/`.
+
+### Read A Problem
+
+```typescript
+import { isProblem, parseProblem } from "@sdxc/problem";
+import { isSuccess } from "@sdxc/result";
+
+if (isProblem(response)) {
+	let result = await parseProblem(response);
+	if (isSuccess(result)) result.data.type; // "https://example.com/probs/out-of-credit"
+}
+```
+
+With a catalog, `parse` names the entry a response belongs to and validates its extensions:
+
+```typescript
+let result = await problems.parse(response);
+
+if (isSuccess(result) && problems.is(result.data, "outOfCredit")) {
+	result.data.extensions.balance; // number
+}
+```
+
+A `type` outside the catalog still parses, with `name: null`, as RFC 9457 requires clients
+to accept problem types they do not know.
+
+### Report Validation Failures
+
+```typescript
+import { issuesFrom, validationProblem } from "@sdxc/problem";
+import * as s from "remix/data-schema";
+
+let result = s.parseSafe(schema, body);
+if (!result.success) return validationProblem(issuesFrom(result.issues));
+// 422 with {"errors":[{"pointer":"/user/email","code":"invalid","message":"..."}], ...}
+```
+
+## API
+
+### `problem(options, init?)`
+
+Returns a `Response` whose status line and body `status` both come from `options.status`,
+with `Content-Type: application/problem+json`. `init` adds headers.
+
+### `stringify(options)`
+
+The document's JSON text, for writing a problem somewhere other than a `Response`.
+
+### `defineProblems(base, entries)`
+
+A catalog: one builder per entry, plus `parse(response)`, `is(problem, name)` and
+`entries()`, which lists every entry with its resolved `type` for rendering an error
+reference. Entries cannot be named `parse`, `is` or `entries`.
+
+### `isProblem(message)`
+
+Whether a `Request` or `Response` declares `application/problem+json`, ignoring parameters
+and case. The body is left unread.
+
+### `parseProblem(response, options?)`
+
+Reads a problem `Response` into a `Result<Problem, ProblemParseError>`. Absent members take
+their RFC defaults, and the status line wins over the body's `status`. Pass
+`options.extensions`, a synchronous Standard Schema, to validate and type the extensions.
+
+### `parse(text, options?)`
+
+The same, from JSON text; `options.status` stands in for the status line.
+
+### `validationProblem(issues, options?)`
+
+A `422` problem whose `errors` extension lists each invalid field. `options` sets any
+standard member, including a different `status`.
+
+### `issuesFrom(source, code?)`
+
+Converts Standard Schema issues, or an error carrying them in `issues`, into `errors`
+entries, turning each path into a JSON Pointer. Every entry gets `code`, `"invalid"` by
+default.
+
+### `toPointer(path)`
+
+Formats an issue path as an RFC 6901 JSON Pointer, escaping `~` and `/`.
+
+### `ISSUES_SCHEMA`
+
+The schema for the `errors` extension, for `s.object({ errors: ISSUES_SCHEMA })`.
+
+### `ProblemParseError`
+
+Why a document is not a problem. `issues` holds the extension schema's issues when that is
+the reason.
+
+### `PROBLEM_MEDIA_TYPE`, `ABOUT_BLANK`
+
+`"application/problem+json"` and `"about:blank"`.
+
+### Types
+
+`Problem<Extensions>` is a parsed document, with `detail` and `instance` as `string | null`
+and extension members under `extensions`. `ProblemOptions<Extensions>` is what a writer
+passes, and `ProblemIssue` is one `errors` entry.
+
+## Pattern: Share A Catalog Between A Server And Its Client
+
+```typescript
+// api-problems.ts, imported by both
+import { ISSUES_SCHEMA, defineProblems } from "@sdxc/problem";
+import * as s from "remix/data-schema";
+
+export const apiProblems = defineProblems("https://docs.example.com/errors/", {
+	notFound: { slug: "not-found", status: 404, title: "The resource does not exist" },
+	validationFailed: {
+		slug: "validation-failed",
+		status: 422,
+		title: "The request body is invalid",
+		extensions: s.object({ errors: ISSUES_SCHEMA }),
+	},
+});
+```
+
+```typescript
+// server
+import { issuesFrom } from "@sdxc/problem";
+import * as s from "remix/data-schema";
+
+let result = s.parseSafe(schema, body);
+if (!result.success) {
+	return apiProblems.validationFailed({ extensions: { errors: issuesFrom(result.issues) } });
+}
+```
+
+```typescript
+// client
+import { isSuccess } from "@sdxc/result";
+
+let response = await fetch(url, { method: "POST", body });
+if (!response.ok) {
+	let result = await apiProblems.parse(response);
+	if (isSuccess(result) && apiProblems.is(result.data, "validationFailed")) {
+		for (let issue of result.data.extensions.errors) showError(issue.pointer, issue.message);
+	}
+}
+```
+
+## Versioning
+
+Releases are dated rather than semantic. A version is the UTC date it was published,
+written `YYYY.M.D`, so `2026.9.4` is the release from 4 September 2026. At most one
+release goes out per day.
+
+Those numbers say when, not what: a later date means a later release and carries no
+compatibility promise. Any release may change or remove an export.
+
+Depend on one exact date, and move it when you are ready to take the change:
+
+```json
+{
+	"dependencies": {
+		"@sdxc/problem": "2026.9.4"
+	}
+}
+```
+
+A caret or tilde range reads the date as major, minor and patch, so it accepts every
+later release in the same year. An exact version keeps the upgrade yours to schedule.
+
+## License
+
+MIT
+
+## Author
+
+[Sergio Xalambrí](https://sergiodxa.com)

package/dist/catalog.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Problem catalogs: an API declares its problem types once, and gets a builder per
+ * type for its handlers and a parser that recognizes those types for its clients,
+ * so the `type`, `status` and `title` of each are written in one place.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { Problem } from "./types.js";
+import { ProblemParseError } from "./parse.js";
+/** One problem type in a catalog. */
+export interface ProblemEntry<Extensions extends object = object> {
+    /** Appended to the catalog's base URL to form `type`; it is the wire contract, so keep it stable. */
+    slug: string;
+    status: number;
+    title: string;
+    /** Types the builder's `extensions` argument and validates them when the catalog parses. */
+    extensions?: StandardSchemaV1<unknown, Extensions>;
+}
+/** The entries of a catalog, keyed by builder name; `parse`, `is` and `entries` name its own methods. */
+export type ProblemEntries = Record<string, ProblemEntry<any>> & {
+    parse?: never;
+    is?: never;
+    entries?: never;
+};
+/** The extension members an entry's schema produces, `undefined` for an entry without one. */
+type ExtensionsOf<Entry> = Entry extends ProblemEntry<infer Extensions> ? Entry extends {
+    extensions: StandardSchemaV1;
+} ? Extensions : undefined : undefined;
+/** What a call site supplies to a builder; `extensions` is required exactly when the entry has a schema. */
+export type BuilderInput<Extensions> = {
+    detail?: string;
+    instance?: string;
+} & ([Extensions] extends [undefined] ? {
+    extensions?: undefined;
+} : {
+    extensions: Extensions;
+});
+/** A builder for one catalog entry, returning its problem `Response`. */
+export type ProblemBuilder<Extensions> = [Extensions] extends [undefined] ? (input?: BuilderInput<Extensions>, init?: ResponseInit) => Response : (input: BuilderInput<Extensions>, init?: ResponseInit) => Response;
+/**
+ * A problem the catalog read: `name` is the entry whose `type` it carries, with that entry's
+ * extensions validated, or `null` for a type outside the catalog, which RFC 9457 requires a
+ * client to accept.
+ */
+export type CatalogProblem<Entries extends ProblemEntries> = {
+    [Name in keyof Entries & string]: Problem<ExtensionsOf<Entries[Name]> extends object ? ExtensionsOf<Entries[Name]> : Record<string, unknown>> & {
+        name: Name;
+    };
+}[keyof Entries & string] | (Problem & {
+    name: null;
+});
+/** One entry as `entries()` lists it, with its resolved `type`. */
+export interface CatalogEntry {
+    name: string;
+    type: string;
+    status: number;
+    title: string;
+}
+/** The methods every catalog carries beside its builders. */
+export interface CatalogMethods<Entries extends ProblemEntries> {
+    /**
+     * Reads a problem response and names the entry it belongs to. A known type whose
+     * extensions fail the entry's schema is a failure.
+     */
+    parse(response: Response): Promise<Result<CatalogProblem<Entries>, ProblemParseError>>;
+    /** Narrows a parsed problem to one entry. */
+    is<Name extends keyof Entries & string>(problem: CatalogProblem<Entries>, name: Name): problem is Extract<CatalogProblem<Entries>, {
+        name: Name;
+    }>;
+    /** Every entry, in declaration order, for rendering an error reference. */
+    entries(): CatalogEntry[];
+}
+/** A defined catalog: one builder per entry, plus its methods. */
+export type ProblemCatalog<Entries extends ProblemEntries> = {
+    [Name in keyof Entries]: ProblemBuilder<ExtensionsOf<Entries[Name]>>;
+} & CatalogMethods<Entries>;
+/**
+ * Declares an API's problem types. Each `type` is `base` followed by the entry's slug, so
+ * `base` ends in `/`: that is what keeps its last path segment when a slug is resolved.
+ *
+ * @param base - The URL the types live under, usually the error reference's docs page.
+ * @param entries - The problem types, keyed by the builder name each becomes.
+ * @returns The catalog.
+ * @example let problems = defineProblems("https://docs.example.com/errors/", { notFound: { slug: "not-found", status: 404, title: "Not found" } });
+ * @example return problems.notFound({ detail: "No article has that slug." });
+ */
+export declare function defineProblems<const Entries extends ProblemEntries>(base: `${string}/`, entries: Entries): ProblemCatalog<Entries>;
+export {};

package/dist/catalog.js

@@ -0,0 +1,39 @@
+import { failure, success } from "@sdxc/result";
+import { ProblemParseError, parseProblem, readExtensions } from "./parse.js";
+import { problem } from "./problem.js";
+/**
+ * Declares an API's problem types. Each `type` is `base` followed by the entry's slug, so
+ * `base` ends in `/`: that is what keeps its last path segment when a slug is resolved.
+ *
+ * @param base - The URL the types live under, usually the error reference's docs page.
+ * @param entries - The problem types, keyed by the builder name each becomes.
+ * @returns The catalog.
+ * @example let problems = defineProblems("https://docs.example.com/errors/", { notFound: { slug: "not-found", status: 404, title: "Not found" } });
+ * @example return problems.notFound({ detail: "No article has that slug." });
+ */
+export function defineProblems(base, entries) {
+    let names = new Map();
+    let listing = [];
+    let catalog = {};
+    for (let [name, entry] of Object.entries(entries)) {
+        let type = `${base}${entry.slug}`;
+        names.set(type, name);
+        listing.push({ name, type, status: entry.status, title: entry.title });
+        catalog[name] = (input = {}, init) => problem({ ...input, type, status: entry.status, title: entry.title }, init);
+    }
+    catalog.parse = async (response) => {
+        let parsed = await parseProblem(response);
+        if (parsed.status === "failure")
+            return parsed;
+        let name = names.get(parsed.data.type) ?? null;
+        if (name === null)
+            return success({ ...parsed.data, name });
+        let extensions = readExtensions(parsed.data.extensions, entries[name]?.extensions);
+        if (extensions.status === "failure")
+            return failure(extensions.error);
+        return success({ ...parsed.data, extensions: extensions.data, name });
+    };
+    catalog.is = (parsed, name) => parsed.name === name;
+    catalog.entries = () => listing.map((entry) => ({ ...entry }));
+    return catalog;
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Public surface of the problem details package: writing and reading RFC 9457
+ * `application/problem+json` documents, validation failures as problems, and
+ * catalogs that declare an API's problem types once.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export type { BuilderInput, CatalogEntry, CatalogMethods, CatalogProblem, ProblemBuilder, ProblemCatalog, ProblemEntries, ProblemEntry, } from "./catalog.js";
+export type { ParseOptions } from "./parse.js";
+export type { Problem, ProblemIssue, ProblemOptions } from "./types.js";
+export { defineProblems } from "./catalog.js";
+export { ISSUES_SCHEMA, issuesFrom, toPointer, validationProblem } from "./issues.js";
+export { isProblem, parse, parseProblem, ProblemParseError } from "./parse.js";
+export { ABOUT_BLANK, PROBLEM_MEDIA_TYPE, problem, stringify } from "./problem.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * Public surface of the problem details package: writing and reading RFC 9457
+ * `application/problem+json` documents, validation failures as problems, and
+ * catalogs that declare an API's problem types once.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export { defineProblems } from "./catalog.js";
+export { ISSUES_SCHEMA, issuesFrom, toPointer, validationProblem } from "./issues.js";
+export { isProblem, parse, parseProblem, ProblemParseError } from "./parse.js";
+export { ABOUT_BLANK, PROBLEM_MEDIA_TYPE, problem, stringify } from "./problem.js";

package/dist/issues.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Validation failures as problems: converting Standard Schema issues into the
+ * `errors` extension's JSON Pointer entries, the schema that reads them back,
+ * and the 422 response that carries them.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import * as s from "remix/data-schema";
+import type { ProblemIssue, ProblemOptions } from "./types.js";
+/**
+ * Formats a Standard Schema issue path as an RFC 6901 JSON Pointer, escaping `~` as `~0`
+ * and `/` as `~1`. An empty or absent path points at the whole document, `""`.
+ *
+ * @param path - The issue's path segments.
+ * @example toPointer(["users", 0, "a/b"]); // "/users/0/a~1b"
+ */
+export declare function toPointer(path: StandardSchemaV1.Issue["path"]): string;
+/**
+ * Converts Standard Schema issues into `errors` entries. Standard Schema issues carry no
+ * code of their own, so every entry gets `code`.
+ *
+ * @param source - The issues, or anything carrying them, such as a validation error.
+ * @param code - The code each entry reports.
+ * @default code "invalid"
+ * @example issuesFrom(parseSafe(schema, input).issues);
+ */
+export declare function issuesFrom(source: readonly StandardSchemaV1.Issue[] | {
+    issues: readonly StandardSchemaV1.Issue[];
+}, code?: string): ProblemIssue[];
+/**
+ * Builds the response for a request that failed validation, `422` unless `options` says
+ * otherwise, listing each invalid field in the `errors` extension.
+ *
+ * @param issues - One entry per invalid field.
+ * @param options - Any standard member to set; `status` defaults to `422`.
+ * @example return validationProblem(issuesFrom(result.issues));
+ */
+export declare function validationProblem(issues: ProblemIssue[], options?: Partial<Omit<ProblemOptions, "extensions">>): Response;
+/**
+ * The schema for the `errors` extension, for composing into an extension schema such as
+ * `s.object({ errors: ISSUES_SCHEMA })`.
+ */
+export declare const ISSUES_SCHEMA: s.Schema<unknown, ProblemIssue[]>;

package/dist/issues.js

@@ -0,0 +1,46 @@
+import * as s from "remix/data-schema";
+import { problem } from "./problem.js";
+/**
+ * Formats a Standard Schema issue path as an RFC 6901 JSON Pointer, escaping `~` as `~0`
+ * and `/` as `~1`. An empty or absent path points at the whole document, `""`.
+ *
+ * @param path - The issue's path segments.
+ * @example toPointer(["users", 0, "a/b"]); // "/users/0/a~1b"
+ */
+export function toPointer(path) {
+    let pointer = "";
+    for (let segment of path ?? []) {
+        let key = typeof segment === "object" ? segment.key : segment;
+        pointer += `/${String(key).replaceAll("~", "~0").replaceAll("/", "~1")}`;
+    }
+    return pointer;
+}
+/**
+ * Converts Standard Schema issues into `errors` entries. Standard Schema issues carry no
+ * code of their own, so every entry gets `code`.
+ *
+ * @param source - The issues, or anything carrying them, such as a validation error.
+ * @param code - The code each entry reports.
+ * @default code "invalid"
+ * @example issuesFrom(parseSafe(schema, input).issues);
+ */
+export function issuesFrom(source, code = "invalid") {
+    let issues = "issues" in source ? source.issues : source;
+    return issues.map((issue) => ({ pointer: toPointer(issue.path), code, message: issue.message }));
+}
+/**
+ * Builds the response for a request that failed validation, `422` unless `options` says
+ * otherwise, listing each invalid field in the `errors` extension.
+ *
+ * @param issues - One entry per invalid field.
+ * @param options - Any standard member to set; `status` defaults to `422`.
+ * @example return validationProblem(issuesFrom(result.issues));
+ */
+export function validationProblem(issues, options = {}) {
+    return problem({ status: 422, ...options, extensions: { errors: issues } });
+}
+/**
+ * The schema for the `errors` extension, for composing into an extension schema such as
+ * `s.object({ errors: ISSUES_SCHEMA })`.
+ */
+export const ISSUES_SCHEMA = s.array(s.object({ pointer: s.string(), code: s.string(), message: s.string() }));

package/dist/parse.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Reads problem documents: detecting one by its media type, and decoding its JSON
+ * into a `Problem` with RFC 9457's defaults resolved and the extension members
+ * optionally validated by a Standard Schema.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { Problem } from "./types.js";
+/** Why a document could not be read as a problem, with the schema's issues when extensions failed validation. */
+export declare class ProblemParseError extends Error {
+    name: string;
+    readonly issues: readonly StandardSchemaV1.Issue[];
+    /**
+     * @param message - What made the document unreadable.
+     * @param issues - The extension schema's issues, empty for any other failure.
+     */
+    constructor(message: string, issues?: readonly StandardSchemaV1.Issue[]);
+}
+/** How to read a problem document. */
+export interface ParseOptions<Extensions extends object> {
+    /** Validates the extension members; without one they are kept as an unchecked record. */
+    extensions?: StandardSchemaV1<unknown, Extensions>;
+    /** The status line's code, which takes precedence over the body's advisory `status`. */
+    status?: number;
+}
+/**
+ * Whether a request or response declares the problem media type. Only the media type
+ * essence is compared, case-insensitively, so parameters like `charset` are accepted;
+ * the body is left unread.
+ *
+ * @param message - A `Request` or `Response`.
+ */
+export declare function isProblem(message: {
+    headers: Headers;
+}): boolean;
+/**
+ * Decodes a problem document's JSON text. Absent members take their RFC defaults; a body
+ * that is not a JSON object, a standard member of the wrong type, a missing status, or
+ * extensions the schema rejects is a failure. A schema must validate synchronously.
+ *
+ * @param text - The document's JSON text.
+ * @param options - The extension schema and the status line's code.
+ * @returns The problem, or why the text is not one.
+ * @template Extensions - The extension members the schema produces.
+ */
+export declare function parse<Extensions extends object = Record<string, unknown>>(text: string, options?: ParseOptions<Extensions>): Result<Problem<Extensions>, ProblemParseError>;
+/**
+ * Reads a problem `Response`, whose status line wins over the body's `status`. A response
+ * that does not declare the problem media type, or whose body cannot be read, is a failure.
+ *
+ * @param response - The response, with its body unread.
+ * @param options - The extension schema.
+ * @returns The problem, or why the response does not carry one.
+ * @template Extensions - The extension members the schema produces.
+ */
+export declare function parseProblem<Extensions extends object = Record<string, unknown>>(response: Response, options?: Omit<ParseOptions<Extensions>, "status">): Promise<Result<Problem<Extensions>, ProblemParseError>>;
+/**
+ * Collects the non-standard members and, when a schema is given, validates them.
+ *
+ * @param body - The decoded document.
+ * @param schema - The extension schema, if any.
+ */
+export declare function readExtensions<Extensions extends object>(body: Record<string, unknown>, schema: StandardSchemaV1<unknown, Extensions> | undefined): Result<Extensions, ProblemParseError>;

package/dist/parse.js

@@ -0,0 +1,119 @@
+import { failure, success } from "@sdxc/result";
+import { ABOUT_BLANK, PROBLEM_MEDIA_TYPE } from "./problem.js";
+import { statusPhrase } from "./status-phrase.js";
+/** Why a document could not be read as a problem, with the schema's issues when extensions failed validation. */
+export class ProblemParseError extends Error {
+    name = "ProblemParseError";
+    issues;
+    /**
+     * @param message - What made the document unreadable.
+     * @param issues - The extension schema's issues, empty for any other failure.
+     */
+    constructor(message, issues = []) {
+        super(message);
+        this.issues = issues;
+    }
+}
+/** The members RFC 9457 defines, which never appear among a parsed problem's extensions. */
+const STANDARD_MEMBERS = new Set(["type", "title", "status", "detail", "instance"]);
+/**
+ * Whether a request or response declares the problem media type. Only the media type
+ * essence is compared, case-insensitively, so parameters like `charset` are accepted;
+ * the body is left unread.
+ *
+ * @param message - A `Request` or `Response`.
+ */
+export function isProblem(message) {
+    let declared = message.headers.get("Content-Type");
+    if (declared === null)
+        return false;
+    return declared.split(";")[0]?.trim().toLowerCase() === PROBLEM_MEDIA_TYPE;
+}
+/**
+ * Decodes a problem document's JSON text. Absent members take their RFC defaults; a body
+ * that is not a JSON object, a standard member of the wrong type, a missing status, or
+ * extensions the schema rejects is a failure. A schema must validate synchronously.
+ *
+ * @param text - The document's JSON text.
+ * @param options - The extension schema and the status line's code.
+ * @returns The problem, or why the text is not one.
+ * @template Extensions - The extension members the schema produces.
+ */
+export function parse(text, options = {}) {
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        return failure(new ProblemParseError("The problem document is not valid JSON."));
+    }
+    if (typeof json !== "object" || json === null || Array.isArray(json)) {
+        return failure(new ProblemParseError("The problem document is not a JSON object."));
+    }
+    let body = json;
+    let status = options.status ?? body.status;
+    if (!Number.isInteger(status)) {
+        return failure(new ProblemParseError("The problem document has no integer status."));
+    }
+    for (let member of ["type", "title", "detail", "instance"]) {
+        if (body[member] !== undefined && typeof body[member] !== "string") {
+            return failure(new ProblemParseError(`The problem member "${member}" is not a string.`));
+        }
+    }
+    let extensions = readExtensions(body, options.extensions);
+    if (extensions.status === "failure")
+        return extensions;
+    return success({
+        type: body.type ?? ABOUT_BLANK,
+        title: body.title ?? statusPhrase(status),
+        status: status,
+        detail: body.detail ?? null,
+        instance: body.instance ?? null,
+        extensions: extensions.data,
+    });
+}
+/**
+ * Reads a problem `Response`, whose status line wins over the body's `status`. A response
+ * that does not declare the problem media type, or whose body cannot be read, is a failure.
+ *
+ * @param response - The response, with its body unread.
+ * @param options - The extension schema.
+ * @returns The problem, or why the response does not carry one.
+ * @template Extensions - The extension members the schema produces.
+ */
+export async function parseProblem(response, options = {}) {
+    if (!isProblem(response)) {
+        return failure(new ProblemParseError(`The response is not ${PROBLEM_MEDIA_TYPE}.`));
+    }
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch {
+        return failure(new ProblemParseError("The response body could not be read."));
+    }
+    return parse(text, { ...options, status: response.status });
+}
+/**
+ * Collects the non-standard members and, when a schema is given, validates them.
+ *
+ * @param body - The decoded document.
+ * @param schema - The extension schema, if any.
+ */
+export function readExtensions(body, schema) {
+    let members = {};
+    for (let [key, value] of Object.entries(body)) {
+        if (!STANDARD_MEMBERS.has(key))
+            members[key] = value;
+    }
+    if (schema === undefined)
+        return success(members);
+    let result = schema["~standard"].validate(members);
+    if (result instanceof Promise) {
+        return failure(new ProblemParseError("The extension schema must validate synchronously."));
+    }
+    if (result.issues !== undefined) {
+        return failure(new ProblemParseError("The problem's extensions failed validation.", result.issues));
+    }
+    return success(result.value);
+}

package/dist/problem.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Writes problem documents: the JSON text and the `Response` that carries it,
+ * with RFC 9457's defaults applied so a status alone produces a valid document.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { ProblemOptions } from "./types.js";
+/** The registered media type of an RFC 9457 JSON problem document. */
+export declare const PROBLEM_MEDIA_TYPE = "application/problem+json";
+/** The `type` of a problem whose status code alone describes it. */
+export declare const ABOUT_BLANK = "about:blank";
+/**
+ * Serializes a problem to its JSON text. Extension members are written first and the
+ * standard members after them, so an extension named like a standard member never
+ * replaces it; `null` or omitted `detail` and `instance` are left out.
+ *
+ * @param options - The problem to write; a parsed `Problem` is accepted as-is.
+ * @returns The document's JSON text.
+ * @example stringify({ status: 404 }); // '{"type":"about:blank","title":"Not Found","status":404}'
+ */
+export declare function stringify(options: ProblemOptions<object>): string;
+/**
+ * Builds the `Response` for a problem, with the status line and the body's `status`
+ * set from the same value and `Content-Type` declaring the problem media type.
+ *
+ * @param options - The problem to answer with.
+ * @param init - Extra headers, such as `Retry-After`, merged under the content type.
+ * @returns A response ready to return from a handler.
+ * @example return problem({ status: 404 });
+ * @example return problem({ status: 429, detail: "Try again in a minute." }, { headers: { "Retry-After": "60" } });
+ */
+export declare function problem(options: ProblemOptions<object>, init?: ResponseInit): Response;

package/dist/problem.js

@@ -0,0 +1,46 @@
+import { statusPhrase } from "./status-phrase.js";
+/** The registered media type of an RFC 9457 JSON problem document. */
+export const PROBLEM_MEDIA_TYPE = "application/problem+json";
+/** The `type` of a problem whose status code alone describes it. */
+export const ABOUT_BLANK = "about:blank";
+/**
+ * Serializes a problem to its JSON text. Extension members are written first and the
+ * standard members after them, so an extension named like a standard member never
+ * replaces it; `null` or omitted `detail` and `instance` are left out.
+ *
+ * @param options - The problem to write; a parsed `Problem` is accepted as-is.
+ * @returns The document's JSON text.
+ * @example stringify({ status: 404 }); // '{"type":"about:blank","title":"Not Found","status":404}'
+ */
+export function stringify(options) {
+    let body = {
+        ...options.extensions,
+        type: options.type ?? ABOUT_BLANK,
+        title: options.title ?? statusPhrase(options.status),
+        status: options.status,
+    };
+    if (options.detail != null)
+        body.detail = options.detail;
+    else
+        delete body.detail;
+    if (options.instance != null)
+        body.instance = options.instance;
+    else
+        delete body.instance;
+    return JSON.stringify(body);
+}
+/**
+ * Builds the `Response` for a problem, with the status line and the body's `status`
+ * set from the same value and `Content-Type` declaring the problem media type.
+ *
+ * @param options - The problem to answer with.
+ * @param init - Extra headers, such as `Retry-After`, merged under the content type.
+ * @returns A response ready to return from a handler.
+ * @example return problem({ status: 404 });
+ * @example return problem({ status: 429, detail: "Try again in a minute." }, { headers: { "Retry-After": "60" } });
+ */
+export function problem(options, init) {
+    let headers = new Headers(init?.headers);
+    headers.set("Content-Type", PROBLEM_MEDIA_TYPE);
+    return new Response(stringify(options), { ...init, status: options.status, headers });
+}

package/dist/status-phrase.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The reason phrase for each HTTP error status, which RFC 9457 makes the `title`
+ * of an `about:blank` problem, so a status alone produces a complete document.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * The reason phrase for `status`, or `"Unknown Status"` for a code the registry
+ * leaves unnamed, so every problem carries a title.
+ *
+ * @param status - The HTTP status code.
+ * @returns The phrase to use as the problem's `title`.
+ */
+export declare function statusPhrase(status: number): string;

package/dist/status-phrase.js

@@ -0,0 +1,58 @@
+/**
+ * The reason phrase for each HTTP error status, which RFC 9457 makes the `title`
+ * of an `about:blank` problem, so a status alone produces a complete document.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** The registered phrase for every 4xx and 5xx status in the IANA HTTP status registry. */
+const STATUS_PHRASES = {
+    400: "Bad Request",
+    401: "Unauthorized",
+    402: "Payment Required",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    406: "Not Acceptable",
+    407: "Proxy Authentication Required",
+    408: "Request Timeout",
+    409: "Conflict",
+    410: "Gone",
+    411: "Length Required",
+    412: "Precondition Failed",
+    413: "Content Too Large",
+    414: "URI Too Long",
+    415: "Unsupported Media Type",
+    416: "Range Not Satisfiable",
+    417: "Expectation Failed",
+    421: "Misdirected Request",
+    422: "Unprocessable Content",
+    423: "Locked",
+    424: "Failed Dependency",
+    425: "Too Early",
+    426: "Upgrade Required",
+    428: "Precondition Required",
+    429: "Too Many Requests",
+    431: "Request Header Fields Too Large",
+    451: "Unavailable For Legal Reasons",
+    500: "Internal Server Error",
+    501: "Not Implemented",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+    505: "HTTP Version Not Supported",
+    506: "Variant Also Negotiates",
+    507: "Insufficient Storage",
+    508: "Loop Detected",
+    511: "Network Authentication Required",
+};
+/**
+ * The reason phrase for `status`, or `"Unknown Status"` for a code the registry
+ * leaves unnamed, so every problem carries a title.
+ *
+ * @param status - The HTTP status code.
+ * @returns The phrase to use as the problem's `title`.
+ */
+export function statusPhrase(status) {
+    return STATUS_PHRASES[status] ?? "Unknown Status";
+}

package/dist/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The shapes of an RFC 9457 problem document: the parsed form a reader receives,
+ * the options a writer passes, and the field-level issue a validation failure lists.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * A problem document as read, with every standard member resolved: `type` and `title`
+ * carry their RFC defaults when the document omits them, and the extension members sit
+ * under `extensions` so none of them can shadow a standard one.
+ *
+ * @template Extensions - The extension members, as a schema validated them.
+ */
+export interface Problem<Extensions extends object = Record<string, unknown>> {
+    /** The URI a client branches on; `"about:blank"` means the status alone describes it. */
+    type: string;
+    title: string;
+    status: number;
+    detail: string | null;
+    /** Identifies this occurrence, for a caller to quote back in a support request. */
+    instance: string | null;
+    extensions: Extensions;
+}
+/**
+ * What a writer passes to describe a problem. Only `status` is required: an omitted
+ * `type` writes `"about:blank"`, and an omitted `title` writes the status phrase.
+ *
+ * @template Extensions - The extension members written at the document's top level.
+ */
+export interface ProblemOptions<Extensions extends object = Record<string, unknown>> {
+    status: number;
+    type?: string;
+    title?: string;
+    detail?: string | null;
+    instance?: string | null;
+    extensions?: Extensions;
+}
+/** One invalid field, the entry shape of a validation failure's `errors` extension. */
+export interface ProblemIssue {
+    /** An RFC 6901 JSON Pointer into the request body; `""` names the body itself. */
+    pointer: string;
+    /** A stable code for a caller branching without reading `message`. */
+    code: string;
+    message: string;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * The shapes of an RFC 9457 problem document: the parsed form a reader receives,
+ * the options a writer passes, and the field-level issue a validation failure lists.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */

package/package.json

@@ -0,0 +1,24 @@
+{
+	"name": "@sdxc/problem",
+	"version": "0.0.0-pre.1",
+	"description": "Build, detect and parse RFC 9457 problem details, and declare an API's problem types in one catalog",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": "./dist/index.js"
+	},
+	"dependencies": {
+		"@sdxc/result": "2026.9.15",
+		"@standard-schema/spec": "^1.1.0",
+		"remix": "3.0.0-rc.2"
+	},
+	"gitHead": "a076dfaede8ecdd39ba3c2bb08b9239031540b67",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sergiodxa/monorepo.git",
+		"directory": "packages/problem"
+	}
+}