@fluixi/reactive 1.0.0-alpha.83 → 1.0.0-alpha.84

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

@@ -1,17 +1,19 @@
 /**
- * L2 (core) — the legacy public reactive API re-expressed on top of L0 (graph) +
- * L1 (runtime), with byte-identical signatures so it is a drop-in for the existing
- * `createSignal`/`createMemo`/`createEffect`/… surface. This is the "re-point": the
- * old API delegates to the TC39-shaped core instead of the bespoke Computation graph.
+ * The `create*` names, over the graph core and the runtime.
  *
- * Scope: the CORE primitives (signals, memos, effects, roots, batch, untrack, on).
- * The wider surface (resources, stores, context, suspense, transitions, the SSR
- * eager-stale/drain hooks) is ported separately before the production export flips
- * — until then this lives behind its own module + spec, validated for behavioural
- * equivalence against the legacy oracle.
+ * 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.
  *
- * Timing note: legacy effects flush SYNCHRONOUSLY on a write (outside batch), so we
- * install a synchronous L1 scheduler here; `batch` still coalesces to one flush.
+ * 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';
@@ -21,9 +23,9 @@ function isThenable(v) {
 }
 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
+// 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
+// synchronous effects), a synchronous scheduler that flushed mid-propagation would
 // run effects before all observers were marked.
 setScheduler(() => { });
 const $SIGNAL = Symbol.for('signal');
@@ -32,7 +34,7 @@ const $MEMO = Symbol.for('memo');
 // 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. */
+/** 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());
@@ -68,11 +70,11 @@ export function createSignal(value, options) {
         l1onCleanup(() => reportReactiveDispose(state));
     return [read, write];
 }
-/** createMemo — a lazy, cached derived value (legacy accessor). */
+/** 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
+    // 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, () => {
@@ -91,38 +93,38 @@ export function createMemo(fn, value, options) {
         }
     }), { equals: options?.equals });
     const read = (() => c.get());
-    // A memo IS a readable reactive accessor — stamp $SIGNAL (matching the legacy
+    // 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.
+    // 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
+    // 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
+ * 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) {
     let prev = value;
     return l1effect(() => {
         const r = fn(prev);
-        // A function result is treated as the next "prev" (legacy) — unless the fn
+        // 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);
 }
 /**
- * createComputed — an EAGER, owner-managed reactive computation (returns void).
+ * 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 (e.g. store internals). On L1 that is an
- * eager effect whose dispose is owned by the current scope.
+ * 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;
@@ -131,7 +133,7 @@ export function createComputed(fn, value) {
     });
 }
 /**
- * createRenderEffect — an effect that runs in the render phase. For the reactive
+ * 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.
  */
@@ -141,16 +143,16 @@ export function createRenderEffect(fn, value) {
         prev = fn(prev);
     });
 }
-/** batch — coalesce writes so dependent effects flush once. */
+/** batch: coalesce writes so dependent effects flush once. */
 export function batch(fn) {
     return l1batch(fn);
 }
-/** untrack — read without subscribing. */
+/** untrack: read without subscribing. */
 export function untrack(fn) {
     return l0untrack(fn);
 }
 /**
- * startTransition — run `fn`'s updates as one batch. (Minimal port: the concurrent
+ * 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.)
  */
@@ -158,14 +160,14 @@ export function startTransition(fn) {
     l1batch(fn);
     return Promise.resolve();
 }
-/** useTransition — `[isPending, startTransition]`. isPending is synchronous here (no deferral). */
+/** 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
+ * 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.
  */
@@ -174,7 +176,7 @@ export function flush() {
     return Promise.resolve();
 }
 /**
- * on(deps, fn, { defer }) — an explicit-dependency helper. Reads `deps` (tracked),
+ * 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) {