@pyreon/reactivity 0.1.0

package/lib/types/index.d.ts

@@ -0,0 +1,725 @@
+function batch(fn) {
+  batchDepth++;
+  try {
+    fn();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0) {
+      const flush = pendingNotifications;
+      pendingNotifications = /* @__PURE__ */new Set();
+      for (const notify of flush) notify();
+    }
+  }
+}
+function isBatching() {
+  return batchDepth > 0;
+}
+function enqueuePendingNotification(notify) {
+  pendingNotifications.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
+*/
+function nextTick() {
+  return new Promise(resolve => queueMicrotask(resolve));
+}
+
+//#endregion
+//#region src/cell.ts
+/**
+* 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.
+*/
+
+function cell(value) {
+  return new Cell(value);
+}
+
+//#endregion
+//#region src/scope.ts
+
+function getCurrentScope() {
+  return _currentScope;
+}
+function setCurrentScope(scope) {
+  _currentScope = scope;
+}
+/** Create a new EffectScope. */
+function effectScope() {
+  return new EffectScope();
+}
+
+//#endregion
+//#region src/tracking.ts
+
+function setDepsCollector(collector) {
+  _depsCollector = collector;
+}
+/**
+* Register the active effect as a subscriber of the given reactive source.
+* The subscriber Set is created lazily on the host — sources read only outside
+* effects never allocate a Set.
+*/
+function trackSubscriber(host) {
+  if (activeEffect) {
+    if (!host._s) host._s = /* @__PURE__ */new Set();
+    const subscribers = host._s;
+    subscribers.add(activeEffect);
+    if (_depsCollector) _depsCollector.push(subscribers);else {
+      let deps = effectDeps.get(activeEffect);
+      if (!deps) {
+        deps = /* @__PURE__ */new Set();
+        effectDeps.set(activeEffect, deps);
+      }
+      deps.add(subscribers);
+    }
+  }
+}
+/**
+* Remove an effect from every subscriber set it was registered in,
+* then clear its dep record. Call this before each re-run and on dispose.
+*/
+function cleanupEffect(fn) {
+  const deps = effectDeps.get(fn);
+  if (deps) {
+    for (const sub of deps) sub.delete(fn);
+    deps.clear();
+  }
+}
+function notifySubscribers(subscribers) {
+  if (subscribers.size === 0) return;
+  if (subscribers.size === 1) {
+    const sub = subscribers.values().next().value;
+    if (isBatching()) enqueuePendingNotification(sub);else sub();
+    return;
+  }
+  if (isBatching()) for (const sub of subscribers) enqueuePendingNotification(sub);else for (const sub of [...subscribers]) sub();
+}
+function withTracking(fn, compute) {
+  const prev = activeEffect;
+  activeEffect = fn;
+  try {
+    return compute();
+  } finally {
+    activeEffect = prev;
+  }
+}
+function runUntracked(fn) {
+  const prev = activeEffect;
+  activeEffect = null;
+  try {
+    return fn();
+  } finally {
+    activeEffect = prev;
+  }
+}
+
+//#endregion
+//#region src/computed.ts
+function computed(fn, options) {
+  let value;
+  let dirty = true;
+  let initialized = false;
+  let disposed = false;
+  const customEquals = options?.equals;
+  const host = {
+    _s: null
+  };
+  const recompute = () => {
+    if (disposed) return;
+    cleanupEffect(recompute);
+    if (customEquals) {
+      const next = withTracking(recompute, fn);
+      if (initialized && customEquals(value, next)) return;
+      value = next;
+      dirty = false;
+      initialized = true;
+      if (host._s) notifySubscribers(host._s);
+    } else {
+      dirty = true;
+      if (host._s) notifySubscribers(host._s);
+    }
+  };
+  const read = () => {
+    trackSubscriber(host);
+    if (dirty) {
+      value = withTracking(recompute, fn);
+      dirty = false;
+      initialized = true;
+    }
+    return value;
+  };
+  read.dispose = () => {
+    disposed = true;
+    cleanupEffect(recompute);
+  };
+  getCurrentScope()?.add({
+    dispose: read.dispose
+  });
+  return read;
+}
+
+//#endregion
+//#region src/effect.ts
+
+function setErrorHandler(fn) {
+  _errorHandler = fn;
+}
+function effect(fn) {
+  const scope = getCurrentScope();
+  let disposed = false;
+  let isFirstRun = true;
+  let cleanup;
+  const runCleanup = () => {
+    if (typeof cleanup === "function") {
+      try {
+        cleanup();
+      } catch (err) {
+        _errorHandler(err);
+      }
+      cleanup = void 0;
+    }
+  };
+  const run = () => {
+    if (disposed) return;
+    runCleanup();
+    cleanupEffect(run);
+    try {
+      cleanup = withTracking(run, fn) || void 0;
+    } catch (err) {
+      _errorHandler(err);
+    }
+    if (!isFirstRun) scope?.notifyEffectRan();
+    isFirstRun = false;
+  };
+  run();
+  const e = {
+    dispose() {
+      runCleanup();
+      disposed = true;
+      cleanupEffect(run);
+    }
+  };
+  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
+*/
+function _bind(fn) {
+  const deps = [];
+  let disposed = false;
+  const run = () => {
+    if (disposed) return;
+    fn();
+  };
+  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;
+  };
+  getCurrentScope()?.add({
+    dispose
+  });
+  return dispose;
+}
+function renderEffect(fn) {
+  const deps = [];
+  let disposed = false;
+  const run = () => {
+    if (disposed) return;
+    for (const s of deps) s.delete(run);
+    deps.length = 0;
+    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;
+  };
+  getCurrentScope()?.add({
+    dispose
+  });
+  return dispose;
+}
+
+//#endregion
+//#region src/createSelector.ts
+/**
+* Create an equality selector — returns a reactive predicate that is true
+* only for the currently selected value.
+*
+* Unlike a plain `() => source() === value`, this only triggers the TWO
+* affected subscribers (deselected + newly selected) instead of ALL
+* subscribers, making selection O(1) regardless of list size.
+*
+* @example
+* const isSelected = createSelector(selectedId)
+* // In each row:
+* class: () => (isSelected(row.id) ? "selected" : "")
+*/
+function createSelector(source) {
+  const subs = /* @__PURE__ */new Map();
+  let current;
+  let initialized = false;
+  effect(() => {
+    const next = source();
+    if (!initialized) {
+      initialized = true;
+      current = next;
+      return;
+    }
+    if (Object.is(next, current)) return;
+    const old = current;
+    current = next;
+    const oldBucket = subs.get(old);
+    const newBucket = subs.get(next);
+    if (oldBucket) for (const fn of [...oldBucket]) fn();
+    if (newBucket) for (const fn of [...newBucket]) fn();
+  });
+  const hosts = /* @__PURE__ */new Map();
+  return value => {
+    let host = hosts.get(value);
+    if (!host) {
+      let bucket = subs.get(value);
+      if (!bucket) {
+        bucket = /* @__PURE__ */new Set();
+        subs.set(value, bucket);
+      }
+      host = {
+        _s: bucket
+      };
+      hosts.set(value, host);
+    }
+    trackSubscriber(host);
+    return Object.is(current, value);
+  };
+}
+
+//#endregion
+//#region src/debug.ts
+
+/**
+* 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}`)
+* })
+*/
+function onSignalUpdate(listener) {
+  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 */
+function _notifyTraceListeners(sig, prev, next) {
+  if (!_traceListeners) return;
+  const event = {
+    signal: sig,
+    name: sig.label,
+    prev,
+    next,
+    stack: (/* @__PURE__ */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) */
+function isTracing() {
+  return _traceListeners !== null;
+}
+/**
+* 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)
+*/
+function why() {
+  if (_whyActive) return;
+  _whyActive = true;
+  _whyLog = [];
+  const dispose = onSignalUpdate(e => {
+    const _subCount = e.signal._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
+    });
+  });
+  queueMicrotask(() => {
+    dispose();
+    if (_whyLog.length === 0) console.log("[pyreon:why] No signal updates detected");
+    _whyActive = false;
+    _whyLog = [];
+  });
+}
+/**
+* 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
+*/
+function inspectSignal(sig) {
+  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;
+}
+
+//#endregion
+//#region src/signal.ts
+function _peek() {
+  return this._v;
+}
+function _set(newValue) {
+  if (Object.is(this._v, newValue)) return;
+  const prev = this._v;
+  this._v = newValue;
+  if (isTracing()) _notifyTraceListeners(this, prev, newValue);
+  if (this._s) notifySubscribers(this._s);
+}
+function _update(fn) {
+  _set.call(this, fn(this._v));
+}
+function _subscribe(listener) {
+  if (!this._s) this._s = /* @__PURE__ */new Set();
+  this._s.add(listener);
+  return () => this._s?.delete(listener);
+}
+function _debug() {
+  return {
+    name: this._n,
+    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.
+*/
+function signal(initialValue, options) {
+  const read = () => {
+    trackSubscriber(read);
+    return read._v;
+  };
+  read._v = initialValue;
+  read._s = null;
+  read._n = options?.name;
+  read.peek = _peek;
+  read.set = _set;
+  read.update = _update;
+  read.subscribe = _subscribe;
+  read.debug = _debug;
+  Object.defineProperty(read, "label", _labelDescriptor);
+  return read;
+}
+
+//#endregion
+//#region src/store.ts
+/**
+* createStore — deep reactive Proxy store.
+*
+* Wraps a plain object/array in a Proxy that creates a fine-grained signal for
+* every property. Direct mutations (`store.count++`, `store.items[0].label = "x"`)
+* trigger only the signals for the mutated properties — not the whole tree.
+*
+* @example
+* const state = createStore({ count: 0, items: [{ id: 1, text: "hello" }] })
+*
+* effect(() => console.log(state.count))  // tracks state.count only
+* state.count++                           // only the count effect re-runs
+* state.items[0].text = "world"           // only text-tracking effects re-run
+*/
+
+/** Returns true if the value is a createStore proxy. */
+function isStore(value) {
+  return value !== null && typeof value === "object" && value[IS_STORE] === true;
+}
+/**
+* Create a deep reactive store from a plain object or array.
+* Returns a proxy — mutations to the proxy trigger fine-grained reactive updates.
+*/
+function createStore(initial) {
+  return wrap(initial);
+}
+function wrap(raw) {
+  const cached = proxyCache.get(raw);
+  if (cached) return cached;
+  const propSignals = /* @__PURE__ */new Map();
+  const isArray = Array.isArray(raw);
+  const lengthSig = isArray ? signal(raw.length) : null;
+  function getOrCreateSignal(key) {
+    if (!propSignals.has(key)) propSignals.set(key, signal(raw[key]));
+    return propSignals.get(key);
+  }
+  const proxy = new Proxy(raw, {
+    get(target, key) {
+      if (key === IS_STORE) return true;
+      if (typeof key === "symbol") return target[key];
+      if (isArray && key === "length") return lengthSig?.();
+      if (!Object.hasOwn(target, key)) return target[key];
+      const value = getOrCreateSignal(key)();
+      if (value !== null && typeof value === "object") return wrap(value);
+      return value;
+    },
+    set(target, key, value) {
+      if (typeof key === "symbol") {
+        target[key] = value;
+        return true;
+      }
+      const prevLength = isArray ? target.length : 0;
+      target[key] = value;
+      if (isArray && key === "length") {
+        lengthSig?.set(value);
+        return true;
+      }
+      if (propSignals.has(key)) propSignals.get(key)?.set(value);else propSignals.set(key, signal(value));
+      if (isArray && target.length !== prevLength) lengthSig?.set(target.length);
+      return true;
+    },
+    deleteProperty(target, key) {
+      delete target[key];
+      if (typeof key !== "symbol" && propSignals.has(key)) {
+        propSignals.get(key)?.set(void 0);
+        propSignals.delete(key);
+      }
+      if (isArray) lengthSig?.set(target.length);
+      return true;
+    },
+    has(target, key) {
+      return Reflect.has(target, key);
+    },
+    ownKeys(target) {
+      return Reflect.ownKeys(target);
+    },
+    getOwnPropertyDescriptor(target, key) {
+      return Reflect.getOwnPropertyDescriptor(target, key);
+    }
+  });
+  proxyCache.set(raw, proxy);
+  return proxy;
+}
+
+//#endregion
+//#region src/reconcile.ts
+/**
+* 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.
+*/
+function reconcile(source, target) {
+  _reconcileInner(source, target, /* @__PURE__ */new WeakSet());
+}
+function _reconcileInner(source, target, seen) {
+  if (seen.has(source)) return;
+  seen.add(source);
+  if (Array.isArray(source) && Array.isArray(target)) _reconcileArray(source, target, seen);else _reconcileObject(source, target, seen);
+}
+function _reconcileArray(source, target, seen) {
+  const targetLen = target.length;
+  const sourceLen = source.length;
+  for (let i = 0; i < sourceLen; i++) {
+    const sv = source[i];
+    const tv = target[i];
+    if (i < targetLen && sv !== null && typeof sv === "object" && tv !== null && typeof tv === "object") _reconcileInner(sv, tv, seen);else target[i] = sv;
+  }
+  if (targetLen > sourceLen) target.length = sourceLen;
+}
+function _reconcileObject(source, target, seen) {
+  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)) _reconcileInner(sv, tv, seen);else target[key] = sv;
+    } else target[key] = sv;
+    targetKeys.delete(key);
+  }
+  for (const key of targetKeys) delete target[key];
+}
+
+//#endregion
+//#region src/resource.ts
+/**
+* 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
+*/
+function createResource(source, fetcher) {
+  const data = signal(void 0);
+  const loading = signal(false);
+  const error = signal(void 0);
+  let requestId = 0;
+  const doFetch = param => {
+    const id = ++requestId;
+    loading.set(true);
+    error.set(void 0);
+    fetcher(param).then(result => {
+      if (id !== requestId) return;
+      data.set(result);
+      loading.set(false);
+    }).catch(err => {
+      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()));
+    }
+  };
+}
+
+//#endregion
+//#region src/watch.ts
+/**
+* Watch a reactive source and run a callback whenever it changes.
+*
+* Returns a stop function that disposes the watcher.
+*
+* The callback receives (newValue, oldValue). On the first call (when
+* `immediate` is true) oldValue is `undefined`.
+*
+* The callback may return a cleanup function that is called before each
+* re-run and on stop — useful for cancelling async work.
+*
+* @example
+* const stop = watch(
+*   () => userId(),
+*   async (id, prev) => {
+*     const data = await fetch(`/api/user/${id}`)
+*     setUser(await data.json())
+*   },
+* )
+* // Later: stop()
+*/
+function watch(source, callback, opts = {}) {
+  let oldVal;
+  let isFirst = true;
+  let cleanupFn;
+  const e = effect(() => {
+    const newVal = source();
+    if (isFirst) {
+      isFirst = false;
+      oldVal = newVal;
+      if (opts.immediate) {
+        const result = callback(newVal, void 0);
+        if (typeof result === "function") cleanupFn = result;
+      }
+      return;
+    }
+    if (cleanupFn) {
+      cleanupFn();
+      cleanupFn = void 0;
+    }
+    const result = callback(newVal, oldVal);
+    if (typeof result === "function") cleanupFn = result;
+    oldVal = newVal;
+  });
+  return () => {
+    e.dispose();
+    if (cleanupFn) {
+      cleanupFn();
+      cleanupFn = void 0;
+    }
+  };
+}
+
+//#endregion
+export { Cell, EffectScope, _bind, batch, cell, computed, createResource, createSelector, createStore, effect, effectScope, getCurrentScope, inspectSignal, isStore, nextTick, onSignalUpdate, reconcile, renderEffect, runUntracked, setCurrentScope, setErrorHandler, signal, watch, why };
+//# sourceMappingURL=index.d.ts.map