@zeroxsolutions/jsonapi 0.13.0 → 0.13.2

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 0.13.2 (2026-10-06)
+
+No code changes. It depends on @zeroxsolutions/response, so its version follows response 0.14.4.
+
+## 0.13.1 (2026-09-30)
+
+### 🚀 Features
+
+- **jsonapi:** build the request document a client sends ([20ca1a6](https://github.com/zeroxsolutions/zeroxsolutions/commit/20ca1a6))
+
+### ❤️ Thank You
+
+- Claude Opus 5.5 (1M context)
+- Lương Văn Tú
+
 ## 0.13.0 (2026-09-29)
 
 ### 🩹 Fixes

package/README.md

@@ -27,7 +27,7 @@ what keeps `hono` out of the package an SPA also loads.
 | Import                           | Use in                  | What it holds                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | -------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@zeroxsolutions/jsonapi`        | services, gateway       | `negotiateJsonApi` - the whole decision, from `Content-Type`, `Accept` and the `ext` URIs this surface supports (`supportedExtensions`), to the `JsonApiError` to reject with or `null`: 415 where `Content-Type` is the JSON:API media type carrying a parameter beyond `ext`/`profile` or an `ext` outside `supportedExtensions`; 406 where `Accept` holds JSON:API instances and every one carries such a parameter or `ext`; nothing else |
-| `@zeroxsolutions/jsonapi/client` | SPA, external consumers | `deserializeDocument` (jsona), `readResource` / `readCollection` over it - the same flattening, typed off the route's own document - `readRelated` for what an `include` resolved, which no document type can name; and `ApiError`, the non-2xx a caller throws once a response has come back                                                                                                                                                 |
+| `@zeroxsolutions/jsonapi/client` | SPA, external consumers | `deserializeDocument` (jsona), `readResource` / `readCollection` over it - the same flattening, typed off the route's own document - `readRelated` for what an `include` resolved, which no document type can name; `toRequestDocument`, the JSON:API request document a write sends, each relationship wrapped in its relationship object; and `ApiError`, the non-2xx a caller throws once a response has come back                         |
 
 A transport mounts the decision rather than calling it: `jsonApiContentNegotiation` is the Hono adapter
 over it, and it lives with the other framework wiring. `negotiateJsonApi` itself takes the surface's

package/dist/client/index.d.ts

@@ -1,7 +1,9 @@
 /**
- * The client half of the standard: the document a response carries, flattened once, and the failure a caller throws.
+ * The client half of the standard: the document a response carries, flattened once, the document a write sends, and
+ * the failure a caller throws.
  */
 export { ApiError } from './api-error.js';
 export { deserializeDocument } from './deserialize.js';
 export { readCollection, readRelated, readResource, type Collection, type CollectionOf, type Resource, type ResourceOf, } from './read-document.js';
+export { toRequestDocument, type RelationshipInput, type ToRequestDocument } from './request-document.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EACL,cAAc,EACd,WAAW,EACX,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,UAAU,GAChB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EACL,cAAc,EACd,WAAW,EACX,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,UAAU,GAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/client/index.js

@@ -1,6 +1,8 @@
 /**
- * The client half of the standard: the document a response carries, flattened once, and the failure a caller throws.
+ * The client half of the standard: the document a response carries, flattened once, the document a write sends, and
+ * the failure a caller throws.
  */
 export { ApiError } from './api-error.js';
 export { deserializeDocument } from './deserialize.js';
 export { readCollection, readRelated, readResource, } from './read-document.js';
+export { toRequestDocument } from './request-document.js';

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

@@ -0,0 +1,43 @@
+/** One relationship as a client writes it: the related resource's identifier, `null` to clear a to-one, or a list. */
+export type RelationshipInput = {
+    readonly type: string;
+    readonly id: string;
+} | null | readonly {
+    readonly type: string;
+    readonly id: string;
+}[];
+/**
+ * The request document {@link toRequestDocument} returns: the `type`, then each member it was handed and no other, so
+ * a route's declared body checks it member by member.
+ */
+export type ToRequestDocument<T extends string, Id, A, L> = {
+    data: {
+        type: T;
+    } & ([Id] extends [string] ? {
+        id: Id;
+    } : unknown) & ([A] extends [never] ? unknown : {
+        attributes: A;
+    }) & ([L] extends [never] ? unknown : {
+        relationships: {
+            [K in keyof L]: {
+                data: L[K];
+            };
+        };
+    });
+};
+/**
+ * Builds the JSON:API request document a write sends: one resource object of `type`, its attributes, and each
+ * relationship wrapped in the relationship object the standard requires, so no caller writes `{ data: ... }` by hand.
+ *
+ * The result is typed from the call alone, and never from the type it is assigned to, so a route's declared body can
+ * refuse a document missing the `id` an update needs.
+ *
+ * @param init - `id` on an update and never on a create; the attributes the write changes; each relationship as the
+ *   related resource's identifier, `null` to clear a to-one, or a list for a to-many
+ */
+export declare function toRequestDocument<const T extends string, Id extends string | undefined = undefined, A extends object = never, const L extends Readonly<Record<string, RelationshipInput>> = never>(type: T, init: {
+    id?: Id;
+    attributes?: A;
+    relationships?: L;
+}): ToRequestDocument<T, NoInfer<Id>, NoInfer<A>, NoInfer<L>>;
+//# sourceMappingURL=request-document.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"request-document.d.ts","sourceRoot":"","sources":["../../src/client/request-document.ts"],"names":[],"mappings":"AAAA,sHAAsH;AACtH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9C,IAAI,GACJ,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI;IAC1D,IAAI,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,GAAG,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG;QAAE,EAAE,EAAE,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,GAChE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,OAAO,GAAG;QAAE,UAAU,EAAE,CAAC,CAAA;KAAE,CAAC,GACnD,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,OAAO,GAAG;QAAE,aAAa,EAAE;aAAG,CAAC,IAAI,MAAM,CAAC,GAAG;gBAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;aAAE;SAAE,CAAA;KAAE,CAAC,CAAC;CAC3F,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,CAAC,CAAC,SAAS,MAAM,EACtB,EAAE,SAAS,MAAM,GAAG,SAAS,GAAG,SAAS,EACzC,CAAC,SAAS,MAAM,GAAG,KAAK,EACxB,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,GAAG,KAAK,EAEnE,IAAI,EAAE,CAAC,EACP,IAAI,EAAE;IAAE,EAAE,CAAC,EAAE,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IAAC,aAAa,CAAC,EAAE,CAAC,CAAA;CAAE,GACnD,iBAAiB,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAe3D"}

package/dist/client/request-document.js

@@ -0,0 +1,25 @@
+/**
+ * Builds the JSON:API request document a write sends: one resource object of `type`, its attributes, and each
+ * relationship wrapped in the relationship object the standard requires, so no caller writes `{ data: ... }` by hand.
+ *
+ * The result is typed from the call alone, and never from the type it is assigned to, so a route's declared body can
+ * refuse a document missing the `id` an update needs.
+ *
+ * @param init - `id` on an update and never on a create; the attributes the write changes; each relationship as the
+ *   related resource's identifier, `null` to clear a to-one, or a list for a to-many
+ */
+export function toRequestDocument(type, init) {
+    const { id, attributes, relationships } = init;
+    const linkage = relationships === undefined
+        ? undefined
+        : Object.fromEntries(Object.entries(relationships).map(([name, data]) => [name, { data }]));
+    // The members are the ones handed, which is what the conditional type above spells.
+    return {
+        data: {
+            type,
+            ...(id === undefined ? {} : { id }),
+            ...(attributes === undefined ? {} : { attributes }),
+            ...(linkage === undefined ? {} : { relationships: linkage }),
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/jsonapi",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -30,6 +30,6 @@
   "dependencies": {
     "jsona": "^1.12.0",
     "tslib": "^2.3.0",
-    "@zeroxsolutions/response": "0.14.2"
+    "@zeroxsolutions/response": "0.14.4"
   }
 }