@yedoma-labs/ysuly-problem 0.0.0-stage → 1.0.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,161 @@
-# Temporary Holding Version
+# @yedoma-labs/ysuly-problem
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Type-safe [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) Problem Details for TypeScript, with a mapping from arbitrary thrown errors that never leaks internals. Zero runtime dependencies. Uses only Web-standard APIs (`Response`, `Headers`, `JSON`), so it runs on Node 20+, Bun, Deno and edge runtimes.
+
+## The problem
+
+API error responses are inconsistent. One endpoint returns plain text, another `{ error: "..." }`, a third `{ message, stack }`. The last shape is the dangerous one: stack traces, internal file paths and SQL error messages end up in the browser.
+
+RFC 9457 (which obsoletes RFC 7807) defines a standard shape for error responses: `application/problem+json` with `type`, `title`, `status`, `detail` and `instance`. This library gives you:
+
+- **Builders** that validate and sanitize problem documents.
+- **A safe mapping** from any thrown value to a problem. Unknown errors become a generic 500. Nothing from the error object is copied unless you explicitly allow it.
+- **Framework-free helpers.** `toResponse` returns a standard `Response`. There are no imports from Express, Hono, Fastify or similar. Adapters are one-line functions you write yourself (see below).
+- **Client helpers** to recognize and parse problem responses.
+
+## Install
+
+```sh
+pnpm add @yedoma-labs/ysuly-problem
+```
+
+## Quickstart
+
+```ts
+import { defineProblems, fromError, problem, toResponse } from "@yedoma-labs/ysuly-problem";
+
+// A problem you construct yourself
+const notEnough = problem({
+	type: "https://example.com/problems/insufficient-funds",
+	title: "Insufficient funds",
+	status: 422,
+	detail: "The account balance is lower than the requested amount.",
+	instance: "/transfers/97",
+	extensions: { balance: 30, requested: 50 },
+});
+
+// Known errors, mapped by their `code` property
+const problems = defineProblems({
+	NOT_FOUND: {
+		type: "https://example.com/problems/not-found",
+		title: "Not found",
+		status: 404,
+		detail: "The requested resource does not exist.",
+	},
+});
+
+// Any thrown value: `error.message` and `error.stack` are never copied by default
+export async function handle(request: Request): Promise<Response> {
+	try {
+		return await route(request); // your routing
+	} catch (error) {
+		return toResponse(
+			fromError(error, {
+				registry: problems,
+				instanceFromRequestId: request.headers.get("x-request-id") ?? undefined,
+			}),
+		);
+	}
+}
+```
+
+`toResponse` returns a `Response` with `Content-Type: application/problem+json; charset=utf-8` and a JSON body.
+
+## Framework adapters
+
+The library has no framework imports. An adapter is a few lines in your own code. For Express, inside an error middleware `(err, req, res, next)`:
+
+```ts
+const p = fromError(err, { registry: problems });
+res.status(p.status).type("application/problem+json").json(p);
+```
+
+For Web-standard runtimes, `toResponse` is the adapter.
+
+## API
+
+### `problem(input)`
+
+Builds a validated `ProblemDetails`. Invalid input throws a `ProblemError` with `code === "INVALID_PROBLEM"` and an `issues` array.
+
+- `status`: integer from 100 to 599 (required).
+- `title`: required, sanitized, at most 200 characters.
+- `type`: URI reference, defaults to `"about:blank"`.
+- `detail`: optional, sanitized, at most 1000 characters.
+- `instance`: optional URI reference.
+- `extensions`: optional object. Keys `type`, `title`, `status`, `detail` and `instance` are rejected. Values must be JSON-serializable. Extensions are flattened into the output.
+
+Text fields lose control characters, line breaks and tabs become single spaces, and over-long text is cut at a code point boundary with an ellipsis.
+
+### `toResponse(problem, { headers? })`
+
+Returns a `Response`. The problem is validated and sanitized again. Custom headers are merged, but `Content-Type` is always the problem media type. Statuses that cannot carry a body (1xx, 204, 205, 304) throw `ProblemError`.
+
+### `fromError(error, options?)`
+
+Maps any value to a `ProblemDetails`. Options:
+
+- `registry`: a `defineProblems` result, or a `Map` whose string keys match `error.code` and whose class keys match with `instanceof`. The first matching entry wins.
+- `expose(error) => boolean`: opt-in for unknown errors. Only when this returns `true` is `error.message` copied into `detail`, sanitized and truncated.
+- `fallback`: template for unknown errors. Default: `{ status: 500, title: "Internal Server Error" }`.
+- `instanceFromRequestId`: sets `instance` to `urn:request:<id>`.
+
+### `defineProblems(templates, { by? })`
+
+Defines named problem templates and validates them immediately. Each key is matched against `error.code` (default), against the error's constructor name (`by: "className"`), or against either (`by: "both"`). Matching never looks at `message`.
+
+### `isProblemDetails(value)`
+
+Type guard. `title` must be a non-empty string, `status` an integer from 100 to 599, and the optional members must have the right types.
+
+### `parseProblem(response)`
+
+Returns `Promise<ProblemDetails | undefined>`. It returns a problem only if the media type is `application/problem+json` or `application/json` and the body is a valid problem. Bodies over 64 KiB, malformed JSON and read errors return `undefined`. The function never throws. It consumes the response body, so call `response.clone()` first if you need the body later.
+
+```ts
+const response = await fetch("/api/transfers/97", { method: "POST", body });
+if (!response.ok) {
+	const problem = await parseProblem(response);
+	console.error(problem?.title ?? response.statusText);
+}
+```
+
+## Security rules
+
+1. **Unknown errors are opaque.** Without a registry match and without `expose`, the response contains only the fallback status and title. No `message`, `stack`, `cause`, `name` or file paths.
+2. **Registry matches use only the template.** The title, status, type and detail come from the template. `error.message` is never used for a matched error, even with `expose`.
+3. **Exposure is an explicit opt-in per error.** Only `expose(error) === true` copies a message, and it is sanitized and truncated first.
+4. **Matching is explicit.** Registry keys are matched against `code` or the constructor name, never against the message text.
+5. **Errors from `problem()` carry no input values.** `ProblemError.message` lists the problems, not the offending data.
+6. **Reserved members cannot be overridden through extensions.** `__proto__` is rejected as well.
+7. **Client parsing is bounded.** `parseProblem` reads at most 64 KiB and never throws.
+
+Limits of the library: it cannot tell which messages are sensitive. If you pass `expose: () => true`, every message reaches the client, so do that only for error types you have reviewed. Extensions are sent exactly as you give them. Do not put secrets in them.
+
+## Comparison with http-problem-details
+
+[`http-problem-details`](https://www.npmjs.com/package/http-problem-details) is an existing small package for the same standard. This library is intentionally slimmer and its main difference is the default error mapping:
+
+- Unknown errors become a generic 500 by default. Messages are copied only after an explicit `expose` decision.
+- Registry templates are validated when they are defined. Matching is explicit (`code`, class name, or both), never by message text.
+- Only Web-standard APIs are used, with zero runtime dependencies.
+
+I have not audited the full feature set of `http-problem-details` for this comparison. Check its API against your needs before choosing one.
+
+## Runtime support
+
+Node 20 and newer, Bun, Deno and edge runtimes that provide `Response`, `Headers`, `ReadableStream` and `TextDecoder`.
+
+## Development
+
+```sh
+pnpm install
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,351 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+// src/sanitize.ts
+const WHITESPACE_RUNS = /\s+/g;
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/g;
+/**
+* Makes free text safe for a human-readable problem field: every whitespace run
+* (tabs, line breaks, Unicode line separators) becomes one space, other control
+* characters are removed, surrounding whitespace is trimmed and the result is
+* cut to `maxLength` code points.
+*/
+function sanitizeText(value, maxLength) {
+	return truncate(value.replace(WHITESPACE_RUNS, " ").replace(CONTROL_CHARS, "").trim(), maxLength);
+}
+/** Cuts a string to at most `maxLength` code points, ending with an ellipsis if cut. */
+function truncate(value, maxLength) {
+	if (value.length <= maxLength) return value;
+	const chars = Array.from(value);
+	if (chars.length <= maxLength) return value;
+	return `${chars.slice(0, maxLength - 1).join("")}…`;
+}
+// src/problem.ts
+/** Content-Type for RFC 9457 problem documents. */
+const PROBLEM_CONTENT_TYPE = "application/problem+json; charset=utf-8";
+/** Default problem `type` as defined by RFC 9457. */
+const DEFAULT_PROBLEM_TYPE = "about:blank";
+const TITLE_MAX_LENGTH = 200;
+const DETAIL_MAX_LENGTH = 1e3;
+const URI_MAX_LENGTH = 2048;
+/** Members defined by RFC 9457. They may not be used as extension keys. */
+const RESERVED_MEMBERS = /* @__PURE__ */ new Set([
+	"type",
+	"title",
+	"status",
+	"detail",
+	"instance"
+]);
+/** Thrown when problem details cannot be built or are invalid. Carries no input values. */
+var ProblemError = class extends Error {
+	code = "INVALID_PROBLEM";
+	issues;
+	constructor(issues) {
+		super(`Invalid problem details: ${issues.join("; ")}`);
+		this.name = "ProblemError";
+		this.issues = issues;
+	}
+};
+/**
+* Builds a validated problem document. Text fields are sanitized and length
+* limited; invalid input throws a `ProblemError` with code `INVALID_PROBLEM`.
+*/
+function problem(input) {
+	return normalizeProblem(input);
+}
+/** @internal Validates and normalizes a problem input. Shared by all helpers. */
+function normalizeProblem(input) {
+	const issues = [];
+	if (!isValidStatus(input.status)) issues.push("status must be an integer between 100 and 599");
+	const title = typeof input.title === "string" ? sanitizeText(input.title, 200) : "";
+	if (title === "") issues.push("title must be a non-empty string");
+	const type = input.type === void 0 ? DEFAULT_PROBLEM_TYPE : uriReference("type", input.type, issues);
+	const instance = input.instance === void 0 ? void 0 : uriReference("instance", input.instance, issues);
+	const detail = optionalText("detail", input.detail, DETAIL_MAX_LENGTH, issues);
+	const extensions = {};
+	if (input.extensions !== void 0) {
+		if (!isRecord(input.extensions)) issues.push("extensions must be a plain object");
+		else for (const [key, value] of Object.entries(input.extensions)) if (RESERVED_MEMBERS.has(key)) issues.push(`extension key "${key}" collides with a reserved problem member`);
+		else if (key === "__proto__") issues.push("extension key \"__proto__\" is not allowed");
+		else if (!isJsonSerializable(value)) issues.push(`extension "${key}" must be JSON-serializable`);
+		else extensions[key] = value;
+	}
+	if (issues.length > 0) throw new ProblemError(issues);
+	const result = {
+		type,
+		title,
+		status: input.status
+	};
+	if (detail !== void 0) result.detail = detail;
+	if (instance !== void 0) result.instance = instance;
+	for (const [key, value] of Object.entries(extensions)) result[key] = value;
+	return result;
+}
+/** @internal */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** @internal */
+function isValidStatus(value) {
+	return typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 599;
+}
+const URI_REFERENCE_FORBIDDEN = /[\s\u0000-\u001f\u007f]/;
+function uriReference(name, value, issues) {
+	if (typeof value !== "string" || value.length === 0 || value.length > URI_MAX_LENGTH || URI_REFERENCE_FORBIDDEN.test(value)) {
+		issues.push(`${name} must be a non-empty URI reference without whitespace or control characters (max ${URI_MAX_LENGTH} characters)`);
+		return "";
+	}
+	return value;
+}
+function optionalText(name, value, maxLength, issues) {
+	if (value === void 0) return;
+	if (typeof value !== "string") {
+		issues.push(`${name} must be a string`);
+		return;
+	}
+	const text = sanitizeText(value, maxLength);
+	return text === "" ? void 0 : text;
+}
+function isJsonSerializable(value) {
+	try {
+		return JSON.stringify(value) !== void 0;
+	} catch {
+		return false;
+	}
+}
+// src/client.ts
+/** Largest problem body that `parseProblem` will read. */
+const PARSE_MAX_BYTES = 65536;
+/**
+* Type guard for problem documents: `title` is a non-empty string, `status` is
+* an integer between 100 and 599, and `type`, `detail`, `instance` are strings
+* when present. Extension members are not inspected.
+*/
+function isProblemDetails(value) {
+	if (!isRecord(value)) return false;
+	const { type, title, status, detail, instance } = value;
+	return typeof title === "string" && title.length > 0 && isValidStatus(status) && (type === void 0 || typeof type === "string") && (detail === void 0 || typeof detail === "string") && (instance === void 0 || typeof instance === "string");
+}
+/**
+* Reads a problem document from a `Response`. Returns `undefined` unless the
+* media type is `application/problem+json` or `application/json` and the body is
+* a valid problem. Bodies over 64 KiB, malformed JSON and read errors also
+* yield `undefined`; this function never throws.
+*
+* The response body is consumed. Call `response.clone()` first if it is needed later.
+*/
+async function parseProblem(response) {
+	try {
+		const mediaType = response.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase();
+		if (mediaType !== "application/problem+json" && mediaType !== "application/json") return;
+		const declared = Number(response.headers.get("content-length"));
+		if (Number.isFinite(declared) && declared > PARSE_MAX_BYTES) {
+			await response.body?.cancel();
+			return;
+		}
+		const bytes = await readLimited(response.body, PARSE_MAX_BYTES);
+		if (bytes === void 0) return;
+		const parsed = JSON.parse(new TextDecoder().decode(bytes));
+		return isProblemDetails(parsed) ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
+/** Reads a stream up to `limit` bytes. Resolves to `undefined` if the limit is exceeded. */
+async function readLimited(body, limit) {
+	if (body === null) return;
+	const reader = body.getReader();
+	const chunks = [];
+	let total = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		total += value.byteLength;
+		if (total > limit) {
+			await reader.cancel();
+			return;
+		}
+		chunks.push(value);
+	}
+	const bytes = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return bytes;
+}
+// src/from-error.ts
+const DEFAULT_FALLBACK = {
+	status: 500,
+	title: "Internal Server Error"
+};
+const REQUEST_ID_MAX_LENGTH = 128;
+/**
+* Maps any thrown value to a problem document without leaking internals.
+*
+* Unknown errors produce only the fallback (by default status 500 and a generic
+* title). Their `message`, `stack`, `cause` and `name` are never included unless
+* `expose(error)` returns `true`.
+*/
+function fromError(error, options = {}) {
+	const instance = instanceFor(options.instanceFromRequestId);
+	const matched = findTemplate(error, options.registry);
+	if (matched !== void 0) return normalizeProblem({
+		type: matched.type,
+		title: matched.title,
+		status: matched.status,
+		detail: matched.detail,
+		instance
+	});
+	const fallback = options.fallback ?? DEFAULT_FALLBACK;
+	const exposed = options.expose !== void 0 && isExposed(options.expose, error);
+	return normalizeProblem({
+		type: fallback.type,
+		title: fallback.title,
+		status: fallback.status,
+		detail: exposed ? messageOf(error) : fallback.detail,
+		instance
+	});
+}
+function instanceFor(requestId) {
+	if (requestId === void 0 || requestId === "") return;
+	try {
+		return `urn:request:${encodeURIComponent(truncate(requestId, REQUEST_ID_MAX_LENGTH))}`;
+	} catch {
+		return;
+	}
+}
+function findTemplate(error, registry) {
+	if (registry === void 0) return;
+	try {
+		if (isMap(registry)) {
+			for (const [matcher, template] of registry) if (typeof matcher === "string" ? readProperty(error, "code") === matcher : error instanceof matcher) return template;
+			return;
+		}
+		const { by, templates } = registry;
+		for (const [key, template] of Object.entries(templates)) {
+			const byCode = by !== "className" && readProperty(error, "code") === key;
+			const byClassName = by !== "code" && constructorName(error) === key;
+			if (byCode || byClassName) return template;
+		}
+		return;
+	} catch {
+		return;
+	}
+}
+function isMap(registry) {
+	return registry instanceof Map;
+}
+function isExposed(expose, error) {
+	try {
+		return expose(error) === true;
+	} catch {
+		return false;
+	}
+}
+function messageOf(error) {
+	try {
+		const message = readProperty(error, "message");
+		return typeof message === "string" ? message : void 0;
+	} catch {
+		return;
+	}
+}
+function constructorName(value) {
+	const ctor = readProperty(value, "constructor");
+	return typeof ctor === "function" ? ctor.name : void 0;
+}
+function readProperty(value, key) {
+	if (typeof value !== "object" && typeof value !== "function" || value === null) return;
+	return value[key];
+}
+// src/registry.ts
+const MATCH_MODES = /* @__PURE__ */ new Set([
+	"code",
+	"className",
+	"both"
+]);
+/**
+* Defines named problem templates for `fromError`. Every template is validated
+* immediately, so invalid definitions fail at startup instead of per request.
+*
+* @example
+* const problems = defineProblems({
+*   NotFound: { status: 404, title: "Not found", type: "https://example.com/problems/not-found" },
+* });
+* fromError(error, { registry: problems });
+*/
+function defineProblems(templates, options = {}) {
+	const by = options.by ?? "code";
+	const issues = [];
+	if (!MATCH_MODES.has(by)) issues.push("by must be \"code\", \"className\" or \"both\"");
+	for (const [key, template] of Object.entries(templates)) {
+		if (key === "") {
+			issues.push("template keys must be non-empty");
+			continue;
+		}
+		try {
+			normalizeProblem({
+				...template,
+				extensions: void 0
+			});
+		} catch (error) {
+			if (error instanceof ProblemError) issues.push(`${key}: ${error.issues.join("; ")}`);
+			else throw error;
+		}
+	}
+	if (issues.length > 0) throw new ProblemError(issues);
+	return Object.freeze({
+		templates: Object.freeze({ ...templates }),
+		by
+	});
+}
+// src/response.ts
+/** Statuses that cannot carry a body, or that the Response constructor rejects. */
+const BODYLESS_OR_UNSUPPORTED_STATUSES = /* @__PURE__ */ new Set([
+	101,
+	103,
+	204,
+	205,
+	304
+]);
+/**
+* Creates a Web-standard `Response` carrying the problem as
+* `application/problem+json; charset=utf-8`. The problem is validated and
+* sanitized again before it is serialized.
+*/
+function toResponse(problem, options = {}) {
+	const normalized = normalizeProblem(toProblemInput(problem));
+	if (normalized.status < 200 || BODYLESS_OR_UNSUPPORTED_STATUSES.has(normalized.status)) throw new ProblemError([`status ${normalized.status} cannot be sent with a problem body (use 200-599, except 204, 205 and 304)`]);
+	const headers = new Headers(options.headers);
+	headers.set("content-type", PROBLEM_CONTENT_TYPE);
+	return new Response(JSON.stringify(normalized), {
+		status: normalized.status,
+		headers
+	});
+}
+/** Converts the flattened wire shape into the input shape used for validation. */
+function toProblemInput(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new ProblemError(["problem must be an object"]);
+	const { type, title, status, detail, instance, ...extensions } = value;
+	return {
+		type,
+		title,
+		status,
+		detail,
+		instance,
+		extensions
+	};
+}
+exports.DEFAULT_PROBLEM_TYPE = DEFAULT_PROBLEM_TYPE;
+exports.DETAIL_MAX_LENGTH = DETAIL_MAX_LENGTH;
+exports.PROBLEM_CONTENT_TYPE = PROBLEM_CONTENT_TYPE;
+exports.ProblemError = ProblemError;
+exports.TITLE_MAX_LENGTH = TITLE_MAX_LENGTH;
+exports.defineProblems = defineProblems;
+exports.fromError = fromError;
+exports.isProblemDetails = isProblemDetails;
+exports.parseProblem = parseProblem;
+exports.problem = problem;
+exports.toResponse = toResponse;
+
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/sanitize.ts","../src/problem.ts","../src/client.ts","../src/from-error.ts","../src/registry.ts","../src/response.ts"],"sourcesContent":["const WHITESPACE_RUNS = /\\s+/g;\nconst CONTROL_CHARS = /[\\u0000-\\u001f\\u007f-\\u009f]/g;\n\n/**\n * Makes free text safe for a human-readable problem field: every whitespace run\n * (tabs, line breaks, Unicode line separators) becomes one space, other control\n * characters are removed, surrounding whitespace is trimmed and the result is\n * cut to `maxLength` code points.\n */\nexport function sanitizeText(value: string, maxLength: number): string {\n\tconst cleaned = value.replace(WHITESPACE_RUNS, \" \").replace(CONTROL_CHARS, \"\").trim();\n\treturn truncate(cleaned, maxLength);\n}\n\n/** Cuts a string to at most `maxLength` code points, ending with an ellipsis if cut. */\nexport function truncate(value: string, maxLength: number): string {\n\t// A string never has more code points than code units, so this is a cheap pre-check.\n\tif (value.length <= maxLength) {\n\t\treturn value;\n\t}\n\tconst chars = Array.from(value);\n\tif (chars.length <= maxLength) {\n\t\treturn value;\n\t}\n\treturn `${chars.slice(0, maxLength - 1).join(\"\")}…`;\n}\n","import { sanitizeText } from \"./sanitize.js\";\n\n/** Content-Type for RFC 9457 problem documents. */\nexport const PROBLEM_CONTENT_TYPE = \"application/problem+json; charset=utf-8\";\n\n/** Default problem `type` as defined by RFC 9457. */\nexport const DEFAULT_PROBLEM_TYPE = \"about:blank\";\n\nexport const TITLE_MAX_LENGTH = 200;\nexport const DETAIL_MAX_LENGTH = 1000;\nconst URI_MAX_LENGTH = 2048;\n\n/** Members defined by RFC 9457. They may not be used as extension keys. */\nexport const RESERVED_MEMBERS: ReadonlySet<string> = new Set([\n\t\"type\",\n\t\"title\",\n\t\"status\",\n\t\"detail\",\n\t\"instance\",\n]);\n\n/**\n * An RFC 9457 problem document. Extension members are flattened next to the\n * standard members, as the specification requires.\n */\nexport interface ProblemDetails {\n\ttype?: string;\n\ttitle: string;\n\tstatus: number;\n\tdetail?: string;\n\tinstance?: string;\n\t[extension: string]: unknown;\n}\n\n/**\n * Input for `problem()`. Extensions are passed separately so that they can be\n * checked against the reserved members before a document is built.\n */\nexport interface ProblemInput {\n\ttype?: string;\n\ttitle: string;\n\tstatus: number;\n\tdetail?: string;\n\tinstance?: string;\n\textensions?: Readonly<Record<string, unknown>>;\n}\n\nexport type ProblemErrorCode = \"INVALID_PROBLEM\";\n\n/** Thrown when problem details cannot be built or are invalid. Carries no input values. */\nexport class ProblemError extends Error {\n\treadonly code: ProblemErrorCode = \"INVALID_PROBLEM\";\n\treadonly issues: readonly string[];\n\n\tconstructor(issues: readonly string[]) {\n\t\tsuper(`Invalid problem details: ${issues.join(\"; \")}`);\n\t\tthis.name = \"ProblemError\";\n\t\tthis.issues = issues;\n\t}\n}\n\n/**\n * Builds a validated problem document. Text fields are sanitized and length\n * limited; invalid input throws a `ProblemError` with code `INVALID_PROBLEM`.\n */\nexport function problem(input: ProblemInput): ProblemDetails {\n\treturn normalizeProblem(input);\n}\n\n/** @internal Validates and normalizes a problem input. Shared by all helpers. */\nexport function normalizeProblem(input: ProblemInput): ProblemDetails {\n\tconst issues: string[] = [];\n\n\tif (!isValidStatus(input.status)) {\n\t\tissues.push(\"status must be an integer between 100 and 599\");\n\t}\n\n\tconst title = typeof input.title === \"string\" ? sanitizeText(input.title, TITLE_MAX_LENGTH) : \"\";\n\tif (title === \"\") {\n\t\tissues.push(\"title must be a non-empty string\");\n\t}\n\n\tconst type =\n\t\tinput.type === undefined ? DEFAULT_PROBLEM_TYPE : uriReference(\"type\", input.type, issues);\n\tconst instance =\n\t\tinput.instance === undefined ? undefined : uriReference(\"instance\", input.instance, issues);\n\tconst detail = optionalText(\"detail\", input.detail, DETAIL_MAX_LENGTH, issues);\n\n\tconst extensions: Record<string, unknown> = {};\n\tif (input.extensions !== undefined) {\n\t\tif (!isRecord(input.extensions)) {\n\t\t\tissues.push(\"extensions must be a plain object\");\n\t\t} else {\n\t\t\tfor (const [key, value] of Object.entries(input.extensions)) {\n\t\t\t\tif (RESERVED_MEMBERS.has(key)) {\n\t\t\t\t\tissues.push(`extension key \"${key}\" collides with a reserved problem member`);\n\t\t\t\t} else if (key === \"__proto__\") {\n\t\t\t\t\tissues.push('extension key \"__proto__\" is not allowed');\n\t\t\t\t} else if (!isJsonSerializable(value)) {\n\t\t\t\t\tissues.push(`extension \"${key}\" must be JSON-serializable`);\n\t\t\t\t} else {\n\t\t\t\t\textensions[key] = value;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tif (issues.length > 0) {\n\t\tthrow new ProblemError(issues);\n\t}\n\n\tconst result: ProblemDetails = { type, title, status: input.status };\n\tif (detail !== undefined) {\n\t\tresult.detail = detail;\n\t}\n\tif (instance !== undefined) {\n\t\tresult.instance = instance;\n\t}\n\tfor (const [key, value] of Object.entries(extensions)) {\n\t\tresult[key] = value;\n\t}\n\treturn result;\n}\n\n/** @internal */\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/** @internal */\nexport function isValidStatus(value: unknown): value is number {\n\treturn typeof value === \"number\" && Number.isInteger(value) && value >= 100 && value <= 599;\n}\n\nconst URI_REFERENCE_FORBIDDEN = /[\\s\\u0000-\\u001f\\u007f]/;\n\nfunction uriReference(name: string, value: unknown, issues: string[]): string {\n\tif (\n\t\ttypeof value !== \"string\" ||\n\t\tvalue.length === 0 ||\n\t\tvalue.length > URI_MAX_LENGTH ||\n\t\tURI_REFERENCE_FORBIDDEN.test(value)\n\t) {\n\t\tissues.push(\n\t\t\t`${name} must be a non-empty URI reference without whitespace or control characters (max ${URI_MAX_LENGTH} characters)`,\n\t\t);\n\t\treturn \"\";\n\t}\n\treturn value;\n}\n\nfunction optionalText(\n\tname: string,\n\tvalue: unknown,\n\tmaxLength: number,\n\tissues: string[],\n): string | undefined {\n\tif (value === undefined) {\n\t\treturn undefined;\n\t}\n\tif (typeof value !== \"string\") {\n\t\tissues.push(`${name} must be a string`);\n\t\treturn undefined;\n\t}\n\tconst text = sanitizeText(value, maxLength);\n\treturn text === \"\" ? undefined : text;\n}\n\nfunction isJsonSerializable(value: unknown): boolean {\n\ttry {\n\t\treturn JSON.stringify(value) !== undefined;\n\t} catch {\n\t\treturn false;\n\t}\n}\n","import { isRecord, isValidStatus, type ProblemDetails } from \"./problem.js\";\n\n/** Largest problem body that `parseProblem` will read. */\nconst PARSE_MAX_BYTES = 64 * 1024;\n\n/**\n * Type guard for problem documents: `title` is a non-empty string, `status` is\n * an integer between 100 and 599, and `type`, `detail`, `instance` are strings\n * when present. Extension members are not inspected.\n */\nexport function isProblemDetails(value: unknown): value is ProblemDetails {\n\tif (!isRecord(value)) {\n\t\treturn false;\n\t}\n\tconst { type, title, status, detail, instance } = value;\n\treturn (\n\t\ttypeof title === \"string\" &&\n\t\ttitle.length > 0 &&\n\t\tisValidStatus(status) &&\n\t\t(type === undefined || typeof type === \"string\") &&\n\t\t(detail === undefined || typeof detail === \"string\") &&\n\t\t(instance === undefined || typeof instance === \"string\")\n\t);\n}\n\n/**\n * Reads a problem document from a `Response`. Returns `undefined` unless the\n * media type is `application/problem+json` or `application/json` and the body is\n * a valid problem. Bodies over 64 KiB, malformed JSON and read errors also\n * yield `undefined`; this function never throws.\n *\n * The response body is consumed. Call `response.clone()` first if it is needed later.\n */\nexport async function parseProblem(response: Response): Promise<ProblemDetails | undefined> {\n\ttry {\n\t\tconst mediaType = response.headers.get(\"content-type\")?.split(\";\")[0]?.trim().toLowerCase();\n\t\tif (mediaType !== \"application/problem+json\" && mediaType !== \"application/json\") {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst declared = Number(response.headers.get(\"content-length\"));\n\t\tif (Number.isFinite(declared) && declared > PARSE_MAX_BYTES) {\n\t\t\tawait response.body?.cancel();\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst bytes = await readLimited(response.body, PARSE_MAX_BYTES);\n\t\tif (bytes === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst parsed: unknown = JSON.parse(new TextDecoder().decode(bytes));\n\t\treturn isProblemDetails(parsed) ? parsed : undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/** Reads a stream up to `limit` bytes. Resolves to `undefined` if the limit is exceeded. */\nasync function readLimited(\n\tbody: ReadableStream<Uint8Array> | null,\n\tlimit: number,\n): Promise<Uint8Array | undefined> {\n\tif (body === null) {\n\t\treturn undefined;\n\t}\n\tconst reader = body.getReader();\n\tconst chunks: Uint8Array[] = [];\n\tlet total = 0;\n\tfor (;;) {\n\t\tconst { done, value } = await reader.read();\n\t\tif (done) {\n\t\t\tbreak;\n\t\t}\n\t\ttotal += value.byteLength;\n\t\tif (total > limit) {\n\t\t\tawait reader.cancel();\n\t\t\treturn undefined;\n\t\t}\n\t\tchunks.push(value);\n\t}\n\tconst bytes = new Uint8Array(total);\n\tlet offset = 0;\n\tfor (const chunk of chunks) {\n\t\tbytes.set(chunk, offset);\n\t\toffset += chunk.byteLength;\n\t}\n\treturn bytes;\n}\n","import { normalizeProblem, type ProblemDetails } from \"./problem.js\";\nimport type { ProblemRegistry, ProblemTemplate } from \"./registry.js\";\nimport { truncate } from \"./sanitize.js\";\n\n/** A class used as a registry key in `fromError`. Matched with `instanceof`. */\nexport type ErrorClass = abstract new (...args: never[]) => unknown;\n\nexport interface FromErrorOptions {\n\t/**\n\t * Opt-in for unknown errors. Only when this returns `true` is the error\n\t * message copied into `detail` (sanitized and length limited).\n\t */\n\texpose?: (error: unknown) => boolean;\n\t/**\n\t * Known errors. A `ProblemRegistry` from `defineProblems`, or a `Map` whose\n\t * string keys match `error.code` and whose class keys match with `instanceof`.\n\t * The first matching entry wins. Matched errors never expose their message.\n\t */\n\tregistry?: ProblemRegistry | ReadonlyMap<ErrorClass | string, ProblemTemplate>;\n\t/** Template for unknown errors. Defaults to status 500 and a generic title. */\n\tfallback?: ProblemTemplate;\n\t/** Request identifier. When set, `instance` becomes `urn:request:<id>`. */\n\tinstanceFromRequestId?: string;\n}\n\nconst DEFAULT_FALLBACK: ProblemTemplate = { status: 500, title: \"Internal Server Error\" };\nconst REQUEST_ID_MAX_LENGTH = 128;\n\n/**\n * Maps any thrown value to a problem document without leaking internals.\n *\n * Unknown errors produce only the fallback (by default status 500 and a generic\n * title). Their `message`, `stack`, `cause` and `name` are never included unless\n * `expose(error)` returns `true`.\n */\nexport function fromError(error: unknown, options: FromErrorOptions = {}): ProblemDetails {\n\tconst instance = instanceFor(options.instanceFromRequestId);\n\n\tconst matched = findTemplate(error, options.registry);\n\tif (matched !== undefined) {\n\t\treturn normalizeProblem({\n\t\t\ttype: matched.type,\n\t\t\ttitle: matched.title,\n\t\t\tstatus: matched.status,\n\t\t\tdetail: matched.detail,\n\t\t\tinstance,\n\t\t});\n\t}\n\n\tconst fallback = options.fallback ?? DEFAULT_FALLBACK;\n\tconst exposed = options.expose !== undefined && isExposed(options.expose, error);\n\treturn normalizeProblem({\n\t\ttype: fallback.type,\n\t\ttitle: fallback.title,\n\t\tstatus: fallback.status,\n\t\tdetail: exposed ? messageOf(error) : fallback.detail,\n\t\tinstance,\n\t});\n}\n\nfunction instanceFor(requestId: string | undefined): string | undefined {\n\tif (requestId === undefined || requestId === \"\") {\n\t\treturn undefined;\n\t}\n\ttry {\n\t\treturn `urn:request:${encodeURIComponent(truncate(requestId, REQUEST_ID_MAX_LENGTH))}`;\n\t} catch {\n\t\t// Lone surrogates cannot be encoded; an unusable request id is dropped, not thrown.\n\t\treturn undefined;\n\t}\n}\n\nfunction findTemplate(\n\terror: unknown,\n\tregistry: FromErrorOptions[\"registry\"],\n): ProblemTemplate | undefined {\n\tif (registry === undefined) {\n\t\treturn undefined;\n\t}\n\ttry {\n\t\tif (isMap(registry)) {\n\t\t\tfor (const [matcher, template] of registry) {\n\t\t\t\tconst hit =\n\t\t\t\t\ttypeof matcher === \"string\"\n\t\t\t\t\t\t? readProperty(error, \"code\") === matcher\n\t\t\t\t\t\t: error instanceof matcher;\n\t\t\t\tif (hit) {\n\t\t\t\t\treturn template;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst { by, templates } = registry;\n\t\tfor (const [key, template] of Object.entries(templates)) {\n\t\t\tconst byCode = by !== \"className\" && readProperty(error, \"code\") === key;\n\t\t\tconst byClassName = by !== \"code\" && constructorName(error) === key;\n\t\t\tif (byCode || byClassName) {\n\t\t\t\treturn template;\n\t\t\t}\n\t\t}\n\t\treturn undefined;\n\t} catch {\n\t\t// A throwing getter or hostile matcher must not change the response shape.\n\t\treturn undefined;\n\t}\n}\n\nfunction isMap(\n\tregistry: NonNullable<FromErrorOptions[\"registry\"]>,\n): registry is ReadonlyMap<ErrorClass | string, ProblemTemplate> {\n\treturn registry instanceof Map;\n}\n\nfunction isExposed(expose: (error: unknown) => boolean, error: unknown): boolean {\n\ttry {\n\t\treturn expose(error) === true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nfunction messageOf(error: unknown): string | undefined {\n\ttry {\n\t\tconst message = readProperty(error, \"message\");\n\t\treturn typeof message === \"string\" ? message : undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nfunction constructorName(value: unknown): string | undefined {\n\tconst ctor = readProperty(value, \"constructor\");\n\treturn typeof ctor === \"function\" ? ctor.name : undefined;\n}\n\nfunction readProperty(value: unknown, key: string): unknown {\n\tif ((typeof value !== \"object\" && typeof value !== \"function\") || value === null) {\n\t\treturn undefined;\n\t}\n\treturn (value as Record<string, unknown>)[key];\n}\n","import { normalizeProblem, ProblemError } from \"./problem.js\";\n\n/** A problem definition that can be reused for errors of a known kind. */\nexport interface ProblemTemplate {\n\ttype?: string;\n\ttitle: string;\n\tstatus: number;\n\tdetail?: string;\n}\n\nexport type ProblemTemplates = Readonly<Record<string, ProblemTemplate>>;\n\n/**\n * How registry keys are matched against errors:\n * - `code`: `error.code === key` (default, survives minification)\n * - `className`: `error.constructor.name === key`\n * - `both`: either of the two\n */\nexport type MatchBy = \"code\" | \"className\" | \"both\";\n\nexport interface DefineProblemsOptions {\n\tby?: MatchBy;\n}\n\nexport interface ProblemRegistry<T extends ProblemTemplates = ProblemTemplates> {\n\treadonly templates: T;\n\treadonly by: MatchBy;\n}\n\nconst MATCH_MODES: ReadonlySet<string> = new Set([\"code\", \"className\", \"both\"]);\n\n/**\n * Defines named problem templates for `fromError`. Every template is validated\n * immediately, so invalid definitions fail at startup instead of per request.\n *\n * @example\n * const problems = defineProblems({\n *   NotFound: { status: 404, title: \"Not found\", type: \"https://example.com/problems/not-found\" },\n * });\n * fromError(error, { registry: problems });\n */\nexport function defineProblems<const T extends ProblemTemplates>(\n\ttemplates: T,\n\toptions: DefineProblemsOptions = {},\n): ProblemRegistry<T> {\n\tconst by = options.by ?? \"code\";\n\tconst issues: string[] = [];\n\n\tif (!MATCH_MODES.has(by)) {\n\t\tissues.push('by must be \"code\", \"className\" or \"both\"');\n\t}\n\n\tfor (const [key, template] of Object.entries(templates)) {\n\t\tif (key === \"\") {\n\t\t\tissues.push(\"template keys must be non-empty\");\n\t\t\tcontinue;\n\t\t}\n\t\ttry {\n\t\t\tnormalizeProblem({ ...template, extensions: undefined });\n\t\t} catch (error) {\n\t\t\tif (error instanceof ProblemError) {\n\t\t\t\tissues.push(`${key}: ${error.issues.join(\"; \")}`);\n\t\t\t} else {\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t}\n\t}\n\n\tif (issues.length > 0) {\n\t\tthrow new ProblemError(issues);\n\t}\n\n\treturn Object.freeze({ templates: Object.freeze({ ...templates }), by });\n}\n","import {\n\tnormalizeProblem,\n\tPROBLEM_CONTENT_TYPE,\n\ttype ProblemDetails,\n\tProblemError,\n\ttype ProblemInput,\n} from \"./problem.js\";\n\n/** Statuses that cannot carry a body, or that the Response constructor rejects. */\nconst BODYLESS_OR_UNSUPPORTED_STATUSES: ReadonlySet<number> = new Set([101, 103, 204, 205, 304]);\n\nexport interface ToResponseOptions {\n\t/** Extra headers. The Content-Type is always set to the problem media type. */\n\theaders?: HeadersInit;\n}\n\n/**\n * Creates a Web-standard `Response` carrying the problem as\n * `application/problem+json; charset=utf-8`. The problem is validated and\n * sanitized again before it is serialized.\n */\nexport function toResponse(problem: ProblemDetails, options: ToResponseOptions = {}): Response {\n\tconst normalized = normalizeProblem(toProblemInput(problem));\n\n\tif (normalized.status < 200 || BODYLESS_OR_UNSUPPORTED_STATUSES.has(normalized.status)) {\n\t\tthrow new ProblemError([\n\t\t\t`status ${normalized.status} cannot be sent with a problem body (use 200-599, except 204, 205 and 304)`,\n\t\t]);\n\t}\n\n\tconst headers = new Headers(options.headers);\n\theaders.set(\"content-type\", PROBLEM_CONTENT_TYPE);\n\n\treturn new Response(JSON.stringify(normalized), {\n\t\tstatus: normalized.status,\n\t\theaders,\n\t});\n}\n\n/** Converts the flattened wire shape into the input shape used for validation. */\nfunction toProblemInput(value: ProblemDetails): ProblemInput {\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n\t\tthrow new ProblemError([\"problem must be an object\"]);\n\t}\n\tconst { type, title, status, detail, instance, ...extensions } = value;\n\treturn { type, title, status, detail, instance, extensions };\n}\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -0,0 +1,129 @@
+/** Content-Type for RFC 9457 problem documents. */
+export declare const PROBLEM_CONTENT_TYPE = "application/problem+json; charset=utf-8";
+/** Default problem `type` as defined by RFC 9457. */
+export declare const DEFAULT_PROBLEM_TYPE = "about:blank";
+export declare const TITLE_MAX_LENGTH = 200;
+export declare const DETAIL_MAX_LENGTH = 1e3;
+/**
+ * An RFC 9457 problem document. Extension members are flattened next to the
+ * standard members, as the specification requires.
+ */
+interface ProblemDetails {
+  type?: string;
+  title: string;
+  status: number;
+  detail?: string;
+  instance?: string;
+  [extension: string]: unknown;
+}
+/**
+ * Input for `problem()`. Extensions are passed separately so that they can be
+ * checked against the reserved members before a document is built.
+ */
+interface ProblemInput {
+  type?: string;
+  title: string;
+  status: number;
+  detail?: string;
+  instance?: string;
+  extensions?: Readonly<Record<string, unknown>>;
+}
+type ProblemErrorCode = "INVALID_PROBLEM";
+/** Thrown when problem details cannot be built or are invalid. Carries no input values. */
+export declare class ProblemError extends Error {
+  readonly code: ProblemErrorCode;
+  readonly issues: readonly string[];
+  constructor(issues: readonly string[]);
+}
+/**
+ * Builds a validated problem document. Text fields are sanitized and length
+ * limited; invalid input throws a `ProblemError` with code `INVALID_PROBLEM`.
+ */
+export declare function problem(input: ProblemInput): ProblemDetails;
+/**
+ * Type guard for problem documents: `title` is a non-empty string, `status` is
+ * an integer between 100 and 599, and `type`, `detail`, `instance` are strings
+ * when present. Extension members are not inspected.
+ */
+export declare function isProblemDetails(value: unknown): value is ProblemDetails;
+/**
+ * Reads a problem document from a `Response`. Returns `undefined` unless the
+ * media type is `application/problem+json` or `application/json` and the body is
+ * a valid problem. Bodies over 64 KiB, malformed JSON and read errors also
+ * yield `undefined`; this function never throws.
+ *
+ * The response body is consumed. Call `response.clone()` first if it is needed later.
+ */
+export declare function parseProblem(response: Response): Promise<ProblemDetails | undefined>;
+/** A problem definition that can be reused for errors of a known kind. */
+interface ProblemTemplate {
+  type?: string;
+  title: string;
+  status: number;
+  detail?: string;
+}
+type ProblemTemplates = Readonly<Record<string, ProblemTemplate>>;
+/**
+ * How registry keys are matched against errors:
+ * - `code`: `error.code === key` (default, survives minification)
+ * - `className`: `error.constructor.name === key`
+ * - `both`: either of the two
+ */
+type MatchBy = "code" | "className" | "both";
+interface DefineProblemsOptions {
+  by?: MatchBy;
+}
+interface ProblemRegistry<T extends ProblemTemplates = ProblemTemplates> {
+  readonly templates: T;
+  readonly by: MatchBy;
+}
+/**
+ * Defines named problem templates for `fromError`. Every template is validated
+ * immediately, so invalid definitions fail at startup instead of per request.
+ *
+ * @example
+ * const problems = defineProblems({
+ *   NotFound: { status: 404, title: "Not found", type: "https://example.com/problems/not-found" },
+ * });
+ * fromError(error, { registry: problems });
+ */
+export declare function defineProblems<const T extends ProblemTemplates>(templates: T, options?: DefineProblemsOptions): ProblemRegistry<T>;
+/** A class used as a registry key in `fromError`. Matched with `instanceof`. */
+type ErrorClass = abstract new (...args: never[]) => unknown;
+interface FromErrorOptions {
+  /**
+   * Opt-in for unknown errors. Only when this returns `true` is the error
+   * message copied into `detail` (sanitized and length limited).
+   */
+  expose?: (error: unknown) => boolean;
+  /**
+   * Known errors. A `ProblemRegistry` from `defineProblems`, or a `Map` whose
+   * string keys match `error.code` and whose class keys match with `instanceof`.
+   * The first matching entry wins. Matched errors never expose their message.
+   */
+  registry?: ProblemRegistry | ReadonlyMap<ErrorClass | string, ProblemTemplate>;
+  /** Template for unknown errors. Defaults to status 500 and a generic title. */
+  fallback?: ProblemTemplate;
+  /** Request identifier. When set, `instance` becomes `urn:request:<id>`. */
+  instanceFromRequestId?: string;
+}
+/**
+ * Maps any thrown value to a problem document without leaking internals.
+ *
+ * Unknown errors produce only the fallback (by default status 500 and a generic
+ * title). Their `message`, `stack`, `cause` and `name` are never included unless
+ * `expose(error)` returns `true`.
+ */
+export declare function fromError(error: unknown, options?: FromErrorOptions): ProblemDetails;
+interface ToResponseOptions {
+  /** Extra headers. The Content-Type is always set to the problem media type. */
+  headers?: HeadersInit;
+}
+/**
+ * Creates a Web-standard `Response` carrying the problem as
+ * `application/problem+json; charset=utf-8`. The problem is validated and
+ * sanitized again before it is serialized.
+ */
+export declare function toResponse(problem: ProblemDetails, options?: ToResponseOptions): Response;
+export type { DefineProblemsOptions, ErrorClass, FromErrorOptions, MatchBy, ProblemDetails, ProblemErrorCode, ProblemInput, ProblemRegistry, ProblemTemplate, ProblemTemplates, ToResponseOptions };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+/** Content-Type for RFC 9457 problem documents. */
+export declare const PROBLEM_CONTENT_TYPE = "application/problem+json; charset=utf-8";
+/** Default problem `type` as defined by RFC 9457. */
+export declare const DEFAULT_PROBLEM_TYPE = "about:blank";
+export declare const TITLE_MAX_LENGTH = 200;
+export declare const DETAIL_MAX_LENGTH = 1e3;
+/**
+ * An RFC 9457 problem document. Extension members are flattened next to the
+ * standard members, as the specification requires.
+ */
+interface ProblemDetails {
+  type?: string;
+  title: string;
+  status: number;
+  detail?: string;
+  instance?: string;
+  [extension: string]: unknown;
+}
+/**
+ * Input for `problem()`. Extensions are passed separately so that they can be
+ * checked against the reserved members before a document is built.
+ */
+interface ProblemInput {
+  type?: string;
+  title: string;
+  status: number;
+  detail?: string;
+  instance?: string;
+  extensions?: Readonly<Record<string, unknown>>;
+}
+type ProblemErrorCode = "INVALID_PROBLEM";
+/** Thrown when problem details cannot be built or are invalid. Carries no input values. */
+export declare class ProblemError extends Error {
+  readonly code: ProblemErrorCode;
+  readonly issues: readonly string[];
+  constructor(issues: readonly string[]);
+}
+/**
+ * Builds a validated problem document. Text fields are sanitized and length
+ * limited; invalid input throws a `ProblemError` with code `INVALID_PROBLEM`.
+ */
+export declare function problem(input: ProblemInput): ProblemDetails;
+/**
+ * Type guard for problem documents: `title` is a non-empty string, `status` is
+ * an integer between 100 and 599, and `type`, `detail`, `instance` are strings
+ * when present. Extension members are not inspected.
+ */
+export declare function isProblemDetails(value: unknown): value is ProblemDetails;
+/**
+ * Reads a problem document from a `Response`. Returns `undefined` unless the
+ * media type is `application/problem+json` or `application/json` and the body is
+ * a valid problem. Bodies over 64 KiB, malformed JSON and read errors also
+ * yield `undefined`; this function never throws.
+ *
+ * The response body is consumed. Call `response.clone()` first if it is needed later.
+ */
+export declare function parseProblem(response: Response): Promise<ProblemDetails | undefined>;
+/** A problem definition that can be reused for errors of a known kind. */
+interface ProblemTemplate {
+  type?: string;
+  title: string;
+  status: number;
+  detail?: string;
+}
+type ProblemTemplates = Readonly<Record<string, ProblemTemplate>>;
+/**
+ * How registry keys are matched against errors:
+ * - `code`: `error.code === key` (default, survives minification)
+ * - `className`: `error.constructor.name === key`
+ * - `both`: either of the two
+ */
+type MatchBy = "code" | "className" | "both";
+interface DefineProblemsOptions {
+  by?: MatchBy;
+}
+interface ProblemRegistry<T extends ProblemTemplates = ProblemTemplates> {
+  readonly templates: T;
+  readonly by: MatchBy;
+}
+/**
+ * Defines named problem templates for `fromError`. Every template is validated
+ * immediately, so invalid definitions fail at startup instead of per request.
+ *
+ * @example
+ * const problems = defineProblems({
+ *   NotFound: { status: 404, title: "Not found", type: "https://example.com/problems/not-found" },
+ * });
+ * fromError(error, { registry: problems });
+ */
+export declare function defineProblems<const T extends ProblemTemplates>(templates: T, options?: DefineProblemsOptions): ProblemRegistry<T>;
+/** A class used as a registry key in `fromError`. Matched with `instanceof`. */
+type ErrorClass = abstract new (...args: never[]) => unknown;
+interface FromErrorOptions {
+  /**
+   * Opt-in for unknown errors. Only when this returns `true` is the error
+   * message copied into `detail` (sanitized and length limited).
+   */
+  expose?: (error: unknown) => boolean;
+  /**
+   * Known errors. A `ProblemRegistry` from `defineProblems`, or a `Map` whose
+   * string keys match `error.code` and whose class keys match with `instanceof`.
+   * The first matching entry wins. Matched errors never expose their message.
+   */
+  registry?: ProblemRegistry | ReadonlyMap<ErrorClass | string, ProblemTemplate>;
+  /** Template for unknown errors. Defaults to status 500 and a generic title. */
+  fallback?: ProblemTemplate;
+  /** Request identifier. When set, `instance` becomes `urn:request:<id>`. */
+  instanceFromRequestId?: string;
+}
+/**
+ * Maps any thrown value to a problem document without leaking internals.
+ *
+ * Unknown errors produce only the fallback (by default status 500 and a generic
+ * title). Their `message`, `stack`, `cause` and `name` are never included unless
+ * `expose(error)` returns `true`.
+ */
+export declare function fromError(error: unknown, options?: FromErrorOptions): ProblemDetails;
+interface ToResponseOptions {
+  /** Extra headers. The Content-Type is always set to the problem media type. */
+  headers?: HeadersInit;
+}
+/**
+ * Creates a Web-standard `Response` carrying the problem as
+ * `application/problem+json; charset=utf-8`. The problem is validated and
+ * sanitized again before it is serialized.
+ */
+export declare function toResponse(problem: ProblemDetails, options?: ToResponseOptions): Response;
+export type { DefineProblemsOptions, ErrorClass, FromErrorOptions, MatchBy, ProblemDetails, ProblemErrorCode, ProblemInput, ProblemRegistry, ProblemTemplate, ProblemTemplates, ToResponseOptions };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,340 @@
+// src/sanitize.ts
+const WHITESPACE_RUNS = /\s+/g;
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/g;
+/**
+* Makes free text safe for a human-readable problem field: every whitespace run
+* (tabs, line breaks, Unicode line separators) becomes one space, other control
+* characters are removed, surrounding whitespace is trimmed and the result is
+* cut to `maxLength` code points.
+*/
+function sanitizeText(value, maxLength) {
+	return truncate(value.replace(WHITESPACE_RUNS, " ").replace(CONTROL_CHARS, "").trim(), maxLength);
+}
+/** Cuts a string to at most `maxLength` code points, ending with an ellipsis if cut. */
+function truncate(value, maxLength) {
+	if (value.length <= maxLength) return value;
+	const chars = Array.from(value);
+	if (chars.length <= maxLength) return value;
+	return `${chars.slice(0, maxLength - 1).join("")}…`;
+}
+// src/problem.ts
+/** Content-Type for RFC 9457 problem documents. */
+const PROBLEM_CONTENT_TYPE = "application/problem+json; charset=utf-8";
+/** Default problem `type` as defined by RFC 9457. */
+const DEFAULT_PROBLEM_TYPE = "about:blank";
+const TITLE_MAX_LENGTH = 200;
+const DETAIL_MAX_LENGTH = 1e3;
+const URI_MAX_LENGTH = 2048;
+/** Members defined by RFC 9457. They may not be used as extension keys. */
+const RESERVED_MEMBERS = /* @__PURE__ */ new Set([
+	"type",
+	"title",
+	"status",
+	"detail",
+	"instance"
+]);
+/** Thrown when problem details cannot be built or are invalid. Carries no input values. */
+var ProblemError = class extends Error {
+	code = "INVALID_PROBLEM";
+	issues;
+	constructor(issues) {
+		super(`Invalid problem details: ${issues.join("; ")}`);
+		this.name = "ProblemError";
+		this.issues = issues;
+	}
+};
+/**
+* Builds a validated problem document. Text fields are sanitized and length
+* limited; invalid input throws a `ProblemError` with code `INVALID_PROBLEM`.
+*/
+function problem(input) {
+	return normalizeProblem(input);
+}
+/** @internal Validates and normalizes a problem input. Shared by all helpers. */
+function normalizeProblem(input) {
+	const issues = [];
+	if (!isValidStatus(input.status)) issues.push("status must be an integer between 100 and 599");
+	const title = typeof input.title === "string" ? sanitizeText(input.title, 200) : "";
+	if (title === "") issues.push("title must be a non-empty string");
+	const type = input.type === void 0 ? DEFAULT_PROBLEM_TYPE : uriReference("type", input.type, issues);
+	const instance = input.instance === void 0 ? void 0 : uriReference("instance", input.instance, issues);
+	const detail = optionalText("detail", input.detail, DETAIL_MAX_LENGTH, issues);
+	const extensions = {};
+	if (input.extensions !== void 0) {
+		if (!isRecord(input.extensions)) issues.push("extensions must be a plain object");
+		else for (const [key, value] of Object.entries(input.extensions)) if (RESERVED_MEMBERS.has(key)) issues.push(`extension key "${key}" collides with a reserved problem member`);
+		else if (key === "__proto__") issues.push("extension key \"__proto__\" is not allowed");
+		else if (!isJsonSerializable(value)) issues.push(`extension "${key}" must be JSON-serializable`);
+		else extensions[key] = value;
+	}
+	if (issues.length > 0) throw new ProblemError(issues);
+	const result = {
+		type,
+		title,
+		status: input.status
+	};
+	if (detail !== void 0) result.detail = detail;
+	if (instance !== void 0) result.instance = instance;
+	for (const [key, value] of Object.entries(extensions)) result[key] = value;
+	return result;
+}
+/** @internal */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** @internal */
+function isValidStatus(value) {
+	return typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 599;
+}
+const URI_REFERENCE_FORBIDDEN = /[\s\u0000-\u001f\u007f]/;
+function uriReference(name, value, issues) {
+	if (typeof value !== "string" || value.length === 0 || value.length > URI_MAX_LENGTH || URI_REFERENCE_FORBIDDEN.test(value)) {
+		issues.push(`${name} must be a non-empty URI reference without whitespace or control characters (max ${URI_MAX_LENGTH} characters)`);
+		return "";
+	}
+	return value;
+}
+function optionalText(name, value, maxLength, issues) {
+	if (value === void 0) return;
+	if (typeof value !== "string") {
+		issues.push(`${name} must be a string`);
+		return;
+	}
+	const text = sanitizeText(value, maxLength);
+	return text === "" ? void 0 : text;
+}
+function isJsonSerializable(value) {
+	try {
+		return JSON.stringify(value) !== void 0;
+	} catch {
+		return false;
+	}
+}
+// src/client.ts
+/** Largest problem body that `parseProblem` will read. */
+const PARSE_MAX_BYTES = 65536;
+/**
+* Type guard for problem documents: `title` is a non-empty string, `status` is
+* an integer between 100 and 599, and `type`, `detail`, `instance` are strings
+* when present. Extension members are not inspected.
+*/
+function isProblemDetails(value) {
+	if (!isRecord(value)) return false;
+	const { type, title, status, detail, instance } = value;
+	return typeof title === "string" && title.length > 0 && isValidStatus(status) && (type === void 0 || typeof type === "string") && (detail === void 0 || typeof detail === "string") && (instance === void 0 || typeof instance === "string");
+}
+/**
+* Reads a problem document from a `Response`. Returns `undefined` unless the
+* media type is `application/problem+json` or `application/json` and the body is
+* a valid problem. Bodies over 64 KiB, malformed JSON and read errors also
+* yield `undefined`; this function never throws.
+*
+* The response body is consumed. Call `response.clone()` first if it is needed later.
+*/
+async function parseProblem(response) {
+	try {
+		const mediaType = response.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase();
+		if (mediaType !== "application/problem+json" && mediaType !== "application/json") return;
+		const declared = Number(response.headers.get("content-length"));
+		if (Number.isFinite(declared) && declared > PARSE_MAX_BYTES) {
+			await response.body?.cancel();
+			return;
+		}
+		const bytes = await readLimited(response.body, PARSE_MAX_BYTES);
+		if (bytes === void 0) return;
+		const parsed = JSON.parse(new TextDecoder().decode(bytes));
+		return isProblemDetails(parsed) ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
+/** Reads a stream up to `limit` bytes. Resolves to `undefined` if the limit is exceeded. */
+async function readLimited(body, limit) {
+	if (body === null) return;
+	const reader = body.getReader();
+	const chunks = [];
+	let total = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		total += value.byteLength;
+		if (total > limit) {
+			await reader.cancel();
+			return;
+		}
+		chunks.push(value);
+	}
+	const bytes = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return bytes;
+}
+// src/from-error.ts
+const DEFAULT_FALLBACK = {
+	status: 500,
+	title: "Internal Server Error"
+};
+const REQUEST_ID_MAX_LENGTH = 128;
+/**
+* Maps any thrown value to a problem document without leaking internals.
+*
+* Unknown errors produce only the fallback (by default status 500 and a generic
+* title). Their `message`, `stack`, `cause` and `name` are never included unless
+* `expose(error)` returns `true`.
+*/
+function fromError(error, options = {}) {
+	const instance = instanceFor(options.instanceFromRequestId);
+	const matched = findTemplate(error, options.registry);
+	if (matched !== void 0) return normalizeProblem({
+		type: matched.type,
+		title: matched.title,
+		status: matched.status,
+		detail: matched.detail,
+		instance
+	});
+	const fallback = options.fallback ?? DEFAULT_FALLBACK;
+	const exposed = options.expose !== void 0 && isExposed(options.expose, error);
+	return normalizeProblem({
+		type: fallback.type,
+		title: fallback.title,
+		status: fallback.status,
+		detail: exposed ? messageOf(error) : fallback.detail,
+		instance
+	});
+}
+function instanceFor(requestId) {
+	if (requestId === void 0 || requestId === "") return;
+	try {
+		return `urn:request:${encodeURIComponent(truncate(requestId, REQUEST_ID_MAX_LENGTH))}`;
+	} catch {
+		return;
+	}
+}
+function findTemplate(error, registry) {
+	if (registry === void 0) return;
+	try {
+		if (isMap(registry)) {
+			for (const [matcher, template] of registry) if (typeof matcher === "string" ? readProperty(error, "code") === matcher : error instanceof matcher) return template;
+			return;
+		}
+		const { by, templates } = registry;
+		for (const [key, template] of Object.entries(templates)) {
+			const byCode = by !== "className" && readProperty(error, "code") === key;
+			const byClassName = by !== "code" && constructorName(error) === key;
+			if (byCode || byClassName) return template;
+		}
+		return;
+	} catch {
+		return;
+	}
+}
+function isMap(registry) {
+	return registry instanceof Map;
+}
+function isExposed(expose, error) {
+	try {
+		return expose(error) === true;
+	} catch {
+		return false;
+	}
+}
+function messageOf(error) {
+	try {
+		const message = readProperty(error, "message");
+		return typeof message === "string" ? message : void 0;
+	} catch {
+		return;
+	}
+}
+function constructorName(value) {
+	const ctor = readProperty(value, "constructor");
+	return typeof ctor === "function" ? ctor.name : void 0;
+}
+function readProperty(value, key) {
+	if (typeof value !== "object" && typeof value !== "function" || value === null) return;
+	return value[key];
+}
+// src/registry.ts
+const MATCH_MODES = /* @__PURE__ */ new Set([
+	"code",
+	"className",
+	"both"
+]);
+/**
+* Defines named problem templates for `fromError`. Every template is validated
+* immediately, so invalid definitions fail at startup instead of per request.
+*
+* @example
+* const problems = defineProblems({
+*   NotFound: { status: 404, title: "Not found", type: "https://example.com/problems/not-found" },
+* });
+* fromError(error, { registry: problems });
+*/
+function defineProblems(templates, options = {}) {
+	const by = options.by ?? "code";
+	const issues = [];
+	if (!MATCH_MODES.has(by)) issues.push("by must be \"code\", \"className\" or \"both\"");
+	for (const [key, template] of Object.entries(templates)) {
+		if (key === "") {
+			issues.push("template keys must be non-empty");
+			continue;
+		}
+		try {
+			normalizeProblem({
+				...template,
+				extensions: void 0
+			});
+		} catch (error) {
+			if (error instanceof ProblemError) issues.push(`${key}: ${error.issues.join("; ")}`);
+			else throw error;
+		}
+	}
+	if (issues.length > 0) throw new ProblemError(issues);
+	return Object.freeze({
+		templates: Object.freeze({ ...templates }),
+		by
+	});
+}
+// src/response.ts
+/** Statuses that cannot carry a body, or that the Response constructor rejects. */
+const BODYLESS_OR_UNSUPPORTED_STATUSES = /* @__PURE__ */ new Set([
+	101,
+	103,
+	204,
+	205,
+	304
+]);
+/**
+* Creates a Web-standard `Response` carrying the problem as
+* `application/problem+json; charset=utf-8`. The problem is validated and
+* sanitized again before it is serialized.
+*/
+function toResponse(problem, options = {}) {
+	const normalized = normalizeProblem(toProblemInput(problem));
+	if (normalized.status < 200 || BODYLESS_OR_UNSUPPORTED_STATUSES.has(normalized.status)) throw new ProblemError([`status ${normalized.status} cannot be sent with a problem body (use 200-599, except 204, 205 and 304)`]);
+	const headers = new Headers(options.headers);
+	headers.set("content-type", PROBLEM_CONTENT_TYPE);
+	return new Response(JSON.stringify(normalized), {
+		status: normalized.status,
+		headers
+	});
+}
+/** Converts the flattened wire shape into the input shape used for validation. */
+function toProblemInput(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new ProblemError(["problem must be an object"]);
+	const { type, title, status, detail, instance, ...extensions } = value;
+	return {
+		type,
+		title,
+		status,
+		detail,
+		instance,
+		extensions
+	};
+}
+export { DEFAULT_PROBLEM_TYPE, DETAIL_MAX_LENGTH, PROBLEM_CONTENT_TYPE, ProblemError, TITLE_MAX_LENGTH, defineProblems, fromError, isProblemDetails, parseProblem, problem, toResponse };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/sanitize.ts","../src/problem.ts","../src/client.ts","../src/from-error.ts","../src/registry.ts","../src/response.ts"],"sourcesContent":["const WHITESPACE_RUNS = /\\s+/g;\nconst CONTROL_CHARS = /[\\u0000-\\u001f\\u007f-\\u009f]/g;\n\n/**\n * Makes free text safe for a human-readable problem field: every whitespace run\n * (tabs, line breaks, Unicode line separators) becomes one space, other control\n * characters are removed, surrounding whitespace is trimmed and the result is\n * cut to `maxLength` code points.\n */\nexport function sanitizeText(value: string, maxLength: number): string {\n\tconst cleaned = value.replace(WHITESPACE_RUNS, \" \").replace(CONTROL_CHARS, \"\").trim();\n\treturn truncate(cleaned, maxLength);\n}\n\n/** Cuts a string to at most `maxLength` code points, ending with an ellipsis if cut. */\nexport function truncate(value: string, maxLength: number): string {\n\t// A string never has more code points than code units, so this is a cheap pre-check.\n\tif (value.length <= maxLength) {\n\t\treturn value;\n\t}\n\tconst chars = Array.from(value);\n\tif (chars.length <= maxLength) {\n\t\treturn value;\n\t}\n\treturn `${chars.slice(0, maxLength - 1).join(\"\")}…`;\n}\n","import { sanitizeText } from \"./sanitize.js\";\n\n/** Content-Type for RFC 9457 problem documents. */\nexport const PROBLEM_CONTENT_TYPE = \"application/problem+json; charset=utf-8\";\n\n/** Default problem `type` as defined by RFC 9457. */\nexport const DEFAULT_PROBLEM_TYPE = \"about:blank\";\n\nexport const TITLE_MAX_LENGTH = 200;\nexport const DETAIL_MAX_LENGTH = 1000;\nconst URI_MAX_LENGTH = 2048;\n\n/** Members defined by RFC 9457. They may not be used as extension keys. */\nexport const RESERVED_MEMBERS: ReadonlySet<string> = new Set([\n\t\"type\",\n\t\"title\",\n\t\"status\",\n\t\"detail\",\n\t\"instance\",\n]);\n\n/**\n * An RFC 9457 problem document. Extension members are flattened next to the\n * standard members, as the specification requires.\n */\nexport interface ProblemDetails {\n\ttype?: string;\n\ttitle: string;\n\tstatus: number;\n\tdetail?: string;\n\tinstance?: string;\n\t[extension: string]: unknown;\n}\n\n/**\n * Input for `problem()`. Extensions are passed separately so that they can be\n * checked against the reserved members before a document is built.\n */\nexport interface ProblemInput {\n\ttype?: string;\n\ttitle: string;\n\tstatus: number;\n\tdetail?: string;\n\tinstance?: string;\n\textensions?: Readonly<Record<string, unknown>>;\n}\n\nexport type ProblemErrorCode = \"INVALID_PROBLEM\";\n\n/** Thrown when problem details cannot be built or are invalid. Carries no input values. */\nexport class ProblemError extends Error {\n\treadonly code: ProblemErrorCode = \"INVALID_PROBLEM\";\n\treadonly issues: readonly string[];\n\n\tconstructor(issues: readonly string[]) {\n\t\tsuper(`Invalid problem details: ${issues.join(\"; \")}`);\n\t\tthis.name = \"ProblemError\";\n\t\tthis.issues = issues;\n\t}\n}\n\n/**\n * Builds a validated problem document. Text fields are sanitized and length\n * limited; invalid input throws a `ProblemError` with code `INVALID_PROBLEM`.\n */\nexport function problem(input: ProblemInput): ProblemDetails {\n\treturn normalizeProblem(input);\n}\n\n/** @internal Validates and normalizes a problem input. Shared by all helpers. */\nexport function normalizeProblem(input: ProblemInput): ProblemDetails {\n\tconst issues: string[] = [];\n\n\tif (!isValidStatus(input.status)) {\n\t\tissues.push(\"status must be an integer between 100 and 599\");\n\t}\n\n\tconst title = typeof input.title === \"string\" ? sanitizeText(input.title, TITLE_MAX_LENGTH) : \"\";\n\tif (title === \"\") {\n\t\tissues.push(\"title must be a non-empty string\");\n\t}\n\n\tconst type =\n\t\tinput.type === undefined ? DEFAULT_PROBLEM_TYPE : uriReference(\"type\", input.type, issues);\n\tconst instance =\n\t\tinput.instance === undefined ? undefined : uriReference(\"instance\", input.instance, issues);\n\tconst detail = optionalText(\"detail\", input.detail, DETAIL_MAX_LENGTH, issues);\n\n\tconst extensions: Record<string, unknown> = {};\n\tif (input.extensions !== undefined) {\n\t\tif (!isRecord(input.extensions)) {\n\t\t\tissues.push(\"extensions must be a plain object\");\n\t\t} else {\n\t\t\tfor (const [key, value] of Object.entries(input.extensions)) {\n\t\t\t\tif (RESERVED_MEMBERS.has(key)) {\n\t\t\t\t\tissues.push(`extension key \"${key}\" collides with a reserved problem member`);\n\t\t\t\t} else if (key === \"__proto__\") {\n\t\t\t\t\tissues.push('extension key \"__proto__\" is not allowed');\n\t\t\t\t} else if (!isJsonSerializable(value)) {\n\t\t\t\t\tissues.push(`extension \"${key}\" must be JSON-serializable`);\n\t\t\t\t} else {\n\t\t\t\t\textensions[key] = value;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tif (issues.length > 0) {\n\t\tthrow new ProblemError(issues);\n\t}\n\n\tconst result: ProblemDetails = { type, title, status: input.status };\n\tif (detail !== undefined) {\n\t\tresult.detail = detail;\n\t}\n\tif (instance !== undefined) {\n\t\tresult.instance = instance;\n\t}\n\tfor (const [key, value] of Object.entries(extensions)) {\n\t\tresult[key] = value;\n\t}\n\treturn result;\n}\n\n/** @internal */\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/** @internal */\nexport function isValidStatus(value: unknown): value is number {\n\treturn typeof value === \"number\" && Number.isInteger(value) && value >= 100 && value <= 599;\n}\n\nconst URI_REFERENCE_FORBIDDEN = /[\\s\\u0000-\\u001f\\u007f]/;\n\nfunction uriReference(name: string, value: unknown, issues: string[]): string {\n\tif (\n\t\ttypeof value !== \"string\" ||\n\t\tvalue.length === 0 ||\n\t\tvalue.length > URI_MAX_LENGTH ||\n\t\tURI_REFERENCE_FORBIDDEN.test(value)\n\t) {\n\t\tissues.push(\n\t\t\t`${name} must be a non-empty URI reference without whitespace or control characters (max ${URI_MAX_LENGTH} characters)`,\n\t\t);\n\t\treturn \"\";\n\t}\n\treturn value;\n}\n\nfunction optionalText(\n\tname: string,\n\tvalue: unknown,\n\tmaxLength: number,\n\tissues: string[],\n): string | undefined {\n\tif (value === undefined) {\n\t\treturn undefined;\n\t}\n\tif (typeof value !== \"string\") {\n\t\tissues.push(`${name} must be a string`);\n\t\treturn undefined;\n\t}\n\tconst text = sanitizeText(value, maxLength);\n\treturn text === \"\" ? undefined : text;\n}\n\nfunction isJsonSerializable(value: unknown): boolean {\n\ttry {\n\t\treturn JSON.stringify(value) !== undefined;\n\t} catch {\n\t\treturn false;\n\t}\n}\n","import { isRecord, isValidStatus, type ProblemDetails } from \"./problem.js\";\n\n/** Largest problem body that `parseProblem` will read. */\nconst PARSE_MAX_BYTES = 64 * 1024;\n\n/**\n * Type guard for problem documents: `title` is a non-empty string, `status` is\n * an integer between 100 and 599, and `type`, `detail`, `instance` are strings\n * when present. Extension members are not inspected.\n */\nexport function isProblemDetails(value: unknown): value is ProblemDetails {\n\tif (!isRecord(value)) {\n\t\treturn false;\n\t}\n\tconst { type, title, status, detail, instance } = value;\n\treturn (\n\t\ttypeof title === \"string\" &&\n\t\ttitle.length > 0 &&\n\t\tisValidStatus(status) &&\n\t\t(type === undefined || typeof type === \"string\") &&\n\t\t(detail === undefined || typeof detail === \"string\") &&\n\t\t(instance === undefined || typeof instance === \"string\")\n\t);\n}\n\n/**\n * Reads a problem document from a `Response`. Returns `undefined` unless the\n * media type is `application/problem+json` or `application/json` and the body is\n * a valid problem. Bodies over 64 KiB, malformed JSON and read errors also\n * yield `undefined`; this function never throws.\n *\n * The response body is consumed. Call `response.clone()` first if it is needed later.\n */\nexport async function parseProblem(response: Response): Promise<ProblemDetails | undefined> {\n\ttry {\n\t\tconst mediaType = response.headers.get(\"content-type\")?.split(\";\")[0]?.trim().toLowerCase();\n\t\tif (mediaType !== \"application/problem+json\" && mediaType !== \"application/json\") {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst declared = Number(response.headers.get(\"content-length\"));\n\t\tif (Number.isFinite(declared) && declared > PARSE_MAX_BYTES) {\n\t\t\tawait response.body?.cancel();\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst bytes = await readLimited(response.body, PARSE_MAX_BYTES);\n\t\tif (bytes === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst parsed: unknown = JSON.parse(new TextDecoder().decode(bytes));\n\t\treturn isProblemDetails(parsed) ? parsed : undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/** Reads a stream up to `limit` bytes. Resolves to `undefined` if the limit is exceeded. */\nasync function readLimited(\n\tbody: ReadableStream<Uint8Array> | null,\n\tlimit: number,\n): Promise<Uint8Array | undefined> {\n\tif (body === null) {\n\t\treturn undefined;\n\t}\n\tconst reader = body.getReader();\n\tconst chunks: Uint8Array[] = [];\n\tlet total = 0;\n\tfor (;;) {\n\t\tconst { done, value } = await reader.read();\n\t\tif (done) {\n\t\t\tbreak;\n\t\t}\n\t\ttotal += value.byteLength;\n\t\tif (total > limit) {\n\t\t\tawait reader.cancel();\n\t\t\treturn undefined;\n\t\t}\n\t\tchunks.push(value);\n\t}\n\tconst bytes = new Uint8Array(total);\n\tlet offset = 0;\n\tfor (const chunk of chunks) {\n\t\tbytes.set(chunk, offset);\n\t\toffset += chunk.byteLength;\n\t}\n\treturn bytes;\n}\n","import { normalizeProblem, type ProblemDetails } from \"./problem.js\";\nimport type { ProblemRegistry, ProblemTemplate } from \"./registry.js\";\nimport { truncate } from \"./sanitize.js\";\n\n/** A class used as a registry key in `fromError`. Matched with `instanceof`. */\nexport type ErrorClass = abstract new (...args: never[]) => unknown;\n\nexport interface FromErrorOptions {\n\t/**\n\t * Opt-in for unknown errors. Only when this returns `true` is the error\n\t * message copied into `detail` (sanitized and length limited).\n\t */\n\texpose?: (error: unknown) => boolean;\n\t/**\n\t * Known errors. A `ProblemRegistry` from `defineProblems`, or a `Map` whose\n\t * string keys match `error.code` and whose class keys match with `instanceof`.\n\t * The first matching entry wins. Matched errors never expose their message.\n\t */\n\tregistry?: ProblemRegistry | ReadonlyMap<ErrorClass | string, ProblemTemplate>;\n\t/** Template for unknown errors. Defaults to status 500 and a generic title. */\n\tfallback?: ProblemTemplate;\n\t/** Request identifier. When set, `instance` becomes `urn:request:<id>`. */\n\tinstanceFromRequestId?: string;\n}\n\nconst DEFAULT_FALLBACK: ProblemTemplate = { status: 500, title: \"Internal Server Error\" };\nconst REQUEST_ID_MAX_LENGTH = 128;\n\n/**\n * Maps any thrown value to a problem document without leaking internals.\n *\n * Unknown errors produce only the fallback (by default status 500 and a generic\n * title). Their `message`, `stack`, `cause` and `name` are never included unless\n * `expose(error)` returns `true`.\n */\nexport function fromError(error: unknown, options: FromErrorOptions = {}): ProblemDetails {\n\tconst instance = instanceFor(options.instanceFromRequestId);\n\n\tconst matched = findTemplate(error, options.registry);\n\tif (matched !== undefined) {\n\t\treturn normalizeProblem({\n\t\t\ttype: matched.type,\n\t\t\ttitle: matched.title,\n\t\t\tstatus: matched.status,\n\t\t\tdetail: matched.detail,\n\t\t\tinstance,\n\t\t});\n\t}\n\n\tconst fallback = options.fallback ?? DEFAULT_FALLBACK;\n\tconst exposed = options.expose !== undefined && isExposed(options.expose, error);\n\treturn normalizeProblem({\n\t\ttype: fallback.type,\n\t\ttitle: fallback.title,\n\t\tstatus: fallback.status,\n\t\tdetail: exposed ? messageOf(error) : fallback.detail,\n\t\tinstance,\n\t});\n}\n\nfunction instanceFor(requestId: string | undefined): string | undefined {\n\tif (requestId === undefined || requestId === \"\") {\n\t\treturn undefined;\n\t}\n\ttry {\n\t\treturn `urn:request:${encodeURIComponent(truncate(requestId, REQUEST_ID_MAX_LENGTH))}`;\n\t} catch {\n\t\t// Lone surrogates cannot be encoded; an unusable request id is dropped, not thrown.\n\t\treturn undefined;\n\t}\n}\n\nfunction findTemplate(\n\terror: unknown,\n\tregistry: FromErrorOptions[\"registry\"],\n): ProblemTemplate | undefined {\n\tif (registry === undefined) {\n\t\treturn undefined;\n\t}\n\ttry {\n\t\tif (isMap(registry)) {\n\t\t\tfor (const [matcher, template] of registry) {\n\t\t\t\tconst hit =\n\t\t\t\t\ttypeof matcher === \"string\"\n\t\t\t\t\t\t? readProperty(error, \"code\") === matcher\n\t\t\t\t\t\t: error instanceof matcher;\n\t\t\t\tif (hit) {\n\t\t\t\t\treturn template;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst { by, templates } = registry;\n\t\tfor (const [key, template] of Object.entries(templates)) {\n\t\t\tconst byCode = by !== \"className\" && readProperty(error, \"code\") === key;\n\t\t\tconst byClassName = by !== \"code\" && constructorName(error) === key;\n\t\t\tif (byCode || byClassName) {\n\t\t\t\treturn template;\n\t\t\t}\n\t\t}\n\t\treturn undefined;\n\t} catch {\n\t\t// A throwing getter or hostile matcher must not change the response shape.\n\t\treturn undefined;\n\t}\n}\n\nfunction isMap(\n\tregistry: NonNullable<FromErrorOptions[\"registry\"]>,\n): registry is ReadonlyMap<ErrorClass | string, ProblemTemplate> {\n\treturn registry instanceof Map;\n}\n\nfunction isExposed(expose: (error: unknown) => boolean, error: unknown): boolean {\n\ttry {\n\t\treturn expose(error) === true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nfunction messageOf(error: unknown): string | undefined {\n\ttry {\n\t\tconst message = readProperty(error, \"message\");\n\t\treturn typeof message === \"string\" ? message : undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nfunction constructorName(value: unknown): string | undefined {\n\tconst ctor = readProperty(value, \"constructor\");\n\treturn typeof ctor === \"function\" ? ctor.name : undefined;\n}\n\nfunction readProperty(value: unknown, key: string): unknown {\n\tif ((typeof value !== \"object\" && typeof value !== \"function\") || value === null) {\n\t\treturn undefined;\n\t}\n\treturn (value as Record<string, unknown>)[key];\n}\n","import { normalizeProblem, ProblemError } from \"./problem.js\";\n\n/** A problem definition that can be reused for errors of a known kind. */\nexport interface ProblemTemplate {\n\ttype?: string;\n\ttitle: string;\n\tstatus: number;\n\tdetail?: string;\n}\n\nexport type ProblemTemplates = Readonly<Record<string, ProblemTemplate>>;\n\n/**\n * How registry keys are matched against errors:\n * - `code`: `error.code === key` (default, survives minification)\n * - `className`: `error.constructor.name === key`\n * - `both`: either of the two\n */\nexport type MatchBy = \"code\" | \"className\" | \"both\";\n\nexport interface DefineProblemsOptions {\n\tby?: MatchBy;\n}\n\nexport interface ProblemRegistry<T extends ProblemTemplates = ProblemTemplates> {\n\treadonly templates: T;\n\treadonly by: MatchBy;\n}\n\nconst MATCH_MODES: ReadonlySet<string> = new Set([\"code\", \"className\", \"both\"]);\n\n/**\n * Defines named problem templates for `fromError`. Every template is validated\n * immediately, so invalid definitions fail at startup instead of per request.\n *\n * @example\n * const problems = defineProblems({\n *   NotFound: { status: 404, title: \"Not found\", type: \"https://example.com/problems/not-found\" },\n * });\n * fromError(error, { registry: problems });\n */\nexport function defineProblems<const T extends ProblemTemplates>(\n\ttemplates: T,\n\toptions: DefineProblemsOptions = {},\n): ProblemRegistry<T> {\n\tconst by = options.by ?? \"code\";\n\tconst issues: string[] = [];\n\n\tif (!MATCH_MODES.has(by)) {\n\t\tissues.push('by must be \"code\", \"className\" or \"both\"');\n\t}\n\n\tfor (const [key, template] of Object.entries(templates)) {\n\t\tif (key === \"\") {\n\t\t\tissues.push(\"template keys must be non-empty\");\n\t\t\tcontinue;\n\t\t}\n\t\ttry {\n\t\t\tnormalizeProblem({ ...template, extensions: undefined });\n\t\t} catch (error) {\n\t\t\tif (error instanceof ProblemError) {\n\t\t\t\tissues.push(`${key}: ${error.issues.join(\"; \")}`);\n\t\t\t} else {\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t}\n\t}\n\n\tif (issues.length > 0) {\n\t\tthrow new ProblemError(issues);\n\t}\n\n\treturn Object.freeze({ templates: Object.freeze({ ...templates }), by });\n}\n","import {\n\tnormalizeProblem,\n\tPROBLEM_CONTENT_TYPE,\n\ttype ProblemDetails,\n\tProblemError,\n\ttype ProblemInput,\n} from \"./problem.js\";\n\n/** Statuses that cannot carry a body, or that the Response constructor rejects. */\nconst BODYLESS_OR_UNSUPPORTED_STATUSES: ReadonlySet<number> = new Set([101, 103, 204, 205, 304]);\n\nexport interface ToResponseOptions {\n\t/** Extra headers. The Content-Type is always set to the problem media type. */\n\theaders?: HeadersInit;\n}\n\n/**\n * Creates a Web-standard `Response` carrying the problem as\n * `application/problem+json; charset=utf-8`. The problem is validated and\n * sanitized again before it is serialized.\n */\nexport function toResponse(problem: ProblemDetails, options: ToResponseOptions = {}): Response {\n\tconst normalized = normalizeProblem(toProblemInput(problem));\n\n\tif (normalized.status < 200 || BODYLESS_OR_UNSUPPORTED_STATUSES.has(normalized.status)) {\n\t\tthrow new ProblemError([\n\t\t\t`status ${normalized.status} cannot be sent with a problem body (use 200-599, except 204, 205 and 304)`,\n\t\t]);\n\t}\n\n\tconst headers = new Headers(options.headers);\n\theaders.set(\"content-type\", PROBLEM_CONTENT_TYPE);\n\n\treturn new Response(JSON.stringify(normalized), {\n\t\tstatus: normalized.status,\n\t\theaders,\n\t});\n}\n\n/** Converts the flattened wire shape into the input shape used for validation. */\nfunction toProblemInput(value: ProblemDetails): ProblemInput {\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n\t\tthrow new ProblemError([\"problem must be an object\"]);\n\t}\n\tconst { type, title, status, detail, instance, ...extensions } = value;\n\treturn { type, title, status, detail, instance, extensions };\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,86 @@
 {
-  "name": "@yedoma-labs/ysuly-problem",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@yedoma-labs/ysuly-problem",
+	"version": "1.0.0",
+	"description": "Type-safe RFC 9457 Problem Details with safe error mapping, zero dependencies",
+	"type": "module",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			},
+			"require": {
+				"types": "./dist/index.d.cts",
+				"default": "./dist/index.cjs"
+			}
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"engines": {
+		"node": ">=20"
+	},
+	"packageManager": "pnpm@12.15.0",
+	"scripts": {
+		"build": "tsdown",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"test:coverage": "vitest run --coverage",
+		"lint": "biome check src tests",
+		"lint:fix": "biome check --write src tests",
+		"format": "biome format --write src tests",
+		"typecheck": "tsc --noEmit",
+		"prepublishOnly": "pnpm run build"
+	},
+	"keywords": [
+		"problem-details",
+		"rfc9457",
+		"rfc7807",
+		"problem+json",
+		"error-handling",
+		"api",
+		"typescript",
+		"zero-dependency"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/yedoma-labs/ysuly-problem"
+	},
+	"author": "",
+	"license": "MIT",
+	"simple-git-hooks": {
+		"pre-commit": "pnpm exec lint-staged",
+		"pre-push": "pnpm run typecheck && pnpm run test",
+		"commit-msg": "pnpm exec commitlint --edit $1"
+	},
+	"lint-staged": {
+		"*.ts": [
+			"biome check --write"
+		]
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.6.3",
+		"@commitlint/cli": "^21.2.4",
+		"@commitlint/config-conventional": "^21.2.4",
+		"@semantic-release/changelog": "^7.0.0",
+		"@semantic-release/commit-analyzer": "^13.0.1",
+		"@semantic-release/exec": "^7.1.0",
+		"@semantic-release/git": "^11.0.1",
+		"@semantic-release/github": "^12.0.10",
+		"@semantic-release/npm": "^13.2.0",
+		"@semantic-release/release-notes-generator": "^14.1.1",
+		"@types/node": "26.6.5",
+		"@typescript/typescript6": "^6.0.2",
+		"@vitest/coverage-v8": "^5.0.5",
+		"lint-staged": "^17.6.0",
+		"semantic-release": "^25.0.9",
+		"simple-git-hooks": "^2.14.0",
+		"tsdown": "^0.23.2",
+		"typescript": "7.0.2",
+		"vitest": "5.0.5"
+	}
+}