@warp-drive/core 5.7.0-alpha.13 → 5.7.0-alpha.15

package/declarations/store/-types/q/schema-service.d.ts

@@ -1,6 +1,6 @@
 import type { CAUTION_MEGA_DANGER_ZONE_Extension, ProcessedExtension } from "../../../reactive.js";
 import type { ExtensibleField } from "../../../reactive/-private/schema.js";
-import type { RecordIdentifier, StableRecordIdentifier } from "../../../types/identifier.js";
+import type { ResourceKey } from "../../../types/identifier.js";
 import type { ObjectValue } from "../../../types/json/raw.js";
 import type { Derivation, HashFn, Transformation } from "../../../types/schema/concepts.js";
 import type { ArrayField, CacheableFieldSchema, DerivedField, FieldSchema, GenericField, HashField, IdentityField, LegacyAttributeField, LegacyRelationshipField, ObjectField, Schema, Trait } from "../../../types/schema/fields.js";
@@ -74,7 +74,7 @@ export interface SchemaService {
 	*
 	* @public
 	*/
-	hasResource(resource: ObjectWithStringTypeProperty | StableRecordIdentifier): boolean;
+	hasResource(resource: ObjectWithStringTypeProperty | ResourceKey): boolean;
 	/**
 	* Queries whether the SchemaService recognizes `type` as a resource trait
 	*
@@ -86,7 +86,7 @@ export interface SchemaService {
 	*
 	* @public
 	*/
-	resourceHasTrait(resource: ObjectWithStringTypeProperty | StableRecordIdentifier, trait: string): boolean;
+	resourceHasTrait(resource: ObjectWithStringTypeProperty | ResourceKey, trait: string): boolean;
 	/**
 	* Queries for the fields of a given resource type or resource identity.
 	*
@@ -94,7 +94,7 @@ export interface SchemaService {
 	*
 	* @public
 	*/
-	fields(resource: ObjectWithStringTypeProperty | StableRecordIdentifier): Map<string, FieldSchema>;
+	fields(resource: ObjectWithStringTypeProperty | ResourceKey): Map<string, FieldSchema>;
 	/**
 	* Queries for the fields of a given resource type or resource identity.
 	*
@@ -102,7 +102,7 @@ export interface SchemaService {
 	*
 	* @public
 	*/
-	cacheFields?(resource: ObjectWithStringTypeProperty | StableRecordIdentifier): Map<string, Exclude<CacheableFieldSchema, IdentityField>>;
+	cacheFields?(resource: ObjectWithStringTypeProperty | ResourceKey): Map<string, Exclude<CacheableFieldSchema, IdentityField>>;
 	/**
 	* Returns the transformation registered with the name provided
 	* by `field.type`. Validates that the field is a valid transformable.
@@ -129,7 +129,7 @@ export interface SchemaService {
 	*
 	* @public
 	*/
-	resource(resource: ObjectWithStringTypeProperty | StableRecordIdentifier): Schema;
+	resource(resource: ObjectWithStringTypeProperty | ResourceKey): Schema;
 	/**
 	* Enables registration of multiple Schemas at once.
 	*
@@ -253,7 +253,7 @@ export interface SchemaService {
 	* @public
 	* @deprecated
 	*/
-	attributesDefinitionFor?(identifier: RecordIdentifier | ObjectWithStringTypeProperty): AttributesSchema;
+	attributesDefinitionFor?(key: ResourceKey | ObjectWithStringTypeProperty): AttributesSchema;
 	/**
 	* DEPRECATED - use `fields` instead
 	*
@@ -332,7 +332,7 @@ export interface SchemaService {
 	* @public
 	* @deprecated
 	*/
-	relationshipsDefinitionFor?(identifier: RecordIdentifier | ObjectWithStringTypeProperty): RelationshipsSchema;
+	relationshipsDefinitionFor?(key: ResourceKey | ObjectWithStringTypeProperty): RelationshipsSchema;
 	/**
 	* Returns all known resource types
 	*
@@ -350,7 +350,7 @@ export interface SchemaService {
 	*
 	* @public
 	*/
-	CAUTION_MEGA_DANGER_ZONE_resourceExtensions?(resource: StableRecordIdentifier | {
+	CAUTION_MEGA_DANGER_ZONE_resourceExtensions?(resource: ResourceKey | {
 		type: string;
 	}): null | ProcessedExtension["features"];
 	/**

package/declarations/store/deprecated/-private.d.ts

@@ -1,11 +1,11 @@
-import type { StableNewRecordIdentifier, StableRecordIdentifier } from "../../types/identifier.js";
+import type { NewResourceKey, ResourceKey } from "../../types/identifier.js";
 import type { Value } from "../../types/json/raw.js";
 import type { OpaqueRecordInstance, TypedRecordInstance, TypeFromInstance } from "../../types/record.js";
 import type { LegacyAttributeField, LegacyRelationshipField } from "../../types/schema/fields.js";
 import type { SingleResourceDocument } from "../../types/spec/json-api-raw.js";
 import { type InstanceCache } from "../-private.js";
 import type { Store } from "./store.js";
-export declare function preloadData(store: Store, identifier: StableNewRecordIdentifier, preload: Record<string, Value>): void;
+export declare function preloadData(store: Store, identifier: NewResourceKey, preload: Record<string, Value>): void;
 export interface BaseFinderOptions {
 	reload?: boolean;
 	backgroundReload?: boolean;
@@ -55,7 +55,7 @@ export interface ModelSchema<T = unknown> {
 	eachRelationship<K extends KeyOrString<T>>(callback: (this: ModelSchema<T>, key: K, relationship: LegacyRelationshipField) => void, binding?: T): void;
 	eachTransformedAttribute<K extends KeyOrString<T>>(callback: (this: ModelSchema<T>, key: K, type: string | null) => void, binding?: T): void;
 }
-export declare function resourceIsFullyDeleted(instanceCache: InstanceCache, identifier: StableRecordIdentifier): boolean;
+export declare function resourceIsFullyDeleted(instanceCache: InstanceCache, identifier: ResourceKey): boolean;
 /**
 A `RecordReference` is a low-level API that allows users and
 addon authors to perform meta-operations on a record.
@@ -73,7 +73,7 @@ export declare class RecordReference {
 	private ___identifier;
 	/** @internal */
 	private _ref;
-	constructor(store: Store, identifier: StableRecordIdentifier);
+	constructor(store: Store, identifier: ResourceKey);
 	/** @internal */
 	destroy(): void;
 	get type(): string;
@@ -112,7 +112,7 @@ export declare class RecordReference {
 	@public
 	@return The identifier of the record.
 	*/
-	identifier(): StableRecordIdentifier;
+	identifier(): ResourceKey;
 	/**
 	How the reference will be looked up when it is loaded. Currently
 	this always returns `identity` to signify that a record will be

package/declarations/store/deprecated/store.d.ts

@@ -1,6 +1,6 @@
 import type { TypeFromInstance } from "../../types/record.js";
 import type { ResourceIdentifierObject } from "../../types/spec/json-api-raw.js";
-import type { CollectionRecordArray, LiveArray } from "../-private.js";
+import type { LegacyLiveArray, LegacyQueryArray } from "../-private.js";
 import { Store } from "../-private/store-service.js";
 import type { FindAllOptions, FindRecordOptions, LegacyResourceQuery, ModelSchema, QueryOptions } from "./-private.js";
 import { RecordReference } from "./-private.js";
@@ -548,9 +548,9 @@ declare module "../-private/store-service" {
 		@param type the name of the resource
 		@param options
 		*/
-		findAll<T>(type: TypeFromInstance<T>, options?: FindAllOptions): Promise<LiveArray<T>>;
+		findAll<T>(type: TypeFromInstance<T>, options?: FindAllOptions): Promise<LegacyLiveArray<T>>;
 		/** @deprecated */
-		findAll(type: string, options?: FindAllOptions): Promise<LiveArray>;
+		findAll(type: string, options?: FindAllOptions): Promise<LegacyLiveArray>;
 		/**
 		This method delegates a query to the adapter. This is the one place where
 		adapter-level semantics are exposed to the application.
@@ -565,13 +565,13 @@ declare module "../-private/store-service" {
 		
 		If you do something like this:
 		
-		```javascript
+		```js
 		store.query('person', { page: 1 });
 		```
 		
 		The request made to the server will look something like this:
 		
-		```
+		```http
 		GET "/api/v1/person?page=1"
 		```
 		
@@ -591,8 +591,7 @@ declare module "../-private/store-service" {
 		```
 		
 		This method returns a promise, which is resolved with a
-		[`Collection`](/ember-data/release/classes/Collection)
-		once the server returns.
+		{@link LegacyQueryArray} once the server returns.
 		
 		@public
 		@deprecated use {@link Store.request} instead
@@ -602,9 +601,9 @@ declare module "../-private/store-service" {
 		@param query a query to be used by the adapter
 		@param options optional, may include `adapterOptions` hash which will be passed to adapter.query
 		*/
-		query<T>(type: TypeFromInstance<T>, query: LegacyResourceQuery, options?: QueryOptions): Promise<CollectionRecordArray<T>>;
+		query<T>(type: TypeFromInstance<T>, query: LegacyResourceQuery, options?: QueryOptions): Promise<LegacyQueryArray<T>>;
 		/** @deprecated */
-		query(type: string, query: LegacyResourceQuery, options?: QueryOptions): Promise<CollectionRecordArray>;
+		query(type: string, query: LegacyResourceQuery, options?: QueryOptions): Promise<LegacyQueryArray>;
 		/**
 		This method makes a request for one record, where the `id` is not known
 		beforehand (if the `id` is known, use [`findRecord`](../methods/findRecord?anchor=findRecord)

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" | "RecordCache" | "StoreMap" | "Store" | "$type" | "TransformName" | "RequestSignature" | "IS_FUTURE" | "DOC" | "ManagedArrayMap" | "ManagedObjectMap" | "Support" | "SOURCE" | "MUTATE" | "Destroy" | "Checkout" | "Context";
+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 { ResourceKey, RequestKey } 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, ResourceKey, RequestKey } 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>;