@zeroxsolutions/response 0.14.2 → 0.14.3

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 0.14.3 (2026-09-30)
+
+### 🚀 Features
+
+- **response:** declare a write's request document off its resource ([3eea112](https://github.com/zeroxsolutions/zeroxsolutions/commit/3eea112))
+
+### 🩹 Fixes
+
+- **response:** refuse an update that names an attribute with a default ([4e9ee0a](https://github.com/zeroxsolutions/zeroxsolutions/commit/4e9ee0a))
+- **response:** accept the request members JSON:API defines ([35e8395](https://github.com/zeroxsolutions/zeroxsolutions/commit/35e8395))
+
+### ❤️ Thank You
+
+- Claude Opus 5.5 (1M context)
+- Lương Văn Tú
+
 ## 0.14.2 (2026-09-29)
 
 ### 🩹 Fixes

package/README.md

@@ -271,6 +271,42 @@ It locates each issue by the slot it was read from: a body member as `source.poi
 `source.parameter`, a header as `source.header`. A path segment gets `meta` instead - the spec defines
 those three members and none of them means a path segment, so borrowing one would say something false.
 
+## A request document
+
+A write's body is declared off the same resource the route answers with, so the document a client reads
+and the one it writes cannot drift:
+
+```ts
+import { readRequestDocument, requestDocumentSchema } from '@zeroxsolutions/response';
+
+export const createItemDocument = requestDocumentSchema(itemResource, 'create', {
+  attributes: ['startsAt', 'durationMinutes'],
+  relationships: ['place'],
+});
+
+// in the handler; relationships.place is the id the linkage named, or null
+const { attributes, relationships } = readRequestDocument(c.req.valid('json'));
+```
+
+`attributes` and `relationships` name what a client may write, checked against the resource at compile
+time. A `'create'` requires `data.type`, refuses `data.id`, and keeps each named attribute as optional as
+its schema makes it; it requires `attributes` itself only where one named attribute is required. An `'update'` requires `data.type` and `data.id`, and every member is optional: a
+missing one keeps its current value. So an update throws when it is declared if it names an attribute
+whose schema fills a value for a missing key - a `.default()`, a `.prefault()` or a `.catch()`, beneath
+any wrapper - since the fill would overwrite the stored value; drop the default from the resource's
+attribute, or leave the attribute out of the update. An attribute whose schema is async is not checked,
+since a sync parse cannot run it. The schema throws `RequestConflict` for a `type` other than the
+endpoint's, and `RequestForbidden` for a client id on a create or a member the route does not write. It
+throws from its first step, out of `safeParse` as well, so `@zeroxsolutions/server`'s error handler
+answers them 409 and 403. A member that fails its own schema stays the validation hook's 422, at
+`/data/attributes/<name>`. On an update, `readRequestDocument(document, { id })` throws `RequestConflict`
+when `data.id` is not the id the URL names.
+
+The other members JSON:API 1.1 defines for a request are accepted, and nothing reads them: `lid`, `meta`
+and `links` on the resource object, `meta` and `links` on a relationship object, `lid` and `meta` on an
+identifier, and the top-level `meta` and `jsonapi`. A member the standard does not define still fails the
+schema, so it is a 422.
+
 ## Exports
 
 One root, no subpath, and `src/index.ts` lists every name it publishes:
@@ -281,6 +317,8 @@ One root, no subpath, and `src/index.ts` lists every name it publishes:
   passes to `listResponse`;
 - the resource declaration - `jsonApiResource`, `toOne` / `toMany`, `declaredDocumentShape` - and the
   types their signatures name;
+- the request document - `requestDocumentSchema`, `readRequestDocument`, the types their signatures name,
+  and `RequestConflict` / `RequestForbidden`, which its checks throw;
 - the error document's types, `JsonApiError`, `BASE_ERROR_CODES`, `toErrorObject` / `toErrorDocument`;
 - `defineErrorMap` / `errorEntry` / `createDomainErrorResolver` and `createUpstreamErrorTranslator`, with
   the answer, entry and map types they take;

package/dist/index.d.ts

@@ -16,4 +16,6 @@ export { toMany, toOne, type LoadContextArguments, type RelatedResource, type Re
 export { jsonApiResource, type JsonApiResource, type ResourceOptions } from './resource.js';
 export type { CollectionExtras, LoadedRows, RequestedDocumentShape, ResourceSerializer, Row } from './serialize.js';
 export { createUpstreamErrorTranslator, type UpstreamErrorAnswer } from './upstream-error.js';
+export { readRequestDocument, requestDocumentSchema, type AttributeName, type ReadRequestDocument, type RelationshipName, type RequestDocument, type RequestDocumentSchema, type RequestMode, type WritableResource, } from './request-document.js';
+export { RequestConflict, RequestForbidden } from './request-refusal.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,aAAa,EACb,YAAY,EACZ,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,YAAY,EACZ,gBAAgB,EAChB,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,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,OAAO,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AAC3F,YAAY,EACV,aAAa,EACb,IAAI,EACJ,IAAI,EACJ,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,MAAM,EACN,KAAK,EACL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC5F,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AACpH,OAAO,EAAE,6BAA6B,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,aAAa,EACb,YAAY,EACZ,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,YAAY,EACZ,gBAAgB,EAChB,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,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,OAAO,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AAC3F,YAAY,EACV,aAAa,EACb,IAAI,EACJ,IAAI,EACJ,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,MAAM,EACN,KAAK,EACL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC5F,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AACpH,OAAO,EAAE,6BAA6B,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,WAAW,EAChB,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -12,3 +12,5 @@ export { countedCollectionMetaSchema, offsetPaginationLinksSchema } from './prim
 export { toMany, toOne, } from './relationship.js';
 export { jsonApiResource } from './resource.js';
 export { createUpstreamErrorTranslator } from './upstream-error.js';
+export { readRequestDocument, requestDocumentSchema, } from './request-document.js';
+export { RequestConflict, RequestForbidden } from './request-refusal.js';

package/dist/relationship.d.ts

@@ -61,10 +61,16 @@ export interface RelationshipDef<C = unknown, R extends RelatedResource<never> =
  *
  * The context is inferred from the loader and from the related resource. An explicit `toOne<Ctx>(...)`
  * would stop TypeScript inferring the related resource, which then widens and drops every literal below it.
+ *
+ * Its cardinality is the literal 'one', so a request document typed off the declaration tells a to-one from a to-many.
  */
-export declare function toOne<const R extends RelatedResource<never>, C = ContextOf<R>>(related: () => R, read: (row: Row) => unknown, options?: RelationshipOptions<C>): RelationshipDef<NoInfer<C>, R>;
+export declare function toOne<const R extends RelatedResource<never>, C = ContextOf<R>>(related: () => R, read: (row: Row) => unknown, options?: RelationshipOptions<C>): RelationshipDef<NoInfer<C>, R> & {
+    readonly cardinality: 'one';
+};
 /** Declares a to-many relationship - its `data` is an array of identifiers. The context is inferred as for `toOne`. */
-export declare function toMany<const R extends RelatedResource<never>, C = ContextOf<R>>(related: () => R, read: (row: Row) => unknown, options?: RelationshipOptions<C>): RelationshipDef<NoInfer<C>, R>;
+export declare function toMany<const R extends RelatedResource<never>, C = ContextOf<R>>(related: () => R, read: (row: Row) => unknown, options?: RelationshipOptions<C>): RelationshipDef<NoInfer<C>, R> & {
+    readonly cardinality: 'many';
+};
 /** The linkage schema for one relationship, pinned to the related `type` so a wrong type fails the parse. */
 export declare function relationshipSchema<C>(def: RelationshipDef<C>): ZodType;
 /** The `relationships` member for a whole resource - one key per declaration, absent when it declares none. */

package/dist/relationship.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationship.d.ts","sourceRoot":"","sources":["../src/relationship.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"relationship.d.ts","sourceRoot":"","sources":["../src/relationship.ts"],"names":[],"mappings":"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"}

package/dist/relationship.js

@@ -10,6 +10,8 @@ export function loadContext(contextArguments) {
  *
  * The context is inferred from the loader and from the related resource. An explicit `toOne<Ctx>(...)`
  * would stop TypeScript inferring the related resource, which then widens and drops every literal below it.
+ *
+ * Its cardinality is the literal 'one', so a request document typed off the declaration tells a to-one from a to-many.
  */
 export function toOne(related, read, options) {
     return { cardinality: 'one', related, read, load: options?.load };

package/dist/request-document.d.ts

@@ -0,0 +1,183 @@
+import type { input, output, ZodObject, ZodType } from 'zod';
+import { type JsonApiObject, type Meta, type RelationshipLinks, type ResourceIdentifier, type ResourceLinks } from './primitives.js';
+/** Whether a request document creates its resource, or updates the one its URL names. */
+export type RequestMode = 'create' | 'update';
+/** What a request document needs of a relationship: how many it holds, and the type it points at. */
+interface WritableRelationship {
+    readonly cardinality: 'one' | 'many';
+    readonly related: () => {
+        readonly type: string;
+    };
+}
+/** What a request document needs of a resource declaration - every `jsonApiResource` is one. */
+export interface WritableResource {
+    readonly type: string;
+    readonly attributes: ZodObject;
+    readonly relationships: Readonly<Record<string, WritableRelationship>>;
+}
+/** The attribute names a resource declares. */
+export type AttributeName<R extends WritableResource> = keyof R['attributes']['shape'] & string;
+/** The relationship names a resource declares, and none where it declares no relationship. */
+export type RelationshipName<R extends WritableResource> = string extends keyof R['relationships'] ? never : keyof R['relationships'] & string;
+/** Which side of the schema a document type describes: what a client sends, or what a handler reads. */
+type Side = 'input' | 'output';
+/** `T`'s members named in `K`, each keeping the optionality `T` gives it. */
+type PickMembers<T, K> = {
+    [P in keyof T as P extends K ? P : never]: T[P];
+};
+type AttributesOf<R extends WritableResource, K, M extends RequestMode, S extends Side> = M extends 'update' ? Partial<PickMembers<S extends 'input' ? input<R['attributes']> : output<R['attributes']>, K>> : PickMembers<S extends 'input' ? input<R['attributes']> : output<R['attributes']>, K>;
+/**
+ * The identifier a relationship's linkage carries, typed by the resource it points at. Its `lid` and `meta` are
+ * members JSON:API 1.1 allows, which the schema accepts and nothing reads.
+ */
+type IdentifierOf<D> = D extends {
+    related: () => {
+        type: infer T extends string;
+    };
+} ? {
+    type: T;
+    id: string;
+    lid?: string;
+    meta?: Meta;
+} : never;
+/** The members JSON:API 1.1 lets a relationship object carry beside its `data`, accepted and never read. */
+interface LinkageExtras {
+    meta?: Meta;
+    links?: RelationshipLinks;
+}
+/** A relationship as a request writes it: a to-one's identifier or `null`, a to-many's identifiers. */
+type LinkageOf<D> = (D extends {
+    cardinality: 'many';
+} ? {
+    data: readonly IdentifierOf<D>[];
+} : D extends {
+    cardinality: 'one';
+} ? {
+    data: IdentifierOf<D> | null;
+} : {
+    data: IdentifierOf<D> | readonly IdentifierOf<D>[] | null;
+}) & LinkageExtras;
+type LinkagesOf<R extends WritableResource, K extends RelationshipName<R>, M extends RequestMode> = M extends 'update' ? {
+    [P in K]?: LinkageOf<R['relationships'][P]>;
+} : {
+    [P in K]: LinkageOf<R['relationships'][P]>;
+};
+/** A member a route names nothing under, or any member of an update, may be left out; a create sends what it names. */
+type Member<N extends string, K, V, M extends RequestMode> = [K] extends [never] ? {
+    [P in N]?: V;
+} : M extends 'update' ? {
+    [P in N]?: V;
+} : {
+    [P in N]: V;
+};
+/**
+ * A create's `attributes`, which it sends only where one attribute it names is required: JSON:API makes the member
+ * optional, so a create whose named attributes are all optional may leave it out.
+ */
+type AttributesMember<R extends WritableResource, AK, M extends RequestMode, S extends Side> = Record<never, never> extends PickMembers<input<R['attributes']>, AK> ? {
+    attributes?: AttributesOf<R, AK, M, S>;
+} : Member<'attributes', AK, AttributesOf<R, AK, M, S>, M>;
+/** The members JSON:API 1.1 lets a resource object carry beside its type, id and fields, accepted and never read. */
+interface ResourceObjectExtras {
+    lid?: string;
+    meta?: Meta;
+    links?: ResourceLinks;
+}
+/**
+ * The request document a route declares for `R`: one resource object under `data`, the attributes it names under
+ * `attributes`, and each relationship it names as a relationship object. `S` picks what a client sends (`'input'`) or
+ * what the handler reads (`'output'`).
+ */
+export type RequestDocument<R extends WritableResource, M extends RequestMode, AK extends AttributeName<R> = never, RK extends RelationshipName<R> = never, S extends Side = 'output'> = {
+    data: {
+        type: R['type'];
+    } & ResourceObjectExtras & (M extends 'update' ? {
+        id: string;
+    } : {
+        id?: never;
+    }) & AttributesMember<R, AK, M, S> & Member<'relationships', RK, LinkagesOf<R, RK, M>, M>;
+    meta?: Meta;
+    jsonapi?: JsonApiObject;
+};
+/** The schema {@link requestDocumentSchema} builds: it reads what a client sends into what a handler reads. */
+export type RequestDocumentSchema<R extends WritableResource, M extends RequestMode, AK extends AttributeName<R>, RK extends RelationshipName<R>> = ZodType<RequestDocument<R, M, AK, RK, 'output'>, RequestDocument<R, M, AK, RK, 'input'>>;
+/**
+ * The body schema of a write, built from the same resource declaration the route answers with, so the document a
+ * client reads and the one it writes cannot drift.
+ *
+ * `'create'` requires `data.type`, refuses `data.id`, keeps each named attribute as optional as its schema makes it,
+ * and requires each named relationship (a to-one left empty is sent as `{ data: null }`). It requires `attributes`
+ * itself only where one named attribute is required, since JSON:API makes the member optional. `'update'` requires
+ * `data.type` and `data.id`, and makes every member optional, because JSON:API 1.1 has a server read a missing member
+ * as its current value. An update therefore refuses, at declaration, to name an attribute whose schema fills a value
+ * for a missing key, through a `.default()`, a `.prefault()` or a `.catch()` beneath any wrapper, since the fill would
+ * overwrite the stored value. An attribute whose schema is async is not asked, since a sync parse cannot run it, and
+ * is accepted as it is.
+ *
+ * Every other member JSON:API 1.1 defines for a request is accepted and read by nothing: `lid`, `meta` and `links` on
+ * the resource object, `meta` and `links` on a relationship object, `lid` and `meta` on an identifier, and the
+ * top-level `meta` and `jsonapi`. A member it does not define fails the schema.
+ *
+ * Call it once every related resource it names has been declared, since it reads each one's `type`.
+ *
+ * @param writes - the attributes and relationships a client may write; a name the resource does not declare fails to
+ *   compile
+ * @throws Error at declaration on a name the resource does not declare, or on an update naming an attribute that
+ *   fills a value for a missing key
+ * @throws RequestConflict on a `data.type` other than the resource's - out of `safeParse` as well, because a throwing
+ *   transform escapes it, against what zod documents (zod@4.3.6)
+ * @throws RequestForbidden on a `data.id` in a create, or on an attribute or relationship `writes` does not name - out
+ *   of `safeParse` as well
+ */
+export declare function requestDocumentSchema<R extends WritableResource, M extends RequestMode, const AK extends AttributeName<R> = never, const RK extends RelationshipName<R> = never>(resource: R, mode: M, writes?: {
+    readonly attributes?: readonly AK[];
+    readonly relationships?: readonly RK[];
+}): RequestDocumentSchema<R, M, AK, RK>;
+/** What {@link readRequestDocument} reads: any document {@link requestDocumentSchema} produced. */
+interface RequestDocumentLike {
+    data: {
+        id?: string;
+        attributes?: object;
+        relationships?: Readonly<Record<string, {
+            data: ResourceIdentifier | readonly ResourceIdentifier[] | null;
+        } | undefined>>;
+    };
+}
+/** The ids a relationship's linkage names: one or `null` for a to-one, a list for a to-many. */
+type IdsOf<L> = L extends readonly {
+    id: string;
+}[] ? string[] : L extends {
+    id: string;
+} ? string : null;
+/** What a handler writes from a request document: its attributes, and each relationship as the ids it names. */
+export type ReadRequestDocument<D> = D extends {
+    data: infer Data;
+} ? {
+    attributes: Data extends {
+        attributes?: infer A;
+    } ? Exclude<A, undefined> : Record<never, never>;
+    relationships: Data extends {
+        relationships?: infer L;
+    } ? {
+        [K in keyof Exclude<L, undefined>]: IdsOf<Exclude<Exclude<L, undefined>[K], undefined> extends {
+            data: infer X;
+        } ? X : never>;
+    } : Record<never, never>;
+} : never;
+/**
+ * Hands a handler what a request document writes: the attributes as sent, and each relationship reduced to the id it
+ * names, `null` for a cleared to-one, or a list. A member the document left out stays out, which on an update means
+ * keep its current value.
+ *
+ * @param options - on an update, the id the URL names, spelled as the path carries it; a create takes none
+ * @throws RequestConflict when an update's `data.id` is not the URL's, which JSON:API 1.1 answers 409
+ */
+export declare function readRequestDocument<D extends RequestDocumentLike>(document: D, ...options: D extends {
+    data: {
+        id: string;
+    };
+} ? [options: {
+    id: string;
+}] : []): ReadRequestDocument<D>;
+export {};
+//# sourceMappingURL=request-document.d.ts.map

package/dist/request-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-document.d.ts","sourceRoot":"","sources":["../src/request-document.ts"],"names":[],"mappings":"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"}

package/dist/request-document.js

@@ -0,0 +1,170 @@
+import { z } from 'zod';
+import { jsonApiObjectSchema, metaSchema, relationshipLinksSchema, resourceLinksSchema, } from './primitives.js';
+import { RequestConflict, RequestForbidden } from './request-refusal.js';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** One JSON Pointer segment: RFC 6901 escapes `~` as `~0` and `/` as `~1`, in that order. */
+const pointerSegment = (name) => name.replaceAll('~', '~0').replaceAll('/', '~1');
+/**
+ * Throws what JSON:API 1.1 answers 409 or 403, in the order the standard's checks come: the type, a client id, then
+ * each member the route does not write. It reads the body as sent, so it checks only what it can read and leaves
+ * every other defect to the schema's own issue, which the validation hook answers 422.
+ */
+function refuseUnsupported(body, type, mode, writes) {
+    if (!isRecord(body) || !isRecord(body['data']))
+        return;
+    const data = body['data'];
+    const sentType = data['type'];
+    if (typeof sentType === 'string' && sentType !== type) {
+        throw new RequestConflict('/data/type', `This endpoint writes "${type}", and the document names "${sentType}".`);
+    }
+    if (mode === 'create' && Object.hasOwn(data, 'id')) {
+        throw new RequestForbidden('/data/id', `A "${type}" is given its id by the server, so a create names none.`);
+    }
+    for (const member of ['attributes', 'relationships']) {
+        const sent = data[member];
+        if (!isRecord(sent))
+            continue;
+        const refused = Object.keys(sent).find((name) => !writes[member].includes(name));
+        if (refused !== undefined) {
+            throw new RequestForbidden(`/data/${member}/${pointerSegment(refused)}`, `This endpoint does not write "${refused}" on "${type}".`);
+        }
+    }
+}
+/**
+ * Whether `schema` fills a value for a key left out, asked of the schema itself so any `.default()`, `.prefault()` or
+ * `.catch()`, beneath whatever wraps it, answers. An async schema cannot be asked in a sync parse and reads as `false`.
+ */
+function fillsWhenMissing(schema) {
+    try {
+        const result = schema.safeParse(undefined);
+        return result.success && result.data !== undefined;
+    }
+    catch (error) {
+        if (error instanceof z.core.$ZodAsyncError)
+            return false;
+        throw error;
+    }
+}
+/**
+ * The body schema of a write, built from the same resource declaration the route answers with, so the document a
+ * client reads and the one it writes cannot drift.
+ *
+ * `'create'` requires `data.type`, refuses `data.id`, keeps each named attribute as optional as its schema makes it,
+ * and requires each named relationship (a to-one left empty is sent as `{ data: null }`). It requires `attributes`
+ * itself only where one named attribute is required, since JSON:API makes the member optional. `'update'` requires
+ * `data.type` and `data.id`, and makes every member optional, because JSON:API 1.1 has a server read a missing member
+ * as its current value. An update therefore refuses, at declaration, to name an attribute whose schema fills a value
+ * for a missing key, through a `.default()`, a `.prefault()` or a `.catch()` beneath any wrapper, since the fill would
+ * overwrite the stored value. An attribute whose schema is async is not asked, since a sync parse cannot run it, and
+ * is accepted as it is.
+ *
+ * Every other member JSON:API 1.1 defines for a request is accepted and read by nothing: `lid`, `meta` and `links` on
+ * the resource object, `meta` and `links` on a relationship object, `lid` and `meta` on an identifier, and the
+ * top-level `meta` and `jsonapi`. A member it does not define fails the schema.
+ *
+ * Call it once every related resource it names has been declared, since it reads each one's `type`.
+ *
+ * @param writes - the attributes and relationships a client may write; a name the resource does not declare fails to
+ *   compile
+ * @throws Error at declaration on a name the resource does not declare, or on an update naming an attribute that
+ *   fills a value for a missing key
+ * @throws RequestConflict on a `data.type` other than the resource's - out of `safeParse` as well, because a throwing
+ *   transform escapes it, against what zod documents (zod@4.3.6)
+ * @throws RequestForbidden on a `data.id` in a create, or on an attribute or relationship `writes` does not name - out
+ *   of `safeParse` as well
+ */
+export function requestDocumentSchema(resource, mode, writes = {}) {
+    const attributes = writes.attributes ?? [];
+    const relationships = writes.relationships ?? [];
+    for (const name of attributes) {
+        if (!Object.hasOwn(resource.attributes.shape, name)) {
+            throw new Error(`"${resource.type}" declares no attribute "${name}".`);
+        }
+    }
+    for (const name of relationships) {
+        if (!Object.hasOwn(resource.relationships, name)) {
+            throw new Error(`"${resource.type}" declares no relationship "${name}".`);
+        }
+    }
+    if (mode === 'update') {
+        const filling = attributes.find((name) => fillsWhenMissing(resource.attributes.shape[name]));
+        if (filling !== undefined) {
+            throw new Error(`The update names "${filling}", whose schema fills a value when the key is missing; a PATCH would overwrite ` +
+                `the stored value. Drop the default from the resource's attribute, or leave "${filling}" out of the update.`);
+        }
+    }
+    // A member is left out only where the route names nothing under it that a create must send, or on an update.
+    const present = (schema, required) => mode === 'update' || !required ? schema.optional() : schema;
+    const mask = Object.fromEntries(attributes.map((name) => [name, true]));
+    const picked = resource.attributes.pick(mask);
+    const attributesSchema = (mode === 'update' ? picked.partial() : picked).strict();
+    // What zod documents as the test of an optional schema, which is also what an object runs on a missing key.
+    const someAttributeRequired = mode === 'create' && Object.values(picked.shape).some((schema) => !schema.safeParse(undefined).success);
+    const relationshipsSchema = z
+        .object(Object.fromEntries(relationships.map((name) => {
+        const def = resource.relationships[name];
+        const identifier = z
+            .object({
+            type: z.literal(def.related().type),
+            id: z.string(),
+            lid: z.string().optional(),
+            meta: metaSchema.optional(),
+        })
+            .strict();
+        const linkage = z
+            .object({
+            data: def.cardinality === 'one' ? identifier.nullable() : z.array(identifier),
+            meta: metaSchema.optional(),
+            links: relationshipLinksSchema.optional(),
+        })
+            .strict();
+        return [name, mode === 'update' ? linkage.optional() : linkage];
+    })))
+        .strict();
+    const document = z
+        .object({
+        data: z
+            .object({
+            type: z.literal(resource.type),
+            ...(mode === 'update' ? { id: z.string() } : {}),
+            lid: z.string().optional(),
+            attributes: present(attributesSchema, someAttributeRequired),
+            relationships: present(relationshipsSchema, relationships.length > 0),
+            meta: metaSchema.optional(),
+            links: resourceLinksSchema.optional(),
+        })
+            .strict(),
+        meta: metaSchema.optional(),
+        jsonapi: jsonApiObjectSchema.optional(),
+    })
+        .strict();
+    const checked = z.preprocess((body) => {
+        refuseUnsupported(body, resource.type, mode, { attributes, relationships });
+        return body;
+    }, document);
+    // zod types a preprocessed input as `unknown`; what a client sends is the document itself, which a typed client reads.
+    return checked;
+}
+const idsOf = (data) => data === null
+    ? null
+    : Array.isArray(data)
+        ? data.map((one) => one.id)
+        : data.id;
+/**
+ * Hands a handler what a request document writes: the attributes as sent, and each relationship reduced to the id it
+ * names, `null` for a cleared to-one, or a list. A member the document left out stays out, which on an update means
+ * keep its current value.
+ *
+ * @param options - on an update, the id the URL names, spelled as the path carries it; a create takes none
+ * @throws RequestConflict when an update's `data.id` is not the URL's, which JSON:API 1.1 answers 409
+ */
+export function readRequestDocument(document, ...options) {
+    const { data } = document;
+    const [url] = options;
+    if (url !== undefined && data.id !== url.id) {
+        throw new RequestConflict('/data/id', `The document names "${String(data.id)}", and the URL names "${url.id}".`);
+    }
+    const relationships = Object.fromEntries(Object.entries(data.relationships ?? {}).flatMap(([name, linkage]) => linkage === undefined ? [] : [[name, idsOf(linkage.data)]]));
+    // The shape is the document's own, which the route's schema declared; the reduction above is what differs.
+    return { attributes: data.attributes ?? {}, relationships };
+}

package/dist/request-refusal.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A request document naming another resource than its endpoint: a `type` outside the collection, or an `id` other
+ * than the one its URL names. It carries no status and no wire `code`, as `QueryNotPermitted` carries none: the
+ * transport that catches it answers 409, which JSON:API 1.1 requires of both.
+ */
+export declare class RequestConflict extends Error {
+    /** The JSON Pointer (RFC 6901) to the member that conflicts. */
+    readonly pointer: string;
+    constructor(
+    /** The JSON Pointer (RFC 6901) to the member that conflicts. */
+    pointer: string, message: string);
+}
+/**
+ * A request document asking for a write its endpoint does not support: a client-generated id on a create, or an
+ * attribute or relationship the route does not write. The transport answers 403, which JSON:API 1.1 requires of both.
+ */
+export declare class RequestForbidden extends Error {
+    /** The JSON Pointer (RFC 6901) to the member refused. */
+    readonly pointer: string;
+    constructor(
+    /** The JSON Pointer (RFC 6901) to the member refused. */
+    pointer: string, message: string);
+}
+//# sourceMappingURL=request-refusal.d.ts.map

package/dist/request-refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-refusal.d.ts","sourceRoot":"","sources":["../src/request-refusal.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IAEtC,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM;;IADxB,gEAAgE;IACvD,OAAO,EAAE,MAAM,EACxB,OAAO,EAAE,MAAM;CAKlB;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAEvC,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM;;IADxB,yDAAyD;IAChD,OAAO,EAAE,MAAM,EACxB,OAAO,EAAE,MAAM;CAKlB"}

package/dist/request-refusal.js

@@ -0,0 +1,29 @@
+/**
+ * A request document naming another resource than its endpoint: a `type` outside the collection, or an `id` other
+ * than the one its URL names. It carries no status and no wire `code`, as `QueryNotPermitted` carries none: the
+ * transport that catches it answers 409, which JSON:API 1.1 requires of both.
+ */
+export class RequestConflict extends Error {
+    pointer;
+    constructor(
+    /** The JSON Pointer (RFC 6901) to the member that conflicts. */
+    pointer, message) {
+        super(message);
+        this.pointer = pointer;
+        this.name = 'RequestConflict';
+    }
+}
+/**
+ * A request document asking for a write its endpoint does not support: a client-generated id on a create, or an
+ * attribute or relationship the route does not write. The transport answers 403, which JSON:API 1.1 requires of both.
+ */
+export class RequestForbidden extends Error {
+    pointer;
+    constructor(
+    /** The JSON Pointer (RFC 6901) to the member refused. */
+    pointer, message) {
+        super(message);
+        this.pointer = pointer;
+        this.name = 'RequestForbidden';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/response",
-  "version": "0.14.2",
+  "version": "0.14.3",
   "private": false,
   "type": "module",
   "sideEffects": false,