@warp-drive/core 5.8.0-alpha.11 → 5.8.0-alpha.12

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/dist/types/-private.js

@@ -1,6 +1,6 @@
 import { macroCondition, getGlobalConfig } from '@embroider/macros';
 const name = "@warp-drive/core";
-const version = "5.8.0-alpha.11";
+const version = "5.8.0-alpha.12";
 
 // in testing mode, we utilize globals to ensure only one copy exists of
 // these maps, due to bugs in ember-auto-import

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warp-drive/core",
-  "version": "5.8.0-alpha.11",
+  "version": "5.8.0-alpha.12",
   "description": "Core package for WarpDrive | All the Universal Basics",
   "keywords": [
     "ember-addon"
@@ -37,13 +37,13 @@
   },
   "dependencies": {
     "@embroider/macros": "^1.18.1",
-    "@warp-drive/build-config": "5.8.0-alpha.11"
+    "@warp-drive/build-config": "5.8.0-alpha.12"
   },
   "devDependencies": {
     "@babel/core": "^7.28.3",
     "@babel/plugin-transform-typescript": "^7.28.0",
     "@babel/preset-typescript": "^7.27.1",
-    "@warp-drive/internal-config": "5.8.0-alpha.11",
+    "@warp-drive/internal-config": "5.8.0-alpha.12",
     "decorator-transforms": "^2.3.0",
     "ember-source": "~6.6.0",
     "expect-type": "^1.2.2",