@bquery/bquery 1.2.0 → 1.4.0

package/src/platform/storage.ts

@@ -1,208 +1,215 @@
-/**
- * Unified storage adapters for web platform storage APIs.
- * Provides a consistent, promise-based interface with predictable errors.
- */
-
-/**
- * Common interface for all storage adapters.
- * All methods return promises for a unified async API.
- */
-export interface StorageAdapter {
-  /**
-   * Retrieve a value by key.
-   * @param key - The storage key
-   * @returns The stored value or null if not found
-   */
-  get<T>(key: string): Promise<T | null>;
-
-  /**
-   * Store a value by key.
-   * @param key - The storage key
-   * @param value - The value to store
-   */
-  set<T>(key: string, value: T): Promise<void>;
-
-  /**
-   * Remove a value by key.
-   * @param key - The storage key
-   */
-  remove(key: string): Promise<void>;
-
-  /**
-   * Clear all stored values.
-   */
-  clear(): Promise<void>;
-
-  /**
-   * Get all storage keys.
-   * @returns Array of all keys
-   */
-  keys(): Promise<string[]>;
-}
-
-/**
- * Abstract base class for web storage adapters (localStorage/sessionStorage).
- * Implements DRY principle by sharing common logic.
- */
-abstract class WebStorageAdapter implements StorageAdapter {
-  constructor(protected readonly storage: Storage) {}
-
-  async get<T>(key: string): Promise<T | null> {
-    const raw = this.storage.getItem(key);
-    if (raw === null) return null;
-    try {
-      return JSON.parse(raw) as T;
-    } catch {
-      return raw as unknown as T;
-    }
-  }
-
-  async set<T>(key: string, value: T): Promise<void> {
-    const serialized = typeof value === 'string' ? value : JSON.stringify(value);
-    this.storage.setItem(key, serialized);
-  }
-
-  async remove(key: string): Promise<void> {
-    this.storage.removeItem(key);
-  }
-
-  async clear(): Promise<void> {
-    this.storage.clear();
-  }
-
-  async keys(): Promise<string[]> {
-    return Object.keys(this.storage);
-  }
-}
-
-/**
- * localStorage adapter with async interface.
- */
-class LocalStorageAdapter extends WebStorageAdapter {
-  constructor() {
-    super(localStorage);
-  }
-}
-
-/**
- * sessionStorage adapter with async interface.
- */
-class SessionStorageAdapter extends WebStorageAdapter {
-  constructor() {
-    super(sessionStorage);
-  }
-}
-
-/**
- * IndexedDB configuration options.
- */
-export interface IndexedDBOptions {
-  /** Database name */
-  name: string;
-  /** Object store name */
-  store: string;
-  /** Database version (optional) */
-  version?: number;
-}
-
-/**
- * IndexedDB key-value adapter.
- * Wraps IndexedDB with a simple key-value interface.
- */
-class IndexedDBAdapter implements StorageAdapter {
-  private dbPromise: Promise<IDBDatabase> | null = null;
-
-  constructor(private readonly options: IndexedDBOptions) {}
-
-  /**
-   * Opens or creates the IndexedDB database.
-   */
-  private openDB(): Promise<IDBDatabase> {
-    if (this.dbPromise) return this.dbPromise;
-
-    this.dbPromise = new Promise((resolve, reject) => {
-      const request = indexedDB.open(this.options.name, this.options.version ?? 1);
-
-      request.onupgradeneeded = () => {
-        const db = request.result;
-        if (!db.objectStoreNames.contains(this.options.store)) {
-          db.createObjectStore(this.options.store);
-        }
-      };
-
-      request.onsuccess = () => resolve(request.result);
-      request.onerror = () => reject(request.error);
-    });
-
-    return this.dbPromise;
-  }
-
-  /**
-   * Executes a transaction on the object store.
-   */
-  private async withStore<T>(
-    mode: IDBTransactionMode,
-    operation: (store: IDBObjectStore) => IDBRequest<T>
-  ): Promise<T> {
-    const db = await this.openDB();
-    return new Promise((resolve, reject) => {
-      const tx = db.transaction(this.options.store, mode);
-      const store = tx.objectStore(this.options.store);
-      const request = operation(store);
-      request.onsuccess = () => resolve(request.result);
-      request.onerror = () => reject(request.error);
-    });
-  }
-
-  async get<T>(key: string): Promise<T | null> {
-    const result = await this.withStore<T | undefined>('readonly', (store) => store.get(key));
-    return result ?? null;
-  }
-
-  async set<T>(key: string, value: T): Promise<void> {
-    await this.withStore('readwrite', (store) => store.put(value, key));
-  }
-
-  async remove(key: string): Promise<void> {
-    await this.withStore('readwrite', (store) => store.delete(key));
-  }
-
-  async clear(): Promise<void> {
-    await this.withStore('readwrite', (store) => store.clear());
-  }
-
-  async keys(): Promise<string[]> {
-    const result = await this.withStore<IDBValidKey[]>('readonly', (store) => store.getAllKeys());
-    return result.map((key) => String(key));
-  }
-}
-
-/**
- * Storage factory providing access to different storage adapters.
- */
-export const storage = {
-  /**
-   * Create a localStorage adapter.
-   * @returns StorageAdapter wrapping localStorage
-   */
-  local(): StorageAdapter {
-    return new LocalStorageAdapter();
-  },
-
-  /**
-   * Create a sessionStorage adapter.
-   * @returns StorageAdapter wrapping sessionStorage
-   */
-  session(): StorageAdapter {
-    return new SessionStorageAdapter();
-  },
-
-  /**
-   * Create an IndexedDB adapter with key-value interface.
-   * @param options - Database and store configuration
-   * @returns StorageAdapter wrapping IndexedDB
-   */
-  indexedDB(options: IndexedDBOptions): StorageAdapter {
-    return new IndexedDBAdapter(options);
-  },
-};
+/**
+ * Unified storage adapters for web platform storage APIs.
+ * Provides a consistent, promise-based interface with predictable errors.
+ */
+
+/**
+ * Common interface for all storage adapters.
+ * All methods return promises for a unified async API.
+ */
+export interface StorageAdapter {
+  /**
+   * Retrieve a value by key.
+   * @param key - The storage key
+   * @returns The stored value or null if not found
+   */
+  get<T>(key: string): Promise<T | null>;
+
+  /**
+   * Store a value by key.
+   * @param key - The storage key
+   * @param value - The value to store
+   */
+  set<T>(key: string, value: T): Promise<void>;
+
+  /**
+   * Remove a value by key.
+   * @param key - The storage key
+   */
+  remove(key: string): Promise<void>;
+
+  /**
+   * Clear all stored values.
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Get all storage keys.
+   * @returns Array of all keys
+   */
+  keys(): Promise<string[]>;
+}
+
+/**
+ * Abstract base class for web storage adapters (localStorage/sessionStorage).
+ * Implements DRY principle by sharing common logic.
+ */
+abstract class WebStorageAdapter implements StorageAdapter {
+  constructor(protected readonly storage: Storage) {}
+
+  async get<T>(key: string): Promise<T | null> {
+    const raw = this.storage.getItem(key);
+    if (raw === null) return null;
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      return raw as unknown as T;
+    }
+  }
+
+  async set<T>(key: string, value: T): Promise<void> {
+    const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+    this.storage.setItem(key, serialized);
+  }
+
+  async remove(key: string): Promise<void> {
+    this.storage.removeItem(key);
+  }
+
+  async clear(): Promise<void> {
+    this.storage.clear();
+  }
+
+  async keys(): Promise<string[]> {
+    const result: string[] = [];
+    for (let i = 0; i < this.storage.length; i++) {
+      const key = this.storage.key(i);
+      if (key !== null) {
+        result.push(key);
+      }
+    }
+    return result;
+  }
+}
+
+/**
+ * localStorage adapter with async interface.
+ */
+class LocalStorageAdapter extends WebStorageAdapter {
+  constructor() {
+    super(localStorage);
+  }
+}
+
+/**
+ * sessionStorage adapter with async interface.
+ */
+class SessionStorageAdapter extends WebStorageAdapter {
+  constructor() {
+    super(sessionStorage);
+  }
+}
+
+/**
+ * IndexedDB configuration options.
+ */
+export interface IndexedDBOptions {
+  /** Database name */
+  name: string;
+  /** Object store name */
+  store: string;
+  /** Database version (optional) */
+  version?: number;
+}
+
+/**
+ * IndexedDB key-value adapter.
+ * Wraps IndexedDB with a simple key-value interface.
+ */
+class IndexedDBAdapter implements StorageAdapter {
+  private dbPromise: Promise<IDBDatabase> | null = null;
+
+  constructor(private readonly options: IndexedDBOptions) {}
+
+  /**
+   * Opens or creates the IndexedDB database.
+   */
+  private openDB(): Promise<IDBDatabase> {
+    if (this.dbPromise) return this.dbPromise;
+
+    this.dbPromise = new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.options.name, this.options.version ?? 1);
+
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(this.options.store)) {
+          db.createObjectStore(this.options.store);
+        }
+      };
+
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+
+    return this.dbPromise;
+  }
+
+  /**
+   * Executes a transaction on the object store.
+   */
+  private async withStore<T>(
+    mode: IDBTransactionMode,
+    operation: (store: IDBObjectStore) => IDBRequest<T>
+  ): Promise<T> {
+    const db = await this.openDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(this.options.store, mode);
+      const store = tx.objectStore(this.options.store);
+      const request = operation(store);
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    const result = await this.withStore<T | undefined>('readonly', (store) => store.get(key));
+    return result ?? null;
+  }
+
+  async set<T>(key: string, value: T): Promise<void> {
+    await this.withStore('readwrite', (store) => store.put(value, key));
+  }
+
+  async remove(key: string): Promise<void> {
+    await this.withStore('readwrite', (store) => store.delete(key));
+  }
+
+  async clear(): Promise<void> {
+    await this.withStore('readwrite', (store) => store.clear());
+  }
+
+  async keys(): Promise<string[]> {
+    const result = await this.withStore<IDBValidKey[]>('readonly', (store) => store.getAllKeys());
+    return result.map((key) => String(key));
+  }
+}
+
+/**
+ * Storage factory providing access to different storage adapters.
+ */
+export const storage = {
+  /**
+   * Create a localStorage adapter.
+   * @returns StorageAdapter wrapping localStorage
+   */
+  local(): StorageAdapter {
+    return new LocalStorageAdapter();
+  },
+
+  /**
+   * Create a sessionStorage adapter.
+   * @returns StorageAdapter wrapping sessionStorage
+   */
+  session(): StorageAdapter {
+    return new SessionStorageAdapter();
+  },
+
+  /**
+   * Create an IndexedDB adapter with key-value interface.
+   * @param options - Database and store configuration
+   * @returns StorageAdapter wrapping IndexedDB
+   */
+  indexedDB(options: IndexedDBOptions): StorageAdapter {
+    return new IndexedDBAdapter(options);
+  },
+};

package/src/reactive/batch.ts

@@ -0,0 +1,22 @@
+/**
+ * Batched reactive updates.
+ */
+
+import { beginBatch, endBatch } from './internals';
+
+/**
+ * Batches multiple signal updates into a single notification cycle.
+ *
+ * Updates made inside the batch function are deferred until the batch
+ * completes, preventing intermediate re-renders and improving performance.
+ *
+ * @param fn - Function containing multiple signal updates
+ */
+export const batch = (fn: () => void): void => {
+  beginBatch();
+  try {
+    fn();
+  } finally {
+    endBatch();
+  }
+};

package/src/reactive/computed.ts

@@ -0,0 +1,92 @@
+/**
+ * Computed reactive values.
+ */
+
+import {
+  clearDependencies,
+  getCurrentObserver,
+  registerDependency,
+  scheduleObserver,
+  track,
+  type ReactiveSource,
+} from './internals';
+
+/**
+ * A computed value that derives from other reactive sources.
+ *
+ * Computed values are lazily evaluated and cached. They only
+ * recompute when their dependencies change.
+ *
+ * @template T - The type of the computed value
+ */
+export class Computed<T> implements ReactiveSource {
+  private cachedValue!: T;
+  private dirty = true;
+  private subscribers = new Set<() => void>();
+  private readonly markDirty = () => {
+    this.dirty = true;
+    // 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);
+    }
+  };
+
+  /**
+   * Creates a new computed value.
+   * @param compute - Function that computes the value
+   */
+  constructor(private readonly compute: () => T) {}
+
+  /**
+   * Gets the computed value, recomputing if dependencies changed.
+   * During untrack calls, getCurrentObserver returns undefined, preventing dependency tracking.
+   */
+  get value(): T {
+    const current = getCurrentObserver();
+    if (current) {
+      this.subscribers.add(current);
+      registerDependency(current, this);
+    }
+    if (this.dirty) {
+      this.dirty = false;
+      // Clear old dependencies before recomputing
+      clearDependencies(this.markDirty);
+      this.cachedValue = track(this.markDirty, this.compute);
+    }
+    return this.cachedValue;
+  }
+
+  /**
+   * Reads the current computed value without tracking.
+   * Useful when you need the value but don't want to create a dependency.
+   *
+   * @returns The current cached value (recomputes if dirty)
+   */
+  peek(): T {
+    if (this.dirty) {
+      this.dirty = false;
+      // Clear old dependencies before recomputing
+      clearDependencies(this.markDirty);
+      this.cachedValue = track(this.markDirty, this.compute);
+    }
+    return this.cachedValue;
+  }
+
+  /**
+   * Removes an observer from this computed's subscriber set.
+   * @internal
+   */
+  unsubscribe(observer: () => void): void {
+    this.subscribers.delete(observer);
+  }
+}
+
+/**
+ * Creates a new computed value.
+ *
+ * @template T - The type of the computed value
+ * @param fn - Function that computes the value from reactive sources
+ * @returns A new Computed instance
+ */
+export const computed = <T>(fn: () => T): Computed<T> => new Computed(fn);

package/src/reactive/core.ts

@@ -0,0 +1,114 @@
+/**
+ * Core reactive signals.
+ */
+
+import {
+  getCurrentObserver,
+  registerDependency,
+  removeDependency,
+  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 all subscribers from this signal.
+   * Use this when a signal is no longer needed to prevent memory leaks.
+   *
+   * @example
+   * ```ts
+   * const count = signal(0);
+   * effect(() => console.log(count.value));
+   * count.dispose(); // All subscribers removed
+   * ```
+   */
+  dispose(): void {
+    // Remove this signal from each subscriber's dependency set
+    // so the observer no longer holds a strong reference to it
+    for (const subscriber of this.subscribers) {
+      removeDependency(subscriber, this);
+    }
+    this.subscribers.clear();
+  }
+
+  /**
+   * 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);