@warp-drive-mirror/json-api 5.10.0-alpha.0 → 5.10.0-alpha.10

package/dist/index.js

@@ -1,5 +1,5 @@
 import { graphFor, isBelongsTo, peekGraph } from "@warp-drive-mirror/core/graph/-private";
-import { assertPrivateCapabilities, isRequestKey, isResourceKey, logGroup } from "@warp-drive-mirror/core/store/-private";
+import { assertPrivateCapabilities, fieldValueIdentity, isRequestKey, isResourceKey, logGroup } from "@warp-drive-mirror/core/store/-private";
 import Fuse from "fuse.js";
 import jsonToAst from "json-to-ast";
 import { getGlobalConfig, macroCondition } from "@embroider/macros";
@@ -938,14 +938,101 @@ const EMPTY_ITERATOR = { iterator() {
 		};
 	} };
 } };
+/** One attributes hash on a {@link CachedResource}: a **layer** a projection is read through. */
+/**
+* The cache's entry for a single resource: its id, its attribute values split
+* across four **layers**, and the flags tracking where it sits in the
+* create/update/delete lifecycle.
+*
+* A **projection** answers "what is this field's value" by reading a stack of
+* layers top-down; the first layer holding the field wins. The two projections,
+* with their resolution orders:
+*
+* - **remote state**, what the _immutable_ record reads:
+*   {@link RESOLUTION_ORDER_REMOTE_STATE}
+* - **local state**, what an _editable_ copy reads:
+*   {@link RESOLUTION_ORDER_LOCAL_STATE}
+*
+* Local state is remote state with the uncommitted mutations laid over it. The
+* guides call those mutations "the diff"; here they are simply the top layers of
+* local state, {@link CachedResource.localAttrs | localAttrs} and
+* {@link CachedResource.inflightAttrs | inflightAttrs}.
+*
+* A field is **dirty** while `localAttrs` or `inflightAttrs` holds it. A save
+* **commits** the mutation: `didCommit` merges the in-flight values into
+* `remoteAttrs` and removes them from `inflightAttrs`. A push carrying the same
+* value as a pending edit in `localAttrs` has the same effect on that edit: the
+* server already holds it, so it is removed from `localAttrs`. "Same value" is
+* decided by the field's schema: a schema-object with an identity hash compares
+* by that hash, everything else by reference.
+*
+* Thus, a dirty field reads as mutated for local readers only, and goes on doing
+* so while its save is in flight.
+*
+* @internal
+*/
+/** A layer name on a {@link CachedResource}. */
+/**
+* A layer that exists only for the duration of a merge: the attributes arriving from the
+* server in a save response or a push. {@link partitionChangedKeys} reads it as if it were
+* already on the resource; {@link mergeIntoRemote} then folds the same attributes in, handed
+* to it directly. Never part of a reader's resolution order.
+*/
+/** Anything a projection can be read through: a {@link CachedResource}, or the layers a merge reads, built around one. */
+/** What the immutable record reads. */
+const RESOLUTION_ORDER_REMOTE_STATE = ["remoteAttrs", "defaultAttrs"];
+/**
+* What a new local edit replaces: the in-flight value if a save is carrying one, else the
+* persisted value. Put another way, what the record will read once the in-flight save lands,
+* assuming the server agrees. This is local state beneath `localAttrs`, less `defaultAttrs`: an
+* edit equal to a schema default is still an edit, since nothing persisted holds that value.
+*
+* Saving does not use this baseline. {@link JSONAPICache.changedAttrs | changedAttrs} still lists
+* in-flight values as unsaved, so a second save re-sends them rather than assuming the first one
+* will succeed.
+*/
+const RESOLUTION_ORDER_EDIT_BASELINE = ["inflightAttrs", "remoteAttrs"];
+/** What an editable copy reads. */
+const RESOLUTION_ORDER_LOCAL_STATE = [
+	"localAttrs",
+	...RESOLUTION_ORDER_EDIT_BASELINE,
+	"defaultAttrs"
+];
+const RESOLUTION_ORDER_REMOTE_AFTER_COMMIT = [
+	"incomingAttrs",
+	"inflightAttrs",
+	...RESOLUTION_ORDER_REMOTE_STATE
+];
+const RESOLUTION_ORDER_LOCAL_AFTER_COMMIT = ["localAttrs", ...RESOLUTION_ORDER_REMOTE_AFTER_COMMIT];
+const RESOLUTION_ORDER_REMOTE_AFTER_UPSERT = ["incomingAttrs", ...RESOLUTION_ORDER_REMOTE_STATE];
+const RESOLUTION_ORDER_LOCAL_AFTER_UPSERT = [
+	"localAttrs",
+	"inflightAttrs",
+	...RESOLUTION_ORDER_REMOTE_AFTER_UPSERT
+];
+/** The layers an after-merge order folds into `remoteAttrs`, lowest precedence first. */
+function layersFoldedIntoRemote(order) {
+	return order.slice(0, order.indexOf("remoteAttrs")).reverse();
+}
+const MERGE_RESOLUTION = {
+	commit: {
+		remoteAfter: RESOLUTION_ORDER_REMOTE_AFTER_COMMIT,
+		localAfter: RESOLUTION_ORDER_LOCAL_AFTER_COMMIT,
+		folded: layersFoldedIntoRemote(RESOLUTION_ORDER_REMOTE_AFTER_COMMIT)
+	},
+	upsert: {
+		remoteAfter: RESOLUTION_ORDER_REMOTE_AFTER_UPSERT,
+		localAfter: RESOLUTION_ORDER_LOCAL_AFTER_UPSERT,
+		folded: layersFoldedIntoRemote(RESOLUTION_ORDER_REMOTE_AFTER_UPSERT)
+	}
+};
 function makeCache() {
 	return {
 		id: null,
-		remoteAttrs: null,
 		localAttrs: null,
-		defaultAttrs: null,
 		inflightAttrs: null,
-		changes: null,
+		remoteAttrs: null,
+		defaultAttrs: null,
 		errors: null,
 		isNew: false,
 		isDeleted: false,
@@ -996,9 +1083,9 @@ var JSONAPICache = class {
 	/**
 	* Cache the response to a request
 	*
-	* Implements `Cache.put`.
+	* Implements {@link Cache.put | Cache.put}.
 	*
-	* Expects a StructuredDocument whose `content` member is a JsonApiDocument.
+	* Expects a {@link StructuredDocument} whose `content` member is a JsonApiDocument.
 	*
 	* ```js
 	* cache.put({
@@ -1133,6 +1220,16 @@ var JSONAPICache = class {
 	* Update the "remote" or "canonical" (persisted) state of the Cache
 	* by merging new information into the existing state.
 	*
+	* @example
+	* ```ts
+	* cache.patch({
+	*   op: 'update',
+	*   record: identifier,
+	*   field: 'name',
+	*   value: 'Chris',
+	* });
+	* ```
+	*
 	* @category Cache Management
 	* @public
 	* @param op the operation or list of operations to perform
@@ -1154,6 +1251,16 @@ var JSONAPICache = class {
 	/**
 	* Update the "local" or "current" (unpersisted) state of the Cache
 	*
+	* @example
+	* ```ts
+	* cache.mutate({
+	*   op: 'replaceRelatedRecord',
+	*   record: identifier,
+	*   field: 'author',
+	*   value: authorIdentifier,
+	* });
+	* ```
+	*
 	* @category Cache Management
 	* @public
 	*/
@@ -1194,8 +1301,8 @@ var JSONAPICache = class {
 	* not require retainining connections to the Store
 	* and Cache to present data on a per-field basis.
 	*
-	* This generally takes the place of `getAttr` as
-	* an API and may even take the place of `getRelationship`
+	* This generally takes the place of {@link JSONAPICache.getAttr | getAttr} as
+	* an API and may even take the place of {@link JSONAPICache.getRelationship | getRelationship}
 	* depending on implementation specifics, though this
 	* latter usage is less recommended due to the advantages
 	* of the Graph handling necessary entanglements and
@@ -1210,6 +1317,12 @@ var JSONAPICache = class {
 	* the various internal WarpDrive bookkeeping fields.
 	* :::
 	*
+	* @example
+	* ```ts
+	* const resource = cache.peek(identifier);
+	* const document = cache.peek(requestKey);
+	* ```
+	*
 	* @category Cache Management
 	* @public
 	*/
@@ -1249,6 +1362,12 @@ var JSONAPICache = class {
 	/**
 	* Peek the remote resource data from the Cache.
 	*
+	* @example
+	* ```ts
+	* const resource = cache.peekRemoteState(identifier);
+	* const document = cache.peekRemoteState(requestKey);
+	* ```
+	*
 	* @category Cache Management
 	* @public
 	*/
@@ -1289,9 +1408,14 @@ var JSONAPICache = class {
 	* Peek the Cache for the existing request data associated with
 	* a cacheable request.
 	*
-	* This is effectively the reverse of `put` for a request in
+	* This is effectively the reverse of {@link JSONAPICache.put | put} for a request in
 	* that it will return the the request, response, and content
-	* whereas `peek` will return just the `content`.
+	* whereas {@link JSONAPICache.peek | peek} will return just the `content`.
+	*
+	* @example
+	* ```ts
+	* const doc = cache.peekRequest(requestKey);
+	* ```
 	*
 	* @category Cache Management
 	* @public
@@ -1302,9 +1426,20 @@ var JSONAPICache = class {
 	/**
 	* Push resource data from a remote source into the cache for this identifier
 	*
+	* @example
+	* ```ts
+	* cache.upsert(identifier, {
+	*   type: 'user',
+	*   id: '1',
+	*   attributes: { name: 'Chris' },
+	* });
+	* ```
+	*
 	* @category Cache Management
 	* @public
-	* @return if `calculateChanges` is true then calculated key changes should be returned
+	* @return when `calculateChanges` is true, the names of the attributes whose persisted value
+	*   this push changed (the same keys the `'remote'` channel is notified with), or `undefined`
+	*   when none did. Otherwise `void`.
 	*/
 	upsert(identifier, data, calculateChanges) {
 		assertPrivateCapabilities(this._capabilities);
@@ -1350,7 +1485,7 @@ var JSONAPICache = class {
 	*
 	* Each individual resource or document that has
 	* been mutated should be described as an individual
-	* `Change` entry in the returned array.
+	* {@link Change} entry in the returned array.
 	*
 	* A `Change` is described by an object containing up to
 	* three properties: (1) the `identifier` of the entity that
@@ -1415,6 +1550,11 @@ var JSONAPICache = class {
 	* It returns properties from options that should be set on the record during the create
 	* process. This return value behavior is deprecated.
 	*
+	* @example
+	* ```ts
+	* cache.clientDidCreate(identifier, { name: 'Chris' });
+	* ```
+	*
 	* @category Resource Lifecycle
 	* @public
 	*/
@@ -1479,6 +1619,11 @@ var JSONAPICache = class {
 	* [LIFECYCLE] Signals to the cache that a resource
 	* will be part of a save transaction.
 	*
+	* @example
+	* ```ts
+	* cache.willCommit(identifier, context);
+	* ```
+	*
 	* @category Resource Lifecycle
 	* @public
 	*/
@@ -1490,6 +1635,11 @@ var JSONAPICache = class {
 	* [LIFECYCLE] Signals to the cache that a resource
 	* was successfully updated as part of a save transaction.
 	*
+	* @example
+	* ```ts
+	* cache.didCommit(identifier, result);
+	* ```
+	*
 	* @category Resource Lifecycle
 	* @public
 	*/
@@ -1529,6 +1679,11 @@ var JSONAPICache = class {
 	* [LIFECYCLE] Signals to the cache that a resource
 	* was update via a save transaction failed.
 	*
+	* @example
+	* ```ts
+	* cache.commitWasRejected(identifier, errors);
+	* ```
+	*
 	* @category Resource Lifecycle
 	* @public
 	*/
@@ -1545,6 +1700,11 @@ var JSONAPICache = class {
 	*
 	* This method is a candidate to become a mutation
 	*
+	* @example
+	* ```ts
+	* cache.unloadRecord(identifier);
+	* ```
+	*
 	* @category Resource Lifecycle
 	* @public
 	*/
@@ -1585,6 +1745,12 @@ var JSONAPICache = class {
 	* Retrieve the data for an attribute from the cache
 	* with local mutations applied.
 	*
+	* @example
+	* ```ts
+	* const name = cache.getAttr(identifier, 'name');
+	* const zip = cache.getAttr(identifier, ['address', 'zip']);
+	* ```
+	*
 	* @category Resource Data
 	* @public
 	*/
@@ -1598,37 +1764,28 @@ var JSONAPICache = class {
 				if (!test) throw new Error(`Cannot retrieve attributes for identifier ${String(identifier)} as it is not present in the cache`);
 			})(cached);
 			if (!cached) return;
-			if (cached.localAttrs && attribute in cached.localAttrs) return cached.localAttrs[attribute];
-			else if (cached.inflightAttrs && attribute in cached.inflightAttrs) return cached.inflightAttrs[attribute];
-			else if (cached.remoteAttrs && attribute in cached.remoteAttrs) return cached.remoteAttrs[attribute];
-			else if (cached.defaultAttrs && attribute in cached.defaultAttrs) return cached.defaultAttrs[attribute];
-			else {
-				const attrSchema = getCacheFields(this, identifier).get(attribute);
-				assertPrivateCapabilities(this._capabilities);
-				const defaultValue = getDefaultValue(attrSchema, identifier, this._capabilities._store);
-				if (schemaHasLegacyDefaultValueFn(attrSchema)) {
-					cached.defaultAttrs = cached.defaultAttrs || Object.create(null);
-					cached.defaultAttrs[attribute] = defaultValue;
-				}
-				return defaultValue;
+			const layer = layerHolding(attribute, cached, RESOLUTION_ORDER_LOCAL_STATE);
+			if (layer) return layer[attribute];
+			const attrSchema = getCacheFields(this, identifier).get(attribute);
+			assertPrivateCapabilities(this._capabilities);
+			const defaultValue = getDefaultValue(attrSchema, identifier, this._capabilities._store);
+			if (schemaHasLegacyDefaultValueFn(attrSchema)) {
+				cached.defaultAttrs = cached.defaultAttrs || Object.create(null);
+				cached.defaultAttrs[attribute] = defaultValue;
 			}
+			return defaultValue;
 		}
-		const path = attr;
 		const cached = this.__peek(identifier, true);
-		const basePath = path[0];
-		let current = cached.localAttrs && basePath in cached.localAttrs ? cached.localAttrs[basePath] : void 0;
-		if (current === void 0) current = cached.inflightAttrs && basePath in cached.inflightAttrs ? cached.inflightAttrs[basePath] : void 0;
-		if (current === void 0) current = cached.remoteAttrs && basePath in cached.remoteAttrs ? cached.remoteAttrs[basePath] : void 0;
-		if (current === void 0) return;
-		for (let i = 1; i < path.length; i++) {
-			current = current[path[i]];
-			if (current === void 0) return;
-		}
-		return current;
+		return resolveAttr(attr, cached, RESOLUTION_ORDER_LOCAL_STATE);
 	}
 	/**
 	* Retrieve the remote data for an attribute from the cache
 	*
+	* @example
+	* ```ts
+	* const name = cache.getRemoteAttr(identifier, 'name');
+	* ```
+	*
 	* @category Resource Data
 	* @public
 	*/
@@ -1642,35 +1799,30 @@ var JSONAPICache = class {
 				if (!test) throw new Error(`Cannot retrieve remote attributes for identifier ${String(identifier)} as it is not present in the cache`);
 			})(cached);
 			if (!cached) return;
-			if (cached.remoteAttrs && attribute in cached.remoteAttrs) return cached.remoteAttrs[attribute];
-			else if (cached.defaultAttrs && attribute in cached.defaultAttrs) return cached.defaultAttrs[attribute];
-			else {
-				const attrSchema = getCacheFields(this, identifier).get(attribute);
-				assertPrivateCapabilities(this._capabilities);
-				const defaultValue = getDefaultValue(attrSchema, identifier, this._capabilities._store);
-				if (schemaHasLegacyDefaultValueFn(attrSchema)) {
-					cached.defaultAttrs = cached.defaultAttrs || Object.create(null);
-					cached.defaultAttrs[attribute] = defaultValue;
-				}
-				return defaultValue;
+			const layer = layerHolding(attribute, cached, RESOLUTION_ORDER_REMOTE_STATE);
+			if (layer) return layer[attribute];
+			const attrSchema = getCacheFields(this, identifier).get(attribute);
+			assertPrivateCapabilities(this._capabilities);
+			const defaultValue = getDefaultValue(attrSchema, identifier, this._capabilities._store);
+			if (schemaHasLegacyDefaultValueFn(attrSchema)) {
+				cached.defaultAttrs = cached.defaultAttrs || Object.create(null);
+				cached.defaultAttrs[attribute] = defaultValue;
 			}
+			return defaultValue;
 		}
-		const path = attr;
 		const cached = this.__peek(identifier, true);
-		const basePath = path[0];
-		let current = cached.remoteAttrs && basePath in cached.remoteAttrs ? cached.remoteAttrs[basePath] : void 0;
-		if (current === void 0) return;
-		for (let i = 1; i < path.length; i++) {
-			current = current[path[i]];
-			if (current === void 0) return;
-		}
-		return current;
+		return resolveAttr(attr, cached, RESOLUTION_ORDER_REMOTE_STATE);
 	}
 	/**
 	* Mutate the data for an attribute in the cache
 	*
 	* This method is a candidate to become a mutation
 	*
+	* @example
+	* ```ts
+	* cache.setAttr(identifier, 'name', 'Chris');
+	* ```
+	*
 	* @category Resource Data
 	* @public
 	*/
@@ -1678,21 +1830,19 @@ var JSONAPICache = class {
 		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
 			if (!test) throw new Error("setAttr must receive at least one attribute path");
 		})(attr.length > 0);
+		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+			if (!test) throw new Error(`Cannot set '${Array.isArray(attr) ? attr.join(".") : attr}' on '${identifier.type}' to undefined: undefined is not a JSON value. Use null instead. If you feel like this behavior is incorrect, open an issue and ping @runspired.`);
+		})(value !== void 0);
+		if (value === void 0) value = null;
 		const isSimplePath = !Array.isArray(attr) || attr.length === 1;
 		if (Array.isArray(attr) && attr.length === 1) attr = attr[0];
 		if (isSimplePath) {
 			const cached = this.__peek(identifier, false);
 			const currentAttr = attr;
-			const existing = cached.inflightAttrs && currentAttr in cached.inflightAttrs ? cached.inflightAttrs[currentAttr] : cached.remoteAttrs && currentAttr in cached.remoteAttrs ? cached.remoteAttrs[currentAttr] : void 0;
-			if (existing !== value) {
+			if (resolveAttr(currentAttr, cached, RESOLUTION_ORDER_EDIT_BASELINE) !== value) {
 				cached.localAttrs = cached.localAttrs || Object.create(null);
 				cached.localAttrs[currentAttr] = value;
-				cached.changes = cached.changes || Object.create(null);
-				cached.changes[currentAttr] = [existing, value];
-			} else if (cached.localAttrs) {
-				delete cached.localAttrs[currentAttr];
-				delete cached.changes[currentAttr];
-			}
+			} else if (cached.localAttrs) delete cached.localAttrs[currentAttr];
 			if (cached.defaultAttrs && currentAttr in cached.defaultAttrs) delete cached.defaultAttrs[currentAttr];
 			this._capabilities.notifyChange(identifier, "attributes", currentAttr, "local");
 			return;
@@ -1700,32 +1850,50 @@ var JSONAPICache = class {
 		const path = attr;
 		const cached = this.__peek(identifier, false);
 		const basePath = path[0];
-		const existing = cached.inflightAttrs && basePath in cached.inflightAttrs ? cached.inflightAttrs[basePath] : cached.remoteAttrs && basePath in cached.remoteAttrs ? cached.remoteAttrs[basePath] : void 0;
-		let existingAttr;
-		if (existing) {
-			existingAttr = existing[path[1]];
-			for (let i = 2; i < path.length; i++) existingAttr = existingAttr[path[i]];
+		const baseline = resolveAttr(basePath, cached, RESOLUTION_ORDER_EDIT_BASELINE);
+		const isRevert = valueAtPath(baseline, path) === value;
+		const hasLocalClone = !!cached.localAttrs && basePath in cached.localAttrs;
+		if (isRevert && !hasLocalClone) return;
+		cached.localAttrs = cached.localAttrs || Object.create(null);
+		if (!hasLocalClone) {
+			const seed = baseline ?? (cached.defaultAttrs ? cached.defaultAttrs[basePath] : void 0);
+			macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+				if (!test) throw new Error(`Cannot set '${path.join(".")}' on '${identifier.type}': '${basePath}' holds no object to write into`);
+			})(!!seed && typeof seed === "object");
+			cached.localAttrs[basePath] = structuredClone(seed);
 		}
-		if (existingAttr !== value) {
-			cached.localAttrs = cached.localAttrs || Object.create(null);
-			cached.localAttrs[basePath] = cached.localAttrs[basePath] || structuredClone(existing);
-			cached.changes = cached.changes || Object.create(null);
-			let currentLocal = cached.localAttrs[basePath];
-			let nextLink = 1;
-			while (nextLink < path.length - 1) currentLocal = currentLocal[path[nextLink++]];
-			currentLocal[path[nextLink]] = value;
-			cached.changes[basePath] = [existing, cached.localAttrs[basePath]];
-		} else if (cached.localAttrs) try {
-			if (!existing) return;
-			if (JSON.stringify(existing) !== JSON.stringify(cached.localAttrs[basePath])) {
-				delete cached.localAttrs[basePath];
-				delete cached.changes[basePath];
-			}
-		} catch {}
+		let currentLocal = cached.localAttrs[basePath];
+		let nextLink = 1;
+		while (nextLink < path.length - 1) currentLocal = currentLocal[path[nextLink++]];
+		if (currentLocal[path[nextLink]] === value) return;
+		currentLocal[path[nextLink]] = value;
+		if (isRevert) {
+			const field = getCacheFields(this, identifier).get(basePath);
+			if (localCloneMatchesBaseline(this._capabilities.schema, field, baseline, cached.localAttrs[basePath])) delete cached.localAttrs[basePath];
+		}
+		if (cached.defaultAttrs && basePath in cached.defaultAttrs) delete cached.defaultAttrs[basePath];
 		this._capabilities.notifyChange(identifier, "attributes", basePath, "local");
 	}
 	/**
-	* Query the cache for the changed attributes of a resource.
+	* Query the cache for the changed attributes of a resource: every unsaved
+	* mutation, as a `[before, after]` pair per field.
+	*
+	* `before` is the value the mutation replaces, which is not always the
+	* persisted one. A mutation a save is carrying replaces remote state; an edit
+	* made while that save is in flight replaces the in-flight value. So this is
+	* what saving from here would change, which is what `serializePatch` and the
+	* legacy `Snapshot` consume, rather than a diff against persisted state.
+	*
+	* Derived from the layers on each call, so it is always consistent with
+	* {@link JSONAPICache.getAttr | getAttr} and
+	* {@link JSONAPICache.rollbackAttrs | rollbackAttrs}. Dirtiness does not go
+	* through here; see {@link JSONAPICache.hasChangedAttrs | hasChangedAttrs}.
+	*
+	* @example
+	* ```ts
+	* const changes = cache.changedAttrs(identifier);
+	* // { name: ['Igor', 'Chris'] }
+	* ```
 	*
 	* @category Resource Data
 	* @public
@@ -1736,12 +1904,29 @@ var JSONAPICache = class {
 		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
 			if (!test) throw new Error(`Cannot retrieve changed attributes for identifier ${String(identifier)} as it is not present in the cache`);
 		})(cached);
-		if (!cached) return Object.create(null);
-		return cached.changes || Object.create(null);
+		const changes = Object.create(null);
+		if (!cached) return changes;
+		const { localAttrs, inflightAttrs, remoteAttrs } = cached;
+		if (inflightAttrs) {
+			const keys = Object.keys(inflightAttrs);
+			for (let i = 0; i < keys.length; i++) changes[keys[i]] = [remoteAttrs ? remoteAttrs[keys[i]] : void 0, inflightAttrs[keys[i]]];
+		}
+		if (localAttrs) {
+			const keys = Object.keys(localAttrs);
+			for (let i = 0; i < keys.length; i++) changes[keys[i]] = [resolveAttr(keys[i], cached, RESOLUTION_ORDER_EDIT_BASELINE), localAttrs[keys[i]]];
+		}
+		return changes;
 	}
 	/**
 	* Query the cache for whether any mutated attributes exist
 	*
+	* @example
+	* ```ts
+	* if (cache.hasChangedAttrs(identifier)) {
+	*   // ...
+	* }
+	* ```
+	*
 	* @category Resource Data
 	* @public
 	*/
@@ -1758,6 +1943,11 @@ var JSONAPICache = class {
 	*
 	* This method is a candidate to become a mutation
 	*
+	* @example
+	* ```ts
+	* const restoredKeys = cache.rollbackAttrs(identifier);
+	* ```
+	*
 	* @category Resource Data
 	* @public
 	* @return the names of fields that were restored
@@ -1769,7 +1959,6 @@ var JSONAPICache = class {
 		if (cached.localAttrs !== null) {
 			dirtyKeys = Object.keys(cached.localAttrs);
 			cached.localAttrs = null;
-			cached.changes = null;
 		}
 		if (cached.isNew) {
 			cached.isDeletionCommitted = true;
@@ -1789,7 +1978,7 @@ var JSONAPICache = class {
 	/**
 	* Query the cache for the changes to relationships of a resource.
 	*
-	* Returns a map of relationship names to RelationshipDiff objects.
+	* Returns a map of relationship names to {@link RelationshipDiff} objects.
 	*
 	* ```ts
 	* type RelationshipDiff =
@@ -1808,6 +1997,12 @@ var JSONAPICache = class {
 	};
 	```
 	*
+	* @example
+	* ```ts
+	* const diffs = cache.changedRelationships(identifier);
+	* const comments = diffs.get('comments');
+	* ```
+	*
 	* @category Resource Data
 	* @public
 	*/
@@ -1817,6 +2012,13 @@ var JSONAPICache = class {
 	/**
 	* Query the cache for whether any mutated relationships exist
 	*
+	* @example
+	* ```ts
+	* if (cache.hasChangedRelationships(identifier)) {
+	*   // ...
+	* }
+	* ```
+	*
 	* @category Resource Data
 	* @public
 	*/
@@ -1830,6 +2032,11 @@ var JSONAPICache = class {
 	*
 	* This method is a candidate to become a mutation
 	*
+	* @example
+	* ```ts
+	* const restoredFields = cache.rollbackRelationships(identifier);
+	* ```
+	*
 	* @category Resource Data
 	* @public
 	* @return the names of relationships that were restored
@@ -1845,6 +2052,11 @@ var JSONAPICache = class {
 	/**
 	* Query the cache for the current state of a relationship property
 	*
+	* @example
+	* ```ts
+	* const relationship = cache.getRelationship(identifier, 'comments');
+	* ```
+	*
 	* @category Resource Data
 	* @public
 	* @return resource relationship object
@@ -1855,6 +2067,11 @@ var JSONAPICache = class {
 	/**
 	* Query the cache for the remote state of a relationship property
 	*
+	* @example
+	* ```ts
+	* const relationship = cache.getRemoteRelationship(identifier, 'comments');
+	* ```
+	*
 	* @category Resource Data
 	* @public
 	* @return resource relationship object
@@ -1868,6 +2085,11 @@ var JSONAPICache = class {
 	*
 	* This method is a candidate to become a mutation
 	*
+	* @example
+	* ```ts
+	* cache.setIsDeleted(identifier, true);
+	* ```
+	*
 	* @category Resource State
 	* @public
 	*/
@@ -1879,6 +2101,11 @@ var JSONAPICache = class {
 	/**
 	* Query the cache for any validation errors applicable to the given resource.
 	*
+	* @example
+	* ```ts
+	* const errors = cache.getErrors(identifier);
+	* ```
+	*
 	* @category Resource State
 	* @public
 	*/
@@ -1888,6 +2115,13 @@ var JSONAPICache = class {
 	/**
 	* Query the cache for whether a given resource has any available data
 	*
+	* @example
+	* ```ts
+	* if (cache.isEmpty(identifier)) {
+	*   // ...
+	* }
+	* ```
+	*
 	* @category Resource State
 	* @public
 	*/
@@ -1899,6 +2133,13 @@ var JSONAPICache = class {
 	* Query the cache for whether a given resource was created locally and not
 	* yet persisted.
 	*
+	* @example
+	* ```ts
+	* if (cache.isNew(identifier)) {
+	*   // ...
+	* }
+	* ```
+	*
 	* @category Resource State
 	* @public
 	*/
@@ -1909,6 +2150,13 @@ var JSONAPICache = class {
 	* Query the cache for whether a given resource is marked as deleted (but not
 	* necessarily persisted yet).
 	*
+	* @example
+	* ```ts
+	* if (cache.isDeleted(identifier)) {
+	*   // ...
+	* }
+	* ```
+	*
 	* @category Resource State
 	* @public
 	*/
@@ -1919,6 +2167,13 @@ var JSONAPICache = class {
 	* Query the cache for whether a given resource has been deleted and that deletion
 	* has also been persisted.
 	*
+	* @example
+	* ```ts
+	* if (cache.isDeletionCommitted(identifier)) {
+	*   // ...
+	* }
+	* ```
+	*
 	* @category Resource State
 	* @public
 	*/
@@ -2136,20 +2391,189 @@ function getDefaultValue(schema, identifier, store) {
 		if (transform?.defaultValue) return transform.defaultValue(options || null, identifier);
 	}
 }
-function calculateChangedKeys(cached, updates, fields) {
-	const changedKeys = /* @__PURE__ */ new Set();
-	const keys = Object.keys(updates);
-	const length = keys.length;
-	const localAttrs = cached.localAttrs;
-	const original = Object.assign(Object.create(null), cached.remoteAttrs, cached.inflightAttrs);
-	for (let i = 0; i < length; i++) {
-		const key = keys[i];
-		if (!fields.has(key)) continue;
-		const value = updates[key];
-		if (localAttrs && localAttrs[key] !== void 0) continue;
-		if (original[key] !== value) changedKeys.add(key);
+/**
+* The first layer, in the given resolution order, that holds `key`. Presence is `in`, so a value
+* explicitly set to `undefined` counts as present.
+*/
+function layerHolding(key, layers, order) {
+	for (let i = 0; i < order.length; i++) {
+		const layer = layers[order[i]];
+		if (layer && key in layer) return layer;
 	}
-	return changedKeys;
+	return null;
+}
+/**
+* What the projection with the given resolution order reads for `attr`. A path resolves its first
+* segment through the layers and follows the rest into the value, stopping with `undefined` at the
+* first missing link.
+*/
+function resolveAttr(attr, layers, order) {
+	const key = typeof attr === "string" ? attr : attr[0];
+	const layer = layerHolding(key, layers, order);
+	if (!layer) return void 0;
+	return typeof attr === "string" ? layer[key] : valueAtPath(layer[key], attr);
+}
+/** Follow `path` (from its second segment) into `base`, stopping with `undefined` at the first missing link or `null`. */
+function valueAtPath(base, path) {
+	let current = base;
+	for (let i = 1; i < path.length; i++) {
+		if (current === void 0 || current === null) return void 0;
+		current = current[path[i]];
+	}
+	return current;
+}
+/**
+* Whether two values of `field` count as the same value for change detection.
+*
+* A `schema-object`, and each element of a `schema-array`, compares by the identity hash its
+* `ObjectSchema` declares (`identity: { kind: '@hash', ... }`), so the schema decides what "same"
+* means for it. With no hash declared, and for every other field kind, only the same reference
+* counts. That knowingly over-notifies for equal-content objects: content equality is the schema's
+* to define, not the cache's to guess.
+*/
+function attrValuesEqual(schema, field, a, b) {
+	if (a === b) return true;
+	if (field.kind === "schema-object") return schemaObjectsEqual(schema, field, a, b);
+	if (field.kind === "schema-array") return schemaArraysEqual(schema, field, a, b);
+	return false;
+}
+/**
+* A schema-array has no hash of its own: two arrays are the same when they have the same length
+* and every element compares equal as a schema-object of the element type.
+*/
+function schemaArraysEqual(schema, field, a, b) {
+	if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (!schemaObjectsEqual(schema, field, a[i], b[i])) return false;
+	return true;
+}
+function schemaObjectsEqual(schema, field, a, b) {
+	if (a === b) return true;
+	if (!a || !b || typeof a !== "object" || typeof b !== "object") return false;
+	const ia = fieldValueIdentity(schema, field, a);
+	const ib = fieldValueIdentity(schema, field, b);
+	return ia !== null && ib !== null && ia.type === ib.type && ia.hash !== null && ia.hash === ib.hash;
+}
+/**
+* Whether a nested edit's local clone is back to the baseline, so the edit can end. The schema
+* decides first, through {@link attrValuesEqual}: a schema-object with an identity hash matches
+* when its hash does. A value with no schema-defined equality falls back to comparing serialized
+* content, as this path always has: the clone began as a copy of the baseline, so key order
+* agrees while edits only replace existing keys. Anything that cannot serialize counts as still
+* edited, so no edit the cache cannot understand is thrown away.
+*/
+function localCloneMatchesBaseline(schema, field, baseline, clone) {
+	if (field && attrValuesEqual(schema, field, baseline, clone)) return true;
+	if (!baseline || !clone) return false;
+	try {
+		return JSON.stringify(baseline) === JSON.stringify(clone);
+	} catch {
+		return false;
+	}
+}
+/**
+* Which projection each changed key moved in, so the caller can notify on the matching channel:
+* `localOnly` and `remoteOnly` on theirs, `both` unscoped.
+*
+* `undefined` rather than empty Sets: this runs on every `upsert`, and a resource where nothing
+* moved should cost no allocation.
+*/
+const NO_PROJECTION_CHANGES = Object.freeze({
+	localOnly: void 0,
+	remoteOnly: void 0,
+	both: void 0
+});
+/** The layers a merge reads: the resource's own, plus the attributes arriving from the server. */
+function layersForMerge(cached, incomingAttrs) {
+	return {
+		localAttrs: cached.localAttrs,
+		inflightAttrs: cached.inflightAttrs,
+		remoteAttrs: cached.remoteAttrs,
+		defaultAttrs: cached.defaultAttrs,
+		incomingAttrs
+	};
+}
+/**
+* Every key a merge could move: every key in every layer the after-merge order folds into
+* `remoteAttrs`. `null` when there is nothing to examine.
+*/
+function candidateKeys(layers, remoteAfterOrder) {
+	let keys = null;
+	for (let i = 0; i < remoteAfterOrder.length; i++) {
+		const layer = remoteAfterOrder[i];
+		if (layer === "remoteAttrs") break;
+		const hash = layers[layer];
+		if (!hash) continue;
+		const layerKeys = Object.keys(hash);
+		if (!layerKeys.length) continue;
+		if (keys === null) {
+			keys = layerKeys;
+			continue;
+		}
+		for (let j = 0; j < layerKeys.length; j++) if (!keys.includes(layerKeys[j])) keys.push(layerKeys[j]);
+	}
+	return keys;
+}
+/**
+* Fold every layer above `remoteAttrs` in the after-merge order for `kind` into `remoteAttrs`,
+* lowest precedence first, and clear each resource layer that was folded in. The same order
+* {@link partitionChangedKeys} used to predict the result, so the two cannot disagree.
+*
+* Reads the resource layers off `cached` rather than taking a {@link Layered}, so an upsert that
+* is not calculating changes allocates nothing beyond the merge itself.
+*/
+function mergeIntoRemote(cached, incomingAttrs, kind) {
+	const folded = MERGE_RESOLUTION[kind].folded;
+	const target = cached.remoteAttrs || Object.create(null);
+	for (let i = 0; i < folded.length; i++) {
+		const layer = folded[i];
+		const hash = layer === "incomingAttrs" ? incomingAttrs : cached[layer];
+		if (!hash) continue;
+		Object.assign(target, hash);
+		if (layer !== "incomingAttrs") cached[layer] = null;
+		if (cached.defaultAttrs) dropMemoizedDefaults(cached.defaultAttrs, hash);
+	}
+	cached.remoteAttrs = target;
+}
+function dropMemoizedDefaults(defaultAttrs, replacedBy) {
+	const keys = Object.keys(replacedBy);
+	for (let i = 0; i < keys.length; i++) if (keys[i] in defaultAttrs) delete defaultAttrs[keys[i]];
+}
+/**
+* Partition the keys a merge touches by which projection each one moves in. Must run *before*
+* {@link mergeIntoRemote}: it reads the pre-merge layers from `layers` and predicts the merge with
+* the same `RESOLUTION_ORDER_*_AFTER_*` orders `mergeIntoRemote` applies.
+*/
+function partitionChangedKeys(schema, layers, fields, kind) {
+	const { remoteAfter: remoteAfterOrder, localAfter: localAfterOrder } = MERGE_RESOLUTION[kind];
+	const keys = candidateKeys(layers, remoteAfterOrder);
+	if (keys === null) return NO_PROJECTION_CHANGES;
+	let localOnly;
+	let remoteOnly;
+	let both;
+	for (let i = 0; i < keys.length; i++) {
+		const key = keys[i];
+		const field = fields.get(key);
+		if (!field || isRelationship(field)) continue;
+		const remoteBefore = resolveAttr(key, layers, RESOLUTION_ORDER_REMOTE_STATE);
+		const remoteAfter = resolveAttr(key, layers, remoteAfterOrder);
+		const localBefore = resolveAttr(key, layers, RESOLUTION_ORDER_LOCAL_STATE);
+		const localAfter = resolveAttr(key, layers, localAfterOrder);
+		const remoteMoved = !attrValuesEqual(schema, field, remoteBefore, remoteAfter);
+		const localMoved = !attrValuesEqual(schema, field, localBefore, localAfter);
+		if (remoteMoved && localMoved) (both ??= /* @__PURE__ */ new Set()).add(key);
+		else if (remoteMoved) (remoteOnly ??= /* @__PURE__ */ new Set()).add(key);
+		else if (localMoved) (localOnly ??= /* @__PURE__ */ new Set()).add(key);
+	}
+	return both || remoteOnly || localOnly ? {
+		localOnly,
+		remoteOnly,
+		both
+	} : NO_PROJECTION_CHANGES;
+}
+function notifyProjectionChanges(cache, identifier, { both, remoteOnly, localOnly }) {
+	if (both?.size) cache._capabilities.notifyChange(identifier, "attributes", both);
+	if (remoteOnly?.size) cache._capabilities.notifyChange(identifier, "attributes", remoteOnly, "remote");
+	if (localOnly?.size) cache._capabilities.notifyChange(identifier, "attributes", localOnly, "local");
 }
 function cacheIsEmpty(cached) {
 	return !cached || cached.remoteAttrs === null && cached.inflightAttrs === null && cached.localAttrs === null;
@@ -2190,25 +2614,26 @@ function isRelationship(field) {
 	const { kind } = field;
 	return kind === "hasMany" || kind === "belongsTo" || kind === "resource" || kind === "collection";
 }
-function patchLocalAttributes(cached, changedRemoteKeys) {
-	const { localAttrs, remoteAttrs, inflightAttrs, defaultAttrs, changes } = cached;
-	if (!localAttrs) {
-		cached.changes = null;
-		return false;
-	}
-	let hasAppliedPatch = false;
-	const mutatedKeys = Object.keys(localAttrs);
-	for (let i = 0, length = mutatedKeys.length; i < length; i++) {
-		const attr = mutatedKeys[i];
-		if ((inflightAttrs && attr in inflightAttrs ? inflightAttrs[attr] : remoteAttrs && attr in remoteAttrs ? remoteAttrs[attr] : void 0) === localAttrs[attr]) {
-			hasAppliedPatch = true;
-			changedRemoteKeys?.delete(attr);
-			delete localAttrs[attr];
-			delete changes[attr];
+/**
+* After a merge: drop every local edit the new baseline agrees with, by the same equality
+* {@link partitionChangedKeys} uses. Returns whether any edit was dropped.
+*/
+function reconcileLocalEdits(schema, cached, fields) {
+	const { localAttrs, defaultAttrs } = cached;
+	if (!localAttrs) return false;
+	let droppedAnEdit = false;
+	const editedKeys = Object.keys(localAttrs);
+	for (let i = 0; i < editedKeys.length; i++) {
+		const key = editedKeys[i];
+		const field = fields.get(key);
+		const baseline = resolveAttr(key, cached, RESOLUTION_ORDER_EDIT_BASELINE);
+		if (field ? attrValuesEqual(schema, field, baseline, localAttrs[key]) : baseline === localAttrs[key]) {
+			droppedAnEdit = true;
+			delete localAttrs[key];
 		}
-		if (defaultAttrs && attr in defaultAttrs) delete defaultAttrs[attr];
+		if (defaultAttrs && key in defaultAttrs) delete defaultAttrs[key];
 	}
-	return hasAppliedPatch;
+	return droppedAnEdit;
 }
 function putOne(cache, identifiers, resource) {
 	macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
@@ -2300,7 +2725,7 @@ function copyLinksAndMeta(target, source) {
 	if ("meta" in source) target.meta = source.meta;
 }
 function cacheUpsert(cache, identifier, data, calculateChanges) {
-	let changedKeys;
+	let changes = NO_PROJECTION_CHANGES;
 	const peeked = cache.__safePeek(identifier, false);
 	const existed = !!peeked;
 	const cached = peeked || cache._createCache(identifier);
@@ -2323,19 +2748,29 @@ function cacheUpsert(cache, identifier, data, calculateChanges) {
 		cache._capabilities.notifyChange(identifier, "state", null);
 	}
 	const fields = getCacheFields(cache, identifier);
-	if (calculateChanges && existed && data.attributes) changedKeys = calculateChangedKeys(cached, data.attributes, fields);
-	cached.remoteAttrs = Object.assign(cached.remoteAttrs || Object.create(null), data.attributes);
+	if (calculateChanges && existed && data.attributes) changes = partitionChangedKeys(cache._capabilities.schema, layersForMerge(cached, data.attributes), fields, "upsert");
+	mergeIntoRemote(cached, data.attributes ?? null, "upsert");
 	if (cached.localAttrs) {
-		if (patchLocalAttributes(cached, changedKeys)) cache._capabilities.notifyChange(identifier, "state", null);
+		if (reconcileLocalEdits(cache._capabilities.schema, cached, fields)) cache._capabilities.notifyChange(identifier, "state", null);
 	}
 	if (!isUpdate) cache._capabilities.notifyChange(identifier, "added", null);
 	if (data.id) cached.id = data.id;
 	if (data.relationships) setupRelationships(cache.__graph, fields, identifier, data);
-	if (changedKeys?.size) cache._capabilities.notifyChange(identifier, "attributes", changedKeys);
+	macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+		if (!test) throw new Error("An upsert merges nothing into remote state, so no key can move in the local projection alone");
+	})(!changes.localOnly?.size);
+	notifyProjectionChanges(cache, identifier, changes);
 	if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_CACHE)) {
 		if (getGlobalConfig().WarpDriveMirror.debug.LOG_CACHE || globalThis.getWarpDriveRuntimeConfig().debug.LOG_CACHE) console.groupEnd();
 	}
-	return changedKeys?.size ? Array.from(changedKeys) : void 0;
+	return remoteChangedKeys(changes);
+}
+/** Every key whose remote value moved, as the `upsert` return value. */
+function remoteChangedKeys({ both, remoteOnly }) {
+	if (!both?.size) return remoteOnly?.size ? Array.from(remoteOnly) : void 0;
+	const keys = Array.from(both);
+	if (remoteOnly?.size) keys.push(...remoteOnly);
+	return keys;
 }
 function patchCache(Cache, op) {
 	const isRecord = isResourceKey(op.record);
@@ -2438,10 +2873,11 @@ function commitDidError(cache, identifier, errors) {
 		const keys = Object.keys(cached.inflightAttrs);
 		if (keys.length > 0) {
 			const attrs = cached.localAttrs = cached.localAttrs || Object.create(null);
-			for (let i = 0; i < keys.length; i++) if (attrs[keys[i]] === void 0) attrs[keys[i]] = cached.inflightAttrs[keys[i]];
+			for (let i = 0; i < keys.length; i++) if (!(keys[i] in attrs)) attrs[keys[i]] = cached.inflightAttrs[keys[i]];
 		}
 		cached.inflightAttrs = null;
 	}
+	if (reconcileLocalEdits(cache._capabilities.schema, cached, getCacheFields(cache, identifier))) cache._capabilities.notifyChange(identifier, "state", null);
 	if (errors) cached.errors = errors;
 	cache._capabilities.notifyChange(identifier, "errors", null);
 }
@@ -2473,7 +2909,7 @@ function didCommit(cache, committedIdentifier, data, op) {
 	}
 	const fields = getCacheFields(cache, identifier);
 	cached.isNew = false;
-	let newCanonicalAttributes;
+	let responseAttrs = null;
 	if (data) {
 		if (data.id && !cached.id) cached.id = data.id;
 		if (identifier === committedIdentifier && identifier.id !== existingId) cache._capabilities.notifyChange(identifier, "identity", null);
@@ -2501,17 +2937,16 @@ function didCommit(cache, committedIdentifier, data, op) {
 			}
 			setupRelationships(cache.__graph, fields, identifier, data);
 		}
-		newCanonicalAttributes = data.attributes;
+		responseAttrs = data.attributes ?? null;
 	}
-	const changedKeys = newCanonicalAttributes && calculateChangedKeys(cached, newCanonicalAttributes, fields);
-	cached.remoteAttrs = Object.assign(cached.remoteAttrs || Object.create(null), cached.inflightAttrs, newCanonicalAttributes);
-	cached.inflightAttrs = null;
-	patchLocalAttributes(cached, changedKeys);
+	const changes = partitionChangedKeys(cache._capabilities.schema, layersForMerge(cached, responseAttrs), fields, "commit");
+	mergeIntoRemote(cached, responseAttrs, "commit");
+	reconcileLocalEdits(cache._capabilities.schema, cached, fields);
 	if (cached.errors) {
 		cached.errors = null;
 		cache._capabilities.notifyChange(identifier, "errors", null);
 	}
-	if (changedKeys?.size) cache._capabilities.notifyChange(identifier, "attributes", changedKeys);
+	notifyProjectionChanges(cache, identifier, changes);
 	cache._capabilities.notifyChange(identifier, "state", null);
 }
 function willCommit(cache, identifier) {