@warp-drive-mirror/json-api 5.7.0-alpha.14 → 5.7.0-alpha.16

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

@@ -5,9 +5,9 @@ import type { Change } from "@warp-drive-mirror/core/types/cache/change";
 import type { Operation } from "@warp-drive-mirror/core/types/cache/operations";
 import type { CollectionRelationship, ResourceRelationship } from "@warp-drive-mirror/core/types/cache/relationship";
 import type { LocalRelationshipOperation } from "@warp-drive-mirror/core/types/graph";
-import type { StableDocumentIdentifier, StableExistingRecordIdentifier, StableRecordIdentifier } from "@warp-drive-mirror/core/types/identifier";
+import type { PersistedResourceKey, RequestKey, ResourceKey } from "@warp-drive-mirror/core/types/identifier";
 import type { Value } from "@warp-drive-mirror/core/types/json/raw";
-import type { StructuredDataDocument, StructuredDocument, StructuredErrorDocument } from "@warp-drive-mirror/core/types/request";
+import type { RequestContext, StructuredDataDocument, StructuredDocument, StructuredErrorDocument } from "@warp-drive-mirror/core/types/request";
 import type { CollectionResourceDataDocument, ResourceDocument, ResourceErrorDocument, ResourceMetaDocument, SingleResourceDataDocument } from "@warp-drive-mirror/core/types/spec/document";
 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";
@@ -131,9 +131,9 @@ export declare class JSONAPICache implements Cache {
 	/** @internal */
 	_capabilities: CacheCapabilitiesManager;
 	/** @internal */
-	__cache: Map<StableRecordIdentifier, CachedResource>;
+	__cache: Map<ResourceKey, CachedResource>;
 	/** @internal */
-	__destroyedCache: Map<StableRecordIdentifier, CachedResource>;
+	__destroyedCache: Map<ResourceKey, CachedResource>;
 	/** @internal */
 	__documents: Map<string, StructuredDocument<ResourceDocument>>;
 	/** @internal */
@@ -186,8 +186,8 @@ export declare class JSONAPICache implements Cache {
 	/** @internal */
 	_putDocument<T extends ResourceErrorDocument>(doc: StructuredErrorDocument<T>, data: undefined, included: undefined): ResourceErrorDocument;
 	_putDocument<T extends ResourceMetaDocument>(doc: StructuredDataDocument<T>, data: undefined, included: undefined): ResourceMetaDocument;
-	_putDocument<T extends SingleResourceDocument>(doc: StructuredDataDocument<T>, data: StableExistingRecordIdentifier | null, included: StableExistingRecordIdentifier[] | undefined): SingleResourceDataDocument;
-	_putDocument<T extends CollectionResourceDocument>(doc: StructuredDataDocument<T>, data: StableExistingRecordIdentifier[], included: StableExistingRecordIdentifier[] | undefined): CollectionResourceDataDocument;
+	_putDocument<T extends SingleResourceDocument>(doc: StructuredDataDocument<T>, data: PersistedResourceKey | null, included: PersistedResourceKey[] | undefined): SingleResourceDataDocument;
+	_putDocument<T extends CollectionResourceDocument>(doc: StructuredDataDocument<T>, data: PersistedResourceKey[], included: PersistedResourceKey[] | undefined): CollectionResourceDataDocument;
 	/**
 	* Update the "remote" or "canonical" (persisted) state of the Cache
 	* by merging new information into the existing state.
@@ -234,16 +234,16 @@ export declare class JSONAPICache implements Cache {
 	* @category Cache Management
 	* @public
 	*/
-	peek(identifier: StableRecordIdentifier): ResourceObject | null;
-	peek(identifier: StableDocumentIdentifier): ResourceDocument | null;
+	peek(identifier: ResourceKey): ResourceObject | null;
+	peek(identifier: RequestKey): ResourceDocument | null;
 	/**
 	* Peek the remote resource data from the Cache.
 	*
 	* @category Cache Management
 	* @public
 	*/
-	peekRemoteState(identifier: StableRecordIdentifier): ResourceObject | null;
-	peekRemoteState(identifier: StableDocumentIdentifier): ResourceDocument | null;
+	peekRemoteState(identifier: ResourceKey): ResourceObject | null;
+	peekRemoteState(identifier: RequestKey): ResourceDocument | null;
 	/**
 	* Peek the Cache for the existing request data associated with
 	* a cacheable request.
@@ -255,7 +255,7 @@ export declare class JSONAPICache implements Cache {
 	* @category Cache Management
 	* @public
 	*/
-	peekRequest(identifier: StableDocumentIdentifier): StructuredDocument<ResourceDocument> | null;
+	peekRequest(identifier: RequestKey): StructuredDocument<ResourceDocument> | null;
 	/**
 	* Push resource data from a remote source into the cache for this identifier
 	*
@@ -263,7 +263,7 @@ export declare class JSONAPICache implements Cache {
 	* @public
 	* @return if `calculateChanges` is true then calculated key changes should be returned
 	*/
-	upsert(identifier: StableRecordIdentifier, data: ExistingResourceObject, calculateChanges?: boolean): void | string[];
+	upsert(identifier: ResourceKey, data: ExistingResourceObject, calculateChanges?: boolean): void | string[];
 	////////// ============= //////////
 	////////// Cache Forking //////////
 	////////// ============= //////////
@@ -313,7 +313,7 @@ export declare class JSONAPICache implements Cache {
 	*
 	* ```ts
 	* interface Change {
-	*  identifier: StableRecordIdentifier | StableDocumentIdentifier;
+	*  identifier: ResourceKey | RequestKey;
 	*  op: 'upsert' | 'remove';
 	*  patch?: unknown;
 	* }
@@ -363,7 +363,7 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource Lifecycle
 	* @public
 	*/
-	clientDidCreate(identifier: StableRecordIdentifier, options?: Record<string, Value>): Record<string, unknown>;
+	clientDidCreate(identifier: ResourceKey, options?: Record<string, Value>): Record<string, unknown>;
 	/**
 	* [LIFECYCLE] Signals to the cache that a resource
 	* will be part of a save transaction.
@@ -371,7 +371,7 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource Lifecycle
 	* @public
 	*/
-	willCommit(identifier: StableRecordIdentifier): void;
+	willCommit(identifier: ResourceKey, _context: RequestContext | null): void;
 	/**
 	* [LIFECYCLE] Signals to the cache that a resource
 	* was successfully updated as part of a save transaction.
@@ -379,7 +379,7 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource Lifecycle
 	* @public
 	*/
-	didCommit(committedIdentifier: StableRecordIdentifier, result: StructuredDataDocument<SingleResourceDocument>): SingleResourceDataDocument;
+	didCommit(committedIdentifier: ResourceKey, result: StructuredDataDocument<SingleResourceDocument> | null): SingleResourceDataDocument;
 	/**
 	* [LIFECYCLE] Signals to the cache that a resource
 	* was update via a save transaction failed.
@@ -387,7 +387,7 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource Lifecycle
 	* @public
 	*/
-	commitWasRejected(identifier: StableRecordIdentifier, errors?: ApiError[]): void;
+	commitWasRejected(identifier: ResourceKey, errors?: ApiError[]): void;
 	/**
 	* [LIFECYCLE] Signals to the cache that all data for a resource
 	* should be cleared.
@@ -397,7 +397,7 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource Lifecycle
 	* @public
 	*/
-	unloadRecord(identifier: StableRecordIdentifier): void;
+	unloadRecord(identifier: ResourceKey): void;
 	////////// ============= //////////
 	////////// Resource Data //////////
 	////////// ============= //////////
@@ -408,14 +408,14 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource Data
 	* @public
 	*/
-	getAttr(identifier: StableRecordIdentifier, attr: string | string[]): Value | undefined;
+	getAttr(identifier: ResourceKey, attr: string | string[]): Value | undefined;
 	/**
 	* Retrieve the remote data for an attribute from the cache
 	*
 	* @category Resource Data
 	* @public
 	*/
-	getRemoteAttr(identifier: StableRecordIdentifier, attr: string | string[]): Value | undefined;
+	getRemoteAttr(identifier: ResourceKey, attr: string | string[]): Value | undefined;
 	/**
 	* Mutate the data for an attribute in the cache
 	*
@@ -424,7 +424,7 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource Data
 	* @public
 	*/
-	setAttr(identifier: StableRecordIdentifier, attr: string | string[], value: Value): void;
+	setAttr(identifier: ResourceKey, attr: string | string[], value: Value): void;
 	/**
 	* Query the cache for the changed attributes of a resource.
 	*
@@ -432,14 +432,14 @@ export declare class JSONAPICache implements Cache {
 	* @public
 	* @return `{ '<field>': ['<old>', '<new>'] }`
 	*/
-	changedAttrs(identifier: StableRecordIdentifier): ChangedAttributesHash;
+	changedAttrs(identifier: ResourceKey): ChangedAttributesHash;
 	/**
 	* Query the cache for whether any mutated attributes exist
 	*
 	* @category Resource Data
 	* @public
 	*/
-	hasChangedAttrs(identifier: StableRecordIdentifier): boolean;
+	hasChangedAttrs(identifier: ResourceKey): boolean;
 	/**
 	* Tell the cache to discard any uncommitted mutations to attributes
 	*
@@ -449,7 +449,7 @@ export declare class JSONAPICache implements Cache {
 	* @public
 	* @return the names of fields that were restored
 	*/
-	rollbackAttrs(identifier: StableRecordIdentifier): string[];
+	rollbackAttrs(identifier: ResourceKey): string[];
 	/**
 	* Query the cache for the changes to relationships of a resource.
 	*
@@ -459,30 +459,30 @@ export declare class JSONAPICache implements Cache {
 	* type RelationshipDiff =
 	| {
 	kind: 'collection';
-	remoteState: StableRecordIdentifier[];
-	additions: Set<StableRecordIdentifier>;
-	removals: Set<StableRecordIdentifier>;
-	localState: StableRecordIdentifier[];
+	remoteState: ResourceKey[];
+	additions: Set<ResourceKey>;
+	removals: Set<ResourceKey>;
+	localState: ResourceKey[];
 	reordered: boolean;
 	}
 	| {
 	kind: 'resource';
-	remoteState: StableRecordIdentifier | null;
-	localState: StableRecordIdentifier | null;
+	remoteState: ResourceKey | null;
+	localState: ResourceKey | null;
 	};
 	```
 	*
 	* @category Resource Data
 	* @public
 	*/
-	changedRelationships(identifier: StableRecordIdentifier): Map<string, RelationshipDiff>;
+	changedRelationships(identifier: ResourceKey): Map<string, RelationshipDiff>;
 	/**
 	* Query the cache for whether any mutated relationships exist
 	*
 	* @category Resource Data
 	* @public
 	*/
-	hasChangedRelationships(identifier: StableRecordIdentifier): boolean;
+	hasChangedRelationships(identifier: ResourceKey): boolean;
 	/**
 	* Tell the cache to discard any uncommitted mutations to relationships.
 	*
@@ -494,7 +494,7 @@ export declare class JSONAPICache implements Cache {
 	* @public
 	* @return the names of relationships that were restored
 	*/
-	rollbackRelationships(identifier: StableRecordIdentifier): string[];
+	rollbackRelationships(identifier: ResourceKey): string[];
 	/**
 	* Query the cache for the current state of a relationship property
 	*
@@ -502,7 +502,7 @@ export declare class JSONAPICache implements Cache {
 	* @public
 	* @return resource relationship object
 	*/
-	getRelationship(identifier: StableRecordIdentifier, field: string): ResourceRelationship | CollectionRelationship;
+	getRelationship(identifier: ResourceKey, field: string): ResourceRelationship | CollectionRelationship;
 	/**
 	* Query the cache for the remote state of a relationship property
 	*
@@ -510,7 +510,7 @@ export declare class JSONAPICache implements Cache {
 	* @public
 	* @return resource relationship object
 	*/
-	getRemoteRelationship(identifier: StableRecordIdentifier, field: string): ResourceRelationship | CollectionRelationship;
+	getRemoteRelationship(identifier: ResourceKey, field: string): ResourceRelationship | CollectionRelationship;
 	////////// ============== //////////
 	////////// Resource State //////////
 	////////// ============== //////////
@@ -523,21 +523,21 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource State
 	* @public
 	*/
-	setIsDeleted(identifier: StableRecordIdentifier, isDeleted: boolean): void;
+	setIsDeleted(identifier: ResourceKey, isDeleted: boolean): void;
 	/**
 	* Query the cache for any validation errors applicable to the given resource.
 	*
 	* @category Resource State
 	* @public
 	*/
-	getErrors(identifier: StableRecordIdentifier): ApiError[];
+	getErrors(identifier: ResourceKey): ApiError[];
 	/**
 	* Query the cache for whether a given resource has any available data
 	*
 	* @category Resource State
 	* @public
 	*/
-	isEmpty(identifier: StableRecordIdentifier): boolean;
+	isEmpty(identifier: ResourceKey): boolean;
 	/**
 	* Query the cache for whether a given resource was created locally and not
 	* yet persisted.
@@ -545,7 +545,7 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource State
 	* @public
 	*/
-	isNew(identifier: StableRecordIdentifier): boolean;
+	isNew(identifier: ResourceKey): boolean;
 	/**
 	* Query the cache for whether a given resource is marked as deleted (but not
 	* necessarily persisted yet).
@@ -553,7 +553,7 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource State
 	* @public
 	*/
-	isDeleted(identifier: StableRecordIdentifier): boolean;
+	isDeleted(identifier: ResourceKey): boolean;
 	/**
 	* Query the cache for whether a given resource has been deleted and that deletion
 	* has also been persisted.
@@ -561,26 +561,26 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource State
 	* @public
 	*/
-	isDeletionCommitted(identifier: StableRecordIdentifier): boolean;
+	isDeletionCommitted(identifier: ResourceKey): boolean;
 	/**
 	* Private method used to populate an entry for the identifier
 	*
 	* @internal
 	*/
-	_createCache(identifier: StableRecordIdentifier): CachedResource;
+	_createCache(identifier: ResourceKey): CachedResource;
 	/**
 	* Peek whether we have cached resource data matching the identifier
 	* without asserting if the resource data is missing.
 	*
 	* @internal
 	*/
-	__safePeek(identifier: StableRecordIdentifier, allowDestroyed: boolean): CachedResource | undefined;
+	__safePeek(identifier: ResourceKey, allowDestroyed: boolean): CachedResource | undefined;
 	/**
 	* Peek whether we have cached resource data matching the identifier
 	* Asserts if the resource data is missing.
 	*
 	* @internal
 	*/
-	__peek(identifier: StableRecordIdentifier, allowDestroyed: boolean): CachedResource;
+	__peek(identifier: ResourceKey, allowDestroyed: boolean): CachedResource;
 }
 export {};

package/dist/index.js

@@ -1,5 +1,5 @@
 import { graphFor, peekGraph, isBelongsTo } from '@warp-drive-mirror/core/graph/-private';
-import { logGroup, isStableIdentifier, isDocumentIdentifier } from '@warp-drive-mirror/core/store/-private';
+import { logGroup, isResourceKey, isRequestKey } from '@warp-drive-mirror/core/store/-private';
 import Fuse from 'fuse.js';
 import jsonToAst from 'json-to-ast';
 import { macroCondition, getGlobalConfig } from '@embroider/macros';
@@ -1129,7 +1129,7 @@ class JSONAPICache {
     const included = jsonApiDoc.included;
     let i, length;
     const {
-      identifierCache
+      cacheKeyManager
     } = this._capabilities;
     if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
       validateDocumentFields(this._capabilities.schema, jsonApiDoc);
@@ -1181,21 +1181,21 @@ class JSONAPICache {
     }
     if (included) {
       for (i = 0, length = included.length; i < length; i++) {
-        included[i] = putOne(this, identifierCache, included[i]);
+        included[i] = putOne(this, cacheKeyManager, included[i]);
       }
     }
     if (Array.isArray(jsonApiDoc.data)) {
       length = jsonApiDoc.data.length;
       const identifiers = [];
       for (i = 0; i < length; i++) {
-        identifiers.push(putOne(this, identifierCache, jsonApiDoc.data[i]));
+        identifiers.push(putOne(this, cacheKeyManager, jsonApiDoc.data[i]));
       }
       return this._putDocument(doc, identifiers, included);
     }
     if (jsonApiDoc.data === null) {
       return this._putDocument(doc, null, included);
     }
-    const identifier = putOne(this, identifierCache, jsonApiDoc.data);
+    const identifier = putOne(this, cacheKeyManager, jsonApiDoc.data);
     return this._putDocument(doc, identifier, included);
   }
 
@@ -1221,7 +1221,7 @@ class JSONAPICache {
       resourceDocument.included = included;
     }
     const request = doc.request;
-    const identifier = request ? this._capabilities.identifierCache.getOrCreateDocumentIdentifier(request) : null;
+    const identifier = request ? this._capabilities.cacheKeyManager.getOrCreateDocumentIdentifier(request) : null;
     if (identifier) {
       resourceDocument.lid = identifier.lid;
 
@@ -1243,7 +1243,7 @@ class JSONAPICache {
         if (!test) {
           throw new Error(`Expected a parent identifier for a findHasMany request`);
         }
-      })(parentIdentifier && isStableIdentifier(parentIdentifier)) : {};
+      })(parentIdentifier && isResourceKey(parentIdentifier)) : {};
       if (parentField && parentIdentifier) {
         this.__graph.push({
           op: 'updateRelationship',
@@ -1349,7 +1349,7 @@ class JSONAPICache {
    */
 
   peek(identifier) {
-    if ('type' in identifier) {
+    if (isResourceKey(identifier)) {
       const peeked = this.__safePeek(identifier, false);
       if (!peeked) {
         return null;
@@ -1407,7 +1407,7 @@ class JSONAPICache {
    */
 
   peekRemoteState(identifier) {
-    if ('type' in identifier) {
+    if (isResourceKey(identifier)) {
       const peeked = this.__safePeek(identifier, false);
       if (!peeked) {
         return null;
@@ -1548,7 +1548,7 @@ class JSONAPICache {
    *
    * ```ts
    * interface Change {
-   *  identifier: StableRecordIdentifier | StableDocumentIdentifier;
+   *  identifier: ResourceKey | RequestKey;
    *  op: 'upsert' | 'remove';
    *  patch?: unknown;
    * }
@@ -1682,7 +1682,7 @@ class JSONAPICache {
    * @category Resource Lifecycle
    * @public
    */
-  willCommit(identifier) {
+  willCommit(identifier, _context) {
     const cached = this.__peek(identifier, false);
 
     /*
@@ -1738,8 +1738,8 @@ class JSONAPICache {
    * @public
    */
   didCommit(committedIdentifier, result) {
-    const payload = result.content;
-    const operation = result.request.op;
+    const payload = result ? result.content : null;
+    const operation = result ? 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) {
@@ -1761,10 +1761,10 @@ class JSONAPICache {
       })(committedIdentifier.id) : {};
     }
     const {
-      identifierCache
+      cacheKeyManager
     } = this._capabilities;
     const existingId = committedIdentifier.id;
-    const identifier = operation !== 'deleteRecord' && data ? identifierCache.updateRecordIdentifier(committedIdentifier, data) : committedIdentifier;
+    const identifier = operation !== 'deleteRecord' && data ? cacheKeyManager.updateRecordIdentifier(committedIdentifier, data) : committedIdentifier;
     const cached = this.__peek(identifier, false);
     if (cached.isDeleted) {
       this.__graph.push({
@@ -1814,7 +1814,7 @@ class JSONAPICache {
                   if (!inFlightData || !('data' in inFlightData)) {
                     return;
                   }
-                  const actualData = relationshipData ? this._capabilities.identifierCache.getOrCreateRecordIdentifier(relationshipData) : null;
+                  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>'}`);
@@ -1843,7 +1843,7 @@ class JSONAPICache {
     const included = payload && payload.included;
     if (included) {
       for (let i = 0, length = included.length; i < length; i++) {
-        putOne(this, identifierCache, included[i]);
+        putOne(this, cacheKeyManager, included[i]);
       }
     }
     return {
@@ -2281,16 +2281,16 @@ class JSONAPICache {
    * type RelationshipDiff =
      | {
         kind: 'collection';
-        remoteState: StableRecordIdentifier[];
-        additions: Set<StableRecordIdentifier>;
-        removals: Set<StableRecordIdentifier>;
-        localState: StableRecordIdentifier[];
+        remoteState: ResourceKey[];
+        additions: Set<ResourceKey>;
+        removals: Set<ResourceKey>;
+        localState: ResourceKey[];
         reordered: boolean;
        }
      | {
         kind: 'resource';
-        remoteState: StableRecordIdentifier | null;
-        localState: StableRecordIdentifier | null;
+        remoteState: ResourceKey | null;
+        localState: ResourceKey | null;
       };
       ```
    *
@@ -3080,8 +3080,8 @@ function cacheUpsert(cache, identifier, data, calculateChanges) {
   return changedKeys?.size ? Array.from(changedKeys) : undefined;
 }
 function patchCache(Cache, op) {
-  const isRecord = isStableIdentifier(op.record);
-  const isDocument = !isRecord && isDocumentIdentifier(op.record);
+  const isRecord = isResourceKey(op.record);
+  const isDocument = !isRecord && isRequestKey(op.record);
   macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
     if (!test) {
       throw new Error(`Expected Cache.patch op.record to be a record or document identifier`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warp-drive-mirror/json-api",
-  "version": "5.7.0-alpha.14",
+  "version": "5.7.0-alpha.16",
   "description": "A {JSON:API} Cache Implementation for WarpDrive",
   "keywords": [
     "ember-addon"
@@ -32,7 +32,7 @@
     }
   },
   "peerDependencies": {
-    "@warp-drive-mirror/core": "5.7.0-alpha.14"
+    "@warp-drive-mirror/core": "5.7.0-alpha.16"
   },
   "dependencies": {
     "@embroider/macros": "^1.16.12",
@@ -44,8 +44,8 @@
     "@babel/plugin-transform-typescript": "^7.27.0",
     "@babel/preset-typescript": "^7.27.0",
     "@types/json-to-ast": "^2.1.4",
-    "@warp-drive/internal-config": "5.7.0-alpha.14",
-    "@warp-drive-mirror/core": "5.7.0-alpha.14",
+    "@warp-drive/internal-config": "5.7.0-alpha.16",
+    "@warp-drive-mirror/core": "5.7.0-alpha.16",
     "decorator-transforms": "^2.3.0",
     "expect-type": "^1.2.1",
     "typescript": "^5.8.3",