@zeroxsolutions/response 0.12.2 → 0.14.0

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

@@ -44,20 +44,27 @@ export interface RelatedResource<C = unknown> {
      */
     serializerFor(requested?: RequestedDocumentShape, loaded?: LoadedRows): ResourceSerializer;
 }
+/** The context a related resource's loaders run under, read off the resource so a caller never spells it. */
+export type ContextOf<R> = R extends RelatedResource<infer C> ? C : unknown;
 /** A relationship: the resource it points at, how many, how to read it off a row, and who loads it. */
-export interface RelationshipDef<C = unknown> {
+export interface RelationshipDef<C = unknown, R extends RelatedResource<never> = RelatedResource<C>> {
     readonly cardinality: 'one' | 'many';
     /** A thunk, so two resources may name each other without a module-evaluation cycle. */
-    readonly related: () => RelatedResource<C>;
+    readonly related: () => R;
     /** Reads the related row(s) off the primary row, or the related id(s) where a loader is declared. */
     readonly read: (row: Row) => unknown;
     /** Absent where the primary row already carries the related rows. */
     readonly load?: RelationshipLoader<C>;
 }
-/** Declares a to-one relationship - its `data` is a single identifier, or null. */
-export declare function toOne<C = unknown>(related: () => RelatedResource<C>, read: (row: Row) => unknown, options?: RelationshipOptions<C>): RelationshipDef<C>;
-/** Declares a to-many relationship - its `data` is an array of identifiers. */
-export declare function toMany<C = unknown>(related: () => RelatedResource<C>, read: (row: Row) => unknown, options?: RelationshipOptions<C>): RelationshipDef<C>;
+/**
+ * Declares a to-one relationship - its `data` is a single identifier, or null.
+ *
+ * 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.
+ */
+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>;
+/** 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>;
 /** 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

@@ -1,25 +1,34 @@
 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.
     return contextArguments[0];
 }
-/** Declares a to-one relationship - its `data` is a single identifier, or null. */
+/**
+ * Declares a to-one relationship - its `data` is a single identifier, or null.
+ *
+ * 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.
+ */
 export function toOne(related, read, options) {
     return { cardinality: 'one', related, read, load: options?.load };
 }
-/** Declares a to-many relationship - its `data` is an array of identifiers. */
+/** Declares a to-many relationship - its `data` is an array of identifiers. The context is inferred as for `toOne`. */
 export function toMany(related, read, options) {
     return { cardinality: 'many', related, read, load: options?.load };
 }
 /** 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

@@ -2,10 +2,12 @@ import type { output, ZodObject, ZodType } from 'zod';
 import { type CollectionDocument, type ResourceDocument } from './document.js';
 import { type LoadContextArguments, type RelatedResource, type RelationshipDef } from './relationship.js';
 import { type CollectionExtras, type RequestedDocumentShape, type Row } from './serialize.js';
+/** The context every loader in a relationship map runs under. */
+type ContextOfRelationships<R> = R[keyof R] extends RelationshipDef<infer C, any> ? C : unknown;
 /** Per-entity overrides for a resource declaration. */
-export interface ResourceOptions<C> {
+export interface ResourceOptions<R> {
     /** Relationships this resource declares, keyed by the member name they take in `relationships`. */
-    relationships?: Readonly<Record<string, RelationshipDef<C>>>;
+    relationships?: R;
 }
 /**
  * One resource type declared once: the schemas a route answers with, and the serializer that produces
@@ -18,8 +20,10 @@ export interface ResourceOptions<C> {
  * `C` is the context its loaders are called with, inferred from the relationships it declares and from
  * the resources they point at, so every resource in one document's graph loads under one context.
  */
-export interface JsonApiResource<A extends ZodObject, C = unknown> extends RelatedResource<C> {
+export interface JsonApiResource<A extends ZodObject, C = unknown, T extends string = string, R extends Readonly<Record<string, RelationshipDef<any, any>>> = Readonly<Record<string, RelationshipDef<C>>>> extends RelatedResource<C> {
+    readonly type: T;
     readonly attributes: A;
+    readonly relationships: R;
     /** The single-resource document schema - `{ data, included?, links?, meta?, jsonapi? }`. */
     readonly document: ZodType<ResourceDocument<output<A>>>;
     /** The collection document schema - the same members with `data` an array. */
@@ -35,6 +39,16 @@ export interface JsonApiResource<A extends ZodObject, C = unknown> extends Relat
     /** 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<A extends ZodObject, C = unknown>(type: string, attributes: A, options?: ResourceOptions<C>): JsonApiResource<A, C>;
+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,uDAAuD;AACvD,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,mGAAmG;IACnG,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC9D;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,GAAG,OAAO,CAAE,SAAQ,eAAe,CAAC,CAAC,CAAC;IAC3F,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IACvB,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,8EAA8E;IAC9E,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE;;;;;;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,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,GAAG,OAAO,EAC9D,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,CAAC,EACb,OAAO,GAAE,eAAe,CAAC,CAAC,CAAM,GAC/B,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAsEvB"}
+{"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,9 +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 = {}) {
-    const relationships = options.relationships ?? {};
+    // 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();
@@ -44,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 }),
             ]));
@@ -55,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.12.2",
+  "version": "0.14.0",
   "private": false,
   "type": "module",
   "sideEffects": false,