signalium 3.0.2 → 4.0.0

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

@@ -1,9 +1,10 @@
 import { jsx } from "react/jsx-runtime";
 import * as React from "react";
-import React__default, { createContext, useContext as useContext$1, useMemo, useRef, useEffect, useSyncExternalStore } from "react";
-import { b as getCurrentConsumer, k as getGlobalScope, S as SignalScope, l as hashValue, u as unwatchSignal, w as watchSignal, m as schedulePull, s as setCurrentConsumer, j as isReactivePromise, n as isPromise, o as isThennable, c as createReactiveSignal, r as runSignal, d as setRequestScopeGetter, p as signal } from "../debug-BTLbgTPK.js";
-import { i as isAsyncFunctionWithoutTransform, a as isGeneratorFunction, c as createServerAsyncComponentWrapper } from "../component-shared-CLSmdnGU.js";
-import { g as getReactiveFnAndDefinition, r as reactiveSignal, s as snapshot } from "../snapshot-CkndI4Hh.js";
+import React__default, { createContext, useContext as useContext$1, useMemo, useRef, useEffect, useSyncExternalStore, useReducer, useState, useLayoutEffect, useInsertionEffect } from "react";
+import { b as getCurrentConsumer, k as getGlobalScope, S as SignalScope, l as hashValue, m as getObjectHash, n as hashObjectKeys, o as mixHash, p as finalizeHash, A as ARRAY_SEED, q as checkSignal, s as setCurrentConsumer, j as isReactivePromise, r as isPromise, t as isThennable, c as createReactiveSignal, u as runSignal, v as holdLeaseUntilSettled, w as holdSuspendedLease, x as releaseAbandonedAttempt, d as setRequestScopeGetter, y as signal } from "../debug-C3HD8WcT.js";
+import { g as getReactDelivery, s as scheduleReactDelivery, r as runBatch } from "../config-CQLKpPRj.js";
+import { i as isAsyncFunctionWithoutTransform, a as isGeneratorFunction, c as createServerAsyncComponentWrapper } from "../component-shared-B3Q6mIzY.js";
+import { g as getReactiveFnAndDefinition, r as reactiveSignal, s as snapshot } from "../snapshot-CCKlBy-y.js";
 const ScopeContext = createContext(void 0);
 function useScope() {
   return useContext$1(ScopeContext);
@@ -25,7 +26,14 @@ function ContextProvider({ children, contexts = [], inherit = true }) {
   return 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;
@@ -33,22 +41,52 @@ class PauseSignalsManager {
   get paused() {
     return this._paused;
   }
+  trackLease(signal2) {
+    const leases = this.leases;
+    leases.add(signal2);
+    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(signal2) {
-    this.signals.add(signal2);
+    this.signals.set(signal2, (this.signals.get(signal2) ?? 0) + 1);
+    this.leases.delete(signal2);
+    if (this._paused) {
+      signal2._addPausedReaders(1);
+    }
   }
   unregister(signal2) {
-    this.signals.delete(signal2);
+    const count = this.signals.get(signal2);
+    if (count === void 0)
+      return;
+    if (count > 1) {
+      this.signals.set(signal2, count - 1);
+    } else {
+      this.signals.delete(signal2);
+    }
+    if (this._paused) {
+      signal2._addPausedReaders(-1, true);
+    }
   }
   setPaused(value) {
     if (value === this._paused)
       return;
     this._paused = value;
-    for (const signal2 of this.signals) {
-      if (value) {
-        unwatchSignal(signal2);
+    for (const [signal2, count] of this.signals) {
+      signal2._addPausedReaders(value ? count : -count);
+    }
+    for (const signal2 of this.leases) {
+      if (!signal2._isLeased) {
+        this.leases.delete(signal2);
+      } else if (value) {
+        signal2._pauseWatch();
       } else {
-        watchSignal(signal2);
-        schedulePull(signal2);
+        signal2._resumeWatch();
       }
     }
   }
@@ -68,6 +106,299 @@ function PauseSignalsProvider({ value, children }) {
 function usePauseSignalsManager() {
   return useContext$1(PauseSignalsManagerContext);
 }
+function addRenderListener(signal2, manager) {
+  const subscribe = signal2.addListenerLazy(!manager?.paused);
+  if (manager !== null && signal2._isLeased) {
+    manager.trackLease(signal2);
+  }
+  return subscribe;
+}
+function usePausableStore(manager, signal2, subscribe, getSnapshot) {
+  useEffect(() => {
+    if (manager === null)
+      return;
+    manager.register(signal2);
+    return () => manager.unregister(signal2);
+  }, [manager, signal2]);
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+const { imul } = Math;
+const { getPrototypeOf, keys: objectKeys } = Object;
+const EMPTY_PROPS_HASH = 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 getObjectHash(value);
+      }
+      seen.push(value);
+      const h = 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 = ARRAY_SEED;
+      for (let i = 0; i < array.length; i++) {
+        h = mixHash(h, hashPropValue(array[i], seen));
+      }
+      seen.pop();
+      return finalizeHash(h, array.length);
+    }
+  }
+  return hashValue(value, seen);
+}
+function hashProps(props) {
+  const keyMultiplier = 2654435769;
+  const seen = [];
+  let sum = EMPTY_PROPS_HASH;
+  for (const key of objectKeys(props)) {
+    sum += imul(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 = 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 = useRef(void 0);
+  return ref.current ??= override ?? getReactDelivery();
+}
+const useCommitEffect = typeof window === "undefined" ? useEffect : 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(signal2, version, forceUpdate) {
+    this.signal = signal2;
+    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 {
+      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;
+    scheduleReactDelivery(flushDeliveries);
+  }
+}
+function flushDeliveries() {
+  deliveryScheduled = false;
+  const deliveries = PENDING_DELIVERIES;
+  PENDING_DELIVERIES = [];
+  runBatch(() => {
+    for (const delivery of deliveries) {
+      delivery.queued = false;
+      if (delivery.mounted && delivery.signal.updatedCount !== delivery.committed) {
+        delivery.awaitingCommit = true;
+        delivery.forceUpdate();
+      }
+    }
+  });
+}
+function useStateDeliveryState(signal2) {
+  const [, forceUpdate] = useReducer(increment, 0);
+  const [delivery] = useState(() => new StateDelivery(signal2, signal2.updatedCount, forceUpdate));
+  delivery.rendering = true;
+  return delivery;
+}
+function useStateDelivery(delivery, signal2, subscribe, version, manager) {
+  useCommitEffect(() => {
+    delivery.signal = signal2;
+    delivery.committed = version;
+    delivery.awaitingCommit = false;
+    delivery.rendering = false;
+    delivery.check();
+  });
+  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]);
+  useEffect(() => () => delivery.release(), [delivery]);
+}
+const elementPropsByInnerProps = /* @__PURE__ */ new WeakMap();
+const suspendedAttemptsByElement = /* @__PURE__ */ new WeakMap();
+function createComponentElement(Inner, props) {
+  const element = React__default.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(signal2, props) {
+  const element = elementPropsByInnerProps.get(props);
+  let attempts = element === void 0 ? void 0 : suspendedAttemptsByElement.get(element);
+  try {
+    runSignal(signal2);
+    const value = signal2.value;
+    attempts?.delete(signal2);
+    return value;
+  } catch (error) {
+    let pinned = true;
+    if (error !== null && typeof error === "object" && isThennable(error)) {
+      holdLeaseUntilSettled(signal2, error);
+    } else if (isReactSuspenseException(error)) {
+      holdSuspendedLease(signal2);
+    } else {
+      pinned = false;
+    }
+    if (pinned && element !== void 0 && signal2._isLeased) {
+      if (attempts === void 0) {
+        attempts = /* @__PURE__ */ new Set();
+        suspendedAttemptsByElement.set(element, attempts);
+      }
+      attempts.add(signal2);
+    }
+    throw error;
+  } finally {
+    if (attempts !== void 0) {
+      for (const attempt of attempts) {
+        if (attempt !== signal2) {
+          releaseAbandonedAttempt(attempt);
+          attempts.delete(attempt);
+        }
+      }
+    }
+  }
+}
 const thenableOutcome = /* @__PURE__ */ new WeakMap();
 function adoptYieldedThenable(thenable) {
   const expanded = thenable;
@@ -134,10 +465,12 @@ function runSyncReplayAsyncComponent(fn, props, ownerSignal) {
     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 = useRef(void 0);
     const propsRef = useRef(props);
     propsRef.current = props;
@@ -153,18 +486,20 @@ function createAsyncComponentWrapper(fn) {
       owned._isLazy = true;
       fnSignalRef.current = sig = owned;
     }
-    const watch = !manager?.paused;
-    manager?.register(sig);
-    useEffect(() => {
-      return () => manager?.unregister(sig);
-    }, [manager, sig]);
-    useSyncExternalStore(sig.addListenerLazy(watch), () => sig.updatedCount, () => sig.updatedCount);
-    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 = hashValue(props);
-    return useMemo(() => React__default.createElement(Inner, props), [hash]);
+    const hash = usePropsHash(props);
+    return useMemo(() => createComponentElement(Inner, props), [hash]);
   };
   Object.defineProperty(Outer, SIGNALIUM_ASYNC_COMPONENT, { value: true, enumerable: false });
   return Outer;
@@ -180,7 +515,7 @@ function ensureSsrScope() {
     setRequestScopeGetter(() => getScope());
   }
 }
-function component(fn) {
+function component(fn, options) {
   ensureSsrScope();
   if (isAsyncFunctionWithoutTransform(fn)) {
     throw new Error("signalium: `component(async (props) => { await ... })` requires the Signalium Babel preset (async transform).");
@@ -189,12 +524,14 @@ function component(fn) {
     if (typeof window === "undefined") {
       return 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 = useRef(void 0);
     const propsRef = useRef(props);
     propsRef.current = props;
@@ -209,18 +546,20 @@ function component(fn) {
       created._isLazy = true;
       fnSignalRef.current = signal2 = created;
     }
-    const watch = !manager?.paused;
-    manager?.register(signal2);
-    useEffect(() => {
-      return () => manager?.unregister(signal2);
-    }, [manager, signal2]);
-    useSyncExternalStore(signal2.addListenerLazy(watch), () => signal2.updatedCount, () => signal2.updatedCount);
-    runSignal(signal2);
-    return signal2.value;
+    const subscribe = addRenderListener(signal2, manager);
+    const stateDelivery = delivery === "state" ? useStateDeliveryState(signal2) : null;
+    const value = readComponentSignal(signal2, props);
+    if (stateDelivery !== null) {
+      useStateDelivery(stateDelivery, signal2, subscribe, signal2.updatedCount, manager);
+    } else {
+      const getSnapshot = () => signal2.updatedCount;
+      usePausableStore(manager, signal2, subscribe, getSnapshot);
+    }
+    return value;
   };
   return (props) => {
-    const hash = hashValue(props);
-    return useMemo(() => jsx(Component, { ...props }), [hash]);
+    const hash = usePropsHash(props);
+    return useMemo(() => createComponentElement(Component, props), [hash]);
   };
 }
 function useSignal(value, opts) {
@@ -230,30 +569,34 @@ function useSignal(value, opts) {
   }
   return ref.current;
 }
-function useSignalWithSuspension(signal2) {
+function useSignalWithSuspension(signal2, options) {
   const manager = usePauseSignalsManager();
-  const watch = !manager?.paused;
-  manager?.register(signal2);
-  useEffect(() => {
-    return () => manager?.unregister(signal2);
-  }, [manager, signal2]);
-  return useSyncExternalStore(signal2.addListenerLazy(watch), () => signal2.value, () => signal2.value);
+  const delivery = useDeliveryMode(options?.delivery);
+  const subscribe = addRenderListener(signal2, manager);
+  if (delivery === "state") {
+    const stateDelivery = useStateDeliveryState(signal2);
+    const value = signal2.value;
+    useStateDelivery(stateDelivery, signal2, subscribe, signal2.updatedCount, manager);
+    return value;
+  }
+  const getSnapshot = () => signal2.value;
+  return usePausableStore(manager, signal2, subscribe, getSnapshot);
 }
-function useReactiveShallow(fn) {
+function useReactiveShallow(fn, options) {
   if (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] = getReactiveFnAndDefinition(fn);
   const scope = useScope() ?? getGlobalScope();
   const signal2 = scope.get(def, []);
-  return useSignalWithSuspension(signal2);
+  return useSignalWithSuspension(signal2, options);
 }
-function useReactive(fn) {
+function useReactive(fn, options) {
   if (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() ?? getGlobalScope();
   const innerSignalRef = useRef(void 0);
   const cloneSignalRef = useRef(void 0);
@@ -270,17 +613,21 @@ function useReactive(fn) {
     });
   }
   const cloneSignal = cloneSignalRef.current;
-  manager?.register(cloneSignal);
-  useEffect(() => {
-    return () => manager?.unregister(cloneSignal);
-  }, [manager, cloneSignal]);
-  return 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() {