@pyreon/reactivity 0.1.0

package/src/tests/store.test.ts

@@ -0,0 +1,136 @@
+import { effect } from "../effect"
+import { reconcile } from "../reconcile"
+import { createStore, isStore } from "../store"
+
+describe("createStore", () => {
+  test("reads primitive properties reactively", () => {
+    const state = createStore({ count: 0 })
+    const calls: number[] = []
+    effect(() => {
+      calls.push(state.count)
+    })
+    expect(calls).toEqual([0])
+    state.count = 1
+    expect(calls).toEqual([0, 1])
+    state.count = 1 // no-op (same value)
+    expect(calls).toEqual([0, 1])
+  })
+
+  test("deep reactive — nested object", () => {
+    const state = createStore({ user: { name: "Alice", age: 30 } })
+    const names: string[] = []
+    effect(() => {
+      names.push(state.user.name)
+    })
+    expect(names).toEqual(["Alice"])
+    state.user.name = "Bob"
+    expect(names).toEqual(["Alice", "Bob"])
+  })
+
+  test("deep reactive — nested change does NOT re-run parent-only effects", () => {
+    const state = createStore({ user: { name: "Alice", age: 30 } })
+    const userCalls: number[] = []
+    const nameCalls: string[] = []
+    effect(() => {
+      userCalls.push(1)
+      void state.user
+    }) // tracks user object
+    effect(() => {
+      nameCalls.push(state.user.name)
+    }) // tracks name only
+    expect(userCalls.length).toBe(1)
+    state.user.age = 31
+    // Only the age signal fires — user object didn't change, name didn't change
+    expect(nameCalls).toEqual(["Alice"]) // name effect didn't re-run
+  })
+
+  test("array — tracks length on push", () => {
+    const state = createStore({ items: [1, 2, 3] })
+    const lengths: number[] = []
+    effect(() => {
+      lengths.push(state.items.length)
+    })
+    expect(lengths).toEqual([3])
+    state.items.push(4)
+    expect(lengths).toEqual([3, 4])
+  })
+
+  test("array — tracks index access", () => {
+    const state = createStore({ items: ["a", "b"] })
+    const values: string[] = []
+    effect(() => {
+      values.push(state.items[0] as string)
+    })
+    expect(values).toEqual(["a"])
+    state.items[0] = "x"
+    expect(values).toEqual(["a", "x"])
+    state.items[1] = "y" // different index — should not re-run this effect
+    expect(values).toEqual(["a", "x"])
+  })
+
+  test("isStore identifies proxy", () => {
+    const raw = { x: 1 }
+    const store = createStore(raw)
+    expect(isStore(store)).toBe(true)
+    expect(isStore(raw)).toBe(false)
+    expect(isStore(null)).toBe(false)
+    expect(isStore(42)).toBe(false)
+  })
+
+  test("same raw object returns same proxy", () => {
+    const raw = { a: 1 }
+    const s1 = createStore(raw)
+    const s2 = createStore(raw)
+    expect(s1).toBe(s2)
+  })
+})
+
+describe("reconcile", () => {
+  test("updates only changed scalar properties", () => {
+    const state = createStore({ name: "Alice", age: 30 })
+    const nameCalls: string[] = []
+    const ageCalls: number[] = []
+    effect(() => {
+      nameCalls.push(state.name)
+    })
+    effect(() => {
+      ageCalls.push(state.age)
+    })
+    reconcile({ name: "Alice", age: 31 }, state)
+    expect(nameCalls).toEqual(["Alice"]) // unchanged — no re-run
+    expect(ageCalls).toEqual([30, 31]) // changed — re-ran
+  })
+
+  test("reconciles nested objects recursively", () => {
+    const state = createStore({ user: { name: "Alice", age: 30 } })
+    const nameCalls: string[] = []
+    effect(() => {
+      nameCalls.push(state.user.name)
+    })
+    reconcile({ user: { name: "Bob", age: 30 } }, state)
+    expect(nameCalls).toEqual(["Alice", "Bob"])
+  })
+
+  test("reconciles arrays by index", () => {
+    const state = createStore({ items: ["a", "b", "c"] })
+    const calls: string[][] = []
+    effect(() => {
+      calls.push([...state.items])
+    })
+    reconcile({ items: ["a", "X", "c"] }, state)
+    expect(state.items[1]).toBe("X")
+    expect(calls.length).toBe(2) // initial + after reconcile
+  })
+
+  test("trims excess array elements", () => {
+    const state = createStore({ items: [1, 2, 3, 4, 5] })
+    reconcile({ items: [1, 2] }, state)
+    expect(state.items.length).toBe(2)
+  })
+
+  test("removes deleted keys", () => {
+    const state = createStore({ a: 1, b: 2, c: 3 } as Record<string, number>)
+    reconcile({ a: 1, b: 2 }, state)
+    expect("c" in state).toBe(false)
+  })
+})

package/src/tests/tracking.test.ts

@@ -0,0 +1,158 @@
+import { batch } from "../batch"
+import { effect, renderEffect } from "../effect"
+import { signal } from "../signal"
+import { runUntracked } from "../tracking"
+
+describe("tracking", () => {
+  describe("notifySubscribers", () => {
+    test("multi-subscriber notification without batching (snapshot path)", () => {
+      const s = signal(0)
+      let runs1 = 0
+      let runs2 = 0
+
+      effect(() => {
+        s()
+        runs1++
+      })
+      effect(() => {
+        s()
+        runs2++
+      })
+
+      expect(runs1).toBe(1)
+      expect(runs2).toBe(1)
+
+      // Triggers non-batched multi-subscriber path (snapshot via [...subscribers])
+      s.set(1)
+      expect(runs1).toBe(2)
+      expect(runs2).toBe(2)
+    })
+
+    test("multi-subscriber notification during batching", () => {
+      const s = signal(0)
+      let runs1 = 0
+      let runs2 = 0
+
+      effect(() => {
+        s()
+        runs1++
+      })
+      effect(() => {
+        s()
+        runs2++
+      })
+
+      batch(() => {
+        s.set(1)
+      })
+
+      expect(runs1).toBe(2)
+      expect(runs2).toBe(2)
+    })
+
+    test("single subscriber batching path", () => {
+      const s = signal(0)
+      let runs = 0
+
+      effect(() => {
+        s()
+        runs++
+      })
+
+      batch(() => {
+        s.set(1)
+      })
+
+      expect(runs).toBe(2)
+    })
+  })
+
+  describe("runUntracked", () => {
+    test("signal reads inside runUntracked do not create dependencies", () => {
+      const s = signal(0)
+      let runs = 0
+
+      effect(() => {
+        runUntracked(() => s())
+        runs++
+      })
+
+      expect(runs).toBe(1)
+      s.set(1)
+      expect(runs).toBe(1) // not re-run
+    })
+
+    test("restores tracking context after runUntracked", () => {
+      const tracked = signal(0)
+      const untracked = signal(0)
+      let runs = 0
+
+      effect(() => {
+        tracked()
+        runUntracked(() => untracked())
+        runs++
+      })
+
+      expect(runs).toBe(1)
+
+      // tracked signal should still trigger re-run
+      tracked.set(1)
+      expect(runs).toBe(2)
+
+      // untracked signal should not
+      untracked.set(1)
+      expect(runs).toBe(2)
+    })
+  })
+
+  describe("trackSubscriber with depsCollector", () => {
+    test("renderEffect uses fast deps collector path", () => {
+      const s = signal(0)
+      let runs = 0
+
+      const dispose = renderEffect(() => {
+        s()
+        runs++
+      })
+
+      s.set(1)
+      expect(runs).toBe(2)
+
+      dispose()
+      s.set(2)
+      expect(runs).toBe(2)
+    })
+  })
+
+  describe("cleanupEffect", () => {
+    test("effect dynamically tracks/untracks deps on re-run", () => {
+      const cond = signal(true)
+      const a = signal(0)
+      const b = signal(0)
+      let runs = 0
+
+      effect(() => {
+        if (cond()) {
+          a()
+        } else {
+          b()
+        }
+        runs++
+      })
+
+      expect(runs).toBe(1)
+
+      a.set(1) // tracked
+      expect(runs).toBe(2)
+
+      cond.set(false) // switch branch
+      expect(runs).toBe(3)
+
+      a.set(2) // no longer tracked
+      expect(runs).toBe(3)
+
+      b.set(1) // now tracked
+      expect(runs).toBe(4)
+    })
+  })
+})

package/src/tests/watch.test.ts

@@ -0,0 +1,146 @@
+import { signal } from "../signal"
+import { watch } from "../watch"
+
+describe("watch", () => {
+  test("calls callback when source changes", () => {
+    const s = signal(1)
+    const calls: [number, number | undefined][] = []
+
+    watch(
+      () => s(),
+      (newVal, oldVal) => {
+        calls.push([newVal, oldVal])
+      },
+    )
+
+    expect(calls.length).toBe(0) // not called on first run without immediate
+
+    s.set(2)
+    expect(calls).toEqual([[2, 1]])
+
+    s.set(3)
+    expect(calls).toEqual([
+      [2, 1],
+      [3, 2],
+    ])
+  })
+
+  test("immediate option calls callback on first run", () => {
+    const s = signal(1)
+    const calls: [number, number | undefined][] = []
+
+    watch(
+      () => s(),
+      (newVal, oldVal) => {
+        calls.push([newVal, oldVal])
+      },
+      { immediate: true },
+    )
+
+    expect(calls).toEqual([[1, undefined]])
+  })
+
+  test("stop function disposes the watcher", () => {
+    const s = signal(1)
+    let callCount = 0
+
+    const stop = watch(
+      () => s(),
+      () => {
+        callCount++
+      },
+    )
+
+    s.set(2)
+    expect(callCount).toBe(1)
+
+    stop()
+
+    s.set(3)
+    expect(callCount).toBe(1) // no more calls
+  })
+
+  test("cleanup function is called before each re-run", () => {
+    const s = signal(1)
+    const log: string[] = []
+
+    watch(
+      () => s(),
+      (newVal) => {
+        log.push(`run-${newVal}`)
+        return () => log.push(`cleanup-${newVal}`)
+      },
+    )
+
+    s.set(2)
+    expect(log).toEqual(["run-2"])
+
+    s.set(3)
+    expect(log).toEqual(["run-2", "cleanup-2", "run-3"])
+  })
+
+  test("cleanup function from immediate is called on next change", () => {
+    const s = signal(1)
+    const log: string[] = []
+
+    watch(
+      () => s(),
+      (newVal) => {
+        log.push(`run-${newVal}`)
+        return () => log.push(`cleanup-${newVal}`)
+      },
+      { immediate: true },
+    )
+
+    expect(log).toEqual(["run-1"])
+
+    s.set(2)
+    expect(log).toEqual(["run-1", "cleanup-1", "run-2"])
+  })
+
+  test("cleanup is called on stop", () => {
+    const s = signal(1)
+    const log: string[] = []
+
+    const stop = watch(
+      () => s(),
+      (newVal) => {
+        log.push(`run-${newVal}`)
+        return () => log.push(`cleanup-${newVal}`)
+      },
+    )
+
+    s.set(2)
+    expect(log).toEqual(["run-2"])
+
+    stop()
+    expect(log).toEqual(["run-2", "cleanup-2"])
+  })
+
+  test("callback returning non-function does not set cleanup", () => {
+    const s = signal(1)
+    let callCount = 0
+
+    watch(
+      () => s(),
+      () => {
+        callCount++
+        // returns void, not a function
+      },
+    )
+
+    s.set(2)
+    s.set(3)
+    expect(callCount).toBe(2)
+  })
+
+  test("stop without cleanup does not throw", () => {
+    const s = signal(1)
+    const stop = watch(
+      () => s(),
+      () => {},
+    )
+
+    stop() // no cleanup function was set, should not throw
+  })
+})

package/src/tracking.ts

@@ -0,0 +1,103 @@
+// Global subscriber tracking context
+
+import { enqueuePendingNotification, isBatching } from "./batch"
+
+let activeEffect: (() => void) | null = null
+
+// Tracks which subscriber sets each effect is registered in, so we can
+// clean them up before a re-run (dynamic dependency tracking).
+const effectDeps = new WeakMap<() => void, Set<Set<() => void>>>()
+
+// Fast deps collector for renderEffect — avoids WeakMap overhead entirely.
+// When set, trackSubscriber pushes subscriber sets here instead of effectDeps.
+let _depsCollector: Set<() => void>[] | null = null
+
+export function setDepsCollector(collector: Set<() => void>[] | null): void {
+  _depsCollector = collector
+}
+
+/**
+ * Subscriber host — any reactive source that can have downstream subscribers.
+ * Signals, computeds, and createSelector buckets all implement this interface.
+ * The Set is created lazily — only allocated when an effect actually tracks this source.
+ */
+export interface SubscriberHost {
+  /** @internal subscriber set — null until first tracked by an effect */
+  _s: Set<() => void> | null
+}
+
+/**
+ * Register the active effect as a subscriber of the given reactive source.
+ * The subscriber Set is created lazily on the host — sources read only outside
+ * effects never allocate a Set.
+ */
+export function trackSubscriber(host: SubscriberHost) {
+  if (activeEffect) {
+    if (!host._s) host._s = new Set()
+    const subscribers = host._s
+    subscribers.add(activeEffect)
+    if (_depsCollector) {
+      // Fast path: renderEffect stores deps inline, no WeakMap
+      _depsCollector.push(subscribers)
+    } else {
+      // Record this dep so we can remove it on cleanup
+      let deps = effectDeps.get(activeEffect)
+      if (!deps) {
+        deps = new Set()
+        effectDeps.set(activeEffect, deps)
+      }
+      deps.add(subscribers)
+    }
+  }
+}
+
+/**
+ * Remove an effect from every subscriber set it was registered in,
+ * then clear its dep record. Call this before each re-run and on dispose.
+ */
+export function cleanupEffect(fn: () => void): void {
+  const deps = effectDeps.get(fn)
+  if (deps) {
+    for (const sub of deps) sub.delete(fn)
+    deps.clear()
+  }
+}
+
+export function notifySubscribers(subscribers: Set<() => void>) {
+  if (subscribers.size === 0) return
+  // Single-subscriber fast path: avoid any iteration overhead.
+  if (subscribers.size === 1) {
+    const sub = subscribers.values().next().value as () => void
+    if (isBatching()) enqueuePendingNotification(sub)
+    else sub()
+    return
+  }
+  if (isBatching()) {
+    // Effects are queued not run inline — no re-entrancy risk, iterate the live Set directly.
+    for (const sub of subscribers) enqueuePendingNotification(sub)
+  } else {
+    // Effects run inline and may call cleanupEffect (removes) + trackSubscriber (re-adds).
+    // Snapshot first to prevent the iterator from visiting re-inserted entries → infinite loop.
+    for (const sub of [...subscribers]) sub()
+  }
+}
+
+export function withTracking<T>(fn: () => void, compute: () => T): T {
+  const prev = activeEffect
+  activeEffect = fn
+  try {
+    return compute()
+  } finally {
+    activeEffect = prev
+  }
+}
+
+export function runUntracked<T>(fn: () => T): T {
+  const prev = activeEffect
+  activeEffect = null
+  try {
+    return fn()
+  } finally {
+    activeEffect = prev
+  }
+}

package/src/watch.ts

@@ -0,0 +1,69 @@
+import { effect } from "./effect"
+
+export interface WatchOptions {
+  /** If true, call the callback immediately with the current value on setup. Default: false. */
+  immediate?: boolean
+}
+
+/**
+ * Watch a reactive source and run a callback whenever it changes.
+ *
+ * Returns a stop function that disposes the watcher.
+ *
+ * The callback receives (newValue, oldValue). On the first call (when
+ * `immediate` is true) oldValue is `undefined`.
+ *
+ * The callback may return a cleanup function that is called before each
+ * re-run and on stop — useful for cancelling async work.
+ *
+ * @example
+ * const stop = watch(
+ *   () => userId(),
+ *   async (id, prev) => {
+ *     const data = await fetch(`/api/user/${id}`)
+ *     setUser(await data.json())
+ *   },
+ * )
+ * // Later: stop()
+ */
+export function watch<T>(
+  source: () => T,
+  // biome-ignore lint/suspicious/noConfusingVoidType: void is intentional — callers may return void
+  callback: (newVal: T, oldVal: T | undefined) => void | (() => void),
+  opts: WatchOptions = {},
+): () => void {
+  let oldVal: T | undefined
+  let isFirst = true
+  let cleanupFn: (() => void) | undefined
+
+  const e = effect(() => {
+    const newVal = source()
+
+    if (isFirst) {
+      isFirst = false
+      oldVal = newVal
+      if (opts.immediate) {
+        const result = callback(newVal, undefined)
+        if (typeof result === "function") cleanupFn = result
+      }
+      return
+    }
+
+    if (cleanupFn) {
+      cleanupFn()
+      cleanupFn = undefined
+    }
+
+    const result = callback(newVal, oldVal)
+    if (typeof result === "function") cleanupFn = result
+    oldVal = newVal
+  })
+
+  return () => {
+    e.dispose()
+    if (cleanupFn) {
+      cleanupFn()
+      cleanupFn = undefined
+    }
+  }
+}