@warp-drive/core 5.8.0-alpha.3 → 5.8.0-alpha.32

package/dist/unpkg/dev-deprecated/declarations/types/graph.d.ts

@@ -0,0 +1,47 @@
+import type { AddToResourceRelationshipMutation as AddResourceMutation, RemoveFromResourceRelationshipMutation as RemoveResourceMutation } from "./cache/mutations.js";
+import type { AddToResourceRelationshipOperation as AddResourceOperation, RemoveFromResourceRelationshipOperation as RemoveResourceOperation, UpdateResourceRelationshipOperation } from "./cache/operations.js";
+import type { ResourceKey } from "./identifier.js";
+import type { CollectionResourceRelationship, SingleResourceRelationship } from "./spec/json-api-raw.js";
+export interface Operation {
+	op: string;
+}
+export interface UpdateRelationshipOperation {
+	op: "updateRelationship";
+	record: ResourceKey;
+	field: string;
+	value: SingleResourceRelationship | CollectionResourceRelationship;
+}
+export interface DeleteRecordOperation {
+	op: "deleteRecord";
+	record: ResourceKey;
+	isNew: boolean;
+}
+export interface UnknownOperation {
+	op: "never";
+	record: ResourceKey;
+	field: string;
+}
+export interface ReplaceRelatedRecordOperation {
+	op: "replaceRelatedRecord";
+	record: ResourceKey;
+	field: string;
+	value: ResourceKey | null;
+	prior?: ResourceKey;
+	index?: number;
+}
+export interface SortRelatedRecords {
+	op: "sortRelatedRecords";
+	record: ResourceKey;
+	field: string;
+	value: ResourceKey[];
+}
+export interface ReplaceRelatedRecordsOperation {
+	op: "replaceRelatedRecords";
+	record: ResourceKey;
+	field: string;
+	value: ResourceKey[];
+	prior?: ResourceKey[];
+	index?: number;
+}
+export type RemoteRelationshipOperation = UpdateResourceRelationshipOperation | UpdateRelationshipOperation | ReplaceRelatedRecordOperation | ReplaceRelatedRecordsOperation | RemoveResourceOperation | AddResourceOperation | DeleteRecordOperation | SortRelatedRecords;
+export type LocalRelationshipOperation = ReplaceRelatedRecordsOperation | ReplaceRelatedRecordOperation | AddResourceMutation | RemoveResourceMutation | SortRelatedRecords;

package/dist/unpkg/dev-deprecated/declarations/types/identifier.d.ts

@@ -0,0 +1,86 @@
+export declare const DEBUG_CLIENT_ORIGINATED: unique symbol;
+export declare const DEBUG_KEY_TYPE: unique symbol;
+export declare const DEBUG_STALE_CACHE_OWNER: unique symbol;
+export declare const CACHE_OWNER: "__$co";
+export type CacheKeyType = "record" | "document";
+/**
+* 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
+*/
+export interface RequestKey {
+	lid: string;
+	type: "@document";
+}
+/** @deprecated use {@link RequestKey} */
+export type StableDocumentIdentifier = RequestKey;
+/**
+* Used when an ResourceKey is known to be the stable version
+*/
+interface ResourceKeyBase<T extends string = string> {
+	/**
+	* A string representing a unique identity.
+	*
+	* @public
+	*/
+	lid: string;
+	/**
+	* the primary `ResourceType` or "model name" this ResourceKey belongs to.
+	*
+	* @public
+	*/
+	type: T;
+}
+/**
+* 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.
+*/
+export interface PersistedResourceKey<T extends string = string> extends ResourceKeyBase<T> {
+	/**
+	* the PrimaryKey for the resource this ResourceKey represents.
+	*
+	* @public
+	*/
+	id: string;
+}
+/** @deprecated use {@link PersistedResourceKey} */
+export type StableExistingRecordIdentifier<T extends string = string> = PersistedResourceKey<T>;
+/**
+* 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.
+*/
+export interface NewResourceKey<T extends string = string> extends ResourceKeyBase<T> {
+	/**
+	* the PrimaryKey for the resource this ResourceKey represents. `null`
+	* if not yet assigned a PrimaryKey value.
+	*
+	* @public
+	*/
+	id: string | null;
+}
+/**
+* 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
+*/
+export type ResourceKey<T extends string = string> = PersistedResourceKey<T> | NewResourceKey<T>;
+/** @deprecated use {@link ResourceKey} */
+export type StableRecordIdentifier<T extends string = string> = ResourceKey<T>;
+export {};

package/dist/unpkg/dev-deprecated/declarations/types/json/raw.d.ts

@@ -0,0 +1,6 @@
+export type PrimitiveValue = string | number | boolean | null;
+export interface ObjectValue {
+	[key: string]: Value;
+}
+export type ArrayValue = Value[];
+export type Value = PrimitiveValue | ArrayValue | ObjectValue;

package/dist/unpkg/dev-deprecated/declarations/types/params.d.ts

@@ -0,0 +1,8 @@
+export type SerializablePrimitive = string | number | boolean | null;
+export type Serializable = SerializablePrimitive | SerializablePrimitive[];
+export type QueryParamsSerializationOptions = {
+	arrayFormat?: "bracket" | "indices" | "repeat" | "comma";
+};
+export type QueryParamsSource = ({
+	include?: string | string[];
+} & Record<Exclude<string, "include">, Serializable>) | URLSearchParams;

package/dist/unpkg/dev-deprecated/declarations/types/record.d.ts

@@ -0,0 +1,269 @@
+import type { Type } from "./symbols.js";
+/**
+* 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
+*/
+export 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.
+*
+*/
+export type TypeFromInstance<T> = T extends TypedRecordInstance ? T[typeof Type] : never;
+/**
+* A type utility that extracts the Type if available,
+* otherwise it returns string
+*
+*/
+export 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.
+*
+*/
+export 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.
+*
+*/
+export type Includes<
+	T extends TypedRecordInstance,
+	MAX_DEPTH extends _DEPTHCOUNT = DEFAULT_MAX_DEPTH
+> = ExtractUnion<MAX_DEPTH, T, true>;
+export type OpaqueRecordInstance = unknown;
+export type _StringSatisfiesIncludes<
+	T extends string,
+	SET extends string,
+	FT extends string
+> = T extends SET ? FT : T extends `${infer U},${infer V}` ? U extends SET ? _StringSatisfiesIncludes<V, Exclude<SET, U>, FT> : never : never;
+export type StringSatisfiesIncludes<
+	T extends string,
+	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 {};