@warp-drive-mirror/json-api 5.8.0-alpha.5 → 5.8.0-alpha.7

package/README.md

@@ -26,7 +26,7 @@
 <br>
 
 <p align="center">
-A {JSON:API} Cache Implementation for <em>Warp</em><strong>Drive</strong>.
+A {json:api} Cache Implementation for <em>Warp</em><strong>Drive</strong>.
 </p>
 
 <br>
@@ -41,7 +41,7 @@ pnpm add -E @warp-drive-mirror/json-api
 
 ## Documentation
 
-*Get Started* → [Guides](https://docs.warp-drive.io)
+*Get Started* → [Guides](https://warp-drive.io)
 
 
 <br>

package/declarations/-private/cache.d.ts

@@ -11,82 +11,12 @@ import type { CollectionResourceDataDocument, ResourceDocument, ResourceErrorDoc
 import type { ApiError } from "@warp-drive-mirror/core/types/spec/error";
 import type { CollectionResourceDocument, ExistingResourceObject, ResourceObject, SingleResourceDocument } from "@warp-drive-mirror/core/types/spec/json-api-raw";
 /**
-* ### JSONAPICache
-*
 * ```ts
 * import { JSONAPICache } from '@warp-drive-mirror/json-api';
 * ```
 *
-A {@link Cache} implementation tuned for [{json:api}](https://jsonapi.org/)
-
-This format excels at simiplifying common complex problems around cache
-consistency and information density. Because most API responses can be quickly
-transformed into {json:api} format without losing any information, WarpDrive
-recommends that most apps use this Cache implementation.
-
-If a cache built to understand another format would do better for your app then
-it just needs to follow the same interface.
-
-Do you really need a cache? Are sunsets beautiful? Caching is what powers features like
-immutability, mutation management, and allows ***Warp*Drive** to understand your relational
-data.
-
-Some caches are simple request/response maps. ***Warp*Drive**'s is not. The Cache deeply
-understands the structure of your data, ensuring your data remains consistent both within
-and across requests.
-
-### Installation
-
-::: code-group
-
-```sh [pnpm]
-pnpm add -E @warp-drive-mirror/core@latest @warp-drive-mirror/json-api@latest
-```
-
-```sh [npm]
-npm add -E @warp-drive-mirror/core@latest @warp-drive-mirror/json-api@latest
-```
-
-```sh [yarn]
-yarn add -E @warp-drive-mirror/core@latest @warp-drive-mirror/json-api@latest
-```
-
-```sh [bun]
-bun add --exact @warp-drive-mirror/core@latest @warp-drive-mirror/json-api@latest
-```
-
-:::
-
-### Setup
-
-```ts [services/store.ts]
-import { Fetch, RequestManager, Store } from '@warp-drive-mirror/core';
-import {
-registerDerivations,
-SchemaService,
-} from '@warp-drive-mirror/core/reactive';
-import { CacheHandler } from '@warp-drive-mirror/core/store';
-import type { CacheCapabilitiesManager } from '@warp-drive-mirror/core/types'; // [!code focus:2]
-import { JSONAPICache } from '@warp-drive-mirror/json-api';
-
-export default class AppStore extends Store {
-
-requestManager = new RequestManager()
-.use([Fetch])
-.useCache(CacheHandler);
-
-createSchemaService() {
-const schema = new SchemaService();
-registerDerivations(schema);
-return schema;
-}
-
-createCache(capabilities: CacheCapabilitiesManager) { // [!code focus:3]
-return new JSONAPICache(capabilities);
-}
-}
-```
-
+* A {@link Cache} implementation tuned for [{json:api}](https://jsonapi.org/)
+*
 * @categoryDescription Cache Management
 * APIs for primary cache management functionality
 * @categoryDescription Cache Forking
@@ -99,8 +29,8 @@ return new JSONAPICache(capabilities);
 * APIs that support granular field level management of resource data
 * @categoryDescription Resource State
 * APIs that support managing Resource states
-
-@public
+*
+* @public
 */
 export declare class JSONAPICache implements Cache {
 	/**
@@ -325,7 +255,7 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource Lifecycle
 	* @public
 	*/
-	willCommit(identifier: ResourceKey, _context: RequestContext | null): void;
+	willCommit(identifier: ResourceKey | ResourceKey[], _context: RequestContext | null): void;
 	/**
 	* [LIFECYCLE] Signals to the cache that a resource
 	* was successfully updated as part of a save transaction.
@@ -333,7 +263,9 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource Lifecycle
 	* @public
 	*/
-	didCommit(committedIdentifier: ResourceKey, result: StructuredDataDocument<SingleResourceDocument> | null): SingleResourceDataDocument;
+	didCommit(committedIdentifier: ResourceKey, result: StructuredDataDocument<SingleResourceDataDocument> | null): SingleResourceDataDocument;
+	didCommit(committedIdentifier: ResourceKey[], result: StructuredDataDocument<SingleResourceDataDocument> | null): SingleResourceDataDocument;
+	didCommit(committedIdentifier: ResourceKey[], result: StructuredDataDocument<CollectionResourceDataDocument> | null): CollectionResourceDataDocument;
 	/**
 	* [LIFECYCLE] Signals to the cache that a resource
 	* was update via a save transaction failed.
@@ -341,7 +273,7 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource Lifecycle
 	* @public
 	*/
-	commitWasRejected(identifier: ResourceKey, errors?: ApiError[]): void;
+	commitWasRejected(identifier: ResourceKey | ResourceKey[], errors?: ApiError[]): void;
 	/**
 	* [LIFECYCLE] Signals to the cache that all data for a resource
 	* should be cleared.

package/declarations/index.d.ts

@@ -1 +1,5 @@
+/**
+* @module
+* @mergeModuleWith <project>
+*/
 export { JSONAPICache } from "./-private/cache.js";

package/dist/index.js

@@ -361,7 +361,7 @@ class Reporter {
         }
       }
     }
-    const contextStr = `${counts.error} errors and ${counts.warning} warnings found in the {JSON:API} document returned by ${this.contextDocument.request?.method} ${this.contextDocument.request?.url}`;
+    const contextStr = `${counts.error} errors and ${counts.warning} warnings found in the {json:api} document returned by ${this.contextDocument.request?.method} ${this.contextDocument.request?.url}`;
     const errorString = contextStr + `\n\n` + errorLines.join('\n');
 
     // eslint-disable-next-line no-console, @typescript-eslint/no-unused-expressions
@@ -449,10 +449,10 @@ function validateTopLevelDocumentMembers(reporter, doc) {
           const extension = reporter.getExtension(extensionName);
           extension(reporter, [key]);
         } else {
-          reporter.warn([key], `Unrecognized extension ${extensionName}. The data provided by "${key}" will be ignored as it is not a valid {JSON:API} member`);
+          reporter.warn([key], `Unrecognized extension ${extensionName}. The data provided by "${key}" will be ignored as it is not a valid {json:api} member`);
         }
       } else {
-        reporter.error([key], `Unrecognized top-level member. The data it provides is ignored as it is not a valid {JSON:API} member`);
+        reporter.error([key], `Unrecognized top-level member. The data it provides is ignored as it is not a valid {json:api} member`);
       }
     }
   }
@@ -462,24 +462,24 @@ function validateTopLevelDocumentMembers(reporter, doc) {
 
   // 1. MUST have either `data`, `errors`, or `meta`
   if (!('data' in doc) && !('errors' in doc) && !('meta' in doc)) {
-    reporter.error([], 'A {JSON:API} Document must contain one-of `data` `errors` or `meta`');
+    reporter.error([], 'A {json:api} Document must contain one-of `data` `errors` or `meta`');
   }
 
   // 2. MUST NOT have both `data` and `errors`
   if ('data' in doc && 'errors' in doc) {
-    reporter.error(['data'], 'A {JSON:API} Document MUST NOT contain both `data` and `errors` members');
+    reporter.error(['data'], 'A {json:api} Document MUST NOT contain both `data` and `errors` members');
   }
 
   // 3. MUST NOT have both `included` and `errors`
   // while not explicitly stated in the spec, this is a logical extension of the above rule
   // since `included` is only valid when `data` is present.
   if ('included' in doc && 'errors' in doc) {
-    reporter.error(['included'], 'A {JSON:API} Document MUST NOT contain both `included` and `errors` members');
+    reporter.error(['included'], 'A {json:api} Document MUST NOT contain both `included` and `errors` members');
   }
 
   // 4. MUST NOT have `included` if `data` is not present
   if ('included' in doc && !('data' in doc)) {
-    reporter.error(['included'], 'A {JSON:API} Document MUST NOT contain `included` if `data` is not present');
+    reporter.error(['included'], 'A {json:api} Document MUST NOT contain `included` if `data` is not present');
   }
 
   // 5. MUST NOT have `included` if `data` is null
@@ -489,7 +489,7 @@ function validateTopLevelDocumentMembers(reporter, doc) {
   if ('included' in doc && doc.data === null) {
     const isMaybeDelete = reporter.contextDocument.request?.method?.toUpperCase() === 'DELETE' || reporter.contextDocument.request?.op === 'deleteRecord';
     const method = !reporter.strict.linkage && isMaybeDelete ? 'warn' : 'error';
-    reporter[method](['included'], 'A {JSON:API} Document MUST NOT contain `included` if `data` is null');
+    reporter[method](['included'], 'A {json:api} Document MUST NOT contain `included` if `data` is null');
   }
 
   // Simple Validation of Top-Level Members
@@ -576,7 +576,7 @@ function validateLinks(reporter, doc, type, path = ['links']) {
   const keys = Object.keys(links);
   for (const key of keys) {
     if (!VALID_TOP_LEVEL_LINKS.includes(key)) {
-      reporter.warn([...path, key], `Unrecognized top-level link. The data it provides may be ignored as it is not a valid {JSON:API} link for a ${type}`);
+      reporter.warn([...path, key], `Unrecognized top-level link. The data it provides may be ignored as it is not a valid {json:api} link for a ${type}`);
     }
     // links may be either a string or an object with an href property or null
     if (links[key] === null) ; else if (typeof links[key] === 'string') {
@@ -738,7 +738,7 @@ function validateTopLevelResourceShape(reporter, resource, path) {
           const extension = reporter.getExtension(extensionName);
           extension(reporter, [...path, key]);
         } else {
-          reporter.warn([...path, key], `Unrecognized extension ${extensionName}. The data provided by "${key}" will be ignored as it is not a valid {JSON:API} ResourceObject member`);
+          reporter.warn([...path, key], `Unrecognized extension ${extensionName}. The data provided by "${key}" will be ignored as it is not a valid {json:api} ResourceObject member`);
         }
       } else {
         // check if this is an attribute or relationship
@@ -767,7 +767,7 @@ function validateTopLevelResourceShape(reporter, resource, path) {
             }
           }
         }
-        reporter.error([...path, key], `Unrecognized ResourceObject member. The data it provides is ignored as it is not a valid {JSON:API} ResourceObject member.${didYouMean}`);
+        reporter.error([...path, key], `Unrecognized ResourceObject member. The data it provides is ignored as it is not a valid {json:api} ResourceObject member.${didYouMean}`);
       }
     }
   }
@@ -801,7 +801,7 @@ function validateResourceAttributes(reporter, type, resource, path) {
           const extension = reporter.getExtension(extensionName);
           extension(reporter, [...path, key]);
         } else {
-          reporter.warn([...path, key], `Unrecognized extension ${extensionName}. The data provided by "${key}" will be ignored as it is not a valid {JSON:API} ResourceObject member`);
+          reporter.warn([...path, key], `Unrecognized extension ${extensionName}. The data provided by "${key}" will be ignored as it is not a valid {json:api} ResourceObject member`);
         }
       } else {
         const method = reporter.strict.unknownAttribute ? 'error' : 'warn';
@@ -835,7 +835,7 @@ function validateResourceRelationships(reporter, type, resource, path) {
           const extension = reporter.getExtension(extensionName);
           extension(reporter, [...path, key]);
         } else {
-          reporter.warn([...path, key], `Unrecognized extension ${extensionName}. The data provided by "${key}" will be ignored as it is not a valid {JSON:API} ResourceObject member`);
+          reporter.warn([...path, key], `Unrecognized extension ${extensionName}. The data provided by "${key}" will be ignored as it is not a valid {json:api} ResourceObject member`);
         }
       } else {
         const method = reporter.strict.unknownRelationship ? 'error' : 'warn';
@@ -955,82 +955,12 @@ function makeCache() {
 }
 
 /**
- * ### JSONAPICache
- *
  * ```ts
  * import { JSONAPICache } from '@warp-drive-mirror/json-api';
  * ```
  *
-  A {@link Cache} implementation tuned for [{json:api}](https://jsonapi.org/)
-
-  This format excels at simiplifying common complex problems around cache
-  consistency and information density. Because most API responses can be quickly
-  transformed into {json:api} format without losing any information, WarpDrive
-  recommends that most apps use this Cache implementation.
-
-  If a cache built to understand another format would do better for your app then
-  it just needs to follow the same interface.
-
-  Do you really need a cache? Are sunsets beautiful? Caching is what powers features like
-  immutability, mutation management, and allows ***Warp*Drive** to understand your relational
-  data.
-
-  Some caches are simple request/response maps. ***Warp*Drive**'s is not. The Cache deeply
-  understands the structure of your data, ensuring your data remains consistent both within
-  and across requests.
-
-  ### Installation
-
-  ::: code-group
-
-  ```sh [pnpm]
-  pnpm add -E @warp-drive-mirror/core@latest @warp-drive-mirror/json-api@latest
-  ```
-
-  ```sh [npm]
-  npm add -E @warp-drive-mirror/core@latest @warp-drive-mirror/json-api@latest
-  ```
-
-  ```sh [yarn]
-  yarn add -E @warp-drive-mirror/core@latest @warp-drive-mirror/json-api@latest
-  ```
-
-  ```sh [bun]
-  bun add --exact @warp-drive-mirror/core@latest @warp-drive-mirror/json-api@latest
-  ```
-
-  :::
-
-  ### Setup
-
-  ```ts [services/store.ts]
-  import { Fetch, RequestManager, Store } from '@warp-drive-mirror/core';
-  import {
-    registerDerivations,
-    SchemaService,
-  } from '@warp-drive-mirror/core/reactive';
-  import { CacheHandler } from '@warp-drive-mirror/core/store';
-  import type { CacheCapabilitiesManager } from '@warp-drive-mirror/core/types'; // [!code focus:2]
-  import { JSONAPICache } from '@warp-drive-mirror/json-api';
-
-  export default class AppStore extends Store {
-
-    requestManager = new RequestManager()
-      .use([Fetch])
-      .useCache(CacheHandler);
-
-    createSchemaService() {
-      const schema = new SchemaService();
-      registerDerivations(schema);
-      return schema;
-    }
-
-    createCache(capabilities: CacheCapabilitiesManager) { // [!code focus:3]
-      return new JSONAPICache(capabilities);
-    }
-  }
-  ```
-
+ * A {@link Cache} implementation tuned for [{json:api}](https://jsonapi.org/)
+ *
  * @categoryDescription Cache Management
  * APIs for primary cache management functionality
  * @categoryDescription Cache Forking
@@ -1043,10 +973,9 @@ function makeCache() {
  * APIs that support granular field level management of resource data
  * @categoryDescription Resource State
  * APIs that support managing Resource states
-
-  @public
+ *
+ * @public
  */
-
 class JSONAPICache {
   /**
    * The Cache Version that this implementation implements.
@@ -1689,50 +1618,12 @@ class JSONAPICache {
    * @public
    */
   willCommit(identifier, _context) {
-    const cached = this.__peek(identifier, false);
-
-    /*
-      if we have multiple saves in flight at once then
-      we have information loss no matter what. This
-      attempts to lose the least information.
-       If we were to clear inflightAttrs, previous requests
-      would not be able to use it during their didCommit.
-       If we upsert inflightattrs, previous requests incorrectly
-      see more recent inflight changes as part of their own and
-      will incorrectly mark the new state as the correct remote state.
-       We choose this latter behavior to avoid accidentally removing
-      earlier changes.
-       If apps do not want this behavior they can either
-      - chain save requests serially vs allowing concurrent saves
-      - move to using a request handler that caches the inflight state
-        on a per-request basis
-      - change their save requests to only send a "PATCH" instead of a "PUT"
-        so that only latest changes are involved in each request, and then also
-        ensure that the API or their handler reflects only those changes back
-        for upsert into the cache.
-    */
-    if (cached.inflightAttrs) {
-      if (cached.localAttrs) {
-        Object.assign(cached.inflightAttrs, cached.localAttrs);
+    if (Array.isArray(identifier)) {
+      for (const key of identifier) {
+        willCommit(this, key);
       }
     } else {
-      cached.inflightAttrs = cached.localAttrs;
-    }
-    cached.localAttrs = null;
-    if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
-      if (macroCondition(!getGlobalConfig().WarpDriveMirror.deprecations.DEPRECATE_RELATIONSHIP_REMOTE_UPDATE_CLEARING_LOCAL_STATE)) {
-        // save off info about saved relationships
-        const fields = getCacheFields(this, identifier);
-        fields.forEach((schema, name) => {
-          if (schema.kind === 'belongsTo') {
-            if (this.__graph._isDirty(identifier, name)) {
-              const relationshipData = this.__graph.getData(identifier, name);
-              const inFlight = cached.inflightRelationships = cached.inflightRelationships || Object.create(null);
-              inFlight[name] = relationshipData;
-            }
-          }
-        });
-      }
+      willCommit(this, identifier);
     }
   }
 
@@ -1743,9 +1634,10 @@ class JSONAPICache {
    * @category Resource Lifecycle
    * @public
    */
+
   didCommit(committedIdentifier, result) {
     const payload = result ? result.content : null;
-    const operation = result ? result.request.op : null;
+    const operation = result?.request?.op ?? null;
     const data = payload && payload.data;
     if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_CACHE)) {
       if (getGlobalConfig().WarpDriveMirror.debug.LOG_CACHE || globalThis.getWarpDriveRuntimeConfig().debug.LOG_CACHE) {
@@ -1759,101 +1651,45 @@ class JSONAPICache {
         }
       }
     }
-    if (!data) {
+    const responseIsCollection = Array.isArray(data);
+    const hasMultipleIdentifiers = Array.isArray(committedIdentifier) && committedIdentifier.length > 1;
+    if (Array.isArray(committedIdentifier)) {
+      // if we get back an array of primary data, we treat each
+      // entry as a separate commit for each identifier
       macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
         if (!test) {
-          throw new Error(`Your ${committedIdentifier.type} record was saved to the server, but the response does not have an id and no id has been set client side. Records must have ids. Please update the server response to provide an id in the response or generate the id on the client side either before saving the record or while normalizing the response.`);
+          throw new Error(`Expected the array of primary data to match the array of committed identifiers`);
         }
-      })(committedIdentifier.id) : {};
-    }
-    const {
-      cacheKeyManager
-    } = this._capabilities;
-    const existingId = committedIdentifier.id;
-    const identifier = operation !== 'deleteRecord' && data ? cacheKeyManager.updateRecordIdentifier(committedIdentifier, data) : committedIdentifier;
-    const cached = this.__peek(identifier, false);
-    if (cached.isDeleted) {
-      this.__graph.push({
-        op: 'deleteRecord',
-        record: identifier,
-        isNew: false
-      });
-      cached.isDeletionCommitted = true;
-      this._capabilities.notifyChange(identifier, 'removed', null);
-      // TODO @runspired should we early exit here?
-    }
-    if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
-      if (cached.isNew && !identifier.id && (typeof data?.id !== 'string' || data.id.length > 0)) {
-        const error = new Error(`Expected an id ${String(identifier)} in response ${JSON.stringify(data)}`);
-        //@ts-expect-error
-        error.isAdapterError = true;
-        //@ts-expect-error
-        error.code = 'InvalidError';
-        throw error;
-      }
-    }
-    const fields = getCacheFields(this, identifier);
-    cached.isNew = false;
-    let newCanonicalAttributes;
-    if (data) {
-      if (data.id && !cached.id) {
-        cached.id = data.id;
-      }
-      if (identifier === committedIdentifier && identifier.id !== existingId) {
-        this._capabilities.notifyChange(identifier, 'identity', null);
-      }
-      macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
-        if (!test) {
-          throw new Error(`Expected the ID received for the primary '${identifier.type}' resource being saved to match the current id '${cached.id}' but received '${identifier.id}'.`);
+      })(!hasMultipleIdentifiers || !responseIsCollection || data.length === committedIdentifier.length) : {};
+      if (responseIsCollection) {
+        for (let i = 0; i < committedIdentifier.length; i++) {
+          const identifier = committedIdentifier[i];
+          didCommit(this, identifier, data[i] ?? null, operation);
         }
-      })(identifier.id === cached.id) : {};
-      if (data.relationships) {
-        if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
-          if (macroCondition(!getGlobalConfig().WarpDriveMirror.deprecations.DEPRECATE_RELATIONSHIP_REMOTE_UPDATE_CLEARING_LOCAL_STATE)) {
-            // assert against bad API behavior where a belongsTo relationship
-            // is saved but the return payload indicates a different final state.
-            fields.forEach((field, name) => {
-              if (field.kind === 'belongsTo') {
-                const relationshipData = data.relationships[name]?.data;
-                if (relationshipData !== undefined) {
-                  const inFlightData = cached.inflightRelationships?.[name];
-                  if (!inFlightData || !('data' in inFlightData)) {
-                    return;
-                  }
-                  const actualData = relationshipData ? this._capabilities.cacheKeyManager.getOrCreateRecordIdentifier(relationshipData) : null;
-                  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
-                    if (!test) {
-                      throw new Error(`Expected the resource relationship '<${identifier.type}>.${name}' on ${identifier.lid} to be saved as ${inFlightData.data ? inFlightData.data.lid : '<null>'} but it was saved as ${actualData ? actualData.lid : '<null>'}`);
-                    }
-                  })(inFlightData.data === actualData) : {};
-                }
-              }
-            });
-            cached.inflightRelationships = null;
-          }
+        // but if we get back no data or a single entry, we apply
+        // the change back to the original identifier
+      } else {
+        for (let i = 0; i < committedIdentifier.length; i++) {
+          const identifier = committedIdentifier[i];
+          didCommit(this, identifier, i === 0 ? data : null, operation);
         }
-        setupRelationships(this.__graph, fields, identifier, data);
       }
-      newCanonicalAttributes = data.attributes;
-    }
-    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);
-    if (cached.errors) {
-      cached.errors = null;
-      this._capabilities.notifyChange(identifier, 'errors', null);
+    } else {
+      didCommit(this, committedIdentifier, data, operation);
     }
-    if (changedKeys?.size) notifyAttributes(this._capabilities, identifier, changedKeys);
-    this._capabilities.notifyChange(identifier, 'state', null);
     const included = payload && payload.included;
+    const {
+      cacheKeyManager
+    } = this._capabilities;
     if (included) {
       for (let i = 0, length = included.length; i < length; i++) {
         putOne(this, cacheKeyManager, included[i]);
       }
     }
-    return {
-      data: identifier
+    return hasMultipleIdentifiers && responseIsCollection ? {
+      data: committedIdentifier
+    } : {
+      data: Array.isArray(committedIdentifier) ? committedIdentifier[0] : committedIdentifier
     };
   }
 
@@ -1865,23 +1701,13 @@ class JSONAPICache {
    * @public
    */
   commitWasRejected(identifier, errors) {
-    const cached = this.__peek(identifier, false);
-    if (cached.inflightAttrs) {
-      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]] === undefined) {
-            attrs[keys[i]] = cached.inflightAttrs[keys[i]];
-          }
-        }
+    if (Array.isArray(identifier)) {
+      for (let i = 0; i < identifier.length; i++) {
+        commitDidError(this, identifier[i], errors && i === 0 ? errors : null);
       }
-      cached.inflightAttrs = null;
-    }
-    if (errors) {
-      cached.errors = errors;
+      return;
     }
-    this._capabilities.notifyChange(identifier, 'errors', null);
+    return commitDidError(this, identifier, errors || null);
   }
 
   /**
@@ -3233,5 +3059,160 @@ function getCacheFields(cache, identifier) {
   // the model schema service cannot process fields that are not cache fields
   return cache._capabilities.schema.fields(identifier);
 }
+function commitDidError(cache, identifier, errors) {
+  const cached = cache.__peek(identifier, false);
+  if (cached.inflightAttrs) {
+    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]] === undefined) {
+          attrs[keys[i]] = cached.inflightAttrs[keys[i]];
+        }
+      }
+    }
+    cached.inflightAttrs = null;
+  }
+  if (errors) {
+    cached.errors = errors;
+  }
+  cache._capabilities.notifyChange(identifier, 'errors', null);
+}
+function didCommit(cache, committedIdentifier, data, op) {
+  if (!data) {
+    macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`Your ${committedIdentifier.type} record was saved to the server, but the response does not have an id and no id has been set client side. Records must have ids. Please update the server response to provide an id in the response or generate the id on the client side either before saving the record or while normalizing the response.`);
+      }
+    })(committedIdentifier.id) : {};
+  }
+  const {
+    cacheKeyManager
+  } = cache._capabilities;
+  const existingId = committedIdentifier.id;
+  const identifier = op !== 'deleteRecord' && data ? cacheKeyManager.updateRecordIdentifier(committedIdentifier, data) : committedIdentifier;
+  const cached = cache.__peek(identifier, false);
+  if (cached.isDeleted) {
+    cache.__graph.push({
+      op: 'deleteRecord',
+      record: identifier,
+      isNew: false
+    });
+    cached.isDeletionCommitted = true;
+    cache._capabilities.notifyChange(identifier, 'removed', null);
+    // TODO @runspired should we early exit here?
+  }
+  if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
+    if (cached.isNew && !identifier.id && (typeof data?.id !== 'string' || data.id.length > 0)) {
+      const error = new Error(`Expected an id ${String(identifier)} in response ${JSON.stringify(data)}`);
+      //@ts-expect-error
+      error.isAdapterError = true;
+      //@ts-expect-error
+      error.code = 'InvalidError';
+      throw error;
+    }
+  }
+  const fields = getCacheFields(cache, identifier);
+  cached.isNew = false;
+  let newCanonicalAttributes;
+  if (data) {
+    if (data.id && !cached.id) {
+      cached.id = data.id;
+    }
+    if (identifier === committedIdentifier && identifier.id !== existingId) {
+      cache._capabilities.notifyChange(identifier, 'identity', null);
+    }
+    macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`Expected the ID received for the primary '${identifier.type}' resource being saved to match the current id '${cached.id}' but received '${identifier.id}'.`);
+      }
+    })(identifier.id === cached.id) : {};
+    if (data.relationships) {
+      if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
+        if (macroCondition(!getGlobalConfig().WarpDriveMirror.deprecations.DEPRECATE_RELATIONSHIP_REMOTE_UPDATE_CLEARING_LOCAL_STATE)) {
+          // assert against bad API behavior where a belongsTo relationship
+          // is saved but the return payload indicates a different final state.
+          fields.forEach((field, name) => {
+            if (field.kind === 'belongsTo') {
+              const relationshipData = data.relationships[name]?.data;
+              if (relationshipData !== undefined) {
+                const inFlightData = cached.inflightRelationships?.[name];
+                if (!inFlightData || !('data' in inFlightData)) {
+                  return;
+                }
+                const actualData = relationshipData ? cache._capabilities.cacheKeyManager.getOrCreateRecordIdentifier(relationshipData) : null;
+                macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+                  if (!test) {
+                    throw new Error(`Expected the resource relationship '<${identifier.type}>.${name}' on ${identifier.lid} to be saved as ${inFlightData.data ? inFlightData.data.lid : '<null>'} but it was saved as ${actualData ? actualData.lid : '<null>'}`);
+                  }
+                })(inFlightData.data === actualData) : {};
+              }
+            }
+          });
+          cached.inflightRelationships = null;
+        }
+      }
+      setupRelationships(cache.__graph, fields, identifier, data);
+    }
+    newCanonicalAttributes = data.attributes;
+  }
+  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);
+  if (cached.errors) {
+    cached.errors = null;
+    cache._capabilities.notifyChange(identifier, 'errors', null);
+  }
+  if (changedKeys?.size) notifyAttributes(cache._capabilities, identifier, changedKeys);
+  cache._capabilities.notifyChange(identifier, 'state', null);
+}
+function willCommit(cache, identifier) {
+  const cached = cache.__peek(identifier, false);
+
+  /*
+      if we have multiple saves in flight at once then
+      we have information loss no matter what. This
+      attempts to lose the least information.
+       If we were to clear inflightAttrs, previous requests
+      would not be able to use it during their didCommit.
+       If we upsert inflightattrs, previous requests incorrectly
+      see more recent inflight changes as part of their own and
+      will incorrectly mark the new state as the correct remote state.
+       We choose this latter behavior to avoid accidentally removing
+      earlier changes.
+       If apps do not want this behavior they can either
+      - chain save requests serially vs allowing concurrent saves
+      - move to using a request handler that caches the inflight state
+        on a per-request basis
+      - change their save requests to only send a "PATCH" instead of a "PUT"
+        so that only latest changes are involved in each request, and then also
+        ensure that the API or their handler reflects only those changes back
+        for upsert into the cache.
+    */
+  if (cached.inflightAttrs) {
+    if (cached.localAttrs) {
+      Object.assign(cached.inflightAttrs, cached.localAttrs);
+    }
+  } else {
+    cached.inflightAttrs = cached.localAttrs;
+  }
+  cached.localAttrs = null;
+  if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
+    if (macroCondition(!getGlobalConfig().WarpDriveMirror.deprecations.DEPRECATE_RELATIONSHIP_REMOTE_UPDATE_CLEARING_LOCAL_STATE)) {
+      // save off info about saved relationships
+      const fields = getCacheFields(cache, identifier);
+      fields.forEach((schema, name) => {
+        if (schema.kind === 'belongsTo') {
+          if (cache.__graph._isDirty(identifier, name)) {
+            const relationshipData = cache.__graph.getData(identifier, name);
+            const inFlight = cached.inflightRelationships = cached.inflightRelationships || Object.create(null);
+            inFlight[name] = relationshipData;
+          }
+        }
+      });
+    }
+  }
+}
 
 export { JSONAPICache };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@warp-drive-mirror/json-api",
-  "version": "5.8.0-alpha.5",
-  "description": "A {JSON:API} Cache Implementation for WarpDrive",
+  "version": "5.8.0-alpha.7",
+  "description": "A {json:api} Cache Implementation for WarpDrive",
   "keywords": [
     "ember-addon"
   ],
@@ -32,7 +32,7 @@
     }
   },
   "peerDependencies": {
-    "@warp-drive-mirror/core": "5.8.0-alpha.5"
+    "@warp-drive-mirror/core": "5.8.0-alpha.7"
   },
   "dependencies": {
     "@embroider/macros": "^1.18.1",
@@ -44,8 +44,8 @@
     "@babel/plugin-transform-typescript": "^7.28.0",
     "@babel/preset-typescript": "^7.27.1",
     "@types/json-to-ast": "^2.1.4",
-    "@warp-drive/internal-config": "5.8.0-alpha.5",
-    "@warp-drive-mirror/core": "5.8.0-alpha.5",
+    "@warp-drive/internal-config": "5.8.0-alpha.7",
+    "@warp-drive-mirror/core": "5.8.0-alpha.7",
     "decorator-transforms": "^2.3.0",
     "expect-type": "^1.2.2",
     "typescript": "^5.9.2",