@pyreon/reactivity 0.1.0

package/src/debug.ts

@@ -0,0 +1,134 @@
+/**
+ * @pyreon/reactivity debug utilities.
+ *
+ * Development-only tools for tracing signal updates, inspecting reactive
+ * graphs, and understanding why DOM nodes re-render.
+ *
+ * All utilities are tree-shakeable — they compile away in production builds
+ * when unused.
+ */
+
+import type { Signal, SignalDebugInfo } from "./signal"
+
+// ─── Signal update tracing ───────────────────────────────────────────────────
+
+interface SignalUpdateEvent {
+  /** The signal that changed */
+  signal: Signal<unknown>
+  /** Signal name (from options or label) */
+  name: string | undefined
+  /** Previous value */
+  prev: unknown
+  /** New value */
+  next: unknown
+  /** Stack trace at the point of the .set() / .update() call */
+  stack: string
+  /** Timestamp */
+  timestamp: number
+}
+
+type SignalUpdateListener = (event: SignalUpdateEvent) => void
+
+let _traceListeners: SignalUpdateListener[] | null = null
+
+/**
+ * Register a listener that fires on every signal write.
+ * Returns a dispose function.
+ *
+ * @example
+ * const dispose = onSignalUpdate(e => {
+ *   console.log(`${e.name ?? 'anonymous'}: ${e.prev} → ${e.next}`)
+ * })
+ */
+export function onSignalUpdate(listener: SignalUpdateListener): () => void {
+  if (!_traceListeners) _traceListeners = []
+  _traceListeners.push(listener)
+  return () => {
+    if (!_traceListeners) return
+    _traceListeners = _traceListeners.filter((l) => l !== listener)
+    if (_traceListeners.length === 0) _traceListeners = null
+  }
+}
+
+/** @internal — called from signal.set() when tracing is active */
+export function _notifyTraceListeners(sig: Signal<unknown>, prev: unknown, next: unknown): void {
+  if (!_traceListeners) return
+  const event: SignalUpdateEvent = {
+    signal: sig,
+    name: sig.label,
+    prev,
+    next,
+    stack: new Error().stack ?? "",
+    timestamp: performance.now(),
+  }
+  for (const l of _traceListeners) l(event)
+}
+
+/** Check if any trace listeners are active (fast path for signal.set) */
+export function isTracing(): boolean {
+  return _traceListeners !== null
+}
+
+// ─── why() — trace which signal caused a re-run ──────────────────────────────
+
+let _whyActive = false
+let _whyLog: { name: string | undefined; prev: unknown; next: unknown }[] = []
+
+/**
+ * Trace the next signal update. Logs which signals fire and what changed.
+ * Call before triggering a state change to see what updates and why.
+ *
+ * @example
+ * why()
+ * count.set(5)
+ * // Console: [pyreon:why] "count": 3 → 5 (2 subscribers)
+ */
+export function why(): void {
+  if (_whyActive) return
+  _whyActive = true
+  _whyLog = []
+
+  const dispose = onSignalUpdate((e) => {
+    const _subCount = (e.signal as unknown as { _s: Set<unknown> | null })._s?.size ?? 0
+    const _name = e.name ? `"${e.name}"` : "(anonymous signal)"
+
+    console.log(
+      `[pyreon:why] ${_name}: ${JSON.stringify(e.prev)} → ${JSON.stringify(e.next)} (${_subCount} subscriber${_subCount === 1 ? "" : "s"})`,
+    )
+    _whyLog.push({ name: e.name, prev: e.prev, next: e.next })
+  })
+
+  // Auto-dispose after the current microtask (captures the synchronous batch)
+  queueMicrotask(() => {
+    dispose()
+    if (_whyLog.length === 0) {
+      console.log("[pyreon:why] No signal updates detected")
+    }
+    _whyActive = false
+    _whyLog = []
+  })
+}
+
+// ─── inspectSignal — rich console output ─────────────────────────────────────
+
+/**
+ * Print a signal's current state to the console in a readable format.
+ *
+ * @example
+ * const count = signal(42, { name: "count" })
+ * inspectSignal(count)
+ * // Console:
+ * // 🔍 Signal "count"
+ * //   value: 42
+ * //   subscribers: 3
+ */
+export function inspectSignal<T>(sig: Signal<T>): SignalDebugInfo<T> {
+  const info = sig.debug()
+
+  console.group(`🔍 Signal ${info.name ? `"${info.name}"` : "(anonymous)"}`)
+  console.log("value:", info.value)
+  console.log("subscribers:", info.subscriberCount)
+  console.groupEnd()
+
+  return info
+}

package/src/effect.ts

@@ -0,0 +1,152 @@
+import { getCurrentScope } from "./scope"
+import { cleanupEffect, setDepsCollector, withTracking } from "./tracking"
+
+export interface Effect {
+  dispose(): void
+}
+
+// Global error handler — called for unhandled errors thrown inside effects.
+// Defaults to console.error so silent failures are never swallowed.
+let _errorHandler: (err: unknown) => void = (err) => {
+  console.error("[pyreon] Unhandled effect error:", err)
+}
+
+export function setErrorHandler(fn: (err: unknown) => void): void {
+  _errorHandler = fn
+}
+
+// biome-ignore lint/suspicious/noConfusingVoidType: void is intentional — callbacks that return nothing must be assignable
+export function effect(fn: () => (() => void) | void): Effect {
+  // Capture the scope at creation time — remains correct during future re-runs
+  // even after setCurrentScope(null) has been called post-setup.
+  const scope = getCurrentScope()
+  let disposed = false
+  let isFirstRun = true
+  let cleanup: (() => void) | undefined
+
+  const runCleanup = () => {
+    if (typeof cleanup === "function") {
+      try {
+        cleanup()
+      } catch (err) {
+        _errorHandler(err)
+      }
+      cleanup = undefined
+    }
+  }
+
+  const run = () => {
+    if (disposed) return
+    // Run previous cleanup before re-running
+    runCleanup()
+    // Clean up previous subscriptions before re-running (dynamic dep tracking)
+    cleanupEffect(run)
+    try {
+      cleanup = withTracking(run, fn) || undefined
+    } catch (err) {
+      _errorHandler(err)
+    }
+    // Notify scope after each reactive re-run (not the initial synchronous run)
+    // so onUpdate hooks fire after the DOM has settled.
+    if (!isFirstRun) scope?.notifyEffectRan()
+    isFirstRun = false
+  }
+
+  run()
+
+  const e: Effect = {
+    dispose() {
+      runCleanup()
+      disposed = true
+      cleanupEffect(run)
+    },
+  }
+
+  // Auto-register with the active EffectScope (if any)
+  getCurrentScope()?.add(e)
+
+  return e
+}
+
+/**
+ * Lightweight effect for DOM render bindings.
+ *
+ * Differences from `effect()`:
+ * - No EffectScope registration (caller owns the dispose lifecycle)
+ * - No error handler (errors propagate naturally)
+ * - No onUpdate notification
+ * - Deps stored in a local array instead of the global WeakMap — faster
+ *   creation and disposal (~200ns saved per effect vs WeakMap path)
+ *
+ * Returns a dispose function (not an Effect object — saves 1 allocation).
+ */
+/**
+ * Static-dep binding — compiler helper for template expressions.
+ *
+ * Like renderEffect but assumes dependencies never change (true for all
+ * compiler-emitted template bindings like `_tpl()` text/attribute updates).
+ *
+ * Tracks dependencies only on the first run. Re-runs skip cleanup, re-tracking,
+ * and tracking context save/restore entirely — just calls `fn()` directly.
+ *
+ * Per re-run savings vs renderEffect:
+ * - No deps iteration + Set.delete (cleanup)
+ * - No setDepsCollector + withTracking (re-registration)
+ * - Signal reads hit `if (activeEffect)` null check → instant return
+ */
+export function _bind(fn: () => void): () => void {
+  const deps: Set<() => void>[] = []
+  let disposed = false
+
+  const run = () => {
+    if (disposed) return
+    fn()
+  }
+
+  // First run: track deps so we know what to unsubscribe on dispose
+  setDepsCollector(deps)
+  withTracking(run, fn)
+  setDepsCollector(null)
+
+  const dispose = () => {
+    if (disposed) return
+    disposed = true
+    for (const s of deps) s.delete(run)
+    deps.length = 0
+  }
+
+  // Auto-register with scope so template bindings are disposed during teardown
+  getCurrentScope()?.add({ dispose })
+
+  return dispose
+}
+
+export function renderEffect(fn: () => void): () => void {
+  const deps: Set<() => void>[] = []
+  let disposed = false
+
+  const run = () => {
+    if (disposed) return
+    // Clean up old subscriptions
+    for (const s of deps) s.delete(run)
+    deps.length = 0
+    // Track with fast collector — pushes to our local deps array
+    setDepsCollector(deps)
+    withTracking(run, fn)
+    setDepsCollector(null)
+  }
+
+  run()
+
+  const dispose = () => {
+    if (disposed) return
+    disposed = true
+    for (const s of deps) s.delete(run)
+    deps.length = 0
+  }
+
+  // Auto-register with scope so render effects are disposed during teardown
+  getCurrentScope()?.add({ dispose })
+
+  return dispose
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+// @pyreon/reactivity — signals-based reactive primitives
+
+export { batch, nextTick } from "./batch"
+export { Cell, cell } from "./cell"
+export { type Computed, type ComputedOptions, computed } from "./computed"
+export { createSelector } from "./createSelector"
+export { inspectSignal, onSignalUpdate, why } from "./debug"
+export { _bind, type Effect, effect, renderEffect, setErrorHandler } from "./effect"
+export { reconcile } from "./reconcile"
+export { createResource, type Resource } from "./resource"
+export { EffectScope, effectScope, getCurrentScope, setCurrentScope } from "./scope"
+export { type Signal, type SignalDebugInfo, type SignalOptions, signal } from "./signal"
+export { createStore, isStore } from "./store"
+export { runUntracked } from "./tracking"
+export { type WatchOptions, watch } from "./watch"

package/src/reconcile.ts

@@ -0,0 +1,98 @@
+/**
+ * reconcile — surgically diff new state into an existing createStore proxy.
+ *
+ * Instead of replacing the store root (which would trigger all downstream effects),
+ * reconcile walks both the new value and the store in parallel and only calls
+ * `.set()` on signals whose value actually changed.
+ *
+ * Ideal for applying API responses to a long-lived store:
+ *
+ * @example
+ * const state = createStore({ user: { name: "Alice", age: 30 }, items: [] })
+ *
+ * // API response arrives:
+ * reconcile({ user: { name: "Alice", age: 31 }, items: [{ id: 1 }] }, state)
+ * // → only state.user.age signal fires (name unchanged)
+ * // → state.items[0] is newly created
+ *
+ * Arrays are reconciled by index — elements at the same index are recursively
+ * diffed rather than replaced wholesale. Excess old elements are removed.
+ */
+
+import { isStore } from "./store"
+
+type AnyObject = Record<PropertyKey, unknown>
+
+export function reconcile<T extends object>(source: T, target: T): void {
+  _reconcileInner(source, target, new WeakSet())
+}
+
+function _reconcileInner(source: object, target: object, seen: WeakSet<object>): void {
+  if (seen.has(source)) return // circular reference — stop recursion
+  seen.add(source)
+  if (Array.isArray(source) && Array.isArray(target)) {
+    _reconcileArray(source as unknown[], target as unknown[], seen)
+  } else {
+    _reconcileObject(source as AnyObject, target as AnyObject, seen)
+  }
+}
+
+function _reconcileArray(source: unknown[], target: unknown[], seen: WeakSet<object>): void {
+  const targetLen = target.length
+  const sourceLen = source.length
+
+  // Update / add entries
+  for (let i = 0; i < sourceLen; i++) {
+    const sv = source[i]
+    const tv = (target as unknown[])[i]
+
+    if (
+      i < targetLen &&
+      sv !== null &&
+      typeof sv === "object" &&
+      tv !== null &&
+      typeof tv === "object"
+    ) {
+      // Both sides are objects — recurse
+      _reconcileInner(sv as object, tv as object, seen)
+    } else {
+      // Scalar or new entry — write directly (signal will skip if equal via Object.is)
+      ;(target as unknown[])[i] = sv
+    }
+  }
+
+  // Trim excess entries
+  if (targetLen > sourceLen) {
+    target.length = sourceLen
+  }
+}
+
+function _reconcileObject(source: AnyObject, target: AnyObject, seen: WeakSet<object>): void {
+  const sourceKeys = Object.keys(source)
+  const targetKeys = new Set(Object.keys(target))
+
+  for (const key of sourceKeys) {
+    const sv = source[key]
+    const tv = target[key]
+
+    if (sv !== null && typeof sv === "object" && tv !== null && typeof tv === "object") {
+      if (isStore(tv)) {
+        // Both objects — recurse into the store node
+        _reconcileInner(sv as object, tv as object, seen)
+      } else {
+        // Target is a raw object (not yet proxied) — just assign
+        target[key] = sv
+      }
+    } else {
+      // Scalar: assign (store proxy's set trap skips if Object.is equal)
+      target[key] = sv
+    }
+
+    targetKeys.delete(key)
+  }
+
+  // Remove keys that no longer exist in source
+  for (const key of targetKeys) {
+    delete target[key]
+  }
+}

package/src/resource.ts

@@ -0,0 +1,66 @@
+import { effect } from "./effect"
+import type { Signal } from "./signal"
+import { signal } from "./signal"
+import { runUntracked } from "./tracking"
+
+export interface Resource<T> {
+  /** The latest resolved value (undefined while loading or on error). */
+  data: Signal<T | undefined>
+  /** True while a fetch is in flight. */
+  loading: Signal<boolean>
+  /** The last error thrown by the fetcher, or undefined. */
+  error: Signal<unknown>
+  /** Re-run the fetcher with the current source value. */
+  refetch(): void
+}
+
+/**
+ * Async data primitive. Fetches data reactively whenever `source()` changes.
+ *
+ * @example
+ * const userId = signal(1)
+ * const user = createResource(userId, (id) => fetchUser(id))
+ * // user.data() — the fetched user (undefined while loading)
+ * // user.loading() — true while in flight
+ * // user.error() — last error
+ */
+export function createResource<T, P>(
+  source: () => P,
+  fetcher: (param: P) => Promise<T>,
+): Resource<T> {
+  const data = signal<T | undefined>(undefined)
+  const loading = signal(false)
+  const error = signal<unknown>(undefined)
+  let requestId = 0
+
+  const doFetch = (param: P) => {
+    const id = ++requestId
+    loading.set(true)
+    error.set(undefined)
+    fetcher(param)
+      .then((result) => {
+        if (id !== requestId) return
+        data.set(result)
+        loading.set(false)
+      })
+      .catch((err: unknown) => {
+        if (id !== requestId) return
+        error.set(err)
+        loading.set(false)
+      })
+  }
+
+  effect(() => {
+    const param = source()
+    runUntracked(() => doFetch(param))
+  })
+
+  return {
+    data,
+    loading,
+    error,
+    refetch() {
+      runUntracked(() => doFetch(source()))
+    },
+  }
+}

package/src/scope.ts

@@ -0,0 +1,80 @@
+// EffectScope — auto-tracks effects created during a component's setup
+// and disposes them all at once when the component unmounts.
+
+export class EffectScope {
+  private _effects: { dispose(): void }[] = []
+  private _active = true
+  private _updateHooks: (() => void)[] = []
+  private _updatePending = false
+
+  /** Register an effect/computed to be disposed when this scope stops. */
+  add(e: { dispose(): void }): void {
+    if (this._active) this._effects.push(e)
+  }
+
+  /**
+   * Temporarily re-activate this scope so effects created inside `fn` are
+   * auto-tracked and will be disposed when the scope stops.
+   * Used to ensure effects created in `onMount` callbacks belong to their
+   * component's scope rather than leaking as global effects.
+   */
+  runInScope<T>(fn: () => T): T {
+    const prev = _currentScope
+    _currentScope = this
+    try {
+      return fn()
+    } finally {
+      _currentScope = prev
+    }
+  }
+
+  /** Register a callback to run after any reactive update in this scope. */
+  addUpdateHook(fn: () => void): void {
+    this._updateHooks.push(fn)
+  }
+
+  /**
+   * Called by effects after each non-initial re-run.
+   * Schedules onUpdate hooks via microtask so all synchronous effects settle first.
+   */
+  notifyEffectRan(): void {
+    if (!this._active || this._updateHooks.length === 0 || this._updatePending) return
+    this._updatePending = true
+    queueMicrotask(() => {
+      this._updatePending = false
+      if (!this._active) return
+      for (const fn of this._updateHooks) {
+        try {
+          fn()
+        } catch (err) {
+          console.error("[pyreon] onUpdate hook error:", err)
+        }
+      }
+    })
+  }
+
+  /** Dispose all tracked effects. */
+  stop(): void {
+    if (!this._active) return
+    for (const e of this._effects) e.dispose()
+    this._effects = []
+    this._updateHooks = []
+    this._updatePending = false
+    this._active = false
+  }
+}
+
+let _currentScope: EffectScope | null = null
+
+export function getCurrentScope(): EffectScope | null {
+  return _currentScope
+}
+
+export function setCurrentScope(scope: EffectScope | null): void {
+  _currentScope = scope
+}
+
+/** Create a new EffectScope. */
+export function effectScope(): EffectScope {
+  return new EffectScope()
+}

package/src/signal.ts

@@ -0,0 +1,125 @@
+import { _notifyTraceListeners, isTracing } from "./debug"
+import { notifySubscribers, trackSubscriber } from "./tracking"
+
+export interface SignalDebugInfo<T> {
+  /** Signal name (set via options or inferred) */
+  name: string | undefined
+  /** Current value (same as peek()) */
+  value: T
+  /** Number of active subscribers */
+  subscriberCount: number
+}
+
+export interface Signal<T> {
+  (): T
+  /** Read the current value WITHOUT registering a reactive dependency. */
+  peek(): T
+  set(value: T): void
+  update(fn: (current: T) => T): void
+  /**
+   * Subscribe a static listener directly — no effect overhead (no withTracking,
+   * no cleanupEffect, no effectDeps WeakMap). Use when the dependency is fixed
+   * and dynamic re-tracking is not needed.
+   * Returns a disposer that removes the subscription.
+   */
+  subscribe(listener: () => void): () => void
+  /** Debug name — useful for devtools and logging. */
+  label: string | undefined
+  /** Returns a snapshot of the signal's debug info (value, name, subscriber count). */
+  debug(): SignalDebugInfo<T>
+}
+
+export interface SignalOptions {
+  /** Debug name for this signal — shows up in devtools and debug() output. */
+  name?: string
+}
+
+// Internal shape of a signal function — state stored as properties on the
+// function object so methods can be shared via assignment (not per-signal closures).
+interface SignalFn<T> {
+  (): T
+  /** @internal current value */
+  _v: T
+  /** @internal subscriber set (lazily allocated by trackSubscriber) */
+  _s: Set<() => void> | null
+  /** @internal debug name */
+  _n: string | undefined
+  peek(): T
+  set(value: T): void
+  update(fn: (current: T) => T): void
+  subscribe(listener: () => void): () => void
+  label: string | undefined
+  debug(): SignalDebugInfo<T>
+}
+
+// Shared method implementations — defined once, assigned to every signal.
+// Uses `this` binding (signal methods are always called as `signal.method()`).
+function _peek(this: SignalFn<unknown>) {
+  return this._v
+}
+
+function _set(this: SignalFn<unknown>, newValue: unknown) {
+  if (Object.is(this._v, newValue)) return
+  const prev = this._v
+  this._v = newValue
+  if (isTracing()) _notifyTraceListeners(this as unknown as Signal<unknown>, prev, newValue)
+  if (this._s) notifySubscribers(this._s)
+}
+
+function _update(this: SignalFn<unknown>, fn: (current: unknown) => unknown) {
+  _set.call(this, fn(this._v))
+}
+
+function _subscribe(this: SignalFn<unknown>, listener: () => void): () => void {
+  if (!this._s) this._s = new Set()
+  this._s.add(listener)
+  return () => this._s?.delete(listener)
+}
+
+function _debug(this: SignalFn<unknown>): SignalDebugInfo<unknown> {
+  return {
+    name: this._n,
+    value: this._v,
+    subscriberCount: this._s?.size ?? 0,
+  }
+}
+
+// label getter/setter — maps to _n for devtools-friendly access
+const _labelDescriptor: PropertyDescriptor = {
+  get(this: SignalFn<unknown>) {
+    return this._n
+  },
+  set(this: SignalFn<unknown>, v: string | undefined) {
+    this._n = v
+  },
+  enumerable: false,
+  configurable: true,
+}
+
+/**
+ * Create a reactive signal.
+ *
+ * Only 1 closure is allocated (the read function). State is stored as
+ * properties on the function object (_v, _s) and methods (peek, set,
+ * update, subscribe) are shared across all signals — not per-signal closures.
+ */
+export function signal<T>(initialValue: T, options?: SignalOptions): Signal<T> {
+  // The read function is the only per-signal closure.
+  // It doubles as the SubscriberHost (_s property) for trackSubscriber.
+  const read = (() => {
+    trackSubscriber(read as SignalFn<T>)
+    return read._v
+  }) as unknown as SignalFn<T>
+
+  read._v = initialValue
+  read._s = null
+  read._n = options?.name
+  read.peek = _peek as () => T
+  read.set = _set as (value: T) => void
+  read.update = _update as (fn: (current: T) => T) => void
+  read.subscribe = _subscribe as (listener: () => void) => () => void
+  read.debug = _debug as () => SignalDebugInfo<T>
+  Object.defineProperty(read, "label", _labelDescriptor)
+
+  return read as unknown as Signal<T>
+}