@warp-drive/core 5.8.0-alpha.4 → 5.8.0-alpha.40

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

@@ -4,18 +4,18 @@ import type { PrivateRequestManager, RequestManager } from "../../request/-priva
 import type { Cache } from "../../types/cache.js";
 import type { PersistedResourceKey, ResourceKey } from "../../types/identifier.js";
 import type { TypedRecordInstance, TypeFromInstance } from "../../types/record.js";
+import type { SchemaService } from "../../types/schema/schema-service.js";
 import type { CollectionResourceDocument, EmptyResourceDocument, JsonApiDocument, ResourceIdentifierObject, SingleResourceDocument } from "../../types/spec/json-api-raw.js";
 import type { Type } from "../../types/symbols.js";
 import type { CacheCapabilitiesManager } from "../-types/q/cache-capabilities-manager.js";
 import type { OpaqueRecordInstance } from "../-types/q/record-instance.js";
-import type { SchemaService } from "../-types/q/schema-service.js";
 import type { StoreRequestInput } from "./cache-handler/handler.js";
 import type { CachePolicy } from "./cache-handler/types.js";
 import { InstanceCache, storeFor } from "./caches/instance-cache.js";
 import type { PrivateCacheKeyManager } from "./managers/cache-key-manager.js";
 import { CacheKeyManager } from "./managers/cache-key-manager.js";
 import type { PrivateNotificationManager } from "./managers/notification-manager.js";
-import NotificationManager from "./managers/notification-manager.js";
+import { NotificationManager } from "./managers/notification-manager.js";
 import type { PrivateRecordArrayManager } from "./managers/record-array-manager.js";
 import type { PrivateRequestStateService } from "./network/request-cache.js";
 import { RequestStateService } from "./network/request-cache.js";
@@ -101,7 +101,7 @@ export interface Store {
 	* For Example, to use the default SchemaService for ReactiveResource
 	*
 	* ```ts
-	* import { SchemaService } from '@warp-drive/schema-record';
+	* import { SchemaService } from '@warp-drive/core/reactive';
 	*
 	* class extends Store {
 	*   createSchemaService() {
@@ -110,10 +110,10 @@ export interface Store {
 	* }
 	* ```
 	*
-	* Or to use the SchemaService for @ember-data/model
+	* Or to use the SchemaService for @warp-drive/legacy/model
 	*
 	* ```ts
-	* import { buildSchema } from '@ember-data/model';
+	* import { buildSchema } from '@warp-drive/legacy/model';
 	*
 	* class extends Store {
 	*   createSchemaService() {
@@ -125,13 +125,13 @@ export interface Store {
 	* If you wish to chain services, you must either
 	* instantiate each schema source directly or super to retrieve
 	* an existing service. For convenience, when migrating from
-	* `@ember-data/model` to `@warp-drive/schema-record` a
+	* `@warp-drive/legacy/model` to {@link ReactiveResource} a
 	* SchemaService is provided that handles this transition
 	* for you:
 	*
 	* ```ts
-	* import { DelegatingSchemaService } from '@ember-data/model/migration-support';
-	* import { SchemaService } from '@warp-drive/schema-record';
+	* import { DelegatingSchemaService } from '@warp-drive/legacy/model/migration-support';
+	* import { SchemaService } from '@warp-drive/core/reactive';
 	*
 	* class extends Store {
 	*   createSchemaService() {
@@ -176,7 +176,7 @@ export interface Store {
 	* For Example:
 	*
 	* ```ts
-	* import Store from '@ember-data/store';
+	* import { Store } from '@warp-drive/core';
 	*
 	* class SchemaDelegator {
 	*   constructor(schema) {
@@ -210,7 +210,6 @@ export interface Store {
 	* }
 	* ```
 	*
-	* @param {SchemaService} schema
 	* @deprecated
 	* @public
 	*/
@@ -230,7 +229,7 @@ export interface Store {
 	* For Example:
 	*
 	* ```ts
-	* import Store from '@ember-data/store';
+	* import { Store } from '@warp-drive/core';
 	*
 	* class SchemaDelegator {
 	*   constructor(schema) {
@@ -264,7 +263,6 @@ export interface Store {
 	* }
 	* ```
 	*
-	* @param {SchemaService} schema
 	* @deprecated
 	* @public
 	*/
@@ -290,7 +288,7 @@ export interface Store {
 */
 export declare class Store extends BaseClass {
 	/**
-	* Provides access to the NotificationManager associated
+	* Provides access to the {@link NotificationManager} associated
 	* with this Store instance.
 	*
 	* The NotificationManager can be used to subscribe to
@@ -321,20 +319,18 @@ export declare class Store extends BaseClass {
 	*/
 	readonly cacheKeyManager: CacheKeyManager;
 	/**
-	* Provides access to the requestManager instance associated
+	* Provides access to the {@link RequestManager} instance associated
 	* with this Store instance.
 	*
-	* When using `ember-data` this property is automatically
-	* set to an instance of `RequestManager`. When not using `ember-data`
-	* you must configure this property yourself, either by declaring
-	* it as a service or by initializing it.
+	* See also:
+	* - {@link Fetch}
+	* - {@link CacheHandlerInterface | CacheHandler (Interface)}
+	* - {@link CacheHandler | CacheHandler (Class)}
 	*
 	* ```ts
-	* import Store, { CacheHandler } from '@ember-data/store';
-	* import RequestManager from '@ember-data/request';
-	* import Fetch from '@ember-data/request/fetch';
+	* import { CacheHandler, Fetch, RequestManager, Store } from '@warp-drive/core';
 	*
-	* class extends Store {
+	* class AppStore extends Store {
 	*   requestManager = new RequestManager()
 	*    .use([Fetch])
 	*    .useCache(CacheHandler);
@@ -350,9 +346,9 @@ export declare class Store extends BaseClass {
 	*
 	* Note, when defined, these methods will only be invoked if a
 	* cache key exists for the request, either because the request
-	* contains `cacheOptions.key` or because the [CacheKeyManager](/ember-data/release/classes/CacheKeyManager)
+	* contains `cacheOptions.key` or because the {@link CacheKeyManager}
 	* was able to generate a key for the request using the configured
-	* [generation method](/ember-data/release/functions/@ember-data%2Fstore/setIdentifierGenerationMethod).
+	* {@link setIdentifierGenerationMethod | generation method}.
 	*
 	* `isSoftExpired` will only be invoked if `isHardExpired` returns `false`.
 	*
@@ -557,14 +553,10 @@ export declare class Store extends BaseClass {
 	otherwise it will return `null`. A record is available if it has been fetched earlier, or
 	pushed manually into the store.
 	
-	See [findRecord](../methods/findRecord?anchor=findRecord) if you would like to request this record from the backend.
-	
-	_Note: This is a synchronous method and does not return a promise._
-	
 	**Example 1**
 	
-	```js
-	let post = store.peekRecord('post', '1');
+	```ts
+	const post = store.peekRecord('post', '1');
 	
 	post.id; // '1'
 	```
@@ -575,8 +567,8 @@ export declare class Store extends BaseClass {
 	
 	**Example 2**
 	
-	```js
-	let post = store.peekRecord({ type: 'post', id });
+	```ts
+	const post = store.peekRecord({ type: 'post', id: '1' });
 	post.id; // '1'
 	```
 	
@@ -590,40 +582,34 @@ export declare class Store extends BaseClass {
 	post.id; // '1'
 	```
 	
-	
 	@since 1.13.0
 	@public
-	@param {String|object} modelName - either a string representing the modelName or a ResourceIdentifier object containing both the type (a string) and the id (a string) for the record or an lid (a string) of an existing record
-	@param {String|Integer} id - optional only if the first param is a ResourceIdentifier, else the string id of the record to be retrieved.
-	@return {Model|null} record
+	@param type - either a string representing the modelName or a ResourceIdentifier object containing both the type (a string) and the id (a string) for the record or an lid (a string) of an existing record
+	@param id - optional only if the first param is a ResourceIdentifier, else the string id of the record to be retrieved.
 	*/
 	peekRecord<T>(type: TypeFromInstance<T>, id: string | number): T | null;
 	peekRecord(type: string, id: string | number): unknown | null;
 	peekRecord<T>(identifier: ResourceIdentifierObject<TypeFromInstance<T>>): T | null;
 	peekRecord(identifier: ResourceIdentifierObject): unknown | null;
 	/**
-	This method returns a filtered array that contains all of the
-	known records for a given type in the store.
+	This method returns the {@link LegacyLiveArray} that contains all of the
+	known records for a given type in the store. Each ResourceType has only
+	one LiveArray instance, so multiple calls to `peekAll` with the same type
+	will always return the same instance.
 	
-	Note that because it's just a filter, the result will contain any
+	Note that because it's a LiveArray, the result will contain any
 	locally created records of the type, however, it will not make a
-	request to the backend to retrieve additional records. If you
-	would like to request all the records from the backend please use
-	[store.findAll](../methods/findAll?anchor=findAll).
-	
-	Also note that multiple calls to `peekAll` for a given type will always
-	return the same `RecordArray`.
+	request to the backend to retrieve additional records.
 	
 	Example
 	
-	```javascript
-	let localPosts = store.peekAll('post');
+	```ts
+	const allPosts = store.peekAll('post');
 	```
 	
 	@since 1.13.0
 	@public
-	@param {String} type the name of the resource
-	@return {RecordArray}
+	@param type the name of the resource
 	*/
 	peekAll<T>(type: TypeFromInstance<T>): LegacyLiveArray<T>;
 	peekAll(type: string): LegacyLiveArray;
@@ -708,7 +694,7 @@ export declare class Store extends BaseClass {
 	For this model:
 	
 	```js [app/models/person.js]
-	import Model, { attr, hasMany } from '@ember-data/model';
+	import Model, { attr, hasMany } from '@warp-drive/legacy/model';
 	
 	export default class PersonRoute extends Route {
 	@attr('string') firstName;
@@ -775,23 +761,17 @@ export declare class Store extends BaseClass {
 	}
 	```
 	
-	If you're streaming data or implementing an adapter, make sure
-	that you have converted the incoming data into this form. The
-	store's [normalize](../methods/normalize?anchor=normalize) method is a convenience
-	helper for converting a json payload into the form Ember Data
-	expects.
-	
-	```js
-	store.push(store.normalize('person', data));
-	```
+	If you're streaming data, or implementing response handling, make sure
+	that you have converted the incoming data into this form.
 	
 	This method can be used both to push in brand new
 	records, as well as to update existing records.
 	
+	See also {@link Cache.patch}
+	
 	@public
-	@param {Object} data
-	@return the record(s) that was created or
-	updated.
+	@param data
+	@return the primary record(s) that created or updated.
 	*/
 	push(data: EmptyResourceDocument): null;
 	push<T>(data: SingleResourceDocument<TypeFromInstance<T>>): T;
@@ -803,8 +783,7 @@ export declare class Store extends BaseClass {
 	without creating materialized records.
 	
 	@private
-	@param {Object} jsonApiDoc
-	@return {ResourceKey|Array<ResourceKey>|null} identifiers for the primary records that had data loaded
+	@return identifiers for the primary records that had data loaded
 	*/
 	_push(jsonApiDoc: JsonApiDocument, asyncFlush?: boolean): PersistedResourceKey | PersistedResourceKey[] | null;
 	/**

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

@@ -22,7 +22,6 @@ export { normalizeModelName as _deprecatingNormalize } from "./-private/utils/no
 export type { StoreRequestInput } from "./-private/cache-handler/handler.js";
 export { type LegacyManyArray, type LegacyManyArray as RelatedCollection, createLegacyManyArray } from "./-private/record-arrays/legacy-many-array.js";
 export { log, logGroup } from "./-private/debug/utils.js";
-export { getPromiseState, type PromiseState } from "./-private/new-core-tmp/promise-state.js";
 export { DISPOSE, createRequestSubscription, type RequestArgs, type SubscriptionArgs, type RequestComponentArgs, type RequestSubscription, type ContentFeatures, type RecoveryFeatures, type AutorefreshBehaviorCombos, type AutorefreshBehaviorType } from "./-private/new-core-tmp/request-subscription.js";
 export { getRequestState, type RequestLoadingState, type RequestCacheRequestState as RequestState } from "./-private/new-core-tmp/request-state.js";
 export { type SignalHooks, waitFor } from "./-private/new-core-tmp/reactivity/configure.js";

package/declarations/store/-types/q/cache-capabilities-manager.d.ts

@@ -1,7 +1,7 @@
 import type { RequestKey, ResourceKey } from "../../../types/identifier.js";
+import type { SchemaService } from "../../../types/schema/schema-service.js";
 import type { CacheKeyManager } from "../../-private/managers/cache-key-manager.js";
 import type { NotificationType } from "../../-private/managers/notification-manager.js";
-import type { SchemaService } from "./schema-service.js";
 /**
 * CacheCapabilitiesManager provides encapsulated API access to the minimal
 * subset of the Store's functionality that Cache implementations

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

@@ -42,7 +42,7 @@ export type KeyOrString<T> = keyof T & string extends never ? string : keyof T &
 * "model" class.
 *
 * Only used when using the legacy schema-service implementation
-* for @ember-data/model or when wrapping schema for legacy
+* for @warp-drive/legacy/model or when wrapping schema for legacy
 * Adapters/Serializers.
 *
 */

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

@@ -248,13 +248,13 @@ declare module "../-private/store-service" {
 		}
 		```
 		
-		See [peekRecord](../methods/peekRecord?anchor=peekRecord) to get the cached version of a record.
+		See {@link Store.peekRecord | peekRecord} to get the cached version of a record.
 		
 		### Retrieving Related Model Records
 		
-		If you use an adapter such as Ember's default
-		[`JSONAPIAdapter`](/ember-data/release/classes/JSONAPIAdapter)
-		that supports the [JSON API specification](http://jsonapi.org/) and if your server
+		If you use an adapter such as the
+		[JSONAPIAdapter](/api/@warp-drive/legacy/adapter/json-api/classes/JSONAPIAdapter)
+		which supports the [{json:api} specification](http://jsonapi.org/) and if your server
 		endpoint supports the use of an
 		['include' query parameter](http://jsonapi.org/format/#fetching-includes),
 		you can use `findRecord()` or `findAll()` to automatically retrieve additional records related to
@@ -421,7 +421,7 @@ declare module "../-private/store-service" {
 		records in the store:
 		
 		```js [app/adapters/application.js]
-		import Adapter from '@ember-data/adapter';
+		import { Adapter } from '@warp-drive/legacy/adapter';
 		
 		export default class ApplicationAdapter extends Adapter {
 		shouldReloadAll(store, snapshotsArray) {
@@ -498,13 +498,13 @@ declare module "../-private/store-service" {
 		}
 		```
 		
-		See [peekAll](../methods/peekAll?anchor=peekAll) to get an array of current records in the
+		See {@link Store.peekAll | peekAll} to get an array of current records in the
 		store, without waiting until a reload is finished.
 		
 		### Retrieving Related Model Records
 		
-		If you use an adapter such as Ember's default
-		[`JSONAPIAdapter`](/ember-data/release/classes/JSONAPIAdapter)
+		If you use an adapter such as the default
+		[JSONAPIAdapter](/api/@warp-drive/legacy/adapter/json-api/classes/JSONAPIAdapter)
 		that supports the [JSON API specification](http://jsonapi.org/) and if your server
 		endpoint supports the use of an
 		['include' query parameter](http://jsonapi.org/format/#fetching-includes),
@@ -535,7 +535,7 @@ declare module "../-private/store-service" {
 		}
 		```
 		
-		See [query](../methods/query?anchor=query) to only get a subset of records from the server.
+		See {@link Store.query | query} to only get a subset of records from the server.
 		
 		@public
 		@deprecated use {@link Store.request} instead
@@ -575,7 +575,7 @@ declare module "../-private/store-service" {
 		
 		If you do something like this:
 		
-		```javascript
+		```js
 		store.query('person', { ids: ['1', '2', '3'] });
 		```
 		
@@ -602,7 +602,7 @@ declare module "../-private/store-service" {
 		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)
+		beforehand (if the `id` is known, use {@link Store.findRecord | findRecord}
 		instead).
 		
 		This method can be used when it is certain that the server will return a
@@ -611,37 +611,40 @@ declare module "../-private/store-service" {
 		Each time this method is called a new request is made through the adapter.
 		
 		Let's assume our API provides an endpoint for the currently logged in user
-		via:
 		
-		```
-		// GET /api/current_user
+		```ts
+		// GET /api/user/me
 		{
-		user: {
-		id: 1234,
+		data: {
+		type: 'user',
+		id: '1234',
+		attributes: {
 		username: 'admin'
 		}
 		}
+		}
 		```
 		
 		Since the specific `id` of the `user` is not known beforehand, we can use
 		`queryRecord` to get the user:
 		
-		```javascript
-		store.queryRecord('user', {}).then(function(user) {
-		let username = user.username;
-		// do thing
-		});
+		```ts
+		const user = await store.queryRecord('user', { me: true });
+		user.username; // admin
 		```
 		
 		The request is made through the adapters' `queryRecord`:
 		
-		```js [app/adapters/user.js]
-		import Adapter from '@ember-data/adapter';
-		import $ from 'jquery';
+		```ts [app/adapters/user.ts]
+		import Adapter from '@warp-drive/legacy/adapter';
 		
 		export default class UserAdapter extends Adapter {
-		queryRecord(modelName, query) {
-		return $.getJSON('/api/current_user');
+		async queryRecord(modelName, query) {
+		if (query.me) {
+		const response = await fetch('/api/me');
+		return await response.json();
+		}
+		throw new Error('Unsupported query');
 		}
 		}
 		```
@@ -664,7 +667,7 @@ declare module "../-private/store-service" {
 		}
 		```
 		
-		```javascript
+		```js
 		store.query('user', { username: 'unique' }).then(function(users) {
 		return users.firstObject;
 		}).then(function(user) {
@@ -684,7 +687,7 @@ declare module "../-private/store-service" {
 		}
 		```
 		
-		```javascript
+		```js
 		store.queryRecord('user', { username: 'unique' }).then(function(user) {
 		// user is null
 		});
@@ -744,7 +747,7 @@ declare module "../-private/store-service" {
 		/**
 		Returns the schema for a particular resource type (modelName).
 		
-		When used with Model from @ember-data/model the return is the model class,
+		When used with [Model](/api/@warp-drive/legacy/model/classes/Model) the return is the model class,
 		but this is not guaranteed.
 		
 		If looking to query attribute or relationship information it is
@@ -754,9 +757,7 @@ declare module "../-private/store-service" {
 		signatures.
 		
 		The class of a model might be useful if you want to get a list of all the
-		relationship names of the model, see
-		[`relationshipNames`](/ember-data/release/classes/Model?anchor=relationshipNames)
-		for example.
+		relationship names of the model.
 		
 		@public
 		@deprecated use {@link Store.schema} instead

package/declarations/store.d.ts

@@ -1 +1,2 @@
 export { DefaultCachePolicy, type PolicyConfig, type CacheControlValue, parseCacheControl } from "./store/-private/default-cache-policy.js";
+export type { NotificationManager } from "./store/-private/managers/notification-manager.js";

package/declarations/types/cache.d.ts

@@ -7,7 +7,7 @@ import type { RequestKey, ResourceKey } from "./identifier.js";
 import type { Value } from "./json/raw.js";
 import type { TypeFromInstanceOrString } from "./record.js";
 import type { RequestContext, StructuredDataDocument, StructuredDocument } from "./request.js";
-import type { ResourceDocument, SingleResourceDataDocument } from "./spec/document.js";
+import type { CollectionResourceDataDocument, ResourceDocument, SingleResourceDataDocument } from "./spec/document.js";
 import type { ApiError } from "./spec/error.js";
 /**
 * A hash of changed attributes with the key being the attribute name and the value being an
@@ -253,23 +253,25 @@ export interface Cache {
 	*
 	* @public
 	*/
-	willCommit(cacheKey: ResourceKey, context: RequestContext | null): void;
+	willCommit(cacheKey: ResourceKey | ResourceKey[], context: RequestContext | null): void;
 	/**
 	* [LIFECYCLE] Signals to the cache that a resource
 	* was successfully updated as part of a save transaction.
 	*
 	* @public
-	* @param the primary ResourceKey that was operated on
-	* @param data - a document in the cache format containing any updated data
+	* @param cacheKey - the primary ResourceKey that was operated on
+	* @param result - a document in the cache format containing any updated data
 	*/
-	didCommit(cacheKey: ResourceKey, result: StructuredDataDocument<unknown> | null): SingleResourceDataDocument;
+	didCommit(cacheKey: ResourceKey, result: StructuredDataDocument<SingleResourceDataDocument> | null): SingleResourceDataDocument;
+	didCommit(cacheKey: ResourceKey[], result: StructuredDataDocument<SingleResourceDataDocument> | null): SingleResourceDataDocument;
+	didCommit(cacheKey: ResourceKey[], result: StructuredDataDocument<CollectionResourceDataDocument> | null): CollectionResourceDataDocument;
 	/**
 	* [LIFECYCLE] Signals to the cache that a resource
 	* was update via a save transaction failed.
 	*
 	* @public
 	*/
-	commitWasRejected(cacheKey: ResourceKey, errors?: ApiError[]): void;
+	commitWasRejected(cacheKey: ResourceKey | ResourceKey[], errors?: ApiError[]): void;
 	/**
 	* [LIFECYCLE] Signals to the cache that all data for a resource
 	* should be cleared.

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 {};