@warp-drive/core 5.8.0-alpha.9 → 5.8.0-beta.1

package/declarations/types/record.d.ts

@@ -134,4 +134,136 @@ export type StringSatisfiesIncludes<
 	SET extends string
 > = _StringSatisfiesIncludes<T, SET, T>;
 export declare function createIncludeValidator<T extends TypedRecordInstance>(): <U extends string>(includes: StringSatisfiesIncludes<U, Includes<T>>) => U;
+/**
+* A utility that takes two types, K and T, and produces a new type that is a "mask" of T based on K.
+*
+* That's a mouthful, so let's break it down:
+*
+* Let's say you have a User type and an Address type.
+*
+* ```ts
+* interface Address {
+*   street: string;
+*   city: string;
+*   state: string;
+*   zip: string;
+* }
+*
+* interface User {
+*   name: string;
+*   title: string;
+*   address: Address;
+* }
+* ```
+*
+* Now, imagine you want to load a preview of the user with some information about their address,
+* but you don't want to load the entire user or address. You probably want to still ensure
+* the type of the data you do load matches the underlying Address and User types, but doesn't
+* include everything.
+*
+* If you did this manually, you might do something like this:
+*
+* ```ts
+* interface UserPreview {
+*   name: string;
+*   address: AddressPreview;
+* }
+*
+* interface AddressPreview {
+*   city: string;
+* }
+* ```
+*
+* From a TypeScript performance perspective, this is the best way to approach these preview
+* types, but this is also tedious and error-prone, especially if the User or Address types change.
+*
+* For Address, we could create a validated type using `Pick`:
+*
+* ```ts
+* type AddressPreview = Pick<Address, 'city'>;
+* ```
+*
+* This ensures that if the Address type changes, our AddressPreview will still be valid.
+* However, for UserPreview, we can't just use `Pick` because the `address` property is of type `Address`,
+* not `AddressPreview`. This is where the `Mask` type comes in.
+*
+* With `Mask`, we define the `UserPreview` in two parts
+* - first, we define the subset of fields we want to include from `User`, using `Pick` or an interface.
+* - then, we use `Mask` to replace the related types of fields like Address with their more limited subset.
+*
+* Here's how we can do it:
+*
+* ```ts
+* // First, we define the base of UserPreview with Pick
+* type UserPreviewBase = Pick<User, 'name' | 'address'>;
+* // Then, we use Mask to replace Address with AddressPreview
+* type UserPreview = Mask<{ address: AddressPreview }, UserPreviewBase>;
+* ```
+*
+* Now, `UserPreview` will have the `name` field from `User` and the `address` field will be of type `AddressPreview`.
+* This way, if the `User` or `Address` types change, TypeScript will ensure that our `UserPreview` and `AddressPreview`
+* types remain valid and consistent with the underlying types.
+*
+* But what if your app has data with massive interfaces such that the TypeScript performance of this
+* approach becomes a problem? In that case, see {@link Validate}
+*/
+export type Mask<
+	K extends object,
+	T extends K
+> = { [P in keyof T] : P extends keyof K ? (T[P] extends K[P] ? K[P] : never) : T[P] };
+/**
+* A utility that takes two types, K and T, and ensures that K is a valid subset of T.
+*
+* That's a mouthful, so let's break it down:
+*
+* Let's say you have a User type and an Address type.
+*
+* ```ts
+* interface Address {
+*   street: string;
+*   city: string;
+*   state: string;
+*   zip: string;
+* }
+*
+* interface User {
+*   name: string;
+*   title: string;
+*   address: Address;
+* }
+* ```
+*
+* Now, imagine you want to load a preview of the user with some information about their address,
+* but you don't want to load the entire user or address. You probably want to still ensure
+* the type of the data you do load matches the underlying Address and User types, but doesn't
+* include everything.
+*
+* You might do something like this:
+*
+* ```ts
+* interface UserPreview {
+*   name: string;
+*   address: AddressPreview;
+* }
+*
+* interface AddressPreview {
+*   city: string;
+* }
+* ```
+*
+* From a TypeScript performance perspective, this is the best way to approach these preview
+* types, but this is also error-prone, especially if the User or Address types change.
+*
+* Validate can help ensure that your preview types remain valid.
+*
+* ```ts
+* type IsValidUserPreview = Validate<UserPreview, User>; // This will be valid
+* ```
+*
+* For help creating subsets of types, see {@link Mask}
+*/
+export type Validate<
+	K extends object,
+	T extends K
+> = T extends K ? K : never;
 export {};

package/declarations/types/request.d.ts

@@ -1,3 +1,4 @@
+import type { FetchError } from "../request/-private/utils.js";
 import type { Store } from "../store/-private.js";
 import type { ResourceKey } from "./identifier.js";
 import type { QueryParamsSerializationOptions } from "./params.js";
@@ -8,6 +9,7 @@ export declare const SkipCache: "___(unique) Symbol(SkipCache)";
 export declare const EnableHydration: "___(unique) Symbol(EnableHydration)";
 export declare const IS_FUTURE: "___(unique) Symbol(IS_FUTURE)";
 export declare const STRUCTURED: "___(unique) Symbol(DOC)";
+export type { FetchError };
 export type HTTPMethod = "QUERY" | "GET" | "OPTIONS" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "CONNECT" | "TRACE";
 /**
 * Use these options to adjust {@link CacheHandler} behavior for a request
@@ -159,11 +161,15 @@ 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.
+* When a {@link Future} resolves, it returns an object
+* containing the original {@link RequestInfo | request},
+* the {@link Response | response} set by the handler chain (if any), and
+* the processed content.
 */
 export interface StructuredDataDocument<T> {
+	/**
+	* @private
+	*/
 	[STRUCTURED]?: true;
 	/**
 	* @see {@link ImmutableRequestInfo}
@@ -173,25 +179,34 @@ export interface StructuredDataDocument<T> {
 	content: T;
 }
 /**
-* When a handler chain rejects, it throws an Error that maintains the
-* `{ request, response, content }` shape but is also an Error instance
+* When a {@link Future} rejects, it throws either an {@link Error}
+* an {@link AggregateError} or a {@link DOMException} 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 {
+	/**
+	* @private
+	*/
 	[STRUCTURED]?: true;
+	/**
+	* @see {@link ImmutableRequestInfo}
+	*/
 	request: ImmutableRequestInfo;
 	response: Response | ResponseInfo | null;
 	error: string | object;
 	content?: T;
 }
 /**
-* A union of the resolve/reject data types for a request.
+* A union of the resolve/reject data types for the {@link Future}
+* returned by {@link Store.request | request}
 *
-* See the docs for:
+* See also the docs for:
 *
+* - {@link Future}
 * - {@link StructuredDataDocument} (resolved/successful requests)
 * - {@link StructuredErrorDocument} (rejected/failed requests)
 */
@@ -350,4 +365,3 @@ export interface RequestContext {
 	setStream(stream: ReadableStream | Promise<ReadableStream | null>): void;
 	setResponse(response: Response | ResponseInfo | null): void;
 }
-export {};

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

@@ -571,7 +571,7 @@ export interface SchemaObjectField {
 		* 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
@@ -673,7 +673,7 @@ export interface ArrayField {
 		*
 		* Configures which extensions this array is allowed to use.
 		* Extensions are registered with the store's schema service
-		* via {@link SchemaService.registerDangerousArrayExtension}
+		* via {@link SchemaService.CAUTION_MEGA_DANGER_ZONE_registerExtension}
 		*
 		* Extensions should only be used for temporary enhancements
 		* to arrays to support migrating away from deprecated behaviors
@@ -786,7 +786,7 @@ export interface SchemaArrayField {
 		*
 		* Configures which extensions this array is allowed to use.
 		* Extensions are registered with the store's schema service
-		* via {@link SchemaService.registerDangerousArrayExtension}
+		* via {@link SchemaService.CAUTION_MEGA_DANGER_ZONE_registerExtension}
 		*
 		* Extensions should only be used for temporary enhancements
 		* to arrays to support migrating away from deprecated behaviors
@@ -800,7 +800,7 @@ export interface SchemaArrayField {
 		* 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
@@ -1285,6 +1285,9 @@ export interface LegacyBelongsToField {
 		*
 		* If null, the relationship is unidirectional.
 		*
+		* If the inverse field definition uses a sourceKey,
+		* this should still be the name of the field, not the sourceKey.
+		*
 		* @public
 		*/
 		inverse: string | null;
@@ -1307,8 +1310,9 @@ export interface LegacyBelongsToField {
 		*/
 		polymorphic?: boolean;
 		/**
-		* Whether this field should ever make use of the legacy support infra
-		* from @ember-data/model and the LegacyNetworkMiddleware for adapters and serializers.
+		* Whether this field should ever make use of the legacy request infra
+		* from @warp-drive/legacy/compat and the LegacyNetworkMiddleware for
+		* adapters and serializers.
 		*
 		* When true, none of the legacy support will be utilized. Sync relationships
 		* will be expected to already have all their data. When reloading a sync relationship
@@ -1433,6 +1437,9 @@ export interface LinksModeBelongsToField {
 		*
 		* If null, the relationship is unidirectional.
 		*
+		* If the inverse field definition uses a sourceKey,
+		* this should still be the name of the field, not the sourceKey.
+		*
 		* @public
 		*/
 		inverse: string | null;
@@ -1456,7 +1463,7 @@ export interface LinksModeBelongsToField {
 		polymorphic?: boolean;
 		/**
 		* Whether this field should ever make use of the legacy support infra
-		* from @ember-data/model and the LegacyNetworkMiddleware for adapters and serializers.
+		* from @warp-drive/legacy/model and the LegacyNetworkMiddleware for adapters and serializers.
 		*
 		* MUST be true for PolarisMode + LinksMode
 		*
@@ -1571,7 +1578,7 @@ export interface LegacyHasManyField {
 		*
 		* Configures which extensions this array is allowed to use.
 		* Extensions are registered with the store's schema service
-		* via {@link SchemaService.registerDangerousArrayExtension}
+		* via {@link SchemaService.CAUTION_MEGA_DANGER_ZONE_registerExtension}
 		*
 		* Extensions should only be used for temporary enhancements
 		* to arrays to support migrating away from deprecated behaviors
@@ -1604,6 +1611,9 @@ export interface LegacyHasManyField {
 		*
 		* If null, the relationship is unidirectional.
 		*
+		* If the inverse field definition uses a sourceKey,
+		* this should still be the name of the field, not the sourceKey.
+		*
 		* @public
 		*/
 		inverse: string | null;
@@ -1627,7 +1637,7 @@ export interface LegacyHasManyField {
 		polymorphic?: boolean;
 		/**
 		* Whether this field should ever make use of the legacy support infra
-		* from @ember-data/model and the LegacyNetworkMiddleware for adapters and serializers.
+		* from @warp-drive/legacy/model and the LegacyNetworkMiddleware for adapters and serializers.
 		*
 		* When true, none of the legacy support will be utilized. Sync relationships
 		* will be expected to already have all their data. When reloading a sync relationship
@@ -1742,7 +1752,7 @@ export interface LinksModeHasManyField {
 		*
 		* Configures which extensions this array is allowed to use.
 		* Extensions are registered with the store's schema service
-		* via {@link SchemaService.registerDangerousArrayExtension}
+		* via {@link SchemaService.CAUTION_MEGA_DANGER_ZONE_registerExtension}
 		*
 		* Extensions should only be used for temporary enhancements
 		* to arrays to support migrating away from deprecated behaviors
@@ -1777,6 +1787,9 @@ export interface LinksModeHasManyField {
 		*
 		* If null, the relationship is unidirectional.
 		*
+		* If the inverse field definition uses a sourceKey,
+		* this should still be the name of the field, not the sourceKey.
+		*
 		* @public
 		*/
 		inverse: string | null;
@@ -1800,7 +1813,7 @@ export interface LinksModeHasManyField {
 		polymorphic?: boolean;
 		/**
 		* Whether this field should ever make use of the legacy support infra
-		* from @ember-data/model and the LegacyNetworkMiddleware for adapters and serializers.
+		* from @warp-drive/legacy/model and the LegacyNetworkMiddleware for adapters and serializers.
 		*
 		* MUST be true for PolarisMode + LinksMode
 		*
@@ -2048,7 +2061,7 @@ export interface LegacyResourceSchema {
 	* Configures which extensions this resource 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
@@ -2116,7 +2129,7 @@ export interface ObjectSchema {
 	* 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

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

@@ -21,7 +21,7 @@ interface ObjectWithStringTypeProperty {
 * The primary requirement is merely that any information the service needs to correctly
 * respond to an inquest is available by the time it is asked.
 *
-* The `@ember-data/model` package provides an implementation of this service which
+* The `@warp-drive/legacy/model` package provides an implementation of this service which
 * makes use of your model classes as the source of information to respond to queries
 * about resource schema. While this is useful, this may not be ideal for your application.
 * For instance, Schema information could be sideloaded or pre-flighted for API calls,
@@ -32,7 +32,7 @@ interface ObjectWithStringTypeProperty {
 * hook to return an instance of your service.
 *
 * ```ts
-* import Store from '@ember-data/store';
+* import { Store } from '@warp-drive/core';
 * import CustomSchemas from './custom-schemas';
 *
 * export default class extends Store {
@@ -229,7 +229,7 @@ export interface SchemaService {
 	* be a string reference to a `transform`, and `options` which
 	* should be dictionary in which any key:value pairs are permissable.
 	*
-	* For instance, when using `@ember-data/model`, the following attribute
+	* For instance, when using `@warp-drive/legacy/model`, the following attribute
 	* definition:
 	*
 	* ```ts
@@ -283,7 +283,7 @@ export interface SchemaService {
 	* - `options.as` a string representing the abstract type that the concrete side of
 	*    a relationship must specify when fulfilling a polymorphic inverse.
 	*
-	* For example, the following Model using @ember-data/model would generate this relationships
+	* For example, the following Model using @warp-drive/legacy/model would generate this relationships
 	* definition by default:
 	*
 	* ```js

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

@@ -1,11 +1,21 @@
 import type { PersistedResourceKey } from "../identifier.js";
 import type { ApiError } from "./error.js";
 import type { Links, Meta, PaginationLinks } from "./json-api-raw.js";
+/**
+* This type represents a raw {json:api} document for a meta-only
+* document returned by a request intended to be inserted into the cache.
+*/
 export interface ResourceMetaDocument {
 	lid?: string;
 	meta: Meta;
 	links?: Links | PaginationLinks;
 }
+/**
+* This type represents a raw {json:api} document for a single resource
+* returned by a request intended to be inserted into the cache.
+*
+* For the Reactive value returned by a request using the store, use {@link ReactiveDataDocument} instead.
+*/
 export interface SingleResourceDataDocument<
 	T = PersistedResourceKey,
 	R = PersistedResourceKey
@@ -16,6 +26,12 @@ export interface SingleResourceDataDocument<
 	data: T | null;
 	included?: R[];
 }
+/**
+* This type represents a raw {json:api} document for a resource collection
+* returned by a request intended to be inserted into the cache.
+*
+* For the Reactive value returned by a request using the store, use {@link ReactiveDataDocument} instead.
+*/
 export interface CollectionResourceDataDocument<T = PersistedResourceKey> {
 	lid?: string;
 	links?: Links | PaginationLinks;
@@ -23,11 +39,29 @@ export interface CollectionResourceDataDocument<T = PersistedResourceKey> {
 	data: T[];
 	included?: T[];
 }
+/**
+* A type useful for representing the raw {json:api} documents that
+* the cache may use.
+*
+* For the Reactive value returned by a request using the store, use {@link ReactiveDataDocument} instead.
+*/
 export type ResourceDataDocument<T = PersistedResourceKey> = SingleResourceDataDocument<T> | CollectionResourceDataDocument<T>;
+/**
+* A type useful for representing the raw {json:api} Error documents that
+* the cache may use.
+*
+* For the Reactive value returned by a request using the store, use {@link ReactiveErrorDocument} instead.
+*/
 export interface ResourceErrorDocument {
 	lid?: string;
 	links?: Links | PaginationLinks;
 	meta?: Meta;
 	errors: ApiError[];
 }
+/**
+* A type useful for representing the raw {json:api} documents that
+* the cache may use.
+*
+* For the Reactive value returned by a request using the store, use {@link ReactiveDocument} instead.
+*/
 export type ResourceDocument<T = PersistedResourceKey> = ResourceMetaDocument | SingleResourceDataDocument<T> | CollectionResourceDataDocument<T> | ResourceErrorDocument;