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

package/dist/operations-D1qA6r0_.d.ts

@@ -0,0 +1,244 @@
+import { c as RequestKey, l as ResourceKey, s as PersistedResourceKey } from "./identifier-DQnqOSJK.js";
+import { i as Value } from "./raw-D5hnjiq7.js";
+import { a as ExistingResourceObject } from "./json-api-raw-C5APJHHB.js";
+import { n as Relationship } from "./relationship-CmHzMPKf.js";
+//#region src/types/cache/operations.d.ts
+/**
+ * All operations are objects with at least one property,
+ * `op` which contains a string with the name of the operation
+ * to perform.
+ */
+interface Op {
+  /**
+   * The name of the {@link Op | operation}
+   */
+  op: string;
+}
+/**
+ * Occasionally the Store discovers that two previously
+ * thought to be distinct resources refer to the same resource.
+ *
+ * This operation will be performed, giving the Cache the chance
+ * to cleanup and merge internal state as desired when this discovery
+ * is made.
+ */
+interface MergeOperation extends Op {
+  op: "mergeIdentifiers";
+  /**
+   * The stale {@link ResourceKey | ResourceKey} that
+   * the cache should eliminate in favor of {@link MergeOperation.value | value}
+   */
+  record: ResourceKey;
+  /**
+   * The kept {@link ResourceKey | ResourceKey} that
+   * the cache should also keep and merge {@link MergeOperation.record | record} into.
+   */
+  value: ResourceKey;
+}
+/**
+ * Removes a document and its associated request from
+ * the cache.
+ */
+interface RemoveDocumentOperation extends Op {
+  op: "remove";
+  /**
+   * The cache key for the request
+   */
+  record: RequestKey;
+}
+/**
+ * Removes a resource from the cache. This is treated
+ * as if a remote deletion has occurred, and all references
+ * to the resource should be eliminated.
+ */
+interface RemoveResourceOperation extends Op {
+  op: "remove";
+  /**
+   * The cache key for the resource
+   */
+  record: PersistedResourceKey;
+}
+/**
+ * Adds a resource to the cache.
+ */
+interface AddResourceOperation extends Op {
+  op: "add";
+  /**
+   * The cache key for the resource
+   */
+  record: PersistedResourceKey;
+  /**
+   * The data for the resource
+   */
+  value: ExistingResourceObject;
+}
+/**
+ * Upserts (merges) new state for a resource
+ */
+interface UpdateResourceOperation extends Op {
+  op: "update";
+  /**
+   * The cache key for the resource
+   */
+  record: PersistedResourceKey;
+  /**
+   * The new state to merge into the resource
+   */
+  value: ExistingResourceObject;
+}
+/**
+ * Replaces the state of a field with a new state
+ */
+interface UpdateResourceFieldOperation extends Op {
+  op: "update";
+  /**
+   * The cache key for the resource
+   */
+  record: PersistedResourceKey;
+  /**
+   * The name of the field to update
+   */
+  field: string;
+  /**
+   * The new value for the field
+   */
+  value: Value;
+}
+/**
+ * Replaces the state of a relationship with a new state
+ */
+interface UpdateResourceRelationshipOperation extends Op {
+  op: "update";
+  /**
+   * The cache key for the resource
+   */
+  record: PersistedResourceKey;
+  /**
+   * The name of the relationship to update
+   */
+  field: string;
+  /**
+   * The new state for the relationship
+   */
+  value: Relationship<PersistedResourceKey>;
+}
+/**
+ * Adds a resource to a request document, optionally
+ * at a specific index. This can be used to update the
+ * result of a request.
+ */
+interface AddToDocumentOperation extends Op {
+  op: "add";
+  /**
+   * The cache key for the request document
+   */
+  record: RequestKey;
+  /**
+   * Which member of the document to add to
+   */
+  field: "data" | "included";
+  /**
+   * The resource(s) to add
+   */
+  value: PersistedResourceKey | PersistedResourceKey[];
+  /**
+   * The index at which to insert the resource(s), if applicable
+   */
+  index?: number;
+}
+/**
+ * Adds the specified ResourceKeys to a relationship
+ */
+interface AddToResourceRelationshipOperation extends Op {
+  op: "add";
+  /**
+   * The cache key for the resource whose relationship is being updated
+   */
+  record: PersistedResourceKey;
+  /**
+   * The name of the relationship to add to
+   */
+  field: string;
+  /**
+   * The resource(s) to add to the relationship
+   */
+  value: PersistedResourceKey | PersistedResourceKey[];
+  /**
+   * The index at which to insert the resource(s), if applicable
+   */
+  index?: number;
+}
+/**
+ * Removes the specified ResourceKeys from a relationship
+ */
+interface RemoveFromResourceRelationshipOperation extends Op {
+  op: "remove";
+  /**
+   * The cache key for the resource whose relationship is being updated
+   */
+  record: PersistedResourceKey;
+  /**
+   * The name of the relationship to remove from
+   */
+  field: string;
+  /**
+   * The resource(s) to remove from the relationship
+   */
+  value: PersistedResourceKey | PersistedResourceKey[];
+  /**
+   * The index to remove the resource(s) from, if applicable
+   */
+  index?: number;
+}
+/**
+ * Removes a resource from a request document, optionally
+ * at a specific index. This can be used to update the
+ * result of a request.
+ */
+interface RemoveFromDocumentOperation extends Op {
+  op: "remove";
+  /**
+   * The cache key for the request document
+   */
+  record: RequestKey;
+  /**
+   * Which member of the document to remove from
+   */
+  field: "data" | "included";
+  /**
+   * The resource(s) to remove
+   */
+  value: PersistedResourceKey | PersistedResourceKey[];
+  /**
+   * The index to remove the resource(s) from, if applicable
+   */
+  index?: number;
+}
+/**
+ * {@link Cache} Operations perform updates to the
+ * Cache's "remote" (or clean) state to reflect external
+ * changes.
+ *
+ * Usually operations represent the result of a {@link WebSocket} or
+ * {@link EventSource | ServerEvent} message, though they can also be used to carefully
+ * patch the state of the cache with information known by the
+ * application or developer.
+ *
+ * Operations are applied via {@link Cache.patch}.
+ *
+ * See also:
+ * - {@link MergeOperation}
+ * - {@link RemoveResourceOperation}
+ * - {@link RemoveDocumentOperation}
+ * - {@link AddResourceOperation}
+ * - {@link UpdateResourceOperation}
+ * - {@link UpdateResourceFieldOperation}
+ * - {@link AddToResourceRelationshipOperation}
+ * - {@link RemoveFromResourceRelationshipOperation}
+ * - {@link AddToDocumentOperation}
+ * - {@link RemoveFromDocumentOperation}
+ */
+type Operation = MergeOperation | RemoveResourceOperation | RemoveDocumentOperation | AddResourceOperation | UpdateResourceOperation | UpdateResourceFieldOperation | AddToResourceRelationshipOperation | RemoveFromResourceRelationshipOperation | AddToDocumentOperation | RemoveFromDocumentOperation;
+//#endregion
+export { Op as a, RemoveFromDocumentOperation as c, UpdateResourceFieldOperation as d, UpdateResourceOperation as f, MergeOperation as i, RemoveFromResourceRelationshipOperation as l, AddToDocumentOperation as n, Operation as o, UpdateResourceRelationshipOperation as p, AddToResourceRelationshipOperation as r, RemoveDocumentOperation as s, AddResourceOperation as t, RemoveResourceOperation as u };
+//# sourceMappingURL=operations-D1qA6r0_.d.ts.map

package/dist/operations-D1qA6r0_.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations-D1qA6r0_.d.ts","names":[],"sources":["../src/types/cache/operations.ts"],"mappings":";;;;;;;;;;UA6BiB;;;;EAIf;;;;;;;;;;UAWe,uBAAuB;EACtC;;;;;EAKA,QAAQ;;;;;EAKR,OAAO;;;;;;UAOQ,gCAAgC;EAC/C;;;;EAIA,QAAQ;;;;;;;UAQO,gCAAgC;EAC/C;;;;EAIA,QAAQ;;;;;UAMO,6BAA6B;EAC5C;;;;EAIA,QAAQ;;;;EAIR,OAAO;;;;;UAKQ,gCAAgC;EAC/C;;;;EAIA,QAAQ;;;;EAIR,OAAO;;;;;UAKQ,qCAAqC;EACpD;;;;EAIA,QAAQ;;;;EAIR;;;;EAIA,OAAO;;;;;UAKQ,4CAA4C;EAC3D;;;;EAIA,QAAQ;;;;EAIR;;;;EAIA,OAAO,aAAa;;;;;;;UAQL,+BAA+B;EAC9C;;;;EAIA,QAAQ;;;;EAIR;;;;EAIA,OAAO,uBAAuB;;;;EAI9B;;;;;UAKe,2CAA2C;EAC1D;;;;EAIA,QAAQ;;;;EAIR;;;;EAIA,OAAO,uBAAuB;;;;EAI9B;;;;;UAKe,gDAAgD;EAC/D;;;;EAIA,QAAQ;;;;EAIR;;;;EAIA,OAAO,uBAAuB;;;;EAI9B;;;;;;;UAOe,oCAAoC;EACnD;;;;EAIA,QAAQ;;;;EAIR;;;;EAIA,OAAO,uBAAuB;;;;EAI9B;;;;;;;;;;;;;;;;;;;;;;;;;;KA2BU,YACR,iBACA,0BACA,0BACA,uBACA,0BACA,+BACA,qCACA,0CACA,yBACA"}

package/dist/params-DrEx3bf8.d.ts

@@ -0,0 +1,41 @@
+//#region src/types/params.d.ts
+/**
+ * A JSON-serializable primitive value, suitable for use as a single
+ * query parameter value.
+ */
+type SerializablePrimitive = string | number | boolean | null;
+/**
+ * A JSON-serializable value suitable for use as a query parameter value:
+ * either a {@link SerializablePrimitive} or an array of them.
+ */
+type Serializable = SerializablePrimitive | SerializablePrimitive[];
+/**
+ * Options for controlling how {@link QueryParamsSource} values are
+ * serialized into a URL query string.
+ */
+type QueryParamsSerializationOptions = {
+  /**
+   * How array values should be serialized:
+   *
+   * - `'bracket'` - `key[]=1&key[]=2`
+   * - `'indices'` - `key[0]=1&key[1]=2`
+   * - `'repeat'` - `key=1&key=2`
+   * - `'comma'` - `key=1,2`
+   */
+  arrayFormat?: "bracket" | "indices" | "repeat" | "comma";
+};
+/**
+ * The query parameters to serialize for a request: either a
+ * dictionary of {@link Serializable} values (with an optional
+ * `include` member for specifying relationships to sideload),
+ * or a native `URLSearchParams` instance.
+ */
+type QueryParamsSource = ({
+  /**
+   * the relationship paths to sideload, see {@link Includes}
+   */
+  include?: string | string[];
+} & Record<Exclude<string, "include">, Serializable>) | URLSearchParams;
+//#endregion
+export { SerializablePrimitive as i, QueryParamsSource as n, Serializable as r, QueryParamsSerializationOptions as t };
+//# sourceMappingURL=params-DrEx3bf8.d.ts.map

package/dist/params-DrEx3bf8.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"params-DrEx3bf8.d.ts","names":[],"sources":["../src/types/params.ts"],"mappings":";;;;;KAOY;;;;;KAMA,eAAe,wBAAwB;;;;;KAMvC;;;;;;;;;EASV;;;;;;;;KASU;;;;EAKN;IACE,OAAO,4BAA4B,iBACvC"}

package/dist/raw-D5hnjiq7.d.ts

@@ -0,0 +1,31 @@
+//#region src/types/json/raw.d.ts
+/**
+ * A JSON primitive: a string, number, boolean, or `null`.
+ *
+ * @public
+ */
+type PrimitiveValue = string | number | boolean | null;
+/**
+ * A plain JSON object, whose values are themselves valid {@link Value}s.
+ *
+ * @public
+ */
+interface ObjectValue {
+  [key: string]: Value;
+}
+/**
+ * A JSON array whose members are valid {@link Value}s.
+ *
+ * @public
+ */
+type ArrayValue = Value[];
+/**
+ * Any valid JSON value: a {@link PrimitiveValue}, an {@link ArrayValue}, or an
+ * {@link ObjectValue}.
+ *
+ * @public
+ */
+type Value = PrimitiveValue | ArrayValue | ObjectValue;
+//#endregion
+export { Value as i, ObjectValue as n, PrimitiveValue as r, ArrayValue as t };
+//# sourceMappingURL=raw-D5hnjiq7.d.ts.map

package/dist/raw-D5hnjiq7.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-D5hnjiq7.d.ts","names":[],"sources":["../src/types/json/raw.ts"],"mappings":";;;;;;KAKY;;;;;;UAOK;GACA,cAAA;;;;;;;KAQL,aAAa;;;;;;;KAQb,QAAQ,iBAAiB,aAAa"}

package/dist/reactive/-private.d.ts

@@ -0,0 +1,2 @@
+import { $t as ExtensibleField, F as PrivateReactiveResource, ft as Context, ut as ManagedArray } from "../internal-DtWOpxrR.js";
+export { Context, type ExtensibleField, type ManagedArray, type PrivateReactiveResource };

package/dist/reactive/-private.js

@@ -1 +1,3 @@
-export { a as Context } from "../symbols-3C1OkYtZ.js";
+import { r as Context } from "../-private-BYn1Vh-L.js";
+
+export { Context };

package/dist/reactive.d.ts

@@ -0,0 +1,2 @@
+import { C as getPromiseState, Ct as ReactiveDocument, I as ReactiveResource, L as checkout, N as instantiateRecord, P as teardownRecord, Qt as CAUTION_MEGA_DANGER_ZONE_Extension, R as commit, S as ResolvedPromise, St as ReactiveDataDocument, V as LegacyManyArray, _ as RequestState, an as registerDerivations, b as PromiseState, dt as Checkout, en as ExtensionDef, g as RequestLoadingState, h as createRequestSubscription, in as fromIdentity, lt as ReactiveResourceArray, nn as SchemaService, on as withDefaults, ot as LegacyQueryArray, p as RequestSubscription, rn as Transformation, st as LegacyLiveArray, tn as ProcessedExtension, v as getRequestState, wt as ReactiveErrorDocument, x as RejectedPromise, y as PendingPromise } from "./internal-DtWOpxrR.js";
+export { type CAUTION_MEGA_DANGER_ZONE_Extension, Checkout, type ExtensionDef, type LegacyLiveArray, type LegacyManyArray, type LegacyQueryArray, type PendingPromise, type ProcessedExtension, type PromiseState, type ReactiveDataDocument, type ReactiveDocument, type ReactiveErrorDocument, type ReactiveResource, type ReactiveResourceArray, type RejectedPromise, type RequestLoadingState, type RequestState, type RequestSubscription, type ResolvedPromise, SchemaService, type Transformation, checkout, commit, createRequestSubscription, fromIdentity, getPromiseState, getRequestState, instantiateRecord, registerDerivations, teardownRecord, withDefaults };

package/dist/reactive.js

@@ -1,4 +1,5 @@
-export { u as SchemaService, p as checkout, y as commit, v as fromIdentity, q as instantiateRecord, x as registerDerivations, t as teardownRecord, w as withDefaults } from "./index-CQP2NSqg.js";
-export { C as Checkout } from "./symbols-3C1OkYtZ.js";
-export { f as createRequestSubscription, i as getPromiseState, h as getRequestState } from "./configure-DPUFCemT.js";
-import '@embroider/macros';
+import { d as getRequestState, t as getPromiseState, u as createRequestSubscription } from "./-private-zrP4VGAf.js";
+import { t as Checkout } from "./-private-BYn1Vh-L.js";
+import { a as fromIdentity, c as instantiateRecord, d as commit, i as SchemaService, l as teardownRecord, o as registerDerivations, s as withDefaults, u as checkout } from "./src-BOAWJH_S.js";
+
+export { Checkout, SchemaService, checkout, commit, createRequestSubscription, fromIdentity, getPromiseState, getRequestState, instantiateRecord, registerDerivations, teardownRecord, withDefaults };

package/dist/record-D3QQcaIR.d.ts

@@ -0,0 +1,254 @@
+import { a as Type } from "./symbols-DjRDCeX0.js";
+//#region src/types/record.d.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
+ */
+interface TypedRecordInstance {
+  /**
+   * The type of the resource.
+   *
+   * This is an optional feature that can be used by
+   * record implementations to provide a typescript
+   * hint for the type of the resource.
+   *
+   * When used, WarpDrive APIs can
+   * take advantage of this to provide better type
+   * safety and intellisense.
+   *
+   * @property [Type]
+   * @type {Type}
+   * @type {String}
+   */
+  [Type]: string;
+}
+/**
+ * A type utility that extracts the Type if available,
+ * otherwise it returns never.
+ *
+ */
+type TypeFromInstance<T> = T extends TypedRecordInstance ? T[typeof Type] : never;
+/**
+ * A type utility that extracts the Type if available,
+ * otherwise it returns string
+ *
+ */
+type TypeFromInstanceOrString<T> = T extends TypedRecordInstance ? T[typeof Type] : string;
+type IsUniqueSymbol<T> = T extends `___(unique) Symbol(${string})` ? true : false;
+type Unpacked<T> = T extends (infer U)[] ? U : T;
+type NONE = {
+  __NONE: never;
+};
+type __InternalExtract<MAX_DEPTH extends _DEPTHCOUNT, T extends TypedRecordInstance, V extends TypedRecordInstance, IncludePrefix extends boolean, Ignore, Pre extends string, DEPTH extends _DEPTHCOUNT> = V extends T ? IncludePrefix extends false ? V[typeof Type] : Pre : V extends Ignore ? IncludePrefix extends false ? V[typeof Type] : Pre : IS_MAX_DEPTH<DEPTH, MAX_DEPTH> extends true ? Pre : ExtractUnion<MAX_DEPTH, V, IncludePrefix, Ignore | T, Pre, INC_DEPTH<DEPTH>>;
+type __ExtractIfRecord<MAX_DEPTH extends _DEPTHCOUNT, T extends TypedRecordInstance, V, IncludePrefix extends boolean, Ignore, Pre extends string, DEPTH extends _DEPTHCOUNT> = V extends TypedRecordInstance ? __InternalExtract<MAX_DEPTH, T, V, IncludePrefix, Ignore, Pre, DEPTH> : never;
+type _ExtractUnion<MAX_DEPTH extends _DEPTHCOUNT, T extends TypedRecordInstance, IncludePrefix extends boolean, Ignore, Pre, DEPTH extends _DEPTHCOUNT> = { [K in keyof T]: IsUniqueSymbol<K> extends true ? never : K extends string ? __ExtractIfRecord<MAX_DEPTH, T, Unpacked<Awaited<T[K]>>, IncludePrefix, Ignore, Pre extends string ? `${Pre}.${K}` : K, DEPTH> : never; }[keyof T];
+/**
+ * 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.
+ *
+ */
+type ExtractUnion<MAX_DEPTH extends _DEPTHCOUNT, T extends TypedRecordInstance, IncludePrefix extends boolean = false, Ignore = NONE, Pre = NONE, DEPTH extends _DEPTHCOUNT = 1> = Exclude<IncludePrefix extends true ? _ExtractUnion<MAX_DEPTH, T, IncludePrefix, Ignore, Pre, DEPTH> | Pre : _ExtractUnion<MAX_DEPTH, T, IncludePrefix, Ignore, Pre, DEPTH> | T[typeof Type], NONE>;
+type _DEPTHCOUNT = 1 | 2 | 3 | 4 | 5;
+type INC_DEPTH<START extends _DEPTHCOUNT> = START extends 1 ? 2 : START extends 2 ? 3 : START extends 3 ? 4 : 5;
+type IS_MAX_DEPTH<DEPTH extends _DEPTHCOUNT, MAX_DEPTH extends _DEPTHCOUNT = DEFAULT_MAX_DEPTH> = DEPTH extends MAX_DEPTH ? true : false;
+type DEFAULT_MAX_DEPTH = 3;
+/**
+ * A utility that provides the union of all ResourceName for all potential
+ * includes for the given TypedRecordInstance.
+ *
+ */
+type ExtractSuggestedCacheTypes<T extends TypedRecordInstance, MAX_DEPTH extends _DEPTHCOUNT = DEFAULT_MAX_DEPTH> = ExtractUnion<MAX_DEPTH, T>;
+/**
+ * A utility that provides the union type of all valid include paths for the given
+ * TypedRecordInstance.
+ *
+ * Cyclical paths are filtered out.
+ *
+ */
+type Includes<T extends TypedRecordInstance, MAX_DEPTH extends _DEPTHCOUNT = DEFAULT_MAX_DEPTH> = ExtractUnion<MAX_DEPTH, T, true>;
+/**
+ * A type-erased placeholder for a record instance, used where the
+ * specific record type is not known or not relevant.
+ */
+type OpaqueRecordInstance = unknown;
+/**
+ * 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';
+ * ```
+ */
+type StringSatisfiesIncludes<T extends string, SET extends string> = _StringSatisfiesIncludes<T, SET, T>;
+/**
+ * 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');
+ * ```
+ */
+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}
+ */
+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}
+ */
+type Validate<K extends object, T extends K> = T extends K ? K : never;
+//#endregion
+export { StringSatisfiesIncludes as a, TypedRecordInstance as c, OpaqueRecordInstance as i, Validate as l, Includes as n, TypeFromInstance as o, Mask as r, TypeFromInstanceOrString as s, ExtractSuggestedCacheTypes as t, createIncludeValidator as u };
+//# sourceMappingURL=record-D3QQcaIR.d.ts.map

package/dist/record-D3QQcaIR.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-D3QQcaIR.d.ts","names":[],"sources":["../src/types/record.ts"],"mappings":";;;;;;;;;;;;;UAaiB;;;;;;;;;;;;;;;;GAgBd;;;;;;;KAQS,iBAAiB,KAAK,UAAU,sBAAsB,SAAS;;;;;;KAO/D,yBAAyB,KAAK,UAAU,sBAAsB,SAAS;KAE9E,eAAe,KAAK;KACpB,SAAS,KAAK,iBAAiB,OAAO,IAAI;KAC1C;EAAS;;KAET,kBACH,kBAAkB,aAClB,UAAU,qBACV,UAAU,qBACV,+BACA,QACA,oBACA,cAAc,eAGd,UAAU,IACN,8BACE,SAAS,QACT,MAEF,UAAU,SACR,8BACE,SAAS,QACT,MAEF,aAAa,OAAO,0BAClB,MAEA,aAAa,WAAW,GAAG,eAAe,SAAS,GAAG,KAAK,UAAU;KAE1E,kBACH,kBAAkB,aAClB,UAAU,qBACV,GACA,+BACA,QACA,oBACA,cAAc,eACZ,UAAU,sBAAsB,kBAAkB,WAAW,GAAG,GAAG,eAAe,QAAQ,KAAK;KAE9F,cACH,kBAAkB,aAClB,UAAU,qBACV,+BACA,QACA,KACA,cAAc,kBAGb,WAAW,IAAI,eAAe,0BAE3B,mBAEE,kBACE,WACA,GACA,SAAS,QAAQ,EAAE,MACnB,eACA,QACA,wBAAwB,OAAO,MAAM,GACrC,wBAIF;;;;;;;;;;;;;;;;;;KAmBH,aACH,kBAAkB,aAClB,UAAU,qBACV,uCACA,SAAS,MACT,MAAM,MACN,cAAc,mBACZ,QACF,6BAEI,cAAc,WAAW,GAAG,eAAe,QAAQ,KAAK,SAAS,MAEjE,cAAc,WAAW,GAAG,eAAe,QAAQ,KAAK,SAAS,SAAS,OAC9E;KAGG;KACA,UAAU,cAAc,eAAe,sBAAsB,sBAAsB;KACnF,aACH,cAAc,aACd,kBAAkB,cAAc,qBAC9B,cAAc;KACb;;;;;;KAMO,2BACV,UAAU,qBACV,kBAAkB,cAAc,qBAC9B,aAAa,WAAW;;;;;;;;KAShB,SAAS,UAAU,qBAAqB,kBAAkB,cAAc,qBAAqB,aACvG,WACA;;;;;KAQU;;;;;;;;;;;;;;;;;;KA8BA,wBAAwB,kBAAkB,sBAAsB,yBAAyB,GAAG,KAAK;;;;;;;;;;;;;;;iBAgB7F,uBAAuB,UAAU,yBACd,kBAAkB,UAAU,wBAAwB,GAAG,SAAS,QAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA8E7F,KAAK,kBAAkB,UAAU,QAC1C,WAAW,IAAI,gBAAgB,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAsDjE,SAAS,kBAAkB,UAAU,KAAK,UAAU,IAAI"}

package/dist/relationship-CmHzMPKf.d.ts

@@ -0,0 +1,65 @@
+import { l as ResourceKey } from "./identifier-DQnqOSJK.js";
+import { d as Meta, m as PaginationLinks, u as Links } from "./json-api-raw-C5APJHHB.js";
+//#region src/types/cache/relationship.d.ts
+/**
+ * The stable-cache-key form of a `to-one` {@link SingleResourceRelationship | relationship}.
+ *
+ * Unlike {@link SingleResourceRelationship}, `data` is always in the
+ * stable {@link ResourceKey} form rather than a raw resource identifier.
+ *
+ * @example
+ * ```ts
+ * const relationship: ResourceRelationship = { data: resourceKey };
+ * ```
+ */
+interface ResourceRelationship<T = ResourceKey> {
+  /**
+   * the related resource, or `null` if the relationship has no related resource
+   */
+  data?: T | null;
+  /**
+   * meta information about the relationship
+   */
+  meta?: Meta;
+  /**
+   * links related to the relationship
+   */
+  links?: Links;
+}
+/**
+ * The stable-cache-key form of a `to-many` {@link CollectionResourceRelationship | relationship}.
+ *
+ * Unlike {@link CollectionResourceRelationship}, each entry in `data` is
+ * always in the stable {@link ResourceKey} form rather than a raw resource
+ * identifier.
+ *
+ * @example
+ * ```ts
+ * const relationship: CollectionRelationship = { data: [resourceKey] };
+ * ```
+ */
+interface CollectionRelationship<T = ResourceKey> {
+  /**
+   * the related resources
+   */
+  data?: T[];
+  /**
+   * meta information about the relationship
+   */
+  meta?: Meta;
+  /**
+   * links related to the relationship, including pagination links
+   */
+  links?: PaginationLinks;
+}
+/**
+ * The stable-cache-key form of a relationship, whether `to-one` or `to-many`.
+ *
+ * See also:
+ * - {@link ResourceRelationship}
+ * - {@link CollectionRelationship}
+ */
+type Relationship<T = ResourceKey> = ResourceRelationship<T> | CollectionRelationship<T>;
+//#endregion
+export { Relationship as n, ResourceRelationship as r, CollectionRelationship as t };
+//# sourceMappingURL=relationship-CmHzMPKf.d.ts.map

package/dist/relationship-CmHzMPKf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-CmHzMPKf.d.ts","names":[],"sources":["../src/types/cache/relationship.ts"],"mappings":";;;;;;;;;;;;;;UAsBiB,qBAAqB,IAAI;;;;EAIxC,OAAO;;;;EAIP,OAAO;;;;EAIP,QAAQ;;;;;;;;;;;;;;UAeO,uBAAuB,IAAI;;;;EAI1C,OAAO;;;;EAIP,OAAO;;;;EAIP,QAAQ;;;;;;;;;KAUE,aAAa,IAAI,eAAe,qBAAqB,KAAK,uBAAuB"}