preact-missing-hooks 1.2.0 → 2.1.0

package/dist/indexedDB/requestToPromise.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Wraps an IDBRequest in a Promise.
+ * @module indexedDB/requestToPromise
+ */
+/**
+ * Converts an IDBRequest to a Promise. Rejects with the request's error on failure.
+ * @param request - Native IndexedDB request.
+ * @returns Promise that resolves with the request result or rejects with DOMException.
+ */
+export declare function requestToPromise<T>(request: IDBRequest<T>): Promise<T>;

package/dist/indexedDB/tableController.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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';
+/** 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 declare function createTableController(db: IDBDatabase, tableName: string): ITableController;
+export declare function createTransactionTableController(tx: IDBTransaction, tableName: string): ITableController;

package/dist/indexedDB/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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/dist/useIndexedDB.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Preact hook for IndexedDB: open database, create stores/indexes, return a database controller.
+ * Uses a singleton connection per (name, version).
+ * @module useIndexedDB
+ */
+import type { IndexedDBConfig } from './indexedDB/types';
+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 declare function useIndexedDB(config: IndexedDBConfig): UseIndexedDBReturn;

package/dist/useThreadedWorker.d.ts

@@ -0,0 +1,36 @@
+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;
+}
+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 declare function useThreadedWorker<TData, TResult>(workerFn: (data: TData) => Promise<TResult>, options: UseThreadedWorkerOptions): UseThreadedWorkerReturn<TData, TResult>;

package/dist/useWebRTCIP.d.ts

@@ -0,0 +1,37 @@
+/**
+ * useWebRTCIP – detect local/public IPs via WebRTC ICE candidates and STUN.
+ * Not highly reliable; use as first-priority hint and fall back to a public IP API (e.g. ipapi.co) if needed.
+ * @module useWebRTCIP
+ */
+export interface UseWebRTCIPOptions {
+    /** STUN server URLs (default: Google STUN). */
+    stunServers?: string[];
+    /** Stop gathering after this many ms (default: 3000). */
+    timeout?: number;
+    /** Called once per newly detected IP (no duplicates). */
+    onDetect?: (ip: string) => void;
+}
+export interface UseWebRTCIPReturn {
+    /** Unique IPv4 addresses found from ICE candidates. */
+    ips: string[];
+    /** True while ICE gathering is in progress. */
+    loading: boolean;
+    /** Error message if WebRTC is unavailable or detection fails. */
+    error: string | null;
+}
+/**
+ * Attempts to detect client IP addresses using WebRTC ICE candidates and a STUN server.
+ * Works frontend-only (no backend). Not guaranteed to return a public IP; use as a hint and
+ * fall back to a public IP API (e.g. ipapi.co, ip-api.com) if you need reliability.
+ *
+ * @param options - Optional: stunServers, timeout (ms), onDetect(ip) callback.
+ * @returns { ips, loading, error } – unique IPv4s, loading flag, and error message.
+ *
+ * @example
+ * const { ips, loading, error } = useWebRTCIP({
+ *   timeout: 5000,
+ *   onDetect: (ip) => console.log('Detected:', ip),
+ * })
+ * // If ips is empty and error is set, fall back to: fetch('https://api.ipify.org?format=json')
+ */
+export declare function useWebRTCIP(options?: UseWebRTCIPOptions): UseWebRTCIPReturn;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "preact-missing-hooks",
-  "version": "1.2.0",
+  "version": "2.1.0",
   "description": "A lightweight, extendable collection of missing React-like hooks for Preact — plus fresh, powerful new ones designed specifically for modern Preact apps.",
   "author": "Prakhar Dubey",
   "license": "MIT",
@@ -10,14 +10,64 @@
   "source": "src/index.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.module.js",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.js"
     },
     "./useTransition": {
+      "types": "./dist/useTransition.d.ts",
       "import": "./dist/useTransition.module.js",
-      "require": "./dist/useTransition.js",
-      "types": "./dist/useTransition.d.ts"
+      "require": "./dist/useTransition.js"
+    },
+    "./useMutationObserver": {
+      "types": "./dist/useMutationObserver.d.ts",
+      "import": "./dist/useMutationObserver.module.js",
+      "require": "./dist/useMutationObserver.js"
+    },
+    "./useEventBus": {
+      "types": "./dist/useEventBus.d.ts",
+      "import": "./dist/useEventBus.module.js",
+      "require": "./dist/useEventBus.js"
+    },
+    "./useWrappedChildren": {
+      "types": "./dist/useWrappedChildren.d.ts",
+      "import": "./dist/useWrappedChildren.module.js",
+      "require": "./dist/useWrappedChildren.js"
+    },
+    "./usePreferredTheme": {
+      "types": "./dist/usePreferredTheme.d.ts",
+      "import": "./dist/usePreferredTheme.module.js",
+      "require": "./dist/usePreferredTheme.js"
+    },
+    "./useNetworkState": {
+      "types": "./dist/useNetworkState.d.ts",
+      "import": "./dist/useNetworkState.module.js",
+      "require": "./dist/useNetworkState.js"
+    },
+    "./useClipboard": {
+      "types": "./dist/useClipboard.d.ts",
+      "import": "./dist/useClipboard.module.js",
+      "require": "./dist/useClipboard.js"
+    },
+    "./useRageClick": {
+      "types": "./dist/useRageClick.d.ts",
+      "import": "./dist/useRageClick.module.js",
+      "require": "./dist/useRageClick.js"
+    },
+    "./useThreadedWorker": {
+      "types": "./dist/useThreadedWorker.d.ts",
+      "import": "./dist/useThreadedWorker.module.js",
+      "require": "./dist/useThreadedWorker.js"
+    },
+    "./useIndexedDB": {
+      "types": "./dist/useIndexedDB.d.ts",
+      "import": "./dist/useIndexedDB.module.js",
+      "require": "./dist/useIndexedDB.js"
+    },
+    "./useWebRTCIP": {
+      "types": "./dist/useWebRTCIP.d.ts",
+      "import": "./dist/useWebRTCIP.module.js",
+      "require": "./dist/useWebRTCIP.js"
     }
   },
   "scripts": {
@@ -56,6 +106,7 @@
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/preact": "^3.2.4",
     "@types/jest": "^29.5.14",
+    "fake-indexeddb": "^6.0.2",
     "jsdom": "^26.1.0",
     "microbundle": "^0.15.1",
     "typescript": "^5.8.3",

package/src/index.ts

@@ -5,4 +5,7 @@ export * from './useWrappedChildren'
 export * from './usePreferredTheme'
 export * from './useNetworkState'
 export * from './useClipboard'
-export * from './useRageClick'
+export * from './useRageClick'
+export * from './useThreadedWorker'
+export * from './useIndexedDB'
+export * from './useWebRTCIP'

package/src/indexedDB/dbController.ts

@@ -0,0 +1,92 @@
+/**
+ * Database controller: table(name), transaction(storeNames, mode, callback, options).
+ * @module indexedDB/dbController
+ */
+
+import type { IndexedDBConfig, TransactionOptions } from './types';
+import type { ITableController } from './tableController';
+import { createTableController, createTransactionTableController } from './tableController';
+
+/** Transaction context passed to the callback: provides table(name) bound to this transaction. */
+export interface TransactionContext {
+  /** Returns a table controller bound to this transaction. Use for all ops inside the callback. */
+  table: (name: string) => ITableController;
+}
+
+/**
+ * Database controller built from an open IDBDatabase.
+ * Exposes table(name) and transaction(...).
+ */
+export interface IDBController {
+  /** Underlying IDBDatabase (read-only). */
+  readonly db: IDBDatabase;
+  /** Returns true if an object store with the given name exists. */
+  hasTable: (name: string) => boolean;
+  /** Returns a table controller for the given store (each op opens its own transaction). */
+  table: (name: string) => ITableController;
+  /**
+   * Runs a callback inside a single transaction. All operations in the callback use the same transaction.
+   * @param storeNames - Object store names to include in the transaction.
+   * @param mode - 'readonly' | 'readwrite'.
+   * @param callback - Async or sync function receiving { table(name) }. Return value is ignored; await all ops inside.
+   * @param options - Optional onSuccess/onError callbacks.
+   * @returns Promise that resolves when the transaction completes (after all requests and the callback).
+   */
+  transaction: <T = void>(
+    storeNames: string[],
+    mode: IDBTransactionMode,
+    callback: (tx: TransactionContext) => T | Promise<T>,
+    options?: TransactionOptions
+  ) => Promise<void>;
+}
+
+function withTransactionCallbacks(
+  promise: Promise<void>,
+  options?: TransactionOptions
+): Promise<void> {
+  if (!options) return promise;
+  return promise
+    .then(() => options.onSuccess?.())
+    .catch((err: DOMException) => {
+      options.onError?.(err);
+      throw err;
+    });
+}
+
+/**
+ * Creates a database controller from an open IDBDatabase instance.
+ */
+export function createDBController(db: IDBDatabase, _config: IndexedDBConfig): IDBController {
+  return {
+    get db(): IDBDatabase {
+      return db;
+    },
+
+    hasTable(name: string): boolean {
+      return db.objectStoreNames.contains(name);
+    },
+
+    table(name: string): ITableController {
+      return createTableController(db, name);
+    },
+
+    transaction<T = void>(
+      storeNames: string[],
+      mode: IDBTransactionMode,
+      callback: (tx: TransactionContext) => T | Promise<T>,
+      options?: TransactionOptions
+    ): Promise<void> {
+      const tx = db.transaction(storeNames, mode);
+      const txContext: TransactionContext = {
+        table: (tableName: string) => createTransactionTableController(tx, tableName),
+      };
+      const txPromise = new Promise<void>((resolve, reject) => {
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(tx.error ?? new DOMException('Transaction failed'));
+      });
+      const callbackResult = callback(txContext);
+      const promise = Promise.resolve(callbackResult).then(() => txPromise);
+      return withTransactionCallbacks(promise, options);
+    },
+  };
+}

package/src/indexedDB/index.ts

@@ -0,0 +1,11 @@
+/**
+ * IndexedDB hook system – public API.
+ * @module indexedDB
+ */
+
+export type { IndexedDBConfig, TableSchema, OperationCallbacks, TransactionOptions } from './types';
+export { requestToPromise } from './requestToPromise';
+export type { ITableController } from './tableController';
+export type { IDBController, TransactionContext } from './dbController';
+export { createDBController } from './dbController';
+export { openDB } from './openDB';

package/src/indexedDB/openDB.ts

@@ -0,0 +1,49 @@
+/**
+ * Opens IndexedDB and runs onupgradeneeded to create stores and indexes.
+ * Singleton per (name, version).
+ * @module indexedDB/openDB
+ */
+
+import type { IndexedDBConfig, TableSchema } from './types';
+import { requestToPromise } from './requestToPromise';
+
+const connectionCache = new Map<string, Promise<IDBDatabase>>();
+
+/**
+ * Opens the database and creates/upgrades object stores and indexes from config.
+ * Uses a singleton cache per (name, version); repeated calls with the same config reuse the same connection.
+ */
+export function openDB(config: IndexedDBConfig): Promise<IDBDatabase> {
+  const key = `${config.name}_v${config.version}`;
+  let promise = connectionCache.get(key);
+  if (promise) return promise;
+  promise = _openDB(config);
+  connectionCache.set(key, promise);
+  return promise;
+}
+
+function _openDB(config: IndexedDBConfig): Promise<IDBDatabase> {
+  return new Promise<IDBDatabase>((resolve, reject) => {
+    const request = indexedDB.open(config.name, config.version);
+    request.onerror = () => reject(request.error ?? new DOMException('Failed to open database'));
+    request.onsuccess = () => resolve(request.result);
+    request.onupgradeneeded = (event: IDBVersionChangeEvent) => {
+      const db = (event.target as IDBOpenDBRequest).result;
+      const tables = config.tables;
+      for (const tableName of Object.keys(tables)) {
+        const schema = tables[tableName] as TableSchema;
+        if (!db.objectStoreNames.contains(tableName)) {
+          const store = db.createObjectStore(tableName, {
+            keyPath: schema.keyPath,
+            autoIncrement: schema.autoIncrement ?? false,
+          });
+          if (schema.indexes) {
+            for (const indexName of schema.indexes) {
+              store.createIndex(indexName, indexName, { unique: false });
+            }
+          }
+        }
+      }
+    };
+  });
+}

package/src/indexedDB/requestToPromise.ts

@@ -0,0 +1,16 @@
+/**
+ * Wraps an IDBRequest in a Promise.
+ * @module indexedDB/requestToPromise
+ */
+
+/**
+ * Converts an IDBRequest to a Promise. Rejects with the request's error on failure.
+ * @param request - Native IndexedDB request.
+ * @returns Promise that resolves with the request result or rejects with DOMException.
+ */
+export function requestToPromise<T>(request: IDBRequest<T>): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new DOMException('Unknown IndexedDB error'));
+  });
+}