@fluixi/reactive 1.0.0-alpha.100

package/dist/lib/signal/graph/runtime.js

@@ -0,0 +1,358 @@
+/**
+ * The runtime layer, on top of the graph core in `core.ts`.
+ *
+ * TC39 ships `State`, `Computed` and `Watcher` and stops there. Everything else a
+ * framework needs is left to userland, and this module is that userland:
+ *
+ *   - Owner tree:   createRoot, onCleanup, getOwner, runWithOwner. No graph edges;
+ *                   ownership is about disposal, not dependency.
+ *   - Scheduler:    an effect queue with flushSync and batch.
+ *   - effect():     a re-running side effect, built from a Computed, a Watcher and
+ *                   an owner.
+ *
+ * This is the live implementation. `@fluixi/reactive/signal` re-exports it through
+ * `signal-next.ts`, and `compat.ts` puts the `create*` names over the top, so the
+ * long-standing public API lands here.
+ *
+ * Effects are built on `Signal.subtle.Watcher` the way the proposal intends: the
+ * watcher's notify only schedules, and the re-run, a tracked recompute, happens on
+ * flush.
+ */
+import { Computed, Watcher, untrack } from './core.js';
+import { G } from './state.js';
+import { reportReactiveContext, reportReactiveContextCreated, reportReactiveDispose, reportReactiveNode, } from './observe.js';
+/**
+ * A child scope of `parent`, attached so the parent's teardown disposes it too.
+ *
+ * For a derivation that re-runs: context still resolves up the chain from the
+ * creation-time owner, while anything registered during a run belongs to this
+ * scope and can be torn down before the next one: instead of accumulating on
+ * the enclosing scope and only running when that finally dies.
+ */
+export function createChildOwner(parent) {
+    const owner = makeOwner(parent);
+    if (parent)
+        (parent.owned ??= []).push(owner);
+    return owner;
+}
+/**
+ * Tear down a scope's children and cleanups.
+ *
+ * `final: false` keeps the scope itself alive and reusable, what a re-running
+ * derivation needs between runs.
+ */
+export function disposeScope(owner, final = true) {
+    disposeOwner(owner, final);
+}
+/** True once `owner` has been disposed. Deferred work should bail rather than run. */
+export function isOwnerDisposed(owner) {
+    return !!owner && owner.disposed === true;
+}
+// Owner / scheduler / boundary-hook state all live on the shared globalThis-backed G
+// (see ./state.ts) so duplicate module copies share one graph.
+function makeOwner(parent) {
+    return { cleanups: null, owned: null, parent, contexts: null };
+}
+export function createContext(defaultValue, name) {
+    // Named so a watcher can tell two of them apart. Nothing else reads the description.
+    const id = Symbol(name ?? 'context');
+    reportReactiveContextCreated(id);
+    const Provider = (props) => {
+        // Stamp the value on a DEDICATED child owner, then read `children` under it: never
+        // on the current owner directly. Two sibling <Ctx.Provider> elements used inline (no
+        // wrapping component) run under the same ambient owner, so stamping there lets the
+        // second clobber the first's entry, every descendant then resolves the last value.
+        // A child scope isolates each Provider; because createMemo captures the owner at
+        // creation, the children memos built while reading `props.children` here capture this
+        // scope and resolve the right value even when rendered lazily (Portal/Show/For).
+        reportReactiveContext(id, 'provide', props.value);
+        const parent = G.owner;
+        const owner = makeOwner(parent);
+        (owner.contexts = new Map()).set(id, props.value);
+        if (parent)
+            (parent.owned ??= []).push(owner);
+        G.owner = owner;
+        try {
+            return props.children;
+        }
+        finally {
+            G.owner = parent;
+        }
+    };
+    return { id, defaultValue, Provider };
+}
+/** Read the nearest provided value for `context`, or its default. */
+export function useContext(context) {
+    let o = G.owner;
+    while (o) {
+        if (o.contexts && o.contexts.has(context.id)) {
+            const found = o.contexts.get(context.id);
+            reportReactiveContext(context.id, 'read', found);
+            return found;
+        }
+        o = o.parent;
+    }
+    reportReactiveContext(context.id, 'read', context.defaultValue);
+    return context.defaultValue;
+}
+/** Read `context` starting from a specific owner chain (not the current scope). */
+export function readContextFrom(owner, context) {
+    let o = owner;
+    while (o) {
+        if (o.contexts && o.contexts.has(context.id))
+            return o.contexts.get(context.id);
+        o = o.parent;
+    }
+    return context.defaultValue;
+}
+/** Run `fn` in a child scope that provides `value` for `context`. */
+export function provide(context, value, fn) {
+    const owner = makeOwner(G.owner);
+    (owner.contexts = new Map()).set(context.id, value);
+    if (G.owner)
+        (G.owner.owned ??= []).push(owner);
+    const prev = G.owner;
+    G.owner = owner;
+    try {
+        return fn();
+    }
+    finally {
+        G.owner = prev;
+    }
+}
+// ── Suspend / error hooks, injected by the boundary layers so this file stays clear of them ──
+/** Register how a thrown promise (a suspended read) is reported to a boundary. */
+export function setSuspendHandler(fn) {
+    G.onSuspend = fn;
+}
+/** Report a suspended read (thrown promise) to the nearest boundary from the current owner. */
+export function reportSuspend(promise) {
+    if (G.onSuspend) {
+        G.onSuspend(promise, G.owner);
+        return true;
+    }
+    return false;
+}
+/** Register how a thrown error is routed to an error boundary. Return true if handled. */
+export function setErrorHandler(fn) {
+    G.onError = fn;
+}
+export function getOwner() {
+    return G.owner;
+}
+/** Set the current owner directly, returning the previous one. (Framework render glue.) */
+export function setOwner(owner) {
+    const prev = G.owner;
+    G.owner = owner;
+    return prev;
+}
+export function runWithOwner(owner, fn) {
+    const prev = G.owner;
+    G.owner = owner;
+    try {
+        return fn();
+    }
+    finally {
+        G.owner = prev;
+    }
+}
+/** Register a teardown for the current owner scope. */
+export function onCleanup(fn) {
+    if (!G.owner)
+        return; // no owner -> not retained, runs never (matches Solid)
+    // A disposed owner is dead, pushing here would recreate its (nulled) cleanups
+    // array and never run, a leak. Run the teardown immediately instead, so a
+    // teardown registered from deferred work (a queued onMount) still fires.
+    if (G.owner.disposed) {
+        fn();
+        return;
+    }
+    (G.owner.cleanups ??= []).push(fn);
+}
+// `final` distinguishes a permanent teardown (the scope is gone: mark it disposed so
+// deferred work bails) from an effect's between-runs cleanup (the owner is REUSED for
+// the next run, so it must not be marked disposed). Children are always torn down
+// permanently, only the effect's own owner survives a re-run.
+function disposeOwner(owner, final = true) {
+    if (owner.disposed)
+        return;
+    if (owner.owned) {
+        for (let i = owner.owned.length - 1; i >= 0; i--)
+            disposeOwner(owner.owned[i]);
+        owner.owned = null;
+    }
+    if (owner.cleanups) {
+        for (let i = owner.cleanups.length - 1; i >= 0; i--)
+            owner.cleanups[i]();
+        owner.cleanups = null;
+    }
+    if (final)
+        owner.disposed = true;
+}
+/**
+ * Create a root reactive scope with explicit disposal (TC39 has no ownership). Untracked: what
+ * runs in it belongs to it, so the computation that created it does not depend on its reads.
+ */
+export function createRoot(fn) {
+    const owner = makeOwner(G.owner);
+    if (G.owner)
+        (G.owner.owned ??= []).push(owner);
+    const prev = G.owner;
+    G.owner = owner;
+    try {
+        return untrack(() => fn(() => disposeOwner(owner)));
+    }
+    finally {
+        G.owner = prev;
+    }
+}
+// ── Scheduler (TC39 has none): state on G (see ./state.ts) ───────────────────
+export function setScheduler(fn) {
+    G.hostSchedule = fn ?? ((run) => void Promise.resolve().then(run));
+}
+function enqueue(e) {
+    if (e.queued)
+        return;
+    e.queued = true;
+    G.queue.push(e);
+    if (!G.scheduled && G.batchDepth === 0) {
+        G.scheduled = true;
+        G.hostSchedule(flushSync);
+    }
+}
+/** Drain all pending effects now (synchronously). */
+export function flushSync() {
+    G.scheduled = false;
+    // Re-entrancy guard: an effect that writes a signal during its run re-enqueues;
+    // the running loop below picks that up, so a nested flushSync must be a no-op
+    // (otherwise the same G.queue drains twice).
+    if (G.flushing)
+        return;
+    G.flushing = true;
+    let guard = 0;
+    // An effect that throws must not stop the rest: those queued after it would be dropped
+    // with their `queued` mark still set, so nothing could ever run them again. The first
+    // error is rethrown once the queue is drained.
+    let failed = false;
+    let first;
+    try {
+        while (G.queue.length) {
+            if (++guard > 100000)
+                throw new Error('[fluixi] effect flush did not settle (cycle?)');
+            const batchOf = G.queue;
+            G.queue = [];
+            for (const e of batchOf) {
+                e.queued = false;
+                if (e.disposed)
+                    continue;
+                try {
+                    e.run();
+                }
+                catch (error) {
+                    if (!failed) {
+                        failed = true;
+                        first = error;
+                    }
+                }
+            }
+        }
+    }
+    finally {
+        G.flushing = false;
+    }
+    if (failed)
+        throw first;
+}
+/**
+ * Run pending effects after a write completes, but only at the top level (not
+ * inside a batch). A single write thus marks the whole graph dirty first, then
+ * flushes once (legacy-equivalent synchronous effects, glitch-free). The `G.flushing`
+ * guard makes a write inside an effect a no-op here (the running loop drains it).
+ */
+export function afterWrite() {
+    if (G.batchDepth === 0)
+        flushSync();
+}
+/** Group writes so dependent effects flush once, at the end. */
+export function batch(fn) {
+    G.batchDepth++;
+    try {
+        return fn();
+    }
+    finally {
+        if (--G.batchDepth === 0)
+            flushSync();
+    }
+}
+// ── effect(): built on Computed + Watcher + Owner ───────────────────────────
+class EffectNode {
+    computed;
+    watcher;
+    owner;
+    queued = false;
+    disposed = false;
+    constructor(fn, report = false, name) {
+        this.owner = makeOwner(G.owner);
+        // Tie disposal to the creating scope, when the parent owner tears down it must
+        // fully dispose this effect (unwatch + body cleanups), not just run the body
+        // cleanups. Register dispose() as a parent cleanup rather than as an owned tree.
+        if (G.owner)
+            (G.owner.cleanups ??= []).push(() => this.dispose());
+        // The Computed runs the user fn inside a tracking scope + this effect's owner,
+        // so reads subscribe and onCleanup/nested roots attach here.
+        this.computed = new Computed(() => {
+            // teardown previous run's cleanups before re-running. not final: the owner is
+            // reused for this run, so it must stay alive (only its children are disposed).
+            disposeOwner(this.owner, false);
+            runWithOwner(this.owner, () => {
+                const r = fn();
+                if (typeof r === 'function')
+                    (this.owner.cleanups ??= []).push(r);
+            });
+        });
+        // Before the first run, so a watcher counts that run like every later one. A render
+        // effect is reported too, marked as plumbing: it is not worth drawing, but a node made
+        // inside one has to be able to find its way back to the component that caused it.
+        reportReactiveNode({ kind: 'effect', node: this.computed, handle: this, internal: !report, ...(name ? { name } : {}) });
+        // The watcher only schedules; the recompute happens on flush.
+        this.watcher = new Watcher(() => enqueue(this));
+        this.run(); // initial synchronous run (Solid semantics)
+        this.watcher.watch(this.computed);
+    }
+    run() {
+        if (this.disposed)
+            return;
+        this.watcher.getPending(); // clear pending; reading re-arms the watcher
+        try {
+            this.computed.get(); // recompute if dirty (re-runs the effect body)
+        }
+        catch (e) {
+            // A suspended read (createResource while pending) throws its promise. Report
+            // it to the nearest Suspense boundary; the effect re-runs via normal
+            // reactivity once the resource's state signal changes. Other errors propagate.
+            if (e && typeof e.then === 'function' && G.onSuspend) {
+                G.onSuspend(e, this.owner);
+                return;
+            }
+            // Route a real error to the nearest error boundary; rethrow if none handled it.
+            if (G.onError && G.onError(e, this.owner))
+                return;
+            throw e;
+        }
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        reportReactiveDispose(this.computed);
+        this.watcher.unwatch(this.computed);
+        disposeOwner(this.owner);
+    }
+}
+/** A re-running side effect. Runs once now, then again (G.scheduled) when deps change. */
+export function effect(fn, report = false, name) {
+    // Reported only when the caller says so. Every DOM binding is a render effect through this
+    // same factory, and a graph holding one node per text node is not a graph anyone reads.
+    const node = new EffectNode(fn, report, name);
+    return () => node.dispose();
+}