@alchemy_cms/json_api 4.0.0 → 5.0.0

package/README.md

@@ -12,11 +12,22 @@ or with the package manager of your choice.
 
 ## Usage
 
-`deserialize` converts a JSON:API response into plain, acyclic JS objects:
-each resource's attributes are flattened with its `id`, and relationships
-present in `included` become nested objects (absent ones become `{ id }`
-stubs). Reference cycles are broken automatically, so the result is always
-safe to `JSON.stringify`.
+`deserialize` converts a JSON:API response into plain JS objects: each
+resource's attributes are flattened with its `id`, and relationships present in
+`included` become nested objects (absent ones become `{ id }` stubs).
+
+Each included resource is materialized **once** and shared by every reference
+to it, so the result stays proportional to the size of the response even when
+resources reference each other heavily. A consequence is that back-references
+(e.g. a menu node's `parent`, which lists the node among its `children`) are
+real references, and the result may contain **cycles**:
+
+- `structuredClone`, [devalue](https://github.com/sveltejs/devalue) (Nuxt
+  payloads) and Vue/React state handle this fine.
+- `JSON.stringify` does not. If you need JSON, serialize a projection of the
+  fields you need, or use a cycle-aware serializer.
+- Mutating a resource is visible everywhere it is referenced. Copy before
+  mutating.
 
 ```js
 import { deserialize } from "@alchemy_cms/json_api"

package/dist/deserialize.d.ts

@@ -1,5 +1,6 @@
 /**
- * Deserialize a JSON:API document into plain, acyclic objects.
+ * Deserialize a JSON:API document into plain objects, sharing one object per
+ * resource. The result may contain reference cycles.
  *
  * The `document` is a raw API response with no compile-time shape, so the
  * parameter is `unknown`. The caller names the shape it expects out via `T`;

package/dist/deserialize.js

@@ -1,18 +1,21 @@
 //#region src/deserialize.ts
 var e = ({ type: e, id: t }) => `${e}:${t}`, t = ({ id: e }) => ({ id: e }), n = (t) => new Map(t.map((t) => [e(t), t])), r = (n, r, i) => {
-	let o = e(i), s = r.has(o) ? void 0 : n.get(o);
-	return s ? a(n, r, s) : t(i);
+	let o = n.get(e(i));
+	return o ? a(n, r, o) : t(i);
 }, i = (e, t, n) => Array.isArray(n) ? n.map((n) => r(e, t, n)) : n ? r(e, t, n) : null, a = (t, n, r) => {
-	let a = new Set(n).add(e(r)), o = Object.entries(r.relationships ?? {}).map(([e, n]) => [e, i(t, a, n?.data ?? null)]);
-	return {
+	let a = e(r), o = n.get(a);
+	if (o) return o;
+	let s = {
 		...r.attributes,
-		id: r.id,
-		...Object.fromEntries(o)
+		id: r.id
 	};
+	n.set(a, s);
+	for (let [e, a] of Object.entries(r.relationships ?? {})) s[e] = i(t, n, a?.data ?? null);
+	return s;
 };
 function o(e) {
-	let { data: t = null, included: r = [] } = e == null ? {} : structuredClone(e), i = n(r), o = (e) => a(i, /* @__PURE__ */ new Set(), e);
-	return Array.isArray(t) ? t.map(o) : t ? o(t) : null;
+	let { data: t = null, included: r = [] } = e == null ? {} : structuredClone(e), i = n(r), o = /* @__PURE__ */ new Map(), s = (e) => a(i, o, e);
+	return Array.isArray(t) ? t.map(s) : t ? s(t) : null;
 }
 //#endregion
 export { o as default, o as deserialize };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alchemy_cms/json_api",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "JSON API deserializer for AlchemyCMS",
   "license": "BSD-3-Clause",
   "repository": {