@pyreon/reactivity 0.24.4 → 0.24.6

package/src/effect.ts

@@ -1,467 +0,0 @@
-import { _captureCallerLocation, _rdRecordFire, _rdRegister } from './reactive-devtools'
-import { getCurrentScope } from './scope'
-import { _restoreActiveEffect, _setActiveEffect, setDepsCollector, withTracking } from './tracking'
-
-// Dev-time counter sink — see packages/internals/perf-harness for contract.
-const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
-
-export interface Effect {
-  dispose(): void
-}
-
-export interface EffectOptions {
-  /**
-   * @internal — source location injected by `@pyreon/vite-plugin` at build
-   * time. When present, the runtime skips the `new Error().stack` capture
-   * in `_rdRegister` — saves ~2.2µs per effect creation when devtools is
-   * active. Plain user code should NOT set this; the field is opaque
-   * (no public type) so it's not part of the public API surface.
-   *
-   * Shape: `{ file: string; line: number; col: number }` matching
-   * `@pyreon/reactivity`'s `SourceLocation`.
-   */
-  __sourceLocation?: { file: string; line: number; col: number }
-}
-
-// ─── Effect-scoped snapshot capture (DI from `@pyreon/core`) ─────────────────
-//
-// Effects re-run reactively in response to signal changes. When that re-run
-// happens AFTER the synchronous mount that set the effect up, the surrounding
-// context stack (from `@pyreon/core`'s provide() calls) may have been
-// destructively truncated by `mountReactive`'s `restoreContextStack` cleanup.
-// Without restoring the captured context, signal-driven re-runs of `_bind` /
-// `renderEffect` / `effect` see a half-empty stack and `useContext()` falls
-// back to the default value — silently breaking provider-backed APIs like
-// `useMode()`, `useTheme()`, `useRouter()`, etc. on every reactive update.
-//
-// `@pyreon/reactivity` is below `@pyreon/core` in the dep order, so it can't
-// import `captureContextStack` / `restoreContextStack` directly. Core
-// registers its capture+restore pair via `setSnapshotCapture` at module load.
-// When unset (raw reactivity-only consumers), effects skip context handling
-// — same behavior as before this hook existed.
-export interface ReactiveSnapshotCapture {
-  capture: () => unknown
-  /** Run `fn` with the previously-captured snapshot active. */
-  restore: <T>(snap: unknown, fn: () => T) => T
-}
-
-let _snapshotCapture: ReactiveSnapshotCapture | null = null
-
-/**
- * Register a capture/restore pair so reactivity-layer effects (`_bind`,
- * `renderEffect`, `effect`) can preserve external context (e.g. the core
- * provide/useContext stack) across signal-driven re-runs. Called by
- * `@pyreon/core`'s context module at import time. Idempotent — calling again
- * replaces the previously registered hook.
- */
-export function setSnapshotCapture(hook: ReactiveSnapshotCapture | null): void {
-  _snapshotCapture = hook
-}
-
-// ─── onCleanup ───────────────────────────────────────────────────────────────
-// Thread-local collector for cleanup functions registered via onCleanup()
-// during effect execution. Pushed/popped around the user callback in effect().
-let _cleanupCollector: (() => void)[] | null = null
-
-/**
- * Register a cleanup function inside an effect. The cleanup runs:
- * - Before the effect re-runs (when dependencies change)
- * - When the effect is disposed
- *
- * Can be called multiple times — all cleanups run in registration order.
- * Must be called synchronously during effect setup (like onMount/onUnmount).
- *
- * @example
- * effect(() => {
- *   const controller = new AbortController()
- *   onCleanup(() => controller.abort())
- *   fetch(`/api/user/${userId()}`, { signal: controller.signal })
- *     .then(r => r.json())
- *     .then(data => user.set(data))
- * })
- */
-export function onCleanup(fn: () => void): void {
-  if (_cleanupCollector) {
-    _cleanupCollector.push(fn)
-  }
-}
-
-// Thread-local collector for nested effects — captures effect() calls made
-// inside another effect's fn() body so the parent can dispose them on
-// re-run / disposal. Without this, inner effects leak across outer
-// lifecycle boundaries (caught by cleanup-nested.test.ts).
-let _innerEffectCollector: Effect[] | null = null
-
-// Global error handler — called for unhandled errors thrown inside effects.
-// Defaults to console.error so silent failures are never swallowed.
-//
-// Two-layer model:
-//   1. The user-overridable single handler set via `setErrorHandler` (legacy
-//      direct API).
-//   2. A globalThis bridge `__pyreon_report_error__` that `@pyreon/core`
-//      installs in `registerErrorHandler` to forward effect errors into the
-//      same telemetry pipeline as component / mount / render errors.
-//      Pre-fix the two surfaces were disconnected — Sentry/Datadog wiring via
-//      core's `registerErrorHandler` silently missed effect-thrown errors.
-//      Globalthis-based to avoid an upward import (core depends on
-//      reactivity, not the reverse). Same shape as the perf-harness counter
-//      sink — zero cost when no consumer is installed.
-//
-// Both surfaces fire on every effect error. The legacy handler stays for
-// backward compat; new consumers should prefer `@pyreon/core`'s
-// `registerErrorHandler`.
-
-interface PyreonErrorBridge {
-  __pyreon_report_error__?: (err: unknown, phase: 'effect') => void
-}
-const _errorBridge = globalThis as PyreonErrorBridge
-
-function _defaultErrorHandler(err: unknown): void {
-  // Last-resort unhandled-effect-error reporter — MUST fire in
-  // production (silently swallowing uncaught effect errors is a
-  // serious bug; React/Vue/Solid all log uncaught errors in prod).
-  // Deliberately not __DEV__-gated.
-  // pyreon-lint-disable-next-line pyreon/dev-guard-warnings
-  console.error('[pyreon] Unhandled effect error:', err)
-}
-
-let _userErrorHandler: ((err: unknown) => void) | undefined
-
-export const _errorHandler: (err: unknown) => void = (err) => {
-  // 1. User-set or default direct handler.
-  ;(_userErrorHandler ?? _defaultErrorHandler)(err)
-  // 2. Global telemetry bridge (installed by @pyreon/core's
-  //    registerErrorHandler). Forwards effect errors into reportError so
-  //    Sentry/Datadog wiring captures them alongside component errors.
-  _errorBridge.__pyreon_report_error__?.(err, 'effect')
-}
-
-export function setErrorHandler(fn: (err: unknown) => void): void {
-  _userErrorHandler = fn
-}
-
-/** Remove an effect from all dependency subscriber sets (local deps array). */
-function cleanupLocalDeps(deps: Set<() => void>[], fn: () => void): void {
-  if (deps.length === 1) {
-    ;(deps[0] as Set<() => void>).delete(fn)
-    deps.length = 0
-  } else if (deps.length > 1) {
-    for (let i = 0; i < deps.length; i++) (deps[i] as Set<() => void>).delete(fn)
-    deps.length = 0
-  }
-}
-
-export function effect(
-  fn: () => (() => void) | void,
-  options?: EffectOptions,
-): Effect {
-  // Dev-mode warning for async effect callbacks (audit bug #1). The
-  // tracking context is the synchronous frame around `fn()`'s top half;
-  // anything after the first `await` runs detached, so signal reads on
-  // the back side aren't tracked and the effect won't re-run when those
-  // signals change. The fix at the call site is either to read all
-  // tracked signals BEFORE the first await, or split the work into two
-  // effects (or use `watch` for async-in-callback). Surfacing the warn
-  // at registration is the cheapest catch we can offer: an
-  // `AsyncFunction.prototype.constructor.name === 'AsyncFunction'`
-  // check is true at function-definition time without invoking anything.
-  if (process.env.NODE_ENV !== 'production') {
-    if (fn.constructor && fn.constructor.name === 'AsyncFunction') {
-      // oxlint-disable-next-line no-console
-      console.warn(
-        '[pyreon] effect() received an async function. Signal reads after the first `await` are NOT tracked — only the synchronous prefix is. ' +
-          'Read every tracked signal BEFORE any await, or split into separate effects, or use `watch(source, asyncCb)` for async-in-callback patterns.',
-      )
-    }
-  }
-
-  // Capture the scope at creation time — remains correct during future re-runs
-  // even after setCurrentScope(null) has been called post-setup.
-  const scope = getCurrentScope()
-  // Capture the external (core-context) snapshot at SETUP time. Reactive
-  // re-runs restore it before invoking fn, so provider lookups stay correct
-  // even when the global context stack has been destructively truncated by
-  // mountReactive's restoreContextStack cleanup. See `_bind` for the full
-  // rationale.
-  const snapshot = _snapshotCapture ? _snapshotCapture.capture() : null
-  let disposed = false
-  let isFirstRun = true
-  let cleanup: (() => void) | undefined
-  // Local deps array — avoids WeakMap overhead (like renderEffect)
-  const deps: Set<() => void>[] = []
-
-  let cleanups: (() => void)[] | undefined
-  // Inner effects created during this effect's fn() body. Disposed on
-  // outer re-run (before the next fn()) and on outer dispose(). Without
-  // this, nested effects leak across outer lifecycle boundaries.
-  let innerEffects: Effect[] | null = null
-
-  const runCleanup = () => {
-    if (innerEffects) {
-      for (const ie of innerEffects) {
-        try {
-          ie.dispose()
-        } catch (err) {
-          _errorHandler(err)
-        }
-      }
-      innerEffects = null
-    }
-    if (cleanups) {
-      for (const c of cleanups) {
-        try {
-          c()
-        } catch (err) {
-          _errorHandler(err)
-        }
-      }
-      cleanups = undefined
-    }
-    if (typeof cleanup === 'function') {
-      try {
-        cleanup()
-      } catch (err) {
-        _errorHandler(err)
-      }
-      cleanup = undefined
-    }
-  }
-
-  const run = () => {
-    if (disposed) return
-    if (process.env.NODE_ENV !== 'production') {
-      _countSink.__pyreon_count__?.('reactivity.effectRun')
-      _rdRecordFire(run)
-    }
-    // Run previous cleanup before re-running
-    runCleanup()
-    // Start a new inner-effect collection window. Effects created during
-    // fn() will push themselves into this array and be disposed on the
-    // next re-run or on dispose.
-    const outerCollector = _innerEffectCollector
-    const myInners: Effect[] = []
-    _innerEffectCollector = myInners
-    try {
-      cleanupLocalDeps(deps, run)
-      setDepsCollector(deps)
-      // Collect onCleanup() registrations during execution
-      const collected: (() => void)[] = []
-      _cleanupCollector = collected
-      // First run executes inside the synchronous mount where the context
-      // stack is still intact — call fn directly to avoid pushing the
-      // captured snapshot a redundant second time. Subsequent re-runs
-      // happen AFTER mountReactive's cleanup has truncated the stack, so
-      // they need the snapshot restored to find provider frames.
-      const fnToRun =
-        isFirstRun || snapshot === null || _snapshotCapture === null
-          ? fn
-          : () => (_snapshotCapture as ReactiveSnapshotCapture).restore(snapshot, fn)
-      cleanup = withTracking(run, fnToRun) || undefined
-      _cleanupCollector = null
-      if (collected.length > 0) cleanups = collected
-      setDepsCollector(null)
-    } catch (err) {
-      _cleanupCollector = null
-      setDepsCollector(null)
-      _errorHandler(err)
-    } finally {
-      _innerEffectCollector = outerCollector
-    }
-    if (myInners.length > 0) innerEffects = myInners
-    // 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
-  }
-
-  if (process.env.NODE_ENV !== 'production')
-    // skipFrames=1: skip the `effect()` / `renderEffect()` frame, capture the user's call site.
-    // Prefer build-time-injected location over the ~2.2µs stack-capture
-    // fallback. @pyreon/vite-plugin's `injectSignalNames` rewrites
-    // `effect(() => …)` to `effect(() => …, { __sourceLocation: {…} })`.
-    _rdRegister(
-      run,
-      'effect',
-      null,
-      run,
-      undefined,
-      options?.__sourceLocation ?? _captureCallerLocation(1),
-    )
-
-  run()
-
-  const e: Effect = {
-    dispose() {
-      runCleanup()
-      disposed = true
-      cleanupLocalDeps(deps, run)
-    },
-  }
-
-  // If we're inside another effect's run, register with it so the outer
-  // disposes this inner automatically.
-  if (_innerEffectCollector !== null) {
-    _innerEffectCollector.push(e)
-  } else {
-    // Otherwise 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
-
-  // Capture external (core-context) snapshot at SETUP time. Re-runs restore
-  // it before invoking fn, so signal-driven re-runs see the same provider
-  // chain that was active when the binding was first set up — even if the
-  // global context stack has been destructively truncated by mountReactive's
-  // restoreContextStack cleanup in the meantime.
-  const snapshot = _snapshotCapture ? _snapshotCapture.capture() : null
-
-  const run = () => {
-    if (disposed) return
-    if (snapshot !== null && _snapshotCapture) {
-      _snapshotCapture.restore(snapshot, fn)
-    } else {
-      fn()
-    }
-  }
-
-  // First run: track deps so we know what to unsubscribe on dispose. We
-  // intentionally call `fn` directly (not `run`) here — the synchronous
-  // mount stack is already intact at this point, so restoring the captured
-  // snapshot would just push the same frames again redundantly.
-  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
-}
-
-/** Full re-track path for renderEffect: cleanup old deps, evaluate with tracking. */
-function renderEffectFullTrack(deps: Set<() => void>[], run: () => void, fn: () => void): void {
-  if (deps.length === 1) {
-    ;(deps[0] as Set<() => void>).delete(run)
-    deps.length = 0
-  } else if (deps.length > 1) {
-    for (const s of deps) s.delete(run)
-    deps.length = 0
-  }
-  setDepsCollector(deps)
-  _setActiveEffect(run)
-  try {
-    fn()
-  } finally {
-    _restoreActiveEffect()
-    setDepsCollector(null)
-  }
-}
-
-export function renderEffect(fn: () => void): () => void {
-  // Same dev warning as `effect()` — signal reads after the first
-  // await aren't tracked. See effect()'s docstring for full reasoning.
-  if (process.env.NODE_ENV !== 'production') {
-    if (fn.constructor && fn.constructor.name === 'AsyncFunction') {
-      // oxlint-disable-next-line no-console
-      console.warn(
-        '[pyreon] renderEffect() received an async function. Signal reads after the first `await` are NOT tracked — only the synchronous prefix is. ' +
-          'Read every tracked signal BEFORE any await, or split into separate effects, or use `watch(source, asyncCb)` for async-in-callback patterns.',
-      )
-    }
-  }
-
-  const deps: Set<() => void>[] = []
-  let disposed = false
-  let isFirstRun = true
-
-  // Same rationale as `_bind`: capture the external context snapshot at
-  // SETUP and restore it on signal-driven re-runs so provider lookups stay
-  // correct even after `mountReactive`'s cleanup truncates the global stack.
-  const snapshot = _snapshotCapture ? _snapshotCapture.capture() : null
-
-  const trackedFn =
-    snapshot !== null && _snapshotCapture
-      ? () => (_snapshotCapture as ReactiveSnapshotCapture).restore(snapshot, fn)
-      : fn
-
-  const run = () => {
-    if (disposed) return
-    if (isFirstRun) {
-      isFirstRun = false
-      setDepsCollector(deps)
-      _setActiveEffect(run)
-      try {
-        // First run: stack is still intact (we're inside the synchronous
-        // mount), so call fn directly to avoid pushing the snapshot frames
-        // a second time.
-        fn()
-      } finally {
-        _restoreActiveEffect()
-        setDepsCollector(null)
-      }
-    } else {
-      renderEffectFullTrack(deps, run, trackedFn)
-    }
-  }
-
-  if (process.env.NODE_ENV !== 'production')
-    // skipFrames=1: skip the `effect()` / `renderEffect()` frame, capture the user's call site.
-    _rdRegister(run, 'effect', null, run, undefined, _captureCallerLocation(1))
-
-  run()
-
-  const dispose = () => {
-    if (disposed) return
-    disposed = true
-    if (deps.length === 1) {
-      ;(deps[0] as Set<() => void>).delete(run)
-    } else {
-      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/env.d.ts

@@ -1,6 +0,0 @@
-/**
- * Minimal process type — just enough for `process.env.NODE_ENV` checks.
- * Avoids requiring @types/node in consumers that import pyreon source
- * via the `"bun"` export condition.
- */
-declare var process: { env: { NODE_ENV?: string } }

package/src/index.ts

@@ -1,60 +0,0 @@
-// @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 type {
-  FireSummary,
-  ReactiveEdge,
-  ReactiveFire,
-  ReactiveGraph,
-  ReactiveNode,
-  ReactiveNodeKind,
-  SourceLocation,
-} from './reactive-devtools'
-export {
-  activateReactiveDevtools,
-  deactivateReactiveDevtools,
-  getFireSummaries,
-  getReactiveFires,
-  getReactiveGraph,
-  isReactiveDevtoolsActive,
-} from './reactive-devtools'
-// `writeLpihCache` + `startLpihPolling` ship at the `@pyreon/reactivity/lpih`
-// subpath. They depend on `node:fs/promises` (Node-only) and are dev-mode
-// integration utilities — separating them keeps the core main-entry bundle
-// smaller AND clarifies that LPIH writes are an opt-in side-channel, not a
-// core reactivity primitive. See `./lpih.ts` and `docs/docs/lpih.md`.
-export type { ReactiveTraceEntry } from './reactive-trace'
-export { clearReactiveTrace, getReactiveTrace } from './reactive-trace'
-export {
-  _bind,
-  type Effect,
-  effect,
-  onCleanup,
-  type ReactiveSnapshotCapture,
-  renderEffect,
-  setErrorHandler,
-  setSnapshotCapture,
-} from './effect'
-export { reconcile } from './reconcile'
-export { createResource, type Resource } from './resource'
-export {
-  EffectScope,
-  effectScope,
-  getCurrentScope,
-  onScopeDispose,
-  setCurrentScope,
-} from './scope'
-export {
-  type ReadonlySignal,
-  type Signal,
-  type SignalDebugInfo,
-  type SignalOptions,
-  signal,
-} from './signal'
-export { createStore, isStore, markRaw, shallowReactive } from './store'
-export { runUntracked, runUntracked as untrack } from './tracking'
-export { type WatchOptions, watch } from './watch'