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

package/dist/{types-cjs/signals.d.cts → observe/signals.js}

@@ -1,4 +1,23 @@
-import type { Disposable, Refreshable } from "./core/index.cjs";
+import { TimeoutError } from "./core/error.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";
+
+import { globalQueue, dirtyQueue, Queue, entangleConfirmingTransitions, activeTransition } from "./core/scheduler.js";
+
+import { CONFIG_AUTO_DISPOSE, CONFIG_CHILDREN_FORBIDDEN, EFFECT_USER, $REFRESH, CONFIG_DIRECT_COMMIT, CONFIG_AUTHORITATIVE_READ, CONFIG_FRESH_READ } from "./core/constants.js";
+
+import "./core/invariants.js";
+
+import { registerGraph } from "./core/dev.js";
+
+import "./core/verdict.js";
+
+import { effect, trackedEffect } from "./core/effect.js";
+
+import { installOptimisticEngine } from "./core/optimistic.js";
+
 /**
  * Low-level reactive-cleanup primitive. Registers a callback that runs when
  * the surrounding owner is disposed.
@@ -37,265 +56,31 @@ import type { Disposable, Refreshable } from "./core/index.cjs";
  *   return resource;
  * }
  * ```
- */
-export declare function onCleanup(fn: Disposable): Disposable;
-/**
- * A zero-arg getter for a reactive value. Calling it inside a tracking scope
- * (memo, effect compute, JSX expression) subscribes the scope to changes.
- *
- * Reading outside any tracking scope simply returns the current value without
- * creating a subscription.
- */
-export type Accessor<T> = () => T;
-export type SourceAccessor<T> = Refreshable<Accessor<T>>;
-export declare function accessor<T>(node: any): SourceAccessor<T>;
-/**
- * A signal setter. Accepts either a new value or an updater `(prev) => next`.
- *
- * If the type permits `undefined`, `setState()` (no args) clears to `undefined`.
- *
- * To store a function as the value itself (rather than as an updater), wrap it
- * with an updater: `setHandler(() => myHandler)`.
- */
-export type Setter<in out T> = {
-    <U extends T>(...args: undefined extends T ? [] : [value: Exclude<U, Function> | ((prev: T) => U)]): undefined extends T ? undefined : U;
-    <U extends T>(value: (prev: T) => U): U;
-    <U extends T>(value: Exclude<U, Function>): U;
-    <U extends T>(value: Exclude<U, Function> | ((prev: T) => U)): U;
-};
-/** A `[get, set]` pair returned from `createSignal` / `createOptimistic`. */
-export type Signal<T> = [get: SourceAccessor<T>, set: Setter<T>];
-export type ComputeFunction<Prev, Next extends Prev = Prev> = (v: Prev) => PromiseLike<Next> | AsyncIterable<Next> | Next;
-export type EffectFunction<Prev, Next extends Prev = Prev> = (v: Next, p?: Prev) => (() => void) | void;
-export type EffectBundle<Prev, Next extends Prev = Prev> = {
-    effect: EffectFunction<Prev, Next>;
-    /**
-     * Intercepts compute-phase errors (thrown by the compute function or arriving
-     * from upstream sources). Effect-phase throws are NOT routed here — they are
-     * your own imperative code and escalate to the nearest error boundary.
-     *
-     * This is the error arm of the effect phase: it runs on the same queue and
-     * in the same imperative, writable scope as `effect` (signal writes are
-     * legal), receives the error the user code threw, and observes settled
-     * outcomes — an error that recovers before the effect phase runs the
-     * `effect` arm instead, and a held transition defers it like `effect`.
-     */
-    error: (err: unknown, cleanup: () => void) => void;
-};
-/** Options shared by every effect primitive. */
-interface BaseEffectOptions {
-    /** Debug name (dev mode only) */
-    name?: string;
+ */ function onCleanup(e) {
+    return cleanup(e);
 }
-/** Options for effect primitives that support deferring/scheduling their initial run (`createEffect`, `createRenderEffect`, `createReaction`). */
-export interface EffectOptions extends BaseEffectOptions {
-    /** When true, defers the initial effect execution until the next change */
-    defer?: boolean;
-    /**
-     * When true, enqueues the initial effect callback through the effect queue instead of running
-     * it synchronously at creation. Lets the initial run participate in transitions -- if any
-     * source throws `NotReadyError` during the compute phase, the callback is held until the
-     * transition settles.
-     *
-     * Primarily for render effects that need transition-aware initial mounts (e.g. the root
-     * `insert()` in `render()`).
-     */
-    schedule?: boolean;
-    /**
-     * Advanced. When true, asserts the compute function returns synchronous
-     * values only (never `PromiseLike` / `AsyncIterable`). Skips the
-     * async-shape probe in `recompute` for a small fixed-cost win per run.
-     * Intended for compiler emissions (`_$effect`) and library code that
-     * provably returns sync values. Returning a Promise or async iterable
-     * from a `sync: true` effect is undefined behavior — the value will be
-     * stored as-is and never awaited.
-     */
-    sync?: boolean;
-    /**
-     * Advanced (integration tier). When true, the effect is invisible to the
-     * hydration id scheme: it inherits its parent's id instead of consuming a
-     * child slot, and during hydration its compute runs live instead of
-     * adopting the serialized server value (its first run is not frozen to
-     * the server's decision).
-     *
-     * For **client-only effects created while hydrating** — effects with no
-     * server-rendered counterpart (a router wiring link state, scroll
-     * restoration, etc.). An id-consuming node the server never created would
-     * shift every later sibling's hydration id, making serialized lookups and
-     * template claims after it miss. `transparent` is also the supported
-     * alternative to branching on hydration state
-     * (`if (hydrating) createEffect(...)`), which freezes whatever the first
-     * run decided: create the effect unconditionally and let it observe live
-     * state instead.
-     *
-     * SSR ignores this option (a server-side effect always allocates its id
-     * slot), so only mark effects the server does not create. Outside
-     * hydration it is a no-op.
-     */
-    transparent?: boolean;
+
+function accessor(e) {
+    const t = read.bind(null, e);
+    t[$REFRESH] = e;
+    return t;
 }
-/** Options for plain signals created with `createSignal(value)` or `createOptimistic(value)`. */
-export interface SignalOptions<T> {
-    /** Debug name (dev mode only) */
-    name?: string;
-    /**
-     * Custom equality function, or `false` to always notify subscribers.
-     * Defaults to reference equality (`isEqual`). Pass a comparator (e.g.
-     * `(a, b) => a.id === b.id`) for value-based equality, or `false` to
-     * notify on every write regardless of equality.
-     */
-    equals?: false | ((prev: T, next: T) => boolean);
-    /** Suppress dev-mode warnings when writing inside an owned scope */
-    ownedWrite?: boolean;
-    /** Callback invoked when the signal loses all subscribers */
-    unobserved?: () => void;
+
+function createSignal(e, t) {
+    if (typeof e === "function") {
+        const r = computed(e, t);
+        r.C &= ~CONFIG_AUTO_DISPOSE;
+        return [ accessor(r), setMemo.bind(null, r) ];
+    }
+    const r = signal(e, t);
+    registerGraph(r, getOwner());
+    return [ accessor(r), setSignal.bind(null, r) ];
 }
-/**
- * Options for read-only memos created with `createMemo`.
- * Also used in combination with `SignalOptions` for writable memos
- * (`createSignal(fn)` / `createOptimistic(fn)`).
- */
-export interface MemoOptions<T> {
-    /** Stable identifier for the owner hierarchy */
-    id?: string;
-    /** Debug name (dev mode only) */
-    name?: string;
-    /**
-     * Advanced (integration tier). When true, the memo is invisible to the
-     * hydration id scheme: it inherits its parent's id instead of consuming a
-     * child slot, and during hydration it computes live instead of adopting
-     * the serialized server value. For client-only memos with no
-     * server-rendered counterpart — see {@link EffectOptions.transparent} for
-     * the full semantics. No-op outside hydration.
-     */
-    transparent?: boolean;
-    /**
-     * Custom equality function, or `false` to always notify subscribers.
-     * Defaults to reference equality (`isEqual`). Pass a comparator (e.g.
-     * `(a, b) => a.id === b.id`) for value-based equality, or `false` to
-     * notify on every recompute regardless of equality.
-     */
-    equals?: false | ((prev: T, next: T) => boolean);
-    /** Callback invoked when the computed loses all subscribers */
-    unobserved?: () => void;
-    /**
-     * When true, defers the initial computation until the value is first read,
-     * **and** opts the memo into autodisposal — once it has no remaining
-     * subscribers it is torn down and recomputed from scratch on the next read.
-     * Use it for compute-on-demand values that should not retain state across
-     * idle periods. Non-lazy owned memos live for their owner's lifetime and
-     * never autodispose.
-     */
-    lazy?: boolean;
-    /**
-     * Advanced. When true, asserts the compute function returns synchronous
-     * values only (never `PromiseLike` / `AsyncIterable`). Skips the
-     * async-shape probe in `recompute` for a small fixed-cost win per run.
-     * Intended for compiler emissions (`_$memo`) and library code that
-     * provably returns sync values. Returning a Promise or async iterable
-     * from a `sync: true` memo is undefined behavior — the value will be
-     * stored as-is and never awaited.
-     */
-    sync?: boolean;
-    /**
-     * Commit #0: a committed value the memo is born with, shown until the
-     * compute's first real answer lands. While that first answer is in flight
-     * the memo reads as a settled value everywhere — nothing suspends to a
-     * `<Loading>` boundary, no transition is held (first-flight work is
-     * loading-class, like a boundary fallback), and `isPending(memo)` stays
-     * **false**: commit #0 answers the question by declaration, so first-load
-     * affordances are driven from the value itself (a `null` placeholder, a
-     * `skeleton: true` field, etc.). Once the first answer lands, the loading
-     * value leaves the lineage forever: refetches use normal pending semantics
-     * (stale value shown, `isPending` true, boundaries/transitions coordinate)
-     * — the canonical guard is `data.skeleton || isPending(data)`, whose two
-     * terms cover the two disjoint states.
-     *
-     * Typed strictly as `T`: to use `null`/`undefined` as the placeholder,
-     * declare it in the memo's type (e.g. `createMemo<User | null>(...)`), so
-     * every consumer sees the nullable window honestly. If the placeholder is
-     * shaped data standing in for real data, encode its provenance in the data
-     * (e.g. a `skeleton: true` field) rather than letting it impersonate truth.
-     *
-     * The loading value is also the compute's first `prev`, so `prev`-based
-     * memos fold from it.
-     */
-    loadingValue?: T;
+
+function createMemo(e, t) {
+    return accessor(computed(e, t));
 }
-export type NoInfer<T extends any> = [T][T extends any ? 0 : never];
-/**
- * Creates a simple reactive state with a getter and setter.
- *
- * When called with a plain value, creates a signal with `SignalOptions` (name, equals, ownedWrite, unobserved).
- * When called with a function, creates a writable memo with `SignalOptions & MemoOptions` (adds id, lazy).
- *
- * ```typescript
- * // Plain signal
- * const [state, setState] = createSignal<T>(value, options?: SignalOptions<T>);
- * // Writable memo (function overload)
- * const [state, setState] = createSignal<T>(fn, initialValue?, options?: SignalOptions<T> & MemoOptions<T>);
- * ```
- * @param value initial value of the state; if empty, the state's type will automatically extended with undefined
- * @param options optional object with a name for debugging purposes and equals, a comparator function for the previous and next value to allow fine-grained control over the reactivity
- *
- * @returns `[state: Accessor<T>, setState: Setter<T>]`
- *
- * @example
- * ```ts
- * const [count, setCount] = createSignal(0);
- *
- * count();              // 0
- * setCount(1);          // explicit value
- * setCount(c => c + 1); // updater
- * ```
- *
- * @example
- * ```ts
- * // Writable memo: starts as `fn()`, can be locally overwritten by setter.
- * const [user, setUser] = createSignal(() => fetchUser(userId()));
- *
- * setUser({ ...user(), name: "Alice" }); // optimistic local edit
- * ```
- *
- * @description https://docs.solidjs.com/reference/basic-reactivity/create-signal
- */
-export declare function createSignal<T>(): Signal<T | undefined>;
-export declare function createSignal<T>(value: Exclude<T, Function>, options?: SignalOptions<T>): Signal<T>;
-export declare function createSignal<T>(fn: ComputeFunction<T>, options?: SignalOptions<T> & MemoOptions<T>): Signal<T>;
-/**
- * Creates a readonly derived reactive memoized signal.
- *
- * ```typescript
- * const value = createMemo<T>(compute, options?: MemoOptions<T>);
- * ```
- * @param compute a function that receives its previous value and returns a new value used to react on a computation
- * @param options `MemoOptions` -- id, name, equals, unobserved, lazy, transparent
- *
- * @example
- * ```ts
- * const [first, setFirst] = createSignal("Ada");
- * const [last, setLast] = createSignal("Lovelace");
- *
- * const fullName = createMemo(() => `${first()} ${last()}`);
- *
- * fullName(); // "Ada Lovelace"
- * ```
- *
- * @example
- * ```ts
- * // Async memo — reads surface as pending inside <Loading>
- * const user = createMemo(async () => {
- *   const res = await fetch(`/users/${id()}`);
- *   return res.json();
- * });
- * ```
- *
- * @description https://docs.solidjs.com/reference/basic-reactivity/create-memo
- */
-export declare function createMemo<T>(compute: ComputeFunction<NoInfer<T>, T>, options: MemoOptions<T> & {
-    loadingValue: T;
-}): SourceAccessor<T>;
-export declare function createMemo<T>(compute: ComputeFunction<undefined | NoInfer<T>, T>, options?: MemoOptions<T>): SourceAccessor<T>;
+
 /**
  * Creates a reactive effect with **separate compute and effect phases**.
  *
@@ -363,8 +148,13 @@ export declare function createMemo<T>(compute: ComputeFunction<undefined | NoInf
  * ```
  *
  * @description https://docs.solidjs.com/reference/basic-reactivity/create-effect
- */
-export declare function createEffect<T>(compute: ComputeFunction<undefined | NoInfer<T>, T>, effectFn: EffectFunction<NoInfer<T>, T> | EffectBundle<NoInfer<T>, T>, options?: EffectOptions): void;
+ */ function createEffect(e, t, r) {
+    effect(e, t.effect || t, t.error, {
+        user: true,
+        ...r
+    });
+}
+
 /**
  * Creates a reactive computation that runs during the render phase as DOM elements
  * are created and updated but not necessarily connected.
@@ -393,8 +183,10 @@ export declare function createEffect<T>(compute: ComputeFunction<undefined | NoI
  * ```
  *
  * @description https://docs.solidjs.com/reference/secondary-primitives/create-render-effect
- */
-export declare function createRenderEffect<T>(compute: ComputeFunction<undefined | NoInfer<T>, T>, effectFn: EffectFunction<NoInfer<T>, T>, options?: EffectOptions): void;
+ */ function createRenderEffect(e, t, r) {
+    effect(e, t, undefined, r);
+}
+
 /**
  * Creates a tracked reactive effect where dependency tracking and side effects happen
  * in the same scope.
@@ -439,8 +231,10 @@ export declare function createRenderEffect<T>(compute: ComputeFunction<undefined
  * ```
  *
  * @description https://docs.solidjs.com/reference/secondary-primitives/create-tracked-effect
- */
-export declare function createTrackedEffect(compute: () => void | (() => void), options?: BaseEffectOptions): void;
+ */ function createTrackedEffect(e, t) {
+    trackedEffect(e, t);
+}
+
 /**
  * Creates a reactive computation that runs after the render phase with flexible tracking.
  *
@@ -466,8 +260,44 @@ export declare function createTrackedEffect(compute: () => void | (() => void),
  * ```
  *
  * @description https://docs.solidjs.com/reference/secondary-primitives/create-reaction
- */
-export declare function createReaction(effectFn: EffectFunction<undefined> | EffectBundle<undefined>, options?: EffectOptions): (tracking: () => void) => void;
+ */ function createReaction(e, t) {
+    let r = undefined;
+    cleanup(() => r?.());
+    const n = getOwner();
+    // The currently armed effect node. `track()` replaces the previous
+    // subscription (1.x semantics): without disposing the superseded arm, its
+    // 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 i;
+    return o => {
+        if (i) {
+            dispose(i);
+            i = undefined;
+        }
+        runWithOwner(n, () => {
+            effect(() => (o(), i = getOwner()), t => {
+                i = undefined;
+                r?.();
+                const n = (e.effect || e)?.();
+                if (false && n !== undefined && typeof n !== "function") ;
+                r = n;
+                dispose(t);
+            }, e.error, {
+                ...t,
+                user: true,
+                defer: true
+            });
+        });
+    };
+}
+
+/** Delivers effect applies on a microtask instead of queueing them (#2930). */ class MicrotaskQueue extends Queue {
+    enqueue(e, t) {
+        queueMicrotask(() => t(e));
+    }
+}
+
 /**
  * Awaits a reactive expression and returns its first fully-settled value as a
  * `Promise`. Pending async reads (`createMemo` returning a promise, etc.) are
@@ -488,8 +318,46 @@ export declare function createReaction(effectFn: EffectFunction<undefined> | Eff
  * ```
  *
  * @param fn a reactive expression to resolve
- */
-export declare function resolve<T>(fn: () => T): Promise<T>;
+ */ function resolve(e) {
+    return new Promise((t, r) => {
+        createRoot(n => {
+            // Deliver effect applies on a microtask instead of the owner queue: an
+            // incomplete transition stashes its effect queues until it settles, but
+            // an action yielding this promise is itself what keeps the transition
+            // open — the stashed res() deadlocked the action (#2930). The compute
+            // 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 i = getOwner();
+            const o = new MicrotaskQueue;
+            o._parent = i.T;
+ // notify() forwards up the normal chain
+                        i.T = 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
+            // settle (#2842). The effect's error channel is notified on rejection.
+                        effect(e, e => {
+                t(e);
+                n();
+            }, e => {
+                // The error arm already unwraps StatusError (#2840) — `err` is the
+                // user's original error, matching what error boundaries expose.
+                r(e);
+                n();
+            }, 
+            // DIRECT_COMMIT: a source settling INTO the held transaction (e.g. a
+            // refresh this action issued) stages its landing; the effect's own
+            // recompute must not stage too, or the microtask apply reads the
+            // stale mainline value and resolves with old data.
+            {
+                user: true,
+                Xt: CONFIG_DIRECT_COMMIT
+            });
+        });
+    });
+}
+
 /**
  * Invalidates one reactive source, forcing it to re-execute even if its inputs
  * haven't changed, and returns a promise for the target's NEXT QUIESCENT
@@ -530,18 +398,76 @@ export declare function resolve<T>(fn: () => T): Promise<T>;
  * // Imperative settle point
  * const fresh = await refresh(user);
  * ```
- */
-export declare function refresh<T>(target: Refreshable<T>): Promise<T extends (...args: any) => infer V ? V : T>;
-/** Falsy values a truthy predicate result is narrowed against. */
-export type Truthy<T> = Exclude<T, false | 0 | 0n | "" | null | undefined>;
-export interface UntilOptions {
-    /** Reject with `TimeoutError` if the predicate has not turned truthy within
-     * this many milliseconds. Strongly recommended when the confirming truth
-     * arrives over a transport that can drop (sockets, subscriptions). */
-    timeout?: number;
-    /** Reject with `signal.reason` on abort. */
-    signal?: AbortSignal;
+ */ function refresh(e) {
+    const t = e?.[$REFRESH];
+    if (!t) {
+        return Promise.resolve(undefined);
+    }
+    // Mark now, watch on a microtask. The waiter is resolve()'s machinery with
+    // two extra reader bits, but it must NOT compute at call time (effects
+    // recompute eagerly on creation): same-tick refreshes coalesce into ONE
+    // re-ask only because every mark lands before anything pulls, and eager
+    // per-call pulls turned three refreshes into three fetches. Deferred, the
+    // waiter's first read sees the coalesced state: FRESH_READ pulls the node
+    // through recompute if it is still dirty (self-deduping — a clean node
+    // no-ops, so N waiters cost one pull; this also closes the race where a
+    // waiter reads the PRE-re-ask value as settled and delivers stale), after
+    // which the read either parks on the re-ask's pending window (async — the
+    // settle walk re-runs it on every landing, equal-value and
+    // staged-under-hold included, and a rejection arrives through the effect's
+    // error channel) or serves the sync answer. AUTHORITATIVE_READ keeps an
+    // action's own optimistic override out of the delivered value. resolve()'s
+    // 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".
+    
+    // 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 r = new Promise((r, n) => {
+        queueMicrotask(() => {
+            // No createRoot: the microtask has no ambient owner, so the effect is
+            // naturally detached, and settle disposes the node directly — the root
+            // added ~560B of otherwise-shakeable machinery for nothing but the
+            // dev-mode NO_OWNER_EFFECT warning, so dev keeps a root husk purely to
+            // stay quiet. The waiter swaps in its microtask queue during its own
+            // first compute (before the initial apply enqueue), replacing the
+            // root-owner plumbing.
+            // 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 i = null;
+            const make = () => effect(() => {
+                if (i === null) {
+                    i = getOwner();
+                    const e = new MicrotaskQueue;
+                    e._parent = i.T;
+                    i.T = e;
+                }
+                return read(t);
+            }, t => {
+                r(typeof e === "function" ? t : e);
+                dispose(i);
+            }, e => {
+                n(e);
+                dispose(i);
+            }, {
+                user: true,
+                Xt: CONFIG_DIRECT_COMMIT | CONFIG_AUTHORITATIVE_READ | CONFIG_FRESH_READ
+            });
+            make();
+        });
+    });
+    // Fire-and-forget refresh must not turn a failed refetch into an unhandled
+    // rejection; awaiting callers attach their own handlers to `promise`.
+        r.catch(() => {});
+    return r;
 }
+
 /**
  * Awaits a reactive predicate and resolves the first time it settles *truthy*,
  * with that (narrowed) value. Falsy results and pending async reads both mean
@@ -582,12 +508,20 @@ export interface UntilOptions {
  *
  * Must be called *outside* a tracking scope.
  *
+ * Inside an action, call it from a step: after an `await`, put a bare `yield`
+ * before `yield until(...)`. The runtime cannot hook an async generator's
+ * `await` continuation, so the `until(...)` expression — which CREATES the
+ * predicate's reader — would otherwise run outside the transaction; created
+ * there it is born held (A29) and replays only at the commit its own promise
+ * holds open (#3482). See {@link action}.
+ *
  * @example
  * ```ts
  * const send = action(async function* (text: string) {
  *   const clientId = crypto.randomUUID();
  *   setMessages(m => { m.push({ clientId, text, pending: true }); }); // optimistic
  *   await socket.send({ clientId, text }); // fire-and-forget transport
+ *   yield; // re-enter the transaction after the await
  *   // Hold until the live source echoes the write (authoritative view —
  *   // the optimistic row above cannot satisfy this):
  *   yield until(() => messages.some(m => m.clientId === clientId), { timeout: 10_000 });
@@ -596,43 +530,84 @@ export interface UntilOptions {
  *
  * @param fn a reactive predicate over authoritative state
  * @param options optional `timeout` (ms) and abort `signal`
- */
-export declare function until<T>(fn: () => T, options?: UntilOptions): Promise<Truthy<T>>;
-/**
- * Creates an optimistic signal that can be used to optimistically update a value
- * and then revert it back to the previous value at end of transition.
- *
- * When called with a plain value, creates an optimistic signal with `SignalOptions` (name, equals, ownedWrite, unobserved).
- * When called with a function, creates a writable optimistic memo with `SignalOptions & MemoOptions` (adds id, lazy).
- *
- * ```typescript
- * // Plain optimistic signal
- * const [state, setState] = createOptimistic<T>(value, options?: SignalOptions<T>);
- * // Writable optimistic memo (function overload)
- * const [state, setState] = createOptimistic<T>(fn, options?: SignalOptions<T> & MemoOptions<T>);
- * ```
- * @param value initial value of the signal; if empty, the signal's type will automatically extended with undefined
- * @param options optional object with a name for debugging purposes and equals, a comparator function for the previous and next value to allow fine-grained control over the reactivity
- *
- * @returns `[state: Accessor<T>, setState: Setter<T>]`
- *
- * @example
- * ```ts
- * const [todos, setTodos] = createOptimistic(initialTodos);
- *
- * const addTodo = action(function* (text: string) {
- *   const tempId = crypto.randomUUID();
- *   setTodos(t => [...t, { id: tempId, text, pending: true }]); // optimistic
- *   const saved = yield api.createTodo(text);
- *   setTodos(t => t.map(x => (x.id === tempId ? saved : x)));   // reconcile
- * });
- * ```
- *
- * @description https://docs.solidjs.com/reference/basic-reactivity/create-optimistic-signal
- */
-export declare function createOptimistic<T>(): Signal<T | undefined>;
-export declare function createOptimistic<T>(value: Exclude<T, Function>, options?: SignalOptions<T>): Signal<T>;
-export declare function createOptimistic<T>(fn: ComputeFunction<T>, options?: SignalOptions<T> & MemoOptions<T>): Signal<T>;
+ */ function until(e, t) {
+    // Late-bind the wakeup hook for the A17-silent ack paths (pay-for-use:
+    // apps that never call until() never retain it).
+    installAuthoritativeRead();
+    // Flip-entanglement (#3164 follow-up): the transaction this until() holds
+    // open (the action's, when yielded from one). The predicate is the user's
+    // declaration of what confirms it — when a foreign transition's staged
+    // write flips it truthy, that transition merges here and reveals at the
+    // joint settle instead of painting the confirmation under live optimism.
+        const r = activeTransition;
+    return new Promise((n, 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
+            // yielded it into is still open — that transaction being open is the
+            // entire point of the hold.
+            const u = getOwner();
+            const s = new MicrotaskQueue;
+            s._parent = u.T;
+            u.T = s;
+            let f;
+            let a;
+            const settle = e => {
+                if (f !== undefined) clearTimeout(f);
+                if (a !== undefined) o.removeEventListener("abort", a);
+                e();
+                c();
+            };
+            effect(r === null ? e : () => {
+                const t = e();
+                // Runs inside the compute (pure phase): the confirming
+                // transition's stamps are live and its commit hasn't run, so
+                // the merge lands before any reveal. Falsy evaluations skip —
+                // non-flipping updates were never named as the confirmation.
+                                if (t) entangleConfirmingTransitions(getObserver(), r);
+                return t;
+            }, e => {
+                // Falsy is "not yet": keep the subscription live and wait for the
+                // next evaluation. Only a truthy settled value resolves.
+                if (e) settle(() => n(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
+            // apply — a staged effect value would deadlock the hold on data
+            // the hold itself is keeping uncommitted.
+            {
+                user: true,
+                Xt: CONFIG_AUTHORITATIVE_READ | CONFIG_DIRECT_COMMIT
+            });
+            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
+                });
+            }
+        });
+    });
+}
+
+function createOptimistic(e, t) {
+    // Install before the node exists: only engine-installed programs can carry
+    // an _overrideValue slot (same runtime-install pattern as
+    // GlobalQueue._clearOptimisticStore in createOptimisticStore).
+    installOptimisticEngine();
+    if (typeof e === "function") {
+        const r = optimisticComputed(e, t);
+        r.C &= ~CONFIG_AUTO_DISPOSE;
+        return [ accessor(r), setSignal.bind(null, r) ];
+    }
+    const r = optimisticSignal(e, t);
+    registerGraph(r, getOwner());
+    return [ accessor(r), setSignal.bind(null, r) ];
+}
+
 /**
  * Schedules `callback` to run **once** after the reactive graph has fully
  * settled — i.e. once every pending async read inside the current owner has
@@ -726,6 +701,25 @@ export declare function createOptimistic<T>(fn: ComputeFunction<T>, options?: Si
  *
  * @param callback Function to run; may return a cleanup function that fires
  *   on owner disposal
- */
-export declare function onSettled(callback: () => void | (() => void)): void;
-export {};
+ */ function onSettled(e) {
+    const t = getOwner();
+    t && !(t.C & CONFIG_CHILDREN_FORBIDDEN) ? trackedEffect(() => untrack(e), {
+        name: "onSettled"
+    }) : globalQueue.enqueue(EFFECT_USER, function fire() {
+        // Settled means derived. A settle that reverts optimism (or replays
+        // gated reads) only enqueues the affected subscribers; the pass after
+        // the commit re-derives them. Fired in the commit pass, the callback
+        // read the optimistic source already reverted beside a sync memo of it
+        // still holding the optimistic value — reads do not pull (#3411). Fall
+        // to the next pass while the heap has work; `run` swapped the queue,
+        // so this lands there, and `enqueue` keeps the drain alive.
+        if (dirtyQueue.EE >= dirtyQueue.Ct) return globalQueue.enqueue(EFFECT_USER, fire);
+        // 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
+        // dropped — never bound to an unrelated owner or run eagerly.
+                e();
+    });
+}
+
+export { accessor, createEffect, createMemo, createOptimistic, createReaction, createRenderEffect, createSignal, createTrackedEffect, onCleanup, onSettled, refresh, resolve, until };