@warp-drive/core 5.7.0-alpha.9 → 5.7.0

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,86 @@
-// 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,7 @@ export type CacheOptions<T = unknown> = {
 	* than to invalidate findRecord requests for one.
 	*
 	*/
-	types?: T extends TypedRecordInstance ? ExtractSuggestedCacheTypes<T>[] : string[];
+	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 +65,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 +99,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 +118,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 +133,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 +146,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 +171,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 +186,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 +266,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 +289,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 +310,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 +322,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<

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

@@ -1,5 +1,15 @@
 import type { ObjectValue, PrimitiveValue, Value } from "../json/raw.js";
 /**
+* Options signature for Legacy Attributes.
+*/
+export interface AttrOptions {
+	/**
+	* A primitive value or a function which produces a value.
+	*/
+	defaultValue?: PrimitiveValue | (() => Value);
+	[key: string]: Value | (() => Value) | undefined;
+}
+/**
 * A generic "field" that can be used to define
 * primitive value fields.
 *
@@ -52,7 +62,7 @@ export interface GenericField {
 	*/
 	sourceKey?: string;
 	/**
-	* the name of the transform to use, if any
+	* the name of the {@link Transformation} to use, if any
 	*
 	* @public
 	*/
@@ -463,7 +473,7 @@ export interface ObjectField {
 		* Configures which extensions this object should use.
 		*
 		* Extensions are registered with the store's schema service
-		* via {@link SchemaService.registerDangerousObjectExtension}
+		* via {@link SchemaService.CAUTION_MEGA_DANGER_ZONE_registerExtension}
 		*
 		* Extensions should only be used for temporary enhancements
 		* to objects to support migrating away from deprecated patterns
@@ -545,6 +555,15 @@ export interface SchemaObjectField {
 	* @public
 	*/
 	options?: {
+		/**
+		* If true, if no value for this field exists in the cache,
+		* an empty `{}` will be used as the source for a new SchemaObject
+		* of the associated schema type, as opposed to the field's
+		* value being `null`.
+		*
+		* If `polymorphic` is `true`, defaultValue will be considered `false`.
+		*/
+		defaultValue?: boolean;
 		/**
 		* ::: warning ⚠️ Dangerous Feature Ahead
 		* :::
@@ -754,6 +773,13 @@ export interface SchemaArrayField {
 	* @public
 	*/
 	options?: {
+		/**
+		* If true, if no value for this field exists in the cache,
+		* an empty `[]` will be used as the value of the field,
+		* as opposed to the field's value being `null`.
+		*
+		*/
+		defaultValue?: boolean;
 		/**
 		* ::: warning ⚠️ Dangerous Feature Ahead
 		* :::
@@ -1172,8 +1198,9 @@ export interface LegacyAttributeField {
 	* Must comply to the specific transform's options
 	* schema.
 	*
+	* See {@link AttrOptions} for more info.
 	*/
-	options?: ObjectValue;
+	options?: AttrOptions;
 }
 /**
 * > [!CAUTION]

package/declarations/types/spec/document.d.ts

@@ -1,37 +1,33 @@
-import type { StableExistingRecordIdentifier } from "../identifier.js";
+import type { PersistedResourceKey } from "../identifier.js";
 import type { ApiError } from "./error.js";
 import type { Links, Meta, PaginationLinks } from "./json-api-raw.js";
 export interface ResourceMetaDocument {
-	// the url or cache-key associated with the structured document
 	lid?: string;
 	meta: Meta;
 	links?: Links | PaginationLinks;
 }
 export interface SingleResourceDataDocument<
-	T = StableExistingRecordIdentifier,
-	R = StableExistingRecordIdentifier
+	T = PersistedResourceKey,
+	R = PersistedResourceKey
 > {
-	// the url or cache-key associated with the structured document
 	lid?: string;
 	links?: Links | PaginationLinks;
 	meta?: Meta;
 	data: T | null;
 	included?: R[];
 }
-export interface CollectionResourceDataDocument<T = StableExistingRecordIdentifier> {
-	// the url or cache-key associated with the structured document
+export interface CollectionResourceDataDocument<T = PersistedResourceKey> {
 	lid?: string;
 	links?: Links | PaginationLinks;
 	meta?: Meta;
 	data: T[];
 	included?: T[];
 }
-export type ResourceDataDocument<T = StableExistingRecordIdentifier> = SingleResourceDataDocument<T> | CollectionResourceDataDocument<T>;
+export type ResourceDataDocument<T = PersistedResourceKey> = SingleResourceDataDocument<T> | CollectionResourceDataDocument<T>;
 export interface ResourceErrorDocument {
-	// the url or cache-key associated with the structured document
 	lid?: string;
 	links?: Links | PaginationLinks;
 	meta?: Meta;
 	errors: ApiError[];
 }
-export type ResourceDocument<T = StableExistingRecordIdentifier> = ResourceMetaDocument | SingleResourceDataDocument<T> | CollectionResourceDataDocument<T> | ResourceErrorDocument;
+export type ResourceDocument<T = PersistedResourceKey> = ResourceMetaDocument | SingleResourceDataDocument<T> | CollectionResourceDataDocument<T> | ResourceErrorDocument;