@warp-drive/core 5.7.0-alpha.2 → 5.7.0-alpha.21

package/declarations/types/cache/operations.d.ts

@@ -1,85 +1,168 @@
-import type { StableDocumentIdentifier, StableExistingRecordIdentifier, StableRecordIdentifier } from "../identifier.js";
+import type { PersistedResourceKey, RequestKey, ResourceKey } from "../identifier.js";
 import type { Value } from "../json/raw.js";
 import type { ExistingResourceObject } from "../spec/json-api-raw.js";
 import type { Relationship } from "./relationship.js";
+/**
+* All operations are objects with at least one property,
+* `op` which contains a string with the name of the operation
+* to perform.
+*/
 export interface Op {
+	/**
+	* The name of the {@link Op | operation}
+	*/
 	op: string;
 }
-// Occasionally the IdentifierCache
-// discovers that two previously thought
-// to be distinct Identifiers refer to
-// the same ResourceBlob. This Operation
-// will be performed giving the Cache the
-// change to cleanup and merge internal
-// state as desired when this discovery
-// is made.
+/**
+* Occasionally the Store discovers that two previously
+* thought to be distinct resources refer to the same resource.
+*
+* This operation will be performed, giving the Cache the chance
+* to cleanup and merge internal state as desired when this discovery
+* is made.
+*/
 export interface MergeOperation extends Op {
 	op: "mergeIdentifiers";
-	// existing
-	record: StableRecordIdentifier;
-	// new
-	value: StableRecordIdentifier;
+	/**
+	* The stale {@link ResourceKey | ResourceKey} that
+	* the cache should eliminate in favor of {@link MergeOperation.value | value}
+	*/
+	record: ResourceKey;
+	/**
+	* The kept {@link ResourceKey | ResourceKey} that
+	* the cache should also keep and merge {@link MergeOperation.record | record} into.
+	*/
+	value: ResourceKey;
 }
+/**
+* Removes a document and its associated request from
+* the cache.
+*/
 export interface RemoveDocumentOperation extends Op {
 	op: "remove";
-	record: StableDocumentIdentifier;
+	/**
+	* The cache key for the request
+	*/
+	record: RequestKey;
 }
+/**
+* Removes a resource from the cache. This is treated
+* as if a remote deletion has occurred, and all references
+* to the resource should be eliminated.
+*/
 export interface RemoveResourceOperation extends Op {
 	op: "remove";
-	record: StableExistingRecordIdentifier;
+	/**
+	* The cache key for the resource
+	*/
+	record: PersistedResourceKey;
 }
+/**
+* Adds a resource to the cache.
+*/
 export interface AddResourceOperation extends Op {
 	op: "add";
-	record: StableExistingRecordIdentifier;
+	/**
+	* The cache key for the resource
+	*/
+	record: PersistedResourceKey;
+	/**
+	* The data for the resource
+	*/
 	value: ExistingResourceObject;
 }
+/**
+* Upserts (merges) new state for a resource
+*/
 export interface UpdateResourceOperation extends Op {
 	op: "update";
-	record: StableExistingRecordIdentifier;
+	record: PersistedResourceKey;
 	value: ExistingResourceObject;
 }
+/**
+* Replaces the state of a field with a new state
+*/
 export interface UpdateResourceFieldOperation extends Op {
 	op: "update";
-	record: StableExistingRecordIdentifier;
+	record: PersistedResourceKey;
 	field: string;
 	value: Value;
 }
+/**
+* Replaces the state of a relationship with a new state
+*/
 export interface UpdateResourceRelationshipOperation extends Op {
 	op: "update";
-	record: StableExistingRecordIdentifier;
+	record: PersistedResourceKey;
 	field: string;
-	value: Relationship<StableExistingRecordIdentifier>;
+	value: Relationship<PersistedResourceKey>;
 }
+/**
+* Adds a resource to a request document, optionally
+* at a specific index. This can be used to update the
+* result of a request.
+*/
 export interface AddToDocumentOperation extends Op {
 	op: "add";
-	record: StableDocumentIdentifier;
+	record: RequestKey;
 	field: "data" | "included";
-	value: StableExistingRecordIdentifier | StableExistingRecordIdentifier[];
+	value: PersistedResourceKey | PersistedResourceKey[];
 	index?: number;
 }
+/**
+* Adds the specified ResourceKeys to a relationship
+*/
 export interface AddToResourceRelationshipOperation extends Op {
 	op: "add";
-	record: StableExistingRecordIdentifier;
+	record: PersistedResourceKey;
 	field: string;
-	value: StableExistingRecordIdentifier | StableExistingRecordIdentifier[];
+	value: PersistedResourceKey | PersistedResourceKey[];
 	index?: number;
 }
+/**
+* Removes the specified ResourceKeys from a relationship
+*/
 export interface RemoveFromResourceRelationshipOperation extends Op {
 	op: "remove";
-	record: StableExistingRecordIdentifier;
+	record: PersistedResourceKey;
 	field: string;
-	value: StableExistingRecordIdentifier | StableExistingRecordIdentifier[];
+	value: PersistedResourceKey | PersistedResourceKey[];
 	index?: number;
 }
+/**
+* Removes a resource from a request document, optionally
+* at a specific index. This can be used to update the
+* result of a request.
+*/
 export interface RemoveFromDocumentOperation extends Op {
 	op: "remove";
-	record: StableDocumentIdentifier;
+	record: RequestKey;
 	field: "data" | "included";
-	value: StableExistingRecordIdentifier | StableExistingRecordIdentifier[];
+	value: PersistedResourceKey | PersistedResourceKey[];
 	index?: number;
 }
-// An Operation is an action that updates
-// the remote state of the Cache in some
-// manner. Additional Operations will be
-// added in the future.
+/**
+* {@link Cache} Operations perform updates to the
+* Cache's "remote" (or clean) state to reflect external
+* changes.
+*
+* Usually operations represent the result of a {@link WebSocket} or
+* {@link EventSource | ServerEvent} message, though they can also be used to carefully
+* patch the state of the cache with information known by the
+* application or developer.
+*
+* Operations are applied via {@link Cache.patch}.
+*
+* See also:
+* - {@link MergeOperation}
+* - {@link RemoveResourceOperation}
+* - {@link RemoveDocumentOperation}
+* - {@link AddResourceOperation}
+* - {@link UpdateResourceOperation}
+* - {@link UpdateResourceFieldOperation}
+* - {@link AddToResourceRelationshipOperation}
+* - {@link RemoveFromResourceRelationshipOperation}
+* - {@link AddToDocumentOperation}
+* - {@link RemoveFromDocumentOperation}
+*/
 export type Operation = MergeOperation | RemoveResourceOperation | RemoveDocumentOperation | AddResourceOperation | UpdateResourceOperation | UpdateResourceFieldOperation | AddToResourceRelationshipOperation | RemoveFromResourceRelationshipOperation | AddToDocumentOperation | RemoveFromDocumentOperation;

package/declarations/types/cache/relationship.d.ts

@@ -1,16 +1,16 @@
-import type { StableRecordIdentifier } from "../identifier.js";
+import type { ResourceKey } from "../identifier.js";
 import type { Links, Meta, PaginationLinks } from "../spec/json-api-raw.js";
 // we request that it be in the stable form already.
-export interface ResourceRelationship<T = StableRecordIdentifier> {
+export interface ResourceRelationship<T = ResourceKey> {
 	data?: T | null;
 	meta?: Meta;
 	links?: Links;
 }
 // Note: in v1 data could be a ResourceIdentifier, now
 // we request that it be in the stable form already.
-export interface CollectionRelationship<T = StableRecordIdentifier> {
+export interface CollectionRelationship<T = ResourceKey> {
 	data?: T[];
 	meta?: Meta;
 	links?: PaginationLinks;
 }
-export type Relationship<T = StableRecordIdentifier> = ResourceRelationship<T> | CollectionRelationship<T>;
+export type Relationship<T = ResourceKey> = ResourceRelationship<T> | CollectionRelationship<T>;

package/declarations/types/cache.d.ts

@@ -3,7 +3,7 @@ import type { Change } from "./cache/change.js";
 import type { Mutation } from "./cache/mutations.js";
 import type { Operation } from "./cache/operations.js";
 import type { CollectionRelationship, ResourceRelationship } from "./cache/relationship.js";
-import type { StableDocumentIdentifier, StableRecordIdentifier } from "./identifier.js";
+import type { RequestKey, ResourceKey } from "./identifier.js";
 import type { Value } from "./json/raw.js";
 import type { TypeFromInstanceOrString } from "./record.js";
 import type { RequestContext, StructuredDataDocument, StructuredDocument } from "./request.js";
@@ -13,20 +13,19 @@ import type { ApiError } from "./spec/error.js";
 * A hash of changed attributes with the key being the attribute name and the value being an
 * array of `[oldValue, newValue]`.
 *
-* @internal
 */
 export type ChangedAttributesHash = Record<string, [Value | undefined, Value]>;
 export 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;
 };
 /**
 * The interface for WarpDrive Caches.
@@ -34,16 +33,13 @@ export type RelationshipDiff = {
 * A Cache handles in-memory storage of Document and Resource
 * data.
 *
-* @class (Interface) Cache
 * @public
 */
 export interface Cache {
 	/**
 	* The Cache Version that this implementation implements.
 	*
-	* @type {'2'}
 	* @public
-	* @property version
 	*/
 	version: "2";
 	// Cache Management
@@ -65,8 +61,6 @@ export interface Cache {
 	* a `content` member and therefor must not assume the existence
 	* of `request` and `response` on the document.
 	*
-	* @param {StructuredDocument} doc
-	* @return {ResourceDocument}
 	* @public
 	*/
 	put<T>(doc: StructuredDocument<T> | {
@@ -77,15 +71,12 @@ export interface Cache {
 	* by merging new information into the existing state.
 	*
 	* @public
-	* @param {Operation | Operation[]} op the operation(s) to perform
-	* @return {void}
+	* @param op the operation(s) to perform
 	*/
 	patch(op: Operation | Operation[]): void;
 	/**
 	* Update the "local" or "current" (unpersisted) state of the Cache
 	*
-	* @param {Mutation} mutation
-	* @return {void}
 	* @public
 	*/
 	mutate(mutation: Mutation): void;
@@ -117,11 +108,10 @@ export interface Cache {
 	* notifications for relational data.
 	*
 	* @public
-	* @param {StableRecordIdentifier | StableDocumentIdentifier} identifier
-	* @return {ResourceDocument | ResourceBlob | null} the known resource data
+	* @return the known resource data, if any
 	*/
-	peek<T = unknown>(identifier: StableRecordIdentifier<TypeFromInstanceOrString<T>>): T | null;
-	peek(identifier: StableDocumentIdentifier): ResourceDocument | null;
+	peek<T = unknown>(cacheKey: ResourceKey<TypeFromInstanceOrString<T>>): T | null;
+	peek(cacheKey: RequestKey): ResourceDocument | null;
 	/**
 	* Peek remote resource data from the Cache.
 	*
@@ -152,11 +142,10 @@ export interface Cache {
 	* notifications for relational data.
 	*
 	* @public
-	* @param {StableRecordIdentifier | StableDocumentIdentifier} identifier
-	* @return {ResourceDocument | ResourceBlob | null} the known resource data
+	* @return the known data, if any
 	*/
-	peekRemoteState<T = unknown>(identifier: StableRecordIdentifier<TypeFromInstanceOrString<T>>): T | null;
-	peekRemoteState(identifier: StableDocumentIdentifier): ResourceDocument | null;
+	peekRemoteState<T = unknown>(cacheKey: ResourceKey<TypeFromInstanceOrString<T>>): T | null;
+	peekRemoteState(cacheKey: RequestKey): ResourceDocument | null;
 	/**
 	* Peek the Cache for the existing request data associated with
 	* a cacheable request
@@ -165,21 +154,16 @@ export interface Cache {
 	* that it will return the the request, response, and content
 	* whereas `peek` will return just the `content`.
 	*
-	* @param {StableDocumentIdentifier}
-	* @return {StructuredDocument<ResourceDocument> | null}
 	* @public
 	*/
-	peekRequest(identifier: StableDocumentIdentifier): StructuredDocument<ResourceDocument> | null;
+	peekRequest(cacheKey: RequestKey): StructuredDocument<ResourceDocument> | null;
 	/**
-	* Push resource data from a remote source into the cache for this identifier
+	* Push resource data from a remote source into the cache for this ResourceKey
 	*
 	* @public
-	* @param identifier
-	* @param data
-	* @param hasRecord
-	* @return {void | string[]} if `hasRecord` is true then calculated key changes should be returned
+	* @return if `hasRecord` is true then calculated key changes should be returned
 	*/
-	upsert(identifier: StableRecordIdentifier, data: ResourceBlob, hasRecord: boolean): void | string[];
+	upsert(cacheKey: ResourceKey, data: ResourceBlob, hasRecord: boolean): void | string[];
 	// Cache Forking Support
 	// =====================
 	/**
@@ -190,7 +174,6 @@ export interface Cache {
 	* utilize this method to fork the cache.
 	*
 	* @public
-	* @return {Promise<Cache>}
 	*/
 	fork(): Promise<Cache>;
 	/**
@@ -200,9 +183,6 @@ export interface Cache {
 	* preferring instead to merge at the Store level, which will
 	* utilize this method to merge the caches.
 	*
-	* @param {Cache} cache
-	* @public
-	* @return {Promise<void>}
 	*/
 	merge(cache: Cache): Promise<void>;
 	/**
@@ -214,7 +194,7 @@ export interface Cache {
 	* `Change` entry in the returned array.
 	*
 	* A `Change` is described by an object containing up to
-	* three properties: (1) the `identifier` of the entity that
+	* three properties: (1) the `CacheKey` of the entity that
 	* changed; (2) the `op` code of that change being one of
 	* `upsert` or `remove`, and if the op is `upsert` a `patch`
 	* containing the data to merge into the cache for the given
@@ -229,7 +209,7 @@ export interface Cache {
 	*
 	* ```ts
 	* interface Change {
-	*  identifier: StableRecordIdentifier | StableDocumentIdentifier;
+	*  key: ResourceKey | RequestKey;
 	*  op: 'upsert' | 'remove';
 	*  patch?: unknown;
 	* }
@@ -261,8 +241,6 @@ export interface Cache {
 	* behavior supports optimizing pre/fetching of data for route transitions
 	* via data-only SSR modes.
 	*
-	* @param {ReadableStream} stream
-	* @return {Promise<void>}
 	* @public
 	*/
 	hydrate(stream: ReadableStream<unknown>): Promise<void>;
@@ -275,37 +253,31 @@ export interface Cache {
 	* process. This return value behavior is deprecated.
 	*
 	* @public
-	* @param identifier
-	* @param createArgs
 	*/
-	clientDidCreate(identifier: StableRecordIdentifier, createArgs?: Record<string, unknown>): Record<string, unknown>;
+	clientDidCreate(cacheKey: ResourceKey, createArgs?: Record<string, unknown>): Record<string, unknown>;
 	/**
 	* [LIFECYCLE] Signals to the cache that a resource
 	* will be part of a save transaction.
 	*
 	* @public
-	* @param identifier
 	*/
-	willCommit(identifier: StableRecordIdentifier, context: RequestContext): void;
+	willCommit(cacheKey: ResourceKey, context: RequestContext | null): void;
 	/**
 	* [LIFECYCLE] Signals to the cache that a resource
 	* was successfully updated as part of a save transaction.
 	*
 	* @public
-	* @param identifier - the primary identifier that was operated on
+	* @param the primary ResourceKey that was operated on
 	* @param data - a document in the cache format containing any updated data
-	* @return {SingleResourceDataDocument}
 	*/
-	didCommit(identifier: StableRecordIdentifier, result: StructuredDataDocument<unknown>): SingleResourceDataDocument;
+	didCommit(cacheKey: ResourceKey, result: StructuredDataDocument<unknown> | null): SingleResourceDataDocument;
 	/**
 	* [LIFECYCLE] Signals to the cache that a resource
 	* was update via a save transaction failed.
 	*
 	* @public
-	* @param identifier
-	* @param errors
 	*/
-	commitWasRejected(identifier: StableRecordIdentifier, errors?: ApiError[]): void;
+	commitWasRejected(cacheKey: ResourceKey, errors?: ApiError[]): void;
 	/**
 	* [LIFECYCLE] Signals to the cache that all data for a resource
 	* should be cleared.
@@ -313,40 +285,30 @@ export interface Cache {
 	* This method is a candidate to become a mutation
 	*
 	* @public
-	* @param identifier
 	*/
-	unloadRecord(identifier: StableRecordIdentifier): void;
+	unloadRecord(cacheKey: ResourceKey): void;
 	// Granular Resource Data APIs
 	// ===========================
 	/**
 	* Retrieve the data for an attribute from the cache
 	*
 	* @public
-	* @param identifier
-	* @param field
-	* @return {unknown}
 	*/
-	getAttr(identifier: StableRecordIdentifier, field: string | string[]): Value | undefined;
+	getAttr(cacheKey: ResourceKey, field: string | string[]): Value | undefined;
 	/**
 	* Retrieve remote state without any local changes for a specific attribute
 	*
 	* @public
-	* @param identifier
-	* @param field
-	* @return {unknown}
 	*/
-	getRemoteAttr(identifier: StableRecordIdentifier, field: string | string[]): Value | undefined;
+	getRemoteAttr(cacheKey: ResourceKey, field: string | string[]): Value | undefined;
 	/**
 	* Mutate the data for an attribute in the cache
 	*
 	* This method is a candidate to become a mutation
 	*
 	* @public
-	* @param identifier
-	* @param field
-	* @param value
 	*/
-	setAttr(identifier: StableRecordIdentifier, field: string | string[], value: Value): void;
+	setAttr(cacheKey: ResourceKey, field: string | string[], value: Value): void;
 	/**
 	* Query the cache for the changed attributes of a resource.
 	*
@@ -357,28 +319,23 @@ export interface Cache {
 	* ```
 	*
 	* @public
-	* @param identifier
-	* @return {Record<string, [unknown, unknown]>} `{ <field>: [<old>, <new>] }`
 	*/
-	changedAttrs(identifier: StableRecordIdentifier): ChangedAttributesHash;
+	changedAttrs(cacheKey: ResourceKey): ChangedAttributesHash;
 	/**
 	* Query the cache for whether any mutated attributes exist
 	*
 	* @public
-	* @param identifier
-	* @return {Boolean}
 	*/
-	hasChangedAttrs(identifier: StableRecordIdentifier): boolean;
+	hasChangedAttrs(cacheKey: ResourceKey): boolean;
 	/**
 	* Tell the cache to discard any uncommitted mutations to attributes
 	*
 	* This method is a candidate to become a mutation
 	*
 	* @public
-	* @param identifier
-	* @return {String[]} the names of fields that were restored
+	* @return the names of fields that were restored
 	*/
-	rollbackAttrs(identifier: StableRecordIdentifier): string[];
+	rollbackAttrs(cacheKey: ResourceKey): string[];
 	/**
 	* Query the cache for the changes to relationships of a resource.
 	*
@@ -388,32 +345,28 @@ export interface 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;
 	};
 	```
 	*
 	* @public
-	* @param {StableRecordIdentifier} identifier
-	* @return {Map<string, RelationshipDiff>}
 	*/
-	changedRelationships(identifier: StableRecordIdentifier): Map<string, RelationshipDiff>;
+	changedRelationships(cacheKey: ResourceKey): Map<string, RelationshipDiff>;
 	/**
 	* Query the cache for whether any mutated attributes exist
 	*
 	* @public
-	* @param {StableRecordIdentifier} identifier
-	* @return {Boolean}
 	*/
-	hasChangedRelationships(identifier: StableRecordIdentifier): boolean;
+	hasChangedRelationships(cacheKey: ResourceKey): boolean;
 	/**
 	* Tell the cache to discard any uncommitted mutations to relationships.
 	*
@@ -422,28 +375,23 @@ export interface Cache {
 	* This method is a candidate to become a mutation
 	*
 	* @public
-	* @param {StableRecordIdentifier} identifier
-	* @return {String[]} the names of relationships that were restored
+	* @return the names of relationships that were restored
 	*/
-	rollbackRelationships(identifier: StableRecordIdentifier): string[];
+	rollbackRelationships(cacheKey: ResourceKey): string[];
 	/**
 	* Query the cache for the current state of a relationship property
 	*
 	* @public
-	* @param {StableRecordIdentifier} identifier
-	* @param {String} field
 	* @return resource relationship object
 	*/
-	getRelationship(identifier: StableRecordIdentifier, field: string, isCollection?: boolean): ResourceRelationship | CollectionRelationship;
+	getRelationship(cacheKey: ResourceKey, field: string, isCollection?: boolean): ResourceRelationship | CollectionRelationship;
 	/**
 	* Query the cache for the server state of a relationship property without any local changes
 	*
 	* @public
-	* @param {StableRecordIdentifier} identifier
-	* @param {String} field
 	* @return resource relationship object
 	*/
-	getRemoteRelationship(identifier: StableRecordIdentifier, field: string, isCollection?: boolean): ResourceRelationship | CollectionRelationship;
+	getRemoteRelationship(cacheKey: ResourceKey, field: string, isCollection?: boolean): ResourceRelationship | CollectionRelationship;
 	// Resource State
 	// ===============
 	/**
@@ -453,49 +401,39 @@ export interface Cache {
 	* This method is a candidate to become a mutation
 	*
 	* @public
-	* @param identifier
-	* @param {Boolean} isDeleted
 	*/
-	setIsDeleted(identifier: StableRecordIdentifier, isDeleted: boolean): void;
+	setIsDeleted(cacheKey: ResourceKey, isDeleted: boolean): void;
 	/**
 	* Query the cache for any validation errors applicable to the given resource.
 	*
 	* @public
 	*/
-	getErrors(identifier: StableRecordIdentifier): ApiError[];
+	getErrors(cacheKey: ResourceKey): ApiError[];
 	/**
 	* Query the cache for whether a given resource has any available data
 	*
 	* @public
-	* @param identifier
-	* @return {Boolean}
 	*/
-	isEmpty(identifier: StableRecordIdentifier): boolean;
+	isEmpty(cacheKey: ResourceKey): boolean;
 	/**
 	* Query the cache for whether a given resource was created locally and not
 	* yet persisted.
 	*
 	* @public
-	* @param identifier
-	* @return {Boolean}
 	*/
-	isNew(identifier: StableRecordIdentifier): boolean;
+	isNew(cacheKey: ResourceKey): boolean;
 	/**
 	* Query the cache for whether a given resource is marked as deleted (but not
 	* necessarily persisted yet).
 	*
 	* @public
-	* @param identifier
-	* @return {Boolean}
 	*/
-	isDeleted(identifier: StableRecordIdentifier): boolean;
+	isDeleted(cacheKey: ResourceKey): boolean;
 	/**
 	* Query the cache for whether a given resource has been deleted and that deletion
 	* has also been persisted.
 	*
 	* @public
-	* @param identifier
-	* @return {Boolean}
 	*/
-	isDeletionCommitted(identifier: StableRecordIdentifier): boolean;
+	isDeletionCommitted(cacheKey: ResourceKey): boolean;
 }