@zeroxsolutions/response 0.12.0 → 0.12.2

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## 0.12.2 (2026-09-27)
+
+### 🚀 Features
+
+- **response:** declare a refusal's Retry-After off errorResponse ([53cc8d1](https://github.com/zeroxsolutions/zeroxsolutions/commit/53cc8d1))
+- **response:** add the status a refused burst answers with ([910c52d](https://github.com/zeroxsolutions/zeroxsolutions/commit/910c52d))
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Claude Opus 5.5 (1M context)
+- Lương Văn Tú
+
+## 0.12.1 (2026-09-18)
+
+### 🚀 Features
+
+- **response:** load a relationship from the service that holds it ([98cef38](https://github.com/zeroxsolutions/zeroxsolutions/commit/98cef38))
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú
+
 ## 0.12.0 (2026-09-13)
 
 ### 💅 Refactors

package/README.md

@@ -41,6 +41,50 @@ stopped publishing, with both halves compiling and both suites green.
 const { fields, include } = declaredDocumentShape(classes); // feeds `@zeroxsolutions/query`'s permits
 ```
 
+## A relationship another service holds
+
+Where the related rows are not on the row this handler loaded, the relationship declares how to load
+them, and the serializer calls that loader when a request includes it. Nothing composes in the route.
+
+```ts
+export const trips = jsonApiResource('trips', tripAttributesSchema, {
+  relationships: {
+    place: toOne(
+      () => places,               // the resource the loaded rows are published as
+      (row) => row.placeId,       // beside a loader this reads the ID off the row, not the row
+      { load: (ids, context: TripDocumentContext) => context.catalogue.places.byIds(ids) },
+    ),
+  },
+});
+
+// the serialize call carries what the loaders may call, and the compiler asks for it
+return c.json(await trips.serializeMany(rows, { links }, query, { catalogue: c.var.catalogue }));
+```
+
+The loader is called ONCE per document, with every id the page carries for that relationship,
+deduplicated and in no order, so a page of fifty trips costs one call upstream rather than fifty. It is
+called only where the request's `include` names the relationship: a document that includes nothing makes
+no call at all, and still publishes the identifier, which is the key its own row carried.
+
+| The loader | What the document carries |
+| --- | --- |
+| answers a row for an id | that identifier, and the row under `included` |
+| answers no row for an id it was given | that identifier, and nothing under `included` |
+| throws | nothing; the failure comes out of `serialize` for the route to answer |
+
+An id with no row back is how a row this caller may not see stays out of the document. Dropping the
+identifier with it would tell the client the trip has no place, which the row it was read off does not
+say, so including a relationship never changes the `data` a client reads. A loader's failure is left
+alone because the loader is the route's own call on another service, and the upstream error map below
+is what turns it into an answer.
+
+The context is how a loader reaches a client bound to THIS request. A resource is declared once at
+module scope and can close over nothing request-shaped, so the serialize call hands it over, and its
+type is inferred from the loaders the declaration reaches: a resource that reaches one does not compile
+without it, and a resource that reaches none takes no such argument. One document therefore loads under
+one context type, including through a relationship whose own rows came off the row above it
+(`include=days.place` loads every day's place in one call).
+
 ## Errors
 
 The domain raises a plain `Error` subclass carrying only domain data; the transport decides what it

package/dist/api-response.d.ts

@@ -4,7 +4,8 @@ import { errorDocumentSchema } from './errors/index.js';
 import { JSON_API_MEDIA_TYPE } from './media-type.js';
 import type { JsonApiResource } from './resource.js';
 /**
- * An OpenAPI response object for this spelling - one media type, one schema.
+ * An OpenAPI response object for this spelling - one media type, one schema, and the `Retry-After` a
+ * refusal that tells its caller how long to wait declares.
  *
  * Exported because a consumer emitting declarations has to NAME it: a route built from these helpers
  * is an exported const whose type mentions it, and a private one fails that emit with TS4023.
@@ -14,11 +15,36 @@ export interface JsonApiResponse<S extends ZodType> {
     content: Record<typeof JSON_API_MEDIA_TYPE, {
         schema: S;
     }>;
+    headers?: {
+        'Retry-After': RetryAfterHeader;
+    };
 }
-/** The response object for a failure status - the `errors[]` document. */
-export declare function errorResponse(description: string): JsonApiResponse<typeof errorDocumentSchema>;
+/**
+ * The `Retry-After` header object a refusal declares: whole seconds, sent on every answer it gives.
+ *
+ * A type alias, not an interface: `@hono/zod-openapi` types a header as openapi3-ts's `HeaderObject`,
+ * which carries an `x-${string}` index signature, and an interface is not assignable to one.
+ */
+export type RetryAfterHeader = {
+    description: string;
+    required: true;
+    schema: {
+        type: 'integer';
+        minimum: 1;
+    };
+};
+/**
+ * The response object for a failure status - the `errors[]` document.
+ *
+ * @param options.retryAfterSeconds - how long a refused caller is told to wait, in whole seconds.
+ *   Pass it only where the refusal always sets `Retry-After`, since the header is declared required.
+ * @throws {RangeError} when `retryAfterSeconds` is not a positive integer.
+ */
+export declare function errorResponse(description: string, options?: {
+    retryAfterSeconds: number;
+}): JsonApiResponse<typeof errorDocumentSchema>;
 /** The response object for a single resource, off the resource's own declaration. */
-export declare function okResponse<A extends ZodObject>(description: string, resource: JsonApiResource<A>): JsonApiResponse<ZodType<ResourceDocument<output<A>>>>;
+export declare function okResponse<A extends ZodObject, C = unknown>(description: string, resource: JsonApiResource<A, C>): JsonApiResponse<ZodType<ResourceDocument<output<A>>>>;
 /** The response object for a collection, off the resource's own declaration. */
-export declare function listResponse<A extends ZodObject>(description: string, resource: JsonApiResource<A>): JsonApiResponse<ZodType<CollectionDocument<output<A>>>>;
+export declare function listResponse<A extends ZodObject, C = unknown>(description: string, resource: JsonApiResource<A, C>): JsonApiResponse<ZodType<CollectionDocument<output<A>>>>;
 //# sourceMappingURL=api-response.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"api-response.d.ts","sourceRoot":"","sources":["../src/api-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,OAAO;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,OAAO,mBAAmB,EAAE;QAAE,MAAM,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC;CAC5D;AAOD,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAAC,OAAO,mBAAmB,CAAC,CAE9F;AAED,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,CAAC,SAAS,SAAS,EAC5C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,GAC3B,eAAe,CAAC,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAEvD;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,EAC9C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,GAC3B,eAAe,CAAC,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAEzD"}
+{"version":3,"file":"api-response.d.ts","sourceRoot":"","sources":["../src/api-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,OAAO;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,OAAO,mBAAmB,EAAE;QAAE,MAAM,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC;IAC3D,OAAO,CAAC,EAAE;QAAE,aAAa,EAAE,gBAAgB,CAAA;KAAE,CAAC;CAC/C;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,IAAI,CAAC;IACf,MAAM,EAAE;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,OAAO,EAAE,CAAC,CAAA;KAAE,CAAC;CACzC,CAAC;AAOF;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IAAE,iBAAiB,EAAE,MAAM,CAAA;CAAE,GACtC,eAAe,CAAC,OAAO,mBAAmB,CAAC,CAqB7C;AAED,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,GAAG,OAAO,EACzD,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC9B,eAAe,CAAC,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAEvD;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,GAAG,OAAO,EAC3D,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC9B,eAAe,CAAC,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAEzD"}

package/dist/api-response.js

@@ -4,9 +4,32 @@ const answers = (description, schema) => ({
     description,
     content: { [JSON_API_MEDIA_TYPE]: { schema } },
 });
-/** The response object for a failure status - the `errors[]` document. */
-export function errorResponse(description) {
-    return answers(description, errorDocumentSchema);
+/**
+ * The response object for a failure status - the `errors[]` document.
+ *
+ * @param options.retryAfterSeconds - how long a refused caller is told to wait, in whole seconds.
+ *   Pass it only where the refusal always sets `Retry-After`, since the header is declared required.
+ * @throws {RangeError} when `retryAfterSeconds` is not a positive integer.
+ */
+export function errorResponse(description, options) {
+    const response = answers(description, errorDocumentSchema);
+    if (!options) {
+        return response;
+    }
+    const { retryAfterSeconds } = options;
+    if (!Number.isInteger(retryAfterSeconds) || retryAfterSeconds < 1) {
+        throw new RangeError(`retryAfterSeconds must be a positive integer, got ${retryAfterSeconds}`);
+    }
+    return {
+        ...response,
+        headers: {
+            'Retry-After': {
+                description: `Seconds to wait before calling again: ${retryAfterSeconds}`,
+                required: true,
+                schema: { type: 'integer', minimum: 1 },
+            },
+        },
+    };
 }
 /** The response object for a single resource, off the resource's own declaration. */
 export function okResponse(description, resource) {

package/dist/document-load.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The pass that fills a document's relationships from the services that hold them, before it is
+ * serialized. What a relationship's rows look like once here belongs to `serialize.ts`; what a
+ * relationship declares belongs to `relationship.ts`.
+ */
+import type { RelatedResource, RelationshipDef } from './relationship.js';
+import type { LoadedRows, RequestedDocumentShape, 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.
+ *
+ * The identifier is read off the primary row either way, so including a relationship never changes the
+ * linkage a client reads - only what lands under `included`.
+ */
+export declare function loadedRelated<C>(def: RelationshipDef<C>, row: Row, loaded: LoadedRows | undefined): Row | Row[] | null;
+/**
+ * Runs every loader the request's `include` reaches, one call per relationship, with the whole page's
+ * ids.
+ *
+ * A relationship the request did not include is never loaded, so a document that asks for none makes no
+ * call at all and answers `undefined`. Two include paths through one relationship (`place` and
+ * `place.region`) still load it once. A loader's failure is not caught here.
+ *
+ * @param rows - the primary rows of the document, which is the whole page on a collection
+ */
+export declare function loadIncludedRows<C>(root: RelatedResource<C>, rows: readonly Row[], requested: RequestedDocumentShape | undefined, context: C): Promise<LoadedRows | undefined>;
+//# sourceMappingURL=document-load.d.ts.map

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

@@ -0,0 +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"}

package/dist/document-load.js

@@ -0,0 +1,80 @@
+/** The ids one row carries for a loaded relationship. A null or absent key asks for nothing. */
+function readIds(value) {
+    const values = Array.isArray(value) ? value : [value];
+    return values.filter((one) => typeof one === 'string');
+}
+/** The rows one row already carries for a relationship that declares no loader. */
+function readRows(value) {
+    const values = Array.isArray(value) ? value : [value];
+    return values.filter((one) => typeof one === 'object' && one !== null);
+}
+/**
+ * What one loaded relationship hands the serializer for a row: the row its loader answered, or the
+ * identifier alone where it answered none.
+ *
+ * The identifier is read off the primary row either way, so including a relationship never changes the
+ * 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 });
+    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. */
+async function loadRelated(def, rows, loaded, context) {
+    const { load } = def;
+    if (load === undefined)
+        return rows.flatMap((row) => readRows(def.read(row)));
+    // The type is registered before the call, so a loader that answers nothing still means "these are all of them".
+    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))))];
+    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);
+    }
+    return related;
+}
+/**
+ * Runs every loader the request's `include` reaches, one call per relationship, with the whole page's
+ * ids.
+ *
+ * A relationship the request did not include is never loaded, so a document that asks for none makes no
+ * call at all and answers `undefined`. Two include paths through one relationship (`place` and
+ * `place.region`) still load it once. A loader's failure is not caught here.
+ *
+ * @param rows - the primary rows of the document, which is the whole page on a collection
+ */
+export async function loadIncludedRows(root, rows, requested, context) {
+    const paths = requested?.include?.map((path) => path.split('.')) ?? [];
+    if (paths.length === 0)
+        return undefined;
+    const loaded = new Map();
+    let depth = new Map([['', { resource: root, rows }]]);
+    for (let index = 0; index < Math.max(...paths.map((segments) => segments.length)); index += 1) {
+        const reached = new Map();
+        for (const segments of paths) {
+            const name = segments.at(index);
+            const path = segments.slice(0, index + 1).join('.');
+            if (name === undefined || reached.has(path))
+                continue;
+            const parent = depth.get(segments.slice(0, index).join('.'));
+            const def = parent?.resource.relationships[name];
+            // An include path naming no declared relationship is the query guard's refusal, not this pass's.
+            if (parent === undefined || def === undefined)
+                continue;
+            reached.set(path, { parent, def });
+        }
+        if (reached.size === 0)
+            break;
+        // The relationships reached at one depth are separate services, so their loads run together.
+        const entries = [...reached];
+        const walked = await Promise.all(entries.map(([, { parent, def }]) => loadRelated(def, parent.rows, loaded, context)));
+        depth = new Map(entries.map(([path, { def }], at) => [path, { resource: def.related(), rows: walked[at] ?? [] }]));
+    }
+    return loaded.size === 0 ? undefined : loaded;
+}

package/dist/document-shape.d.ts

@@ -13,5 +13,5 @@ export interface DeclaredDocumentShape {
  * The attribute keys ARE the projection, so a list written by hand beside them permits a column the resource stopped
  * publishing, or refuses one it started, with both halves compiling and both suites green.
  */
-export declare function declaredDocumentShape(root: RelatedResource): DeclaredDocumentShape;
+export declare function declaredDocumentShape<C>(root: RelatedResource<C>): DeclaredDocumentShape;
 //# sourceMappingURL=document-shape.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"document-shape.d.ts","sourceRoot":"","sources":["../src/document-shape.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAE7E,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACpC,2GAA2G;IAC3G,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACjC,sEAAsE;IACtE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,qBAAqB,CAuBlF"}
+{"version":3,"file":"document-shape.d.ts","sourceRoot":"","sources":["../src/document-shape.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAE7E,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACpC,2GAA2G;IAC3G,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACjC,sEAAsE;IACtE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,qBAAqB,CAuBxF"}

package/dist/document.d.ts

@@ -33,7 +33,7 @@ export interface CollectionDocument<A> {
     jsonapi?: JsonApiObject;
 }
 /** Wraps `attributes` into a resource object - `{ type, id, attributes, relationships?, links?, meta? }`. */
-export declare function resourceObjectSchema(type: string, attributes: ZodObject, relationships?: Readonly<Record<string, RelationshipDef>>): ZodType;
+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? }`.
  *
@@ -41,7 +41,7 @@ export declare function resourceObjectSchema(type: string, attributes: ZodObject
  * through thunks, so nothing static carries the attribute type, and a client typing a route off this
  * schema would otherwise read every member as `unknown`.
  */
-export declare function resourceDocumentSchema<A = unknown>(root: RelatedResource): ZodType<ResourceDocument<A>>;
+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`. */
-export declare function collectionDocumentSchema<A = unknown>(root: RelatedResource): ZodType<CollectionDocument<A>>;
+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,CAClC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,EACrB,aAAa,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAM,GAC5D,OAAO,CAUT;AAgBD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAQvG;AAED,oGAAoG;AACpG,wBAAgB,wBAAwB,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAQ3G"}
+{"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"}

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

@@ -37,6 +37,10 @@ export declare const BASE_ERROR_CODES: {
         readonly status: 422;
         readonly title: "Unprocessable Entity";
     };
+    readonly TOO_MANY_REQUESTS: {
+        readonly status: 429;
+        readonly title: "Too Many Requests";
+    };
     readonly INTERNAL_SERVER_ERROR: {
         readonly status: 500;
         readonly title: "Internal Server Error";

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

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

package/dist/errors/error-registry.js

@@ -8,6 +8,7 @@ export const BASE_ERROR_CODES = {
     CONFLICT: { status: 409, title: 'Conflict' },
     UNSUPPORTED_MEDIA_TYPE: { status: 415, title: 'Unsupported Media Type' },
     UNPROCESSABLE_ENTITY: { status: 422, title: 'Unprocessable Entity' },
+    TOO_MANY_REQUESTS: { status: 429, title: 'Too Many Requests' },
     INTERNAL_SERVER_ERROR: { status: 500, title: 'Internal Server Error' },
     BAD_GATEWAY: { status: 502, title: 'Bad Gateway' },
 };

package/dist/index.d.ts

@@ -1,7 +1,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 } from './api-response.js';
+export { errorResponse, listResponse, okResponse, type JsonApiResponse, type RetryAfterHeader, } from './api-response.js';
 export type { CollectionDocument, Relationship, ResourceDocument, ResourceObject } from './document.js';
 export { declaredDocumentShape, type DeclaredDocumentShape } from './document-shape.js';
 export { createDomainErrorResolver, defineErrorMap, errorEntry, type DomainErrorAnswer, type DomainErrorEntry, } from './domain-error-resolver.js';
@@ -9,8 +9,8 @@ export type { DomainErrorMap, ErrorClass, UpstreamErrorMap } from './error-map.j
 export { BASE_ERROR_CODES, errorDocumentSchema, JsonApiError, toErrorDocument, toErrorObject, type ErrorDocument, type ErrorLinks, type ErrorObject, type ErrorSource, type ErrorStatus, type JsonApiErrorInit, type ResolvedError, } from './errors/index.js';
 export { JSON_API_MEDIA_TYPE } from './media-type.js';
 export type { JsonApiObject, Link, Meta, PaginationLinks, ResourceIdentifier, ResourceLinks } from './primitives.js';
-export { toMany, toOne, type RelatedResource, type RelationshipDef } from './relationship.js';
+export { 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, RequestedDocumentShape, ResourceSerializer, Row } from './serialize.js';
+export type { CollectionExtras, LoadedRows, RequestedDocumentShape, ResourceSerializer, Row } from './serialize.js';
 export { createUpstreamErrorTranslator, type UpstreamErrorAnswer } from './upstream-error.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

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

package/dist/relationship.d.ts

@@ -1,37 +1,72 @@
 import type { ZodObject, ZodType } from 'zod';
-import type { RequestedDocumentShape, ResourceSerializer, Row } from './serialize.js';
+import type { LoadedRows, RequestedDocumentShape, ResourceSerializer, Row } from './serialize.js';
+/**
+ * Loads the rows of one relationship whose service is not the one answering this document.
+ *
+ * It is called ONCE per document, with every id the page carries for that relationship, deduplicated
+ * and in no order, so a page of fifty rows costs one call and not fifty. It runs only where the
+ * request's `include` names the relationship.
+ *
+ * @param ids - the ids to read; never empty, and each one appears once
+ * @param context - what the serialize call was handed, which is how a load reaches THIS request's client
+ * @returns the rows, in any order; an id it answers no row for keeps its identifier and is not included
+ * @throws whatever the call upstream throws, which leaves `serialize` unchanged for the route to map
+ */
+export interface RelationshipLoader<C> {
+    (ids: readonly string[], context: C): Promise<readonly Row[]>;
+}
+/** What a relationship declares beyond the resource it points at and how to read it off a row. */
+export interface RelationshipOptions<C> {
+    /** Loads the related rows; declared where another service holds them, and left out where the row carries them. */
+    readonly load: RelationshipLoader<C>;
+}
+/**
+ * The context argument a serialize call takes, which is the argument list and not the context itself.
+ *
+ * A resource no relationship of which declares a loader takes none. One that reaches a loader takes
+ * that loader's own context, and the call does not compile without it.
+ */
+export type LoadContextArguments<C> = unknown extends C ? [context?: undefined] : [context: C];
+/** The context a serialize call was handed, for the load pass to give the loaders. */
+export declare function loadContext<C>(contextArguments: LoadContextArguments<C>): C;
 /** What a relationship needs from the resource it points at, so this module never imports the descriptor. */
-export interface RelatedResource {
+export interface RelatedResource<C = unknown> {
     readonly type: string;
-    readonly relationships: Readonly<Record<string, RelationshipDef>>;
+    readonly relationships: Readonly<Record<string, RelationshipDef<C>>>;
     /** This type's declared attributes - the keys are the projection, so they are also what a fieldset may name. */
     readonly attributes: ZodObject;
     /** This type's resource object schema - what a document validates its `data` and `included` against. */
     readonly resourceObject: ZodType;
-    /** This type's serializer under one request, which is what carries a sparse fieldset into `included`. */
-    serializerFor(requested?: RequestedDocumentShape): ResourceSerializer;
+    /**
+     * This type's serializer under one request, which is what carries a sparse fieldset into `included`.
+     *
+     * @param loaded - one document's loaded rows; a serializer built over them serves that document alone
+     */
+    serializerFor(requested?: RequestedDocumentShape, loaded?: LoadedRows): ResourceSerializer;
 }
-/** A relationship: the resource it points at, how many, and how to read it off a row. */
-export interface RelationshipDef {
+/** 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> {
     readonly cardinality: 'one' | 'many';
     /** A thunk, so two resources may name each other without a module-evaluation cycle. */
-    readonly related: () => RelatedResource;
-    /** Reads the related row(s) off the primary row; what ts-japi's `Relator` fetches. */
+    readonly related: () => RelatedResource<C>;
+    /** 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(related: () => RelatedResource, read: (row: Row) => unknown): RelationshipDef;
+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(related: () => RelatedResource, read: (row: Row) => unknown): RelationshipDef;
+export declare function toMany<C = unknown>(related: () => RelatedResource<C>, read: (row: Row) => unknown, options?: RelationshipOptions<C>): RelationshipDef<C>;
 /** The linkage schema for one relationship, pinned to the related `type` so a wrong type fails the parse. */
-export declare function relationshipSchema(def: RelationshipDef): ZodType;
+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. */
-export declare function relationshipsSchema(relationships: Readonly<Record<string, RelationshipDef>>): ZodType | undefined;
+export declare function relationshipsSchema<C>(relationships: Readonly<Record<string, RelationshipDef<C>>>): ZodType | undefined;
 /**
  * Every resource reachable from `root` through its relationships, `root` first, each visited once.
  *
  * This is what calls the thunks, so it runs on first use rather than at declaration - two resources naming
  * each other are both defined by then, which is the whole reason the declaration holds a thunk.
  */
-export declare function reachableResources(root: RelatedResource): RelatedResource[];
+export declare function reachableResources<C>(root: RelatedResource<C>): RelatedResource<C>[];
 //# sourceMappingURL=relationship.d.ts.map

package/dist/relationship.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationship.d.ts","sourceRoot":"","sources":["../src/relationship.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAE9C,OAAO,KAAK,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAEtF,6GAA6G;AAC7G,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;IAClE,gHAAgH;IAChH,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,wGAAwG;IACxG,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,yGAAyG;IACzG,aAAa,CAAC,SAAS,CAAC,EAAE,sBAAsB,GAAG,kBAAkB,CAAC;CACvE;AAED,yFAAyF;AACzF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,KAAK,GAAG,MAAM,CAAC;IACrC,uFAAuF;IACvF,QAAQ,CAAC,OAAO,EAAE,MAAM,eAAe,CAAC;IACxC,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC;CACtC;AAED,mFAAmF;AACnF,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,eAAe,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,GAAG,eAAe,CAElG;AAED,+EAA+E;AAC/E,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,eAAe,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,GAAG,eAAe,CAEnG;AAED,6GAA6G;AAC7G,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAOhE;AAED,+GAA+G;AAC/G,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,GACvD,OAAO,GAAG,SAAS,CAIrB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,eAAe,EAAE,CAS3E"}
+{"version":3,"file":"relationship.d.ts","sourceRoot":"","sources":["../src/relationship.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAElG;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,SAAS,GAAG,EAAE,CAAC,CAAC;CAC/D;AAED,kGAAkG;AAClG,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,kHAAkH;IAClH,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;CACtC;AAED;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI,OAAO,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;AAE/F,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,CAAC,EAAE,gBAAgB,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,CAAC,CAG3E;AAED,6GAA6G;AAC7G,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrE,gHAAgH;IAChH,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,wGAAwG;IACxG,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;;;;OAIG;IACH,aAAa,CAAC,SAAS,CAAC,EAAE,sBAAsB,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,kBAAkB,CAAC;CAC5F;AAED,uGAAuG;AACvG,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,QAAQ,CAAC,WAAW,EAAE,KAAK,GAAG,MAAM,CAAC;IACrC,uFAAuF;IACvF,QAAQ,CAAC,OAAO,EAAE,MAAM,eAAe,CAAC,CAAC,CAAC,CAAC;IAC3C,qGAAqG;IACrG,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC;IACrC,qEAAqE;IACrE,QAAQ,CAAC,IAAI,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;CACvC;AAED,mFAAmF;AACnF,wBAAgB,KAAK,CAAC,CAAC,GAAG,OAAO,EAC/B,OAAO,EAAE,MAAM,eAAe,CAAC,CAAC,CAAC,EACjC,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,EAC3B,OAAO,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC/B,eAAe,CAAC,CAAC,CAAC,CAEpB;AAED,+EAA+E;AAC/E,wBAAgB,MAAM,CAAC,CAAC,GAAG,OAAO,EAChC,OAAO,EAAE,MAAM,eAAe,CAAC,CAAC,CAAC,EACjC,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,EAC3B,OAAO,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC/B,eAAe,CAAC,CAAC,CAAC,CAEpB;AAED,6GAA6G;AAC7G,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAOtE;AAED,+GAA+G;AAC/G,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,GAC1D,OAAO,GAAG,SAAS,CAIrB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,EAAE,CASpF"}

package/dist/relationship.js

@@ -1,12 +1,17 @@
 import { z } from 'zod';
 import { metaSchema, resourceIdentifierSchema, resourceLinksSchema } 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. */
-export function toOne(related, read) {
-    return { cardinality: 'one', related, read };
+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. */
-export function toMany(related, read) {
-    return { cardinality: 'many', related, read };
+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) {

package/dist/resource.d.ts

@@ -1,11 +1,11 @@
 import type { output, ZodObject, ZodType } from 'zod';
 import { type CollectionDocument, type ResourceDocument } from './document.js';
-import type { RelatedResource, RelationshipDef } from './relationship.js';
+import { type LoadContextArguments, type RelatedResource, type RelationshipDef } from './relationship.js';
 import { type CollectionExtras, type RequestedDocumentShape, type Row } from './serialize.js';
 /** Per-entity overrides for a resource declaration. */
-export interface ResourceOptions {
+export interface ResourceOptions<C> {
     /** Relationships this resource declares, keyed by the member name they take in `relationships`. */
-    relationships?: Readonly<Record<string, RelationshipDef>>;
+    relationships?: Readonly<Record<string, RelationshipDef<C>>>;
 }
 /**
  * One resource type declared once: the schemas a route answers with, and the serializer that produces
@@ -14,8 +14,11 @@ export interface ResourceOptions {
  *
  * Its schemas are lazy getters because a relationship holds a THUNK: two resources may name each other,
  * and the graph is only walkable once every module has evaluated.
+ *
+ * `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> extends RelatedResource {
+export interface JsonApiResource<A extends ZodObject, C = unknown> extends RelatedResource<C> {
     readonly attributes: A;
     /** The single-resource document schema - `{ data, included?, links?, meta?, jsonapi? }`. */
     readonly document: ZodType<ResourceDocument<output<A>>>;
@@ -24,12 +27,14 @@ export interface JsonApiResource<A extends ZodObject> extends RelatedResource {
     /**
      * Serializes one row into a single-resource document.
      *
-     * @param requested - a sparse fieldset drops attributes at RUNTIME that the declared type still names.
+     * @param requested - a sparse fieldset drops attributes at RUNTIME that the declared type still names,
+     *   and an included relationship that declares a loader is loaded before the document is built
+     * @param context - what the loaders are given; the call takes it only where a loader is reachable
      */
-    serialize(row: Row, requested?: RequestedDocumentShape): Promise<ResourceDocument<output<A>>>;
+    serialize(row: Row, requested?: RequestedDocumentShape, ...context: LoadContextArguments<C>): Promise<ResourceDocument<output<A>>>;
     /** Serializes rows into a collection document, merging in pagination `links` and `meta`. */
-    serializeMany(rows: Row[], extras?: CollectionExtras, requested?: RequestedDocumentShape): Promise<CollectionDocument<output<A>>>;
+    serializeMany(rows: Row[], extras?: CollectionExtras, requested?: RequestedDocumentShape, ...context: LoadContextArguments<C>): Promise<CollectionDocument<output<A>>>;
 }
 /** Declares a JSON:API resource type - its `type`, the schema of its `attributes`, and its relationships. */
-export declare function jsonApiResource<A extends ZodObject>(type: string, attributes: A, options?: ResourceOptions): JsonApiResource<A>;
+export declare function jsonApiResource<A extends ZodObject, C = unknown>(type: string, attributes: A, options?: ResourceOptions<C>): JsonApiResource<A, C>;
 //# 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;AACvB,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAE3B,KAAK,GAAG,EACT,MAAM,gBAAgB,CAAC;AAExB,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,mGAAmG;IACnG,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;CAC3D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,SAAS,CAAE,SAAQ,eAAe;IAC3E,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IACvB,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,8EAA8E;IAC9E,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9F,4FAA4F;IAC5F,aAAa,CACX,IAAI,EAAE,GAAG,EAAE,EACX,MAAM,CAAC,EAAE,gBAAgB,EACzB,SAAS,CAAC,EAAE,sBAAsB,GACjC,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC3C;AAgBD,6GAA6G;AAC7G,wBAAgB,eAAe,CAAC,CAAC,SAAS,SAAS,EACjD,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,CAAC,EACb,OAAO,GAAE,eAAoB,GAC5B,eAAe,CAAC,CAAC,CAAC,CA0DpB"}
+{"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"}

package/dist/resource.js

@@ -1,5 +1,7 @@
 import { Relator } from 'ts-japi';
 import { collectionDocumentSchema, resourceDocumentSchema, resourceObjectSchema, } from './document.js';
+import { loadedRelated, loadIncludedRows } from './document-load.js';
+import { loadContext } from './relationship.js';
 import { createSerializer, serializeCollection, serializeResource, } from './serialize.js';
 /**
  * How many requested shapes one resource keeps a serializer for. The shape is spelled by the caller's
@@ -35,28 +37,31 @@ export function jsonApiResource(type, attributes, options = {}) {
         get collectionDocument() {
             return (many ??= collectionDocumentSchema(resource));
         },
-        serializerFor(requested) {
+        serializerFor(requested, loaded) {
             const key = shapeKey(requested);
-            const built = serializers.get(key);
+            const built = loaded === undefined ? serializers.get(key) : undefined;
             if (built)
                 return built;
             const relators = Object.fromEntries(Object.entries(relationships).map(([name, def]) => [
                 name,
-                new Relator(async (row) => def.read(row), 
+                new Relator(async (row) => def.load === undefined ? def.read(row) : loadedRelated(def, row, loaded), 
                 // The lazy overload, so a pair of resources naming each other resolves on use, not on construction.
-                () => def.related().serializerFor(requested), { relatedName: name }),
+                () => def.related().serializerFor(requested, loaded), { relatedName: name }),
             ]));
             const serializer = createSerializer(type, { projection, relators }, requested);
-            if (serializers.size < MAX_KEPT_SERIALIZERS)
+            // A serializer holding one document's loaded rows would answer the next request with them.
+            if (loaded === undefined && serializers.size < MAX_KEPT_SERIALIZERS)
                 serializers.set(key, serializer);
             return serializer;
         },
-        serialize(row, requested) {
+        async serialize(row, requested, ...context) {
+            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), row);
+            return serializeResource(resource.serializerFor(requested, loaded), row, loaded);
         },
-        serializeMany(rows, extras, requested) {
-            return serializeCollection(resource.serializerFor(requested), rows, extras);
+        async serializeMany(rows, extras, requested, ...context) {
+            const loaded = await loadIncludedRows(resource, rows, requested, loadContext(context));
+            return serializeCollection(resource.serializerFor(requested, loaded), rows, extras, loaded);
         },
     };
     return resource;

package/dist/serialize.d.ts

@@ -2,6 +2,14 @@ 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>;
+/**
+ * The rows one document's relationship loaders answered, keyed by related type and then by id.
+ *
+ * A type listed here was loaded for this document, so it publishes exactly the rows its loader
+ * answered. An id the loader was asked for and did not answer is linkage the parent row carried, and
+ * there is no resource object for it.
+ */
+export type LoadedRows = ReadonlyMap<string, ReadonlyMap<string, Row>>;
 /** A ts-japi serializer over rows. */
 export type ResourceSerializer = Serializer<Row>;
 type SerializerConfig = Partial<SerializerOptions<Row>>;
@@ -36,9 +44,10 @@ export interface CollectionExtras {
  * Serializes one row into a single-resource document.
  *
  * @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): Promise<Row>;
+export declare function serializeResource(serializer: ResourceSerializer, data: Row, loaded?: LoadedRows): Promise<Row>;
 /** Serializes a list of rows into a collection document, merging in the pagination `links` and `meta`. */
-export declare function serializeCollection(serializer: ResourceSerializer, items: Row[], extras?: CollectionExtras): Promise<Row>;
+export declare function serializeCollection(serializer: ResourceSerializer, items: Row[], extras?: CollectionExtras, loaded?: LoadedRows): Promise<Row>;
 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,EAAE,KAAK,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,0EAA0E;AAC1E,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C,sCAAsC;AACtC,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;AAEjD,KAAK,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC;AAExD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,mFAAmF;IACnF,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IACrD,mEAAmE;IACnE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAgCD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,gBAAgB,EAC1B,SAAS,CAAC,EAAE,sBAAsB,GACjC,kBAAkB,CAgBpB;AAED,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAQD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,UAAU,EAAE,kBAAkB,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAE/F;AAED,0GAA0G;AAC1G,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,kBAAkB,EAC9B,KAAK,EAAE,GAAG,EAAE,EACZ,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CAAC,GAAG,CAAC,CAMd"}
+{"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"}

package/dist/serialize.js

@@ -59,18 +59,34 @@ function stamped(doc) {
     const existing = (doc.jsonapi ?? {});
     return { ...doc, jsonapi: { ...existing, version: JSON_API_VERSION } };
 }
+/**
+ * Drops from `included` every resource of a loaded type that its loader did not answer.
+ *
+ * A loaded relationship hands the serializer the identifier its parent row carried whenever the loader
+ * answered no row for it, so that the linkage stays. That identifier is not a resource, and a document
+ * carrying it under `included` would publish a resource object with no attributes.
+ */
+function includedAsLoaded(document, loaded) {
+    if (loaded === undefined || document.included === undefined)
+        return document;
+    return {
+        ...document,
+        included: document.included.filter((resource) => loaded.get(resource.type)?.has(resource.id) ?? true),
+    };
+}
 /**
  * Serializes one row into a single-resource document.
  *
  * @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 async function serializeResource(serializer, data) {
-    return stamped((await serializer.serialize(data)));
+export async function serializeResource(serializer, data, loaded) {
+    return stamped(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 = {}) {
+export async function serializeCollection(serializer, items, extras = {}, loaded) {
     return {
-        ...stamped((await serializer.serialize(items))),
+        ...stamped(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.0",
+  "version": "0.12.2",
   "private": false,
   "type": "module",
   "sideEffects": false,