@pyreon/reactivity 0.24.4 → 0.24.6

package/src/reconcile.ts

@@ -1,118 +0,0 @@
-/**
- * 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>
-
-// Keys that, written through the bracket-assignment paths below, would
-// mutate Object.prototype (or a constructor's prototype) instead of the
-// store. `reconcile` is explicitly documented for applying API responses
-// directly (`reconcile(JSON.parse(body), store)`), and
-// `JSON.parse('{"__proto__":{…}}')` yields an OWN enumerable `__proto__`
-// key that `Object.keys` returns — the canonical prototype-pollution
-// merge vector. Skip these unconditionally on both the write and the
-// stale-key-removal pass.
-const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
-
-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 {
-  // The `seen` set is keyed on `source`, not `target` — protects against
-  // CIRCULAR references in the source tree (avoids infinite recursion). A
-  // consequence: DIAMOND-shaped sources (the SAME nested object referenced
-  // from two different parent paths in `source`) only get reconciled into
-  // their FIRST encountered position in `target`. The second occurrence is
-  // skipped. This is intentional — reconcile assumes source is a tree, not
-  // a DAG. Pass distinct object references (or deep-clone before reconcile)
-  // if your source is a DAG.
-  if (seen.has(source)) return
-  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) {
-    if (DANGEROUS_KEYS.has(key)) continue
-    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) {
-    if (DANGEROUS_KEYS.has(key)) continue
-    delete target[key]
-  }
-}

package/src/resource.ts

@@ -1,84 +0,0 @@
-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
-  /**
-   * Stop the source-tracking effect. After dispose(), source changes no
-   * longer trigger fetches and any in-flight response is ignored. Idempotent.
-   * Required for resources created outside an `EffectScope` to avoid leaking
-   * the source-tracking effect for the lifetime of the program.
-   */
-  dispose(): 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)
-      })
-  }
-
-  let disposed = false
-  const sourceEffect = effect(() => {
-    const param = source()
-    runUntracked(() => doFetch(param))
-  })
-
-  return {
-    data,
-    loading,
-    error,
-    refetch() {
-      if (disposed) return
-      runUntracked(() => doFetch(source()))
-    },
-    dispose() {
-      if (disposed) return
-      disposed = true
-      // Bump requestId so any pending in-flight response is treated as stale
-      // and discarded by the .then/.catch handlers — prevents post-dispose
-      // writes to data/loading/error.
-      requestId++
-      sourceEffect.dispose()
-    },
-  }
-}

package/src/scope.ts

@@ -1,123 +0,0 @@
-// 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 }[] | null = null
-  private _active = true
-  private _updateHooks: (() => void)[] | null = null
-  private _updatePending = false
-
-  /** Register an effect/computed to be disposed when this scope stops. */
-  add(e: { dispose(): void }): void {
-    if (!this._active) return
-    if (this._effects === null) this._effects = []
-    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 {
-    // Mirror `add()`'s behavior: silently no-op when scope is stopped.
-    // Without this, hooks pushed after `stop()` would leak into a freshly-
-    // allocated `_updateHooks` array and never fire (because `notifyEffectRan`
-    // checks `_active` first), giving the caller no feedback that the
-    // registration was futile.
-    if (!this._active) return
-    if (this._updateHooks === null) this._updateHooks = []
-    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 || this._updateHooks.length === 0 || this._updatePending) return
-    this._updatePending = true
-    queueMicrotask(() => {
-      this._updatePending = false
-      if (!this._active || !this._updateHooks) 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
-    if (this._effects) {
-      for (const e of this._effects) e.dispose()
-    }
-    this._effects = null
-    this._updateHooks = null
-    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()
-}
-
-/**
- * Register a callback to run when the current `EffectScope` stops. Vue 3
- * parity. Must be called inside `scope.runInScope(fn)` — the registration
- * captures the ambient scope, so calling outside any scope is a no-op (with
- * a dev warning to surface the missing scope).
- *
- * Use to clean up resources tied to a scope's lifetime: timers, listeners,
- * external subscriptions. Equivalent to calling `getCurrentScope()?.add({
- * dispose: fn })` but with the scope capture handled.
- *
- * @example
- * scope.runInScope(() => {
- *   const ws = new WebSocket(url)
- *   onScopeDispose(() => ws.close())
- *   // ws.close() runs when scope.stop() is called
- * })
- */
-export function onScopeDispose(fn: () => void): void {
-  const scope = _currentScope
-  if (!scope) {
-    if (process.env.NODE_ENV !== 'production') {
-      // oxlint-disable-next-line no-console
-      console.warn(
-        '[pyreon] onScopeDispose() called without an active EffectScope — callback will never run. ' +
-          'Wrap the call in `scope.runInScope(() => { ... })` or check `getCurrentScope()` before calling.',
-      )
-    }
-    return
-  }
-  scope.add({ dispose: fn })
-}

package/src/signal.ts

@@ -1,261 +0,0 @@
-import { batch, enqueuePendingNotification, isBatching } from './batch'
-import { _notifyTraceListeners, isTracing } from './debug'
-import { _captureCallerLocation, _rdRecordFire, _rdRegister } from './reactive-devtools'
-import { _recordSignalWrite } from './reactive-trace'
-import { notifySubscribers, trackSubscriber } 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 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
-}
-
-/**
- * Read-only reactive value — the common interface that both Signal and Computed satisfy.
- * Use this as the parameter type when a function only needs to read a reactive value.
- */
-export type ReadonlySignal<T> = () => T
-
-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
-  /**
-   * Register a direct updater — even lighter than subscribe().
-   * Intended for compiler-emitted DOM bindings (_bindText, _bindDirect).
-   * Returns a disposer that removes the updater (O(1)); the live set
-   * stays bounded under register/dispose churn.
-   */
-  direct(updater: () => void): () => void
-  /**
-   * Debug name — useful for devtools and logging. Set via the `name` option at
-   * creation; can be reassigned at any time (`s.label = 'renamed'`) since it's
-   * stored as a regular own property on the signal function.
-   */
-  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 — 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 signal 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 }
-}
-
-// 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 direct updater set — compiler-emitted DOM updaters (lazily allocated) */
-  _d: Set<() => void> | null
-  peek(): T
-  set(value: T): void
-  update(fn: (current: T) => T): void
-  subscribe(listener: () => void): () => void
-  /** Register a direct updater — lighter than subscribe; O(1) set-based disposal. */
-  direct(updater: () => 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
-  if (process.env.NODE_ENV !== 'production')
-    _countSink.__pyreon_count__?.('reactivity.signalWrite')
-  const prev = this._v
-  this._v = newValue
-  // Dev-only bounded ring buffer of recent writes — attached to error
-  // reports so a crash carries the causal sequence of signal changes,
-  // not just the thrown value. Tree-shaken in prod via the gate.
-  // Deliberately separate from the `isTracing()` path below: that one
-  // is opt-in (requires an onSignalUpdate listener) and captures a
-  // stack (expensive); this is always-on in dev and intentionally
-  // cheap (string preview, no stack).
-  if (process.env.NODE_ENV !== 'production') {
-    _recordSignalWrite(this.label, prev, newValue)
-    _rdRecordFire(this)
-  }
-  if (isTracing()) {
-    // Trace listeners are user-supplied debug code that fires on every
-    // signal write. A throwing listener here would leave `_v` updated but
-    // subscribers never notified (state divergence: readers see the new
-    // value, but no effects run). Trace failures must not corrupt program
-    // state — wrap in try/catch and route through `_userErrorHandler` so
-    // the corruption is at least visible. Listeners are removed via the
-    // disposer returned by `onSignalUpdate`; this catch prevents one bad
-    // listener from breaking unrelated reactive flow.
-    try {
-      _notifyTraceListeners(this as unknown as Signal<unknown>, prev, newValue)
-    } catch (err) {
-      if (process.env.NODE_ENV !== 'production') {
-        // oxlint-disable-next-line no-console
-        console.error(
-          '[pyreon] signal trace listener threw — listener is buggy. Subscribers continue uninterrupted.',
-          err,
-        )
-      }
-    }
-  }
-  // Auto-batch the notification chain. Without this, a diamond dependency
-  // graph (a → b, c → d → effect) fires the apex effect TWICE per write
-  // because subscribers cascade inline: the first path through `b` reaches
-  // `effect`, whose read clears `d`'s dirty flag; then `c`'s notification
-  // re-dirties `d` and re-notifies `effect`. Wrapping the notify chain in
-  // `batch()` routes cascade-notifications through the pending Set, which
-  // dedupes on `d.recompute` and on `effect.run`.
-  //
-  // The batch is synchronous — observable behaviour is unchanged for the
-  // common case (subscribers still fire immediately after the write). Only
-  // the dedup semantics change, which is a bug fix.
-  //
-  // Short-circuit when already inside a batch so we don't wrap redundantly.
-  if (isBatching()) {
-    if (this._d) notifyDirect(this._d)
-    if (this._s) notifySubscribers(this._s)
-  } else {
-    batch(() => {
-      if (this._d) notifyDirect(this._d)
-      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)
-}
-
-/**
- * Register a direct updater — lighter than subscribe().
- * Used by compiler-emitted _bindText/_bindDirect for zero-overhead DOM bindings.
- *
- * Backed by a `Set` (same as `_s`), NOT a flat array. The array form
- * disposed by nulling the slot (`arr[idx] = null`) but never compacted —
- * so a long-lived signal (theme/locale/auth, or a signal read inside
- * `<For>` rows) bound by churning components accumulated one permanent
- * dead slot per ever-mounted binding. That is an app-lifetime memory
- * leak AND degrades the signal-write hot path: `notifyDirect` iterated
- * O(total-ever-registered), not O(live). A Set bounds growth to the live
- * set and keeps disposal + iteration O(live); the "Set.delete overhead"
- * the array form optimised for is negligible against an unbounded array.
- */
-function _directFn(this: SignalFn<unknown>, updater: () => void): () => void {
-  if (!this._d) this._d = new Set()
-  const set = this._d
-  set.add(updater)
-  return () => {
-    set.delete(updater)
-  }
-}
-
-/**
- * Notify direct updaters — set iteration, batch-aware. Disposed updaters
- * are already absent from the set (O(1) delete on disposal).
- */
-function notifyDirect(updaters: Set<() => void>): void {
-  if (isBatching()) {
-    for (const fn of updaters) enqueuePendingNotification(fn)
-  } else {
-    for (const fn of updaters) fn()
-  }
-}
-
-function _debug(this: SignalFn<unknown>): SignalDebugInfo<unknown> {
-  return {
-    name: this.label,
-    value: this._v,
-    subscriberCount: this._s?.size ?? 0,
-  }
-}
-
-/**
- * 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> {
-  if (process.env.NODE_ENV !== 'production')
-    _countSink.__pyreon_count__?.('reactivity.signalCreate')
-  // The read function is the only per-signal closure.
-  // It doubles as the SubscriberHost (_s property) for trackSubscriber.
-  const read = ((...args: unknown[]) => {
-    if (process.env.NODE_ENV !== 'production' && args.length > 0) {
-      // oxlint-disable-next-line no-console
-      console.warn(
-        '[Pyreon] signal() was called with an argument. ' +
-          'Use signal.set(value) or signal.update(fn) to write. ' +
-          'signal(value) only reads — the argument is ignored.',
-      )
-    }
-    trackSubscriber(read as SignalFn<T>)
-    return read._v
-  }) as unknown as SignalFn<T>
-
-  read._v = initialValue
-  read._s = null
-  read._d = null
-  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.direct = _directFn as (updater: () => void) => () => void
-  read.debug = _debug as () => SignalDebugInfo<T>
-  read.label = options?.name
-
-  if (process.env.NODE_ENV !== 'production') {
-    // Prefer build-time-injected location (zero runtime cost) over the
-    // ~2.2µs stack-capture fallback. @pyreon/vite-plugin's
-    // `injectSignalLocations` rewrites `signal(0)` to
-    // `signal(0, { __sourceLocation: {...} })` at transform time so most
-    // dev-mode signals never pay the stack-capture cost.
-    const loc = options?.__sourceLocation
-      ? options.__sourceLocation
-      : _captureCallerLocation(1)
-    _rdRegister(read, 'signal', read, null, read.label, loc)
-  }
-
-  return read as unknown as Signal<T>
-}