@pyreon/reactivity 0.14.0 → 0.16.0

package/src/tests/createSelector.test.ts

@@ -229,4 +229,63 @@ describe('createSelector', () => {
       expect(isSelected(2)).toBe(false)
     })
   })
+
+  // Regression: pre-fix, the source-tracking effect ran forever AND the
+  // per-value subs/hosts Maps grew unboundedly. With dynamic value spaces
+  // (UUIDs, ephemeral IDs) this leaked memory for the lifetime of the
+  // program. dispose() now stops the effect AND clears both Maps.
+  describe('dispose', () => {
+    test('stops source-tracking after dispose', () => {
+      const selected = signal(0)
+      const isSelected = createSelector(() => selected())
+      const runs: number[] = []
+      effect(() => {
+        runs.push(isSelected(1) ? 1 : 0)
+      })
+      expect(runs).toEqual([0])
+      selected.set(1)
+      expect(runs).toEqual([0, 1])
+
+      isSelected.dispose()
+      // Source change after dispose — the effect that tracks `isSelected(1)`
+      // should NOT re-run because the selector's internal effect was stopped.
+      selected.set(2)
+      expect(runs).toEqual([0, 1])
+    })
+
+    test('post-dispose calls return last-known result without tracking', () => {
+      const selected = signal(0)
+      const isSelected = createSelector(() => selected())
+      isSelected.dispose()
+      // Last known value was 0 — calls return its match against the query.
+      expect(isSelected(0)).toBe(true)
+      expect(isSelected(1)).toBe(false)
+    })
+
+    test('dispose is idempotent', () => {
+      const selected = signal(0)
+      const isSelected = createSelector(() => selected())
+      expect(() => {
+        isSelected.dispose()
+        isSelected.dispose()
+        isSelected.dispose()
+      }).not.toThrow()
+    })
+
+    test('post-dispose: source no longer propagates to selector', () => {
+      // Observable consequence of stopping the internal effect — proves
+      // the per-value Maps are no longer being populated either (because
+      // the tracking path is bypassed entirely after dispose).
+      const selected = signal('initial')
+      const isSelected = createSelector(() => selected())
+      // Build up the cache by querying many unique values.
+      for (let i = 0; i < 100; i++) isSelected(`uuid-${i}`)
+      isSelected.dispose()
+      // After dispose, the source is no longer tracked — changing it
+      // doesn't propagate to the selector's internal `current` value.
+      selected.set('changed')
+      expect(isSelected('initial')).toBe(true) // last-known wins
+      expect(isSelected('changed')).toBe(false) // never propagated
+    })
+  })
 })

package/src/tests/effect.test.ts

@@ -397,3 +397,68 @@ describe('effect — error handling', () => {
     setErrorHandler((_err) => {})
   })
 })
+
+// ─── Audit bug #1: async effect runtime warning ──────────────────────────────
+//
+// Companion to the `pyreon/no-async-effect` lint rule. The runtime warn
+// catches the case where the lint rule was suppressed or the effect call
+// site was constructed dynamically (e.g. via a higher-order helper that
+// the lint rule's static check doesn't see).
+
+describe('effect — async function warning (audit bug #1)', () => {
+  test('warns when called with an async arrow function', () => {
+    const warns: string[] = []
+    const orig = console.warn
+    console.warn = (...args: unknown[]) => warns.push(args.join(' '))
+    try {
+      // Async effect callbacks are intentionally NOT in `effect()`'s type
+      // signature — that's the point. The test deliberately misuses the
+      // API to verify the runtime warning catches what the type system
+      // would normally reject. Cast through `unknown` to silence TS.
+      const asyncFn = async (): Promise<void> => {}
+      effect(asyncFn as unknown as () => void)
+    } finally {
+      console.warn = orig
+    }
+    expect(warns.some((m) => m.includes('async function'))).toBe(true)
+    expect(warns.some((m) => m.includes('await'))).toBe(true)
+  })
+
+  test('does NOT warn for synchronous effect callbacks', () => {
+    const warns: string[] = []
+    const orig = console.warn
+    console.warn = (...args: unknown[]) => warns.push(args.join(' '))
+    try {
+      effect(() => {})
+    } finally {
+      console.warn = orig
+    }
+    expect(warns.some((m) => m.includes('async function'))).toBe(false)
+  })
+
+  test('renderEffect warns when called with an async arrow function', () => {
+    const warns: string[] = []
+    const orig = console.warn
+    console.warn = (...args: unknown[]) => warns.push(args.join(' '))
+    try {
+      const asyncFn = async (): Promise<void> => {}
+      renderEffect(asyncFn as unknown as () => void)
+    } finally {
+      console.warn = orig
+    }
+    expect(warns.some((m) => m.includes('renderEffect'))).toBe(true)
+    expect(warns.some((m) => m.includes('async function'))).toBe(true)
+  })
+
+  test('renderEffect does NOT warn for synchronous callbacks', () => {
+    const warns: string[] = []
+    const orig = console.warn
+    console.warn = (...args: unknown[]) => warns.push(args.join(' '))
+    try {
+      renderEffect(() => {})
+    } finally {
+      console.warn = orig
+    }
+    expect(warns.some((m) => m.includes('async function'))).toBe(false)
+  })
+})

package/src/tests/fanout-repro.test.ts

@@ -0,0 +1,179 @@
+/**
+ * Reproduction of the deferred bug from PR #490 (queryReactiveKey-1000 journey).
+ *
+ * Symptom from real-app stress: a `reactKey` signal subscribed to by ~100
+ * effects (each useQuery's setOptions effect) sees `signalWrite` increment
+ * on every `.set(i)` in a tight external loop, but only 1 of N effect runs
+ * propagates per .set — `effectRun` stays at the initial-mount count.
+ *
+ * Hypothesis to test: `notifySubscribers` in tracking.ts iterates the live
+ * Set with `originalSize` cap. If an effect's body calls cleanupEffect (which
+ * removes itself from the Set) AND re-subscribes (adds itself back at the
+ * end), the iteration order shifts so subsequent effects' positions move
+ * BEFORE `i`, causing them to be skipped on this pass.
+ *
+ * See packages/core/reactivity/src/tracking.ts:77-105 (notifySubscribers).
+ */
+import { describe, expect, it } from 'vitest'
+import { effect, effectScope, signal } from '../index'
+
+describe('signal fan-out under tight external write loop', () => {
+  it('100 effects subscribing to same signal — each fires on every external .set', () => {
+    const sig = signal(0)
+    const counts = new Array(100).fill(0)
+
+    for (let i = 0; i < 100; i++) {
+      const idx = i
+      effect(() => {
+        sig() // subscribe
+        counts[idx]++
+      })
+    }
+
+    // Each effect ran ONCE at registration.
+    for (const c of counts) expect(c).toBe(1)
+
+    // 10 external writes from outside any batch.
+    for (let i = 1; i <= 10; i++) sig.set(i)
+
+    // Each effect should have re-fired 10 times → total = 11.
+    for (let i = 0; i < counts.length; i++) {
+      expect(counts[i], `effect[${i}] runs after 10 sets`).toBe(11)
+    }
+  })
+
+  it('1 effect — fires on every external .set (control)', () => {
+    const sig = signal(0)
+    let count = 0
+
+    effect(() => {
+      sig()
+      count++
+    })
+
+    expect(count).toBe(1)
+    for (let i = 1; i <= 10; i++) sig.set(i)
+    expect(count).toBe(11)
+  })
+
+  it('5 effects + 5 external sets — each effect fires per set', () => {
+    const sig = signal(0)
+    const counts = new Array(5).fill(0)
+
+    for (let i = 0; i < 5; i++) {
+      const idx = i
+      effect(() => {
+        sig()
+        counts[idx]++
+      })
+    }
+
+    for (let i = 1; i <= 5; i++) sig.set(i)
+
+    // Each effect: 1 initial + 5 re-runs = 6.
+    for (let i = 0; i < counts.length; i++) {
+      expect(counts[i], `effect[${i}]`).toBe(6)
+    }
+  })
+
+  it('100 effects inside an EffectScope — each fires on every external .set', () => {
+    const sig = signal(0)
+    const counts = new Array(100).fill(0)
+    const scope = effectScope()
+
+    scope.runInScope(() => {
+      for (let i = 0; i < 100; i++) {
+        const idx = i
+        effect(() => {
+          sig()
+          counts[idx]++
+        })
+      }
+    })
+
+    for (const c of counts) expect(c).toBe(1)
+
+    for (let i = 1; i <= 10; i++) sig.set(i)
+
+    for (let i = 0; i < counts.length; i++) {
+      expect(counts[i], `effect[${i}] runs after 10 sets`).toBe(11)
+    }
+  })
+
+  it('1000 effects subscribing to same signal — each fires per .set', () => {
+    const sig = signal(0)
+    const counts = new Array(1000).fill(0)
+    for (let i = 0; i < 1000; i++) {
+      const idx = i
+      effect(() => {
+        sig()
+        counts[idx]++
+      })
+    }
+    for (let i = 1; i <= 10; i++) sig.set(i)
+    let failed = 0
+    for (let i = 0; i < counts.length; i++) {
+      if (counts[i] !== 11) failed++
+    }
+    expect(failed, `effects with wrong count`).toBe(0)
+  })
+
+  it('effects created INSIDE another effect run (inner-effect collector path)', () => {
+    const trigger = signal(0)
+    const sig = signal(0)
+    const counts = new Array(50).fill(0)
+    let outerRuns = 0
+
+    // Outer effect creates 50 INNER effects on each run.
+    effect(() => {
+      trigger()
+      outerRuns++
+      for (let i = 0; i < 50; i++) {
+        const idx = i
+        effect(() => {
+          sig()
+          counts[idx]++
+        })
+      }
+    })
+
+    // Reset counts after initial outer run created the inners with their initial run.
+    expect(outerRuns).toBe(1)
+    for (const c of counts) expect(c).toBe(1)
+
+    // Now flip sig 10 times — every inner should fire 10 more times.
+    for (let i = 1; i <= 10; i++) sig.set(i)
+
+    let failed = 0
+    for (let i = 0; i < counts.length; i++) {
+      if (counts[i] !== 11) failed++
+    }
+    expect(failed, `inner effects with wrong count`).toBe(0)
+  })
+
+  it('100 effects whose body writes to an unrelated signal during run', () => {
+    // Mirrors useQuery's effect: body calls observer.setOptions(options())
+    // which fires the observer's subscribe callback, which calls batch()
+    // and writes to N "result slot" signals (which may have 0 or N subscribers).
+    const sig = signal(0)
+    const slot = signal('')
+    const counts = new Array(100).fill(0)
+
+    for (let i = 0; i < 100; i++) {
+      const idx = i
+      effect(() => {
+        sig() // subscribe to sig
+        // Simulate observer.setOptions's downstream subscribe-callback work:
+        // an inner write to a different signal that has no subscribers.
+        slot.set(`run-${idx}`) // 100 different values, each Object.is fails
+        counts[idx]++
+      })
+    }
+
+    for (let i = 1; i <= 10; i++) sig.set(i)
+
+    for (let i = 0; i < counts.length; i++) {
+      expect(counts[i], `effect[${i}] runs after 10 sets`).toBe(11)
+    }
+  })
+})

package/src/tests/manifest-snapshot.test.ts

@@ -68,11 +68,27 @@ describe('gen-docs — reactivity snapshot', () => {
 
   it('renders @pyreon/reactivity to MCP api-reference entries — one per api[] item', () => {
     const record = renderApiReferenceEntries(reactivityManifest)
-    expect(Object.keys(record).length).toBe(8)
+    // 25 entries: 8 original (signal/computed/effect/batch/onCleanup/watch/
+    // createStore/untrack) + 1 createResource (PR #459) + 13 from M1
+    // enrichment (renderEffect, nextTick, createSelector, cell, reconcile,
+    // isStore, effectScope, getCurrentScope, setCurrentScope,
+    // onSignalUpdate, inspectSignal, why, setErrorHandler) + 3 from M4
+    // Vue parity (markRaw, shallowReactive, onScopeDispose).
+    expect(Object.keys(record).length).toBe(25)
     expect(Object.keys(record)).toContain('reactivity/signal')
+    expect(Object.keys(record)).toContain('reactivity/createResource')
     // Spot-check the flagship API — signal is the core primitive
     const signal = record['reactivity/signal']!
     expect(signal.mistakes?.split('\n').length).toBe(6)
     expect(signal.notes).toContain('CALLABLE FUNCTION')
+    // Spot-check createResource has the dispose mistake (regression for H3)
+    const resource = record['reactivity/createResource']!
+    expect(resource.mistakes).toContain('Forgetting `dispose()`')
+    // Spot-check newly-added entries surface their key foot-guns
+    expect(record['reactivity/createSelector']!.mistakes).toContain(
+      'every row subscribes to source',
+    )
+    expect(record['reactivity/effectScope']!.mistakes).toContain('leak')
+    expect(record['reactivity/cell']!.notes).toContain('NOT callable')
   })
 })

package/src/tests/resource.test.ts

@@ -230,4 +230,97 @@ describe('createResource', () => {
     await new Promise((r) => setTimeout(r, 10))
     expect(results).toEqual(['user-1', 'user-5', 'user-5'])
   })
+
+  // Regression: pre-fix, the source-tracking effect ran forever with no API
+  // to stop it. Resources created outside an EffectScope leaked the effect
+  // for the lifetime of the program. dispose() now stops the effect AND
+  // marks pending in-flight responses as stale.
+  describe('dispose', () => {
+    test('stops source-tracking after dispose', async () => {
+      const src = signal(1)
+      const calls: number[] = []
+      const resource = createResource(
+        () => src(),
+        (id) => {
+          calls.push(id)
+          return Promise.resolve(`user-${id}`)
+        },
+      )
+
+      await new Promise((r) => setTimeout(r, 10))
+      expect(calls).toEqual([1])
+
+      resource.dispose()
+
+      // Source change after dispose — should NOT trigger a new fetch.
+      src.set(2)
+      await new Promise((r) => setTimeout(r, 10))
+      expect(calls).toEqual([1])
+    })
+
+    test('refetch is a no-op after dispose', async () => {
+      const src = signal(1)
+      const calls: number[] = []
+      const resource = createResource(
+        () => src(),
+        (id) => {
+          calls.push(id)
+          return Promise.resolve(`user-${id}`)
+        },
+      )
+
+      await new Promise((r) => setTimeout(r, 10))
+      expect(calls).toEqual([1])
+
+      resource.dispose()
+      resource.refetch()
+      await new Promise((r) => setTimeout(r, 10))
+      expect(calls).toEqual([1])
+    })
+
+    test('in-flight response is discarded after dispose', async () => {
+      const src = signal(1)
+      // Capture the resolver via a one-element holder so TS doesn't narrow
+      // the closure-assigned variable to `never` after the new Promise
+      // callback returns. `let r = null` then assignment inside the
+      // callback narrows to `never` post-callback (no follow-callback flow).
+      const holder: { resolve: (v: string) => void } = {
+        resolve: () => undefined,
+      }
+      const resource = createResource(
+        () => src(),
+        () =>
+          new Promise<string>((r) => {
+            holder.resolve = r
+          }),
+      )
+
+      // Don't resolve yet — fetch is in flight.
+      expect(resource.loading()).toBe(true)
+      resource.dispose()
+
+      // Now resolve — handlers should see the bumped requestId and discard.
+      holder.resolve('late-result')
+      await new Promise((r) => setTimeout(r, 10))
+
+      expect(resource.data()).toBeUndefined()
+      // loading was true at dispose; response was discarded so the
+      // post-fetch `loading.set(false)` never ran. That's the documented
+      // contract — dispose freezes the resource at its current state.
+      expect(resource.loading()).toBe(true)
+    })
+
+    test('dispose is idempotent', () => {
+      const src = signal(1)
+      const resource = createResource(
+        () => src(),
+        (id) => Promise.resolve(`user-${id}`),
+      )
+      expect(() => {
+        resource.dispose()
+        resource.dispose()
+        resource.dispose()
+      }).not.toThrow()
+    })
+  })
 })

package/src/tests/scope.test.ts

@@ -199,4 +199,33 @@ describe('effectScope', () => {
     expect(errors.length).toBe(1)
     console.error = origError
   })
+
+  // Regression: pre-fix, addUpdateHook always allocated `_updateHooks` and
+  // pushed the fn even after `stop()`. The fn never fired (because
+  // notifyEffectRan checks `_active` first), but the registration leaked
+  // an array allocation and gave the caller no signal that the hook was
+  // futile. Mirrors `add()`'s silent-no-op-when-stopped contract.
+  test('addUpdateHook honors _active — silently no-ops on stopped scope', () => {
+    const scope = effectScope()
+    scope.stop()
+
+    let hookFired = false
+    scope.addUpdateHook(() => {
+      hookFired = true
+    })
+
+    // Cause an update — the hook should NOT fire because scope is stopped.
+    scope.notifyEffectRan()
+    expect(hookFired).toBe(false)
+
+    // The internal `_updateHooks` should not have been allocated either.
+    // We can't introspect the private field, but the observable contract
+    // is "stopped scopes don't fire hooks under any circumstance" — which
+    // would have held pre-fix too because `notifyEffectRan` already
+    // gated on `_active`. The fix prevents the array allocation; we test
+    // the consequence: no fire, regardless of how often you push.
+    for (let i = 0; i < 100; i++) scope.addUpdateHook(() => {})
+    scope.notifyEffectRan()
+    expect(hookFired).toBe(false)
+  })
 })

package/src/tests/signal.test.ts

@@ -1,4 +1,5 @@
 import { batch } from '../batch'
+import { onSignalUpdate } from '../debug'
 import { effect } from '../effect'
 import { signal } from '../signal'
 
@@ -231,4 +232,111 @@ describe('signal', () => {
       warnSpy.mockRestore()
     })
   })
+
+  // Regression: pre-fix, a throwing trace listener (registered via
+  // onSignalUpdate) was called inline between the `_v` write and subscriber
+  // notification. If it threw, `_v` was updated but no effects ran — divergent
+  // state. Fix wraps the trace dispatch in try/catch.
+  describe('throwing trace listener does not corrupt state', () => {
+    test('subscribers still fire when a trace listener throws', () => {
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+      const s = signal(0)
+      const subscriberRuns: number[] = []
+      effect(() => {
+        subscriberRuns.push(s())
+      })
+
+      const dispose = onSignalUpdate(() => {
+        throw new Error('trace listener boom')
+      })
+
+      // Pre-fix: the throwing listener would prevent the subscriber from
+      // firing. Post-fix: the listener throws, gets logged, subscriber runs.
+      s.set(5)
+      expect(subscriberRuns).toEqual([0, 5])
+      // Dev mode logs the listener error — bisect-verify the wrap is in place
+      expect(errorSpy).toHaveBeenCalledWith(
+        expect.stringContaining('trace listener threw'),
+        expect.any(Error),
+      )
+
+      dispose()
+      errorSpy.mockRestore()
+    })
+
+    test('multiple writes survive a chronically-broken listener', () => {
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+      const s = signal(0)
+      const seen: number[] = []
+      effect(() => {
+        seen.push(s())
+      })
+
+      const dispose = onSignalUpdate(() => {
+        throw new Error('always')
+      })
+      s.set(1)
+      s.set(2)
+      s.set(3)
+      expect(seen).toEqual([0, 1, 2, 3])
+
+      dispose()
+      errorSpy.mockRestore()
+    })
+  })
+
+  // L7 audit gap: cap-iteration in notifySubscribers caps at originalSize to
+  // avoid infinite loops if a subscriber re-inserts itself or others into the
+  // Set. The contract: subscribers added DURING notification fire next round,
+  // not this round (no double-fire). Pin the contract.
+  describe('subscriber cap-iteration during notification (L7)', () => {
+    test('subscriber added mid-notification fires on the NEXT write, not the current one', () => {
+      const s = signal(0)
+      const fires: string[] = []
+
+      const lateSubscriber = (): void => {
+        fires.push('late')
+      }
+
+      s.subscribe(() => {
+        fires.push('first')
+        // Add a NEW subscriber during the notification. Per cap-iteration
+        // contract, it should NOT fire this round.
+        s.subscribe(lateSubscriber)
+      })
+
+      s.set(1)
+      // Only "first" fires this round — "late" gets registered, doesn't run.
+      expect(fires).toEqual(['first'])
+
+      // Next write — both fire (first was already there, late is now registered).
+      fires.length = 0
+      s.set(2)
+      expect(fires.sort()).toEqual(['first', 'late'])
+    })
+
+    test('subscriber that disposes itself mid-iteration cleans up cleanly', () => {
+      const s = signal(0)
+      let disposeMe: (() => void) | null = null
+      let firstRuns = 0
+      let secondRuns = 0
+
+      s.subscribe(() => {
+        firstRuns++
+      })
+      disposeMe = s.subscribe(() => {
+        secondRuns++
+        disposeMe?.() // self-dispose
+      })
+
+      s.set(1)
+      expect(firstRuns).toBe(1)
+      expect(secondRuns).toBe(1)
+
+      // Next write — second is gone, first still fires.
+      s.set(2)
+      expect(firstRuns).toBe(2)
+      expect(secondRuns).toBe(1)
+    })
+  })
 })

package/src/tests/store.test.ts

@@ -143,6 +143,60 @@ describe('createStore', () => {
     expect(bValues).toEqual([2, undefined])
   })
 
+  // Regression: delete-then-reassign cycle. Pre-fix `deleteProperty` removed
+  // the entry from `propSignals`, so a later `set` on the same key created a
+  // FRESH signal — but every effect that previously read the key was tracked
+  // against the OLD signal, which had been dropped. Effects never re-ran on
+  // the reassign. Fix keeps the signal in `propSignals`, and `get` short-
+  // circuits to the existing signal when the key isn't `hasOwn` but a tracked
+  // signal exists. See store.ts (deleteProperty, get).
+  test('delete-then-reassign re-runs effects (signal identity preserved)', () => {
+    const state = createStore({ a: 1, b: 2 } as Record<string, number | undefined>)
+    const bValues: (number | undefined)[] = []
+    effect(() => {
+      bValues.push(state.b)
+    })
+    expect(bValues).toEqual([2])
+    delete state.b
+    expect(bValues).toEqual([2, undefined])
+    state.b = 99
+    expect(bValues).toEqual([2, undefined, 99])
+    // Cycle a second time to lock the contract — same signal identity reused.
+    delete state.b
+    state.b = 7
+    expect(bValues).toEqual([2, undefined, 99, undefined, 7])
+  })
+
+  // Regression: built-in objects with internal slots (Map, Set, Date, …) used
+  // to be wrapped in the proxy, which broke their methods (`Map.prototype.set`
+  // called on a Proxy → `TypeError: incompatible receiver`). Fix returns the
+  // raw instance from `wrap()` for these types — no fine-grained reactivity
+  // for their contents, but they're at least usable. See store.ts
+  // (isBuiltinNonProxiable).
+  test('Map fields are returned raw, not wrapped (proxy-incompatible)', () => {
+    const state = createStore({ users: new Map<string, number>() })
+    expect(() => state.users.set('alice', 1)).not.toThrow()
+    expect(state.users.get('alice')).toBe(1)
+    expect(state.users.size).toBe(1)
+  })
+
+  test('Set fields are returned raw, not wrapped', () => {
+    const state = createStore({ tags: new Set<string>() })
+    expect(() => state.tags.add('foo')).not.toThrow()
+    expect(state.tags.has('foo')).toBe(true)
+  })
+
+  test('Date fields are returned raw, not wrapped', () => {
+    const d = new Date('2026-01-01')
+    const state = createStore({ created: d })
+    expect(state.created.getFullYear()).toBe(2026)
+  })
+
+  test('RegExp fields are returned raw, not wrapped', () => {
+    const state = createStore({ rx: /abc/ })
+    expect(state.rx.test('abc')).toBe(true)
+  })
+
   test('setting array length directly triggers reactivity', () => {
     const state = createStore({ items: [1, 2, 3, 4, 5] })
     const lengths: number[] = []