@bquery/bquery 1.2.0 → 1.3.0

package/src/reactive/core.ts

@@ -0,0 +1,93 @@
+/**
+ * Core reactive signals.
+ */
+
+import {
+  getCurrentObserver,
+  registerDependency,
+  scheduleObserver,
+  type ReactiveSource,
+} from './internals';
+
+/**
+ * A reactive value container that notifies subscribers on change.
+ *
+ * Signals are the foundational primitive of the reactive system.
+ * Reading a signal's value inside an effect or computed automatically
+ * establishes a reactive dependency.
+ *
+ * @template T - The type of the stored value
+ */
+export class Signal<T> implements ReactiveSource {
+  private subscribers = new Set<() => void>();
+
+  /**
+   * Creates a new signal with an initial value.
+   * @param _value - The initial value
+   */
+  constructor(private _value: T) {}
+
+  /**
+   * Gets the current value and tracks the read if inside an observer.
+   * During untrack calls, getCurrentObserver returns undefined, preventing dependency tracking.
+   */
+  get value(): T {
+    const current = getCurrentObserver();
+    if (current) {
+      this.subscribers.add(current);
+      registerDependency(current, this);
+    }
+    return this._value;
+  }
+
+  /**
+   * Sets a new value and notifies all subscribers if the value changed.
+   * Uses Object.is for equality comparison.
+   */
+  set value(next: T) {
+    if (Object.is(this._value, next)) return;
+    this._value = next;
+    // Create snapshot to avoid issues with subscribers modifying the set during iteration
+    const subscribersSnapshot = Array.from(this.subscribers);
+    for (const subscriber of subscribersSnapshot) {
+      scheduleObserver(subscriber);
+    }
+  }
+
+  /**
+   * Reads the current value without tracking.
+   * Useful when you need the value but don't want to create a dependency.
+   *
+   * @returns The current value
+   */
+  peek(): T {
+    return this._value;
+  }
+
+  /**
+   * Updates the value using a function.
+   * Useful for updates based on the current value.
+   *
+   * @param updater - Function that receives current value and returns new value
+   */
+  update(updater: (current: T) => T): void {
+    this.value = updater(this._value);
+  }
+
+  /**
+   * Removes an observer from this signal's subscriber set.
+   * @internal
+   */
+  unsubscribe(observer: () => void): void {
+    this.subscribers.delete(observer);
+  }
+}
+
+/**
+ * Creates a new reactive signal.
+ *
+ * @template T - The type of the signal value
+ * @param value - The initial value
+ * @returns A new Signal instance
+ */
+export const signal = <T>(value: T): Signal<T> => new Signal(value);

package/src/reactive/effect.ts

@@ -0,0 +1,43 @@
+/**
+ * Reactive effects.
+ */
+
+import { CleanupFn, Observer, track, clearDependencies } from './internals';
+
+/**
+ * Creates a side effect that automatically re-runs when dependencies change.
+ *
+ * The effect runs immediately upon creation and then re-runs whenever
+ * any signal or computed value read inside it changes.
+ *
+ * @param fn - The effect function to run
+ * @returns A cleanup function to stop the effect
+ */
+export const effect = (fn: () => void | CleanupFn): CleanupFn => {
+  let cleanupFn: CleanupFn | void;
+  let isDisposed = false;
+
+  const observer: Observer = () => {
+    if (isDisposed) return;
+
+    if (cleanupFn) {
+      cleanupFn();
+    }
+
+    // Clear old dependencies before running to avoid stale subscriptions
+    clearDependencies(observer);
+
+    cleanupFn = track(observer, fn);
+  };
+
+  observer();
+
+  return () => {
+    isDisposed = true;
+    if (cleanupFn) {
+      cleanupFn();
+    }
+    // Clean up all dependencies when effect is disposed
+    clearDependencies(observer);
+  };
+};

package/src/reactive/index.ts

@@ -1,22 +1,23 @@
-/**
- * Reactive module providing fine-grained reactivity primitives.
- *
- * @module bquery/reactive
- */
-
-export {
-  Computed,
-  Signal,
-  batch,
-  computed,
-  effect,
-  isComputed,
-  isSignal,
-  persistedSignal,
-  readonly,
-  signal,
-  untrack,
-  watch,
-} from './signal';
-
-export type { CleanupFn, Observer, ReadonlySignal } from './signal';
+/**
+ * Reactive module providing fine-grained reactivity primitives.
+ *
+ * @module bquery/reactive
+ */
+
+export {
+  Computed,
+  Signal,
+  batch,
+  computed,
+  effect,
+  isComputed,
+  isSignal,
+  linkedSignal,
+  persistedSignal,
+  readonly,
+  signal,
+  untrack,
+  watch,
+} from './signal';
+
+export type { CleanupFn, LinkedSignal, Observer, ReadonlySignal } from './signal';

package/src/reactive/internals.ts

@@ -0,0 +1,105 @@
+/**
+ * Internal reactive plumbing shared across primitives.
+ * @internal
+ */
+
+export type Observer = () => void;
+export type CleanupFn = () => void;
+
+/**
+ * Interface for reactive sources (Signals, Computed) that can unsubscribe observers.
+ * @internal
+ */
+export interface ReactiveSource {
+  unsubscribe(observer: Observer): void;
+}
+
+const observerStack: Observer[] = [];
+let batchDepth = 0;
+const pendingObservers = new Set<Observer>();
+
+// Track dependencies for each observer to enable cleanup
+const observerDependencies = new WeakMap<Observer, Set<ReactiveSource>>();
+
+export const track = <T>(observer: Observer, fn: () => T): T => {
+  observerStack.push(observer);
+  try {
+    return fn();
+  } finally {
+    observerStack.pop();
+  }
+};
+
+export const getCurrentObserver = (): Observer | undefined =>
+  observerStack[observerStack.length - 1];
+
+/**
+ * Executes a function without exposing the current observer to dependencies.
+ * Unlike disabling tracking globally, this still allows nested reactive internals
+ * (e.g., computed recomputation) to track their own dependencies.
+ * @internal
+ */
+export const withoutCurrentObserver = <T>(fn: () => T): T => {
+  // Push undefined to temporarily "hide" the current observer
+  // This way, Signal.value reads won't link to the previous observer,
+  // but nested track() calls (e.g., computed recompute) still work normally.
+  observerStack.push(undefined as unknown as Observer);
+  try {
+    return fn();
+  } finally {
+    observerStack.pop();
+  }
+};
+
+export const scheduleObserver = (observer: Observer): void => {
+  if (batchDepth > 0) {
+    pendingObservers.add(observer);
+    return;
+  }
+  observer();
+};
+
+const flushObservers = (): void => {
+  for (const observer of Array.from(pendingObservers)) {
+    pendingObservers.delete(observer);
+    observer();
+  }
+};
+
+export const beginBatch = (): void => {
+  batchDepth += 1;
+};
+
+export const endBatch = (): void => {
+  batchDepth -= 1;
+  if (batchDepth === 0) {
+    flushObservers();
+  }
+};
+
+/**
+ * Registers a dependency between an observer and a reactive source.
+ * @internal
+ */
+export const registerDependency = (observer: Observer, source: ReactiveSource): void => {
+  let deps = observerDependencies.get(observer);
+  if (!deps) {
+    deps = new Set();
+    observerDependencies.set(observer, deps);
+  }
+  deps.add(source);
+};
+
+/**
+ * Clears all dependencies for an observer, unsubscribing from all sources.
+ * @internal
+ */
+export const clearDependencies = (observer: Observer): void => {
+  const deps = observerDependencies.get(observer);
+  if (deps) {
+    for (const source of deps) {
+      source.unsubscribe(observer);
+    }
+    deps.clear();
+  }
+};

package/src/reactive/linked.ts

@@ -0,0 +1,56 @@
+/**
+ * Linked (writable) computed helpers.
+ */
+
+import { computed, Computed } from './computed';
+
+/**
+ * A writable computed-like signal.
+ */
+export interface LinkedSignal<T> {
+  /** Gets or sets the current value with dependency tracking. */
+  value: T;
+  /** Gets the current value without dependency tracking. */
+  peek(): T;
+}
+
+/**
+ * Creates a writable computed signal by linking a getter and setter.
+ *
+ * @template T - The derived value type
+ * @param getValue - Getter that derives the current value
+ * @param setValue - Setter that writes back to underlying signals
+ * @returns A writable computed-like signal
+ *
+ * @example
+ * ```ts
+ * const first = signal('Ada');
+ * const last = signal('Lovelace');
+ * const fullName = linkedSignal(
+ *   () => `${first.value} ${last.value}`,
+ *   (next) => {
+ *     const [a, b] = next.split(' ');
+ *     first.value = a ?? '';
+ *     last.value = b ?? '';
+ *   }
+ * );
+ * ```
+ */
+export const linkedSignal = <T>(
+  getValue: () => T,
+  setValue: (value: T) => void
+): LinkedSignal<T> => {
+  const derived: Computed<T> = computed(getValue);
+
+  return {
+    get value(): T {
+      return derived.value;
+    },
+    set value(next: T) {
+      setValue(next);
+    },
+    peek(): T {
+      return derived.peek();
+    },
+  };
+};

package/src/reactive/persisted.ts

@@ -0,0 +1,74 @@
+/**
+ * LocalStorage-backed signals.
+ */
+
+import { signal, Signal } from './core';
+import { effect } from './effect';
+
+/**
+ * Creates a signal that persists to localStorage.
+ *
+ * @template T - The type of the signal value
+ * @param key - The localStorage key
+ * @param initialValue - The initial value if not found in storage
+ * @returns A Signal that syncs with localStorage (falls back to in-memory if unavailable)
+ */
+export const persistedSignal = <T>(key: string, initialValue: T): Signal<T> => {
+  // Check if localStorage is available and accessible
+  let hasLocalStorage = false;
+  let storage: Storage | null = null;
+
+  try {
+    // In Safari private mode, accessing localStorage can throw SecurityError
+    storage = globalThis.localStorage;
+    if (storage) {
+      // Test actual access to ensure it's not just present but usable
+      // Use a randomized test key to avoid overwriting real user data
+      const testKey = `__bquery_test_${Math.random().toString(36).slice(2, 9)}__`;
+      const testValue = '__test__';
+      try {
+        storage.setItem(testKey, testValue);
+        storage.getItem(testKey);
+        hasLocalStorage = true;
+      } finally {
+        // Ensure we don't leave any test data behind
+        try {
+          storage.removeItem(testKey);
+        } catch {
+          // Ignore cleanup errors (e.g., storage becoming unavailable)
+        }
+      }
+    }
+  } catch {
+    // localStorage unavailable or access denied (Safari private mode, sandboxed iframes, etc.)
+    hasLocalStorage = false;
+  }
+
+  let stored: T = initialValue;
+
+  if (hasLocalStorage && storage) {
+    try {
+      const raw = storage.getItem(key);
+      if (raw !== null) {
+        stored = JSON.parse(raw) as T;
+      }
+    } catch {
+      // Use initial value on parse error or access denial
+    }
+  }
+
+  const sig = signal(stored);
+
+  // Only set up persistence effect if localStorage is available
+  if (hasLocalStorage && storage) {
+    effect(() => {
+      try {
+        storage!.setItem(key, JSON.stringify(sig.value));
+      } catch {
+        // Ignore storage errors (quota exceeded, sandboxed iframes, etc.)
+      }
+    });
+  }
+
+  return sig;
+};

package/src/reactive/readonly.ts

@@ -0,0 +1,35 @@
+/**
+ * Read-only signal wrappers.
+ */
+
+import type { Signal } from './core';
+
+/**
+ * A readonly wrapper around a signal that prevents writes.
+ * Provides read-only access to a signal's value while maintaining reactivity.
+ *
+ * @template T - The type of the wrapped value
+ */
+export interface ReadonlySignal<T> {
+  /** Gets the current value with dependency tracking. */
+  readonly value: T;
+  /** Gets the current value without dependency tracking. */
+  peek(): T;
+}
+
+/**
+ * Creates a read-only view of a signal.
+ * Useful for exposing reactive state without allowing modifications.
+ *
+ * @template T - The type of the signal value
+ * @param sig - The signal to wrap
+ * @returns A readonly signal wrapper
+ */
+export const readonly = <T>(sig: Signal<T>): ReadonlySignal<T> => ({
+  get value(): T {
+    return sig.value;
+  },
+  peek(): T {
+    return sig.peek();
+  },
+});