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

package/declarations/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/declarations/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/declarations/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/declarations/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/declarations/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/declarations/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/declarations/reactive/-private.d.ts

@@ -1,2 +1,2 @@
-export { Context } from "./-private/symbols.js";
-export type { PrivateReactiveResource } from "./-private/record.js";
+import { Jn as ExtensibleField, ct as Context, j as PrivateReactiveResource, ot as ManagedArray } from "../internal-Cz-893zD.js";
+export { Context, type ExtensibleField, type ManagedArray, type PrivateReactiveResource };

package/declarations/reactive.d.ts

@@ -1,286 +1,2 @@
-/**
-* # About
-*
-* This module provides an implementation of reactive objects that a Store may use for creating
-* reactive representations of the raw data for requests, resources and their relationships
-* stored in the cache.
-*
-* - For configuring the store to use these reactive objects, see [The Setup Guide](/guides/configuration/)
-* - For defining resource schemas, see [The Schema Guide](/guides/the-manual/schemas/)
-*
-* Any method that returns a record instance will use the `instantiateRecord`
-* hook configured above to instantiate a ReactiveResource once this is in place.
-* After that, its up to you what ReactiveResource can do.
-*
-* ## Modes
-*
-* ReactiveResource has two modes: `legacy` and `polaris`.
-*
-* **LegacyMode** can be used to emulate the behaviors and capabilities of WarpDrive's `Model` class,
-* and because there is little distinction between Model and a ReactiveResource in LegacyMode we refer
-* to both of these approaches as LegacyMode. This mode is the default experience in V5.
-*
-* In LegacyMode:
-*
-* - records are mutable
-* - local changes immediately reflect app wide
-* - records have all the APIs of Model (references, state props, currentState, methods etc)
-* - the continued use of `@warp-drive/legacy` is required (though most imports from it can be removed)
-* - `async: true` relationships are supported (but not recommended outside of [LinksMode](/guides/the-manual/misc/links-mode.md))
-*
-* ---
-*
-* **PolarisMode** is an upcoming suite of features that will become the default experience in V6.
-*
-* In PolarisMode:
-*
-* - records are immutable, unless creating a new resource or explicitly checking out a record for editing
-* - local changes are isolated until committed, displaying only via the editable version of the record
-* - records have a more limited API, focused on only what is in their schema.
-* - some common operations may have more friction to perform because intended utilities are not yet available
-* - `async: true` relationships are not supported (see [LinksMode](/guides/the-manual/misc/links-mode.md))
-* - The `@warp-drive/legacy` package is not required
-*
-* These modes are interopable. The reactive object (record) for a resource in PolarisMode can relate to
-* a record in LegacyMode and vice-versa. This interopability is true whether the record in LegacyMode is
-* a ReactiveResource or a Model.
-*
-* ---
-*
-* ## Basic Usage
-*
-* ReactiveResource is a reactive object that transforms raw data from an associated
-* cache into reactive data backed by Signals.
-*
-* The shape of the object and the transformation of raw cache data into its
-* reactive form is controlled by a resource schema.
-*
-* For instance, lets say your API is a [{json:api}](https://jsonapi.org) and your store is using
-* the Cache provided by {@link @warp-drive/json-api! | @warp-drive/json-api}, and a request
-* returns the following raw data:
-*
-* ```ts
-* {
-*   data: {
-*     type: 'user',
-*     id: '1',
-*     attributes: { firstName: 'Chris', lastName: 'Thoburn' },
-*     relationships: { pets: { data: [{ type: 'dog', id: '1' }] }}
-*   },
-*   included: [
-*     {
-*       type: 'dog',
-*       id: '1',
-*       attributes: { name: 'Rey' },
-*       relationships: { owner: { data: { type: 'user', id: '1' }}}
-*     }
-*   ]
-* }
-* ```
-*
-* We could describe the `'user'` and `'dog'` resources in the above payload
-* with the following schemas:
-*
-* ```ts
-* store.schema.registerResources([
-*   {
-*     type: 'user',
-*     identity: { type: '@id', name: 'id' },
-*     fields: [
-*       {
-*         type: '@identity',
-*         name: '$type',
-*         kind: 'derived',
-*         options: { key: 'type' },
-*       },
-*       { kind: 'field', name: 'firstName' },
-*       { kind: 'field', name: 'lastName' },
-*       {
-*         kind: 'derived',
-*         name: 'name',
-*         type: 'concat',
-*         options: { fields: ['firstName', 'lastName'], separator: ' ' }
-*       },
-*       {
-*         kind: 'hasMany',
-*         name: 'pets',
-*         type: 'pet',
-*         options: {
-*           async: false,
-*           inverse: 'owner',
-*           polymorphic: true,
-*           linksMode: true,
-*         }
-*       }
-*     ]
-*   },
-*   {
-*     type: 'dog',
-*     identity: { type: '@id', name: 'id' },
-*     fields: [
-*       {
-*         type: '@identity',
-*         name: '$type',
-*         kind: 'derived',
-*         options: { key: 'type' },
-*       },
-*       { kind: 'field', name: 'name' },
-*       {
-*         kind: 'belongsTo',
-*         name: 'owner',
-*         type: 'user',
-*         options: {
-*           async: false,
-*           inverse: 'pets',
-*           as: 'pet',
-*           linksMode: true,
-*         }
-*       }
-*     ]
-*   }
-* ]);
-* ```
-*
-* With these schemas in place, the reactive objects that the store would
-* provide us whenever we encountered a `'user'` or a `'dog'` would be:
-*
-* ```ts
-* interface Pet {
-*   readonly id: string;
-*   readonly owner: User;
-* }
-*
-* interface Dog extends Pet {
-*   readonly $type: 'dog';
-*   readonly name: string;
-* }
-*
-* interface EditableUser {
-*   readonly $type: 'user';
-*   readonly id: string;
-*   firstName: string;
-*   lastName: string;
-*   readonly name: string;
-*   pets: Array<Dog | Pet>;
-* }
-*
-* interface User {
-*   readonly $type: 'user';
-*   readonly id: string;
-*   readonly firstName: string;
-*   readonly lastName: string;
-*   readonly name: string;
-*   readonly pets: Readonly<Array<Dog | Pet>>;
-*   [Checkout](): Promise<EditableUser>
-* }>
-* ```
-*
-* Note how based on the schema the reactive object we receive is able to produce
-* `name` on user (despite no name field being in the cache), provide `$type`
-* pulled from the identity of the resource, and flatten the individual attributes
-* and relationships onto the record for easier use.
-*
-* Notice also how we typed this object with `readonly`. This is because while
-* ReactiveResource instances are ***deeply reactive***, they are also ***immutable***.
-*
-* We can mutate a ReactiveResource only be explicitly asking permission to do so, and
-* in the process gaining access to an editable copy. The immutable version will
-* not show any in-process edits made to this editable copy.
-*
-* ```ts
-* import { Checkout } from '@warp-drive/schema-record';
-*
-* const editable = await user[Checkout]();
-* ```
-*
-* ## Utilities
-*
-* ReactiveResource provides a schema builder that simplifies setting up a couple of
-* conventional fields like identity and `$type`. We can rewrite the schema
-* definition above using this utility like so:
-*
-* ```ts
-* import { withDefaults } from '@warp-drive/core/reactive';
-*
-* store.schema.registerResources([
-*   withDefaults({
-*     type: 'user',
-*     fields: [
-*       { kind: 'field', name: 'firstName' },
-*       { kind: 'field', name: 'lastName' },
-*       {
-*         kind: 'derived',
-*         name: 'name',
-*         type: 'concat',
-*         options: { fields: ['firstName', 'lastName'], separator: ' ' }
-*       },
-*       {
-*         kind: 'hasMany',
-*         name: 'pets',
-*         type: 'pet',
-*         options: {
-*           async: false,
-*           inverse: 'owner',
-*           polymorphic: true,
-*           linksMode: true,
-*           resetOnRemoteUpdate: false,
-*         }
-*       }
-*     ]
-*   }),
-*   withDefaults({
-*     type: 'dog',
-*     fields: [
-*       { kind: 'field', name: 'name' },
-*       {
-*         kind: 'belongsTo',
-*         name: 'owner',
-*         type: 'user',
-*         options: {
-*           async: false,
-*           inverse: 'pets',
-*           as: 'pet',
-*           linksMode: true,
-*           resetOnRemoteUpdate: false,
-*         }
-*       }
-*     ]
-*   })
-* ]);
-* ```
-*
-* ## Type Support
-*
-* ### Resource Schemas
-*
-* - {@link PolarisResourceSchema}
-* - {@link LegacyResourceSchema}
-* - {@link ObjectSchema}
-*
-* ### Resource Schema Type Utils
-*
-* - {@link resourceSchema}
-* - {@link objectSchema}
-* - {@link isResourceSchema}
-* - {@link isLegacyResourceSchema}
-*
-* ### Field Schemas
-*
-* - {@link LegacyModeFieldSchema}
-* - {@link PolarisModeFieldSchema}
-*
-* @module
-*/
-import { checkout } from "./reactive/-private/record.js";
-export { instantiateRecord, teardownRecord } from "./reactive/-private/hooks.js";
-export { type CAUTION_MEGA_DANGER_ZONE_Extension, type ProcessedExtension, type ExtensionDef, type Transformation, SchemaService, withDefaults, fromIdentity, registerDerivations } from "./reactive/-private/schema.js";
-export { commit, type ReactiveResource } from "./reactive/-private/record.js";
-export { checkout };
-export { Checkout } from "./reactive/-private/symbols.js";
-export { type ReactiveDocument, type ReactiveDataDocument, type ReactiveErrorDocument } from "./reactive/-private/document.js";
-export { createRequestSubscription, getRequestState, type RequestSubscription, type RequestLoadingState, type RequestState } from "./signals/-private.js";
-export { getPromiseState, type PromiseState, type ResolvedPromise, type RejectedPromise, type PendingPromise } from "./signals/-private.js";
-export type { LegacyLiveArray } from "./store/-private/record-arrays/legacy-live-array.js";
-export type { LegacyManyArray } from "./store/-private/record-arrays/legacy-many-array.js";
-export type { LegacyQueryArray } from "./store/-private/record-arrays/legacy-query.js";
-export type { ReactiveResourceArray } from "./store/-private/record-arrays/resource-array.js";
+import { $n as fromIdentity, A as teardownRecord, C as getPromiseState, L as LegacyManyArray, M as ReactiveResource, N as checkout, P as commit, Qn as Transformation, S as ResolvedPromise, Xn as ProcessedExtension, Yn as ExtensionDef, Zn as SchemaService, _ as RequestState, at as ReactiveResourceArray, b as PromiseState, bt as ReactiveErrorDocument, er as registerDerivations, g as RequestLoadingState, h as createRequestSubscription, k as instantiateRecord, nt as LegacyQueryArray, p as RequestSubscription, qn as CAUTION_MEGA_DANGER_ZONE_Extension, rt as LegacyLiveArray, st as Checkout, tr as withDefaults, v as getRequestState, vt as ReactiveDataDocument, x as RejectedPromise, y as PendingPromise, yt as ReactiveDocument } from "./internal-Cz-893zD.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 };