@warp-drive/core 5.7.0-alpha.3 → 5.7.0-alpha.30

package/declarations/types/graph.d.ts

@@ -1,46 +1,46 @@
 import type { AddToResourceRelationshipMutation as AddResourceMutation, RemoveFromResourceRelationshipMutation as RemoveResourceMutation } from "./cache/mutations.js";
 import type { AddToResourceRelationshipOperation as AddResourceOperation, RemoveFromResourceRelationshipOperation as RemoveResourceOperation, UpdateResourceRelationshipOperation } from "./cache/operations.js";
-import type { StableRecordIdentifier } from "./identifier.js";
+import type { ResourceKey } from "./identifier.js";
 import type { CollectionResourceRelationship, SingleResourceRelationship } from "./spec/json-api-raw.js";
 export interface Operation {
 	op: string;
 }
 export interface UpdateRelationshipOperation {
 	op: "updateRelationship";
-	record: StableRecordIdentifier;
+	record: ResourceKey;
 	field: string;
 	value: SingleResourceRelationship | CollectionResourceRelationship;
 }
 export interface DeleteRecordOperation {
 	op: "deleteRecord";
-	record: StableRecordIdentifier;
+	record: ResourceKey;
 	isNew: boolean;
 }
 export interface UnknownOperation {
 	op: "never";
-	record: StableRecordIdentifier;
+	record: ResourceKey;
 	field: string;
 }
 export interface ReplaceRelatedRecordOperation {
 	op: "replaceRelatedRecord";
-	record: StableRecordIdentifier;
+	record: ResourceKey;
 	field: string;
-	value: StableRecordIdentifier | null;
-	prior?: StableRecordIdentifier;
+	value: ResourceKey | null;
+	prior?: ResourceKey;
 	index?: number;
 }
 export interface SortRelatedRecords {
 	op: "sortRelatedRecords";
-	record: StableRecordIdentifier;
+	record: ResourceKey;
 	field: string;
-	value: StableRecordIdentifier[];
+	value: ResourceKey[];
 }
 export interface ReplaceRelatedRecordsOperation {
 	op: "replaceRelatedRecords";
-	record: StableRecordIdentifier;
+	record: ResourceKey;
 	field: string;
-	value: StableRecordIdentifier[];
-	prior?: StableRecordIdentifier[];
+	value: ResourceKey[];
+	prior?: ResourceKey[];
 	index?: number;
 }
 export type RemoteRelationshipOperation = UpdateResourceRelationshipOperation | UpdateRelationshipOperation | ReplaceRelatedRecordOperation | ReplaceRelatedRecordsOperation | RemoveResourceOperation | AddResourceOperation | DeleteRecordOperation | SortRelatedRecords;

package/declarations/types/identifier.d.ts

@@ -1,112 +1,88 @@
 // provided for additional debuggability
 export declare const DEBUG_CLIENT_ORIGINATED: unique symbol;
-export declare const DEBUG_IDENTIFIER_BUCKET: unique symbol;
+export declare const DEBUG_KEY_TYPE: unique symbol;
 export declare const DEBUG_STALE_CACHE_OWNER: unique symbol;
 // also present in production
 export declare const CACHE_OWNER: "__$co";
-export type IdentifierBucket = "record" | "document";
-export interface Identifier {
-	lid: string;
-	clientId?: string;
-}
-export interface ExistingRecordIdentifier<T extends string = string> extends Identifier {
-	id: string;
-	type: T;
-}
-export interface NewRecordIdentifier<T extends string = string> extends Identifier {
-	id: string | null;
-	type: T;
-}
-export type StableDocumentIdentifier = {
-	lid: string;
-};
-export type RequestKey = StableDocumentIdentifier;
+export type CacheKeyType = "record" | "document";
 /**
-* An Identifier specific to a record which may or may not
-* be present in the cache.
+* A referentially stable object with a unique string (lid) that can be used
+* as a reference to request data in the cache.
 *
-* The absence of an `id` DOES NOT indicate that this
-* Identifier is for a new client-created record as it
-* may also indicate that it was generated for a secondary
-* index and the primary `id` index is not yet known.
+* Only requests that are assigned a RequestKey are retrievable/replayable from
+* the cache, though requests without RequestKeys may still update cache state.
 *
-* @internal
+* @public
 */
-export type RecordIdentifier<T extends string = string> = ExistingRecordIdentifier<T> | NewRecordIdentifier<T>;
+export interface RequestKey {
+	lid: string;
+	type: "@document";
+}
+/** @deprecated use {@link RequestKey} */
+export type StableDocumentIdentifier = RequestKey;
 /**
-* Used when an Identifier is known to be the stable version
-*
-* @internal
+* Used when an ResourceKey is known to be the stable version
 */
-export interface StableIdentifier extends Identifier {
-	[DEBUG_IDENTIFIER_BUCKET]?: string;
+interface ResourceKeyBase<T extends string = string> {
+	/**
+	* A string representing a unique identity.
+	*
+	* @public
+	*/
+	lid: string;
+	/**
+	* the primary `ResourceType` or "model name" this ResourceKey belongs to.
+	*
+	* @public
+	*/
+	type: T;
 }
 /**
-* Used when a StableRecordIdentifier was not created locally as part
+* Used when a ResourceKey was not created locally as part
 * of a call to store.createRecord
 *
-* Distinguishing between this Identifier and one for a client created
-* record that was created with an ID is generally speaking not possible
+* Distinguishing between this ResourceKey and one for a client created
+* resource that was created with an ID is generally speaking not possible
 * at runtime, so anything with an ID typically narrows to this.
-*
-* @internal
 */
-export interface StableExistingRecordIdentifier<T extends string = string> extends StableIdentifier {
+export interface PersistedResourceKey<T extends string = string> extends ResourceKeyBase<T> {
+	/**
+	* the PrimaryKey for the resource this ResourceKey represents.
+	*
+	* @public
+	*/
 	id: string;
-	type: T;
-	[DEBUG_CLIENT_ORIGINATED]?: boolean;
-	[CACHE_OWNER]: number | undefined;
-	[DEBUG_STALE_CACHE_OWNER]?: number | undefined;
 }
+/** @deprecated use {@link PersistedResourceKey} */
+export type StableExistingRecordIdentifier<T extends string = string> = PersistedResourceKey<T>;
 /**
-* Used when a StableRecordIdentifier was created locally
+* Used when a ResourceKey was created locally
 * (by a call to store.createRecord).
 *
-* It is possible in rare circumstances to have a StableRecordIdentifier
+* It is possible in rare circumstances to have a ResourceKey
 * that is not for a new record but does not have an ID. This would
 * happen if a user intentionally created one for use with a secondary-index
 * prior to the record having been fully loaded.
-*
-* @internal
 */
-export interface StableNewRecordIdentifier<T extends string = string> extends StableIdentifier {
+export interface NewResourceKey<T extends string = string> extends ResourceKeyBase<T> {
+	/**
+	* the PrimaryKey for the resource this ResourceKey represents. `null`
+	* if not yet assigned a PrimaryKey value.
+	*
+	* @public
+	*/
 	id: string | null;
-	type: T;
-	[DEBUG_CLIENT_ORIGINATED]?: boolean;
-	[CACHE_OWNER]: number | undefined;
-	[DEBUG_STALE_CACHE_OWNER]?: number | undefined;
 }
 /**
 * A referentially stable object with a unique string (lid) that can be used
 * as a reference to data in the cache.
 *
-* Every record instance has a unique identifier, and identifiers may refer
+* Every resource has a unique ResourceKey, and ResourceKeys may refer
 * to data that has never been loaded (for instance, in an async relationship).
 *
-* @class StableRecordIdentifier
-* @public
-*/
-/**
-* A string representing a unique identity.
-*
-* @property lid
-* @type {String}
-* @public
-*/
-/**
-* the primary resource `type` or `modelName` this identity belongs to.
-*
-* @property type
-* @type {String}
-* @public
-*/
-/**
-* the primary id for the record this identity belongs to. `null`
-* if not yet assigned an id.
-*
-* @property id
-* @type {String | null}
 * @public
 */
-export type StableRecordIdentifier<T extends string = string> = StableExistingRecordIdentifier<T> | StableNewRecordIdentifier<T>;
-export type ResourceKey<T extends string = string> = StableRecordIdentifier<T>;
+export type ResourceKey<T extends string = string> = PersistedResourceKey<T> | NewResourceKey<T>;
+/** @deprecated use {@link ResourceKey} */
+export type StableRecordIdentifier<T extends string = string> = ResourceKey<T>;
+export {};

package/declarations/types/params.d.ts

@@ -1,9 +1,8 @@
-import type { Includes, TypedRecordInstance } from "./record.js";
 export type SerializablePrimitive = string | number | boolean | null;
 export type Serializable = SerializablePrimitive | SerializablePrimitive[];
 export type QueryParamsSerializationOptions = {
 	arrayFormat?: "bracket" | "indices" | "repeat" | "comma";
 };
-export type QueryParamsSource<T = unknown> = ({
-	include?: T extends TypedRecordInstance ? Includes<T>[] : string | string[];
+export type QueryParamsSource = ({
+	include?: string | string[];
 } & Record<Exclude<string, "include">, Serializable>) | URLSearchParams;

package/declarations/types/request.d.ts

@@ -1,9 +1,9 @@
-import type { StableRecordIdentifier } from "./identifier.js";
+import type { Store } from "../store/-private.js";
+import type { ResourceKey } from "./identifier.js";
 import type { QueryParamsSerializationOptions } from "./params.js";
-import type { ExtractSuggestedCacheTypes, Includes, TypedRecordInstance, TypeFromInstanceOrString } from "./record.js";
+import type { TypeFromInstanceOrString } from "./record.js";
 import type { ResourceIdentifierObject } from "./spec/json-api-raw.js";
 import type { RequestSignature } from "./symbols.js";
-type Store = unknown;
 export declare const SkipCache: "___(unique) Symbol(SkipCache)";
 export declare const EnableHydration: "___(unique) Symbol(EnableHydration)";
 export declare const IS_FUTURE: "___(unique) Symbol(IS_FUTURE)";
@@ -13,7 +13,7 @@ export type HTTPMethod = "QUERY" | "GET" | "OPTIONS" | "POST" | "PUT" | "PATCH"
 * Use these options to adjust CacheHandler behavior for a request.
 *
 */
-export type CacheOptions<T = unknown> = {
+export type CacheOptions = {
 	/**
 	* A key that uniquely identifies this request. If not present, the url wil be used
 	* as the key for any GET request, while all other requests will not be cached.
@@ -47,7 +47,10 @@ export type CacheOptions<T = unknown> = {
 	* than to invalidate findRecord requests for one.
 	*
 	*/
-	types?: T extends TypedRecordInstance ? ExtractSuggestedCacheTypes<T>[] : string[];
+	// TODO: Ideally this would be T extends TypedRecordInstance ? ExtractSuggestedCacheTypes<T>[] : string[];
+	// but that leads to `Type instantiation is excessively deep and possibly infinite.`
+	// issues when `T` has many properties.
+	types?: string[];
 	/**
 	* If true, the request will never be handled by the cache-manager and thus
 	* will never resolve from cache nor update the cache.
@@ -65,31 +68,25 @@ export type FindRecordRequestOptions<
 	url: string;
 	method: "GET";
 	headers: Headers;
-	cacheOptions?: CacheOptions<T>;
+	cacheOptions?: CacheOptions;
 	op: "findRecord";
 	records: [ResourceIdentifierObject<TypeFromInstanceOrString<T>>];
 	[RequestSignature]?: RT;
 };
-export type QueryRequestOptions<
-	RT = unknown,
-	T = unknown
-> = {
+export type QueryRequestOptions<RT = unknown> = {
 	url: string;
 	method: "GET";
 	headers: Headers;
-	cacheOptions?: CacheOptions<T>;
+	cacheOptions?: CacheOptions;
 	op: "query";
 	[RequestSignature]?: RT;
 };
-export type PostQueryRequestOptions<
-	RT = unknown,
-	T = unknown
-> = {
+export type PostQueryRequestOptions<RT = unknown> = {
 	url: string;
 	method: "POST" | "QUERY";
 	headers: Headers;
 	body?: string | BodyInit | FormData;
-	cacheOptions: CacheOptions<T> & {
+	cacheOptions: CacheOptions & {
 		key: string;
 	};
 	op: "query";
@@ -105,14 +102,14 @@ export type DeleteRequestOptions<
 	op: "deleteRecord";
 	body?: string | BodyInit | FormData;
 	data: {
-		record: StableRecordIdentifier<TypeFromInstanceOrString<T>>;
+		record: ResourceKey<TypeFromInstanceOrString<T>>;
 	};
 	records: [ResourceIdentifierObject<TypeFromInstanceOrString<T>>];
 	[RequestSignature]?: RT;
 };
 type ImmutableRequest<T> = Readonly<T> & {
 	readonly headers: ImmutableHeaders;
-	readonly records: [StableRecordIdentifier];
+	readonly records: [ResourceKey];
 };
 export type UpdateRequestOptions<
 	RT = unknown,
@@ -124,7 +121,7 @@ export type UpdateRequestOptions<
 	op: "updateRecord";
 	body?: string | BodyInit | FormData;
 	data: {
-		record: StableRecordIdentifier<TypeFromInstanceOrString<T>>;
+		record: ResourceKey<TypeFromInstanceOrString<T>>;
 	};
 	records: [ResourceIdentifierObject<TypeFromInstanceOrString<T>>];
 	[RequestSignature]?: RT;
@@ -139,7 +136,7 @@ export type CreateRequestOptions<
 	op: "createRecord";
 	body?: string | BodyInit | FormData;
 	data: {
-		record: StableRecordIdentifier<TypeFromInstanceOrString<T>>;
+		record: ResourceKey<TypeFromInstanceOrString<T>>;
 	};
 	records: [ResourceIdentifierObject<TypeFromInstanceOrString<T>>];
 	[RequestSignature]?: RT;
@@ -152,17 +149,22 @@ export type RemotelyAccessibleIdentifier<T extends string = string> = {
 	type: T;
 	lid?: string;
 };
-export type ConstrainedRequestOptions = {
+export interface ConstrainedRequestOptions {
 	reload?: boolean;
 	backgroundReload?: boolean;
 	host?: string;
 	namespace?: string;
 	resourcePath?: string;
 	urlParamsSettings?: QueryParamsSerializationOptions;
-};
-export type FindRecordOptions<T = unknown> = ConstrainedRequestOptions & {
-	include?: T extends TypedRecordInstance ? Includes<T>[] : string | string[];
-};
+}
+export interface FindRecordOptions extends ConstrainedRequestOptions {
+	include?: string | string[];
+}
+/**
+* When a handler chain resolves, it returns an object
+* containing the original request, the response set by the handler
+* chain (if any), and the processed content.
+*/
 export interface StructuredDataDocument<T> {
 	[STRUCTURED]?: true;
 	/**
@@ -172,6 +174,14 @@ export interface StructuredDataDocument<T> {
 	response: Response | ResponseInfo | null;
 	content: T;
 }
+/**
+* When a handler chain rejects, it throws an Error that maintains the
+* `{ request, response, content }` shape but is also an Error instance
+* itself.
+*
+* If using the error originates from the {@link Fetch | Fetch Handler}
+* the error will be a {@link FetchError}
+*/
 export interface StructuredErrorDocument<T = unknown> extends Error {
 	[STRUCTURED]?: true;
 	request: ImmutableRequestInfo;
@@ -179,14 +189,27 @@ export interface StructuredErrorDocument<T = unknown> extends Error {
 	error: string | object;
 	content?: T;
 }
+/**
+* A union of the resolve/reject data types for a request.
+*
+* See the docs for:
+*
+* - {@link StructuredDataDocument} (resolved/successful requests)
+* - {@link StructuredErrorDocument} (rejected/failed requests)
+*/
 export type StructuredDocument<T> = StructuredDataDocument<T> | StructuredErrorDocument<T>;
 /**
-* JavaScript's native Request class.
+* The {@link RequestInit} interface accepted by the native {@link fetch} API.
 *
 * WarpDrive provides our own typings due to incompleteness in the native typings.
 *
+* @privateRemarks
+* - [MDN Reference (fetch)](https://developer.mozilla.org/docs/Web/API/Window/fetch)
+* - [MDN Reference (RequestInit)](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)
+* - [MDN Reference (Request)](https://developer.mozilla.org/docs/Web/API/Request)
+*
 */
-interface Request {
+interface NativeRequestInit {
 	/** Returns the cache mode associated with request, which is a string indicating how the request will interact with the browser's cache when fetching.
 	*/
 	cache?: RequestCache;
@@ -246,14 +269,21 @@ export interface ImmutableHeaders extends Headers {
 	toJSON(): [string, string][];
 }
 /**
-* Extends JavaScript's native {@link Request} object with additional
-* properties specific to the RequestManager's capabilities.
+* Extends JavaScript's native {@link fetch} {@link NativeRequestInit | RequestInit} with additional
+* properties specific to the {@link RequestManager | RequestManager's} capabilities.
 *
+* This interface is used to define the shape of a request that can be made via
+* either the {@link RequestManager.request} or {@link Store.request} methods.
+*
+* @privateRemarks
+* - [MDN Reference (fetch)](https://developer.mozilla.org/docs/Web/API/Window/fetch)
+* - [MDN Reference (RequestInit)](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)
+* - [MDN Reference (Request)](https://developer.mozilla.org/docs/Web/API/Request)
+*
+* @public
+* @since 4.12
 */
-export interface RequestInfo<
-	RT = unknown,
-	T = unknown
-> extends Request {
+export interface RequestInfo<RT = unknown> extends NativeRequestInit {
 	/**
 	* If provided, used instead of the AbortController auto-configured for each request by the RequestManager
 	*
@@ -262,16 +292,16 @@ export interface RequestInfo<
 	/**
 	* @see {@link CacheOptions}
 	*/
-	cacheOptions?: CacheOptions<T>;
+	cacheOptions?: CacheOptions;
 	store?: Store;
 	op?: string;
 	/**
-	* The identifiers of the primary resources involved in the request
+	* The {@link ResourceKey | ResourceKeys} of the primary resources involved in the request
 	* (if any). This may be used by handlers to perform transactional
 	* operations on the store.
 	*
 	*/
-	records?: StableRecordIdentifier[];
+	records?: ResourceKey[];
 	disableTestWaiter?: boolean;
 	/**
 	* data that a handler should convert into
@@ -283,7 +313,7 @@ export interface RequestInfo<
 	*/
 	data?: Record<string, unknown>;
 	/**
-	* options specifically intended for handlers
+	* options specifically intended for {@link Handler | Handlers}
 	* to utilize to process the request
 	*
 	*/
@@ -295,11 +325,8 @@ export interface RequestInfo<
 * Immutable version of {@link RequestInfo}. This is what is passed to handlers.
 *
 */
-export type ImmutableRequestInfo<
-	RT = unknown,
-	T = unknown
-> = Readonly<Omit<RequestInfo<RT, T>, "controller">> & {
-	readonly cacheOptions?: Readonly<CacheOptions<T>>;
+export type ImmutableRequestInfo<RT = unknown> = Readonly<Omit<RequestInfo<RT>, "controller">> & {
+	readonly cacheOptions?: Readonly<CacheOptions>;
 	readonly headers?: ImmutableHeaders;
 	readonly data?: Readonly<Record<string, unknown>>;
 	readonly options?: Readonly<Record<string, unknown>>;

package/declarations/types/schema/concepts.d.ts

@@ -1,4 +1,4 @@
-import type { StableRecordIdentifier } from "../identifier.js";
+import type { ResourceKey } from "../identifier.js";
 import type { ObjectValue, Value } from "../json/raw.js";
 import type { OpaqueRecordInstance } from "../record.js";
 import type { Type } from "../symbols.js";
@@ -8,7 +8,7 @@ export type Transformation<
 > = {
 	serialize(value: PT, options: ObjectValue | null, record: OpaqueRecordInstance): T;
 	hydrate(value: T | undefined, options: ObjectValue | null, record: OpaqueRecordInstance): PT;
-	defaultValue?(options: ObjectValue | null, identifier: StableRecordIdentifier): T;
+	defaultValue?(options: ObjectValue | null, identifier: ResourceKey): T;
 	[Type]: string;
 };
 export type Derivation<