yayson 4.0.0 → 4.2.0

package/README.md

@@ -2,7 +2,10 @@
 
 A library for serializing and reading [JSON API](http://jsonapi.org) data in JavaScript.
 
-YAYSON supports both ESM and CommonJS, has zero dependencies, and works in the browser and in Node.js 20+.
+- Zero dependencies
+- Full TypeScript support with type inference from schema registries
+- Optional runtime validation with [Zod](https://github.com/colinhacks/zod) or any compatible library
+- Dual ESM/CJS package — works in browsers and Node.js 20+
 
 [![NPM](https://nodei.co/npm/yayson.png?downloads=true)](https://nodei.co/npm/yayson/)
 
@@ -12,85 +15,6 @@ YAYSON supports both ESM and CommonJS, has zero dependencies, and works in the b
 npm install yayson
 ```
 
-## Upgrading from 3.x
-
-Version 4.x is a full TypeScript rewrite with several new features and breaking changes.
-
-### New features
-
-- **TypeScript support** — Full type definitions included, with type inference from schema registries
-- **Schema validation** — Optional runtime validation using [Zod](https://github.com/colinhacks/zod) or any compatible library with `parse()`/`safeParse()` methods
-- **Dual ESM/CJS package** — Native ES module support alongside CommonJS
-- **`yayson/utils` entry point** — Helper functions (`getType`, `getLinks`, `getMeta`, `getRelationshipLinks`, `getRelationshipMeta`) for reading model metadata
-- **`retrieveAll(type, data)`** — Sync data and return only models of a specific type
-- **`syncAll()`** — Always returns an array (useful when you always want array behavior)
-- **`fields` property** — Limit which attributes a Presenter includes in its output
-
-### Breaking changes
-
-#### Node.js version
-
-Node.js 20+ is now required (was 14+).
-
-#### Metadata uses Symbols instead of plain properties
-
-In 3.x, resource type, links, and meta were stored as plain properties on models (`model.type`, `model.links`, `model.meta`). Relationship metadata used `model._links` and `model._meta`.
-
-In 4.x, these use Symbol keys to avoid collisions with your data. Use the helpers from `yayson/utils`:
-
-```javascript
-// 3.x
-model.type
-model.links
-model.meta
-relatedModel._links
-relatedModel._meta
-
-// 4.x
-import { getType, getLinks, getMeta, getRelationshipLinks, getRelationshipMeta } from 'yayson/utils'
-getType(model)
-getLinks(model)
-getMeta(model)
-getRelationshipLinks(relatedModel)
-getRelationshipMeta(relatedModel)
-```
-
-#### `sync()` restores 3.x behavior
-
-`sync()` now matches 3.x behavior: single resources return a model directly, collections return an array. If you always want an array, use `syncAll()`.
-
-```javascript
-// Single resource — returns model directly
-const event = store.sync({ data: { type: 'events', id: '1', attributes: { name: 'Demo' } } })
-event.name // 'Demo'
-
-// Collection — returns array
-const events = store.sync({ data: [{ type: 'events', id: '1', attributes: { name: 'Demo' } }] })
-events.length // 1
-
-// Always returns array
-const events = store.syncAll(data)
-
-// retrieve/retrieveAll also available
-const event = store.retrieve('events', data)
-const events = store.retrieveAll('events', data)
-```
-
-#### Document-level meta uses Symbols
-
-In 3.x, document-level metadata was stored as `result.meta`. In 4.x, it uses a Symbol key:
-
-```javascript
-// 3.x
-const result = store.sync(data)
-result.meta // { total: 100 }
-
-// 4.x
-import { META } from 'yayson/utils'
-const result = store.sync(data)
-result[META] // { total: 100 }
-```
-
 ## Presenting data
 
 A basic `Presenter` can look like this:
@@ -157,6 +81,49 @@ class BikePresenter extends Presenter {
 }
 ```
 
+### Declaring cardinality and optional relationships
+
+By default a missing relationship renders as `data: null`. This isn't valid JSON:API for to-many relationships (the spec requires `[]`) and can mislead clients when a relationship simply wasn't loaded. Use the config form to declare cardinality and optional semantics:
+
+```javascript
+class BikePresenter extends Presenter {
+  static type = 'bikes'
+
+  relationships() {
+    return {
+      wheels: { presenter: WheelPresenter, hasMany: true },
+      manufacturer: { presenter: ManufacturerPresenter, optional: true },
+      accessories: { presenter: AccessoryPresenter, hasMany: true, optional: true },
+    }
+  }
+}
+
+BikePresenter.render({ id: 1 })
+```
+
+This produces:
+
+```javascript
+{
+  data: {
+    id: '1',
+    type: 'bikes',
+    attributes: {},
+    relationships: {
+      wheels: { data: [] } // hasMany + no data → empty array, not null
+      // manufacturer and accessories omitted entirely — they weren't loaded
+    }
+  }
+}
+```
+
+- **`hasMany: true`** — declares a to-many relationship. Empty or missing data renders as `data: []` instead of `data: null`.
+- **`optional: true`** — when the relationship key is absent from the instance, the relationship is omitted from the output (or rendered with just `links` if `links()` configures one for that key). An explicit `null` on the instance still renders as `data: null` — `optional` distinguishes "not loaded" from "explicitly empty".
+
+In `payload()` output, `optional` omission is disabled (a write request asserts state, so dropping a relationship would be misleading), but `hasMany` still applies so a client can correctly clear a to-many with `data: []`.
+
+The bare-class form (`relationships() { return { wheels: WheelPresenter } }`) is unchanged.
+
 ### Filtering attributes with fields
 
 Use the static `fields` property to limit which attributes are included in the output:
@@ -256,6 +223,49 @@ This would produce:
 
 Both `meta` and `links` are optional and add top-level properties to the JSON API document.
 
+### Creating payloads with payload()
+
+Use `payload()` to serialize a single resource for create or update API requests. Unlike `render()`, it omits `included` resources — only the primary resource with relationship linkage is produced:
+
+```javascript
+class WheelPresenter extends Presenter {
+  static type = 'wheels'
+}
+
+class BikePresenter extends Presenter {
+  static type = 'bikes'
+  relationships() {
+    return { wheels: WheelPresenter }
+  }
+}
+
+// Create (no id)
+BikePresenter.payload({ name: 'Monark', wheels: [{ id: 1 }, { id: 2 }] })
+```
+
+This would produce:
+
+```javascript
+{
+  data: {
+    type: 'bikes',
+    attributes: {
+      name: 'Monark'
+    },
+    relationships: {
+      wheels: {
+        data: [
+          { type: 'wheels', id: '1' },
+          { type: 'wheels', id: '2' }
+        ]
+      }
+    }
+  }
+}
+```
+
+For updates, include an `id` and it will appear in the output. `payload()` also accepts `meta` and `links` options like `render()`. It throws on arrays and null — use `render()` for collections.
+
 ## Parsing data
 
 You can use a `Store` like this:
@@ -266,7 +276,7 @@ const { Store } = yayson()
 const store = new Store()
 
 const data = await adapter.get({ path: '/events/' + id })
-const event = store.sync(data) // single resource → model directly
+const event = store.sync(data) // single resource -> model directly
 ```
 
 The `sync()` method returns a single model for single resources and an array for collections. Use `syncAll()` if you always want an array.
@@ -303,6 +313,55 @@ const events = store.retrieveAll('events', response)
 // events.length === 2
 ```
 
+### Building models from create payloads
+
+Use `build()` to create a model from a JSON:API document without storing it. This is useful for create payloads where the `id` may not yet exist:
+
+```javascript
+const model = store.build({
+  data: {
+    type: 'events',
+    attributes: { name: 'New Event' },
+  },
+})
+
+model.name // 'New Event'
+model.id // undefined
+```
+
+If the store already has synced data, `build()` resolves relationships against it. Unresolved references become stubs with just `id` and type:
+
+```javascript
+store.syncAll({
+  data: [{ type: 'images', id: '5', attributes: { url: 'http://example.com/img.jpg' } }],
+})
+
+const model = store.build({
+  data: {
+    type: 'events',
+    attributes: { name: 'New Event' },
+    relationships: {
+      image: { data: { type: 'images', id: '5' } },
+      sponsor: { data: { type: 'sponsors', id: '99' } },
+    },
+  },
+})
+
+model.image.url // 'http://example.com/img.jpg' (resolved from store)
+model.sponsor.id // '99' (stub — not in store)
+```
+
+A static version is also available when you don't need a store instance:
+
+```javascript
+const model = Store.build({
+  data: {
+    type: 'events',
+    attributes: { name: 'New Event' },
+  },
+})
+```
+
 ### Finding synced data
 
 You can also find in previously synced data:
@@ -451,17 +510,39 @@ const store = new Store({
 const event = store.sync({
   event: { id: '1', name: 'Demo Event' },
 })
-// single resource → returns model directly
+// single resource -> returns model directly
 
 const allSynced = store.syncAll({
   event: { id: '1', name: 'Demo Event' },
   images: [{ id: '2', url: 'http://example.com/image.jpg' }],
 })
 // syncAll always returns array
+```
 
+```javascript
 const event = store.find('event', '1')
 ```
 
+#### Creating payloads with payload()
+
+The legacy presenter also supports `payload()` for create/update requests. It produces the legacy envelope format without `links` or sideloaded collections:
+
+```javascript
+class TirePresenter extends Presenter {
+  static type = 'tire'
+}
+
+class CarPresenter extends Presenter {
+  static type = 'car'
+  relationships() {
+    return { tires: TirePresenter }
+  }
+}
+
+CarPresenter.payload({ name: 'Volvo', tires: [{ id: 1 }, { id: 2 }] })
+// { car: { name: 'Volvo', tires: [1, 2] } }
+```
+
 #### Filtering by type with retrieveAll
 
 Use `retrieveAll()` to sync data and return only models of a specific type:
@@ -485,6 +566,40 @@ const store = new Store({
 })
 ```
 
+#### Building models from create payloads
+
+The legacy store also supports `build()` for creating models without storing them:
+
+```javascript
+const model = store.build({
+  event: { name: 'New Event' },
+})
+
+model.name // 'New Event'
+model.id // undefined
+```
+
+Relationships are resolved against existing store data when available:
+
+```javascript
+store.syncAll({
+  links: { 'event.images': { type: 'images' } },
+  images: [{ id: '2', name: 'Header' }],
+})
+
+const model = store.build({
+  event: { name: 'New Event', images: [2] },
+})
+
+model.images[0].name // 'Header' (resolved from store)
+```
+
+A static version is also available:
+
+```javascript
+const model = Store.build({ event: { name: 'New Event' } })
+```
+
 ### Schema Validation for Legacy Store
 
 The legacy store also supports schema validation and type inference, maintaining full backward compatibility:
@@ -575,3 +690,78 @@ const event = store.find('event', '1')
 ```
 
 **Note**: Validation happens eagerly during `sync()` when schemas are configured. This allows you to check `store.validationErrors` immediately after syncing.
+
+## Upgrading from 4.0
+
+### Unresolved relationships resolve to stubs
+
+References missing from `included` now resolve to a stub `{ id, [TYPE]: type }` instead of `null`. References with `id: null` are dropped (arrays filter them out; to-one becomes `null`).
+
+Tighten schemas that typed relationships as nullable, and detect "not sideloaded" by absence of attributes rather than `=== null`.
+
+## Upgrading from 3.x
+
+Version 4.x is a full TypeScript rewrite with several breaking changes.
+
+### Node.js version
+
+Node.js 20+ is now required (was 14+).
+
+### Metadata uses Symbols instead of plain properties
+
+In 3.x, resource type, links, and meta were stored as plain properties on models (`model.type`, `model.links`, `model.meta`). Relationship metadata used `model._links` and `model._meta`.
+
+In 4.x, these use Symbol keys to avoid collisions with your data. Use the helpers from `yayson/utils`:
+
+```javascript
+// 3.x
+model.type
+model.links
+model.meta
+relatedModel._links
+relatedModel._meta
+
+// 4.x
+import { getType, getLinks, getMeta, getRelationshipLinks, getRelationshipMeta } from 'yayson/utils'
+getType(model)
+getLinks(model)
+getMeta(model)
+getRelationshipLinks(relatedModel)
+getRelationshipMeta(relatedModel)
+```
+
+### `sync()` restores 3.x behavior
+
+`sync()` now matches 3.x behavior: single resources return a model directly, collections return an array. If you always want an array, use `syncAll()`.
+
+```javascript
+// Single resource — returns model directly
+const event = store.sync({ data: { type: 'events', id: '1', attributes: { name: 'Demo' } } })
+event.name // 'Demo'
+
+// Collection — returns array
+const events = store.sync({ data: [{ type: 'events', id: '1', attributes: { name: 'Demo' } }] })
+events.length // 1
+
+// Always returns array
+const events = store.syncAll(data)
+
+// retrieve/retrieveAll also available
+const event = store.retrieve('events', data)
+const events = store.retrieveAll('events', data)
+```
+
+### Document-level meta uses Symbols
+
+In 3.x, document-level metadata was stored as `result.meta`. In 4.x, it uses a Symbol key:
+
+```javascript
+// 3.x
+const result = store.sync(data)
+result.meta // { total: 100 }
+
+// 4.x
+import { META } from 'yayson/utils'
+const result = store.sync(data)
+result[META] // { total: 100 }
+```

package/build/legacy.cjs

@@ -1,8 +1,8 @@
-const require_symbols = require('./symbols-nFs99aEX.cjs');
-const require_yayson = require('./yayson-CUfrxK9d.cjs');
+const require_symbols = require('./symbols-B--FS78o.cjs');
+const require_yayson = require('./yayson-C4P8J4sn.cjs');
 
 //#region src/yayson/legacy-presenter.ts
-function hasId(value) {
+function hasId$1(value) {
 	return typeof value === "object" && value !== null && "id" in value;
 }
 function createLegacyPresenter(Presenter) {
@@ -27,8 +27,8 @@ function createLegacyPresenter(Presenter) {
 				if (data == null) {
 					id = attributes[key + "Id"];
 					if (id != null) attributes[key] = id;
-				} else if (Array.isArray(data)) attributes[key] = data.map((obj) => hasId(obj) ? obj.id : obj);
-				else if (hasId(data)) attributes[key] = data.id;
+				} else if (Array.isArray(data)) attributes[key] = data.map((obj) => hasId$1(obj) ? obj.id : obj);
+				else if (hasId$1(data)) attributes[key] = data.id;
 			}
 			const relationshipKeys = relationships ? Object.keys(relationships) : [];
 			return require_yayson.filterByFields(attributes, this.constructor.fields ? [...this.constructor.fields, ...relationshipKeys] : void 0);
@@ -39,9 +39,9 @@ function createLegacyPresenter(Presenter) {
 			const result = [];
 			if (!relationships) return result;
 			for (const key in relationships) {
-				const factory = relationships[key];
-				if (!factory) throw new Error(`Presenter for ${key} in ${this.constructor.type} is not defined`);
-				const presenter = new factory(scope);
+				const entry = relationships[key];
+				if (!entry) throw new Error(`Presenter for ${key} in ${this.constructor.type} is not defined`);
+				const presenter = new (typeof entry === "function" ? entry : entry.presenter)(scope);
 				const data = this.constructor.adapter.get(instance, key);
 				if (data != null) presenter.toJSON(data, { defaultPlural: true });
 				const type = scope[this.pluralType()] != null ? this.pluralType() : this.constructor.type;
@@ -72,7 +72,7 @@ function createLegacyPresenter(Presenter) {
 				}
 				if (this.scope[this.constructor.type] && !this.scope[this.pluralType()]) {
 					const existingValue = this.scope[this.constructor.type];
-					if (attrs && hasId(existingValue) && existingValue.id !== attrs.id) {
+					if (attrs && hasId$1(existingValue) && existingValue.id !== attrs.id) {
 						this.scope[this.pluralType()] = [this.scope[this.constructor.type]];
 						delete this.scope[this.constructor.type];
 						const pluralArray = this.scope[this.pluralType()];
@@ -80,7 +80,7 @@ function createLegacyPresenter(Presenter) {
 					} else added = false;
 				} else if (this.scope[this.pluralType()]) {
 					const existing = this.scope[this.pluralType()];
-					if (Array.isArray(existing)) if (attrs && !existing.some((i) => hasId(i) && i.id === attrs.id)) existing.push(attrs);
+					if (Array.isArray(existing)) if (attrs && !existing.some((i) => hasId$1(i) && i.id === attrs.id)) existing.push(attrs);
 					else added = false;
 				} else if (opts.defaultPlural) this.scope[this.pluralType()] = attrs ? [attrs] : [];
 				else this.scope[this.constructor.type] = attrs;
@@ -88,6 +88,11 @@ function createLegacyPresenter(Presenter) {
 			}
 			return this.scope;
 		}
+		payload(instance) {
+			if (Array.isArray(instance)) throw new Error("payload() expects a single resource, not an array");
+			if (instance == null) throw new Error("payload() requires a resource, got null");
+			return { [this.constructor.type]: this.attributes(instance) };
+		}
 		render(instanceOrCollection) {
 			return this.toJSON(instanceOrCollection);
 		}
@@ -97,12 +102,18 @@ function createLegacyPresenter(Presenter) {
 		static render(instanceOrCollection, _options) {
 			return new this().render(instanceOrCollection);
 		}
+		static payload(instance) {
+			return new this().payload(instance);
+		}
 	};
 }
 
 //#endregion
 //#region src/yayson/legacy-store.ts
-var LegacyStore = class {
+function hasId(model) {
+	return model.id != null;
+}
+var LegacyStore = class LegacyStore {
 	types;
 	records;
 	relations;
@@ -125,33 +136,56 @@ var LegacyStore = class {
 		this.validationErrors = [];
 		this.models = {};
 	}
-	toModel(rec, type, models) {
-		const idStr = String(rec.data.id);
-		if (!models[type]) models[type] = {};
-		if (models[type][idStr]) return models[type][idStr];
-		const model = {
-			...rec.data,
-			id: rec.data.id
-		};
-		model[require_symbols.TYPE] = type;
-		if (rec.data.meta != null) model[require_symbols.META] = rec.data.meta;
-		if (rec.data.links != null) model[require_symbols.LINKS] = rec.data.links;
-		models[type][idStr] = model;
+	#createStub(type, id) {
+		const stub = { id };
+		stub[require_symbols.TYPE] = type;
+		return stub;
+	}
+	#resolveRelationships(model, type, resolver) {
 		const relations = this.relations[type];
-		if (relations) for (const attribute in relations) {
+		if (!relations) return;
+		for (const attribute in relations) {
 			const relationType = relations[attribute];
 			const value = model[attribute];
-			model[attribute] = Array.isArray(value) ? value.map((id) => this.find(relationType, String(id), models)) : this.find(relationType, String(value), models);
+			if (Array.isArray(value)) model[attribute] = value.filter((id) => id != null).map((id) => resolver(relationType, String(id)));
+			else if (value != null) model[attribute] = resolver(relationType, String(value));
+			else model[attribute] = null;
+		}
+	}
+	#createModel(rec, type, options) {
+		const models = options?.models;
+		const model = { ...rec.data };
+		if (rec.data.id != null) model.id = rec.data.id;
+		model[require_symbols.TYPE] = type;
+		if (rec.data.meta != null) model[require_symbols.META] = rec.data.meta;
+		if (rec.data.links != null) model[require_symbols.LINKS] = rec.data.links;
+		if (models && hasId(model)) {
+			const idStr = String(model.id);
+			if (!models[type]) models[type] = {};
+			models[type][idStr] = model;
 		}
+		const resolver = (relationType, id) => {
+			return this.#findModel(relationType, id, models ?? {}) ?? this.#createStub(relationType, id);
+		};
+		this.#resolveRelationships(model, type, resolver);
+		return model;
+	}
+	toModel(rec, type, models) {
+		const idStr = String(rec.data.id);
+		if (!models[type]) models[type] = {};
+		if (models[type][idStr]) return models[type][idStr];
+		const result = this.#createModel(rec, type, { models });
+		if (!hasId(result)) throw new Error(`Expected model of type ${type} to have an id`);
+		const model = result;
 		if (this.schemas && this.schemas[type]) {
 			const schema = this.schemas[type];
-			const result = require_yayson.validate(schema, model, this.strict);
-			if (!result.valid) this.validationErrors.push({
+			const result$1 = require_yayson.validate(schema, model, this.strict);
+			if (!result$1.valid) this.validationErrors.push({
 				type,
 				id: idStr,
-				error: result.error
+				error: result$1.error
 			});
-			const validatedModel = result.data;
+			const validatedModel = result$1.data;
 			validatedModel[require_symbols.TYPE] = model[require_symbols.TYPE];
 			validatedModel[require_symbols.LINKS] = model[require_symbols.LINKS];
 			validatedModel[require_symbols.META] = model[require_symbols.META];
@@ -177,6 +211,30 @@ var LegacyStore = class {
 	findRecords(type) {
 		return this.records.filter((r) => r.type === type);
 	}
+	#findModel(type, id, models) {
+		const rec = this.findRecord(type, id);
+		if (rec == null) return null;
+		return models[type]?.[id] ?? this.toModel(rec, type, models);
+	}
+	static build(data) {
+		return new LegacyStore().build(data);
+	}
+	build(data) {
+		if (data.links) this.setupRelations(data.links);
+		let name;
+		for (const key in data) if (key !== "meta" && key !== "links") {
+			name = key;
+			break;
+		}
+		if (name == null) throw new Error("build() expects a single resource, not an array");
+		const value = data[name];
+		if (value == null || Array.isArray(value)) throw new Error("build() expects a single resource, not an array");
+		const type = this.types[name] || name;
+		return this.#createModel({
+			type,
+			data: value
+		}, type);
+	}
 	/** @deprecated Use retrieve() instead. */
 	retrive(type, data) {
 		return this.retrieve(type, data);
@@ -190,12 +248,7 @@ var LegacyStore = class {
 		return model;
 	}
 	find(type, id, models) {
-		const modelsObj = models ?? this.models;
-		const idStr = String(id);
-		const rec = this.findRecord(type, idStr);
-		if (rec == null) return null;
-		if (!modelsObj[type]) modelsObj[type] = {};
-		return modelsObj[type][idStr] || this.toModel(rec, type, modelsObj);
+		return this.#findModel(type, String(id), models ?? this.models);
 	}
 	findAll(type, models) {
 		const modelsObj = models ?? this.models;