@solidjs/signals 2.0.0-rc.5 → 2.0.0-rc.7

package/dist/prod/signals.js

@@ -1,6 +1,6 @@
 import { TimeoutError } from "./core/error.js";
 
-import { computed, optimisticComputed, setSignal, optimisticSignal, runWithOwner, setMemo, signal, markRefresh, installAuthoritativeRead, read, untrack } from "./core/core.js";
+import { computed, optimisticComputed, setSignal, optimisticSignal, runWithOwner, setMemo, signal, installAuthoritativeRead, markRefresh, read, untrack } from "./core/core.js";
 
 import { cleanup, createRoot, getOwner, dispose, getObserver } from "./core/owner.js";
 
@@ -78,7 +78,74 @@ function createMemo(e, t) {
     return accessor(computed(e, t));
 }
 
-function createEffect(e, t, n) {
+/**
+ * Creates a reactive effect with **separate compute and effect phases**.
+ *
+ * - `compute(prev)` runs reactively — *put all reactive reads here*. The
+ *   returned value is passed to `effect` and is also the new "previous" value
+ *   for the next run.
+ * - `effect(next, prev?)` runs imperatively (untracked) after the queue
+ *   flushes. *Put DOM writes / fetch / logging / subscriptions here.* It may
+ *   return a cleanup function which runs before the next effect or on
+ *   disposal.
+ *
+ * Reactive reads inside `effect` will *not* re-trigger this effect — that's
+ * intentional. If you need a single-phase tracked effect, use
+ * `createTrackedEffect` (with the tradeoffs noted there).
+ *
+ * Pass an `EffectBundle` (`{ effect, error }`) instead of a plain function to
+ * intercept **compute-phase** errors — errors thrown by `compute` or arriving
+ * from upstream reactive sources (including async rejections), which your own
+ * code has no frame to `try/catch`. The `error` handler is the error arm of
+ * the effect phase: it runs on the same schedule and in the same imperative,
+ * writable scope as `effect` (setting error state via signals is fine), and
+ * only for *settled* errors — a transient error that recovers before the
+ * effect phase runs `effect` with the recovered value instead, and a held
+ * transition defers it exactly as it defers `effect`. Without an `error`
+ * handler a compute-phase error is logged and the effect simply skips that
+ * run — a non-render effect's reactivity failing does not crash the app.
+ * Rethrowing from `error` escalates it to the nearest error boundary
+ * (halting the system if none exists).
+ *
+ * The **effect phase is different**: it is your own imperative code, so handle
+ * failures with `try/catch` where they occur. An uncaught effect-phase throw
+ * is treated as an unhandled application error — caught by the nearest
+ * `createErrorBoundary`/`<Errored>`, and permanently halting the reactive
+ * system if there is none. It is *not* routed to the bundle's `error` handler.
+ *
+ * ```typescript
+ * createEffect<T>(compute, effectFn | { effect, error }, options?: EffectOptions);
+ * ```
+ * @param compute a function that receives its previous value and returns a new value used to react on a computation
+ * @param effectFn a function that receives the new value and is used to perform side effects (return a cleanup function), or an `EffectBundle` with `effect` and `error` handlers
+ * @param options `EffectOptions` -- name, defer, schedule, transparent
+ *
+ * @example
+ * ```ts
+ * const [count, setCount] = createSignal(0);
+ *
+ * createEffect(
+ *   () => count(),                  // compute: tracks `count`
+ *   value => console.log(value)     // effect: side effect
+ * );
+ *
+ * setCount(1); // logs 1 after the next flush
+ * ```
+ *
+ * @example
+ * ```ts
+ * createEffect(
+ *   () => userId(),
+ *   id => {
+ *     const ctrl = new AbortController();
+ *     fetch(`/users/${id}`, { signal: ctrl.signal });
+ *     return () => ctrl.abort(); // cleanup before next run / disposal
+ *   }
+ * );
+ * ```
+ *
+ * @description https://docs.solidjs.com/reference/basic-reactivity/create-effect
+ */ function createEffect(e, t, n) {
     effect(e, t.effect || t, t.error, {
         user: true,
         ...n
@@ -121,6 +188,16 @@ function createEffect(e, t, n) {
  * Creates a tracked reactive effect where dependency tracking and side effects happen
  * in the same scope.
  *
+ * @deprecated Do not use in new code. For a side effect that follows reactive
+ * state, use `createEffect(compute, effect)` — it separates tracking from the
+ * side effect, knows its dependencies before it runs, and participates in
+ * async and transitions. For one-time DOM work after render (measuring,
+ * attaching third-party widgets to a ref), use `onSettled`. Tracking from
+ * inside the effect phase — the only thing this primitive adds — is retained
+ * solely to ease 1.x migration: it runs beside user-effect callbacks after
+ * values commit, never holds a transition, and cannot observe a write staged
+ * earlier in the same flush by a signal it has not read yet.
+ *
  * WARNING: Because tracking and effects happen in the same scope, this primitive
  * may run multiple times for a single change or show tearing (reading inconsistent
  * state). Use only when dynamic subscription patterns require same-scope tracking.
@@ -189,15 +266,15 @@ function createEffect(e, t, n) {
     // sources stayed live (firing the callback for replaced dependencies), each
     // accumulated arm delivered its own fire, and un-fired arms leaked as live
     // effect nodes until the owner disposed (#2861).
-        let o;
-    return i => {
-        if (o) {
-            dispose(o);
-            o = undefined;
+        let i;
+    return o => {
+        if (i) {
+            dispose(i);
+            i = undefined;
         }
         runWithOwner(r, () => {
-            effect(() => (i(), o = getOwner()), t => {
-                o = undefined;
+            effect(() => (o(), i = getOwner()), t => {
+                i = undefined;
                 n?.();
                 const r = (e.effect || e)?.();
                 if (false && r !== undefined && typeof r !== "function") ;
@@ -251,11 +328,11 @@ function createEffect(e, t, n) {
             // still runs in place (under the transaction's view when created inside
             // an action step), and status/boundary notifications keep their normal
             // route through the inherited queue.
-            const o = getOwner();
-            const i = new MicrotaskQueue;
-            i.ke = o.C;
+            const i = getOwner();
+            const o = new MicrotaskQueue;
+            o.Le = i.C;
  // notify() forwards up the normal chain
-                        o.C = i;
+                        i.C = o;
             // A user effect rather than a bare computed: computeds are pull-based and
             // are only re-enqueued when a pending source *resolves* — a rejection just
             // marks them errored, so nothing would re-run and the promise would never
@@ -275,7 +352,7 @@ function createEffect(e, t, n) {
             // stale mainline value and resolves with old data.
             {
                 user: true,
-                dt: CONFIG_DIRECT_COMMIT
+                At: CONFIG_DIRECT_COMMIT
             });
         });
     });
@@ -343,7 +420,14 @@ function createEffect(e, t, n) {
     // own eager compute is untouched: created after a refresh it still settles
     // stale-while-revalidate (#2930) — its contract is "first settled value",
     // not "next quiescent state".
-        markRefresh(t);
+    
+    // An authoritative reader is woken through a late-bound hook when the truth
+    // lands EQUAL to a standing override (the A17-silent path). Every setter of
+    // that reader bit must install it — until() does, and this waiter is the
+    // other one (#3303: refresh of an optimistic in an app that never called
+    // until() dereferenced the null hook).
+        installAuthoritativeRead();
+    markRefresh(t);
     const n = new Promise((n, r) => {
         queueMicrotask(() => {
             // No createRoot: the microtask has no ambient owner, so the effect is
@@ -356,24 +440,24 @@ function createEffect(e, t, n) {
             // Typed as the effect node, not Owner: the capture runs inside the
             // effect's own compute, where the ambient owner IS the effect —
             // exactly what dispose() takes.
-            let o = null;
+            let i = null;
             const make = () => effect(() => {
-                if (o === null) {
-                    o = getOwner();
+                if (i === null) {
+                    i = getOwner();
                     const e = new MicrotaskQueue;
-                    e.ke = o.C;
-                    o.C = e;
+                    e.Le = i.C;
+                    i.C = e;
                 }
                 return read(t);
             }, t => {
                 n(typeof e === "function" ? t : e);
-                dispose(o);
+                dispose(i);
             }, e => {
                 r(e);
-                dispose(o);
+                dispose(i);
             }, {
                 user: true,
-                dt: CONFIG_DIRECT_COMMIT | CONFIG_AUTHORITATIVE_READ | CONFIG_FRESH_READ
+                At: CONFIG_DIRECT_COMMIT | CONFIG_AUTHORITATIVE_READ | CONFIG_FRESH_READ
             });
             make();
         });
@@ -448,9 +532,9 @@ function createEffect(e, t, n) {
     // write flips it truthy, that transition merges here and reveals at the
     // joint settle instead of painting the confirmation under live optimism.
         const n = activeTransition;
-    return new Promise((r, o) => {
-        const i = t?.signal;
-        if (i?.aborted) return o(i.reason);
+    return new Promise((r, i) => {
+        const o = t?.signal;
+        if (o?.aborted) return i(o.reason);
         createRoot(c => {
             // Same delivery contract as resolve() (#2930): effect applies ride a
             // microtask so the promise can settle while the transaction the caller
@@ -458,13 +542,13 @@ function createEffect(e, t, n) {
             // entire point of the hold.
             const s = getOwner();
             const u = new MicrotaskQueue;
-            u.ke = s.C;
+            u.Le = s.C;
             s.C = u;
             let f;
             let a;
             const settle = e => {
                 if (f !== undefined) clearTimeout(f);
-                if (a !== undefined) i.removeEventListener("abort", a);
+                if (a !== undefined) o.removeEventListener("abort", a);
                 e();
                 c();
             };
@@ -480,7 +564,7 @@ function createEffect(e, t, n) {
                 // Falsy is "not yet": keep the subscription live and wait for the
                 // next evaluation. Only a truthy settled value resolves.
                 if (e) settle(() => r(e));
-            }, e => settle(() => o(e)), 
+            }, e => settle(() => i(e)), 
             // AUTHORITATIVE_READ: overrides invisible to the predicate.
             // DIRECT_COMMIT: truth that stages into the held transaction (a
             // refresh the action issued) must flow through to the microtask
@@ -488,12 +572,12 @@ function createEffect(e, t, n) {
             // the hold itself is keeping uncommitted.
             {
                 user: true,
-                dt: CONFIG_AUTHORITATIVE_READ | CONFIG_DIRECT_COMMIT
+                At: CONFIG_AUTHORITATIVE_READ | CONFIG_DIRECT_COMMIT
             });
-            if (t?.timeout !== undefined) f = setTimeout(() => settle(() => o(new TimeoutError)), t.timeout);
-            if (i !== undefined) {
-                a = () => settle(() => o(i.reason));
-                i.addEventListener("abort", a, {
+            if (t?.timeout !== undefined) f = setTimeout(() => settle(() => i(new TimeoutError)), t.timeout);
+            if (o !== undefined) {
+                a = () => settle(() => i(o.reason));
+                o.addEventListener("abort", a, {
                     once: true
                 });
             }
@@ -610,7 +694,7 @@ function createOptimistic(e, t) {
  *   on owner disposal
  */ function onSettled(e) {
     const t = getOwner();
-    t && !(t.T & CONFIG_CHILDREN_FORBIDDEN) ? createTrackedEffect(() => untrack(e), undefined) : globalQueue.enqueue(EFFECT_USER, () => {
+    t && !(t.T & CONFIG_CHILDREN_FORBIDDEN) ? trackedEffect(() => untrack(e), undefined) : globalQueue.enqueue(EFFECT_USER, () => {
         // Unowned, out-of-band fire (no owner, or a children-forbidden one this
         // one-shot must not bind to): a returned cleanup has no lifecycle to
         // attach to. Reject it in dev; in production the return is simply