@zeroxsolutions/response 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,3 +1,75 @@
+## 0.14.0 (2026-09-28)
+
+### 🚀 Features
+
+- **response:** answer a created resource with its location ([e9c0086](https://github.com/zeroxsolutions/zeroxsolutions/commit/e9c0086))
+- ⚠️  **response:** refuse a declaration the standard's field rules forbid ([30e6b77](https://github.com/zeroxsolutions/zeroxsolutions/commit/30e6b77))
+
+### 🩹 Fixes
+
+- ⚠️  **response:** walk a pipe's input when checking member names ([0949d22](https://github.com/zeroxsolutions/zeroxsolutions/commit/0949d22))
+- **response:** match link types to their schemas ([0f7c79b](https://github.com/zeroxsolutions/zeroxsolutions/commit/0f7c79b))
+- ⚠️  **response:** refuse a resource id that is not a string ([57f60ab](https://github.com/zeroxsolutions/zeroxsolutions/commit/57f60ab))
+- **response:** keep a primary resource out of included ([c38859f](https://github.com/zeroxsolutions/zeroxsolutions/commit/c38859f))
+- ⚠️  **response:** read only the document members the standard defines ([fc5c51a](https://github.com/zeroxsolutions/zeroxsolutions/commit/fc5c51a))
+- ⚠️  **response:** refuse an error object that carries no member ([7d888ed](https://github.com/zeroxsolutions/zeroxsolutions/commit/7d888ed))
+
+### ⚠️  Breaking Changes
+
+- **response:** walk a pipe's input when checking member names  ([0949d22](https://github.com/zeroxsolutions/zeroxsolutions/commit/0949d22))
+  a nested attribute member name that breaks the
+  standard's member-name rule, and sits behind a .transform() or
+  .pipe(), now throws at jsonApiResource's own declaration where it
+  previously passed unchecked.
+- **response:** refuse a declaration the standard's field rules forbid  ([30e6b77](https://github.com/zeroxsolutions/zeroxsolutions/commit/30e6b77))
+  jsonApiResource throws, and fails to compile, on a field named type or id, a name shared by an attribute and a relationship, an illegal member name, or a foreign-key attribute beside its relationship.
+- **response:** refuse a resource id that is not a string  ([57f60ab](https://github.com/zeroxsolutions/zeroxsolutions/commit/57f60ab))
+  Row['id'] is typed string, and serializing a row, embedded row or foreign key whose id is not a string throws TypeError.
+- **response:** read only the document members the standard defines  ([fc5c51a](https://github.com/zeroxsolutions/zeroxsolutions/commit/fc5c51a))
+  a data document carrying errors, an error document carrying data, and an empty relationship object are refused.
+- **response:** refuse an error object that carries no member  ([7d888ed](https://github.com/zeroxsolutions/zeroxsolutions/commit/7d888ed))
+  toErrorDocument throws on an empty error object.
+
+### ❤️ Thank You
+
+- Claude Opus 5.5 (1M context)
+- Lương Văn Tú
+
+## 0.13.0 (2026-09-27)
+
+### 🚀 Features
+
+- ⚠️  **response:** type the fieldsets and include paths a document answers ([98bbb58](https://github.com/zeroxsolutions/zeroxsolutions/commit/98bbb58))
+- ⚠️  **response:** keep a resource's type, attributes and relationships as literals ([738889e](https://github.com/zeroxsolutions/zeroxsolutions/commit/738889e))
+
+### 🩹 Fixes
+
+- ⚠️  **response:** pin an include path stopping at a wide edge ([515a3e9](https://github.com/zeroxsolutions/zeroxsolutions/commit/515a3e9))
+
+### ⚠️  Breaking Changes
+
+- **response:** pin an include path stopping at a wide edge  ([515a3e9](https://github.com/zeroxsolutions/zeroxsolutions/commit/515a3e9))
+  jsonApiResource's type parameters moved from <A, C> to
+  <T, A, R, C>, so an explicit `jsonApiResource<typeof attrs, Ctx>` no
+  longer compiles; remove the type arguments and let inference type it.
+  The exported ResourceOptions<C> is now ResourceOptions<R>.
+  BREAKING CHANGE: an explicit toOne<Ctx> or toMany<Ctx> no longer
+  compiles; remove the type argument.
+- **response:** type the fieldsets and include paths a document answers  ([98bbb58](https://github.com/zeroxsolutions/zeroxsolutions/commit/98bbb58))
+  declaredDocumentShape answers typed fieldsets and include
+  paths, walks at most three relationships by default, and answers a fieldset
+  only for a type a kept path reaches. DeclaredDocumentShape is removed;
+  TypedDocumentShape replaces it.
+- **response:** keep a resource's type, attributes and relationships as literals  ([738889e](https://github.com/zeroxsolutions/zeroxsolutions/commit/738889e))
+  toOne and toMany take the related resource as their first type
+  parameter and infer the loader context; a call passing the context explicitly,
+  toOne<Ctx>(...), no longer compiles and drops the explicit argument.
+
+### ❤️ Thank You
+
+- Claude Opus 5.5 (1M context)
+- Lương Văn Tú
+
 ## 0.12.2 (2026-09-27)
 
 ### 🚀 Features

package/README.md

@@ -134,6 +134,7 @@ app.onError(
     namespace: 'academics',   // every code THESE handlers mint carries it, so one surface has one vocabulary
     category: ['academics', 'http'],
     resolve: createDomainErrorResolver(academicsErrors),
+    authenticationChallenge: 'Bearer',
   }),
 );
 ```

package/dist/created-response.d.ts

@@ -0,0 +1,23 @@
+import type { Link } from './primitives.js';
+/**
+ * The arguments of a 201 that created `document`'s resource: the document, the status, and the `Location` the standard
+ * asks a 201 to carry. Spread into `c.json(...)`.
+ *
+ * `type` and `id` sit in the bound alongside `links`, both of which every `ResourceObject` carries: a document
+ * whose resource has no `links` at all would otherwise share no property with a bound of `links` alone, which
+ * is a "weak type" TypeScript refuses to accept a value for - and a resource with no self link is the common case.
+ *
+ * @throws Error when the resource's `self` link names another location, since the standard requires the two to match
+ */
+export declare function createdResponse<D extends {
+    data: {
+        type: string;
+        id: string;
+        links?: {
+            self?: Link;
+        };
+    };
+}>(document: D, location: string): readonly [D, 201, {
+    Location: string;
+}];
+//# sourceMappingURL=created-response.d.ts.map

package/dist/created-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"created-response.d.ts","sourceRoot":"","sources":["../src/created-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAM5C;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,IAAI,CAAA;SAAE,CAAA;KAAE,CAAA;CAAE,EACvG,QAAQ,EAAE,CAAC,EACX,QAAQ,EAAE,MAAM,GACf,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAMzC"}

package/dist/created-response.js

@@ -0,0 +1,19 @@
+/** Where a link points, whichever of the standard's forms it takes. */
+const hrefOf = (link) => link === null || link === undefined ? undefined : typeof link === 'string' ? link : link.href;
+/**
+ * The arguments of a 201 that created `document`'s resource: the document, the status, and the `Location` the standard
+ * asks a 201 to carry. Spread into `c.json(...)`.
+ *
+ * `type` and `id` sit in the bound alongside `links`, both of which every `ResourceObject` carries: a document
+ * whose resource has no `links` at all would otherwise share no property with a bound of `links` alone, which
+ * is a "weak type" TypeScript refuses to accept a value for - and a resource with no self link is the common case.
+ *
+ * @throws Error when the resource's `self` link names another location, since the standard requires the two to match
+ */
+export function createdResponse(document, location) {
+    const self = hrefOf(document.data.links?.self);
+    if (self !== undefined && self !== location) {
+        throw new Error(`The created resource's self link "${self}" differs from its Location "${location}".`);
+    }
+    return [document, 201, { Location: location }];
+}

package/dist/document-load.d.ts

@@ -4,7 +4,7 @@
  * relationship declares belongs to `relationship.ts`.
  */
 import type { RelatedResource, RelationshipDef } from './relationship.js';
-import type { LoadedRows, RequestedDocumentShape, Row } from './serialize.js';
+import { type LoadedRows, type RequestedDocumentShape, type Row } from './serialize.js';
 /**
  * What one loaded relationship hands the serializer for a row: the row its loader answered, or the
  * identifier alone where it answered none.

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

@@ -1 +1 @@
-{"version":3,"file":"document-load.d.ts","sourceRoot":"","sources":["../src/document-load.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,sBAAsB,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AA0B9E;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,EACvB,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,UAAU,GAAG,SAAS,GAC7B,GAAG,GAAG,GAAG,EAAE,GAAG,IAAI,CAIpB;AA0BD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,EACxB,IAAI,EAAE,SAAS,GAAG,EAAE,EACpB,SAAS,EAAE,sBAAsB,GAAG,SAAS,EAC7C,OAAO,EAAE,CAAC,GACT,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CA8BjC"}
+{"version":3,"file":"document-load.d.ts","sourceRoot":"","sources":["../src/document-load.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAe,KAAK,UAAU,EAAE,KAAK,sBAAsB,EAAE,KAAK,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAmCrG;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,EACvB,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,UAAU,GAAG,SAAS,GAC7B,GAAG,GAAG,GAAG,EAAE,GAAG,IAAI,CAKpB;AA2BD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,EACxB,IAAI,EAAE,SAAS,GAAG,EAAE,EACpB,SAAS,EAAE,sBAAsB,GAAG,SAAS,EAC7C,OAAO,EAAE,CAAC,GACT,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CA8BjC"}

package/dist/document-load.js

@@ -1,7 +1,18 @@
-/** The ids one row carries for a loaded relationship. A null or absent key asks for nothing. */
-function readIds(value) {
+import { assertRowId } from './serialize.js';
+/**
+ * The ids one row carries for a loaded relationship. A null or absent key asks for nothing; any other
+ * non-string is refused rather than silently dropped, naming the relationship's own related `type`.
+ */
+function readIds(value, type) {
     const values = Array.isArray(value) ? value : [value];
-    return values.filter((one) => typeof one === 'string');
+    const ids = [];
+    for (const one of values) {
+        if (one === null || one === undefined)
+            continue;
+        assertRowId(type, { id: one });
+        ids.push(one);
+    }
+    return ids;
 }
 /** The rows one row already carries for a relationship that declares no loader. */
 function readRows(value) {
@@ -16,8 +27,9 @@ function readRows(value) {
  * linkage a client reads - only what lands under `included`.
  */
 export function loadedRelated(def, row, loaded) {
-    const answered = loaded?.get(def.related().type);
-    const rows = readIds(def.read(row)).map((id) => answered?.get(id) ?? { id });
+    const type = def.related().type;
+    const answered = loaded?.get(type);
+    const rows = readIds(def.read(row), type).map((id) => answered?.get(id) ?? { id });
     return def.cardinality === 'many' ? rows : (rows.at(0) ?? null);
 }
 /** Runs one relationship's loader, and answers the rows the next depth reads its ids off. */
@@ -29,13 +41,13 @@ async function loadRelated(def, rows, loaded, context) {
     const type = def.related().type;
     const answered = loaded.get(type) ?? new Map();
     loaded.set(type, answered);
-    const ids = [...new Set(rows.flatMap((row) => readIds(def.read(row))))];
+    const ids = [...new Set(rows.flatMap((row) => readIds(def.read(row), type)))];
     if (ids.length === 0)
         return [];
     const related = await load(ids, context);
     for (const row of related) {
-        if (typeof row.id === 'string')
-            answered.set(row.id, row);
+        assertRowId(type, row);
+        answered.set(row.id, row);
     }
     return related;
 }

package/dist/document.d.ts

@@ -1,10 +1,10 @@
 import type { ZodObject, ZodType } from 'zod';
-import { type JsonApiObject, type Meta, type PaginationLinks, type ResourceIdentifier, type ResourceLinks } from './primitives.js';
+import { type JsonApiObject, type Meta, type PaginationLinks, type RelationshipLinks, type ResourceIdentifier, type ResourceLinks, type TopLevelLinks } 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;
+    links?: RelationshipLinks;
     meta?: Meta;
 }
 /** A resource object, with `attributes` carrying the declared attribute type. */
@@ -20,7 +20,7 @@ export interface ResourceObject<A> {
 export interface ResourceDocument<A> {
     data: ResourceObject<A>;
     included?: ResourceObject<unknown>[];
-    links?: ResourceLinks;
+    links?: TopLevelLinks;
     meta?: Meta;
     jsonapi?: JsonApiObject;
 }
@@ -32,7 +32,12 @@ export interface CollectionDocument<A> {
     meta?: Meta;
     jsonapi?: JsonApiObject;
 }
-/** Wraps `attributes` into a resource object - `{ type, id, attributes, relationships?, links?, meta? }`. */
+/**
+ * Wraps `attributes` into a resource object - `{ type, id, attributes?, relationships?, links?, meta? }`.
+ *
+ * `attributes` parses as absent here, unlike {@link ResourceObject}'s own required member: this schema
+ * also validates a document read off another server, which may publish a resource with none.
+ */
 export declare function resourceObjectSchema<C>(type: string, attributes: ZodObject, relationships?: Readonly<Record<string, RelationshipDef<C>>>): ZodType;
 /**
  * The document for a SINGLE resource - `{ data, included?, links?, meta?, jsonapi? }`.
@@ -40,8 +45,15 @@ export declare function resourceObjectSchema<C>(type: string, attributes: ZodObj
  * `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`.
+ *
+ * Strict at the top level: the standard forbids any top-level member beyond these (extension members
+ * aside), which is what refuses a `data` document that also carries `errors`.
  */
 export declare function resourceDocumentSchema<A = unknown, C = unknown>(root: RelatedResource<C>): ZodType<ResourceDocument<A>>;
-/** The document for a COLLECTION - the same members, with `data` an array and paginated `links`. */
+/**
+ * The document for a COLLECTION - the same members, with `data` an array and paginated `links`.
+ *
+ * Strict at the top level for the same reason as {@link resourceDocumentSchema}.
+ */
 export declare function collectionDocumentSchema<A = unknown, C = unknown>(root: RelatedResource<C>): ZodType<CollectionDocument<A>>;
 //# sourceMappingURL=document.d.ts.map

package/dist/document.d.ts.map

@@ -1 +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,CAAC,CAAC,EACpC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,EACrB,aAAa,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAM,GAC/D,OAAO,CAUT;AAgBD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAC7D,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAQ9B;AAED,oGAAoG;AACpG,wBAAgB,wBAAwB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAC/D,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAQhC"}
+{"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,EAML,KAAK,aAAa,EAClB,KAAK,IAAI,EACT,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,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,iBAAiB,CAAC;IAC1B,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;IAGX,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;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,EACrB,aAAa,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAM,GAC/D,OAAO,CAUT;AAgBD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAC7D,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAQ9B;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAC/D,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAQhC"}

package/dist/document.js

@@ -1,13 +1,18 @@
 import { z } from 'zod';
-import { jsonApiObjectSchema, metaSchema, paginationLinksSchema, resourceLinksSchema, } from './primitives.js';
+import { jsonApiObjectSchema, metaSchema, paginationLinksSchema, resourceLinksSchema, topLevelLinksSchema, } from './primitives.js';
 import { relationshipsSchema, reachableResources } from './relationship.js';
-/** Wraps `attributes` into a resource object - `{ type, id, attributes, relationships?, links?, meta? }`. */
+/**
+ * Wraps `attributes` into a resource object - `{ type, id, attributes?, relationships?, links?, meta? }`.
+ *
+ * `attributes` parses as absent here, unlike {@link ResourceObject}'s own required member: this schema
+ * also validates a document read off another server, which may publish a resource with none.
+ */
 export function resourceObjectSchema(type, attributes, relationships = {}) {
     const linkage = relationshipsSchema(relationships);
     return z.object({
         type: z.literal(type),
         id: z.string(),
-        attributes,
+        attributes: attributes.optional(),
         ...(linkage ? { relationships: linkage.optional() } : {}),
         links: resourceLinksSchema.optional(),
         meta: metaSchema.optional(),
@@ -32,19 +37,26 @@ function includedSchema(root) {
  * `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`.
+ *
+ * Strict at the top level: the standard forbids any top-level member beyond these (extension members
+ * aside), which is what refuses a `data` document that also carries `errors`.
  */
 export function resourceDocumentSchema(root) {
-    return z.object({
+    return z.strictObject({
         data: root.resourceObject,
         included: includedSchema(root).optional(),
-        links: resourceLinksSchema.optional(),
+        links: topLevelLinksSchema.optional(),
         meta: metaSchema.optional(),
         jsonapi: jsonApiObjectSchema.optional(),
     });
 }
-/** The document for a COLLECTION - the same members, with `data` an array and paginated `links`. */
+/**
+ * The document for a COLLECTION - the same members, with `data` an array and paginated `links`.
+ *
+ * Strict at the top level for the same reason as {@link resourceDocumentSchema}.
+ */
 export function collectionDocumentSchema(root) {
-    return z.object({
+    return z.strictObject({
         data: z.array(root.resourceObject),
         included: includedSchema(root).optional(),
         links: paginationLinksSchema.optional(),

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

@@ -42,7 +42,7 @@ export declare const errorLinksSchema: z.ZodObject<{
     }, 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. */
+/** A single JSON:API error object: every member is optional, and at least one is present. */
 export declare const errorObjectSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     links: z.ZodOptional<z.ZodObject<{
@@ -94,6 +94,9 @@ 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`.
  *
+ * Strict at the top level: the standard forbids any top-level member beyond these (extension members
+ * aside), which is what refuses a document that carries both `errors` and `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.
  */
@@ -182,8 +185,10 @@ export declare const errorDocumentSchema: z.ZodObject<{
     }, z.core.$strip>>;
     jsonapi: z.ZodOptional<z.ZodObject<{
         version: z.ZodOptional<z.ZodString>;
+        ext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        profile: z.ZodOptional<z.ZodArray<z.ZodString>>;
         meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
-}, z.core.$strip>;
+}, z.core.$strict>;
 export type ErrorDocument = z.infer<typeof errorDocumentSchema>;
 //# sourceMappingURL=error-document.d.ts.map

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

@@ -1 +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"}
+{"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,6FAA6F;AAC7F,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAYoF,CAAC;AACnH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAK9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/errors/error-document.js

@@ -10,7 +10,7 @@ export const errorSourceSchema = z
     .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. */
+/** A single JSON:API error object: every member is optional, and at least one is present. */
 export const errorObjectSchema = z
     .object({
     id: z.string(),
@@ -22,14 +22,18 @@ export const errorObjectSchema = z
     source: errorSourceSchema,
     meta: metaSchema,
 })
-    .partial();
+    .partial()
+    .refine((object) => Object.keys(object).length > 0, { message: 'An error object carries at least one member.' });
 /**
  * A JSON:API error document - a top-level `errors` array of at least one member, which never carries `data`.
  *
+ * Strict at the top level: the standard forbids any top-level member beyond these (extension members
+ * aside), which is what refuses a document that carries both `errors` and `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({
+export const errorDocumentSchema = z.strictObject({
     errors: z.array(errorObjectSchema).min(1),
     meta: metaSchema.optional(),
     links: z.object({ self: linkSchema, describedby: linkSchema }).partial().optional(),

package/dist/index.d.ts

@@ -2,6 +2,7 @@
  * 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, type RetryAfterHeader, } from './api-response.js';
+export { createdResponse } from './created-response.js';
 export type { CollectionDocument, Relationship, ResourceDocument, ResourceObject } from './document.js';
 export * from './document-graph.js';
 export { declaredDocumentShape } from './document-shape.js';
@@ -9,7 +10,7 @@ export { createDomainErrorResolver, defineErrorMap, errorEntry, type DomainError
 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 type { JsonApiObject, Link, Meta, PaginationLinks, RelationshipLinks, ResourceIdentifier, ResourceLinks, TopLevelLinks, } from './primitives.js';
 export { toMany, toOne, type LoadContextArguments, type RelatedResource, type RelationshipDef, type RelationshipLoader, type RelationshipOptions, } from './relationship.js';
 export { jsonApiResource, type JsonApiResource, type ResourceOptions } from './resource.js';
 export type { CollectionExtras, LoadedRows, RequestedDocumentShape, ResourceSerializer, Row } from './serialize.js';

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,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACxG,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,YAAY,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrH,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,EAAE,kBAAkB,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACxG,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,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"}

package/dist/index.js

@@ -2,6 +2,7 @@
  * 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 { createdResponse } from './created-response.js';
 export * from './document-graph.js';
 export { declaredDocumentShape } from './document-shape.js';
 export { createDomainErrorResolver, defineErrorMap, errorEntry, } from './domain-error-resolver.js';

package/dist/member-name.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Whether a string is a legal JSON:API member name.
+ *
+ * Copied rather than imported at `packages/query/src/bracket-params.ts`'s own `isMemberName`: this
+ * package may not import `@zeroxsolutions/query` (nor the reverse), so each side of that boundary
+ * keeps its own copy of the one rule instead.
+ */
+export declare function isMemberName(name: string): boolean;
+//# sourceMappingURL=member-name.d.ts.map

package/dist/member-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"member-name.d.ts","sourceRoot":"","sources":["../src/member-name.ts"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD"}

package/dist/member-name.js

@@ -0,0 +1,15 @@
+/** Characters a member name may start or end with: the standard's globally allowed characters. */
+const GLOBAL = 'a-zA-Z0-9\\u0080-\\u{10FFFF}';
+/** Additionally allowed between the first and last character: hyphen, low line and space. */
+const MIDDLE = '\\-_ ';
+const MEMBER_NAME = new RegExp(`^[${GLOBAL}](?:[${GLOBAL}${MIDDLE}]*[${GLOBAL}])?$`, 'u');
+/**
+ * Whether a string is a legal JSON:API member name.
+ *
+ * Copied rather than imported at `packages/query/src/bracket-params.ts`'s own `isMemberName`: this
+ * package may not import `@zeroxsolutions/query` (nor the reverse), so each side of that boundary
+ * keeps its own copy of the one rule instead.
+ */
+export function isMemberName(name) {
+    return MEMBER_NAME.test(name);
+}

package/dist/primitives.d.ts

@@ -59,7 +59,60 @@ export declare const resourceLinksSchema: z.ZodObject<{
 }, 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. */
+/** A document's own top-level `self`/`related`, plus the description of the document itself. */
+export declare const topLevelLinksSchema: 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]>>;
+    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>;
+/** A single-resource document's top-level links - inferred from {@link topLevelLinksSchema}. */
+export type TopLevelLinks = z.infer<typeof topLevelLinksSchema>;
+/** Collection pagination links, plus the description of the document itself. */
 export declare const paginationLinksSchema: z.ZodObject<{
     self: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         rel: z.ZodOptional<z.ZodString>;
@@ -141,9 +194,126 @@ export declare const paginationLinksSchema: z.ZodObject<{
             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>;
 /** Collection pagination links - inferred from {@link paginationLinksSchema}. */
 export type PaginationLinks = z.infer<typeof paginationLinksSchema>;
+/** A relationship's links: its own `self`/`related`, and the pages of a to-many linkage. */
+export declare const relationshipLinksSchema: 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]>>;
+    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]>>;
+    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]>>;
+    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]>>;
+}, z.core.$strip>;
+/** A relationship's links - inferred from {@link relationshipLinksSchema}. */
+export type RelationshipLinks = z.infer<typeof relationshipLinksSchema>;
 /** A resource identifier object - the `{ type, id }` linkage that points at another resource. */
 export declare const resourceIdentifierSchema: z.ZodObject<{
     type: z.ZodString;
@@ -151,9 +321,11 @@ export declare const resourceIdentifierSchema: z.ZodObject<{
 }, 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. */
+/** The top-level `jsonapi` member: the version this document is written to, the extensions and profiles it applies. */
 export declare const jsonApiObjectSchema: z.ZodObject<{
     version: z.ZodOptional<z.ZodString>;
+    ext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    profile: z.ZodOptional<z.ZodArray<z.ZodString>>;
     meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 /** The top-level `jsonapi` member - inferred from {@link jsonApiObjectSchema}. */

package/dist/primitives.d.ts.map

@@ -1 +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"}
+{"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,gGAAgG;AAChG,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAqE,CAAC;AACtG,gGAAgG;AAChG,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,gFAAgF;AAChF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAOhC,CAAC;AACH,iFAAiF;AACjF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,4FAA4F;AAC5F,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAKlC,CAAC;AACH,8EAA8E;AAC9E,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,iGAAiG;AACjG,eAAO,MAAM,wBAAwB;;;iBAAiD,CAAC;AACvF,0FAA0F;AAC1F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,uHAAuH;AACvH,eAAO,MAAM,mBAAmB;;;;;iBAK9B,CAAC;AACH,kFAAkF;AAClF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/primitives.js

@@ -30,18 +30,30 @@ 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. */
+/** A document's own top-level `self`/`related`, plus the description of the document itself. */
+export const topLevelLinksSchema = resourceLinksSchema.extend({ describedby: linkSchema.optional() });
+/** Collection pagination links, plus the description of the document itself. */
 export const paginationLinksSchema = z.object({
     self: linkSchema.optional(),
     first: linkSchema.optional(),
     prev: linkSchema.optional(),
     next: linkSchema.optional(),
     last: linkSchema.optional(),
+    describedby: linkSchema.optional(),
+});
+/** A relationship's links: its own `self`/`related`, and the pages of a to-many linkage. */
+export const relationshipLinksSchema = resourceLinksSchema.extend({
+    first: linkSchema.optional(),
+    last: linkSchema.optional(),
+    prev: linkSchema.optional(),
+    next: 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. */
+/** The top-level `jsonapi` member: the version this document is written to, the extensions and profiles it applies. */
 export const jsonApiObjectSchema = z.object({
     version: z.string().optional(),
+    ext: z.array(z.string()).optional(),
+    profile: z.array(z.string()).optional(),
     meta: metaSchema.optional(),
 });

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { metaSchema, resourceIdentifierSchema, resourceLinksSchema } from './primitives.js';
+import { metaSchema, relationshipLinksSchema, resourceIdentifierSchema } from './primitives.js';
 /** The context a serialize call was handed, for the load pass to give the loaders. */
 export function loadContext(contextArguments) {
     // A conditional tuple's element does not narrow back to `C`, and this is the one place that reads it.
@@ -21,10 +21,14 @@ export function toMany(related, read, options) {
 /** 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({
+    return z
+        .object({
         data: (def.cardinality === 'one' ? identifier.nullable() : z.array(identifier)).optional(),
-        links: resourceLinksSchema.optional(),
+        links: relationshipLinksSchema.optional(),
         meta: metaSchema.optional(),
+    })
+        .refine((relationship) => Object.keys(relationship).length > 0, {
+        message: 'A relationship object carries links, data or meta.',
     });
 }
 /** The `relationships` member for a whole resource - one key per declaration, absent when it declares none. */

package/dist/resource.d.ts

@@ -39,7 +39,16 @@ export interface JsonApiResource<A extends ZodObject, C = unknown, T extends str
     /** Serializes rows into a collection document, merging in pagination `links` and `meta`. */
     serializeMany(rows: Row[], extras?: CollectionExtras, requested?: RequestedDocumentShape, ...context: LoadContextArguments<C>): Promise<CollectionDocument<output<A>>>;
 }
+/** A relationship map's own names, and none where the map is the empty default. */
+type RelationshipName<R> = string extends keyof R ? never : keyof R & string;
+/**
+ * `never` where a name breaks the standard's one field namespace (an attribute or relationship named `type` or `id`,
+ * or a name that is both), which turns the declaring call into a compile error.
+ */
+type FieldNamespace<A extends ZodObject, R> = [
+    (keyof A['shape'] & string & ('type' | 'id' | RelationshipName<R>)) | (RelationshipName<R> & ('type' | 'id'))
+] extends [never] ? unknown : never;
 /** Declares a JSON:API resource type - its `type`, the schema of its `attributes`, and its relationships. */
-export declare function jsonApiResource<const T extends string, A extends ZodObject, const R extends Readonly<Record<string, RelationshipDef<any, any>>> = Readonly<Record<string, never>>, C = ContextOfRelationships<R>>(type: T, attributes: A, options?: ResourceOptions<R>): JsonApiResource<A, C, T, R>;
+export declare function jsonApiResource<const T extends string, A extends ZodObject, const R extends Readonly<Record<string, RelationshipDef<any, any>>> = Readonly<Record<string, never>>, C = ContextOfRelationships<R>>(type: T, attributes: A & FieldNamespace<A, R>, options?: ResourceOptions<R>): JsonApiResource<A, C, T, R>;
 export {};
 //# sourceMappingURL=resource.d.ts.map

package/dist/resource.d.ts.map

@@ -1 +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;AAEvB,OAAO,EAAe,KAAK,oBAAoB,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACvH,OAAO,EAIL,KAAK,gBAAgB,EAErB,KAAK,sBAAsB,EAE3B,KAAK,GAAG,EACT,MAAM,gBAAgB,CAAC;AAExB,iEAAiE;AAEjE,KAAK,sBAAsB,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,eAAe,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC;AAEhG,uDAAuD;AACvD,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,mGAAmG;IACnG,aAAa,CAAC,EAAE,CAAC,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe,CAC9B,CAAC,SAAS,SAAS,EACnB,CAAC,GAAG,OAAO,EACX,CAAC,SAAS,MAAM,GAAG,MAAM,EAEzB,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAC5G,SAAQ,eAAe,CAAC,CAAC,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,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;;;;;;OAMG;IACH,SAAS,CACP,GAAG,EAAE,GAAG,EACR,SAAS,CAAC,EAAE,sBAAsB,EAClC,GAAG,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,4FAA4F;IAC5F,aAAa,CACX,IAAI,EAAE,GAAG,EAAE,EACX,MAAM,CAAC,EAAE,gBAAgB,EACzB,SAAS,CAAC,EAAE,sBAAsB,EAClC,GAAG,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC3C;AAgBD,6GAA6G;AAC7G,wBAAgB,eAAe,CAC7B,KAAK,CAAC,CAAC,SAAS,MAAM,EACtB,CAAC,SAAS,SAAS,EAEnB,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,EACrG,CAAC,GAAG,sBAAsB,CAAC,CAAC,CAAC,EAC7B,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,GAAE,eAAe,CAAC,CAAC,CAAM,GAAG,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAwEvF"}
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"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"}

package/dist/resource.js

@@ -1,8 +1,10 @@
 import { Relator } from 'ts-japi';
+import { z } from 'zod';
 import { collectionDocumentSchema, resourceDocumentSchema, resourceObjectSchema, } from './document.js';
 import { loadedRelated, loadIncludedRows } from './document-load.js';
+import { isMemberName } from './member-name.js';
 import { loadContext } from './relationship.js';
-import { createSerializer, serializeCollection, serializeResource, } from './serialize.js';
+import { assertRowId, 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.
@@ -15,11 +17,67 @@ const MAX_KEPT_SERIALIZERS = 64;
 function shapeKey(requested) {
     return JSON.stringify([requested?.fields ?? null, requested?.include ?? null]);
 }
+/**
+ * Steps past the wrappers that change presence or transport, not shape, as a declaration's schemas nest:
+ * optional/nullable/default, an array's element, a union's members, and a pipe's `in` - which is what a
+ * `.transform()` or `.pipe()` compiles to, so a nested object behind either is still checked.
+ *
+ * A `z.record()` and a `z.lazy()` schema are left unwalked on purpose: a record's keys are the caller's
+ * own data, not members this declaration names, and a lazy schema resolves its inner type only on use,
+ * which is past the point this walk runs.
+ */
+function membersOf(schema) {
+    const def = schema.def;
+    if (def.innerType)
+        return membersOf(def.innerType);
+    if (def.type === 'array' && def.element)
+        return membersOf(def.element);
+    if (def.type === 'union' && def.options)
+        return def.options.flatMap(membersOf);
+    if (def.type === 'pipe' && def.in)
+        return membersOf(def.in);
+    return [schema];
+}
+/** Every member name an attribute schema declares, at every depth. */
+function memberNames(schema) {
+    return membersOf(schema).flatMap((member) => member instanceof z.ZodObject
+        ? Object.entries(member.shape).flatMap(([name, inner]) => [name, ...memberNames(inner)])
+        : []);
+}
+/**
+ * @throws Error on a type or member name the standard does not allow, a name outside the one field namespace, or an
+ *   attribute that republishes a relationship's own reference as a foreign key
+ */
+function assertDeclaration(type, attributes, 
+// Only `cardinality` is read here; the full `RelationshipDef<C, R>` is contravariant in `C` through its
+// optional `load`, which makes a map typed with concrete C/R fail against one typed `any`/`any`.
+relationships) {
+    if (!isMemberName(type))
+        throw new Error(`"${type}" is not a legal JSON:API type.`);
+    const attributeNames = Object.keys(attributes.shape);
+    for (const name of [...memberNames(attributes), ...Object.keys(relationships)]) {
+        if (!isMemberName(name))
+            throw new Error(`"${name}" is not a legal JSON:API member name on "${type}".`);
+    }
+    for (const name of [...attributeNames, ...Object.keys(relationships)]) {
+        if (name === 'type' || name === 'id')
+            throw new Error(`"${type}" cannot declare a field named "${name}".`);
+    }
+    for (const [name, def] of Object.entries(relationships)) {
+        if (attributeNames.includes(name))
+            throw new Error(`"${type}" declares "${name}" as an attribute and a relationship.`);
+        const keys = def.cardinality === 'one' ? [`${name}Id`, `${name}_id`] : [`${name}Ids`, `${name}_ids`];
+        const foreignKey = keys.find((key) => attributeNames.includes(key));
+        if (foreignKey)
+            throw new Error(`"${type}" publishes "${foreignKey}"; the "${name}" relationship already carries it.`);
+    }
+}
 /** Declares a JSON:API resource type - its `type`, the schema of its `attributes`, and its relationships. */
 export function jsonApiResource(type, attributes, options = {}) {
     // Safe: when `relationships` is omitted, R is inferred as its own empty-relationships default above,
     // which `{}` already satisfies.
     const relationships = (options.relationships ?? {});
+    assertDeclaration(type, attributes, 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();
@@ -46,7 +104,14 @@ export function jsonApiResource(type, attributes, options = {}) {
                 return built;
             const relators = Object.fromEntries(Object.entries(relationships).map(([name, def]) => [
                 name,
-                new Relator(async (row) => def.load === undefined ? def.read(row) : loadedRelated(def, row, loaded), 
+                new Relator(async (row) => {
+                    const related = def.load === undefined ? def.read(row) : loadedRelated(def, row, loaded);
+                    // A relationship absent on the row reads back `undefined`, not the `null` its own type promises.
+                    for (const one of Array.isArray(related) ? related : related == null ? [] : [related]) {
+                        assertRowId(def.related().type, one);
+                    }
+                    return related;
+                }, 
                 // The lazy overload, so a pair of resources naming each other resolves on use, not on construction.
                 () => def.related().serializerFor(requested, loaded), { relatedName: name }),
             ]));
@@ -57,11 +122,14 @@ export function jsonApiResource(type, attributes, options = {}) {
             return serializer;
         },
         async serialize(row, requested, ...context) {
+            assertRowId(type, row);
             const loaded = await loadIncludedRows(resource, [row], requested, loadContext(context));
             // ts-japi hands back an untyped object; the declared attributes are this resource's own schema.
             return serializeResource(resource.serializerFor(requested, loaded), row, loaded);
         },
         async serializeMany(rows, extras, requested, ...context) {
+            for (const row of rows)
+                assertRowId(type, row);
             const loaded = await loadIncludedRows(resource, rows, requested, loadContext(context));
             return serializeCollection(resource.serializerFor(requested, loaded), rows, extras, loaded);
         },

package/dist/serialize.d.ts

@@ -1,7 +1,17 @@
 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>;
+/** One row as a serializer hands it over. Its `id` is the resource id, which the standard makes a string. */
+export interface Row {
+    id: string;
+    [member: string]: unknown;
+}
+/**
+ * Refuses a row whose id is not a string at runtime. The type is the defence that matters: on a create this fires
+ * after the write committed, so it only stops a wrong document from going out.
+ *
+ * @throws TypeError naming the resource type
+ */
+export declare function assertRowId(type: string, row: unknown): void;
 /**
  * The rows one document's relationship loaders answered, keyed by related type and then by id.
  *
@@ -46,8 +56,8 @@ export interface CollectionExtras {
  * @param data - the row to serialize; its `id` member becomes the resource id
  * @param loaded - what this document's relationship loaders answered, which decides its `included`
  */
-export declare function serializeResource(serializer: ResourceSerializer, data: Row, loaded?: LoadedRows): Promise<Row>;
+export declare function serializeResource(serializer: ResourceSerializer, data: Row, loaded?: LoadedRows): Promise<Record<string, unknown>>;
 /** 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, loaded?: LoadedRows): Promise<Row>;
+export declare function serializeCollection(serializer: ResourceSerializer, items: Row[], extras?: CollectionExtras, loaded?: LoadedRows): Promise<Record<string, unknown>>;
 export {};
 //# sourceMappingURL=serialize.d.ts.map

package/dist/serialize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,UAAU,EAAqB,KAAK,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,0EAA0E;AAC1E,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;AAEvE,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;AA0BD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,kBAAkB,EAC9B,IAAI,EAAE,GAAG,EACT,MAAM,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,GAAG,CAAC,CAEd;AAED,0GAA0G;AAC1G,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,kBAAkB,EAC9B,KAAK,EAAE,GAAG,EAAE,EACZ,MAAM,GAAE,gBAAqB,EAC7B,MAAM,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,GAAG,CAAC,CAMd"}
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,UAAU,EAAqB,KAAK,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,6GAA6G;AAC7G,MAAM,WAAW,GAAG;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI,CAK5D;AAED;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;AAEvE,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;AA8CD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,kBAAkB,EAC9B,IAAI,EAAE,GAAG,EACT,MAAM,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAElC;AAED,0GAA0G;AAC1G,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,kBAAkB,EAC9B,KAAK,EAAE,GAAG,EAAE,EACZ,MAAM,GAAE,gBAAqB,EAC7B,MAAM,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAMlC"}

package/dist/serialize.js

@@ -1,5 +1,17 @@
 import { Relator, Serializer } from 'ts-japi';
 import { JSON_API_VERSION } from './media-type.js';
+/**
+ * Refuses a row whose id is not a string at runtime. The type is the defence that matters: on a create this fires
+ * after the write committed, so it only stops a wrong document from going out.
+ *
+ * @throws TypeError naming the resource type
+ */
+export function assertRowId(type, row) {
+    const id = row?.id;
+    if (typeof id !== 'string') {
+        throw new TypeError(`A "${type}" row carries a ${typeof id} id; a JSON:API id is a string.`);
+    }
+}
 /**
  * Whether the static projection publishes `name`, read so that a `0` counts as hidden under either mode.
  *
@@ -54,7 +66,11 @@ export function createSerializer(type, options, requested) {
             }),
     });
 }
-/** Raises the `jsonapi` member to {@link JSON_API_VERSION}, keeping whatever else ts-japi put there. */
+/**
+ * Raises the `jsonapi` member to {@link JSON_API_VERSION}, keeping whatever else ts-japi put there.
+ *
+ * Typed over a document, not a {@link Row}: a document carries no `id` of its own, unlike the row serialized into it.
+ */
 function stamped(doc) {
     const existing = (doc.jsonapi ?? {});
     return { ...doc, jsonapi: { ...existing, version: JSON_API_VERSION } };
@@ -74,6 +90,19 @@ function includedAsLoaded(document, loaded) {
         included: document.included.filter((resource) => loaded.get(resource.type)?.has(resource.id) ?? true),
     };
 }
+/** The `type` and `id` pair a resource object is identified by. */
+const identity = (resource) => JSON.stringify([resource.type, resource.id]);
+/**
+ * Drops from `included` every resource already present as primary data. A compound document carries one resource
+ * object per type and id, and a client indexing both members by that pair reads the second as a conflict.
+ */
+function withoutPrimary(document) {
+    if (document.included === undefined || document.data == null)
+        return document;
+    const data = Array.isArray(document.data) ? document.data : [document.data];
+    const primary = new Set(data.map(identity));
+    return { ...document, included: document.included.filter((resource) => !primary.has(identity(resource))) };
+}
 /**
  * Serializes one row into a single-resource document.
  *
@@ -81,12 +110,12 @@ function includedAsLoaded(document, loaded) {
  * @param loaded - what this document's relationship loaders answered, which decides its `included`
  */
 export async function serializeResource(serializer, data, loaded) {
-    return stamped(includedAsLoaded(await serializer.serialize(data), loaded));
+    return stamped(withoutPrimary(includedAsLoaded(await serializer.serialize(data), loaded)));
 }
 /** Serializes a list of rows into a collection document, merging in the pagination `links` and `meta`. */
 export async function serializeCollection(serializer, items, extras = {}, loaded) {
     return {
-        ...stamped(includedAsLoaded(await serializer.serialize(items), loaded)),
+        ...stamped(withoutPrimary(includedAsLoaded(await serializer.serialize(items), loaded))),
         ...(extras.links ? { links: extras.links } : {}),
         ...(extras.meta ? { meta: extras.meta } : {}),
     };

package/package.json

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