@warp-drive-mirror/core 5.10.0-alpha.2 → 5.10.0-alpha.21

package/dist/{aliases-BWYW5EhX.d.ts → aliases-BG5TxALl.d.ts}

@@ -1,4 +1,3 @@
-//#region src/types/cache/aliases.d.ts
 /**
  * The `ResourceBlob` is an opaque type that must satisfy two constraints.
  *
@@ -10,8 +9,10 @@
  *
  * This opaqueness allows arbitrary storage of any serializable/transferable
  * state, including such things as `Buffer`s and `String`s.
+ *
+ * @summary Opaque raw resource data whose format the Cache defines and from which the CacheKeyManager can derive a
+ * `ResourceKey`.
  */
 type ResourceBlob = unknown;
-//#endregion
 export { ResourceBlob as t };
-//# sourceMappingURL=aliases-BWYW5EhX.d.ts.map
+//# sourceMappingURL=aliases-BG5TxALl.d.ts.map

package/dist/aliases-BG5TxALl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aliases-BG5TxALl.d.ts","names":[],"sources":["../src/types/cache/aliases.ts"],"mappings":";;;;;;;;;;;;;;;KA2BY"}

package/dist/{change-C7kqv2kW.d.ts → change-INHMiZ2a.d.ts}

@@ -1,9 +1,10 @@
-import { c as RequestKey, l as ResourceKey } from "./identifier-DQnqOSJK.js";
-//#region src/types/cache/change.d.ts
+import { c as RequestKey, l as ResourceKey } from "./identifier-DmgDehQK.js";
 /**
  * Describes a single mutation to a resource or document that occurred
  * in the cache, as returned by {@link Cache.diff}.
  *
+ * @summary One upsert or removal of a resource or document recorded by the cache, with an optional patch, as
+ * returned by `cache.diff`.
  * @example
  * ```ts
  * const change: Change = {
@@ -36,6 +37,5 @@ interface Change {
    */
   patch?: unknown;
 }
-//#endregion
 export { Change as t };
-//# sourceMappingURL=change-C7kqv2kW.d.ts.map
+//# sourceMappingURL=change-INHMiZ2a.d.ts.map

package/dist/change-INHMiZ2a.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-INHMiZ2a.d.ts","names":[],"sources":["../src/types/cache/change.ts"],"mappings":";;;;;;;;;;;;;;;;UAwBiB;;;;EAIf,YAAY,cAAc;;;;;EAK1B;;;;;;;;;;;;EAYA"}

package/dist/{concepts-DFldVwEM.d.ts → concepts-vh86nAcd.d.ts}

@@ -1,8 +1,7 @@
-import { l as ResourceKey } from "./identifier-DQnqOSJK.js";
-import { a as Type } from "./symbols-DjRDCeX0.js";
-import { i as OpaqueRecordInstance } from "./record-D3QQcaIR.js";
-import { i as Value, n as ObjectValue } from "./raw-D5hnjiq7.js";
-//#region src/types/schema/concepts.d.ts
+import { l as ResourceKey } from "./identifier-DmgDehQK.js";
+import { a as Type } from "./symbols-DVa1PMFG.js";
+import { i as OpaqueRecordInstance } from "./record-f5-uOgHt.js";
+import { i as Value, n as ObjectValue } from "./raw-adYGuEGM.js";
 /**
  * A Transformation converts a cached primitive value into a richer
  * "presentation" value exposed on a record, and back again.
@@ -14,6 +13,9 @@ import { i as Value, n as ObjectValue } from "./raw-D5hnjiq7.js";
  * Transformations must be registered with the SchemaService via
  * `schema.registerTransformation(transform)` before use, keyed by the
  * name assigned to their {@link Type} property.
+ *
+ * @summary A registered pair of `serialize` and `hydrate` functions that convert a field's raw cached value to and from
+ * the value exposed on a record.
  */
 type Transformation<T extends Value = Value, PT = unknown> = {
   /**
@@ -47,6 +49,9 @@ type Transformation<T extends Value = Value, PT = unknown> = {
  * Derivations must be registered with the SchemaService via
  * `schema.registerDerivation(derivation)` before use, keyed by the
  * name assigned to their {@link Type} property.
+ *
+ * @summary A registered function that computes a memoized, read-only field value from a record's other fields, backing
+ * `derived` fields.
  */
 type Derivation<R = unknown, T = unknown, FM extends ObjectValue | null = ObjectValue | null> = {
   /**
@@ -65,6 +70,9 @@ type Derivation<R = unknown, T = unknown, FM extends ObjectValue | null = Object
  * HashFns must be registered with the SchemaService via
  * `schema.registerHashFn(hashFn)` before use, keyed by the name
  * assigned to their {@link Type} property.
+ *
+ * @summary A registered function that computes a stable string identity from an object's cache data, used for `@hash`
+ * fields and polymorphic schema-object types.
  */
 type HashFn<T extends object = object> = {
   /**
@@ -72,6 +80,5 @@ type HashFn<T extends object = object> = {
    */
   [Type]: string;
 } & ((data: T, options: ObjectValue | null, prop: string | null) => string);
-//#endregion
 export { HashFn as n, Transformation as r, Derivation as t };
-//# sourceMappingURL=concepts-DFldVwEM.d.ts.map
+//# sourceMappingURL=concepts-vh86nAcd.d.ts.map

package/dist/concepts-vh86nAcd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concepts-vh86nAcd.d.ts","names":[],"sources":["../src/types/schema/concepts.ts"],"mappings":";;;;;;;;;;;;;;;;;;;KA0BY,eAAe,UAAU,QAAQ,OAAO;;;;;EAKlD,UAAU,OAAO,IAAI,SAAS,oBAAoB,QAAQ,uBAAuB;;;;;EAMjF,QAAQ,OAAO,eAAe,SAAS,oBAAoB,QAAQ,uBAAuB;;;;;EAM1F,cAAc,SAAS,oBAAoB,YAAY,cAAc;;;;GAKpE;;;;;;;;;;;;;;;;;KAkBS,WAAW,aAAa,aAAa,WAAW,qBAAqB;;;;GAI9E;MACG,QAAQ,GAAG,SAAS,IAAI,iBAAiB;;;;;;;;;;;;;;;;KAiBnC,OAAO;;;;GAIhB;MACG,MAAM,GAAG,SAAS,oBAAoB"}

package/dist/{configure-B_F639tN.d.ts → configure-BfXDuPUb.d.ts}

@@ -1,4 +1,3 @@
-//#region src/signals/reactivity/configure.d.ts
 declare const ARRAY_SIGNAL: "___(unique) Symbol(#[])";
 /**
  * An Opaque type that represents a framework specific or TC39 signal.
@@ -12,10 +11,12 @@ type SignalRef = unknown;
  * The hooks which MUST be configured in order to use reactive arrays,
  * resources and documents with framework specfic signals or TC39 signals.
  *
- * Support for multiple frameworks simultaneously can be done via
- * this abstraction by returning multiple signals from the `createSignal`
- * method, and consuming the correct one via the correct framework via
- * the `consumeSignal` and `notifySignal` methods.
+ * To support multiple frameworks on the same page, import
+ * `@warp-drive-mirror/alien-signals/install` before each framework's `install` entry
+ * point. Its hooks implement {@link SignalHooks.register}, so each framework's
+ * hooks, passed to {@link registerSignals}, are added to its signals graph
+ * instead of replacing it, and its memos stay up to date for every framework.
+ * See [Using Ember and React on the Same Page](/guides/the-manual/cookbook/multiple-frameworks-on-one-page.md).
  *
  * Unlike many signals implementations, WarpDrive does not wrap values as
  * signals directly, but instead uses signals to alert the reactive layer
@@ -30,6 +31,8 @@ type SignalRef = unknown;
  * scenarios you may also be interested in integrating with the {@link NotificationManager}
  * more directly.
  *
+ * @summary The create, consume, notify, and memo hooks a framework or TC39 signals implementation
+ * supplies to `setupSignals` to make WarpDrive data reactive.
  * @public
  */
 interface SignalHooks<T = SignalRef> {
@@ -76,6 +79,23 @@ interface SignalHooks<T = SignalRef> {
    * for things like test-waiters.
    */
   waitFor?: <K>(promise: Promise<K>) => Promise<K>;
+  /**
+   * An optional method that returns whether a signal consumed right now would be tracked by the
+   * framework, for instance because a component is rendering.
+   *
+   * ***Warp*Drive** itself does not call it. Hooks that compose other implementations, such as
+   * the ones `@warp-drive-mirror/alien-signals/install` configures, use it to skip work for reads that no
+   * framework would track.
+   */
+  isTracking?: () => boolean;
+  /**
+   * An optional method, present only on hooks that compose other signals implementations into
+   * their own, such as the ones `@warp-drive-mirror/alien-signals/install` configures.
+   *
+   * {@link registerSignals} calls it instead of replacing the configured hooks, so that a
+   * framework's hooks are added alongside the ones already configured rather than replacing them.
+   */
+  register?: <K>(buildConfig: (options: HooksOptions) => SignalHooks<K>) => void;
 }
 /**
  * Contains information a {@link SignalHooks} implementation may want
@@ -90,6 +110,8 @@ interface SignalHooks<T = SignalRef> {
  * }
  * ```
  *
+ * @summary The options passed to the `setupSignals` callback, including the well-known key WarpDrive
+ * uses for an array's contents signal.
  * @public
  */
 interface HooksOptions {
@@ -110,8 +132,9 @@ interface HooksOptions {
   };
 }
 /**
- * Configures the signals implementation to use. Supports multiple
- * implementations simultaneously.
+ * Configures the signals implementation to use, replacing any configured
+ * before. To add a framework's hooks alongside those of other frameworks, use
+ * {@link registerSignals} instead.
  *
  * See {@link HooksOptions} for the options passed to the provided function
  * when called.
@@ -119,16 +142,40 @@ interface HooksOptions {
  * See {@link SignalHooks} for the implementation the callback function should
  * return.
  *
+ * @summary Registers the signal hooks WarpDrive uses for reactivity, built by a callback that receives
+ * `HooksOptions`.
  * @public
  * @param buildConfig - a function that takes options and returns a configuration object
  */
 declare function setupSignals<T>(buildConfig: (options: HooksOptions) => SignalHooks<T>): void;
+/**
+ * Adds the hooks built by `buildConfig` to the configured signals implementation if it composes
+ * other implementations, such as `@warp-drive-mirror/alien-signals`, and otherwise configures them with
+ * {@link setupSignals}.
+ *
+ * A framework's `install` entry point calls this rather than `setupSignals`, so that importing
+ * `@warp-drive-mirror/alien-signals/install` first lets every framework on the page share its signals
+ * and memos.
+ *
+ * @example
+ * ```ts
+ * import { registerSignals } from '@warp-drive-mirror/core/configure';
+ *
+ * registerSignals(buildSignalConfig);
+ * ```
+ *
+ * @summary Registers signal hooks with the configured composing implementation, or configures
+ * them with `setupSignals` when there is none.
+ * @since 5.10.0
+ * @public
+ * @param buildConfig - a function that takes options and returns a configuration object
+ */
+declare function registerSignals<T>(buildConfig: (options: HooksOptions) => SignalHooks<T>): void;
 /**
  * Wraps `promise` using the configured {@link SignalHooks.waitFor}, if any,
  * for things like test-waiters. Returns `promise` unchanged if no
  * `waitFor` hook is configured.
  */
 declare function waitFor<K>(promise: Promise<K>): Promise<K>;
-//#endregion
-export { setupSignals as a, SignalRef as i, HooksOptions as n, waitFor as o, SignalHooks as r, ARRAY_SIGNAL as t };
-//# sourceMappingURL=configure-B_F639tN.d.ts.map
+export { registerSignals as a, SignalRef as i, HooksOptions as n, setupSignals as o, SignalHooks as r, waitFor as s, ARRAY_SIGNAL as t };
+//# sourceMappingURL=configure-BfXDuPUb.d.ts.map

package/dist/configure-BfXDuPUb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configure-BfXDuPUb.d.ts","names":[],"sources":["../src/signals/reactivity/configure.ts"],"mappings":"A,cAMa;;;;;;;;KAsCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA6BK,YAAY,IAAI;;;;;;;;;;EAU/B,eAAe,aAAa,yBAAyB;;;;EAIrD,gBAAgB,QAAQ;;;;EAIxB,eAAe,QAAQ;;;;;;;;EAQvB,aAAa,GAAG,aAAa,sBAAsB,UAAU,YAAY;;;;;;;;;;;;EAazE;;;;;EAMA,WAAW,GAAG,SAAS,QAAQ,OAAO,QAAQ;;;;;;;;;EAU9C;;;;;;;;EASA,YAAY,GAAG,cAAc,SAAS,iBAAiB,YAAY;;;;;;;;;;;;;;;;;;;UAoBpD;;;;;;EAMf;;;;;;;;IAQE;;;;;;;;;;;;;;;;;;;iBAoBY,aAAa,GAAG,cAAc,SAAS,iBAAiB,YAAY;;;;;;;;;;;;;;;;;;;;;;;iBAmCpE,gBAAgB,GAAG,cAAc,SAAS,iBAAiB,YAAY;;;;;;iBA4DvE,QAAQ,GAAG,SAAS,QAAQ,KAAK,QAAQ"}

package/dist/configure.d.ts

@@ -1,2 +1,2 @@
-import { a as setupSignals, n as HooksOptions, r as SignalHooks } from "./configure-B_F639tN.js";
-export { type HooksOptions, type SignalHooks, setupSignals };
+import { a as registerSignals, n as HooksOptions, o as setupSignals, r as SignalHooks } from "./configure-BfXDuPUb.js";
+export { type HooksOptions, type SignalHooks, registerSignals, setupSignals };

package/dist/configure.js

@@ -1,3 +1,3 @@
-import { M as setupSignals } from "./-private-CArItnX4.js";
+import { M as registerSignals, N as setupSignals } from "./-private-CvZfrDZl.js";
 
-export { setupSignals };
+export { registerSignals, setupSignals };

package/dist/{document-Ca4ZZBd9.d.ts → document-B8Fup751.d.ts}

@@ -1,10 +1,12 @@
-import { s as PersistedResourceKey } from "./identifier-DQnqOSJK.js";
-import { d as Meta, m as PaginationLinks, u as Links } from "./json-api-raw-C5APJHHB.js";
-import { t as ApiError } from "./error-0uD6GkNX.js";
-//#region src/types/spec/document.d.ts
+import { s as PersistedResourceKey } from "./identifier-DmgDehQK.js";
+import { d as Meta, m as PaginationLinks, u as Links } from "./json-api-raw-juUdIITO.js";
+import { t as ApiError } from "./error-j5n1yL9m.js";
 /**
  * This type represents a raw {json:api} document for a meta-only
  * document returned by a request intended to be inserted into the cache.
+ *
+ * @summary A raw {json:api} document carrying only `meta` and optional `links`, as returned by a request and
+ * inserted into the cache.
  */
 interface ResourceMetaDocument {
   /**
@@ -25,6 +27,9 @@ interface ResourceMetaDocument {
  * returned by a request intended to be inserted into the cache.
  *
  * For the Reactive value returned by a request using the store, use {@link ReactiveDataDocument} instead.
+ *
+ * @summary A raw {json:api} document whose `data` is a single resource or `null`, as returned by a request and
+ * inserted into the cache.
  */
 interface SingleResourceDataDocument<T = PersistedResourceKey, R = PersistedResourceKey> {
   /**
@@ -53,6 +58,9 @@ interface SingleResourceDataDocument<T = PersistedResourceKey, R = PersistedReso
  * returned by a request intended to be inserted into the cache.
  *
  * For the Reactive value returned by a request using the store, use {@link ReactiveDataDocument} instead.
+ *
+ * @summary A raw {json:api} document whose `data` is an array of resources, as returned by a request and inserted
+ * into the cache.
  */
 interface CollectionResourceDataDocument<T = PersistedResourceKey> {
   /**
@@ -85,6 +93,9 @@ interface CollectionResourceDataDocument<T = PersistedResourceKey> {
  * - {@link CollectionResourceDataDocument}
  *
  * For the Reactive value returned by a request using the store, use {@link ReactiveDataDocument} instead.
+ *
+ * @summary Either a single-resource or a collection raw {json:api} data document, as stored in and returned by
+ * the cache.
  */
 type ResourceDataDocument<T = PersistedResourceKey> = SingleResourceDataDocument<T> | CollectionResourceDataDocument<T>;
 /**
@@ -92,6 +103,9 @@ type ResourceDataDocument<T = PersistedResourceKey> = SingleResourceDataDocument
  * the cache may use.
  *
  * For the Reactive value returned by a request using the store, use {@link ReactiveErrorDocument} instead.
+ *
+ * @summary A raw {json:api} document carrying an `errors` array for a failed request, as stored in and returned
+ * by the cache.
  */
 interface ResourceErrorDocument {
   /**
@@ -122,8 +136,10 @@ interface ResourceErrorDocument {
  * - {@link ResourceErrorDocument}
  *
  * For the Reactive value returned by a request using the store, use {@link ReactiveDocument} instead.
+ *
+ * @summary Any raw {json:api} document the cache stores and returns: meta-only, single-resource, collection, or
+ * error.
  */
 type ResourceDocument<T = PersistedResourceKey> = ResourceMetaDocument | SingleResourceDataDocument<T> | CollectionResourceDataDocument<T> | ResourceErrorDocument;
-//#endregion
 export { ResourceMetaDocument as a, ResourceErrorDocument as i, ResourceDataDocument as n, SingleResourceDataDocument as o, ResourceDocument as r, CollectionResourceDataDocument as t };
-//# sourceMappingURL=document-Ca4ZZBd9.d.ts.map
+//# sourceMappingURL=document-B8Fup751.d.ts.map

package/dist/document-B8Fup751.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-B8Fup751.d.ts","names":[],"sources":["../src/types/spec/document.ts"],"mappings":";;;;;;;;;;UAmBiB;;;;EAIf;;;;EAIA,MAAM;;;;EAIN,QAAQ,QAAQ;;;;;;;;;;;UAYD,2BAA2B,IAAI,sBAAsB,IAAI;;;;EAIxE;;;;EAIA,QAAQ,QAAQ;;;;EAIhB,OAAO;;;;EAIP,MAAM;;;;EAIN,WAAW;;;;;;;;;;;UAYI,+BAA+B,IAAI;;;;EAIlD;;;;EAIA,QAAQ,QAAQ;;;;EAIhB,OAAO;;;;EAIP,MAAM;;;;EAIN,WAAW;;;;;;;;;;;;;;;KAgBD,qBAAqB,IAAI,wBACjC,2BAA2B,KAC3B,+BAA+B;;;;;;;;;;UAWlB;;;;EAIf;;;;EAIA,QAAQ,QAAQ;;;;EAIhB,OAAO;;;;EAIP,QAAQ;;;;;;;;;;;;;;;;;KAkBE,iBAAiB,IAAI,wBAC7B,uBACA,2BAA2B,KAC3B,+BAA+B,KAC/B"}

package/dist/{error-0uD6GkNX.d.ts → error-j5n1yL9m.d.ts}

@@ -1,10 +1,11 @@
-import { c as Link, d as Meta } from "./json-api-raw-C5APJHHB.js";
-//#region src/types/spec/error.d.ts
+import { c as Link, d as Meta } from "./json-api-raw-juUdIITO.js";
 /**
  * Represents a single error in the `errors` member of a {json:api} document.
  *
  * [{json:api} Spec](https://jsonapi.org/format/#error-objects)
  *
+ * @summary One {json:api} error object, with optional `status`, `code`, `title`, `detail`, `source`, `links`, and
+ * `meta`, found in a document's `errors` array.
  * @example
  * ```json
  * {
@@ -76,6 +77,5 @@ interface ApiError {
    */
   meta?: Meta;
 }
-//#endregion
 export { ApiError as t };
-//# sourceMappingURL=error-0uD6GkNX.d.ts.map
+//# sourceMappingURL=error-j5n1yL9m.d.ts.map

package/dist/error-j5n1yL9m.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-j5n1yL9m.d.ts","names":[],"sources":["../src/types/spec/error.ts"],"mappings":";;;;;;;;;;;;;;;;;;UAwBiB;;;;EAIf;;;;;EAKA;;;;EAIA;;;;EAIA;;;;IAIE,QAAQ;;;;IAIR,OAAO;;;;;EAKT;;;;EAIA;;;;;;;;EAQA;;;;IAIE;;;;IAIA;;;;IAIA;;;;;EAKF,OAAO"}