@warp-drive/core 5.8.0-beta.0 → 5.8.0-beta.2

package/dist/types/record.js

@@ -61,4 +61,131 @@ function createIncludeValidator() {
     return includes;
   };
 }
+
+/**
+ * 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}
+ */
+
+/**
+ * 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 { createIncludeValidator };

package/dist/types/request.js

@@ -8,19 +8,22 @@ const IS_FUTURE = getOrSetGlobal('IS_FUTURE', Symbol('IS_FUTURE'));
 const STRUCTURED = getOrSetGlobal('DOC', Symbol('DOC'));
 
 /**
- * Use these options to adjust CacheHandler behavior for a request.
+ * Use these options to adjust {@link CacheHandler} behavior for a request
+ * via {@link RequestInfo.cacheOptions}.
  *
  */
 
 /**
- * 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.
  */
 
 /**
- * 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}
@@ -28,10 +31,12 @@ const STRUCTURED = getOrSetGlobal('DOC', Symbol('DOC'));
  */
 
 /**
- * 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)
  */
@@ -69,7 +74,4 @@ const STRUCTURED = getOrSetGlobal('DOC', Symbol('DOC'));
  *
  */
 
-function withBrand(obj) {
-  return obj;
-}
-export { EnableHydration, IS_FUTURE, STRUCTURED, SkipCache, withBrand };
+export { EnableHydration, IS_FUTURE, STRUCTURED, SkipCache };

package/dist/types/runtime.js

@@ -4,7 +4,7 @@ const RuntimeConfig = getOrSetUniversal('WarpDriveRuntimeConfig', {
 });
 function trySessionStorage() {
   // This works even when sessionStorage is not available.
-  // See https://github.com/emberjs/data/issues/9784
+  // See https://github.com/warp-drive-data/warp-drive/issues/9784
   try {
     return globalThis.sessionStorage;
   } catch {

package/dist/types/schema/fields.js

@@ -443,6 +443,20 @@
  * @public
  */
 
+/**
+ * A trait for use on a PolarisMode record
+ */
+
+/**
+ * A trait for use on a LegacyMode record
+ */
+
+/**
+ * A union of
+ * - {@link LegacyTrait}
+ * - {@link PolarisTrait}
+ */
+
 /**
  * A no-op type utility that enables type-checking resource schema
  * definitions.

package/dist/types/symbols.js

@@ -11,7 +11,7 @@ const RecordStore = getOrSetGlobal('Store', Symbol('Store'));
  * record implementations to provide a typescript
  * hint for the type of the resource.
  *
- * When used, EmberData/WarpDrive APIs can
+ * When used, WarpDrive APIs can
  * take advantage of this to provide better type
  * safety and intellisense.
  *
@@ -48,7 +48,7 @@ const Type = getOrSetGlobal('$type', Symbol('$type'));
  * record implementations to provide a typescript
  * hint for the type of the resource.
  *
- * When used, EmberData/WarpDrive APIs can
+ * When used, WarpDrive APIs can
  * take advantage of this to provide better type
  * safety and intellisense.
  *