@zeroxsolutions/response 0.12.0

package/dist/document.d.ts

@@ -0,0 +1,47 @@
+import type { ZodObject, ZodType } from 'zod';
+import { type JsonApiObject, type Meta, type PaginationLinks, type ResourceIdentifier, type ResourceLinks } from './primitives.js';
+import { type RelatedResource, type RelationshipDef } from './relationship.js';
+/** One relationship as a document carries it - the linkage, plus its own links and meta. */
+export interface Relationship {
+    data?: ResourceIdentifier | ResourceIdentifier[] | null;
+    links?: ResourceLinks;
+    meta?: Meta;
+}
+/** A resource object, with `attributes` carrying the declared attribute type. */
+export interface ResourceObject<A> {
+    type: string;
+    id: string;
+    attributes: A;
+    relationships?: Record<string, Relationship>;
+    links?: ResourceLinks;
+    meta?: Meta;
+}
+/** A single-resource document. `included` holds other resource types, so its attributes stay unknown. */
+export interface ResourceDocument<A> {
+    data: ResourceObject<A>;
+    included?: ResourceObject<unknown>[];
+    links?: ResourceLinks;
+    meta?: Meta;
+    jsonapi?: JsonApiObject;
+}
+/** A collection document - the same members with `data` an array and paginated `links`. */
+export interface CollectionDocument<A> {
+    data: ResourceObject<A>[];
+    included?: ResourceObject<unknown>[];
+    links?: PaginationLinks;
+    meta?: Meta;
+    jsonapi?: JsonApiObject;
+}
+/** Wraps `attributes` into a resource object - `{ type, id, attributes, relationships?, links?, meta? }`. */
+export declare function resourceObjectSchema(type: string, attributes: ZodObject, relationships?: Readonly<Record<string, RelationshipDef>>): ZodType;
+/**
+ * The document for a SINGLE resource - `{ data, included?, links?, meta?, jsonapi? }`.
+ *
+ * `A` is asserted rather than inferred: the schema is assembled from a relationship graph reached
+ * through thunks, so nothing static carries the attribute type, and a client typing a route off this
+ * schema would otherwise read every member as `unknown`.
+ */
+export declare function resourceDocumentSchema<A = unknown>(root: RelatedResource): ZodType<ResourceDocument<A>>;
+/** The document for a COLLECTION - the same members, with `data` an array and paginated `links`. */
+export declare function collectionDocumentSchema<A = unknown>(root: RelatedResource): ZodType<CollectionDocument<A>>;
+//# sourceMappingURL=document.d.ts.map

package/dist/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAC9C,OAAO,EAKL,KAAK,aAAa,EAClB,KAAK,IAAI,EACT,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAA2C,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAExH,4FAA4F;AAC5F,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,GAAG,IAAI,CAAC;IACxD,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,CAAC,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC7C,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AAED,yGAAyG;AACzG,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IACxB,QAAQ,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,2FAA2F;AAC3F,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC;IACrC,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,6GAA6G;AAC7G,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,EACrB,aAAa,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAM,GAC5D,OAAO,CAUT;AAgBD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAQvG;AAED,oGAAoG;AACpG,wBAAgB,wBAAwB,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAQ3G"}

package/dist/document.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { jsonApiObjectSchema, metaSchema, paginationLinksSchema, resourceLinksSchema, } from './primitives.js';
+import { relationshipsSchema, reachableResources } from './relationship.js';
+/** Wraps `attributes` into a resource object - `{ type, id, attributes, relationships?, links?, meta? }`. */
+export function resourceObjectSchema(type, attributes, relationships = {}) {
+    const linkage = relationshipsSchema(relationships);
+    return z.object({
+        type: z.literal(type),
+        id: z.string(),
+        attributes,
+        ...(linkage ? { relationships: linkage.optional() } : {}),
+        links: resourceLinksSchema.optional(),
+        meta: metaSchema.optional(),
+    });
+}
+/**
+ * The `included` member: every resource reachable from `root`, as a union over their resource objects.
+ *
+ * A one-resource graph has no union to build, so its `included` is that resource's own array - a
+ * self-referential include (`?include=parent`) is the case that reaches it.
+ */
+function includedSchema(root) {
+    const reachable = reachableResources(root);
+    const [only] = reachable;
+    return reachable.length === 1
+        ? z.array(only?.resourceObject ?? z.never())
+        : z.array(z.union(reachable.map((resource) => resource.resourceObject)));
+}
+/**
+ * The document for a SINGLE resource - `{ data, included?, links?, meta?, jsonapi? }`.
+ *
+ * `A` is asserted rather than inferred: the schema is assembled from a relationship graph reached
+ * through thunks, so nothing static carries the attribute type, and a client typing a route off this
+ * schema would otherwise read every member as `unknown`.
+ */
+export function resourceDocumentSchema(root) {
+    return z.object({
+        data: root.resourceObject,
+        included: includedSchema(root).optional(),
+        links: resourceLinksSchema.optional(),
+        meta: metaSchema.optional(),
+        jsonapi: jsonApiObjectSchema.optional(),
+    });
+}
+/** The document for a COLLECTION - the same members, with `data` an array and paginated `links`. */
+export function collectionDocumentSchema(root) {
+    return z.object({
+        data: z.array(root.resourceObject),
+        included: includedSchema(root).optional(),
+        links: paginationLinksSchema.optional(),
+        meta: metaSchema.optional(),
+        jsonapi: jsonApiObjectSchema.optional(),
+    });
+}

package/dist/domain-error-resolver.d.ts

@@ -0,0 +1,37 @@
+import type { DomainErrorMap, ErrorClass } from './error-map.js';
+import type { ErrorLinks, ErrorSource } from './errors/error-document.js';
+import type { ErrorStatus } from './errors/error-registry.js';
+import type { ResolvedError } from './errors/resolved-error.js';
+import type { Meta } from './primitives.js';
+/** What a transport renders for one domain-error class. */
+export interface DomainErrorAnswer<E extends Error = Error> extends ErrorStatus {
+    /** This transport's own word for the failure, which a client switches on. */
+    code: string;
+    /** A page about this occurrence, and a page about its type of problem. */
+    links?: ErrorLinks;
+    /**
+     * The request slot to blame, read off the raised error - omit to render no `source` member.
+     *
+     * It lives in the MAP and not on the error because the two name different things: an error knows it refused a query
+     * parameter, and which member of the standard's `source` carries that is what this transport decides.
+     */
+    source?: (error: E) => ErrorSource;
+    /** The data a client acts on, read off the raised error - omit to render no `meta` member. */
+    meta?: (error: E) => Meta;
+}
+/** One entry of a domain error map: the class it answers for, and that answer. */
+export interface DomainErrorEntry {
+    readonly type: ErrorClass;
+    readonly answer: DomainErrorAnswer;
+}
+/** One entry of that map, inferring the error type so its `source` and `meta` read the members that class has. */
+export declare function errorEntry<E extends Error>(type: ErrorClass<E>, answer: DomainErrorAnswer<E>): DomainErrorEntry;
+/** Builds a transport's type-keyed error map - the one place deciding how each error type answers on the wire. */
+export declare function defineErrorMap(entries: Iterable<DomainErrorEntry>): DomainErrorMap;
+/**
+ * A `createErrorHandler` `resolve` hook mapping a raised error by its constructor identity - a hit renders the entry's
+ * answer with the error's `message` as `detail`, a miss returns `undefined` so an unregistered type falls through to a
+ * generic 500.
+ */
+export declare function createDomainErrorResolver(map: DomainErrorMap): (error: Error) => ResolvedError | undefined;
+//# sourceMappingURL=domain-error-resolver.d.ts.map

package/dist/domain-error-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-error-resolver.d.ts","sourceRoot":"","sources":["../src/domain-error-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C,2DAA2D;AAC3D,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,KAAK,GAAG,KAAK,CAAE,SAAQ,WAAW;IAC7E,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,WAAW,CAAC;IACnC,8FAA8F;IAC9F,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;CAC3B;AAED,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC;AAED,kHAAkH;AAClH,wBAAgB,UAAU,CAAC,CAAC,SAAS,KAAK,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAI/G;AAED,kHAAkH;AAClH,wBAAgB,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GAAG,cAAc,CAElF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,cAAc,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,aAAa,GAAG,SAAS,CAuB1G"}

package/dist/domain-error-resolver.js

@@ -0,0 +1,39 @@
+/** One entry of that map, inferring the error type so its `source` and `meta` read the members that class has. */
+export function errorEntry(type, answer) {
+    // The map is keyed by constructor identity and only ever read back through that key, so the answer declared here is
+    // only ever handed an instance of `type`.
+    return { type, answer: answer };
+}
+/** Builds a transport's type-keyed error map - the one place deciding how each error type answers on the wire. */
+export function defineErrorMap(entries) {
+    return new Map(Array.from(entries, ({ type, answer }) => [type, answer]));
+}
+/**
+ * A `createErrorHandler` `resolve` hook mapping a raised error by its constructor identity - a hit renders the entry's
+ * answer with the error's `message` as `detail`, a miss returns `undefined` so an unregistered type falls through to a
+ * generic 500.
+ */
+export function createDomainErrorResolver(map) {
+    return (error) => {
+        const answer = map.get(error.constructor);
+        if (!answer) {
+            return undefined;
+        }
+        const source = answer.source?.(error);
+        const meta = answer.meta?.(error);
+        return {
+            status: answer.status,
+            errors: [
+                {
+                    ...(answer.links !== undefined ? { links: answer.links } : {}),
+                    status: String(answer.status),
+                    code: answer.code,
+                    title: answer.title,
+                    detail: error.message,
+                    ...(source !== undefined ? { source } : {}),
+                    ...(meta !== undefined ? { meta } : {}),
+                },
+            ],
+        };
+    };
+}

package/dist/error-map.d.ts

@@ -0,0 +1,14 @@
+import type { DomainErrorAnswer } from './domain-error-resolver.js';
+import type { UpstreamErrorAnswer } from './upstream-error.js';
+/** A constructor of an `Error` subclass - the key of a type-keyed error map, never called through. */
+export type ErrorClass<E extends Error = Error> = new (...args: any[]) => E;
+/** A transport's map from an error's CONSTRUCTOR IDENTITY to the answer this wire renders for it. */
+export type DomainErrorMap = ReadonlyMap<ErrorClass, DomainErrorAnswer>;
+/**
+ * A transport's map from the `code` a fronted service rendered to this transport's own answer.
+ *
+ * A plain object rather than a `Map`: the key is a string the source spells literally, so an object literal already
+ * carries the lookup and the literal keys a builder would otherwise have to hand back.
+ */
+export type UpstreamErrorMap = Readonly<Record<string, UpstreamErrorAnswer>>;
+//# sourceMappingURL=error-map.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"error-map.d.ts","sourceRoot":"","sources":["../src/error-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,sGAAsG;AAEtG,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,KAAK,GAAG,KAAK,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAE5E,qGAAqG;AACrG,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;AAExE;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC"}

package/dist/error-map.js

@@ -0,0 +1 @@
+export {};

package/dist/errors/error-document.d.ts

@@ -0,0 +1,189 @@
+import { z } from 'zod';
+/** Where in the request a JSON:API error originates (spec: error object `source`). */
+export declare const errorSourceSchema: z.ZodObject<{
+    pointer: z.ZodOptional<z.ZodString>;
+    parameter: z.ZodOptional<z.ZodString>;
+    header: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ErrorSource = z.infer<typeof errorSourceSchema>;
+/** An error object's `links`: a page about this occurrence, and a page about its type of problem. */
+export declare const errorLinksSchema: z.ZodObject<{
+    about: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        rel: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodString>;
+        hreflang: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        href: z.ZodString;
+        describedby: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            rel: z.ZodOptional<z.ZodString>;
+            title: z.ZodOptional<z.ZodString>;
+            type: z.ZodOptional<z.ZodString>;
+            hreflang: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+            meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            href: z.ZodString;
+        }, z.core.$strip>, z.ZodNull]>>;
+    }, z.core.$strip>, z.ZodNull]>>;
+    type: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        rel: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodString>;
+        hreflang: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        href: z.ZodString;
+        describedby: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            rel: z.ZodOptional<z.ZodString>;
+            title: z.ZodOptional<z.ZodString>;
+            type: z.ZodOptional<z.ZodString>;
+            hreflang: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+            meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            href: z.ZodString;
+        }, z.core.$strip>, z.ZodNull]>>;
+    }, z.core.$strip>, z.ZodNull]>>;
+}, z.core.$strip>;
+export type ErrorLinks = z.infer<typeof errorLinksSchema>;
+/** A single JSON:API error object; every member is optional, and nothing here enforces the spec's at-least-one. */
+export declare const errorObjectSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    links: z.ZodOptional<z.ZodObject<{
+        about: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            rel: z.ZodOptional<z.ZodString>;
+            title: z.ZodOptional<z.ZodString>;
+            type: z.ZodOptional<z.ZodString>;
+            hreflang: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+            meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            href: z.ZodString;
+            describedby: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                rel: z.ZodOptional<z.ZodString>;
+                title: z.ZodOptional<z.ZodString>;
+                type: z.ZodOptional<z.ZodString>;
+                hreflang: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+                meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                href: z.ZodString;
+            }, z.core.$strip>, z.ZodNull]>>;
+        }, z.core.$strip>, z.ZodNull]>>;
+        type: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            rel: z.ZodOptional<z.ZodString>;
+            title: z.ZodOptional<z.ZodString>;
+            type: z.ZodOptional<z.ZodString>;
+            hreflang: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+            meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            href: z.ZodString;
+            describedby: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                rel: z.ZodOptional<z.ZodString>;
+                title: z.ZodOptional<z.ZodString>;
+                type: z.ZodOptional<z.ZodString>;
+                hreflang: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+                meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                href: z.ZodString;
+            }, z.core.$strip>, z.ZodNull]>>;
+        }, z.core.$strip>, z.ZodNull]>>;
+    }, z.core.$strip>>;
+    status: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    detail: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodObject<{
+        pointer: z.ZodOptional<z.ZodString>;
+        parameter: z.ZodOptional<z.ZodString>;
+        header: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type ErrorObject = z.infer<typeof errorObjectSchema>;
+/**
+ * A JSON:API error document - a top-level `errors` array of at least one member, which never carries `data`.
+ *
+ * Nothing here renders the top-level `meta` or `links`. They are declared so the schema `errorResponse` publishes is
+ * the whole document, and a client parsing another server's document keeps them.
+ */
+export declare const errorDocumentSchema: z.ZodObject<{
+    errors: z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        links: z.ZodOptional<z.ZodObject<{
+            about: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                rel: z.ZodOptional<z.ZodString>;
+                title: z.ZodOptional<z.ZodString>;
+                type: z.ZodOptional<z.ZodString>;
+                hreflang: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+                meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                href: z.ZodString;
+                describedby: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    rel: z.ZodOptional<z.ZodString>;
+                    title: z.ZodOptional<z.ZodString>;
+                    type: z.ZodOptional<z.ZodString>;
+                    hreflang: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+                    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                    href: z.ZodString;
+                }, z.core.$strip>, z.ZodNull]>>;
+            }, z.core.$strip>, z.ZodNull]>>;
+            type: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                rel: z.ZodOptional<z.ZodString>;
+                title: z.ZodOptional<z.ZodString>;
+                type: z.ZodOptional<z.ZodString>;
+                hreflang: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+                meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                href: z.ZodString;
+                describedby: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    rel: z.ZodOptional<z.ZodString>;
+                    title: z.ZodOptional<z.ZodString>;
+                    type: z.ZodOptional<z.ZodString>;
+                    hreflang: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+                    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                    href: z.ZodString;
+                }, z.core.$strip>, z.ZodNull]>>;
+            }, z.core.$strip>, z.ZodNull]>>;
+        }, z.core.$strip>>;
+        status: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodObject<{
+            pointer: z.ZodOptional<z.ZodString>;
+            parameter: z.ZodOptional<z.ZodString>;
+            header: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    links: z.ZodOptional<z.ZodObject<{
+        self: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            rel: z.ZodOptional<z.ZodString>;
+            title: z.ZodOptional<z.ZodString>;
+            type: z.ZodOptional<z.ZodString>;
+            hreflang: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+            meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            href: z.ZodString;
+            describedby: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                rel: z.ZodOptional<z.ZodString>;
+                title: z.ZodOptional<z.ZodString>;
+                type: z.ZodOptional<z.ZodString>;
+                hreflang: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+                meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                href: z.ZodString;
+            }, z.core.$strip>, z.ZodNull]>>;
+        }, z.core.$strip>, z.ZodNull]>>;
+        describedby: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            rel: z.ZodOptional<z.ZodString>;
+            title: z.ZodOptional<z.ZodString>;
+            type: z.ZodOptional<z.ZodString>;
+            hreflang: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+            meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            href: z.ZodString;
+            describedby: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                rel: z.ZodOptional<z.ZodString>;
+                title: z.ZodOptional<z.ZodString>;
+                type: z.ZodOptional<z.ZodString>;
+                hreflang: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+                meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                href: z.ZodString;
+            }, z.core.$strip>, z.ZodNull]>>;
+        }, z.core.$strip>, z.ZodNull]>>;
+    }, z.core.$strip>>;
+    jsonapi: z.ZodOptional<z.ZodObject<{
+        version: z.ZodOptional<z.ZodString>;
+        meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ErrorDocument = z.infer<typeof errorDocumentSchema>;
+//# sourceMappingURL=error-document.d.ts.map

package/dist/errors/error-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-document.d.ts","sourceRoot":"","sources":["../../src/errors/error-document.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,sFAAsF;AACtF,eAAO,MAAM,iBAAiB;;;;iBAMlB,CAAC;AACb,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,qGAAqG;AACrG,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAA8D,CAAC;AAC5F,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,mHAAmH;AACnH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAWlB,CAAC;AACb,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAK9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/errors/error-document.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { jsonApiObjectSchema, linkSchema, metaSchema } from '../primitives.js';
+/** Where in the request a JSON:API error originates (spec: error object `source`). */
+export const errorSourceSchema = z
+    .object({
+    pointer: z.string(),
+    parameter: z.string(),
+    header: z.string(),
+})
+    .partial();
+/** An error object's `links`: a page about this occurrence, and a page about its type of problem. */
+export const errorLinksSchema = z.object({ about: linkSchema, type: linkSchema }).partial();
+/** A single JSON:API error object; every member is optional, and nothing here enforces the spec's at-least-one. */
+export const errorObjectSchema = z
+    .object({
+    id: z.string(),
+    links: errorLinksSchema,
+    status: z.string(),
+    code: z.string(),
+    title: z.string(),
+    detail: z.string(),
+    source: errorSourceSchema,
+    meta: metaSchema,
+})
+    .partial();
+/**
+ * A JSON:API error document - a top-level `errors` array of at least one member, which never carries `data`.
+ *
+ * Nothing here renders the top-level `meta` or `links`. They are declared so the schema `errorResponse` publishes is
+ * the whole document, and a client parsing another server's document keeps them.
+ */
+export const errorDocumentSchema = z.object({
+    errors: z.array(errorObjectSchema).min(1),
+    meta: metaSchema.optional(),
+    links: z.object({ self: linkSchema, describedby: linkSchema }).partial().optional(),
+    jsonapi: jsonApiObjectSchema.optional(),
+});

package/dist/errors/error-registry.d.ts

@@ -0,0 +1,49 @@
+/** The HTTP status and human-readable title an error answers with. */
+export interface ErrorStatus {
+    status: number;
+    title: string;
+}
+/** The transport-level failures every service shares, rendered by status; a domain error maps by its TYPE instead. */
+export declare const BASE_ERROR_CODES: {
+    readonly BAD_REQUEST: {
+        readonly status: 400;
+        readonly title: "Bad Request";
+    };
+    readonly UNAUTHORIZED: {
+        readonly status: 401;
+        readonly title: "Unauthorized";
+    };
+    readonly FORBIDDEN: {
+        readonly status: 403;
+        readonly title: "Forbidden";
+    };
+    readonly NOT_FOUND: {
+        readonly status: 404;
+        readonly title: "Not Found";
+    };
+    readonly NOT_ACCEPTABLE: {
+        readonly status: 406;
+        readonly title: "Not Acceptable";
+    };
+    readonly CONFLICT: {
+        readonly status: 409;
+        readonly title: "Conflict";
+    };
+    readonly UNSUPPORTED_MEDIA_TYPE: {
+        readonly status: 415;
+        readonly title: "Unsupported Media Type";
+    };
+    readonly UNPROCESSABLE_ENTITY: {
+        readonly status: 422;
+        readonly title: "Unprocessable Entity";
+    };
+    readonly INTERNAL_SERVER_ERROR: {
+        readonly status: 500;
+        readonly title: "Internal Server Error";
+    };
+    readonly BAD_GATEWAY: {
+        readonly status: 502;
+        readonly title: "Bad Gateway";
+    };
+};
+//# sourceMappingURL=error-registry.d.ts.map

package/dist/errors/error-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-registry.d.ts","sourceRoot":"","sources":["../../src/errors/error-registry.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,sHAAsH;AACtH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAWmB,CAAC"}

package/dist/errors/error-registry.js

@@ -0,0 +1,13 @@
+/** The transport-level failures every service shares, rendered by status; a domain error maps by its TYPE instead. */
+export const BASE_ERROR_CODES = {
+    BAD_REQUEST: { status: 400, title: 'Bad Request' },
+    UNAUTHORIZED: { status: 401, title: 'Unauthorized' },
+    FORBIDDEN: { status: 403, title: 'Forbidden' },
+    NOT_FOUND: { status: 404, title: 'Not Found' },
+    NOT_ACCEPTABLE: { status: 406, title: 'Not Acceptable' },
+    CONFLICT: { status: 409, title: 'Conflict' },
+    UNSUPPORTED_MEDIA_TYPE: { status: 415, title: 'Unsupported Media Type' },
+    UNPROCESSABLE_ENTITY: { status: 422, title: 'Unprocessable Entity' },
+    INTERNAL_SERVER_ERROR: { status: 500, title: 'Internal Server Error' },
+    BAD_GATEWAY: { status: 502, title: 'Bad Gateway' },
+};

package/dist/errors/index.d.ts

@@ -0,0 +1,6 @@
+export * from './error-document.js';
+export * from './resolved-error.js';
+export * from './error-registry.js';
+export * from './jsonapi-error.js';
+export * from './to-error-document.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC"}

package/dist/errors/index.js

@@ -0,0 +1,5 @@
+export * from './error-document.js';
+export * from './resolved-error.js';
+export * from './error-registry.js';
+export * from './jsonapi-error.js';
+export * from './to-error-document.js';

package/dist/errors/jsonapi-error.d.ts

@@ -0,0 +1,27 @@
+import type { Meta } from '../primitives.js';
+import type { ErrorLinks, ErrorSource } from './error-document.js';
+import type { ErrorStatus } from './error-registry.js';
+/** The fields required to throw a {@link JsonApiError} - a registry entry plus its `code` and context. */
+export interface JsonApiErrorInit extends ErrorStatus {
+    code: string;
+    /** Human-readable, request-specific explanation; the error's `message` falls back to the title without one. */
+    detail?: string;
+    /** Where in the request the error originates. */
+    source?: ErrorSource;
+    /** A page about this occurrence, and a page about its type of problem. */
+    links?: ErrorLinks;
+    /** The data a client acts on that no other member carries. */
+    meta?: Meta;
+}
+/** A throwable error carrying the members of a JSON:API error object, which `onError` renders into a document. */
+export declare class JsonApiError extends Error {
+    readonly status: number;
+    readonly title: string;
+    readonly code: string;
+    readonly detail?: string;
+    readonly source?: ErrorSource;
+    readonly links?: ErrorLinks;
+    readonly meta?: Meta;
+    constructor(init: JsonApiErrorInit);
+}
+//# sourceMappingURL=jsonapi-error.d.ts.map

package/dist/errors/jsonapi-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonapi-error.d.ts","sourceRoot":"","sources":["../../src/errors/jsonapi-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,0GAA0G;AAC1G,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,+GAA+G;IAC/G,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AAED,kHAAkH;AAClH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;gBAET,IAAI,EAAE,gBAAgB;CAWnC"}

package/dist/errors/jsonapi-error.js

@@ -0,0 +1,21 @@
+/** A throwable error carrying the members of a JSON:API error object, which `onError` renders into a document. */
+export class JsonApiError extends Error {
+    status;
+    title;
+    code;
+    detail;
+    source;
+    links;
+    meta;
+    constructor(init) {
+        super(init.detail ?? init.title);
+        this.name = 'JsonApiError';
+        this.status = init.status;
+        this.title = init.title;
+        this.code = init.code;
+        this.detail = init.detail;
+        this.source = init.source;
+        this.links = init.links;
+        this.meta = init.meta;
+    }
+}

package/dist/errors/resolved-error.d.ts

@@ -0,0 +1,7 @@
+import type { ErrorObject } from './error-document.js';
+/** A resolved failure: the HTTP status to emit and the JSON:API error objects to render. */
+export interface ResolvedError {
+    status: number;
+    errors: ErrorObject[];
+}
+//# sourceMappingURL=resolved-error.d.ts.map

package/dist/errors/resolved-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolved-error.d.ts","sourceRoot":"","sources":["../../src/errors/resolved-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,4FAA4F;AAC5F,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB"}

package/dist/errors/resolved-error.js

@@ -0,0 +1 @@
+export {};

package/dist/errors/to-error-document.d.ts

@@ -0,0 +1,11 @@
+import { type ErrorDocument, type ErrorObject } from './error-document.js';
+import { JsonApiError } from './jsonapi-error.js';
+/** Projects a {@link JsonApiError} onto a JSON:API error object (status stringified per spec), each optional member where set. */
+export declare function toErrorObject(error: JsonApiError): ErrorObject;
+/**
+ * Renders one or more errors as a validated JSON:API error document, stamped with the spec version it is written to.
+ *
+ * @throws a `ZodError` on an empty array, which is not a legal error document
+ */
+export declare function toErrorDocument(errors: ErrorObject | JsonApiError | (ErrorObject | JsonApiError)[]): ErrorDocument;
+//# sourceMappingURL=to-error-document.d.ts.map

package/dist/errors/to-error-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-error-document.d.ts","sourceRoot":"","sources":["../../src/errors/to-error-document.ts"],"names":[],"mappings":"AACA,OAAO,EAAuB,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAChG,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,kIAAkI;AAClI,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,CAU9D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,GAAG,CAAC,WAAW,GAAG,YAAY,CAAC,EAAE,GAAG,aAAa,CAIlH"}