signalium 3.0.2 → 4.0.0

package/dist/cjs/development/react/index.js

@@ -2,9 +2,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const jsxRuntime = require("react/jsx-runtime");
 const React = require("react");
-const debug = require("../debug-C46WDxhL.js");
-const componentShared = require("../component-shared-Cug2Y5YZ.js");
-const snapshot = require("../snapshot-CbZ6IH3B.js");
+const debug = require("../debug-CbAX7VeM.js");
+const config = require("../config-D6wyrhrW.js");
+const componentShared = require("../component-shared-BjwFh5Jq.js");
+const snapshot = require("../snapshot-BTMVSd8Y.js");
 function _interopNamespaceDefault(e) {
   const n = Object.create(null, { [Symbol.toStringTag]: { value: "Module" } });
   if (e) {
@@ -43,7 +44,14 @@ function ContextProvider({ children, contexts = [], inherit = true }) {
   return jsxRuntime.jsx(ScopeContext.Provider, { value: scope, children });
 }
 class PauseSignalsManager {
-  signals = /* @__PURE__ */ new Set();
+  /**
+   * Readers per registered signal. Scope-cached signals can be shared across providers, so pausing
+   * counts readers on the signal instead of pausing it outright.
+   */
+  signals = /* @__PURE__ */ new Map();
+  /** Unclaimed render leases taken under this provider (e.g. a suspended mount). Pruned lazily. */
+  leases = /* @__PURE__ */ new Set();
+  pruneLeasesAt = 64;
   _paused;
   constructor(initialPaused) {
     this._paused = initialPaused;
@@ -51,22 +59,52 @@ class PauseSignalsManager {
   get paused() {
     return this._paused;
   }
+  trackLease(signal) {
+    const leases = this.leases;
+    leases.add(signal);
+    if (leases.size >= this.pruneLeasesAt) {
+      for (const leased of leases) {
+        if (!leased._isLeased)
+          leases.delete(leased);
+      }
+      this.pruneLeasesAt = Math.max(64, leases.size * 2);
+    }
+  }
+  /** Call before the reader subscribes, so a paused reader never takes the watch. */
   register(signal) {
-    this.signals.add(signal);
+    this.signals.set(signal, (this.signals.get(signal) ?? 0) + 1);
+    this.leases.delete(signal);
+    if (this._paused) {
+      signal._addPausedReaders(1);
+    }
   }
   unregister(signal) {
-    this.signals.delete(signal);
+    const count = this.signals.get(signal);
+    if (count === void 0)
+      return;
+    if (count > 1) {
+      this.signals.set(signal, count - 1);
+    } else {
+      this.signals.delete(signal);
+    }
+    if (this._paused) {
+      signal._addPausedReaders(-1, true);
+    }
   }
   setPaused(value) {
     if (value === this._paused)
       return;
     this._paused = value;
-    for (const signal of this.signals) {
-      if (value) {
-        debug.unwatchSignal(signal);
+    for (const [signal, count] of this.signals) {
+      signal._addPausedReaders(value ? count : -count);
+    }
+    for (const signal of this.leases) {
+      if (!signal._isLeased) {
+        this.leases.delete(signal);
+      } else if (value) {
+        signal._pauseWatch();
       } else {
-        debug.watchSignal(signal);
-        debug.schedulePull(signal);
+        signal._resumeWatch();
       }
     }
   }
@@ -86,6 +124,299 @@ function PauseSignalsProvider({ value, children }) {
 function usePauseSignalsManager() {
   return React.useContext(PauseSignalsManagerContext);
 }
+function addRenderListener(signal, manager) {
+  const subscribe = signal.addListenerLazy(!manager?.paused);
+  if (manager !== null && signal._isLeased) {
+    manager.trackLease(signal);
+  }
+  return subscribe;
+}
+function usePausableStore(manager, signal, subscribe, getSnapshot) {
+  React.useEffect(() => {
+    if (manager === null)
+      return;
+    manager.register(signal);
+    return () => manager.unregister(signal);
+  }, [manager, signal]);
+  return React.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+const { imul } = Math;
+const { getPrototypeOf, keys: objectKeys } = Object;
+const EMPTY_PROPS_HASH = debug.hashValue({});
+function hashPropValue(value, seen) {
+  if (typeof value === "object" && value !== null) {
+    const proto = getPrototypeOf(value);
+    if (proto === Object.prototype) {
+      const keys = objectKeys(value);
+      if (keys.includes("$$typeof") && typeof value.$$typeof === "symbol") {
+        return debug.getObjectHash(value);
+      }
+      seen.push(value);
+      const h = debug.hashObjectKeys(value, keys, seen);
+      seen.pop();
+      return h;
+    }
+    if (proto === Array.prototype) {
+      if (seen.includes(value))
+        return 0;
+      seen.push(value);
+      const array = value;
+      let h = debug.ARRAY_SEED;
+      for (let i = 0; i < array.length; i++) {
+        h = debug.mixHash(h, hashPropValue(array[i], seen));
+      }
+      seen.pop();
+      return debug.finalizeHash(h, array.length);
+    }
+  }
+  return debug.hashValue(value, seen);
+}
+function hashProps(props) {
+  const keyMultiplier = 2654435769;
+  const seen = [];
+  let sum = EMPTY_PROPS_HASH;
+  for (const key of objectKeys(props)) {
+    sum += imul(debug.hashValue(key), keyMultiplier) ^ hashPropValue(props[key], seen);
+  }
+  return sum >>> 0;
+}
+function shallowIdentical(prev, next) {
+  let count = 0;
+  for (const key in next) {
+    if (!Object.is(prev[key], next[key]) || !(key in prev))
+      return false;
+    count++;
+  }
+  for (const _key in prev) {
+    count--;
+  }
+  return count === 0;
+}
+class PropsHashCache {
+  props;
+  hash;
+  constructor(props, hash) {
+    this.props = props;
+    this.hash = hash;
+  }
+}
+function usePropsHash(props) {
+  const ref = React.useRef(null);
+  const cache = ref.current;
+  if (cache !== null) {
+    if (cache.props === props || shallowIdentical(cache.props, props)) {
+      return cache.hash;
+    }
+    const hash2 = hashProps(props);
+    cache.props = props;
+    cache.hash = hash2;
+    return hash2;
+  }
+  const hash = hashProps(props);
+  ref.current = new PropsHashCache(props, hash);
+  return hash;
+}
+function useDeliveryMode(override) {
+  const ref = React.useRef(void 0);
+  return ref.current ??= override ?? config.getReactDelivery();
+}
+const useCommitEffect = typeof window === "undefined" ? React.useEffect : React.useLayoutEffect;
+const increment = (n) => n + 1;
+class StateDelivery {
+  signal;
+  committed;
+  forceUpdate;
+  /** In the pending-delivery queue. */
+  queued = false;
+  /** A `setState` was delivered and its render has not committed yet. */
+  awaitingCommit = false;
+  /** Visible: between the subscription layout effect's setup and cleanup. Only visible readers get deliveries. */
+  mounted = false;
+  /**
+   * Set by every render, cleared by its commit. Still set when Suspense hides the reader, it means
+   * the reader's own render suspended, so it stays live: a change may no longer need what it
+   * suspended on.
+   */
+  rendering = false;
+  /** The subscription layout effect has run before: its next run is a reveal, not a first mount. */
+  connected = false;
+  /**
+   * A commit included the reader without connecting it: it was committed hidden (prerendered in a
+   * hidden `<Activity>`, or mounted into a Suspense-hidden tree), so its first connect is a reveal.
+   */
+  committedHidden = false;
+  /** The subscription currently held, the subscribe function it was made with, and its signal and pause manager. */
+  subscribedWith = null;
+  subscribedSignal = null;
+  pauseManager = null;
+  unsubscribe = null;
+  listener;
+  constructor(signal, version, forceUpdate) {
+    this.signal = signal;
+    this.committed = version;
+    this.forceUpdate = forceUpdate;
+    this.listener = () => this.check();
+  }
+  check() {
+    if (this.queued || this.awaitingCommit || !this.mounted)
+      return;
+    if (this.signal.updatedCount !== this.committed) {
+      enqueueDelivery(this);
+    }
+  }
+  /**
+   * Brings the signal up to date the way a read would, and reports whether it moved past the
+   * committed version. A signal nobody watched (the reader was hidden, or its render lease expired
+   * before the commit) is not recomputed when its dependencies change, so its `updatedCount` alone
+   * can be stale.
+   */
+  pull() {
+    try {
+      debug.checkSignal(this.signal);
+    } catch {
+      return 2;
+    }
+    return this.signal.updatedCount !== this.committed ? 1 : 0;
+  }
+  subscribe(subscribe, manager) {
+    if (this.subscribedWith === subscribe && this.pauseManager === manager)
+      return;
+    this.release();
+    manager?.register(this.signal);
+    this.subscribedSignal = this.signal;
+    this.pauseManager = manager;
+    this.unsubscribe = subscribe(this.listener);
+    this.subscribedWith = subscribe;
+  }
+  release() {
+    if (this.unsubscribe === null)
+      return;
+    this.unsubscribe();
+    this.pauseManager?.unregister(this.subscribedSignal);
+    this.unsubscribe = null;
+    this.subscribedWith = null;
+    this.subscribedSignal = null;
+    this.pauseManager = null;
+  }
+}
+let PENDING_DELIVERIES = [];
+let deliveryScheduled = false;
+function enqueueDelivery(delivery) {
+  delivery.queued = true;
+  PENDING_DELIVERIES.push(delivery);
+  if (!deliveryScheduled) {
+    deliveryScheduled = true;
+    config.scheduleReactDelivery(flushDeliveries);
+  }
+}
+function flushDeliveries() {
+  deliveryScheduled = false;
+  const deliveries = PENDING_DELIVERIES;
+  PENDING_DELIVERIES = [];
+  config.runBatch(() => {
+    for (const delivery of deliveries) {
+      delivery.queued = false;
+      if (delivery.mounted && delivery.signal.updatedCount !== delivery.committed) {
+        delivery.awaitingCommit = true;
+        delivery.forceUpdate();
+      }
+    }
+  });
+}
+function useStateDeliveryState(signal) {
+  const [, forceUpdate] = React.useReducer(increment, 0);
+  const [delivery] = React.useState(() => new StateDelivery(signal, signal.updatedCount, forceUpdate));
+  delivery.rendering = true;
+  return delivery;
+}
+function useStateDelivery(delivery, signal, subscribe, version, manager) {
+  useCommitEffect(() => {
+    delivery.signal = signal;
+    delivery.committed = version;
+    delivery.awaitingCommit = false;
+    delivery.rendering = false;
+    delivery.check();
+  });
+  React.useInsertionEffect(() => {
+    if (delivery.connected)
+      return;
+    queueMicrotask(() => {
+      if (!delivery.connected)
+        delivery.committedHidden = true;
+    });
+  }, [delivery]);
+  useCommitEffect(() => {
+    const revealing = delivery.connected || delivery.committedHidden;
+    delivery.connected = true;
+    delivery.committedHidden = false;
+    delivery.mounted = true;
+    delivery.subscribe(subscribe, manager);
+    const pulled = delivery.pull();
+    if (pulled === 2 || pulled === 1 && revealing) {
+      delivery.awaitingCommit = true;
+      delivery.forceUpdate();
+    } else if (pulled === 1) {
+      delivery.check();
+    }
+    return () => {
+      if (delivery.rendering) {
+        delivery.awaitingCommit = false;
+      } else {
+        delivery.mounted = false;
+      }
+    };
+  }, [subscribe, manager]);
+  React.useEffect(() => () => delivery.release(), [delivery]);
+}
+const elementPropsByInnerProps = /* @__PURE__ */ new WeakMap();
+const suspendedAttemptsByElement = /* @__PURE__ */ new WeakMap();
+function createComponentElement(Inner, props) {
+  const element = React.createElement(Inner, props);
+  elementPropsByInnerProps.set(element.props, props);
+  return element;
+}
+function isReactSuspenseException(error) {
+  if (!(error instanceof Error))
+    return false;
+  const { message } = error;
+  return message.startsWith("Suspense Exception") || /^Minified React error #(460|542)\b/.test(message);
+}
+function readComponentSignal(signal, props) {
+  const element = elementPropsByInnerProps.get(props);
+  let attempts = element === void 0 ? void 0 : suspendedAttemptsByElement.get(element);
+  try {
+    debug.runSignal(signal);
+    const value = signal.value;
+    attempts?.delete(signal);
+    return value;
+  } catch (error) {
+    let pinned = true;
+    if (error !== null && typeof error === "object" && debug.isThennable(error)) {
+      debug.holdLeaseUntilSettled(signal, error);
+    } else if (isReactSuspenseException(error)) {
+      debug.holdSuspendedLease(signal);
+    } else {
+      pinned = false;
+    }
+    if (pinned && element !== void 0 && signal._isLeased) {
+      if (attempts === void 0) {
+        attempts = /* @__PURE__ */ new Set();
+        suspendedAttemptsByElement.set(element, attempts);
+      }
+      attempts.add(signal);
+    }
+    throw error;
+  } finally {
+    if (attempts !== void 0) {
+      for (const attempt of attempts) {
+        if (attempt !== signal) {
+          debug.releaseAbandonedAttempt(attempt);
+          attempts.delete(attempt);
+        }
+      }
+    }
+  }
+}
 const thenableOutcome = /* @__PURE__ */ new WeakMap();
 function adoptYieldedThenable(thenable) {
   const expanded = thenable;
@@ -152,10 +483,12 @@ function runSyncReplayAsyncComponent(fn, props, ownerSignal) {
     debug.setCurrentConsumer(prevConsumer);
   }
 }
-function createAsyncComponentWrapper(fn) {
+function createAsyncComponentWrapper(fn, options) {
+  const deliveryOverride = options?.delivery;
   const Inner = (props) => {
     const scope = useScope();
     const manager = usePauseSignalsManager();
+    const delivery = useDeliveryMode(deliveryOverride);
     const fnSignalRef = React.useRef(void 0);
     const propsRef = React.useRef(props);
     propsRef.current = props;
@@ -171,18 +504,20 @@ function createAsyncComponentWrapper(fn) {
       owned._isLazy = true;
       fnSignalRef.current = sig = owned;
     }
-    const watch = !manager?.paused;
-    manager?.register(sig);
-    React.useEffect(() => {
-      return () => manager?.unregister(sig);
-    }, [manager, sig]);
-    React.useSyncExternalStore(sig.addListenerLazy(watch), () => sig.updatedCount, () => sig.updatedCount);
-    debug.runSignal(sig);
-    return sig.value;
+    const subscribe = addRenderListener(sig, manager);
+    const stateDelivery = delivery === "state" ? useStateDeliveryState(sig) : null;
+    const value = readComponentSignal(sig, props);
+    if (stateDelivery !== null) {
+      useStateDelivery(stateDelivery, sig, subscribe, sig.updatedCount, manager);
+    } else {
+      const getSnapshot = () => sig.updatedCount;
+      usePausableStore(manager, sig, subscribe, getSnapshot);
+    }
+    return value;
   };
   const Outer = (props) => {
-    const hash = debug.hashValue(props);
-    return React.useMemo(() => React.createElement(Inner, props), [hash]);
+    const hash = usePropsHash(props);
+    return React.useMemo(() => createComponentElement(Inner, props), [hash]);
   };
   Object.defineProperty(Outer, SIGNALIUM_ASYNC_COMPONENT, { value: true, enumerable: false });
   return Outer;
@@ -198,7 +533,7 @@ function ensureSsrScope() {
     debug.setRequestScopeGetter(() => getScope());
   }
 }
-function component(fn) {
+function component(fn, options) {
   ensureSsrScope();
   if (componentShared.isAsyncFunctionWithoutTransform(fn)) {
     throw new Error("signalium: `component(async (props) => { await ... })` requires the Signalium Babel preset (async transform).");
@@ -207,12 +542,14 @@ function component(fn) {
     if (typeof window === "undefined") {
       return componentShared.createServerAsyncComponentWrapper(fn);
     }
-    return createAsyncComponentWrapper(fn);
+    return createAsyncComponentWrapper(fn, options);
   }
   const syncFn = fn;
+  const deliveryOverride = options?.delivery;
   const Component = (props) => {
     const scope = useScope();
     const manager = usePauseSignalsManager();
+    const delivery = useDeliveryMode(deliveryOverride);
     const fnSignalRef = React.useRef(void 0);
     const propsRef = React.useRef(props);
     propsRef.current = props;
@@ -227,18 +564,20 @@ function component(fn) {
       created._isLazy = true;
       fnSignalRef.current = signal = created;
     }
-    const watch = !manager?.paused;
-    manager?.register(signal);
-    React.useEffect(() => {
-      return () => manager?.unregister(signal);
-    }, [manager, signal]);
-    React.useSyncExternalStore(signal.addListenerLazy(watch), () => signal.updatedCount, () => signal.updatedCount);
-    debug.runSignal(signal);
-    return signal.value;
+    const subscribe = addRenderListener(signal, manager);
+    const stateDelivery = delivery === "state" ? useStateDeliveryState(signal) : null;
+    const value = readComponentSignal(signal, props);
+    if (stateDelivery !== null) {
+      useStateDelivery(stateDelivery, signal, subscribe, signal.updatedCount, manager);
+    } else {
+      const getSnapshot = () => signal.updatedCount;
+      usePausableStore(manager, signal, subscribe, getSnapshot);
+    }
+    return value;
   };
   return (props) => {
-    const hash = debug.hashValue(props);
-    return React.useMemo(() => jsxRuntime.jsx(Component, { ...props }), [hash]);
+    const hash = usePropsHash(props);
+    return React.useMemo(() => createComponentElement(Component, props), [hash]);
   };
 }
 function useSignal(value, opts) {
@@ -248,30 +587,34 @@ function useSignal(value, opts) {
   }
   return ref.current;
 }
-function useSignalWithSuspension(signal) {
+function useSignalWithSuspension(signal, options) {
   const manager = usePauseSignalsManager();
-  const watch = !manager?.paused;
-  manager?.register(signal);
-  React.useEffect(() => {
-    return () => manager?.unregister(signal);
-  }, [manager, signal]);
-  return React.useSyncExternalStore(signal.addListenerLazy(watch), () => signal.value, () => signal.value);
+  const delivery = useDeliveryMode(options?.delivery);
+  const subscribe = addRenderListener(signal, manager);
+  if (delivery === "state") {
+    const stateDelivery = useStateDeliveryState(signal);
+    const value = signal.value;
+    useStateDelivery(stateDelivery, signal, subscribe, signal.updatedCount, manager);
+    return value;
+  }
+  const getSnapshot = () => signal.value;
+  return usePausableStore(manager, signal, subscribe, getSnapshot);
 }
-function useReactiveShallow(fn) {
+function useReactiveShallow(fn, options) {
   if (debug.getCurrentConsumer()) {
     throw new Error("signalium: `useReactiveShallow` cannot be called inside a reactive function. Call your reactive function directly instead — it already participates in the signal graph.");
   }
   const [, def] = snapshot.getReactiveFnAndDefinition(fn);
   const scope = useScope() ?? debug.getGlobalScope();
   const signal = scope.get(def, []);
-  return useSignalWithSuspension(signal);
+  return useSignalWithSuspension(signal, options);
 }
-function useReactive(fn) {
+function useReactive(fn, options) {
   if (debug.getCurrentConsumer()) {
     throw new Error("signalium: `useReactive` cannot be called inside a reactive function. Call your reactive function directly instead — it already participates in the signal graph.");
   }
   const manager = usePauseSignalsManager();
-  const watch = !manager?.paused;
+  const delivery = useDeliveryMode(options?.delivery);
   const scope = useScope() ?? debug.getGlobalScope();
   const innerSignalRef = React.useRef(void 0);
   const cloneSignalRef = React.useRef(void 0);
@@ -288,17 +631,21 @@ function useReactive(fn) {
     });
   }
   const cloneSignal = cloneSignalRef.current;
-  manager?.register(cloneSignal);
-  React.useEffect(() => {
-    return () => manager?.unregister(cloneSignal);
-  }, [manager, cloneSignal]);
-  return React.useSyncExternalStore(cloneSignal.addListenerLazy(watch), () => cloneSignal.value, () => cloneSignal.value);
+  const subscribe = addRenderListener(cloneSignal, manager);
+  if (delivery === "state") {
+    const stateDelivery = useStateDeliveryState(cloneSignal);
+    const value = cloneSignal.value;
+    useStateDelivery(stateDelivery, cloneSignal, subscribe, cloneSignal.updatedCount, manager);
+    return value;
+  }
+  const getSnapshot = () => cloneSignal.value;
+  return usePausableStore(manager, cloneSignal, subscribe, getSnapshot);
 }
-function useReactiveDeep(fn) {
+function useReactiveDeep(fn, options) {
   {
     warnUseReactiveDeepOnce();
   }
-  return useReactive(fn);
+  return useReactive(fn, options);
 }
 let _useReactiveDeepWarned = false;
 function warnUseReactiveDeepOnce() {