@fluixi/reactive 1.0.0-alpha.100

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

@@ -0,0 +1,197 @@
+/**
+ * The `create*` names, over the graph core and the runtime.
+ *
+ * Signatures are identical to the ones this API has always had, so nothing calling
+ * `createSignal`, `createMemo` or `createEffect` can tell the difference. What
+ * changed underneath is that they now delegate to the TC39-shaped core in `core.ts`
+ * rather than to the bespoke `Computation` graph, which survives in `../signal.ts`
+ * as archive.
+ *
+ * This module covers the primitives: signals, memos, effects, roots, batch, untrack
+ * and on. The wider surface, resources and stores and context and suspense and
+ * transitions and the SSR hooks, is ported in the modules beside it.
+ *
+ * Timing: effects flush synchronously on a write outside a batch, which is what this
+ * API has always done, so the scheduler installed here is synchronous. `batch` still
+ * coalesces a group of writes into one flush.
+ */
+import { State, Computed, untrack as l0untrack } from './core.js';
+import { effect as l1effect, batch as l1batch, setScheduler, afterWrite, flushSync, reportSuspend, getOwner, runWithOwner, onCleanup as l1onCleanup, } from './runtime.js';
+import { isObserved, reportReactiveDispose, reportReactiveNode } from './observe.js';
+function isThenable(v) {
+    return !!v && typeof v.then === 'function';
+}
+export { createRoot, onCleanup, getOwner, setOwner, runWithOwner } from './runtime.js';
+// Compat owns all flush points (afterWrite / batch), so the host scheduler is a
+// no-op: enqueue only queues; a write marks the whole graph then flushes once via
+// afterWrite. This separates marking from running (glitch-free, legacy-equivalent
+// synchronous effects), a synchronous scheduler that flushed mid-propagation would
+// run effects before all observers were marked.
+setScheduler(() => { });
+const $SIGNAL = Symbol.for('signal');
+const $MEMO = Symbol.for('memo');
+// The legacy createSignal attaches a ReactiveNode (with a live `.value`/`.version`)
+// under this symbol; consumers like the store read `signal[$NODE].value` to gate
+// updates. compat exposes a matching node-like view so those consumers work unchanged.
+const $NODE = Symbol.for('signal-node');
+/** createSignal, a writable cell, returned as the legacy `[get, set]` tuple. */
+export function createSignal(value, options) {
+    const state = new State(value, { equals: options?.equals });
+    const read = (() => state.get());
+    const write = ((next) => {
+        const v = typeof next === 'function' ? next(state.peek()) : next;
+        state.set(v); // marks the graph dirty
+        afterWrite(); // then flush effects once (no-op inside a batch)
+        return v;
+    });
+    Object.defineProperty(read, $SIGNAL, { value: true, enumerable: true });
+    // Node-like view for consumers (e.g. the store) that read `signal[$NODE].value`.
+    Object.defineProperty(read, $NODE, {
+        value: {
+            get value() {
+                return state.peek();
+            },
+            get version() {
+                return state.version;
+            },
+        },
+        enumerable: false,
+    });
+    reportReactiveNode({
+        kind: 'signal',
+        node: state,
+        handle: read,
+        name: options?.name,
+        set: write,
+    });
+    // A signal goes when its owner does, the same as a memo. A list rebuilt without a key
+    // makes one per row per update, and a watcher that is never told keeps every one of them.
+    if (isObserved())
+        l1onCleanup(() => reportReactiveDispose(state));
+    return [read, write];
+}
+/** createMemo, a lazy, cached derived value (legacy accessor). */
+export function createMemo(fn, value, options) {
+    let prev = value;
+    // Capture the owner at creation so the memo's fn (and any component it renders, e.g.
+    // a lazy route) runs under this scope's owner, preserving context up the owner chain
+    // even when the memo recomputes later (async SSR drain). Matches legacy memo semantics.
+    const owner = getOwner();
+    const c = new Computed(() => runWithOwner(owner, () => {
+        try {
+            return (prev = fn(prev));
+        }
+        catch (e) {
+            // A suspended read (resource/lazy while pending) throws its promise. Legacy
+            // memos keep their previous value and let a Suspense boundary handle it,
+            // rather than rethrowing the promise as an error.
+            if (isThenable(e)) {
+                reportSuspend(e);
+                return prev;
+            }
+            throw e;
+        }
+    }), { equals: options?.equals });
+    const read = (() => c.get());
+    // A memo is a readable reactive accessor: stamp $SIGNAL (matching the legacy
+    // createMemo) so `isSignal(memo)` is true. Without this, the DOM runtime's
+    // insert() fails to recognise a control-flow memo (For/Switch/Index/Dynamic)
+    // as reactive, caches it as a component, and freezes it -> updates never apply.
+    Object.defineProperty(read, $SIGNAL, { value: true, enumerable: true });
+    Object.defineProperty(read, $MEMO, { value: true, enumerable: true });
+    reportReactiveNode({ kind: 'memo', node: c, handle: read, name: options?.name });
+    // A memo has no dispose of its own, it goes when its owner does. Without saying so, a
+    // list that re-renders leaves every row it ever had in a watcher's graph.
+    if (isObserved())
+        l1onCleanup(() => reportReactiveDispose(c));
+    return read;
+}
+/**
+ * createEffect, a re-running side effect. The fn receives the previous return
+ * value and may return a new one (legacy signature) or a cleanup function.
+ */
+export function createEffect(fn, value, options) {
+    let prev = value;
+    return l1effect(() => {
+        const r = fn(prev);
+        // A function result is treated as the next "prev" (legacy), unless the fn
+        // never returns one, in which case onCleanup is the cleanup path. We keep the
+        // legacy carry-the-value behaviour; cleanups use onCleanup.
+        prev = r;
+    }, true, options?.name);
+}
+/**
+ * createComputed, an EAGER, owner-managed reactive computation (returns void).
+ * Unlike a lazy memo it runs immediately and re-runs eagerly when a dep changes;
+ * used for derivations with side effects, such as store internals. It is an eager
+ * effect whose dispose is owned by the current scope.
+ */
+export function createComputed(fn, value) {
+    let prev = value;
+    l1effect(() => {
+        prev = fn(prev);
+    });
+}
+/**
+ * createRenderEffect, an effect that runs in the render phase. For the reactive
+ * core this is an eager effect (the render-vs-commit timing distinction is a DOM-
+ * layer concern); returns a dispose like createEffect.
+ */
+export function createRenderEffect(fn, value) {
+    let prev = value;
+    return l1effect(() => {
+        prev = fn(prev);
+    });
+}
+/** batch: coalesce writes so dependent effects flush once. */
+export function batch(fn) {
+    return l1batch(fn);
+}
+/** untrack: read without subscribing. */
+export function untrack(fn) {
+    return l0untrack(fn);
+}
+/**
+ * startTransition: run `fn`'s updates as one batch. (Minimal port, the concurrent
+ * time-slicing/deferral of the legacy implementation is a later refinement; the
+ * batched-commit semantics that callers rely on are preserved.)
+ */
+export function startTransition(fn) {
+    l1batch(fn);
+    return Promise.resolve();
+}
+/** useTransition: `[isPending, startTransition]`. isPending is synchronous here (no deferral). */
+export function useTransition() {
+    return [() => false, startTransition];
+}
+/** Force any pending effects to run now. */
+export { flushSync };
+/**
+ * flush: drain pending effects, returning a Promise (legacy `flush()` is async; many
+ * callers do `flush().then(...)`). Effects already flush synchronously on each write via
+ * afterWrite, so this just settles any remainder and resolves.
+ */
+export function flush() {
+    flushSync();
+    return Promise.resolve();
+}
+/**
+ * on(deps, fn, { defer }), an explicit-dependency helper. Reads `deps` (tracked),
+ * then runs `fn(value, prevValue, prevResult)` untracked. `defer` skips the first run.
+ */
+export function on(deps, fn, options) {
+    const isArray = Array.isArray(deps);
+    let prevValue;
+    let defer = options?.defer ?? false;
+    return (prevResult) => {
+        const value = (isArray ? deps.map((d) => d()) : deps());
+        if (defer) {
+            defer = false;
+            prevValue = value;
+            return undefined;
+        }
+        const result = l0untrack(() => fn(value, prevValue, prevResult));
+        prevValue = value;
+        return result;
+    };
+}