@zeroxsolutions/response 0.12.0

package/dist/errors/to-error-document.js

@@ -0,0 +1,25 @@
+import { JSON_API_VERSION } from '../media-type.js';
+import { errorDocumentSchema } 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 function toErrorObject(error) {
+    return {
+        ...(error.links !== undefined ? { links: error.links } : {}),
+        status: String(error.status),
+        code: error.code,
+        title: error.title,
+        ...(error.detail !== undefined ? { detail: error.detail } : {}),
+        ...(error.source !== undefined ? { source: error.source } : {}),
+        ...(error.meta !== undefined ? { meta: error.meta } : {}),
+    };
+}
+/**
+ * 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 function toErrorDocument(errors) {
+    const list = Array.isArray(errors) ? errors : [errors];
+    const objects = list.map((error) => (error instanceof JsonApiError ? toErrorObject(error) : error));
+    return errorDocumentSchema.parse({ errors: objects, jsonapi: { version: JSON_API_VERSION } });
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The response half of the HTTP contract, in the one wire spelling this house answers: a JSON:API document.
+ */
+export { errorResponse, listResponse, okResponse, type JsonApiResponse } from './api-response.js';
+export type { CollectionDocument, Relationship, ResourceDocument, ResourceObject } from './document.js';
+export { declaredDocumentShape, type DeclaredDocumentShape } from './document-shape.js';
+export { createDomainErrorResolver, defineErrorMap, errorEntry, type DomainErrorAnswer, type DomainErrorEntry, } from './domain-error-resolver.js';
+export type { DomainErrorMap, ErrorClass, UpstreamErrorMap } from './error-map.js';
+export { BASE_ERROR_CODES, errorDocumentSchema, JsonApiError, toErrorDocument, toErrorObject, type ErrorDocument, type ErrorLinks, type ErrorObject, type ErrorSource, type ErrorStatus, type JsonApiErrorInit, type ResolvedError, } from './errors/index.js';
+export { JSON_API_MEDIA_TYPE } from './media-type.js';
+export type { JsonApiObject, Link, Meta, PaginationLinks, ResourceIdentifier, ResourceLinks } from './primitives.js';
+export { toMany, toOne, type RelatedResource, type RelationshipDef } from './relationship.js';
+export { jsonApiResource, type JsonApiResource, type ResourceOptions } from './resource.js';
+export type { CollectionExtras, RequestedDocumentShape, ResourceSerializer, Row } from './serialize.js';
+export { createUpstreamErrorTranslator, type UpstreamErrorAnswer } from './upstream-error.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAClG,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACxG,OAAO,EAAE,qBAAqB,EAAE,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACxF,OAAO,EACL,yBAAyB,EACzB,cAAc,EACd,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrH,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC9F,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC5F,YAAY,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AACxG,OAAO,EAAE,6BAA6B,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * The response half of the HTTP contract, in the one wire spelling this house answers: a JSON:API document.
+ */
+export { errorResponse, listResponse, okResponse } from './api-response.js';
+export { declaredDocumentShape } from './document-shape.js';
+export { createDomainErrorResolver, defineErrorMap, errorEntry, } from './domain-error-resolver.js';
+export { BASE_ERROR_CODES, errorDocumentSchema, JsonApiError, toErrorDocument, toErrorObject, } from './errors/index.js';
+export { JSON_API_MEDIA_TYPE } from './media-type.js';
+export { toMany, toOne } from './relationship.js';
+export { jsonApiResource } from './resource.js';
+export { createUpstreamErrorTranslator } from './upstream-error.js';

package/dist/media-type.d.ts

@@ -0,0 +1,5 @@
+/** The JSON:API media type - the one every response of this spelling is served as. */
+export declare const JSON_API_MEDIA_TYPE = "application/vnd.api+json";
+/** The spec version every document this package emits is written to; ts-japi's own default is `1.0`. */
+export declare const JSON_API_VERSION = "1.1";
+//# sourceMappingURL=media-type.d.ts.map

package/dist/media-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-type.d.ts","sourceRoot":"","sources":["../src/media-type.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,eAAO,MAAM,mBAAmB,6BAA6B,CAAC;AAE9D,wGAAwG;AACxG,eAAO,MAAM,gBAAgB,QAAQ,CAAC"}

package/dist/media-type.js

@@ -0,0 +1,4 @@
+/** The JSON:API media type - the one every response of this spelling is served as. */
+export const JSON_API_MEDIA_TYPE = 'application/vnd.api+json';
+/** The spec version every document this package emits is written to; ts-japi's own default is `1.0`. */
+export const JSON_API_VERSION = '1.1';

package/dist/primitives.d.ts

@@ -0,0 +1,161 @@
+import { z } from 'zod';
+/** The free-form JSON:API `meta` member - any JSON object. */
+export declare const metaSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/** A free-form `meta` member - inferred from {@link metaSchema}. */
+export type Meta = z.infer<typeof metaSchema>;
+/** A JSON:API link - a URI-reference, a link object, or `null` where the link does not exist. */
+export declare const linkSchema: 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]>;
+/** A JSON:API link value - inferred from {@link linkSchema}. */
+export type Link = z.infer<typeof linkSchema>;
+/** The `self`/`related` pair a resource object and a relationship both carry. */
+export declare const resourceLinksSchema: 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]>>;
+    related: 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>;
+/** A resource object's links - inferred from {@link resourceLinksSchema}. */
+export type ResourceLinks = z.infer<typeof resourceLinksSchema>;
+/** Collection pagination links: `self` plus the `first`/`prev`/`next`/`last` navigation, each null at the page that has none. */
+export declare const paginationLinksSchema: 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]>>;
+    first: 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]>>;
+    prev: 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]>>;
+    next: 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]>>;
+    last: 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>;
+/** Collection pagination links - inferred from {@link paginationLinksSchema}. */
+export type PaginationLinks = z.infer<typeof paginationLinksSchema>;
+/** A resource identifier object - the `{ type, id }` linkage that points at another resource. */
+export declare const resourceIdentifierSchema: z.ZodObject<{
+    type: z.ZodString;
+    id: z.ZodString;
+}, z.core.$strip>;
+/** A type-and-id resource identifier - inferred from {@link resourceIdentifierSchema}. */
+export type ResourceIdentifier = z.infer<typeof resourceIdentifierSchema>;
+/** The top-level `jsonapi` member - the spec version this document is written to, plus meta. */
+export declare const jsonApiObjectSchema: z.ZodObject<{
+    version: z.ZodOptional<z.ZodString>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/** The top-level `jsonapi` member - inferred from {@link jsonApiObjectSchema}. */
+export type JsonApiObject = z.infer<typeof jsonApiObjectSchema>;
+//# sourceMappingURL=primitives.d.ts.map

package/dist/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../src/primitives.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8DAA8D;AAC9D,eAAO,MAAM,UAAU,wCAAoC,CAAC;AAC5D,oEAAoE;AACpE,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAsB9C,iGAAiG;AACjG,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;8BAIrB,CAAC;AACH,gEAAgE;AAChE,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAE9C,iFAAiF;AACjF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAG9B,CAAC;AACH,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,iIAAiI;AACjI,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAMhC,CAAC;AACH,iFAAiF;AACjF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,iGAAiG;AACjG,eAAO,MAAM,wBAAwB;;;iBAAiD,CAAC;AACvF,0FAA0F;AAC1F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,gGAAgG;AAChG,eAAO,MAAM,mBAAmB;;;iBAG9B,CAAC;AACH,kFAAkF;AAClF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/primitives.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+/** The free-form JSON:API `meta` member - any JSON object. */
+export const metaSchema = z.record(z.string(), z.unknown());
+/** Everything a link object may say about its target except where it points and what describes it. */
+const linkTarget = {
+    /** The link's relation type - a registered or extension relation, per RFC 8288. */
+    rel: z.string().optional(),
+    title: z.string().optional(),
+    /** The media type of the target. */
+    type: z.string().optional(),
+    hreflang: z.union([z.string(), z.array(z.string())]).optional(),
+    meta: metaSchema.optional(),
+};
+/**
+ * The description document a link points at - a link itself, minus a `describedby` of its own.
+ *
+ * The standard nests these without limit, which a schema can only express through `z.lazy`. A lazy member renders as a
+ * `$defs` ref that the OpenAPI document has nowhere to resolve, and the gateway serving it answers 500
+ * (@hono/zod-openapi@1.4.0) - so the cycle stops at one level, which is every document anyone writes.
+ */
+const describedbySchema = z.union([z.string(), z.object({ href: z.string(), ...linkTarget }), z.null()]);
+/** A JSON:API link - a URI-reference, a link object, or `null` where the link does not exist. */
+export const linkSchema = z.union([
+    z.string(),
+    z.object({ href: z.string(), describedby: describedbySchema.optional(), ...linkTarget }),
+    z.null(),
+]);
+/** The `self`/`related` pair a resource object and a relationship both carry. */
+export const resourceLinksSchema = z.object({
+    self: linkSchema.optional(),
+    related: linkSchema.optional(),
+});
+/** Collection pagination links: `self` plus the `first`/`prev`/`next`/`last` navigation, each null at the page that has none. */
+export const paginationLinksSchema = z.object({
+    self: linkSchema.optional(),
+    first: linkSchema.optional(),
+    prev: linkSchema.optional(),
+    next: linkSchema.optional(),
+    last: linkSchema.optional(),
+});
+/** A resource identifier object - the `{ type, id }` linkage that points at another resource. */
+export const resourceIdentifierSchema = z.object({ type: z.string(), id: z.string() });
+/** The top-level `jsonapi` member - the spec version this document is written to, plus meta. */
+export const jsonApiObjectSchema = z.object({
+    version: z.string().optional(),
+    meta: metaSchema.optional(),
+});

package/dist/relationship.d.ts

@@ -0,0 +1,37 @@
+import type { ZodObject, ZodType } from 'zod';
+import type { RequestedDocumentShape, ResourceSerializer, Row } from './serialize.js';
+/** What a relationship needs from the resource it points at, so this module never imports the descriptor. */
+export interface RelatedResource {
+    readonly type: string;
+    readonly relationships: Readonly<Record<string, RelationshipDef>>;
+    /** This type's declared attributes - the keys are the projection, so they are also what a fieldset may name. */
+    readonly attributes: ZodObject;
+    /** This type's resource object schema - what a document validates its `data` and `included` against. */
+    readonly resourceObject: ZodType;
+    /** This type's serializer under one request, which is what carries a sparse fieldset into `included`. */
+    serializerFor(requested?: RequestedDocumentShape): ResourceSerializer;
+}
+/** A relationship: the resource it points at, how many, and how to read it off a row. */
+export interface RelationshipDef {
+    readonly cardinality: 'one' | 'many';
+    /** A thunk, so two resources may name each other without a module-evaluation cycle. */
+    readonly related: () => RelatedResource;
+    /** Reads the related row(s) off the primary row; what ts-japi's `Relator` fetches. */
+    readonly read: (row: Row) => unknown;
+}
+/** Declares a to-one relationship - its `data` is a single identifier, or null. */
+export declare function toOne(related: () => RelatedResource, read: (row: Row) => unknown): RelationshipDef;
+/** Declares a to-many relationship - its `data` is an array of identifiers. */
+export declare function toMany(related: () => RelatedResource, read: (row: Row) => unknown): RelationshipDef;
+/** The linkage schema for one relationship, pinned to the related `type` so a wrong type fails the parse. */
+export declare function relationshipSchema(def: RelationshipDef): ZodType;
+/** The `relationships` member for a whole resource - one key per declaration, absent when it declares none. */
+export declare function relationshipsSchema(relationships: Readonly<Record<string, RelationshipDef>>): ZodType | undefined;
+/**
+ * Every resource reachable from `root` through its relationships, `root` first, each visited once.
+ *
+ * This is what calls the thunks, so it runs on first use rather than at declaration - two resources naming
+ * each other are both defined by then, which is the whole reason the declaration holds a thunk.
+ */
+export declare function reachableResources(root: RelatedResource): RelatedResource[];
+//# sourceMappingURL=relationship.d.ts.map

package/dist/relationship.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship.d.ts","sourceRoot":"","sources":["../src/relationship.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAE9C,OAAO,KAAK,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAEtF,6GAA6G;AAC7G,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;IAClE,gHAAgH;IAChH,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,wGAAwG;IACxG,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,yGAAyG;IACzG,aAAa,CAAC,SAAS,CAAC,EAAE,sBAAsB,GAAG,kBAAkB,CAAC;CACvE;AAED,yFAAyF;AACzF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,KAAK,GAAG,MAAM,CAAC;IACrC,uFAAuF;IACvF,QAAQ,CAAC,OAAO,EAAE,MAAM,eAAe,CAAC;IACxC,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC;CACtC;AAED,mFAAmF;AACnF,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,eAAe,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,GAAG,eAAe,CAElG;AAED,+EAA+E;AAC/E,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,eAAe,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,GAAG,eAAe,CAEnG;AAED,6GAA6G;AAC7G,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAOhE;AAED,+GAA+G;AAC/G,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,GACvD,OAAO,GAAG,SAAS,CAIrB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,eAAe,EAAE,CAS3E"}

package/dist/relationship.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { metaSchema, resourceIdentifierSchema, resourceLinksSchema } from './primitives.js';
+/** Declares a to-one relationship - its `data` is a single identifier, or null. */
+export function toOne(related, read) {
+    return { cardinality: 'one', related, read };
+}
+/** Declares a to-many relationship - its `data` is an array of identifiers. */
+export function toMany(related, read) {
+    return { cardinality: 'many', related, read };
+}
+/** The linkage schema for one relationship, pinned to the related `type` so a wrong type fails the parse. */
+export function relationshipSchema(def) {
+    const identifier = resourceIdentifierSchema.extend({ type: z.literal(def.related().type) });
+    return z.object({
+        data: (def.cardinality === 'one' ? identifier.nullable() : z.array(identifier)).optional(),
+        links: resourceLinksSchema.optional(),
+        meta: metaSchema.optional(),
+    });
+}
+/** The `relationships` member for a whole resource - one key per declaration, absent when it declares none. */
+export function relationshipsSchema(relationships) {
+    const entries = Object.entries(relationships);
+    if (entries.length === 0)
+        return undefined;
+    return z.object(Object.fromEntries(entries.map(([name, def]) => [name, relationshipSchema(def).optional()])));
+}
+/**
+ * Every resource reachable from `root` through its relationships, `root` first, each visited once.
+ *
+ * This is what calls the thunks, so it runs on first use rather than at declaration - two resources naming
+ * each other are both defined by then, which is the whole reason the declaration holds a thunk.
+ */
+export function reachableResources(root) {
+    const seen = new Map();
+    const visit = (resource) => {
+        if (seen.has(resource.type))
+            return;
+        seen.set(resource.type, resource);
+        for (const def of Object.values(resource.relationships))
+            visit(def.related());
+    };
+    visit(root);
+    return [...seen.values()];
+}

package/dist/resource.d.ts

@@ -0,0 +1,35 @@
+import type { output, ZodObject, ZodType } from 'zod';
+import { type CollectionDocument, type ResourceDocument } from './document.js';
+import type { RelatedResource, RelationshipDef } from './relationship.js';
+import { type CollectionExtras, type RequestedDocumentShape, type Row } from './serialize.js';
+/** Per-entity overrides for a resource declaration. */
+export interface ResourceOptions {
+    /** Relationships this resource declares, keyed by the member name they take in `relationships`. */
+    relationships?: Readonly<Record<string, RelationshipDef>>;
+}
+/**
+ * One resource type declared once: the schemas a route answers with, and the serializer that produces
+ * them. A route's `responses` and its handler's document come off this same value, so the document the
+ * handler emits is the one the route advertises.
+ *
+ * Its schemas are lazy getters because a relationship holds a THUNK: two resources may name each other,
+ * and the graph is only walkable once every module has evaluated.
+ */
+export interface JsonApiResource<A extends ZodObject> extends RelatedResource {
+    readonly attributes: A;
+    /** The single-resource document schema - `{ data, included?, links?, meta?, jsonapi? }`. */
+    readonly document: ZodType<ResourceDocument<output<A>>>;
+    /** The collection document schema - the same members with `data` an array. */
+    readonly collectionDocument: ZodType<CollectionDocument<output<A>>>;
+    /**
+     * Serializes one row into a single-resource document.
+     *
+     * @param requested - a sparse fieldset drops attributes at RUNTIME that the declared type still names.
+     */
+    serialize(row: Row, requested?: RequestedDocumentShape): Promise<ResourceDocument<output<A>>>;
+    /** Serializes rows into a collection document, merging in pagination `links` and `meta`. */
+    serializeMany(rows: Row[], extras?: CollectionExtras, requested?: RequestedDocumentShape): Promise<CollectionDocument<output<A>>>;
+}
+/** Declares a JSON:API resource type - its `type`, the schema of its `attributes`, and its relationships. */
+export declare function jsonApiResource<A extends ZodObject>(type: string, attributes: A, options?: ResourceOptions): JsonApiResource<A>;
+//# sourceMappingURL=resource.d.ts.map

package/dist/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACtD,OAAO,EAIL,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAE3B,KAAK,GAAG,EACT,MAAM,gBAAgB,CAAC;AAExB,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,mGAAmG;IACnG,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;CAC3D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,SAAS,CAAE,SAAQ,eAAe;IAC3E,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IACvB,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,8EAA8E;IAC9E,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9F,4FAA4F;IAC5F,aAAa,CACX,IAAI,EAAE,GAAG,EAAE,EACX,MAAM,CAAC,EAAE,gBAAgB,EACzB,SAAS,CAAC,EAAE,sBAAsB,GACjC,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC3C;AAgBD,6GAA6G;AAC7G,wBAAgB,eAAe,CAAC,CAAC,SAAS,SAAS,EACjD,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,CAAC,EACb,OAAO,GAAE,eAAoB,GAC5B,eAAe,CAAC,CAAC,CAAC,CA0DpB"}

package/dist/resource.js

@@ -0,0 +1,63 @@
+import { Relator } from 'ts-japi';
+import { collectionDocumentSchema, resourceDocumentSchema, resourceObjectSchema, } from './document.js';
+import { createSerializer, serializeCollection, serializeResource, } from './serialize.js';
+/**
+ * How many requested shapes one resource keeps a serializer for. The shape is spelled by the caller's
+ * query, so past this bound a serializer is built for the call and not kept.
+ */
+const MAX_KEPT_SERIALIZERS = 64;
+/**
+ * The cache key for a requested shape: its content, not its identity. A route parses a fresh object on
+ * every request, so an identity key keeps one serializer per request for the life of the process.
+ */
+function shapeKey(requested) {
+    return JSON.stringify([requested?.fields ?? null, requested?.include ?? null]);
+}
+/** Declares a JSON:API resource type - its `type`, the schema of its `attributes`, and its relationships. */
+export function jsonApiResource(type, attributes, options = {}) {
+    const relationships = options.relationships ?? {};
+    // The attribute keys ARE the projection, so a row member the schema does not declare never reaches the wire.
+    const projection = Object.fromEntries(Object.keys(attributes.shape).map((name) => [name, 1]));
+    const serializers = new Map();
+    let object;
+    let one;
+    let many;
+    const resource = {
+        type,
+        attributes,
+        relationships,
+        get resourceObject() {
+            return (object ??= resourceObjectSchema(type, attributes, relationships));
+        },
+        get document() {
+            return (one ??= resourceDocumentSchema(resource));
+        },
+        get collectionDocument() {
+            return (many ??= collectionDocumentSchema(resource));
+        },
+        serializerFor(requested) {
+            const key = shapeKey(requested);
+            const built = serializers.get(key);
+            if (built)
+                return built;
+            const relators = Object.fromEntries(Object.entries(relationships).map(([name, def]) => [
+                name,
+                new Relator(async (row) => def.read(row), 
+                // The lazy overload, so a pair of resources naming each other resolves on use, not on construction.
+                () => def.related().serializerFor(requested), { relatedName: name }),
+            ]));
+            const serializer = createSerializer(type, { projection, relators }, requested);
+            if (serializers.size < MAX_KEPT_SERIALIZERS)
+                serializers.set(key, serializer);
+            return serializer;
+        },
+        serialize(row, requested) {
+            // ts-japi hands back an untyped object; the declared attributes are this resource's own schema.
+            return serializeResource(resource.serializerFor(requested), row);
+        },
+        serializeMany(rows, extras, requested) {
+            return serializeCollection(resource.serializerFor(requested), rows, extras);
+        },
+    };
+    return resource;
+}

package/dist/serialize.d.ts

@@ -0,0 +1,44 @@
+import { Serializer, type SerializerOptions } from 'ts-japi';
+import type { PaginationLinks } from './primitives.js';
+/** One row as a serializer hands it over - the shape ts-japi works in. */
+export type Row = Record<string, unknown>;
+/** A ts-japi serializer over rows. */
+export type ResourceSerializer = Serializer<Row>;
+type SerializerConfig = Partial<SerializerOptions<Row>>;
+/**
+ * The half of a parsed list query that shapes the response document, spelled with
+ * `@zeroxsolutions/query`'s own member names so its parse result passes straight through; structural
+ * rather than imported, because the dependency would be one-way and for two keys.
+ */
+export interface RequestedDocumentShape {
+    /** Sparse fieldsets keyed by resource type. A type absent here is unrestricted. */
+    fields?: Readonly<Record<string, readonly string[]>>;
+    /** Relationship paths to include. Absent means a flat document. */
+    include?: readonly string[];
+}
+/**
+ * A ts-japi serializer for a resource `type`, narrowed to the request's sparse fieldset and traversing
+ * the relationship paths it asked to include - both halves of a resource's fields, since the standard
+ * calls attributes and relationships alike its fields.
+ *
+ * The shape is applied by CONSTRUCTING the serializer, never by handing options to `serialize()`: in
+ * ts-japi 1.12.3 a narrower projection passed there leaves the constructed one in force and narrows
+ * nothing.
+ */
+export declare function createSerializer(type: string, options?: SerializerConfig, requested?: RequestedDocumentShape): ResourceSerializer;
+/** Request-derived top-level members merged into a collection document. */
+export interface CollectionExtras {
+    links?: PaginationLinks;
+    /** The document's top-level `meta`. */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Serializes one row into a single-resource document.
+ *
+ * @param data - the row to serialize; its `id` member becomes the resource id
+ */
+export declare function serializeResource(serializer: ResourceSerializer, data: Row): Promise<Row>;
+/** Serializes a list of rows into a collection document, merging in the pagination `links` and `meta`. */
+export declare function serializeCollection(serializer: ResourceSerializer, items: Row[], extras?: CollectionExtras): Promise<Row>;
+export {};
+//# sourceMappingURL=serialize.d.ts.map

package/dist/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,0EAA0E;AAC1E,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C,sCAAsC;AACtC,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;AAEjD,KAAK,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC;AAExD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,mFAAmF;IACnF,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IACrD,mEAAmE;IACnE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAgCD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,gBAAgB,EAC1B,SAAS,CAAC,EAAE,sBAAsB,GACjC,kBAAkB,CAgBpB;AAED,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAQD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,UAAU,EAAE,kBAAkB,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAE/F;AAED,0GAA0G;AAC1G,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,kBAAkB,EAC9B,KAAK,EAAE,GAAG,EAAE,EACZ,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CAAC,GAAG,CAAC,CAMd"}

package/dist/serialize.js

@@ -0,0 +1,77 @@
+import { Relator, Serializer } from 'ts-japi';
+import { JSON_API_VERSION } from './media-type.js';
+/**
+ * Whether the static projection publishes `name`, read so that a `0` counts as hidden under either mode.
+ *
+ * ts-japi 1.12.3 honours an all-`1` projection as a whitelist and an all-`0` one as a blacklist, but a
+ * MIXED one as neither: `{a:1,b:0}` emits both `a` and `b`. A `0` is answered `false` here regardless, so
+ * the projection built below is only ever a whitelist.
+ *
+ * An EMPTY projection emits no attribute at all in that version, so it is a whitelist of nothing rather
+ * than a blacklist of nothing - which is why the blacklist reading below requires the projection to list
+ * something.
+ */
+function publishes(projection, name) {
+    if (projection == null)
+        return true;
+    if (projection[name] === 0)
+        return false;
+    if (projection[name] === 1)
+        return true;
+    const configured = Object.values(projection);
+    return configured.length > 0 && configured.every((value) => value !== 1);
+}
+/** Keeps the named relators, preserving whichever of ts-japi's three forms was given. */
+function narrowRelators(relators, permitted) {
+    if (relators === undefined)
+        return undefined;
+    if (Array.isArray(relators))
+        return relators.filter((one) => permitted.has(one.relatedName));
+    if (relators instanceof Relator)
+        return permitted.has(relators.relatedName) ? relators : undefined;
+    return Object.fromEntries(Object.entries(relators).filter(([name]) => permitted.has(name)));
+}
+/**
+ * A ts-japi serializer for a resource `type`, narrowed to the request's sparse fieldset and traversing
+ * the relationship paths it asked to include - both halves of a resource's fields, since the standard
+ * calls attributes and relationships alike its fields.
+ *
+ * The shape is applied by CONSTRUCTING the serializer, never by handing options to `serialize()`: in
+ * ts-japi 1.12.3 a narrower projection passed there leaves the constructed one in force and narrows
+ * nothing.
+ */
+export function createSerializer(type, options, requested) {
+    const fields = requested?.fields?.[type];
+    const include = requested?.include;
+    return new Serializer(type, {
+        ...options,
+        ...(include === undefined ? {} : { include: [...include] }),
+        ...(fields === undefined
+            ? {}
+            : {
+                projection: Object.fromEntries(fields.filter((name) => publishes(options?.projection, name)).map((name) => [name, 1])),
+                relators: narrowRelators(options?.relators, new Set(fields)),
+            }),
+    });
+}
+/** Raises the `jsonapi` member to {@link JSON_API_VERSION}, keeping whatever else ts-japi put there. */
+function stamped(doc) {
+    const existing = (doc.jsonapi ?? {});
+    return { ...doc, jsonapi: { ...existing, version: JSON_API_VERSION } };
+}
+/**
+ * Serializes one row into a single-resource document.
+ *
+ * @param data - the row to serialize; its `id` member becomes the resource id
+ */
+export async function serializeResource(serializer, data) {
+    return stamped((await serializer.serialize(data)));
+}
+/** Serializes a list of rows into a collection document, merging in the pagination `links` and `meta`. */
+export async function serializeCollection(serializer, items, extras = {}) {
+    return {
+        ...stamped((await serializer.serialize(items))),
+        ...(extras.links ? { links: extras.links } : {}),
+        ...(extras.meta ? { meta: extras.meta } : {}),
+    };
+}