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

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<