@warp-drive-mirror/json-api 5.6.0-beta.1 → 5.6.0-beta.3

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

@@ -1,34 +1,15 @@
-import type { Graph } from "@warp-drive-mirror/core/graph/-private";
 import type { CacheCapabilitiesManager } from "@warp-drive-mirror/core/types";
 import type { Cache, ChangedAttributesHash, RelationshipDiff } from "@warp-drive-mirror/core/types/cache";
 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 { 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";
-interface CachedResource {
-	id: string | null;
-	remoteAttrs: Record<string, Value | undefined> | null;
-	localAttrs: Record<string, Value | undefined> | null;
-	defaultAttrs: Record<string, Value | undefined> | null;
-	inflightAttrs: Record<string, Value | undefined> | null;
-	changes: Record<string, [Value | undefined, Value]> | null;
-	errors: ApiError[] | null;
-	isNew: boolean;
-	isDeleted: boolean;
-	isDeletionCommitted: boolean;
-	/**
-	* debugging only
-	*
-	* @internal
-	*/
-	inflightRelationships?: Record<string, unknown> | null;
-}
 /**
 * ### JSONAPICache
 *
@@ -128,20 +109,7 @@ export declare class JSONAPICache implements Cache {
 	* @public
 	*/
 	version: "2";
-	/** @internal */
-	_capabilities: CacheCapabilitiesManager;
-	/** @internal */
-	__cache: Map<StableRecordIdentifier, CachedResource>;
-	/** @internal */
-	__destroyedCache: Map<StableRecordIdentifier, CachedResource>;
-	/** @internal */
-	__documents: Map<string, StructuredDocument<ResourceDocument>>;
-	/** @internal */
-	__graph: Graph;
 	constructor(capabilities: CacheCapabilitiesManager);
-	////////// ================ //////////
-	////////// Cache Management //////////
-	////////// ================ //////////
 	/**
 	* Cache the response to a request
 	*
@@ -183,11 +151,6 @@ export declare class JSONAPICache implements Cache {
 	put<T extends CollectionResourceDocument>(doc: StructuredDataDocument<T>): CollectionResourceDataDocument;
 	put<T extends ResourceErrorDocument>(doc: StructuredErrorDocument<T>): ResourceErrorDocument;
 	put<T extends ResourceMetaDocument>(doc: StructuredDataDocument<T>): ResourceMetaDocument;
-	/** @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;
 	/**
 	* Update the "remote" or "canonical" (persisted) state of the Cache
 	* by merging new information into the existing state.
@@ -234,16 +197,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 +218,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,10 +226,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[];
-	////////// ============= //////////
-	////////// Cache Forking //////////
-	////////// ============= //////////
+	upsert(identifier: ResourceKey, data: ExistingResourceObject, calculateChanges?: boolean): void | string[];
 	/**
 	* Create a fork of the cache from the current state.
 	*
@@ -275,7 +235,7 @@ export declare class JSONAPICache implements Cache {
 	* utilize this method to fork the cache.
 	*
 	* @category Cache Forking
-	* @internal
+	* @private
 	*/
 	fork(): Promise<Cache>;
 	/**
@@ -286,7 +246,7 @@ export declare class JSONAPICache implements Cache {
 	* utilize this method to merge the caches.
 	*
 	* @category Cache Forking
-	* @internal
+	* @private
 	*/
 	merge(_cache: Cache): Promise<void>;
 	/**
@@ -313,26 +273,23 @@ export declare class JSONAPICache implements Cache {
 	*
 	* ```ts
 	* interface Change {
-	*  identifier: StableRecordIdentifier | StableDocumentIdentifier;
+	*  identifier: ResourceKey | RequestKey;
 	*  op: 'upsert' | 'remove';
 	*  patch?: unknown;
 	* }
 	* ```
 	*
 	* @category Cache Forking
-	* @internal
+	* @private
 	*/
 	diff(): Promise<Change[]>;
-	////////// =========== //////////
-	////////// SSR Support //////////
-	////////// =========== //////////
 	/**
 	* Serialize the entire contents of the Cache into a Stream
 	* which may be fed back into a new instance of the same Cache
 	* via `cache.hydrate`.
 	*
 	* @category SSR Support
-	* @internal
+	* @private
 	*/
 	dump(): Promise<ReadableStream<unknown>>;
 	/**
@@ -348,12 +305,9 @@ export declare class JSONAPICache implements Cache {
 	* via data-only SSR modes.
 	*
 	* @category SSR Support
-	* @internal
+	* @private
 	*/
 	hydrate(stream: ReadableStream<unknown>): Promise<void>;
-	////////// ================== //////////
-	////////// Resource Lifecycle //////////
-	////////// ================== //////////
 	/**
 	* [LIFECYCLE] Signal to the cache that a new record has been instantiated on the client
 	*
@@ -363,7 +317,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 +325,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 +333,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 +341,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,10 +351,7 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource Lifecycle
 	* @public
 	*/
-	unloadRecord(identifier: StableRecordIdentifier): void;
-	////////// ============= //////////
-	////////// Resource Data //////////
-	////////// ============= //////////
+	unloadRecord(identifier: ResourceKey): void;
 	/**
 	* Retrieve the data for an attribute from the cache
 	* with local mutations applied.
@@ -408,14 +359,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 +375,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 +383,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 +400,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 +410,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 +445,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 +453,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,10 +461,7 @@ export declare class JSONAPICache implements Cache {
 	* @public
 	* @return resource relationship object
 	*/
-	getRemoteRelationship(identifier: StableRecordIdentifier, field: string): ResourceRelationship | CollectionRelationship;
-	////////// ============== //////////
-	////////// Resource State //////////
-	////////// ============== //////////
+	getRemoteRelationship(identifier: ResourceKey, field: string): ResourceRelationship | CollectionRelationship;
 	/**
 	* Update the cache state for the given resource to be marked
 	* as locally deleted, or remove such a mark.
@@ -523,21 +471,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 +493,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 +501,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 +509,5 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource State
 	* @public
 	*/
-	isDeletionCommitted(identifier: StableRecordIdentifier): boolean;
-	/**
-	* Private method used to populate an entry for the identifier
-	*
-	* @internal
-	*/
-	_createCache(identifier: StableRecordIdentifier): 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;
-	/**
-	* Peek whether we have cached resource data matching the identifier
-	* Asserts if the resource data is missing.
-	*
-	* @internal
-	*/
-	__peek(identifier: StableRecordIdentifier, allowDestroyed: boolean): CachedResource;
+	isDeletionCommitted(identifier: ResourceKey): boolean;
 }
-export {};

package/declarations/-private/validator/1.1/7.1_top-level-document-members.d.ts

@@ -1,12 +1 @@
-import type { ResourceDocument } from "@warp-drive-mirror/core/types/spec/document";
-import { type Reporter } from "../utils.js";
-/**
-* Reports issues which violate the JSON:API spec for top-level members.
-*
-* Version: 1.1
-* Section: 7.1
-* Link: https://jsonapi.org/format/#document-top-level
-*
-* @internal
-*/
-export declare function validateTopLevelDocumentMembers(reporter: Reporter, doc: ResourceDocument): void;
+export {};

package/declarations/-private/validator/1.1/7.2_resource-objects.d.ts

@@ -1,13 +1 @@
-import type { ResourceDocument } from "@warp-drive-mirror/core/types/spec/document";
-import { type Reporter } from "../utils.js";
-/**
-* Validates the resource objects in either the `data` or `included` members of
-* JSON:API document.
-*
-* Version: 1.1
-* Section: 7.2
-* Link: https://jsonapi.org/format/#document-resource-objects
-*
-* @internal
-*/
-export declare function validateDocumentResources(reporter: Reporter, doc: ResourceDocument): void;
+export {};

package/declarations/-private/validator/1.1/links.d.ts

@@ -1,23 +1 @@
-import type { ResourceDocument } from "@warp-drive-mirror/core/types/spec/document";
-import type { CollectionResourceRelationship, ResourceObject, SingleResourceRelationship } from "@warp-drive-mirror/core/types/spec/json-api-raw";
-import { type PathLike, type Reporter } from "../utils.js";
-/**
-* Validates the links object in a top-level JSON API document or resource object
-*
-* Version: 1.1
-*
-* Section: 7.1 Top Level
-* Link: https://jsonapi.org/format/#document-top-level
-*
-* Section: 7.2.3 Resource Objects
-* Link: https://jsonapi.org/format/#document-resource-object-links
-*
-* Section: 7.2.2.2 Resource Relationships
-* Link: https://jsonapi.org/format/#document-resource-object-relationships
-*
-* Section: 7.6 Document Links
-* Link: https://jsonapi.org/format/#document-links
-*
-* @internal
-*/
-export declare function validateLinks(reporter: Reporter, doc: ResourceDocument | ResourceObject | SingleResourceRelationship | CollectionResourceRelationship, type: "collection-document" | "resource-document" | "resource" | "resource-relationship" | "collection-relationship", path?: PathLike): void;
+export {};

package/declarations/-private/validator/utils.d.ts

@@ -33,8 +33,6 @@ export declare class Reporter {
 	errors: ErrorReport[];
 	ast: ReturnType<typeof jsonToAst>;
 	jsonStr: string;
-	// TODO @runspired make this configurable to consuming apps before
-	// activating by default
 	strict: {
 		linkage: boolean;
 		unknownType: boolean;

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, assertPrivateCapabilities, 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';
@@ -793,7 +793,7 @@ function validateResourceAttributes(reporter, type, resource, path) {
     const field = getRemoteField(schema, key);
     const actualField = schema.get(key);
     if (!field && actualField) {
-      reporter.warn([...path, key], `Expected the ${actualField.kind} field to not have its own resource data. Likely this field should either not be returned in this payload or the field definition should be updated in the schema.`);
+      reporter.warn([...path, key], `Expected the ${actualField.kind} field "${key}" to not have its own data in the ResourceObject's attributes. Likely this field should either not be returned in this payload or the field definition should be updated in the schema.`);
     } else if (!field) {
       if (key.includes(':')) {
         const extensionName = key.split(':')[0];
@@ -827,7 +827,7 @@ function validateResourceRelationships(reporter, type, resource, path) {
     const field = getRemoteField(schema, key);
     const actualField = schema.get(key);
     if (!field && actualField) {
-      reporter.warn([...path, key], `Expected the ${actualField.kind} field to not have its own resource data. Likely this field should either not be returned in this payload or the field definition should be updated in the schema.`);
+      reporter.warn([...path, key], `Expected the ${actualField.kind} field "${key}" to not have its own data in the ResourceObject's relationships. Likely this field should either not be returned in this payload or the field definition should be updated in the schema.`);
     } else if (!field) {
       if (key.includes(':')) {
         const extensionName = key.split(':')[0];
@@ -927,7 +927,6 @@ function validateResourceDocument(reporter, doc) {
 function isImplicit(relationship) {
   return relationship.definition.isImplicit;
 }
-function upgradeCapabilities(obj) {}
 const EMPTY_ITERATOR = {
   iterator() {
     return {
@@ -1129,7 +1128,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,26 +1180,33 @@ 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);
   }
 
   /** @internal */
 
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
   _putDocument(doc, data, included) {
     // @ts-expect-error narrowing within is just horrible  in TS :/
     const resourceDocument = isErrorDocument(doc) ? fromStructuredError(doc) : fromBaseDocument(doc);
@@ -1221,7 +1227,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 +1249,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',
@@ -1271,7 +1277,7 @@ class JSONAPICache {
           logGroup('cache', 'patch', '<BATCH>', String(op.length) + ' operations', '', '');
         }
       }
-      upgradeCapabilities(this._capabilities);
+      assertPrivateCapabilities(this._capabilities);
       this._capabilities._store._join(() => {
         for (const operation of op) {
           patchCache(this, operation);
@@ -1349,7 +1355,7 @@ class JSONAPICache {
    */
 
   peek(identifier) {
-    if ('type' in identifier) {
+    if (isResourceKey(identifier)) {
       const peeked = this.__safePeek(identifier, false);
       if (!peeked) {
         return null;
@@ -1372,13 +1378,10 @@ class JSONAPICache {
           }
         });
       }
-      upgradeCapabilities(this._capabilities);
+      assertPrivateCapabilities(this._capabilities);
       const store = this._capabilities._store;
-      const attrs = this._capabilities.schema.fields(identifier);
+      const attrs = getCacheFields(this, identifier);
       attrs.forEach((attr, key) => {
-        if (attr.kind === 'alias') {
-          return;
-        }
         if (key in attributes && attributes[key] !== undefined) {
           return;
         }
@@ -1410,7 +1413,7 @@ class JSONAPICache {
    */
 
   peekRemoteState(identifier) {
-    if ('type' in identifier) {
+    if (isResourceKey(identifier)) {
       const peeked = this.__safePeek(identifier, false);
       if (!peeked) {
         return null;
@@ -1433,9 +1436,9 @@ class JSONAPICache {
           }
         });
       }
-      upgradeCapabilities(this._capabilities);
+      assertPrivateCapabilities(this._capabilities);
       const store = this._capabilities._store;
-      const attrs = this._capabilities.schema.fields(identifier);
+      const attrs = getCacheFields(this, identifier);
       attrs.forEach((attr, key) => {
         if (key in attributes && attributes[key] !== undefined) {
           return;
@@ -1483,7 +1486,7 @@ class JSONAPICache {
    * @return if `calculateChanges` is true then calculated key changes should be returned
    */
   upsert(identifier, data, calculateChanges) {
-    upgradeCapabilities(this._capabilities);
+    assertPrivateCapabilities(this._capabilities);
     const store = this._capabilities._store;
     if (!store._cbs) {
       let result = undefined;
@@ -1507,7 +1510,7 @@ class JSONAPICache {
    * utilize this method to fork the cache.
    *
    * @category Cache Forking
-   * @internal
+   * @private
    */
   fork() {
     throw new Error(`Not Implemented`);
@@ -1521,7 +1524,7 @@ class JSONAPICache {
    * utilize this method to merge the caches.
    *
    * @category Cache Forking
-   * @internal
+   * @private
    */
   merge(_cache) {
     throw new Error(`Not Implemented`);
@@ -1551,14 +1554,14 @@ class JSONAPICache {
    *
    * ```ts
    * interface Change {
-   *  identifier: StableRecordIdentifier | StableDocumentIdentifier;
+   *  identifier: ResourceKey | RequestKey;
    *  op: 'upsert' | 'remove';
    *  patch?: unknown;
    * }
    * ```
    *
    * @category Cache Forking
-   * @internal
+   * @private
    */
   diff() {
     throw new Error(`Not Implemented`);
@@ -1574,7 +1577,7 @@ class JSONAPICache {
    * via `cache.hydrate`.
    *
    * @category SSR Support
-   * @internal
+   * @private
    */
   dump() {
     throw new Error(`Not Implemented`);
@@ -1593,7 +1596,7 @@ class JSONAPICache {
    * via data-only SSR modes.
    *
    * @category SSR Support
-   * @internal
+   * @private
    */
   hydrate(stream) {
     throw new Error('Not Implemented');
@@ -1629,8 +1632,7 @@ class JSONAPICache {
     cached.isNew = true;
     const createOptions = {};
     if (options !== undefined) {
-      const storeWrapper = this._capabilities;
-      const fields = storeWrapper.schema.fields(identifier);
+      const fields = getCacheFields(this, identifier);
       const graph = this.__graph;
       const propertyNames = Object.keys(options);
       for (let i = 0; i < propertyNames.length; i++) {
@@ -1686,7 +1688,7 @@ class JSONAPICache {
    * @category Resource Lifecycle
    * @public
    */
-  willCommit(identifier) {
+  willCommit(identifier, _context) {
     const cached = this.__peek(identifier, false);
 
     /*
@@ -1720,7 +1722,7 @@ class JSONAPICache {
     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 = this._capabilities.schema.fields(identifier);
+        const fields = getCacheFields(this, identifier);
         fields.forEach((schema, name) => {
           if (schema.kind === 'belongsTo') {
             if (this.__graph._isDirty(identifier, name)) {
@@ -1742,8 +1744,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) {
@@ -1765,10 +1767,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({
@@ -1790,7 +1792,7 @@ class JSONAPICache {
         throw error;
       }
     }
-    const fields = this._capabilities.schema.fields(identifier);
+    const fields = getCacheFields(this, identifier);
     cached.isNew = false;
     let newCanonicalAttributes;
     if (data) {
@@ -1818,7 +1820,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>'}`);
@@ -1847,7 +1849,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 {
@@ -1997,8 +1999,8 @@ class JSONAPICache {
       } else if (cached.defaultAttrs && attribute in cached.defaultAttrs) {
         return cached.defaultAttrs[attribute];
       } else {
-        const attrSchema = this._capabilities.schema.fields(identifier).get(attribute);
-        upgradeCapabilities(this._capabilities);
+        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);
@@ -2064,8 +2066,8 @@ class JSONAPICache {
       } else if (cached.defaultAttrs && attribute in cached.defaultAttrs) {
         return cached.defaultAttrs[attribute];
       } else {
-        const attrSchema = this._capabilities.schema.fields(identifier).get(attribute);
-        upgradeCapabilities(this._capabilities);
+        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);
@@ -2285,16 +2287,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;
       };
       ```
    *
@@ -2327,7 +2329,7 @@ class JSONAPICache {
    * @return the names of relationships that were restored
    */
   rollbackRelationships(identifier) {
-    upgradeCapabilities(this._capabilities);
+    assertPrivateCapabilities(this._capabilities);
     let result;
     this._capabilities._store._join(() => {
       result = this.__graph.rollback(identifier);
@@ -2719,11 +2721,6 @@ function hasLegacyDefaultValueFn(options) {
   return !!options && typeof options.defaultValue === 'function';
 }
 function getDefaultValue(schema, identifier, store) {
-  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
-    if (!test) {
-      throw new Error(`AliasFields should not be directly accessed from the cache`);
-    }
-  })(schema?.kind !== 'alias') : {};
   const options = schema?.options;
   if (!schema || !options && !schema.type) {
     return;
@@ -2830,6 +2827,7 @@ function recordIsLoaded(cached, filterDeleted = false) {
   return filterDeleted && cached.isDeletionCommitted ? false : !isEmpty;
 }
 function _isLoading(peeked, capabilities, identifier) {
+  assertPrivateCapabilities(capabilities);
   // TODO refactor things such that the cache is not required to know
   // about isLoading
   const req = capabilities._store.getRequestStateService();
@@ -3055,7 +3053,7 @@ function cacheUpsert(cache, identifier, data, calculateChanges) {
     cache._capabilities.notifyChange(identifier, 'identity', null);
     cache._capabilities.notifyChange(identifier, 'state', null);
   }
-  const fields = cache._capabilities.schema.fields(identifier);
+  const fields = getCacheFields(cache, identifier);
 
   // if no cache entry existed, no record exists / property has been accessed
   // and thus we do not need to notify changes to any properties.
@@ -3089,8 +3087,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`);
@@ -3124,7 +3122,7 @@ function patchCache(Cache, op) {
       {
         if (isRecord) {
           if ('field' in op) {
-            const field = Cache._capabilities.schema.fields(op.record).get(op.field);
+            const field = getCacheFields(Cache, op.record).get(op.field);
             macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
               if (!test) {
                 throw new Error(`Expected ${op.field} to be a field on ${op.record.type}`);
@@ -3227,5 +3225,13 @@ function patchCache(Cache, op) {
     }
   }
 }
+function getCacheFields(cache, identifier) {
+  if (cache._capabilities.schema.cacheFields) {
+    return cache._capabilities.schema.cacheFields(identifier);
+  }
+
+  // the model schema service cannot process fields that are not cache fields
+  return cache._capabilities.schema.fields(identifier);
+}
 
 export { JSONAPICache };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warp-drive-mirror/json-api",
-  "version": "5.6.0-beta.1",
+  "version": "5.6.0-beta.3",
   "description": "A {JSON:API} Cache Implementation for WarpDrive",
   "keywords": [
     "ember-addon"
@@ -32,24 +32,24 @@
     }
   },
   "peerDependencies": {
-    "@warp-drive-mirror/core": "5.6.0-beta.1"
+    "@warp-drive-mirror/core": "5.6.0-beta.3"
   },
   "dependencies": {
-    "@embroider/macros": "^1.16.12",
+    "@embroider/macros": "^1.18.1",
     "json-to-ast": "2.1.0",
     "fuse.js": "7.1.0"
   },
   "devDependencies": {
-    "@babel/core": "^7.26.10",
-    "@babel/plugin-transform-typescript": "^7.27.0",
-    "@babel/preset-typescript": "^7.27.0",
+    "@babel/core": "^7.28.3",
+    "@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.6.0-beta.2",
-    "@warp-drive-mirror/core": "5.6.0-beta.1",
+    "@warp-drive/internal-config": "5.6.0-beta.4",
+    "@warp-drive-mirror/core": "5.6.0-beta.3",
     "decorator-transforms": "^2.3.0",
-    "expect-type": "^1.2.1",
-    "typescript": "^5.8.3",
-    "vite": "^7.0.0"
+    "expect-type": "^1.2.2",
+    "typescript": "^5.9.2",
+    "vite": "^7.1.3"
   },
   "volta": {
     "extends": "../../../../../../package.json"