@pyreon/reactivity 0.24.4 → 0.24.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/reactivity",
-  "version": "0.24.4",
+  "version": "0.24.6",
   "description": "Signals-based reactivity system for Pyreon",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/reactivity#readme",
   "bugs": {
@@ -15,7 +15,6 @@
   "files": [
     "lib",
     "!lib/**/*.map",
-    "src",
     "README.md",
     "LICENSE"
   ],
@@ -26,12 +25,10 @@
   "types": "./lib/types/index.d.ts",
   "exports": {
     ".": {
-      "bun": "./src/index.ts",
       "import": "./lib/index.js",
       "types": "./lib/types/index.d.ts"
     },
     "./lpih": {
-      "bun": "./src/lpih.ts",
       "import": "./lib/lpih.js",
       "types": "./lib/types/lpih.d.ts"
     }

package/src/batch.ts

@@ -1,196 +0,0 @@
-// Batch multiple signal updates into a single notification pass.
-// Two-tier flush: computed recomputes drain first (within-pass Set-dedup),
-// THEN effects drain (multi-pass with cross-pass re-fire support).
-//
-// Dev-mode invariant gate: see https://github.com/pyreon/pyreon/blob/main/packages/core/reactivity/src/tests/batch.test.ts
-// for the property-based test that fuzzes random cascade graphs against this
-// invariant. The build-time gate folds to dead code in production bundles.
-const __DEV__ = process.env.NODE_ENV !== 'production'
-
-let batchDepth = 0
-
-// Two-tier queue design:
-//
-// 1. **`pendingRecomputes`** — computed.recompute callbacks. Drained FIRST in
-//    a cascading-iteration loop: cascading recomputes enqueued during a
-//    drain land in the same Set (Set.add idempotency dedupes), iteration
-//    visits added entries (JS Set iteration semantics), and the recompute
-//    layer settles before any effect fires. This guarantees effects always
-//    read fully-propagated computed values.
-//
-// 2. **`pendingEffects`** — effect.run callbacks. Drained SECOND, multi-pass.
-//    Within a single pass, Set.add idempotency gives us within-pass dedup
-//    (diamond / multi-dep selector). Across passes (entries re-enqueued
-//    AFTER being visited in the current pass — see `_visitedThisPass`), they
-//    fire AGAIN — needed for control flow that re-renders based on its own
-//    dispatch (e.g. ErrorBoundary's handler calling `error.set(err)` during
-//    the same run that mounted the throwing child). MAX_PASSES caps total
-//    passes at 32 to prevent pathological infinite re-enqueue loops.
-//
-// **Why two tiers, not one Set:**
-//   - Single-Set iteration (the prior design) worked for shallow cascades
-//     because the cascading recompute → effect re-enqueue happened BEFORE
-//     iteration reached the effect. For deep cascades (3+ hops), iteration
-//     reached the effect (with its stale upstream value) BEFORE the cascade
-//     finished propagating. Effect read stale values; subsequent cascade
-//     re-enqueues were dropped by Set.add idempotency.
-//   - Splitting recomputes from effects fixes this: all computed recomputes
-//     settle before any effect runs. The cascade-asymmetry contract from
-//     PR #381 is preserved (effects still fire once per batched change),
-//     AND deep-cascade correctness is added (effects always read settled
-//     values).
-//   - Multi-pass effect drain unblocks ErrorBoundary's "re-fire after
-//     dispatching from inside own run" pattern without breaking the
-//     single-fire contract for non-self-dispatching effects.
-//
-// **How a callback gets routed:** computed registers its `recompute` via
-// `_markRecompute(fn)` at creation time. The internal `_recomputes` WeakSet
-// tracks them. `enqueuePendingNotification` checks the WeakSet to route.
-const pendingRecomputes = new Set<() => void>()
-const pendingEffects = new Set<() => void>()
-const _nextEffectPass = new Set<() => void>()
-let _visitedThisPass: Set<() => void> | null = null
-const _recomputes = new WeakSet<() => void>()
-const MAX_PASSES = 32
-
-/**
- * Mark a callback as a computed recompute (called from computed.ts at
- * creation time). Routes future enqueues into the recompute queue so they
- * settle before any effects fire.
- */
-export function _markRecompute(fn: () => void): void {
-  _recomputes.add(fn)
-}
-
-export function batch(fn: () => void): void {
-  batchDepth++
-  try {
-    fn()
-  } finally {
-    batchDepth--
-    if (batchDepth === 0 && (pendingRecomputes.size > 0 || pendingEffects.size > 0)) {
-      // Keep batching active during flush so cascade-notifications emitted
-      // by flushing subscribers enqueue into the same queues (dedup against
-      // already-queued entries) instead of firing inline.
-      batchDepth = 1
-      try {
-        // Outer loop: alternate between tier-1 (recomputes) and tier-2
-        // (effects) until both queues are empty. An effect can write a
-        // signal whose subscribers include lazy `computed.recompute`s — those
-        // get enqueued into pendingRecomputes mid-effect, and we need to
-        // drain them BEFORE the next effect pass so downstream effects see
-        // the propagated dirty flag. MAX_PASSES caps the OUTER loop —
-        // counts effect-tier passes only since recomputes converge by
-        // `equals` short-circuit and don't infinite-loop in practice.
-        let effectPass = 0
-        while (pendingRecomputes.size > 0 || pendingEffects.size > 0) {
-          // Tier 1: drain all recomputes via cascading iteration. Set
-          // semantics visit entries added during iteration; Set.add
-          // idempotency dedupes diamond cascades. Recomputes converge by
-          // `equals` short-circuit (computedWithEquals returns early when
-          // value is unchanged) and computedLazy's `if (dirty) return`
-          // guard prevents re-fire.
-          for (const r of pendingRecomputes) r()
-          pendingRecomputes.clear()
-
-          // Tier 2: drain ONE pass of effects in multi-pass mode. Within-
-          // pass dedup preserved by Set.add idempotency on entries not yet
-          // visited this pass. Cross-pass re-fire enabled by routing
-          // already-visited entries to `_nextEffectPass` (handled in
-          // `enqueuePendingNotification`). After the pass, loop back to
-          // tier 1 to drain any recomputes the effects enqueued.
-          if (pendingEffects.size > 0) {
-            if (++effectPass > MAX_PASSES) {
-              if (__DEV__) {
-                // Surface labels of dropped effects when available — helps
-                // identify the offending effect in a real app. Falls back to
-                // bare count for anonymous effects.
-                const droppedCount = pendingEffects.size
-                const labels: string[] = []
-                for (const notify of pendingEffects) {
-                  const label = (notify as { _label?: string })._label
-                  if (label) labels.push(label)
-                  if (labels.length >= 5) break
-                }
-                const labelHint = labels.length
-                  ? ` Sample labels: ${labels.join(', ')}${droppedCount > labels.length ? `, …${droppedCount - labels.length} more` : ''}.`
-                  : ''
-                // oxlint-disable-next-line no-console
-                console.warn(
-                  '[pyreon] batch effect flush exceeded MAX_PASSES (32) — possible infinite re-enqueue loop. ' +
-                    `${droppedCount} pending effects dropped.${labelHint} ` +
-                    'Common cause: an effect that writes to a signal it also reads, without a guard. ' +
-                    'See packages/core/reactivity/src/batch.ts for the multi-pass flush contract.',
-                )
-              }
-              // Drop the queue so subsequent batches start clean — without
-              // this, the next batch would re-encounter the offending effect
-              // immediately on its first pass and trip MAX_PASSES instantly,
-              // making the original error harder to diagnose.
-              pendingEffects.clear()
-              _nextEffectPass.clear()
-              break
-            }
-            _visitedThisPass = new Set<() => void>()
-            for (const notify of pendingEffects) {
-              _visitedThisPass.add(notify)
-              notify()
-            }
-            // Promote next-pass entries to pending for the next iteration.
-            pendingEffects.clear()
-            for (const next of _nextEffectPass) pendingEffects.add(next)
-            _nextEffectPass.clear()
-          }
-        }
-      } finally {
-        // Clear ALWAYS — even if a notify threw mid-iteration. Without this,
-        // the unflushed remainder leaks into the next batch and refires
-        // (audit bug #19). Effects wrap their callbacks in try/catch
-        // internally so this is rarely reachable in practice, but raw
-        // signal subscribers (signal.subscribe) and lower-level consumers
-        // can throw straight through, and a future refactor that swallows
-        // less aggressively would silently regress without this guard.
-        pendingRecomputes.clear()
-        pendingEffects.clear()
-        _nextEffectPass.clear()
-        _visitedThisPass = null
-        batchDepth = 0
-      }
-    }
-  }
-}
-
-export function isBatching(): boolean {
-  return batchDepth > 0
-}
-
-export function enquePendingNotificationDeprecated(): void {
-  // Kept as a comment placeholder — actual export is below. (Empty body to
-  // keep this file's exports list stable across the refactor.)
-}
-
-export function enqueuePendingNotification(notify: () => void): void {
-  // Route based on callback kind. Computed recomputes go to tier-1 queue,
-  // effects to tier-2. Within tier 2, already-visited-this-pass entries
-  // route to next-pass for cross-pass re-fire (ErrorBoundary's pattern).
-  if (_recomputes.has(notify)) {
-    pendingRecomputes.add(notify)
-  } else if (_visitedThisPass !== null && _visitedThisPass.has(notify)) {
-    _nextEffectPass.add(notify)
-  } else {
-    pendingEffects.add(notify)
-  }
-}
-
-/**
- * Returns a Promise that resolves after all currently-pending microtasks have flushed.
- * Useful when you need to read the DOM after a batch of signal updates has settled.
- *
- * @example
- * count.set(1); count.set(2)
- * await nextTick()
- * // DOM is now up-to-date
- */
-export function nextTick(): Promise<void> {
-  return new Promise((resolve) => queueMicrotask(resolve))
-}

package/src/cell.ts

@@ -1,72 +0,0 @@
-/**
- * Lightweight reactive cell — class-based alternative to signal().
- *
- * - 1 object allocation vs signal()'s 6 closures
- * - Same API surface: peek(), set(), update(), subscribe(), listen()
- * - NOT callable as a getter (no effect tracking) — use for fixed subscriptions
- * - Methods on prototype, shared across all instances
- * - Single-listener fast path: no Set allocated when ≤1 subscriber
- *
- * Use when you need reactive state but don't need automatic effect dependency tracking.
- * Ideal for list item labels in keyed reconcilers where subscribe() is used directly.
- */
-export class Cell<T> {
-  /** @internal */ _v: T
-  /** @internal */ _l: (() => void) | null = null // single-listener fast path
-  /** @internal */ _s: Set<() => void> | null = null // multi-listener fallback
-
-  constructor(value: T) {
-    this._v = value
-  }
-
-  peek(): T {
-    return this._v
-  }
-
-  set(value: T): void {
-    if (Object.is(this._v, value)) return
-    this._v = value
-    if (this._l) this._l()
-    else if (this._s) for (const fn of this._s) fn()
-  }
-
-  update(fn: (current: T) => T): void {
-    this.set(fn(this._v))
-  }
-
-  /**
-   * Fire-and-forget subscription — no unsubscribe returned.
-   * Use when the listener's lifetime matches the cell's (e.g., list rows).
-   * Saves 1 closure allocation per call vs subscribe().
-   */
-  listen(listener: () => void): void {
-    if (!this._l && !this._s) {
-      this._l = listener
-    } else {
-      // Promote to Set
-      if (!this._s) {
-        this._s = new Set()
-        if (this._l) {
-          this._s.add(this._l)
-          this._l = null
-        }
-      }
-      this._s.add(listener)
-    }
-  }
-
-  subscribe(listener: () => void): () => void {
-    this.listen(listener)
-    // The listener could be in _l (single) or _s (multi).
-    // A later subscribe() call may promote it from _l to _s,
-    // so the disposer must check both locations.
-    return () => {
-      if (this._l === listener) this._l = null
-      else this._s?.delete(listener)
-    }
-  }
-}
-
-export function cell<T>(value: T): Cell<T> {
-  return new Cell(value)
-}

package/src/computed.ts

@@ -1,313 +0,0 @@
-import { _markRecompute } from './batch'
-import { _errorHandler } from './effect'
-import { _captureCallerLocation, _rdRecordFire, _rdRegister } from './reactive-devtools'
-import { getCurrentScope } from './scope'
-import {
-  cleanupEffect,
-  notifySubscribers,
-  setDepsCollector,
-  setSkipDepsCollection,
-  trackSubscriber,
-  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 Computed<T> {
-  (): T
-  /** Remove this computed from all its reactive dependencies. */
-  dispose(): void
-  /** Cached value for compiler-emitted direct bindings (_bindText, _bindDirect). */
-  _v: T
-  /** Register a direct updater — used by compiler-emitted _bindText/_bindDirect. */
-  direct(updater: () => void): () => void
-}
-
-export interface ComputedOptions<T> {
-  /**
-   * Custom equality function. When provided, the computed eagerly re-evaluates
-   * on dependency change and only notifies downstream if `equals(prev, next)`
-   * returns false. Useful for derived objects/arrays to skip spurious updates.
-   *
-   * @example
-   * const sorted = computed(() => items().slice().sort(), {
-   *   equals: (a, b) => a.length === b.length && a.every((v, i) => v === b[i])
-   * })
-   */
-  equals?: (prev: T, next: T) => boolean
-  /**
-   * @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 computed 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 }
-}
-
-/** Remove a computed from all dependency subscriber sets (local deps array). */
-function cleanupLocalDeps(deps: Set<() => void>[], fn: () => void): void {
-  for (let i = 0; i < deps.length; i++) (deps[i] as Set<() => void>).delete(fn)
-  deps.length = 0
-}
-
-/** Re-track dependencies using the local deps array collector. */
-function trackWithLocalDeps<T>(deps: Set<() => void>[], effect: () => void, fn: () => T): T {
-  setDepsCollector(deps)
-  const result = withTracking(effect, fn)
-  setDepsCollector(null)
-  return result
-}
-
-export function computed<T>(fn: () => T, options?: ComputedOptions<T>): Computed<T> {
-  // Dev warning for async computed callbacks (audit bug #1 — extension).
-  // `computed(async () => …)` returns `Computed<Promise<T>>`, which silently
-  // breaks every consumer that expects `Computed<T>`. There's no scenario
-  // where async makes sense here — the recompute fires synchronously and
-  // tracks signals only in the synchronous prefix. For async-derived
-  // state, use `createResource` or a `signal<T>` updated from an effect.
-  if (process.env.NODE_ENV !== 'production') {
-    if (fn.constructor && fn.constructor.name === 'AsyncFunction') {
-      // oxlint-disable-next-line no-console
-      console.warn(
-        '[pyreon] computed() received an async function. The result type becomes `Computed<Promise<T>>`, and signal reads after the first `await` are NOT tracked. ' +
-          'Use `createResource` for async-derived state, or compute synchronously over a signal that holds the awaited value.',
-      )
-    }
-  }
-  // Prefer build-time-injected location (zero runtime cost) over the
-  // ~2.2µs stack-capture fallback. @pyreon/vite-plugin's `injectSignalNames`
-  // rewrites `computed(() => …)` to `computed(() => …, { __sourceLocation: {…} })`
-  // at transform time so most dev-mode computeds never pay the stack-capture cost.
-  const loc = options?.__sourceLocation
-  return options?.equals
-    ? computedWithEquals(fn, options.equals, loc)
-    : computedLazy(fn, loc)
-}
-
-/**
- * Default computed — lazy evaluation with deferred cleanup.
- *
- * On notification: just marks dirty and propagates (no cleanup/re-track).
- * On read: cleans up old deps, re-evaluates, re-tracks.
- *
- * The `if (dirty) return` early exit in recompute prevents double-propagation
- * in diamond patterns (a→b,c→d: b notifies d, c tries to notify d again —
- * skipped because d is already dirty).
- */
-function computedLazy<T>(
-  fn: () => T,
-  injectedLoc?: { file: string; line: number; col: number },
-): Computed<T> {
-  let value: T
-  let dirty = true
-  let disposed = false
-  let tracked = false
-  const deps: Set<() => void>[] = []
-  const host: { _s: Set<() => void> | null } = { _s: null }
-  // Set, not a never-compacted flat array. The array form's disposal
-  // only nulled the slot (`arr[idx] = null`) and never shrank, so a
-  // long-lived computed (a derived theme/locale/auth value, or one read
-  // inside churning `<For>` rows) bound by mount/unmount churn grew one
-  // permanent dead slot per ever-registered binding — app-lifetime
-  // memory growth AND `recompute` iterating O(total-ever) instead of
-  // O(live). Identical bug class already fixed for `signal._d`
-  // (signal.ts `_directFn`); `computed` was left on the broken pattern.
-  let directFns: Set<() => void> | null = null
-
-  const recompute = () => {
-    if (disposed || dirty) return
-    dirty = true
-    if (host._s) notifySubscribers(host._s)
-    if (directFns) for (const f of directFns) f()
-  }
-  _markRecompute(recompute)
-
-  const read = (): T => {
-    trackSubscriber(host)
-    if (dirty) {
-      if (process.env.NODE_ENV !== 'production') {
-        _countSink.__pyreon_count__?.('reactivity.computedRecompute')
-        _rdRecordFire(read)
-      }
-      try {
-        if (tracked) {
-          // Deps already established from first run — skip adding to
-          // subscriber Sets again (they already contain recompute).
-          // Still need withTracking so activeEffect is set correctly
-          // for any NEW signals read on this evaluation.
-          setSkipDepsCollection(true)
-          value = withTracking(recompute, fn)
-          setSkipDepsCollection(false)
-        } else {
-          value = trackWithLocalDeps(deps, recompute, fn)
-          tracked = true
-        }
-      } catch (err) {
-        _errorHandler(err)
-      }
-      dirty = false
-    }
-    return value as T
-  }
-
-  read.dispose = () => {
-    disposed = true
-    cleanupLocalDeps(deps, recompute)
-  }
-
-  Object.defineProperty(read, '_v', {
-    get: () => {
-      if (dirty) read() // ensure value is fresh
-      return value
-    },
-    enumerable: false,
-  })
-
-  // @internal — mirrors `signal._d`. Lets tests deterministically assert
-  // the live direct-updater set stays BOUNDED under register/dispose
-  // churn (the never-compacted-array leak this fix removes).
-  Object.defineProperty(read, '_d', {
-    get: () => directFns,
-    enumerable: false,
-  })
-
-  read.direct = (updater: () => void): (() => void) => {
-    if (!directFns) directFns = new Set()
-    const set = directFns
-    set.add(updater)
-    return () => {
-      set.delete(updater)
-    }
-  }
-
-  if (process.env.NODE_ENV !== 'production')
-    // skipFrames=2: skip computedLazy/computedWithEquals + computed, capture user's call site.
-    _rdRegister(
-      read,
-      'derived',
-      host,
-      recompute,
-      undefined,
-      injectedLoc ?? _captureCallerLocation(2),
-    )
-
-  getCurrentScope()?.add({ dispose: read.dispose })
-  return read as Computed<T>
-}
-
-/**
- * Computed with custom equality — eager evaluation on notification.
- *
- * Re-evaluates immediately when deps change and only notifies downstream
- * if `equals(prev, next)` returns false.
- */
-function computedWithEquals<T>(
-  fn: () => T,
-  equals: (prev: T, next: T) => boolean,
-  injectedLoc?: { file: string; line: number; col: number },
-): Computed<T> {
-  let value: T
-  let dirty = true
-  let initialized = false
-  let disposed = false
-  const deps: Set<() => void>[] = []
-  const host: { _s: Set<() => void> | null } = { _s: null }
-  // Set, not a never-compacted flat array. The array form's disposal
-  // only nulled the slot (`arr[idx] = null`) and never shrank, so a
-  // long-lived computed (a derived theme/locale/auth value, or one read
-  // inside churning `<For>` rows) bound by mount/unmount churn grew one
-  // permanent dead slot per ever-registered binding — app-lifetime
-  // memory growth AND `recompute` iterating O(total-ever) instead of
-  // O(live). Identical bug class already fixed for `signal._d`
-  // (signal.ts `_directFn`); `computed` was left on the broken pattern.
-  let directFns: Set<() => void> | null = null
-
-  const recompute = () => {
-    if (disposed) return
-    if (process.env.NODE_ENV !== 'production') {
-      _countSink.__pyreon_count__?.('reactivity.computedRecompute')
-      _rdRecordFire(read)
-    }
-    cleanupLocalDeps(deps, recompute)
-    try {
-      const next = trackWithLocalDeps(deps, recompute, fn)
-      if (initialized && equals(value as T, next)) return
-      value = next
-      dirty = false
-      initialized = true
-    } catch (err) {
-      _errorHandler(err)
-      return
-    }
-    if (host._s) notifySubscribers(host._s)
-    if (directFns) for (const f of directFns) f()
-  }
-  _markRecompute(recompute)
-
-  const read = (): T => {
-    trackSubscriber(host)
-    if (dirty) {
-      if (process.env.NODE_ENV !== 'production')
-        _countSink.__pyreon_count__?.('reactivity.computedRecompute')
-      cleanupLocalDeps(deps, recompute)
-      try {
-        value = trackWithLocalDeps(deps, recompute, fn)
-      } catch (err) {
-        _errorHandler(err)
-      }
-      dirty = false
-      initialized = true
-    }
-    return value as T
-  }
-
-  read.dispose = () => {
-    disposed = true
-    cleanupLocalDeps(deps, recompute)
-    cleanupEffect(recompute)
-  }
-
-  Object.defineProperty(read, '_v', {
-    get: () => {
-      if (dirty) read()
-      return value
-    },
-    enumerable: false,
-  })
-
-  // @internal — mirrors `signal._d`. Lets tests deterministically assert
-  // the live direct-updater set stays BOUNDED under register/dispose
-  // churn (the never-compacted-array leak this fix removes).
-  Object.defineProperty(read, '_d', {
-    get: () => directFns,
-    enumerable: false,
-  })
-
-  read.direct = (updater: () => void): (() => void) => {
-    if (!directFns) directFns = new Set()
-    const set = directFns
-    set.add(updater)
-    return () => {
-      set.delete(updater)
-    }
-  }
-
-  if (process.env.NODE_ENV !== 'production')
-    // skipFrames=2: skip computedLazy/computedWithEquals + computed, capture user's call site.
-    _rdRegister(
-      read,
-      'derived',
-      host,
-      recompute,
-      undefined,
-      injectedLoc ?? _captureCallerLocation(2),
-    )
-
-  getCurrentScope()?.add({ dispose: read.dispose })
-  return read as Computed<T>
-}