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

package/dist/unpkg/dev/types/identifier.js

@@ -1,61 +1,68 @@
-// provided for additional debuggability
-const DEBUG_CLIENT_ORIGINATED = Symbol('record-originated-on-client');
-const DEBUG_KEY_TYPE = Symbol('key-type');
-const DEBUG_STALE_CACHE_OWNER = Symbol('warpDriveStaleCache');
+//#region src/types/identifier.ts
+/**
+* @private
+*/ const DEBUG_CLIENT_ORIGINATED = Symbol("record-originated-on-client");
+/**
+* @private
+*/
+const DEBUG_KEY_TYPE = Symbol("key-type");
+/**
+* @private
+*/
+const DEBUG_STALE_CACHE_OWNER = Symbol("warpDriveStaleCache");
 function ProdSymbol(str, debugStr) {
-  return Symbol(debugStr);
+	return Symbol(debugStr);
 }
-
-// also present in production
-const CACHE_OWNER = ProdSymbol('__$co', 'CACHE_OWNER');
-
-/**
- * A referentially stable object with a unique string (lid) that can be used
- * as a reference to request data in the cache.
- *
- * Only requests that are assigned a RequestKey are retrievable/replayable from
- * the cache, though requests without RequestKeys may still update cache state.
- *
- * @public
- */
-
+/**
+* @private
+*/
+const CACHE_OWNER = ProdSymbol("__$co", "CACHE_OWNER");
+/**
+* Identifies which "bucket" of the cache a key belongs to: resources
+* (`'record'`, see {@link ResourceKey}) or request documents
+* (`'document'`, see {@link RequestKey}).
+*/
+/**
+* A referentially stable object with a unique string (lid) that can be used
+* as a reference to request data in the cache.
+*
+* Only requests that are assigned a RequestKey are retrievable/replayable from
+* the cache, though requests without RequestKeys may still update cache state.
+*
+* @public
+*/
 /** @deprecated use {@link RequestKey} */
-
-/**
- * Used when an ResourceKey is known to be the stable version
- */
-
-/**
- * Used when a ResourceKey was not created locally as part
- * of a call to store.createRecord
- *
- * Distinguishing between this ResourceKey and one for a client created
- * resource that was created with an ID is generally speaking not possible
- * at runtime, so anything with an ID typically narrows to this.
- */
-
+/**
+* Used when an ResourceKey is known to be the stable version
+*/
+/**
+* Used when a ResourceKey was not created locally as part
+* of a call to store.createRecord
+*
+* Distinguishing between this ResourceKey and one for a client created
+* resource that was created with an ID is generally speaking not possible
+* at runtime, so anything with an ID typically narrows to this.
+*/
 /** @deprecated use {@link PersistedResourceKey} */
-
-/**
- * Used when a ResourceKey was created locally
- * (by a call to store.createRecord).
- *
- * It is possible in rare circumstances to have a ResourceKey
- * that is not for a new record but does not have an ID. This would
- * happen if a user intentionally created one for use with a secondary-index
- * prior to the record having been fully loaded.
- */
-
-/**
- * A referentially stable object with a unique string (lid) that can be used
- * as a reference to data in the cache.
- *
- * Every resource has a unique ResourceKey, and ResourceKeys may refer
- * to data that has never been loaded (for instance, in an async relationship).
- *
- * @public
- */
-
+/**
+* Used when a ResourceKey was created locally
+* (by a call to store.createRecord).
+*
+* It is possible in rare circumstances to have a ResourceKey
+* that is not for a new record but does not have an ID. This would
+* happen if a user intentionally created one for use with a secondary-index
+* prior to the record having been fully loaded.
+*/
+/**
+* A referentially stable object with a unique string (lid) that can be used
+* as a reference to data in the cache.
+*
+* Every resource has a unique ResourceKey, and ResourceKeys may refer
+* to data that has never been loaded (for instance, in an async relationship).
+*
+* @public
+*/
 /** @deprecated use {@link ResourceKey} */
-
-export { CACHE_OWNER, DEBUG_CLIENT_ORIGINATED, DEBUG_KEY_TYPE, DEBUG_STALE_CACHE_OWNER };
+//#endregion
+export { CACHE_OWNER, DEBUG_CLIENT_ORIGINATED, DEBUG_KEY_TYPE, DEBUG_STALE_CACHE_OWNER };
+//# sourceMappingURL=identifier.js.map

package/dist/unpkg/dev/types/identifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifier.js","names":["DEBUG_CLIENT_ORIGINATED","Symbol","DEBUG_KEY_TYPE","DEBUG_STALE_CACHE_OWNER","ProdSymbol","str","debugStr","CACHE_OWNER"],"sources":["../../../../src/types/identifier.ts"],"sourcesContent":["import { DEBUG } from '@warp-drive/core/build-config/env';\n\n// provided for additional debuggability\n/**\n * @private\n */\nexport const DEBUG_CLIENT_ORIGINATED: unique symbol = Symbol('record-originated-on-client');\n/**\n * @private\n */\nexport const DEBUG_KEY_TYPE: unique symbol = Symbol('key-type');\n/**\n * @private\n */\nexport const DEBUG_STALE_CACHE_OWNER: unique symbol = Symbol('warpDriveStaleCache');\n\nfunction ProdSymbol<T extends string>(str: T, debugStr: string): T {\n  return DEBUG ? (Symbol(debugStr) as unknown as T) : str;\n}\n\n// also present in production\n/**\n * @private\n */\nexport const CACHE_OWNER: '__$co' = ProdSymbol('__$co', 'CACHE_OWNER');\n\n/**\n * Identifies which \"bucket\" of the cache a key belongs to: resources\n * (`'record'`, see {@link ResourceKey}) or request documents\n * (`'document'`, see {@link RequestKey}).\n */\nexport type CacheKeyType = 'record' | 'document';\n\n/**\n * A referentially stable object with a unique string (lid) that can be used\n * as a reference to request data in the cache.\n *\n * Only requests that are assigned a RequestKey are retrievable/replayable from\n * the cache, though requests without RequestKeys may still update cache state.\n *\n * @public\n */\nexport interface RequestKey {\n  /**\n   * A string representing a unique identity.\n   */\n  lid: string;\n  /**\n   * Discriminates a {@link RequestKey} from a {@link ResourceKey}.\n   */\n  type: '@document';\n  /** @internal */\n  [CACHE_OWNER]: number | undefined;\n}\n\n/** @deprecated use {@link RequestKey} */\nexport type StableDocumentIdentifier = RequestKey;\n\n/**\n * Used when an ResourceKey is known to be the stable version\n */\ninterface ResourceKeyBase<T extends string = string> {\n  /**\n   * A string representing a unique identity.\n   *\n   * @public\n   */\n  lid: string;\n\n  /**\n   * the primary `ResourceType` or \"model name\" this ResourceKey belongs to.\n   *\n   * @public\n   */\n  type: T;\n\n  /** @internal */\n  [CACHE_OWNER]: number | undefined;\n\n  /** @internal */\n  [DEBUG_CLIENT_ORIGINATED]?: boolean;\n  /** @internal */\n  [DEBUG_STALE_CACHE_OWNER]?: number | undefined;\n}\n\n/**\n * Used when a ResourceKey was not created locally as part\n * of a call to store.createRecord\n *\n * Distinguishing between this ResourceKey and one for a client created\n * resource that was created with an ID is generally speaking not possible\n * at runtime, so anything with an ID typically narrows to this.\n */\nexport interface PersistedResourceKey<T extends string = string> extends ResourceKeyBase<T> {\n  /**\n   * the PrimaryKey for the resource this ResourceKey represents.\n   *\n   * @public\n   */\n  id: string;\n}\n\n/** @deprecated use {@link PersistedResourceKey} */\nexport type StableExistingRecordIdentifier<T extends string = string> = PersistedResourceKey<T>;\n\n/**\n * Used when a ResourceKey was created locally\n * (by a call to store.createRecord).\n *\n * It is possible in rare circumstances to have a ResourceKey\n * that is not for a new record but does not have an ID. This would\n * happen if a user intentionally created one for use with a secondary-index\n * prior to the record having been fully loaded.\n */\nexport interface NewResourceKey<T extends string = string> extends ResourceKeyBase<T> {\n  /**\n   * the PrimaryKey for the resource this ResourceKey represents. `null`\n   * if not yet assigned a PrimaryKey value.\n   *\n   * @public\n   */\n  id: string | null;\n}\n\n/**\n * A referentially stable object with a unique string (lid) that can be used\n * as a reference to data in the cache.\n *\n * Every resource has a unique ResourceKey, and ResourceKeys may refer\n * to data that has never been loaded (for instance, in an async relationship).\n *\n * @public\n */\nexport type ResourceKey<T extends string = string> = PersistedResourceKey<T> | NewResourceKey<T>;\n\n/** @deprecated use {@link ResourceKey} */\nexport type StableRecordIdentifier<T extends string = string> = ResourceKey<T>;\n"],"mappings":";;;GAMA,MAAaA,0BAAyCC,OAAO,6BAA6B;;;;AAI1F,MAAaC,iBAAgCD,OAAO,UAAU;;;;AAI9D,MAAaE,0BAAyCF,OAAO,qBAAqB;AAElF,SAASG,WAA6BC,KAAQC,UAAqB;CACjE,OAAgBL,OAAOK,QAAQ;AACjC;;;;AAMA,MAAaC,cAAuBH,WAAW,SAAS,aAAa"}

package/dist/unpkg/dev/types/record.js

@@ -1,191 +1,221 @@
+//#region src/types/record.ts
 /**
- * Records may be anything, They don't even
- * have to be objects.
- *
- * Whatever they are, if they have a Type
- * property, that property will be used by WarpDrive
- * and WarpDrive to provide better type safety and
- * intellisense.
- *
- * @class TypedRecordInstance
- */
-
+* Records may be anything, They don't even
+* have to be objects.
+*
+* Whatever they are, if they have a Type
+* property, that property will be used by WarpDrive
+* and WarpDrive to provide better type safety and
+* intellisense.
+*
+* @class TypedRecordInstance
+*/
 /**
- * A type utility that extracts the Type if available,
- * otherwise it returns never.
- *
- */
-
+* A type utility that extracts the Type if available,
+* otherwise it returns never.
+*
+*/
 /**
- * A type utility that extracts the Type if available,
- * otherwise it returns string
- *
- */
-
+* A type utility that extracts the Type if available,
+* otherwise it returns string
+*
+*/
 /**
- * A Utility that extracts either resource types or resource paths from a TypedRecordInstance.
- *
- * Its limitations are mostly around its intentional non-recursiveness. It presumes that APIs which
- * implement includes will not allow cyclical include paths, and will collapse includes by type.
- *
- * This follows closer to the JSON:API fields spec than to the includes spec in nature, but in
- * practice it is so impracticle for an API to allow z-algo include paths that this is probably
- * reasonable.
- *
- * We may need to revisit this in the future, opting to either make this restriction optional or
- * to allow for other strategies.
- *
- * There's a 90% chance this particular implementation belongs being in the JSON:API package instead
- * of core-types, but it's here for now.
- *
- */
-
+* A Utility that extracts either resource types or resource paths from a TypedRecordInstance.
+*
+* Its limitations are mostly around its intentional non-recursiveness. It presumes that APIs which
+* implement includes will not allow cyclical include paths, and will collapse includes by type.
+*
+* This follows closer to the JSON:API fields spec than to the includes spec in nature, but in
+* practice it is so impracticle for an API to allow z-algo include paths that this is probably
+* reasonable.
+*
+* We may need to revisit this in the future, opting to either make this restriction optional or
+* to allow for other strategies.
+*
+* There's a 90% chance this particular implementation belongs being in the JSON:API package instead
+* of core-types, but it's here for now.
+*
+*/
 /**
- * A utility that provides the union of all ResourceName for all potential
- * includes for the given TypedRecordInstance.
- *
- */
-
-// ToPaths<ExpandIgnore<T, true>, false>;
-
+* A utility that provides the union of all ResourceName for all potential
+* includes for the given TypedRecordInstance.
+*
+*/
 /**
- * A utility that provides the union type of all valid include paths for the given
- * TypedRecordInstance.
- *
- * Cyclical paths are filtered out.
- *
- */
-
+* A utility that provides the union type of all valid include paths for the given
+* TypedRecordInstance.
+*
+* Cyclical paths are filtered out.
+*
+*/
+/**
+* A type-erased placeholder for a record instance, used where the
+* specific record type is not known or not relevant.
+*/
+/**
+* @internal
+*/
+/**
+* Validates that the comma-separated-string `T` (e.g. `'company,company.ceo,friends'`)
+* only contains paths present in the union `SET` (typically {@link Includes}).
+*
+* TypeScript cannot autocomplete against this type; prefer {@link createIncludeValidator}
+* for a better development experience unless you are writing a similar wrapper utility.
+*
+* @example
+* ```ts
+* import type { StringSatisfiesIncludes, Includes } from '@warp-drive/core/types/record';
+*
+* const includes: StringSatisfiesIncludes<
+*   'company,company.ceo,friends',
+*   Includes<User>
+* > = 'company,company.ceo,friends';
+* ```
+*/
+/**
+* Creates a runtime validator function for comma-separated `include` strings,
+* ensuring at compile time that only valid paths for `T` (per {@link Includes})
+* are supplied.
+*
+* @example
+* ```ts
+* import { createIncludeValidator } from '@warp-drive/core/types/record';
+*
+* const userIncludesValidator = createIncludeValidator<User>;
+*
+* userIncludesValidator('company,company.ceo,friends');
+* ```
+*/
 function createIncludeValidator() {
-  return function validateIncludes(includes) {
-    return includes;
-  };
+	return function validateIncludes(includes) {
+		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 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 };
+* 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}
+*/
+//#endregion
+export { createIncludeValidator };
+//# sourceMappingURL=record.js.map

package/dist/unpkg/dev/types/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","names":["createIncludeValidator","validateIncludes","includes"],"sources":["../../../../src/types/record.ts"],"sourcesContent":["import type { Type } from './symbols.ts';\n\n/**\n * Records may be anything, They don't even\n * have to be objects.\n *\n * Whatever they are, if they have a Type\n * property, that property will be used by WarpDrive\n * and WarpDrive to provide better type safety and\n * intellisense.\n *\n * @class TypedRecordInstance\n */\nexport interface TypedRecordInstance {\n  /**\n   * The type of the resource.\n   *\n   * This is an optional feature that can be used by\n   * record implementations to provide a typescript\n   * hint for the type of the resource.\n   *\n   * When used, WarpDrive APIs can\n   * take advantage of this to provide better type\n   * safety and intellisense.\n   *\n   * @property [Type]\n   * @type {Type}\n   * @type {String}\n   */\n  [Type]: string;\n}\n\n/**\n * A type utility that extracts the Type if available,\n * otherwise it returns never.\n *\n */\nexport type TypeFromInstance<T> = T extends TypedRecordInstance ? T[typeof Type] : never;\n\n/**\n * A type utility that extracts the Type if available,\n * otherwise it returns string\n *\n */\nexport type TypeFromInstanceOrString<T> = T extends TypedRecordInstance ? T[typeof Type] : string;\n\ntype IsUniqueSymbol<T> = T extends `___(unique) Symbol(${string})` ? true : false;\ntype Unpacked<T> = T extends (infer U)[] ? U : T;\ntype NONE = { __NONE: never };\n\ntype __InternalExtract<\n  MAX_DEPTH extends _DEPTHCOUNT,\n  T extends TypedRecordInstance,\n  V extends TypedRecordInstance,\n  IncludePrefix extends boolean,\n  Ignore,\n  Pre extends string,\n  DEPTH extends _DEPTHCOUNT,\n> =\n  // if we extend T, we return the leaf value\n  V extends T\n    ? IncludePrefix extends false\n      ? V[typeof Type]\n      : Pre\n    : // else if we are in Ignore we add the lead and exit\n      V extends Ignore\n      ? IncludePrefix extends false\n        ? V[typeof Type]\n        : Pre\n      : // else if we are at max depth, we return never\n        IS_MAX_DEPTH<DEPTH, MAX_DEPTH> extends true\n        ? Pre\n        : // else add T to Ignore and recurse\n          ExtractUnion<MAX_DEPTH, V, IncludePrefix, Ignore | T, Pre, INC_DEPTH<DEPTH>>;\n\ntype __ExtractIfRecord<\n  MAX_DEPTH extends _DEPTHCOUNT,\n  T extends TypedRecordInstance,\n  V,\n  IncludePrefix extends boolean,\n  Ignore,\n  Pre extends string,\n  DEPTH extends _DEPTHCOUNT,\n> = V extends TypedRecordInstance ? __InternalExtract<MAX_DEPTH, T, V, IncludePrefix, Ignore, Pre, DEPTH> : never;\n\ntype _ExtractUnion<\n  MAX_DEPTH extends _DEPTHCOUNT,\n  T extends TypedRecordInstance,\n  IncludePrefix extends boolean,\n  Ignore,\n  Pre,\n  DEPTH extends _DEPTHCOUNT,\n> = {\n  // for each string key in the record,\n  [K in keyof T]: IsUniqueSymbol<K> extends true\n    ? never\n    : K extends string\n      ? // we recursively extract any values that resolve to a TypedRecordInstance\n        __ExtractIfRecord<\n          MAX_DEPTH,\n          T,\n          Unpacked<Awaited<T[K]>>,\n          IncludePrefix,\n          Ignore,\n          Pre extends string ? `${Pre}.${K}` : K,\n          DEPTH\n        >\n      : never;\n  // then we return any value that is not 'never'\n}[keyof T];\n\n/**\n * A Utility that extracts either resource types or resource paths from a TypedRecordInstance.\n *\n * Its limitations are mostly around its intentional non-recursiveness. It presumes that APIs which\n * implement includes will not allow cyclical include paths, and will collapse includes by type.\n *\n * This follows closer to the JSON:API fields spec than to the includes spec in nature, but in\n * practice it is so impracticle for an API to allow z-algo include paths that this is probably\n * reasonable.\n *\n * We may need to revisit this in the future, opting to either make this restriction optional or\n * to allow for other strategies.\n *\n * There's a 90% chance this particular implementation belongs being in the JSON:API package instead\n * of core-types, but it's here for now.\n *\n */\ntype ExtractUnion<\n  MAX_DEPTH extends _DEPTHCOUNT,\n  T extends TypedRecordInstance,\n  IncludePrefix extends boolean = false,\n  Ignore = NONE,\n  Pre = NONE,\n  DEPTH extends _DEPTHCOUNT = 1,\n> = Exclude<\n  IncludePrefix extends true\n    ? // if we want to include prefix, we union with the prefix. Outer Exclude will filter any \"NONE\" types\n      _ExtractUnion<MAX_DEPTH, T, IncludePrefix, Ignore, Pre, DEPTH> | Pre\n    : // Else we just union the types.\n      _ExtractUnion<MAX_DEPTH, T, IncludePrefix, Ignore, Pre, DEPTH> | T[typeof Type],\n  NONE\n>;\n\ntype _DEPTHCOUNT = 1 | 2 | 3 | 4 | 5;\ntype INC_DEPTH<START extends _DEPTHCOUNT> = START extends 1 ? 2 : START extends 2 ? 3 : START extends 3 ? 4 : 5;\ntype IS_MAX_DEPTH<\n  DEPTH extends _DEPTHCOUNT,\n  MAX_DEPTH extends _DEPTHCOUNT = DEFAULT_MAX_DEPTH,\n> = DEPTH extends MAX_DEPTH ? true : false;\ntype DEFAULT_MAX_DEPTH = 3;\n/**\n * A utility that provides the union of all ResourceName for all potential\n * includes for the given TypedRecordInstance.\n *\n */\nexport type ExtractSuggestedCacheTypes<\n  T extends TypedRecordInstance,\n  MAX_DEPTH extends _DEPTHCOUNT = DEFAULT_MAX_DEPTH,\n> = ExtractUnion<MAX_DEPTH, T>; // ToPaths<ExpandIgnore<T, true>, false>;\n\n/**\n * A utility that provides the union type of all valid include paths for the given\n * TypedRecordInstance.\n *\n * Cyclical paths are filtered out.\n *\n */\nexport type Includes<T extends TypedRecordInstance, MAX_DEPTH extends _DEPTHCOUNT = DEFAULT_MAX_DEPTH> = ExtractUnion<\n  MAX_DEPTH,\n  T,\n  true\n>;\n\n/**\n * A type-erased placeholder for a record instance, used where the\n * specific record type is not known or not relevant.\n */\nexport type OpaqueRecordInstance = unknown;\n\n/**\n * @internal\n */\nexport type _StringSatisfiesIncludes<T extends string, SET extends string, FT extends string> = T extends SET\n  ? FT\n  : T extends `${infer U},${infer V}`\n    ? U extends SET\n      ? _StringSatisfiesIncludes<V, Exclude<SET, U>, FT>\n      : never\n    : never;\n\n/**\n * Validates that the comma-separated-string `T` (e.g. `'company,company.ceo,friends'`)\n * only contains paths present in the union `SET` (typically {@link Includes}).\n *\n * TypeScript cannot autocomplete against this type; prefer {@link createIncludeValidator}\n * for a better development experience unless you are writing a similar wrapper utility.\n *\n * @example\n * ```ts\n * import type { StringSatisfiesIncludes, Includes } from '@warp-drive/core/types/record';\n *\n * const includes: StringSatisfiesIncludes<\n *   'company,company.ceo,friends',\n *   Includes<User>\n * > = 'company,company.ceo,friends';\n * ```\n */\nexport type StringSatisfiesIncludes<T extends string, SET extends string> = _StringSatisfiesIncludes<T, SET, T>;\n\n/**\n * Creates a runtime validator function for comma-separated `include` strings,\n * ensuring at compile time that only valid paths for `T` (per {@link Includes})\n * are supplied.\n *\n * @example\n * ```ts\n * import { createIncludeValidator } from '@warp-drive/core/types/record';\n *\n * const userIncludesValidator = createIncludeValidator<User>;\n *\n * userIncludesValidator('company,company.ceo,friends');\n * ```\n */\nexport function createIncludeValidator<T extends TypedRecordInstance>() {\n  return function validateIncludes<U extends string>(includes: StringSatisfiesIncludes<U, Includes<T>>): U {\n    return includes;\n  };\n}\n\n/**\n * A utility that takes two types, K and T, and produces a new type that is a \"mask\" of T based on K.\n *\n * That's a mouthful, so let's break it down:\n *\n * Let's say you have a User type and an Address type.\n *\n * ```ts\n * interface Address {\n *   street: string;\n *   city: string;\n *   state: string;\n *   zip: string;\n * }\n *\n * interface User {\n *   name: string;\n *   title: string;\n *   address: Address;\n * }\n * ```\n *\n * Now, imagine you want to load a preview of the user with some information about their address,\n * but you don't want to load the entire user or address. You probably want to still ensure\n * the type of the data you do load matches the underlying Address and User types, but doesn't\n * include everything.\n *\n * If you did this manually, you might do something like this:\n *\n * ```ts\n * interface UserPreview {\n *   name: string;\n *   address: AddressPreview;\n * }\n *\n * interface AddressPreview {\n *   city: string;\n * }\n * ```\n *\n * From a TypeScript performance perspective, this is the best way to approach these preview\n * types, but this is also tedious and error-prone, especially if the User or Address types change.\n *\n * For Address, we could create a validated type using `Pick`:\n *\n * ```ts\n * type AddressPreview = Pick<Address, 'city'>;\n * ```\n *\n * This ensures that if the Address type changes, our AddressPreview will still be valid.\n * However, for UserPreview, we can't just use `Pick` because the `address` property is of type `Address`,\n * not `AddressPreview`. This is where the `Mask` type comes in.\n *\n * With `Mask`, we define the `UserPreview` in two parts\n * - first, we define the subset of fields we want to include from `User`, using `Pick` or an interface.\n * - then, we use `Mask` to replace the related types of fields like Address with their more limited subset.\n *\n * Here's how we can do it:\n *\n * ```ts\n * // First, we define the base of UserPreview with Pick\n * type UserPreviewBase = Pick<User, 'name' | 'address'>;\n * // Then, we use Mask to replace Address with AddressPreview\n * type UserPreview = Mask<{ address: AddressPreview }, UserPreviewBase>;\n * ```\n *\n * Now, `UserPreview` will have the `name` field from `User` and the `address` field will be of type `AddressPreview`.\n * This way, if the `User` or `Address` types change, TypeScript will ensure that our `UserPreview` and `AddressPreview`\n * types remain valid and consistent with the underlying types.\n *\n * But what if your app has data with massive interfaces such that the TypeScript performance of this\n * approach becomes a problem? In that case, see {@link Validate}\n */\nexport type Mask<K extends object, T extends K> = {\n  [P in keyof T]: P extends keyof K ? (T[P] extends K[P] ? K[P] : never) : T[P];\n};\n\n/**\n * A utility that takes two types, K and T, and ensures that K is a valid subset of T.\n *\n * That's a mouthful, so let's break it down:\n *\n * Let's say you have a User type and an Address type.\n *\n * ```ts\n * interface Address {\n *   street: string;\n *   city: string;\n *   state: string;\n *   zip: string;\n * }\n *\n * interface User {\n *   name: string;\n *   title: string;\n *   address: Address;\n * }\n * ```\n *\n * Now, imagine you want to load a preview of the user with some information about their address,\n * but you don't want to load the entire user or address. You probably want to still ensure\n * the type of the data you do load matches the underlying Address and User types, but doesn't\n * include everything.\n *\n * You might do something like this:\n *\n * ```ts\n * interface UserPreview {\n *   name: string;\n *   address: AddressPreview;\n * }\n *\n * interface AddressPreview {\n *   city: string;\n * }\n * ```\n *\n * From a TypeScript performance perspective, this is the best way to approach these preview\n * types, but this is also error-prone, especially if the User or Address types change.\n *\n * Validate can help ensure that your preview types remain valid.\n *\n * ```ts\n * type IsValidUserPreview = Validate<UserPreview, User>; // This will be valid\n * ```\n *\n * For help creating subsets of types, see {@link Mask}\n */\nexport type Validate<K extends object, T extends K> = T extends K ? K : never;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgOA,SAAgBA,yBAAwD;CACtE,OAAO,SAASC,iBAAmCC,UAAsD;EACvG,OAAOA;CACT;AACF"}