preact-missing-hooks 1.2.0 → 2.1.0

package/src/useWebRTCIP.ts

@@ -0,0 +1,176 @@
+/**
+ * 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
+ */
+
+import { useEffect, useState, useRef } from 'preact/hooks';
+
+/** IPv4 regex for ICE candidate strings (captures dotted-decimal). */
+const IPV4_REGEX = /\b(?:25[0-5]|2[0-4]\d|1?\d{1,2})(?:\.(?:25[0-5]|2[0-4]\d|1?\d{1,2})){3}\b/g;
+
+const DEFAULT_STUN_SERVERS: string[] = ['stun:stun.l.google.com:19302'];
+const DEFAULT_TIMEOUT_MS = 3000;
+
+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;
+}
+
+function isSSR(): boolean {
+  return typeof window === 'undefined';
+}
+
+function isWebRTCAvailable(): boolean {
+  return typeof RTCPeerConnection !== 'undefined';
+}
+
+/**
+ * Extracts IPv4 addresses from an ICE candidate string.
+ * Filters out common non-public/local patterns (e.g. 0.0.0.0) if desired; currently returns all matches.
+ */
+function extractIPv4FromCandidate(candidate: string): string[] {
+  const matches = candidate.match(IPV4_REGEX);
+  return matches ? [...matches] : [];
+}
+
+/**
+ * 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 function useWebRTCIP(options: UseWebRTCIPOptions = {}): UseWebRTCIPReturn {
+  const {
+    stunServers = DEFAULT_STUN_SERVERS,
+    timeout: timeoutMs = DEFAULT_TIMEOUT_MS,
+    onDetect,
+  } = options;
+
+  const [ips, setIps] = useState<string[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const pcRef = useRef<RTCPeerConnection | null>(null);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const reportedRef = useRef<Set<string>>(new Set());
+  const onDetectRef = useRef(onDetect);
+  onDetectRef.current = onDetect;
+
+  useEffect(() => {
+    if (isSSR()) {
+      setLoading(false);
+      setError('WebRTC IP detection is not available during SSR');
+      return;
+    }
+
+    if (!isWebRTCAvailable()) {
+      setLoading(false);
+      setError('RTCPeerConnection is not available');
+      return;
+    }
+
+    const reported = new Set<string>();
+    reportedRef.current = reported;
+
+    const finish = () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+      }
+      if (pcRef.current) {
+        pcRef.current.close();
+        pcRef.current = null;
+      }
+      setLoading(false);
+    };
+
+    const addIP = (ip: string) => {
+      if (reported.has(ip)) return;
+      reported.add(ip);
+      setIps((prev) => {
+        const next = [...prev, ip];
+        return next;
+      });
+      onDetectRef.current?.(ip);
+    };
+
+    try {
+      const pc = new RTCPeerConnection({
+        iceServers: [{ urls: stunServers }],
+      });
+      pcRef.current = pc;
+
+      pc.onicecandidate = (event) => {
+        const c = event.candidate;
+        if (!c || !c.candidate) return;
+        const found = extractIPv4FromCandidate(c.candidate);
+        found.forEach(addIP);
+      };
+
+      pc.createDataChannel('');
+
+      pc.createOffer()
+        .then((offer) => pc.setLocalDescription(offer))
+        .catch((err) => {
+          setError(err instanceof Error ? err.message : 'Failed to create offer');
+          finish();
+        });
+
+      timeoutRef.current = setTimeout(() => finish(), timeoutMs);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'WebRTC setup failed');
+      finish();
+    }
+
+    return () => {
+      finish();
+    };
+  }, [stunServers.join(','), timeoutMs]);
+
+  return { ips, loading, error };
+}
+
+/*
+ * Example usage (Preact component):
+ *
+ * function MyIPDisplay() {
+ *   const { ips, loading, error } = useWebRTCIP({
+ *     timeout: 4000,
+ *     onDetect: (ip) => { / * optional: e.g. send to analytics * / },
+ *   })
+ *
+ *   if (loading) return <p>Detecting IP…</p>
+ *   if (error) return <p>WebRTC failed: {error}. Try fallback API.</p>
+ *   return <p>IPs (WebRTC): {ips.join(', ') || 'None'}</p>
+ * }
+ *
+ * Fallback to public IP API when WebRTC fails or returns empty:
+ *   const [apiIP, setApiIP] = useState<string | null>(null)
+ *   useEffect(() => {
+ *     if (!loading && ips.length === 0 && error)
+ *       fetch('https://api.ipify.org?format=json').then(r => r.json()).then(d => setApiIP(d.ip))
+ *   }, [loading, ips.length, error])
+ */

package/tests/useIndexedDB.test.tsx

@@ -0,0 +1,208 @@
+/**
+ * @jest-environment jsdom
+ * Polyfill IndexedDB for Node/jsdom (must run before hook code).
+ */
+import 'fake-indexeddb/auto';
+
+/** @jsx h */
+import { h } from 'preact';
+import { render, waitFor } from '@testing-library/preact';
+import '@testing-library/jest-dom';
+import { useIndexedDB } from '@/useIndexedDB';
+
+const DB_NAME = 'test-db-' + Math.random().toString(36).slice(2);
+const DB_VERSION = 1;
+const config = {
+  name: DB_NAME,
+  version: DB_VERSION,
+  tables: {
+    users: {
+      keyPath: 'id',
+      autoIncrement: true,
+      indexes: ['email'],
+    },
+    settings: {
+      keyPath: 'key',
+    },
+  },
+};
+
+describe('useIndexedDB', () => {
+  it('opens database and sets isReady', async () => {
+    let dbRef: ReturnType<typeof useIndexedDB>['db'] = null;
+    function TestComponent() {
+      const result = useIndexedDB(config);
+      dbRef = result.db;
+      return (
+        <div>
+          <span data-testid="ready">{String(result.isReady)}</span>
+          <span data-testid="error">{result.error?.message ?? 'none'}</span>
+        </div>
+      );
+    }
+    render(<TestComponent />);
+    expect(dbRef).toBeNull();
+    await waitFor(() => {
+      expect(dbRef).not.toBeNull();
+    });
+    const readyEl = document.querySelector('[data-testid="ready"]');
+    expect(readyEl?.textContent).toBe('true');
+  });
+
+  it('hasTable returns true for defined tables', async () => {
+    let dbRef: ReturnType<typeof useIndexedDB>['db'] = null;
+    function TestComponent() {
+      const result = useIndexedDB(config);
+      dbRef = result.db;
+      return <div data-testid="ready">{String(result.isReady)}</div>;
+    }
+    render(<TestComponent />);
+    await waitFor(() => expect(dbRef).not.toBeNull());
+    expect(dbRef!.hasTable('users')).toBe(true);
+    expect(dbRef!.hasTable('settings')).toBe(true);
+    expect(dbRef!.hasTable('nonexistent')).toBe(false);
+  });
+
+  it('table insert and count', async () => {
+    let dbRef: ReturnType<typeof useIndexedDB>['db'] = null;
+    function TestComponent() {
+      const result = useIndexedDB(config);
+      dbRef = result.db;
+      return <div>{String(result.isReady)}</div>;
+    }
+    render(<TestComponent />);
+    await waitFor(() => expect(dbRef).not.toBeNull());
+    const users = dbRef!.table('users');
+    const key = await users.insert({ email: 'a@b.com', name: 'Alice' });
+    expect(key).toBe(1);
+    const n = await users.count();
+    expect(n).toBe(1);
+  });
+
+  it('table query with filter', async () => {
+    let dbRef: ReturnType<typeof useIndexedDB>['db'] = null;
+    function TestComponent() {
+      const result = useIndexedDB(config);
+      dbRef = result.db;
+      return <div>{String(result.isReady)}</div>;
+    }
+    render(<TestComponent />);
+    await waitFor(() => expect(dbRef).not.toBeNull());
+    const users = dbRef!.table('users');
+    await users.clear();
+    await users.insert({ email: 'a@b.com' });
+    await users.insert({ email: 'b@b.com' });
+    await users.insert({ email: 'a@c.com' });
+    const found = await users.query((item: { email: string }) => item.email.startsWith('a@'));
+    expect(found).toHaveLength(2);
+    const emails = found.map((x: { email: string }) => x.email).sort();
+    expect(emails).toEqual(['a@b.com', 'a@c.com']);
+  });
+
+  it('table exists, update, delete', async () => {
+    let dbRef: ReturnType<typeof useIndexedDB>['db'] = null;
+    function TestComponent() {
+      const result = useIndexedDB(config);
+      dbRef = result.db;
+      return <div>{String(result.isReady)}</div>;
+    }
+    render(<TestComponent />);
+    await waitFor(() => expect(dbRef).not.toBeNull());
+    const users = dbRef!.table('users');
+    await users.clear();
+    const key = await users.insert({ email: 'x@b.com', name: 'X' });
+    let ok = await users.exists(key);
+    expect(ok).toBe(true);
+    await users.update(key, { name: 'X Updated' });
+    await users.delete(key);
+    ok = await users.exists(key);
+    expect(ok).toBe(false);
+  });
+
+  it('table upsert and bulkInsert', async () => {
+    let dbRef: ReturnType<typeof useIndexedDB>['db'] = null;
+    function TestComponent() {
+      const result = useIndexedDB(config);
+      dbRef = result.db;
+      return <div>{String(result.isReady)}</div>;
+    }
+    render(<TestComponent />);
+    await waitFor(() => expect(dbRef).not.toBeNull());
+    const settings = dbRef!.table('settings');
+    await settings.clear();
+    await settings.upsert({ key: 'theme', value: 'dark' });
+    let n = await settings.count();
+    expect(n).toBe(1);
+    await settings.upsert({ key: 'theme', value: 'light' });
+    n = await settings.count();
+    expect(n).toBe(1);
+    const keys = await settings.bulkInsert([
+      { key: 'a', value: 1 },
+      { key: 'b', value: 2 },
+    ]);
+    expect(keys).toHaveLength(2);
+    n = await settings.count();
+    expect(n).toBe(3);
+  });
+
+  it('table clear', async () => {
+    let dbRef: ReturnType<typeof useIndexedDB>['db'] = null;
+    function TestComponent() {
+      const result = useIndexedDB(config);
+      dbRef = result.db;
+      return <div>{String(result.isReady)}</div>;
+    }
+    render(<TestComponent />);
+    await waitFor(() => expect(dbRef).not.toBeNull());
+    const settings = dbRef!.table('settings');
+    await settings.upsert({ key: 'toClear', value: 1 });
+    await settings.clear();
+    const n = await settings.count();
+    expect(n).toBe(0);
+  });
+
+  it('optional onSuccess and onError callbacks', async () => {
+    let dbRef: ReturnType<typeof useIndexedDB>['db'] = null;
+    function TestComponent() {
+      const result = useIndexedDB(config);
+      dbRef = result.db;
+      return <div>{String(result.isReady)}</div>;
+    }
+    render(<TestComponent />);
+    await waitFor(() => expect(dbRef).not.toBeNull());
+    const users = dbRef!.table('users');
+    let onSuccessCalled = false;
+    await users.insert({ email: 'cb@b.com' }, {
+      onSuccess: () => { onSuccessCalled = true; },
+    });
+    expect(onSuccessCalled).toBe(true);
+    let onErrorCalled = false;
+    await users.update(99999, { email: 'x' }, {
+      onError: () => { onErrorCalled = true; },
+    }).catch(() => { });
+    expect(onErrorCalled).toBe(true);
+  });
+
+  it('transaction runs and commits', async () => {
+    let dbRef: ReturnType<typeof useIndexedDB>['db'] = null;
+    function TestComponent() {
+      const result = useIndexedDB(config);
+      dbRef = result.db;
+      return <div>{String(result.isReady)}</div>;
+    }
+    render(<TestComponent />);
+    await waitFor(() => expect(dbRef).not.toBeNull());
+    await dbRef!.transaction(['users', 'settings'], 'readwrite', async (tx) => {
+      await tx.table('users').insert({ email: 'tx@b.com' });
+      await tx.table('settings').upsert({ key: 'fromTx', value: true });
+    });
+    const users = dbRef!.table('users');
+    const found = await users.query((item: { email: string }) => item.email === 'tx@b.com');
+    expect(found.length).toBeGreaterThanOrEqual(1);
+    expect(found.some((x: { email: string }) => x.email === 'tx@b.com')).toBe(true);
+    const settings = dbRef!.table('settings');
+    const fromTx = await settings.query((item: { key: string }) => item.key === 'fromTx');
+    expect(fromTx).toHaveLength(1);
+    expect((fromTx[0] as { value: boolean }).value).toBe(true);
+  });
+});

package/tests/useThreadedWorker.test.tsx

@@ -0,0 +1,267 @@
+/** @jsx h */
+import { h } from 'preact'
+import { render, waitFor } from '@testing-library/preact'
+import '@testing-library/jest-dom'
+import { useThreadedWorker } from '@/useThreadedWorker'
+
+/** Worker that resolves after delay with the input value (for order/concurrency tests). */
+function delayedWorker<T>(delayMs: number) {
+  return (data: T): Promise<T> =>
+    new Promise((resolve) => setTimeout(() => resolve(data), delayMs))
+}
+
+describe('useThreadedWorker', () => {
+  describe('sequential mode', () => {
+    it('runs one task at a time and returns result', async () => {
+      const worker = vi.fn().mockResolvedValue('done')
+      let api: ReturnType<typeof useThreadedWorker<string, string>>
+
+      function TestComponent() {
+        api = useThreadedWorker(worker, { mode: 'sequential' })
+        return (
+          <div>
+            <span data-testid="loading">{String(api!.loading)}</span>
+            <span data-testid="result">{api!.result ?? ''}</span>
+            <span data-testid="queueSize">{api!.queueSize}</span>
+          </div>
+        )
+      }
+
+      render(<TestComponent />)
+      expect(api!.loading).toBe(false)
+      expect(api!.result).toBeUndefined()
+      expect(api!.queueSize).toBe(0)
+
+      const p = api!.run('a')
+      await waitFor(() => expect(api!.loading).toBe(true))
+      await waitFor(() => expect(api!.queueSize).toBe(1))
+
+      await waitFor(() => expect(worker).toHaveBeenCalledWith('a'))
+      await p
+      await waitFor(() => {
+        expect(api!.result).toBe('done')
+        expect(api!.loading).toBe(false)
+        expect(api!.queueSize).toBe(0)
+      })
+    })
+
+    it('processes tasks in priority order (lower number first)', async () => {
+      const order: number[] = []
+      const worker = (data: { id: number }) =>
+        new Promise<number>((resolve) => {
+          order.push(data.id)
+          setTimeout(() => resolve(data.id), 10)
+        })
+
+      let api: ReturnType<typeof useThreadedWorker<{ id: number }, number>>
+
+      function TestComponent() {
+        api = useThreadedWorker(worker, { mode: 'sequential' })
+        return <div data-testid="queueSize">{api!.queueSize}</div>
+      }
+
+      render(<TestComponent />)
+      // Enqueue all in one tick; processNext runs in microtask so queue is sorted by priority.
+      // Submission order: 100(p2), 200(p1), 300(p3). Execution order must be 200, 100, 300.
+      api!.run({ id: 100 }, { priority: 2 })
+      api!.run({ id: 200 }, { priority: 1 })
+      api!.run({ id: 300 }, { priority: 3 })
+
+      await waitFor(() => expect(order).toHaveLength(3))
+      expect(order).toEqual([200, 100, 300]) // priority 1, then 2, then 3
+    })
+
+    it('FIFO within same priority', async () => {
+      const order: number[] = []
+      const worker = (data: number) =>
+        new Promise<number>((resolve) => {
+          order.push(data)
+          setTimeout(() => resolve(data), 5)
+        })
+
+      let api: ReturnType<typeof useThreadedWorker<number, number>>
+
+      function TestComponent() {
+        api = useThreadedWorker(worker, { mode: 'sequential' })
+        return null
+      }
+
+      render(<TestComponent />)
+      api!.run(1, { priority: 1 })
+      api!.run(2, { priority: 1 })
+      api!.run(3, { priority: 1 })
+
+      await waitFor(() => expect(order).toEqual([1, 2, 3]))
+    })
+
+    it('run() returns a Promise that resolves with worker result', async () => {
+      const worker = (x: number) => Promise.resolve(x * 2)
+      let api: ReturnType<typeof useThreadedWorker<number, number>>
+
+      function TestComponent() {
+        api = useThreadedWorker(worker, { mode: 'sequential' })
+        return null
+      }
+
+      render(<TestComponent />)
+      const result = await api!.run(21)
+      expect(result).toBe(42)
+    })
+
+    it('sets error when worker rejects', async () => {
+      const err = new Error('worker failed')
+      const worker = () => Promise.reject(err)
+      let api: ReturnType<typeof useThreadedWorker<void, void>>
+
+      function TestComponent() {
+        api = useThreadedWorker(worker, { mode: 'sequential' })
+        return (
+          <div>
+            <span data-testid="error">{(api!.error as Error)?.message ?? ''}</span>
+          </div>
+        )
+      }
+
+      render(<TestComponent />)
+      api!.run(undefined).catch(() => { })
+      await waitFor(() => expect(api!.error).toBe(err))
+      expect((api!.error as Error).message).toBe('worker failed')
+    })
+
+    it('clearQueue rejects pending tasks and leaves running task to finish', async () => {
+      const worker = delayedWorker<string>(100)
+      let api: ReturnType<typeof useThreadedWorker<string, string>>
+
+      function TestComponent() {
+        api = useThreadedWorker(worker, { mode: 'sequential' })
+        return null
+      }
+
+      render(<TestComponent />)
+      const first = api!.run('running')
+      const pending1 = api!.run('pending1')
+      const pending2 = api!.run('pending2')
+      await waitFor(() => expect(api!.queueSize).toBeGreaterThanOrEqual(2))
+
+      api!.clearQueue()
+      await expect(pending1.catch((e: Error) => e.message)).resolves.toBe(
+        'Task cleared from queue'
+      )
+      await expect(pending2.catch((e: Error) => e.message)).resolves.toBe(
+        'Task cleared from queue'
+      )
+      await expect(first).resolves.toBe('running')
+    })
+
+    it('terminate clears queue and rejects new run()', async () => {
+      const worker = (x: string) => Promise.resolve(x)
+      let api: ReturnType<typeof useThreadedWorker<string, string>>
+
+      function TestComponent() {
+        api = useThreadedWorker(worker, { mode: 'sequential' })
+        return null
+      }
+
+      render(<TestComponent />)
+      api!.terminate()
+      await expect(api!.run('x').catch((e: Error) => e.message)).resolves.toBe(
+        'Worker is terminated'
+      )
+    })
+  })
+
+  describe('parallel mode', () => {
+    it('runs up to concurrency tasks at once', async () => {
+      let concurrent = 0
+      let maxSeen = 0
+      const worker = async (id: number) => {
+        concurrent += 1
+        maxSeen = Math.max(maxSeen, concurrent)
+        await new Promise((r) => setTimeout(r, 30))
+        concurrent -= 1
+        return id
+      }
+
+      let api: ReturnType<typeof useThreadedWorker<number, number>>
+
+      function TestComponent() {
+        api = useThreadedWorker(worker, { mode: 'parallel', concurrency: 3 })
+        return <span data-testid="queueSize">{api!.queueSize}</span>
+      }
+
+      render(<TestComponent />)
+      api!.run(1)
+      api!.run(2)
+      api!.run(3)
+      api!.run(4)
+      api!.run(5)
+
+      await waitFor(() => expect(maxSeen).toBe(3))
+      expect(api!.queueSize).toBeGreaterThanOrEqual(0)
+      await waitFor(() => expect(api!.loading).toBe(false))
+      expect(api!.result).toBe(5) // last to finish in typical scheduling
+    })
+
+    it('processes all tasks in parallel and drains queue', async () => {
+      const worker = (data: { id: number }) =>
+        new Promise<number>((resolve) => setTimeout(() => resolve(data.id), 20))
+
+      let api: ReturnType<typeof useThreadedWorker<{ id: number }, number>>
+
+      function TestComponent() {
+        api = useThreadedWorker(worker, { mode: 'parallel', concurrency: 2 })
+        return null
+      }
+
+      render(<TestComponent />)
+      const [r1, r2, r3] = await Promise.all([
+        api!.run({ id: 1 }, { priority: 2 }),
+        api!.run({ id: 2 }, { priority: 1 }),
+        api!.run({ id: 3 }, { priority: 1 }),
+      ])
+      expect([r1, r2, r3].sort((a, b) => a - b)).toEqual([1, 2, 3])
+      await waitFor(() => {
+        expect(api!.queueSize).toBe(0)
+        expect(api!.loading).toBe(false)
+      })
+    })
+
+    it('queueSize reflects pending + running', async () => {
+      const worker = delayedWorker<number>(40)
+      let api: ReturnType<typeof useThreadedWorker<number, number>>
+
+      function TestComponent() {
+        api = useThreadedWorker(worker, { mode: 'parallel', concurrency: 2 })
+        return <span data-testid="queueSize">{api!.queueSize}</span>
+      }
+
+      render(<TestComponent />)
+      api!.run(1)
+      api!.run(2)
+      api!.run(3)
+      await waitFor(() => expect(api!.queueSize).toBe(3))
+      await waitFor(() => expect(api!.queueSize).toBeLessThanOrEqual(2))
+      await waitFor(() => expect(api!.queueSize).toBe(0))
+    })
+
+    it('run() Promise resolves with correct result in parallel', async () => {
+      const worker = (x: number) => Promise.resolve(x * 10)
+      let api: ReturnType<typeof useThreadedWorker<number, number>>
+
+      function TestComponent() {
+        api = useThreadedWorker(worker, { mode: 'parallel', concurrency: 2 })
+        return null
+      }
+
+      render(<TestComponent />)
+      const [a, b, c] = await Promise.all([
+        api!.run(1),
+        api!.run(2),
+        api!.run(3),
+      ])
+      expect(a).toBe(10)
+      expect(b).toBe(20)
+      expect(c).toBe(30)
+    })
+  })
+})