@warp-drive-mirror/core 5.10.0-alpha.13 → 5.10.0-alpha.15

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

@@ -1,2 +1,7 @@
+/**
+ * @module
+ * @summary The `macros` function, which returns the Babel plugins that strip WarpDrive deprecation, canary-feature,
+ * debug-logging and env code at build time.
+ */
 import { macros } from "@warp-drive-mirror/build-config/babel-macros";
 export { macros };

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

@@ -1 +1,6 @@
+/**
+ * @module
+ * @summary Build-time flags, such as `JSON_API_CACHE_VALIDATION_ERRORS`, that gate unreleased WarpDrive features for
+ * canary builds.
+ */
 export * from "@warp-drive-mirror/build-config/canary-features";

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

@@ -1 +1,60 @@
+/**
+ * # Log Instrumentation <Badge type="tip" text="debug only" />
+ *
+ * Many portions of the internals are helpfully instrumented with logging.
+ * This instrumentation is always removed from production builds.
+ *
+ * The [Debugging](/guides/the-manual/debugging/) guide explains what each flag logs.
+ *
+ * Log instrumentation is "regionalized" to specific concepts and concerns
+ * to enable you to enable/disable just the areas you are interested in.
+ *
+ * To activate a particular group of logs set the appropriate flag to `true`
+ * either in your build config or via the runtime helper.
+ *
+ *
+ * ## Runtime Activation
+ *
+ * ::: tip 💡 Just Works in browser Dev Tools!
+ * No import is needed, and the logging config is preserved when the page is refreshed
+ * :::
+ *
+ * ```ts
+ * setWarpDriveLogging({
+ *   LOG_CACHE: true,
+ *   LOG_REQUESTS: true,
+ * })
+ * ```
+ *
+ * A runtime helper is attached to `globalThis` to enable activation of the logs
+ * from anywhere in your application including from the devtools panel.
+ *
+ * The runtime helper overrides any build config settings for the given flag
+ * for the current browser tab. It stores the configuration you give it in
+ * `sessionStorage` so that it persists across page reloads of the current tab,
+ * but not across browser tabs or windows.
+ *
+ * If you need to deactivate the logging, you can call the helper again with the
+ * same flag set to `false` or just open a new tab/window.
+ *
+ * ## Buildtime Activation
+ *
+ * ```ts
+ * setConfig(__dirname, app, {
+ *   debug: {
+ *     LOG_CACHE: true,
+ *     LOG_REQUESTS: false,
+ *     LOG_NOTIFICATIONS: true,
+ *   }
+ * });
+ * ```
+ *
+ * The build config settings are used to set the default values for the
+ * logging flags. Any logging flag that is not set in the build config
+ * will default to `false`.
+ *
+ * @summary Debug-only logging flags, such as `LOG_CACHE` and `LOG_REQUESTS`, set in build config or at runtime
+ * via `setWarpDriveLogging`.
+ * @module
+ */
 export * from "@warp-drive-mirror/build-config/debugging";

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

@@ -1 +1,6 @@
+/**
+ * @module
+ * @summary Deprecation flags, such as `DEPRECATE_NON_STRICT_TYPES`, that keep deprecated WarpDrive behavior active
+ * until the build config drops it by `compatWith` version or by flag.
+ */
 export * from "@warp-drive-mirror/build-config/deprecations";

package/dist/build-config.d.ts

@@ -1,2 +1,19 @@
+/**
+ * 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}
+ *
+ * @summary Build-time configuration for WarpDrive: `setConfig` and its babel plugin for deprecations, features,
+ * debug logging, and polyfill settings.
+ * @module
+ */
 import { WarpDriveConfig, babelPlugin, setConfig } from "@warp-drive-mirror/build-config";
 export { type WarpDriveConfig, babelPlugin, setConfig };

package/dist/{configure-CjsojjiI.d.ts → configure-CodrrdQr.d.ts}

@@ -12,10 +12,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
@@ -78,6 +80,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
@@ -114,8 +133,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.
@@ -129,6 +149,29 @@ interface HooksOptions {
  * @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
@@ -136,5 +179,5 @@ declare function setupSignals<T>(buildConfig: (options: HooksOptions) => SignalH
  */
 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-CjsojjiI.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-CodrrdQr.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"configure-CodrrdQr.d.ts","names":[],"sources":["../src/signals/reactivity/configure.ts"],"mappings":";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,10 @@
-import { a as setupSignals, n as HooksOptions, r as SignalHooks } from "./configure-CjsojjiI.js";
-export { type HooksOptions, type SignalHooks, setupSignals };
+/**
+ * Provides a configuration API for the reactivity system
+ * that WarpDrive should use.
+ *
+ * @summary Provides `setupSignals`, which tells WarpDrive which signal and reactivity library to build its
+ * reactive values on.
+ * @module
+ */
+import { a as registerSignals, n as HooksOptions, o as setupSignals, r as SignalHooks } from "./configure-CodrrdQr.js";
+export { type HooksOptions, type SignalHooks, registerSignals, setupSignals };

package/dist/configure.js

@@ -1,3 +1,3 @@
-import { M as setupSignals } from "./-private-BpyvBYFj.js";
+import { M as registerSignals, N as setupSignals } from "./-private-Y-13dsHO.js";
 
-export { setupSignals };
+export { registerSignals, setupSignals };

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

@@ -1,2 +1,2 @@
-import { Gt as GraphEdge, Ht as peekGraph, Jt as CollectionEdge, Kt as ResourceEdge, Ut as isBelongsTo, Vt as graphFor, Wt as Graph, Yt as UpgradedMeta, qt as ImplicitEdge } from "../internal-CgOlgOt3.js";
+import { Gt as GraphEdge, Ht as peekGraph, Jt as CollectionEdge, Kt as ResourceEdge, Ut as isBelongsTo, Vt as graphFor, Wt as Graph, Yt as UpgradedMeta, qt as ImplicitEdge } from "../internal-BOC6nyCi.js";
 export { type CollectionEdge, type Graph, type GraphEdge, type ImplicitEdge, type ResourceEdge, type UpgradedMeta, graphFor, isBelongsTo, peekGraph };

package/dist/graph/-private.js

@@ -57,9 +57,9 @@ function assertValidRelationshipPayload(graph, op) {
 	const { definition, identifier, state } = relationship;
 	const { type } = identifier;
 	const { field } = op;
-	const { isAsync, kind } = definition;
+	const { isAsync, isLinksMode, kind } = definition;
 	if (payload.links) {
-		if (macroCondition(!getGlobalConfig().WarpDriveMirror.features.JSON_API_CACHE_VALIDATION_ERRORS)) warn(`You pushed a record of type '${type}' with a relationship '${field}' configured as 'async: false'. You've included a link but no primary data, this may be an error in your payload. WarpDrive will treat this relationship as known-to-be-empty.`, isAsync || payload.data === null || !!payload.data || state.hasReceivedData, { id: "ds.store.push-link-for-sync-relationship" });
+		if (macroCondition(!getGlobalConfig().WarpDriveMirror.features.JSON_API_CACHE_VALIDATION_ERRORS)) warn(`You pushed a record of type '${type}' with a relationship '${field}' configured as 'async: false'. You've included a link but no primary data, this may be an error in your payload. WarpDrive will treat this relationship as known-to-be-empty.`, isAsync || isLinksMode || payload.data === null || !!payload.data || state.hasReceivedData, { id: "ds.store.push-link-for-sync-relationship" });
 	} else if (payload.data) {
 		if (kind === "belongsTo") {
 			macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {