@cardenelabs/cdl 0.5.0

package/src/reactive/batch.ts

@@ -0,0 +1,48 @@
+import {
+  enterBatch,
+  exitBatch,
+  setCurrentSubscriber,
+} from "./internal";
+
+/**
+ * 複数の signal set を 1 tick に集約する。 batch 内では effect の実行が deferred queue に蓄積、
+ * batch 終了時にまとめて flush される (同じ effect が dep 変化で複数回 trigger されても 1 回に集約)。
+ *
+ * nested batch は最外側の batch 終了時にのみ flush、 途中の内側 batch では実行しない。
+ */
+export function batch<T>(fn: () => T): T {
+  enterBatch();
+  let bodyError: unknown;
+  let bodyThrew = false;
+  let result!: T;
+  try {
+    result = fn();
+  } catch (e) {
+    bodyError = e;
+    bodyThrew = true;
+  }
+  // exitBatch は flushEffects を trigger、 effect が throw する可能性あり。
+  // body 側で先に error が発生した場合、 flush 側 error で上書きすると root cause の body error が失われる。
+  // body error 優先で throw、 flush error は body error があれば silently drop する。
+  try {
+    exitBatch();
+  } catch (flushError) {
+    if (bodyThrew) throw bodyError;
+    throw flushError;
+  }
+  if (bodyThrew) throw bodyError;
+  return result;
+}
+
+/**
+ * fn 内の signal / computed read を dependency 追跡から除外する。 effect 内で
+ * 「値は見たいが再実行 trigger にしたくない」 用途 (initial state だけ読みたい 等)。
+ */
+export function untrack<T>(fn: () => T): T {
+  const prev = setCurrentSubscriber(null);
+  try {
+    return fn();
+  } finally {
+    setCurrentSubscriber(prev);
+  }
+}

package/src/reactive/computed.ts

@@ -0,0 +1,85 @@
+import {
+  currentSubscriber,
+  type Dependency,
+  setCurrentSubscriber,
+  type Subscriber,
+  unsubscribeFromDeps,
+} from "./internal";
+
+/**
+ * dependency 変化時に自動で再計算される derived value。 lazy evaluation で、
+ * `.value` が read されるまでは fn を評価しない。 memoize して dep が変化しない限り再計算しない。
+ *
+ * computed は subscriber (dep 変化を受け取る) かつ dependency (下流の computed / effect の dep になる)
+ * の両側面を持つ = graph の中間 node。
+ */
+export interface Computed<T> {
+  get value(): T;
+  peek(): T;
+}
+
+class ComputedImpl<T> implements Computed<T>, Subscriber, Dependency {
+  private _value!: T;
+  private dirty = true;
+  deps = new Set<Dependency>();
+  private subscribers = new Set<Subscriber>();
+  private initialized = false;
+
+  constructor(private fn: () => T) {}
+
+  notify(): void {
+    this.dirty = true;
+    // 下流の subscribers (effect / 別 computed) に propagate。
+    // 過去実装で `if (this.dirty) return` していたが、 recompute() が throw して dirty 状態に
+    // 残った時、 以降の dep 変化で notify が来ても即 return して downstream に伝わらず、
+    // effect が「computed を再読むと復旧値になっているのに、 呼ばれない」 という stuck 状態を招いた。
+    // effect 側は scheduleEffect の Set dedupe で重複 execute を防ぐので、 常に propagate で問題ない。
+    const subs = Array.from(this.subscribers);
+    for (const sub of subs) {
+      sub.notify();
+    }
+  }
+
+  get value(): T {
+    if (currentSubscriber) {
+      this.addSubscriber(currentSubscriber);
+      currentSubscriber.deps.add(this);
+    }
+    if (this.dirty || !this.initialized) {
+      this.recompute();
+    }
+    return this._value;
+  }
+
+  peek(): T {
+    if (this.dirty || !this.initialized) {
+      this.recompute();
+    }
+    return this._value;
+  }
+
+  private recompute(): void {
+    // 古い deps を解除、 新規 deps を fn 実行中に収集
+    unsubscribeFromDeps(this);
+    const prev = setCurrentSubscriber(this);
+    try {
+      this._value = this.fn();
+      this.initialized = true;
+      this.dirty = false;
+    } finally {
+      setCurrentSubscriber(prev);
+    }
+  }
+
+  addSubscriber(sub: Subscriber): void {
+    this.subscribers.add(sub);
+  }
+
+  removeSubscriber(sub: Subscriber): void {
+    this.subscribers.delete(sub);
+  }
+}
+
+export function computed<T>(fn: () => T): Computed<T> {
+  return new ComputedImpl(fn);
+}

package/src/reactive/effect.ts

@@ -0,0 +1,145 @@
+import {
+  type Dependency,
+  enterBatch,
+  exitBatch,
+  pendingEffects,
+  type Runnable,
+  scheduleEffect,
+  setCurrentSubscriber,
+  type Subscriber,
+  unsubscribeFromDeps,
+} from "./internal";
+
+/**
+ * side-effect を dependency 変化に紐付ける primitive。 effect 生成時に即実行 (eager)、
+ * fn 内で読んだ signal / computed が dep として自動登録される。 dep が変化すると再実行 queue に入り、
+ * batch 外なら即実行、 batch 中なら batch 終了時に flush される。
+ *
+ * fn の戻り値 (cleanup function) は、 次の再実行前 or dispose 時に呼ばれる (DOM listener 解除等)。
+ * effect 関数の戻り値 = dispose function、 呼び出すと以降の再実行を止めて cleanup 実行。
+ */
+class EffectImpl implements Subscriber, Runnable {
+  deps = new Set<Dependency>();
+  private cleanupFn: (() => void) | void | undefined;
+  private disposed = false;
+  private initialized = false;
+
+  constructor(private fn: () => void | (() => void)) {
+    // 初回 execute() が throw した場合、 fn が既に signal を read して dep 登録している可能性あり。
+    // dispose せずに throw だけ返すと、 呼出側は disposer を受け取れず (constructor が throw で return しない)、
+    // 以降の signal 変化で orphaned effect が実行され続ける。 例外前に必ず dispose して dep 解除する。
+    try {
+      this.execute();
+    } catch (e) {
+      this.dispose();
+      throw e;
+    }
+  }
+
+  notify(): void {
+    if (this.disposed) return;
+    scheduleEffect(this);
+  }
+
+  execute(): void {
+    if (this.disposed) return;
+    // execute 全体を implicit batch で包む。 fn 内で signal set が起こると、
+    // signal setter 側の batch (batchDepth=2) から exit した時点で batchDepth が 0 に落ちて
+    // flushEffects が発火、 現 execute() のスタックが残っている状態で再度 execute() が呼ばれる
+    // re-entrancy を招く (nested run の cleanupFn が outer で上書きされて次回 stale)。
+    // execute 全体を batch で包むことで、 execute 完了までは flush が deferred される。
+    enterBatch();
+    let caughtError: unknown;
+    let hasError = false;
+    let cleanupThrew = false;
+    try {
+      try {
+      // 先に古い deps を解除してから cleanup を呼ぶ (順序重要)。
+      // cleanup が前回 dep signal に write すると、 その write が同 effect の notify を trigger して
+      // 自分自身が再 schedule され、 単発 update で spurious re-run / cleanup 駆動 loop になる。
+      // 先に unsubscribe しておけば cleanup 内の write は自分を trigger しない。
+      unsubscribeFromDeps(this);
+      // cleanup 呼出。 cleanup 内の signal read は「外側 subscriber (別 effect / computed) の dep」 に
+      // 混入しないよう currentSubscriber を一時 null 化 (untrack 相当)。
+      if (typeof this.cleanupFn === "function") {
+        const prevSub = setCurrentSubscriber(null);
+        try {
+          this.cleanupFn();
+        } catch (e) {
+          this.cleanupFn = undefined;
+          setCurrentSubscriber(prevSub);
+          cleanupThrew = true;
+          throw e;
+        }
+        this.cleanupFn = undefined;
+        setCurrentSubscriber(prevSub);
+      }
+      // 新規 deps を fn 実行中に収集
+      const prev = setCurrentSubscriber(this);
+      try {
+        this.cleanupFn = this.fn();
+      } finally {
+        setCurrentSubscriber(prev);
+      }
+      // 初回 execute 成功 = initialized。 subsequent execute の throw で transient recovery path を有効化。
+      this.initialized = true;
+    } catch (e) {
+      // fn () / cleanup が throw した場合の処理は 3 case で分岐:
+      // (1) 初回 execute (!initialized) の throw = dispose 完全終了 (constructor 側で catch されるが
+      //     dispose 前に flushEffects が動く可能性、 self-schedule された場合の再実行防止のため synchronous に disposed 化)
+      // (2) subsequent execute + cleanup throw = 新規 fn 実行前に既に unsubscribeFromDeps 済で
+      //     recovery 経路が無い、 dispose 完全終了
+      // (3) subsequent execute + fn throw = fn 内で新規 dep 追加済、 dep 変化での再実行 = transient error 復旧 path、
+      //     dispose せず deps を維持、 self-schedule のみ解除
+      caughtError = e;
+      hasError = true;
+      pendingEffects.delete(this);
+      if (!this.initialized || cleanupThrew) {
+        this.disposed = true;
+        unsubscribeFromDeps(this);
+        this.cleanupFn = undefined;
+      }
+    }
+    } finally {
+      // exitBatch 側で flushEffects が throw する可能性あり、 body 側 (fn/cleanup) の caughtError を優先。
+      try {
+        exitBatch();
+      } catch (flushError) {
+        if (!hasError) {
+          caughtError = flushError;
+          hasError = true;
+        }
+      }
+    }
+    if (hasError) {
+      throw caughtError;
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    // dispose も同様、 cleanup 内 read を外側 subscriber から遮断。
+    // cleanup が throw した場合でも unsubscribeFromDeps は必ず実行して subscriber set から離脱する
+    // (throw で unsubscribe が skip されると、 dead effect が signal.subscribers に残り続けて
+    // 以降の signal 変化で notify され続ける orphan retention 問題)。
+    try {
+      if (typeof this.cleanupFn === "function") {
+        const prevSub = setCurrentSubscriber(null);
+        try {
+          this.cleanupFn();
+        } finally {
+          this.cleanupFn = undefined;
+          setCurrentSubscriber(prevSub);
+        }
+      }
+    } finally {
+      unsubscribeFromDeps(this);
+    }
+  }
+}
+
+export function effect(fn: () => void | (() => void)): () => void {
+  const e = new EffectImpl(fn);
+  return () => e.dispose();
+}

package/src/reactive/index.ts

@@ -0,0 +1,6 @@
+export { signal } from "./signal";
+export type { Signal } from "./signal";
+export { computed } from "./computed";
+export type { Computed } from "./computed";
+export { effect } from "./effect";
+export { batch, untrack } from "./batch";

package/src/reactive/internal.ts

@@ -0,0 +1,109 @@
+/**
+ * Preact signals 相当の pull-based reactive graph の internal state。
+ *
+ * 3 primitive (signal / computed / effect) の依存追跡を「read 時に current subscriber を
+ * dep として自動記録」 + 「write 時に subscriber を notify」 で構成する。
+ *
+ * batch は notify を deferred queue に蓄積して、 top-level batch 終了時にまとめて実行、
+ * 冗長な effect 実行を防ぐ。 untrack は current subscriber を一時的に null にして
+ * 「この read だけ dependency として記録しない」 を実現する。
+ *
+ * 依存追跡 model = pull-based (computed は lazy、 dirty flag で invalidate、 read 時に再計算)、
+ * effect は eager (直ちに実行 + dep 変化時に再実行 queue へ)。
+ */
+
+export interface Subscriber {
+  /** dep から notify されて自身が invalidate された旨を伝える */
+  notify(): void;
+  /** dependency を再計算のため clear + 再収集する時に signal / computed 側から呼ぶ */
+  deps: Set<Dependency>;
+}
+
+export interface Dependency {
+  /** subscriber を dep 側に登録 / 解除する */
+  addSubscriber(sub: Subscriber): void;
+  removeSubscriber(sub: Subscriber): void;
+}
+
+/** 現在計算中の subscriber (computed の fn 内 or effect の fn 内で set される) */
+export let currentSubscriber: Subscriber | null = null;
+
+export function setCurrentSubscriber(sub: Subscriber | null): Subscriber | null {
+  const prev = currentSubscriber;
+  currentSubscriber = sub;
+  return prev;
+}
+
+/**
+ * schedule 対象となる Runnable (effect 実装が implement する)。 Set の key に instance を使うことで
+ * 同 effect が batch 内に複数回 notify されても 1 回に集約される (dedupe)。
+ */
+export interface Runnable {
+  execute(): void;
+}
+
+/** batch 中は effect の実行を deferred queue に蓄積 */
+export let batchDepth = 0;
+export const pendingEffects = new Set<Runnable>();
+
+export function enterBatch(): void {
+  batchDepth++;
+}
+
+export function exitBatch(): void {
+  batchDepth--;
+  if (batchDepth === 0) {
+    flushEffects();
+  }
+}
+
+export function isInBatch(): boolean {
+  return batchDepth > 0;
+}
+
+export function scheduleEffect(runnable: Runnable): void {
+  pendingEffects.add(runnable);
+  if (batchDepth === 0) {
+    flushEffects();
+  }
+}
+
+function flushEffects(): void {
+  // Set を snapshot せず、 直接 iterator で 1 件ずつ取り出し + delete して execute する。
+  // snapshot 化すると、 execute 中に別 effect が signal write で snapshot 内 entry を再 add した場合、
+  // 「nested flushEffects で 1 度実行」 + 「outer snapshot loop でもう 1 度実行」 で二重実行になる
+  // (effect が execute 内 exitBatch で flushEffects を recursively 呼ぶため)。
+  // Set を直接 drain すれば nested flush と outer flush が同じ Set を共有して 1 度のみ実行される。
+  // effect 内で throw した場合でも残 effect を落とさず全て execute する
+  // (最初の error を保持して flush 終わりに throw、 以降の effect は run 済み)。
+  let firstError: unknown;
+  let hasError = false;
+  while (pendingEffects.size > 0) {
+    const iterator = pendingEffects.values();
+    const first = iterator.next();
+    if (first.done) break;
+    const runnable = first.value;
+    pendingEffects.delete(runnable);
+    try {
+      runnable.execute();
+    } catch (e) {
+      if (!hasError) {
+        firstError = e;
+        hasError = true;
+      }
+    }
+  }
+  if (hasError) {
+    throw firstError;
+  }
+}
+
+/**
+ * subscriber の dep set から自身を切り離す (effect dispose / computed の deps 再収集時)。
+ */
+export function unsubscribeFromDeps(sub: Subscriber): void {
+  for (const dep of sub.deps) {
+    dep.removeSubscriber(sub);
+  }
+  sub.deps.clear();
+}

package/src/reactive/signal.ts

@@ -0,0 +1,113 @@
+import {
+  currentSubscriber,
+  type Dependency,
+  enterBatch,
+  exitBatch,
+  setCurrentSubscriber,
+  type Subscriber,
+} from "./internal";
+
+/**
+ * mutable な reactive value。 `.value` getter / setter で読み書き、
+ * 読み取り時に current subscriber (computed / effect) を dep として自動登録する。
+ *
+ * `.peek()` は依存追跡なしで現 value を読み取る (effect 内で「値は見たいが再実行 trigger にしたくない」 用途)。
+ * `.subscribe(fn)` は effect 経路を通さず手動で notification listener を登録する
+ * (framework 統合 / 外部 stream との bridge 用途、 dispose function を返す)。
+ */
+export interface Signal<T> {
+  get value(): T;
+  set value(v: T);
+  peek(): T;
+  subscribe(fn: (v: T) => void): () => void;
+}
+
+class SignalImpl<T> implements Signal<T>, Dependency {
+  private _value: T;
+  private subscribers = new Set<Subscriber>();
+  private manualListeners = new Set<(v: T) => void>();
+
+  constructor(initial: T) {
+    this._value = initial;
+  }
+
+  get value(): T {
+    if (currentSubscriber) {
+      this.addSubscriber(currentSubscriber);
+      currentSubscriber.deps.add(this);
+    }
+    return this._value;
+  }
+
+  set value(next: T) {
+    if (Object.is(next, this._value)) return;
+    this._value = next;
+    // notify cascade 全体を implicit batch で包む。 batch なしで書換えると、
+    // 1 signal set の subscriber 走査中に effect が即 flush されて、 別 subscriber の
+    // dirty marking が終わっていない状態で computed を read してしまう。
+    // 実例 = b = computed(a+1) / c = computed(a*2) / effect(b + c) で a=1→10 の 1 write が、
+    // b は更新 / c は未更新 の中間 state で effect 実行され「13」 の偽値を emit する。
+    // batch でくるむと、 全 subscriber の dirty marking + effect scheduling が終わってから 1 度だけ flush される。
+    enterBatch();
+    try {
+      // subscribers を snapshot、 notify 中に set が起こると subscribers に mutate が起きる可能性
+      const subs = Array.from(this.subscribers);
+      for (const sub of subs) {
+        sub.notify();
+      }
+      // 手動 listener は last (subscriber notify で effect が実行される場合の順序性維持)。
+      // listener 内の signal / computed read が「set した側の subscriber」 に dep として
+      // 混入するのを防ぐため untrack 経路で invoke する (currentSubscriber を一時 null 化)。
+      // manualListeners も snapshot して iteration。 subscribe callback がその場で
+      // 別 listener を add した場合、 live iteration だと new listener を「初回 subscribe callback で 1 回」
+      // + 「本 iteration で notify として 1 回」 の 2 度呼びしてしまう。
+      const listenerSnapshot = Array.from(this.manualListeners);
+      const prevSub = setCurrentSubscriber(null);
+      try {
+        for (const listener of listenerSnapshot) {
+          listener(next);
+        }
+      } finally {
+        setCurrentSubscriber(prevSub);
+      }
+    } finally {
+      exitBatch();
+    }
+  }
+
+  peek(): T {
+    return this._value;
+  }
+
+  subscribe(fn: (v: T) => void): () => void {
+    this.manualListeners.add(fn);
+    // 初回 immediately 実行 (subscribe 時点の値を渡す)。
+    // callback が throw した場合、 listener 未登録の状態に巻き戻して再 throw する
+    // (登録されっぱなしだと以降の set() で毎回 throw する orphan listener になる)。
+    // callback 内の read も untrack して subscribe 呼出側の subscriber に dep 混入させない。
+    const prevSub = setCurrentSubscriber(null);
+    try {
+      fn(this._value);
+    } catch (e) {
+      this.manualListeners.delete(fn);
+      throw e;
+    } finally {
+      setCurrentSubscriber(prevSub);
+    }
+    return () => {
+      this.manualListeners.delete(fn);
+    };
+  }
+
+  addSubscriber(sub: Subscriber): void {
+    this.subscribers.add(sub);
+  }
+
+  removeSubscriber(sub: Subscriber): void {
+    this.subscribers.delete(sub);
+  }
+}
+
+export function signal<T>(initial: T): Signal<T> {
+  return new SignalImpl(initial);
+}