preact-missing-hooks 1.2.0 → 2.1.0

package/src/indexedDB/tableController.ts

@@ -0,0 +1,257 @@
+/**
+ * Table controller: insert, update, delete, exists, query, upsert, bulkInsert, clear, count.
+ * Works in standalone mode (opens its own transaction per op) or bound to a transaction.
+ * @module indexedDB/tableController
+ */
+
+import type { OperationCallbacks } from './types';
+import { requestToPromise } from './requestToPromise';
+
+/** Runs optional callbacks and returns the result. */
+function withCallbacks<T>(
+  promise: Promise<T>,
+  options?: OperationCallbacks<T>
+): Promise<T> {
+  if (!options) return promise;
+  return promise
+    .then((result) => {
+      options.onSuccess?.(result);
+      return result;
+    })
+    .catch((err: DOMException) => {
+      options.onError?.(err);
+      throw err;
+    });
+}
+
+/**
+ * Standalone table controller: opens a new transaction for each operation.
+ */
+function createStandaloneController(db: IDBDatabase, tableName: string): ITableController {
+  function getStore(mode: IDBTransactionMode): IDBObjectStore {
+    const tx = db.transaction([tableName], mode);
+    return tx.objectStore(tableName);
+  }
+
+  return {
+    insert<T>(data: T, options?: OperationCallbacks<IDBValidKey>): Promise<IDBValidKey> {
+      const store = getStore('readwrite');
+      return withCallbacks(requestToPromise(store.add(data)), options);
+    },
+
+    update<T>(key: IDBValidKey, updates: Partial<T>, options?: OperationCallbacks<void>): Promise<void> {
+      const store = getStore('readwrite');
+      const getReq = store.get(key);
+      return withCallbacks(
+        requestToPromise(getReq).then((existing) => {
+          if (existing === undefined) {
+            throw new DOMException('Key not found', 'NotFoundError');
+          }
+          const merged = { ...existing, ...updates } as T;
+          return requestToPromise(store.put(merged));
+        }).then(() => undefined),
+        options
+      );
+    },
+
+    delete(key: IDBValidKey, options?: OperationCallbacks<void>): Promise<void> {
+      const store = getStore('readwrite');
+      return withCallbacks(
+        requestToPromise(store.delete(key)).then(() => undefined),
+        options
+      );
+    },
+
+    exists(key: IDBValidKey): Promise<boolean> {
+      const store = getStore('readonly');
+      return requestToPromise(store.getKey(key)).then((k) => k !== undefined);
+    },
+
+    query<T>(filterFn: (item: T) => boolean, options?: OperationCallbacks<T[]>): Promise<T[]> {
+      const store = getStore('readonly');
+      const request = store.openCursor();
+      const results: T[] = [];
+      return withCallbacks(
+        new Promise<T[]>((resolve, reject) => {
+          request.onsuccess = () => {
+            const cursor = request.result;
+            if (cursor) {
+              if (filterFn(cursor.value as T)) results.push(cursor.value as T);
+              cursor.continue();
+            } else {
+              resolve(results);
+            }
+          };
+          request.onerror = () => reject(request.error ?? new DOMException('Unknown error'));
+        }),
+        options
+      );
+    },
+
+    upsert<T>(data: T, options?: OperationCallbacks<IDBValidKey>): Promise<IDBValidKey> {
+      const store = getStore('readwrite');
+      return withCallbacks(requestToPromise(store.put(data)), options);
+    },
+
+    bulkInsert<T>(items: T[], options?: OperationCallbacks<IDBValidKey[]>): Promise<IDBValidKey[]> {
+      const store = getStore('readwrite');
+      const keys: IDBValidKey[] = [];
+      if (items.length === 0) {
+        return withCallbacks(Promise.resolve(keys), options);
+      }
+      let completed = 0;
+      const promise = new Promise<IDBValidKey[]>((resolve, reject) => {
+        const onDone = () => {
+          completed++;
+          if (completed === items.length) resolve(keys);
+        };
+        items.forEach((item, i) => {
+          const req = store.add(item);
+          req.onsuccess = () => {
+            keys[i] = req.result;
+            onDone();
+          };
+          req.onerror = () => reject(req.error ?? new DOMException('Unknown error'));
+        });
+      });
+      return withCallbacks(promise, options);
+    },
+
+    clear(options?: OperationCallbacks<void>): Promise<void> {
+      const store = getStore('readwrite');
+      return withCallbacks(
+        requestToPromise(store.clear()).then(() => undefined),
+        options
+      );
+    },
+
+    count(options?: OperationCallbacks<number>): Promise<number> {
+      const store = getStore('readonly');
+      return withCallbacks(requestToPromise(store.count()), options ?? {});
+    },
+  };
+}
+
+/**
+ * Transaction-scoped table controller: uses the given transaction (no new transaction).
+ */
+function createTransactionController(tx: IDBTransaction, tableName: string): ITableController {
+  function getStore(): IDBObjectStore {
+    return tx.objectStore(tableName);
+  }
+
+  return {
+    insert<T>(data: T, options?: OperationCallbacks<IDBValidKey>): Promise<IDBValidKey> {
+      const store = getStore();
+      return withCallbacks(requestToPromise(store.add(data)), options);
+    },
+
+    update<T>(key: IDBValidKey, updates: Partial<T>, options?: OperationCallbacks<void>): Promise<void> {
+      const store = getStore();
+      return withCallbacks(
+        requestToPromise(store.get(key)).then((existing) => {
+          if (existing === undefined) {
+            throw new DOMException('Key not found', 'NotFoundError');
+          }
+          const merged = { ...existing, ...updates } as T;
+          return requestToPromise(store.put(merged));
+        }).then(() => undefined),
+        options
+      );
+    },
+
+    delete(key: IDBValidKey, options?: OperationCallbacks<void>): Promise<void> {
+      const store = getStore();
+      return withCallbacks(
+        requestToPromise(store.delete(key)).then(() => undefined),
+        options
+      );
+    },
+
+    exists(key: IDBValidKey): Promise<boolean> {
+      const store = getStore();
+      return requestToPromise(store.getKey(key)).then((k) => k !== undefined);
+    },
+
+    query<T>(filterFn: (item: T) => boolean, options?: OperationCallbacks<T[]>): Promise<T[]> {
+      const store = getStore();
+      const request = store.openCursor();
+      const results: T[] = [];
+      return withCallbacks(
+        new Promise<T[]>((resolve, reject) => {
+          request.onsuccess = () => {
+            const cursor = request.result;
+            if (cursor) {
+              if (filterFn(cursor.value as T)) results.push(cursor.value as T);
+              cursor.continue();
+            } else {
+              resolve(results);
+            }
+          };
+          request.onerror = () => reject(request.error ?? new DOMException('Unknown error'));
+        }),
+        options
+      );
+    },
+
+    upsert<T>(data: T, options?: OperationCallbacks<IDBValidKey>): Promise<IDBValidKey> {
+      const store = getStore();
+      return withCallbacks(requestToPromise(store.put(data)), options);
+    },
+
+    bulkInsert<T>(items: T[], options?: OperationCallbacks<IDBValidKey[]>): Promise<IDBValidKey[]> {
+      const store = getStore();
+      const keys: IDBValidKey[] = [];
+      if (items.length === 0) {
+        return withCallbacks(Promise.resolve(keys), options);
+      }
+      let completed = 0;
+      const promise = new Promise<IDBValidKey[]>((resolve, reject) => {
+        items.forEach((item, i) => {
+          const req = store.add(item);
+          req.onsuccess = () => {
+            keys[i] = req.result;
+            completed++;
+            if (completed === items.length) resolve(keys);
+          };
+          req.onerror = () => reject(req.error ?? new DOMException('Unknown error'));
+        });
+      });
+      return withCallbacks(promise, options);
+    },
+
+    clear(options?: OperationCallbacks<void>): Promise<void> {
+      const store = getStore();
+      return withCallbacks(
+        requestToPromise(store.clear()).then(() => undefined),
+        options
+      );
+    },
+
+    count(options?: OperationCallbacks<number>): Promise<number> {
+      const store = getStore();
+      return withCallbacks(requestToPromise(store.count()), options ?? {});
+    },
+  };
+}
+
+/** Public interface for a table controller (standalone or transaction-scoped). */
+export interface ITableController {
+  insert<T>(data: T, options?: OperationCallbacks<IDBValidKey>): Promise<IDBValidKey>;
+  update<T>(key: IDBValidKey, updates: Partial<T>, options?: OperationCallbacks<void>): Promise<void>;
+  delete(key: IDBValidKey, options?: OperationCallbacks<void>): Promise<void>;
+  exists(key: IDBValidKey): Promise<boolean>;
+  query<T>(filterFn: (item: T) => boolean, options?: OperationCallbacks<T[]>): Promise<T[]>;
+  upsert<T>(data: T, options?: OperationCallbacks<IDBValidKey>): Promise<IDBValidKey>;
+  bulkInsert<T>(items: T[], options?: OperationCallbacks<IDBValidKey[]>): Promise<IDBValidKey[]>;
+  clear(options?: OperationCallbacks<void>): Promise<void>;
+  count(options?: OperationCallbacks<number>): Promise<number>;
+}
+
+export function createTableController(db: IDBDatabase, tableName: string): ITableController {
+  return createStandaloneController(db, tableName);
+}
+
+export function createTransactionTableController(tx: IDBTransaction, tableName: string): ITableController {
+  return createTransactionController(tx, tableName);
+}

package/src/indexedDB/types.ts

@@ -0,0 +1,35 @@
+/**
+ * IndexedDB hook system – shared types.
+ * @module indexedDB/types
+ */
+
+/** Table schema for a single object store. */
+export interface TableSchema {
+  /** Key path (e.g. `"id"` or `["a", "b"]`). */
+  keyPath: string | string[];
+  /** Use auto-increment primary key. */
+  autoIncrement?: boolean;
+  /** Optional index names to create (each indexes the keyPath by default). */
+  indexes?: string[];
+}
+
+/** Configuration passed to useIndexedDB. */
+export interface IndexedDBConfig {
+  /** Database name. */
+  name: string;
+  /** Schema version (increment to trigger onupgradeneeded). */
+  version: number;
+  /** Map of table name → store schema (keyPath, autoIncrement, indexes). */
+  tables: {
+    [tableName: string]: TableSchema;
+  };
+}
+
+/** Optional callbacks for any operation. */
+export interface OperationCallbacks<T = unknown> {
+  onSuccess?: (result: T) => void;
+  onError?: (error: DOMException) => void;
+}
+
+/** Options for transaction. */
+export interface TransactionOptions extends OperationCallbacks<void> { }

package/src/useIndexedDB.ts

@@ -0,0 +1,111 @@
+/**
+ * Preact hook for IndexedDB: open database, create stores/indexes, return a database controller.
+ * Uses a singleton connection per (name, version).
+ * @module useIndexedDB
+ */
+
+import { useState, useEffect, useRef } from 'preact/hooks';
+import type { IndexedDBConfig } from './indexedDB/types';
+import { openDB } from './indexedDB/openDB';
+import { createDBController } from './indexedDB/dbController';
+import type { IDBController } from './indexedDB/dbController';
+
+export type { IndexedDBConfig, IDBController } from './indexedDB';
+
+export interface UseIndexedDBReturn {
+  /** Database controller (table, transaction). Null until the database is open. */
+  db: IDBController | null;
+  /** True once the database is open and ready. */
+  isReady: boolean;
+  /** Error from opening the database, if any. */
+  error: DOMException | null;
+}
+
+/**
+ * Opens an IndexedDB database and returns a controller for tables and transactions.
+ * Handles onupgradeneeded: creates object stores and indexes from config.
+ * Connection is a singleton per (config.name, config.version).
+ *
+ * @param config - Database name, version, and table schemas (keyPath, autoIncrement, indexes).
+ * @returns { db, isReady, error }. Use db.table(name) and db.transaction(...) when isReady is true.
+ *
+ * @example
+ * const { db, isReady, error } = useIndexedDB({
+ *   name: 'my-db',
+ *   version: 1,
+ *   tables: {
+ *     users: { keyPath: 'id', autoIncrement: true, indexes: ['email'] },
+ *   },
+ * })
+ * if (isReady && db) {
+ *   const users = db.table('users')
+ *   await users.insert({ email: 'a@b.com' })
+ *   await db.transaction(['users'], 'readwrite', (tx) => tx.table('users').insert({ email: 'b@b.com' }))
+ * }
+ */
+export function useIndexedDB(config: IndexedDBConfig): UseIndexedDBReturn {
+  const [db, setDb] = useState<IDBController | null>(null);
+  const [error, setError] = useState<DOMException | null>(null);
+  const [isReady, setIsReady] = useState(false);
+  const configRef = useRef(config);
+  configRef.current = config;
+
+  useEffect(() => {
+    let cancelled = false;
+    setError(null);
+    setIsReady(false);
+    setDb(null);
+
+    const { name, version, tables } = configRef.current;
+    openDB({ name, version, tables })
+      .then((database) => {
+        if (cancelled) {
+          database.close();
+          return;
+        }
+        const controller = createDBController(database, configRef.current);
+        setDb(controller);
+        setIsReady(true);
+      })
+      .catch((err: DOMException) => {
+        if (!cancelled) setError(err);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [config.name, config.version]);
+
+  return { db, isReady, error };
+}
+
+/*
+ * Usage example:
+ *
+ * const { db, isReady, error } = useIndexedDB({
+ *   name: 'my-app-db',
+ *   version: 1,
+ *   tables: {
+ *     users: { keyPath: 'id', autoIncrement: true, indexes: ['email'] },
+ *     settings: { keyPath: 'key' },
+ *   },
+ * })
+ *
+ * if (error) return <div>Failed to open database</div>
+ * if (!isReady || !db) return <div>Loading...</div>
+ *
+ * const users = db.table('users')
+ * await users.insert({ email: 'a@b.com', name: 'Alice' })
+ * await users.update(1, { name: 'Alice Smith' })
+ * const found = await users.query((u) => u.email.startsWith('a@'))
+ * const n = await users.count()
+ * await users.delete(1)
+ * await users.upsert({ id: 2, email: 'b@b.com' })
+ * await users.bulkInsert([{ email: 'c@b.com' }, { email: 'd@b.com' }])
+ * await users.clear({ onSuccess: () => console.log('cleared') })
+ *
+ * await db.transaction(['users', 'settings'], 'readwrite', async (tx) => {
+ *   await tx.table('users').insert({ email: 'e@b.com' })
+ *   await tx.table('settings').upsert({ key: 'theme', value: 'dark' })
+ * }, { onSuccess: () => console.log('transaction done') })
+ */

package/src/useThreadedWorker.ts

@@ -0,0 +1,165 @@
+import { useState, useCallback, useRef, useEffect } from 'preact/hooks';
+
+/** Lower number = higher priority. Default priority when not specified. */
+const DEFAULT_PRIORITY = 1;
+
+export type ThreadedWorkerMode = 'sequential' | 'parallel';
+
+export interface UseThreadedWorkerOptions {
+  /** Sequential: single worker, priority-ordered. Parallel: worker pool. */
+  mode: ThreadedWorkerMode;
+  /** Max concurrent workers. Only used when mode is "parallel". Default 4. */
+  concurrency?: number;
+}
+
+export interface RunOptions {
+  /** 1 = highest priority. Lower number runs first. FIFO within same priority. */
+  priority?: number;
+}
+
+interface QueuedTask<TData, TResult> {
+  data: TData;
+  priority: number;
+  sequence: number;
+  resolve: (value: TResult) => void;
+  reject: (reason: unknown) => void;
+}
+
+export interface UseThreadedWorkerReturn<TData, TResult> {
+  /** Enqueue work. Returns a Promise that resolves with the worker result. */
+  run: (data: TData, options?: RunOptions) => Promise<TResult>;
+  /** True while any task is queued or running. */
+  loading: boolean;
+  /** Result of the most recently completed successful task. */
+  result: TResult | undefined;
+  /** Error from the most recently failed task. */
+  error: unknown;
+  /** Number of tasks currently queued + running. */
+  queueSize: number;
+  /** Clear all pending (not yet started) tasks. Running tasks continue. */
+  clearQueue: () => void;
+  /** Stop accepting new work and clear pending queue. Running tasks finish. */
+  terminate: () => void;
+}
+
+/**
+ * Production-grade hook to run async work in a queue with optional priority
+ * and either sequential or parallel execution.
+ *
+ * @param workerFn - Async function to run for each task (e.g. API call, heavy compute).
+ * @param options - mode: "sequential" | "parallel", concurrency (parallel only).
+ * @returns run, loading, result, error, queueSize, clearQueue, terminate.
+ */
+export function useThreadedWorker<TData, TResult>(
+  workerFn: (data: TData) => Promise<TResult>,
+  options: UseThreadedWorkerOptions
+): UseThreadedWorkerReturn<TData, TResult> {
+  const { mode, concurrency = 4 } = options;
+  const maxConcurrent = mode === 'sequential' ? 1 : Math.max(1, concurrency);
+
+  const [loading, setLoading] = useState(false);
+  const [result, setResult] = useState<TResult | undefined>(undefined);
+  const [error, setError] = useState<unknown>(undefined);
+  const [queueSize, setQueueSize] = useState(0);
+
+  const queueRef = useRef<QueuedTask<TData, TResult>[]>([]);
+  const sequenceRef = useRef(0);
+  const activeCountRef = useRef(0);
+  const terminatedRef = useRef(false);
+  const workerFnRef = useRef(workerFn);
+  workerFnRef.current = workerFn;
+
+  const updateQueueSize = useCallback(() => {
+    setQueueSize(queueRef.current.length + activeCountRef.current);
+  }, []);
+
+  const processNext = useCallback(() => {
+    if (terminatedRef.current) return;
+    if (activeCountRef.current >= maxConcurrent) return;
+    if (queueRef.current.length === 0) {
+      if (activeCountRef.current === 0) setLoading(false);
+      updateQueueSize();
+      return;
+    }
+
+    // Sort by priority (asc), then by sequence (FIFO within same priority).
+    queueRef.current.sort((a, b) => {
+      if (a.priority !== b.priority) return a.priority - b.priority;
+      return a.sequence - b.sequence;
+    });
+    const task = queueRef.current.shift()!;
+    activeCountRef.current += 1;
+    setLoading(true);
+    updateQueueSize();
+
+    const fn = workerFnRef.current;
+    fn(task.data)
+      .then((value) => {
+        setResult(value);
+        setError(undefined);
+        task.resolve(value);
+      })
+      .catch((err) => {
+        setError(err);
+        task.reject(err);
+      })
+      .finally(() => {
+        activeCountRef.current -= 1;
+        updateQueueSize();
+        processNext();
+      });
+
+    // Fill remaining slots (parallel mode).
+    if (queueRef.current.length > 0 && activeCountRef.current < maxConcurrent) {
+      processNext();
+    }
+  }, [maxConcurrent, updateQueueSize]);
+
+  const run = useCallback(
+    (data: TData, runOptions?: RunOptions): Promise<TResult> => {
+      if (terminatedRef.current) {
+        return Promise.reject(new Error('Worker is terminated'));
+      }
+      const priority = runOptions?.priority ?? DEFAULT_PRIORITY;
+      const sequence = ++sequenceRef.current;
+      const promise = new Promise<TResult>((resolve, reject) => {
+        queueRef.current.push({ data, priority, sequence, resolve, reject });
+      });
+      updateQueueSize();
+      setLoading(true);
+      queueMicrotask(processNext);
+      return promise;
+    },
+    [processNext, updateQueueSize]
+  );
+
+  const clearQueue = useCallback(() => {
+    const pending = queueRef.current;
+    queueRef.current = [];
+    pending.forEach((t) => t.reject(new Error('Task cleared from queue')));
+    updateQueueSize();
+    if (activeCountRef.current === 0) setLoading(false);
+  }, [updateQueueSize]);
+
+  const terminate = useCallback(() => {
+    terminatedRef.current = true;
+    clearQueue();
+  }, [clearQueue]);
+
+  // Reset terminated on unmount so the same hook instance can't be "revived" without options change.
+  useEffect(() => {
+    return () => {
+      terminatedRef.current = true;
+    };
+  }, []);
+
+  return {
+    run,
+    loading,
+    result,
+    error,
+    queueSize,
+    clearQueue,
+    terminate,
+  };
+}