@warp-drive/core 5.9.0-alpha.9 → 5.9.0-beta.1

package/declarations/aliases-BWYW5EhX.d.ts

@@ -0,0 +1,17 @@
+//#region src/types/cache/aliases.d.ts
+/**
+ * The `ResourceBlob` is an opaque type that must satisfy two constraints.
+ *
+ * 1. it should be possible for the {@link CacheKeyManager} to be able to
+ *    generate a {@link ResourceKey} for it, whether by default or due to
+ *    configuration.
+ * 2. it should be in a format expected by the {@link Cache}. This format
+ *    is {@link Cache}-declared.
+ *
+ * This opaqueness allows arbitrary storage of any serializable/transferable
+ * state, including such things as `Buffer`s and `String`s.
+ */
+type ResourceBlob = unknown;
+//#endregion
+export { ResourceBlob as t };
+//# sourceMappingURL=aliases-BWYW5EhX.d.ts.map

package/declarations/aliases-BWYW5EhX.d.ts.map

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

package/declarations/build-config/babel-macros.d.ts

@@ -1 +1,2 @@
-export { macros } from "@warp-drive/build-config/babel-macros";
+import { macros } from "@warp-drive/build-config/babel-macros";
+export { macros };

package/declarations/build-config/canary-features.d.ts

@@ -1 +1 @@
-export * from "@warp-drive/build-config/canary-features";
+export * from "@warp-drive/build-config/canary-features";

package/declarations/build-config/debugging.d.ts

@@ -1 +1 @@
-export * from "@warp-drive/build-config/debugging";
+export * from "@warp-drive/build-config/debugging";

package/declarations/build-config/deprecations.d.ts

@@ -1 +1 @@
-export * from "@warp-drive/build-config/deprecations";
+export * from "@warp-drive/build-config/deprecations";

package/declarations/build-config/env.d.ts

@@ -1 +1,2 @@
-export { DEBUG, PRODUCTION, IS_CI, IS_RECORDING, SHOULD_RECORD, TESTING } from "@warp-drive/build-config/env";
+import { DEBUG, IS_CI, IS_RECORDING, PRODUCTION, SHOULD_RECORD, TESTING } from "@warp-drive/build-config/env";
+export { DEBUG, IS_CI, IS_RECORDING, PRODUCTION, SHOULD_RECORD, TESTING };

package/declarations/build-config/macros.d.ts

@@ -1 +1,2 @@
-export { assert } from "@warp-drive/build-config/macros";
+import { assert } from "@warp-drive/build-config/macros";
+export { assert };

package/declarations/build-config.d.ts

@@ -1,18 +1,2 @@
-/**
-* This module provides a build-plugin that enables configuration of deprecations,
-* optional features, development/testing support and debug logging.
-*
-* Available settings include:
-*
-* - {@link LOGGING | debugging}
-* - {@link DEPRECATIONS | deprecations}
-* - {@link FEATURES | features}
-* - {@link WarpDriveConfig.polyfillUUID | polyfillUUID}
-* - {@link WarpDriveConfig.includeDataAdapterInProduction | includeDataAdapterInProduction}
-* - {@link WarpDriveConfig.compatWith | compatWith}
-*
-* @module
-*/
-import type { WarpDriveConfig } from "@warp-drive/build-config";
-export { setConfig, babelPlugin } from "@warp-drive/build-config";
-export type { WarpDriveConfig };
+import { WarpDriveConfig, babelPlugin, setConfig } from "@warp-drive/build-config";
+export { type WarpDriveConfig, babelPlugin, setConfig };

package/declarations/change-C7kqv2kW.d.ts

@@ -0,0 +1,41 @@
+import { c as RequestKey, l as ResourceKey } from "./identifier-DQnqOSJK.js";
+//#region src/types/cache/change.d.ts
+/**
+ * Describes a single mutation to a resource or document that occurred
+ * in the cache, as returned by {@link Cache.diff}.
+ *
+ * @example
+ * ```ts
+ * const change: Change = {
+ *   identifier: resourceKey,
+ *   op: 'upsert',
+ *   patch: { name: 'Chris' },
+ * };
+ * ```
+ */
+interface Change {
+  /**
+   * the {@link ResourceKey} or {@link RequestKey} of the entity that changed
+   */
+  identifier: ResourceKey | RequestKey;
+  /**
+   * the type of change that occurred. If `'upsert'`, {@link Change.patch | patch}
+   * will be present with the data to merge into the cache for the entity.
+   */
+  op: "upsert" | "remove";
+  /**
+   * When {@link Change.op | op} is `'upsert'`, the data to merge into the
+   * cache for the entity.
+   *
+   * This is opaque to the Store but should be understood by the Cache and
+   * may be utilized by an Adapter when generating data during a `save`
+   * operation.
+   *
+   * It is generally recommended that `patch` contain only the updated
+   * state, ignoring fields that are unchanged.
+   */
+  patch?: unknown;
+}
+//#endregion
+export { Change as t };
+//# sourceMappingURL=change-C7kqv2kW.d.ts.map

package/declarations/change-C7kqv2kW.d.ts.map

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

package/declarations/concepts-LHsLJZMl.d.ts

@@ -0,0 +1,77 @@
+import { l as ResourceKey } from "./identifier-DQnqOSJK.js";
+import { i as Value, n as ObjectValue } from "./raw-D5hnjiq7.js";
+import { a as Type } from "./symbols-DjRDCeX0.js";
+import { i as OpaqueRecordInstance } from "./record-D3QQcaIR.js";
+//#region src/types/schema/concepts.d.ts
+/**
+ * A Transformation converts a cached primitive value into a richer
+ * "presentation" value exposed on a record, and back again.
+ *
+ * Transformations are used by {@link GenericField}, {@link ObjectField}
+ * and {@link ArrayField} to convert between the raw value stored in the
+ * cache (`T`) and the value read from or written to a record (`PT`).
+ *
+ * Transformations must be registered with the SchemaService via
+ * `schema.registerTransformation(transform)` before use, keyed by the
+ * name assigned to their {@link Type} property.
+ */
+type Transformation<T extends Value = Value, PT = unknown> = {
+  /**
+   * Converts a value from its presentation form (as read from or written
+   * to a record) into the raw form to be stored in the cache.
+   */
+  serialize(value: PT, options: ObjectValue | null, record: OpaqueRecordInstance): T;
+  /**
+   * Converts a value from its raw cached form into the presentation
+   * form exposed on a record.
+   */
+  hydrate(value: T | undefined, options: ObjectValue | null, record: OpaqueRecordInstance): PT;
+  /**
+   * Computes the value to use when no value is present in the cache
+   * for the field.
+   */
+  defaultValue?(options: ObjectValue | null, identifier: ResourceKey): T;
+  /**
+   * The unique name this transformation is registered under.
+   */
+  [Type]: string;
+};
+/**
+ * A Derivation computes a read-only field value from other fields
+ * (and options) on a record.
+ *
+ * Derivations back {@link DerivedField}. They are memoized and only
+ * recomputed when the fields they read change; derived values are never
+ * stored in the cache nor sent to the server.
+ *
+ * Derivations must be registered with the SchemaService via
+ * `schema.registerDerivation(derivation)` before use, keyed by the
+ * name assigned to their {@link Type} property.
+ */
+type Derivation<R = unknown, T = unknown, FM extends ObjectValue | null = ObjectValue | null> = {
+  /**
+   * The unique name this derivation is registered under.
+   */
+  [Type]: string;
+} & ((record: R, options: FM, prop: string) => T);
+/**
+ * A HashFn computes a stable string identity for an object from its
+ * cache data, without access to a record instance.
+ *
+ * HashFns back {@link HashField}, and are used to compute the `@hash`
+ * identity of a schema-object, or to determine the resource type of a
+ * polymorphic schema-object or schema-array member.
+ *
+ * HashFns must be registered with the SchemaService via
+ * `schema.registerHashFn(hashFn)` before use, keyed by the name
+ * assigned to their {@link Type} property.
+ */
+type HashFn<T extends object = object> = {
+  /**
+   * The unique name this hash function is registered under.
+   */
+  [Type]: string;
+} & ((data: T, options: ObjectValue | null, prop: string | null) => string);
+//#endregion
+export { HashFn as n, Transformation as r, Derivation as t };
+//# sourceMappingURL=concepts-LHsLJZMl.d.ts.map

package/declarations/concepts-LHsLJZMl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concepts-LHsLJZMl.d.ts","names":[],"sources":["../src/types/schema/concepts.ts"],"mappings":";;;;;;;;;;;;;;;;;KAiBY,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;;;;;;;;;;;;;;KAeS,WAAW,aAAa,aAAa,WAAW,qBAAqB;;;;GAI9E;MACG,QAAQ,GAAG,SAAS,IAAI,iBAAiB;;;;;;;;;;;;;KAcnC,OAAO;;;;GAIhB;MACG,MAAM,GAAG,SAAS,oBAAoB"}

package/declarations/configure-B_F639tN.d.ts

@@ -0,0 +1,134 @@
+//#region src/signals/reactivity/configure.d.ts
+declare const ARRAY_SIGNAL: "___(unique) Symbol(#[])";
+/**
+ * An Opaque type that represents a framework specific or TC39 signal.
+ *
+ * It may be an array of signals or a single signal.
+ *
+ * @private
+ */
+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.
+ *
+ * Unlike many signals implementations, WarpDrive does not wrap values as
+ * signals directly, but instead uses signals to alert the reactive layer
+ * to changes in the underlying cache. E.g. a signal is associated to a value,
+ * but does not serve as the cache for that value directly. We refer to this as
+ * a "gate", the pattern has also been called "side-signals".
+ *
+ * A no-op implementation is allowed, though it may lead to performance issues
+ * in locations that use createMemo as no memoization would be done. This is
+ * typically desirable only when integrating with a framework that does its own
+ * memoization and does not integrate with any signals-like primitive. For these
+ * scenarios you may also be interested in integrating with the {@link NotificationManager}
+ * more directly.
+ *
+ * @public
+ */
+interface SignalHooks<T = SignalRef> {
+  /**
+   * Create a signal for the given key associated to the given object.
+   *
+   * This method does *not* need to cache the signal, it will only be
+   * called once for a given object and key. However, if your framework
+   * will look for a signal cache on the object in a given location or may
+   * have created its own signal on the object for some reason it may be
+   * useful to ensure such cache is properly updated.
+   */
+  createSignal: (obj: object, key: string | symbol) => T;
+  /**
+   * Consume (mark as acccessed) a signal previously created via createSignal.
+   */
+  consumeSignal: (signal: T) => void;
+  /**
+   * Alert a signal previously created via createSignal that its associated value has changed.
+   */
+  notifySignal: (signal: T) => void;
+  /**
+   * Take the given function and wrap it in signals-based memoization. Analagous
+   * to a Computed in the TC39 spec.
+   *
+   * Should return a function which when run provides the latest value of the original
+   * function.
+   */
+  createMemo: <F>(obj: object, key: string | symbol, fn: () => F) => () => F;
+  /**
+   * If the signals implementation allows synchronous flushing of watchers, and
+   * has scheduled such a flush (e.g. watchers will run before the current calling
+   * context yields) this should return "true".
+   *
+   * This is generally something that should return false for anything but the few
+   * frameworks that extensively handle their own reactivity => render scheduling.
+   *
+   * For an example, see EmberJS's backburner scheduler which functioned as a microtask
+   * polyfill.
+   */
+  willSyncFlushWatchers: () => boolean;
+  /**
+   * An optional method that allows wrapping key promises within WarpDrive
+   * for things like test-waiters.
+   */
+  waitFor?: <K>(promise: Promise<K>) => Promise<K>;
+}
+/**
+ * Contains information a {@link SignalHooks} implementation may want
+ * to use, such as the specialized key used for the signal
+ * representing an array's contents / length.
+ *
+ * ```ts
+ * interface HooksOptions {
+ *   wellknown: {
+ *     Array: symbol | string;
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+interface HooksOptions {
+  /**
+   * A list of specialized symbols/strings
+   * used by WarpDrive to encapsulate key
+   * reactivity concerns.
+   */
+  wellknown: {
+    /**
+     * The key used when the signal provides reactivity for the
+     * `length` or "contents" of an array.
+     *
+     * Arrays only use a single signal for all accesses, regardless
+     * of index, property or method: this one.
+     */
+    Array: symbol | string;
+  };
+}
+/**
+ * Configures the signals implementation to use. Supports multiple
+ * implementations simultaneously.
+ *
+ * See {@link HooksOptions} for the options passed to the provided function
+ * when called.
+ *
+ * See {@link SignalHooks} for the implementation the callback function should
+ * return.
+ *
+ * @public
+ * @param buildConfig - a function that takes options and returns a configuration object
+ */
+declare function setupSignals<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

package/declarations/configure-B_F639tN.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configure-B_F639tN.d.ts","names":[],"sources":["../src/signals/reactivity/configure.ts"],"mappings":";cAMa;;;;;;;;KAsCD;;;;;;;;;;;;;;;;;;;;;;;;;UAyBK,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;;;;;;;;;;;;;;;;;UAkB/B;;;;;;EAMf;;;;;;;;IAQE;;;;;;;;;;;;;;;;iBAiBY,aAAa,GAAG,cAAc,SAAS,iBAAiB,YAAY;;;;;;iBAgEpE,QAAQ,GAAG,SAAS,QAAQ,KAAK,QAAQ"}

package/declarations/configure.d.ts

@@ -1,7 +1,2 @@
-/**
-* Provides a configuration API for the reactivity system
-* that WarpDrive should use.
-*
-* @module
-*/
-export { setupSignals, type HooksOptions, type SignalHooks } from "./signals/-private.js";
+import { a as setupSignals, n as HooksOptions, r as SignalHooks } from "./configure-B_F639tN.js";
+export { type HooksOptions, type SignalHooks, setupSignals };

package/declarations/document-BEn91SwT.d.ts

@@ -0,0 +1,129 @@
+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-50OSEhsF.js";
+//#region src/types/spec/document.d.ts
+/**
+ * This type represents a raw {json:api} document for a meta-only
+ * document returned by a request intended to be inserted into the cache.
+ */
+interface ResourceMetaDocument {
+  /**
+   * the url or cache-key associated with the structured document
+   */
+  lid?: string;
+  /**
+   * meta information about the document
+   */
+  meta: Meta;
+  /**
+   * links related to the document
+   */
+  links?: Links | PaginationLinks;
+}
+/**
+ * This type represents a raw {json:api} document for a single resource
+ * 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.
+ */
+interface SingleResourceDataDocument<T = PersistedResourceKey, R = PersistedResourceKey> {
+  /**
+   * the url or cache-key associated with the structured document
+   */
+  lid?: string;
+  /**
+   * links related to the document
+   */
+  links?: Links | PaginationLinks;
+  /**
+   * meta information about the document
+   */
+  meta?: Meta;
+  /**
+   * the resource the document represents, or `null` if it has none
+   */
+  data: T | null;
+  /**
+   * any additional resources included via sideloading
+   */
+  included?: R[];
+}
+/**
+ * This type represents a raw {json:api} document for a resource collection
+ * 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.
+ */
+interface CollectionResourceDataDocument<T = PersistedResourceKey> {
+  /**
+   * the url or cache-key associated with the structured document
+   */
+  lid?: string;
+  /**
+   * links related to the document, including pagination links
+   */
+  links?: Links | PaginationLinks;
+  /**
+   * meta information about the document
+   */
+  meta?: Meta;
+  /**
+   * the resources the document represents
+   */
+  data: T[];
+  /**
+   * any additional resources included via sideloading
+   */
+  included?: T[];
+}
+/**
+ * A type useful for representing the raw {json:api} documents that
+ * the cache may use.
+ *
+ * See also:
+ * - {@link SingleResourceDataDocument}
+ * - {@link CollectionResourceDataDocument}
+ *
+ * For the Reactive value returned by a request using the store, use {@link ReactiveDataDocument} instead.
+ */
+type ResourceDataDocument<T = PersistedResourceKey> = SingleResourceDataDocument<T> | CollectionResourceDataDocument<T>;
+/**
+ * A type useful for representing the raw {json:api} Error documents that
+ * the cache may use.
+ *
+ * For the Reactive value returned by a request using the store, use {@link ReactiveErrorDocument} instead.
+ */
+interface ResourceErrorDocument {
+  /**
+   * the url or cache-key associated with the structured document
+   */
+  lid?: string;
+  /**
+   * links related to the document
+   */
+  links?: Links | PaginationLinks;
+  /**
+   * meta information about the document
+   */
+  meta?: Meta;
+  /**
+   * the errors the document represents
+   */
+  errors: ApiError[];
+}
+/**
+ * A type useful for representing the raw {json:api} documents that
+ * the cache may use.
+ *
+ * See also:
+ * - {@link ResourceMetaDocument}
+ * - {@link SingleResourceDataDocument}
+ * - {@link CollectionResourceDataDocument}
+ * - {@link ResourceErrorDocument}
+ *
+ * For the Reactive value returned by a request using the store, use {@link ReactiveDocument} instead.
+ */
+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-BEn91SwT.d.ts.map

package/declarations/document-BEn91SwT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-BEn91SwT.d.ts","names":[],"sources":["../src/types/spec/document.ts"],"mappings":";;;;;;;;UAUiB;;;;EAIf;;;;EAIA,MAAM;;;;EAIN,QAAQ,QAAQ;;;;;;;;UASD,2BAA2B,IAAI,sBAAsB,IAAI;;;;EAIxE;;;;EAIA,QAAQ,QAAQ;;;;EAIhB,OAAO;;;;EAIP,MAAM;;;;EAIN,WAAW;;;;;;;;UASI,+BAA+B,IAAI;;;;EAIlD;;;;EAIA,QAAQ,QAAQ;;;;EAIhB,OAAO;;;;EAIP,MAAM;;;;EAIN,WAAW;;;;;;;;;;;;KAaD,qBAAqB,IAAI,wBACjC,2BAA2B,KAC3B,+BAA+B;;;;;;;UAQlB;;;;EAIf;;;;EAIA,QAAQ,QAAQ;;;;EAIhB,OAAO;;;;EAIP,QAAQ;;;;;;;;;;;;;;KAeE,iBAAiB,IAAI,wBAC7B,uBACA,2BAA2B,KAC3B,+BAA+B,KAC/B"}

package/declarations/error-50OSEhsF.d.ts

@@ -0,0 +1,77 @@
+import { c as Link, d as Meta } from "./json-api-raw-C5APJHHB.js";
+//#region src/types/spec/error.d.ts
+/**
+ * Represents a single error in the `errors` member of a {json:api} document.
+ *
+ * [{json:api} Spec](https://jsonapi.org/format/#error-objects)
+ *
+ * @example
+ * ```json
+ * {
+ *   "status": "422",
+ *   "source": { "pointer": "/data/attributes/name" },
+ *   "title": "Invalid Attribute",
+ *   "detail": "name cannot be blank"
+ * }
+ * ```
+ */
+interface ApiError {
+  /**
+   * a unique identifier for this particular occurrence of the problem
+   */
+  id?: string;
+  /**
+   * a short, human-readable summary of the problem that should not
+   * change from occurrence to occurrence of the problem
+   */
+  title?: string;
+  /**
+   * a human-readable explanation specific to this occurrence of the problem
+   */
+  detail?: string;
+  /**
+   * links related to the error
+   */
+  links?: {
+    /**
+     * a link that leads to further details about this particular occurrence of the problem
+     */
+    about?: Link;
+    /**
+     * a link that identifies the type of error that this particular error is an instance of
+     */
+    type?: Link;
+  };
+  /**
+   * the HTTP status code applicable to this problem, expressed as a string value
+   */
+  status?: string;
+  /**
+   * an application-specific error code, expressed as a string value
+   */
+  code?: string;
+  /**
+   * an object containing references to the primary source of the error
+   */
+  source?: {
+    /**
+     * a JSON Pointer to the value in the request document that caused the error
+     */
+    pointer: string;
+    /**
+     * the URI query parameter that caused the error
+     */
+    parameter?: string;
+    /**
+     * the name of a single request header which caused the error
+     */
+    header?: string;
+  };
+  /**
+   * non-standard meta-information about the error
+   */
+  meta?: Meta;
+}
+//#endregion
+export { ApiError as t };
+//# sourceMappingURL=error-50OSEhsF.d.ts.map

package/declarations/error-50OSEhsF.d.ts.map

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