@warp-drive/core 5.6.0-beta.0 → 5.6.0-beta.2

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

@@ -1,7 +1,7 @@
 type UniversalTransientKey = "REQ_ID";
 type UniversalKey = `(transient) ${UniversalTransientKey}` | "RequestMap" | "PromiseCache" | "RequestCache" | "SkipCache" | "EnableHydration" | "WarpDriveRuntimeConfig";
 type TransientKey = "transactionRef" | "configuredGenerationMethod" | "configuredUpdateMethod" | "configuredForgetMethod" | "configuredResetMethod" | "configuredKeyInfoMethod" | "signalHooks";
-type GlobalKey = `(transient) ${TransientKey}` | "AdapterError" | "InvalidError" | "TimeoutError" | "AbortError" | "UnauthorizedError" | "ForbiddenError" | "NotFoundError" | "ConflictError" | "ServerError" | "#{}" | "#[]" | "Signals" | "AvailableShims" | "FAKE_ARR" | "#source" | "#update" | "#notify" | "IS_COLLECTION" | "Touching" | "RequestPromise" | "SaveOp" | "LEGACY_SUPPORT" | "LegacySupport" | "Graphs" | "IS_FROZEN" | "IS_CACHE_HANDLER" | "CONFIG" | "DEBUG_MAP" | "IDENTIFIERS" | "DOCUMENTS" | "CacheForIdentifierCache" | "RecordCache" | "StoreMap" | "Store" | "$type" | "TransformName" | "RequestSignature" | "IS_FUTURE" | "DOC" | "ManagedArrayMap" | "ManagedObjectMap" | "Support" | "SOURCE" | "MUTATE" | "Destroy" | "Identifier" | "Editable" | "EmbeddedPath" | "EmbeddedField" | "Parent" | "Checkout" | "Legacy";
+type GlobalKey = `(transient) ${TransientKey}` | "AdapterError" | "InvalidError" | "TimeoutError" | "AbortError" | "UnauthorizedError" | "ForbiddenError" | "NotFoundError" | "ConflictError" | "ServerError" | "#{}" | "#[]" | "Signals" | "AvailableShims" | "FAKE_ARR" | "#source" | "#update" | "#notify" | "IS_COLLECTION" | "Touching" | "RequestPromise" | "SaveOp" | "LEGACY_SUPPORT" | "LegacySupport" | "Graphs" | "IS_FROZEN" | "IS_CACHE_HANDLER" | "CONFIG" | "DEBUG_MAP" | "IDENTIFIERS" | "DOCUMENTS" | "RecordCache" | "StoreMap" | "Store" | "$type" | "TransformName" | "RequestSignature" | "IS_FUTURE" | "DOC" | "ManagedArrayMap" | "ManagedObjectMap" | "Support" | "SOURCE" | "Destroy" | "Checkout" | "Commit" | "Context";
 type UniqueSymbol<T extends string> = `___(unique) Symbol(${T})`;
 type UniqueSymbolOr<
 	T,

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

@@ -1,7 +1,7 @@
 // The ResourceBlob is an opaque type that must
 // satisfy two constraints.
-// (1) it should be possible for the IdentifierCache
-// to be able to generate a RecordIdentifier for it
+// (1) it should be possible for the CacheKeyManager
+// to be able to generate a ResourceKey for it
 // whether by default or due to configuration.
 // (2) it should be in a format expected by the Cache.
 // This format is Cache declared.

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

@@ -1,6 +1,6 @@
-import type { StableDocumentIdentifier, StableRecordIdentifier } from "../identifier.js";
+import type { RequestKey, ResourceKey } from "../identifier.js";
 export interface Change {
-	identifier: StableRecordIdentifier | StableDocumentIdentifier;
+	identifier: ResourceKey | RequestKey;
 	op: "upsert" | "remove";
 	patch?: unknown;
 }

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

@@ -1,48 +1,48 @@
-import type { StableRecordIdentifier } from "../identifier.js";
+import type { ResourceKey } from "../identifier.js";
 export interface AddToResourceRelationshipMutation {
 	op: "add";
-	record: StableRecordIdentifier;
+	record: ResourceKey;
 	field: string;
-	value: StableRecordIdentifier | StableRecordIdentifier[];
+	value: ResourceKey | ResourceKey[];
 	index?: number;
 }
 export interface RemoveFromResourceRelationshipMutation {
 	op: "remove";
-	record: StableRecordIdentifier;
+	record: ResourceKey;
 	field: string;
-	value: StableRecordIdentifier | StableRecordIdentifier[];
+	value: ResourceKey | ResourceKey[];
 	index?: number;
 }
 export interface ReplaceRelatedRecordMutation {
 	op: "replaceRelatedRecord";
-	record: StableRecordIdentifier;
+	record: ResourceKey;
 	field: string;
 	// never null if field is a collection
-	value: StableRecordIdentifier | null;
+	value: ResourceKey | null;
 	// if field is a collection,
 	//  the value we are swapping with
-	prior?: StableRecordIdentifier;
+	prior?: ResourceKey;
 	index?: number;
 }
 export interface ReplaceRelatedRecordsMutation {
 	op: "replaceRelatedRecords";
-	record: StableRecordIdentifier;
+	record: ResourceKey;
 	field: string;
 	// the records to add. If no prior/index
 	//  specified all existing should be removed
-	value: StableRecordIdentifier[];
+	value: ResourceKey[];
 	// if this is a "splice" the
 	//  records we expect to be removed
-	prior?: StableRecordIdentifier[];
+	prior?: ResourceKey[];
 	// if this is a "splice" the
 	//   index to start from
 	index?: number;
 }
 export interface SortRelatedRecordsMutation {
 	op: "sortRelatedRecords";
-	record: StableRecordIdentifier;
+	record: ResourceKey;
 	field: string;
-	value: StableRecordIdentifier[];
+	value: ResourceKey[];
 }
 // A Mutation is an action that updates
 // the local state of the Cache in some

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>;