@spooky-sync/client-solid2 0.0.1-alpha.1

package/src/lib/Sp00kyProvider.ts

@@ -0,0 +1,104 @@
+import type { Element } from 'solid-js';
+import {
+  createSignal,
+  onSettled,
+  onCleanup,
+  createComponent,
+  createMemo,
+  merge,
+} from 'solid-js';
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+import type { SyncedDbConfig } from '../types';
+import { SyncedDb } from '../index';
+import { Sp00kyContext } from './context';
+
+export interface Sp00kyProviderProps<S extends SchemaStructure> {
+  config: SyncedDbConfig<S>;
+  fallback?: Element;
+  onError?: (error: Error) => void;
+  onReady?: (db: SyncedDb<S>) => void;
+  /**
+   * Prewarm data into the local cache before revealing the UI. Runs after
+   * `init()`; the `fallback` stays visible until it resolves. Use awaitable
+   * `db.preload(...)` calls here to gate first-load on essential data (e.g.
+   * config). On warm loads preload returns instantly, so there's no perceptible
+   * gate after the first run. Best-effort: a rejection is caught and the UI is
+   * revealed anyway.
+   */
+  preload?: (db: SyncedDb<S>) => Promise<void>;
+  children: Element;
+}
+
+export function Sp00kyProvider<S extends SchemaStructure>(
+  props: Sp00kyProviderProps<S>
+): Element {
+  const merged = merge({ fallback: undefined as Element | undefined }, props);
+
+  // Written from the async init continuation — outside any tracking scope.
+  const [db, setDb] = createSignal<SyncedDb<S> | undefined>(undefined, { ownedWrite: true });
+
+  // Init is async, so a dispose can land mid-init. Only that narrow race is
+  // handled here: an instance whose init finished AFTER the provider was
+  // already gone is closed, because nothing will ever reference it.
+  //
+  // A live, mounted client is deliberately NOT closed on cleanup. Doing that
+  // nulls `SyncedDb.sp00ky`, so every later `create`/`update`/`delete` throws
+  // "SyncedDb not initialized" while reads keep rendering from state that is
+  // already subscribed — i.e. mutations die silently and the app looks fine. In
+  // a host app the provider wraps the whole tree and only unmounts with the
+  // page, where the browser reclaims the worker anyway, so the leak this was
+  // meant to fix is worth far less than that risk.
+  let disposed = false;
+
+  onCleanup(() => {
+    disposed = true;
+  });
+
+  // `onSettled` replaces Solid 1's `onMount`.
+  onSettled(() => {
+    void (async () => {
+      try {
+        const instance = new SyncedDb<S>(merged.config);
+        await instance.init();
+        if (disposed) {
+          await instance.close();
+          return;
+        }
+        // Gate first-load UI on prewarmed data. Best-effort: never let a
+        // preload failure keep the app stuck on the fallback.
+        if (merged.preload) {
+          try {
+            await merged.preload(instance);
+          } catch (e) {
+            // oxlint-disable-next-line no-console
+            console.error('Sp00kyProvider: preload failed; revealing UI anyway', e);
+          }
+        }
+        setDb(() => instance);
+        merged.onReady?.(instance);
+      } catch (e) {
+        const error = e instanceof Error ? e : new Error(String(e));
+        if (merged.onError) {
+          merged.onError(error);
+        } else {
+          // oxlint-disable-next-line no-console
+          console.error('Sp00kyProvider: Failed to initialize database', error);
+        }
+      }
+    })();
+  });
+
+  const content = createMemo(() => {
+    const instance = db();
+    if (!instance) return merged.fallback;
+    // Solid 2: the context object IS the provider component.
+    return createComponent(Sp00kyContext, {
+      value: instance,
+      get children() {
+        return merged.children;
+      },
+    });
+  });
+
+  return content as unknown as Element;
+}

package/src/lib/__tests__/conflate.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest';
+import { createEffect, createRoot, flush } from 'solid-js';
+import { conflate } from '../conflate';
+import { fromSubscription } from '../from-subscription';
+
+const tick = () => new Promise<void>((r) => setTimeout(r, 0));
+
+describe('conflate', () => {
+  it('delivers values pushed after a pull is parked', async () => {
+    let cb: ((v: number) => void) | undefined;
+    const it = conflate<number>((c) => {
+      cb = c;
+      return () => (cb = undefined);
+    })[Symbol.asyncIterator]();
+
+    const p = it.next();
+    cb!(1);
+    expect(await p).toEqual({ value: 1, done: false });
+  });
+
+  it('conflates: only the newest unconsumed value survives', async () => {
+    let cb: ((v: number) => void) | undefined;
+    const it = conflate<number>((c) => {
+      cb = c;
+      return () => (cb = undefined);
+    })[Symbol.asyncIterator]();
+
+    cb!(1);
+    cb!(2);
+    cb!(3);
+    expect(await it.next()).toEqual({ value: 3, done: false });
+  });
+
+  it('return() unsubscribes and resolves a parked pull as done', async () => {
+    let unsubscribed = false;
+    let cb: ((v: number) => void) | undefined;
+    const it = conflate<number>((c) => {
+      cb = c;
+      return () => {
+        unsubscribed = true;
+        cb = undefined;
+      };
+    })[Symbol.asyncIterator]();
+
+    const parked = it.next();
+    await it.return!();
+    await tick();
+    expect(unsubscribed).toBe(true);
+    expect(await parked).toEqual({ value: undefined, done: true });
+    expect(await it.next()).toEqual({ value: undefined, done: true });
+  });
+
+  it('supports async subscribe (unsubscribe still runs after return())', async () => {
+    let unsubscribed = false;
+    const it = conflate<number>(async () => {
+      await tick();
+      return () => {
+        unsubscribed = true;
+      };
+    })[Symbol.asyncIterator]();
+
+    await it.return!();
+    await tick();
+    await tick();
+    expect(unsubscribed).toBe(true);
+  });
+
+  it('values pushed after return() are dropped', async () => {
+    let cb: ((v: number) => void) | undefined;
+    const it = conflate<number>((c) => {
+      cb = c;
+      return () => {};
+    })[Symbol.asyncIterator]();
+    await it.return!();
+    cb!(42);
+    expect(await it.next()).toEqual({ value: undefined, done: true });
+  });
+});
+
+describe('fromSubscription', () => {
+  it('serves initial synchronously, then live values; unsubscribes on dispose', async () => {
+    let cb: ((v: number) => void) | undefined;
+    let unsubscribed = false;
+    const subscribe = (c: (v: number) => void) => {
+      cb = c;
+      // spooky-style: fire immediately with current value
+      c(10);
+      return () => {
+        unsubscribed = true;
+        cb = undefined;
+      };
+    };
+
+    await createRoot(async (dispose) => {
+      const v = fromSubscription(subscribe, -1);
+      const seen: number[] = [];
+      createEffect(
+        () => v(),
+        (x) => {
+          seen.push(x);
+        }
+      );
+      flush();
+      expect(v()).toBe(-1); // loadingValue readable synchronously
+      await tick();
+      flush();
+      expect(v()).toBe(10); // immediate emission landed
+
+      cb!(20);
+      await tick();
+      flush();
+      expect(v()).toBe(20);
+      expect(seen).toContain(20);
+
+      dispose();
+      await tick();
+      expect(unsubscribed).toBe(true);
+    });
+  });
+});

package/src/lib/__tests__/create-query.test.ts

@@ -0,0 +1,397 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createEffect, createRoot, createSignal, flush } from 'solid-js';
+import { createQuery } from '../create-query';
+import { SyncedDb } from '../../index';
+
+const tick = () => new Promise<void>((r) => setTimeout(r, 0));
+const settle = async () => {
+  await tick();
+  flush();
+  await tick();
+};
+
+type Emission = Record<string, any>[];
+
+function mockEngine() {
+  const subs = new Map<string, (e: Emission) => void>();
+  const statusSubs = new Map<string, (s: string) => void>();
+  const authoritySubs = new Map<string, (known: boolean) => void>();
+  const unsubscribed: string[] = [];
+  const deregistered: string[] = [];
+  const sp00ky = {
+    subscribeQueryAuthority: vi.fn(
+      (hash: string, cb: (known: boolean) => void, o?: { immediate?: boolean }) => {
+        authoritySubs.set(hash, cb);
+        if (o?.immediate) cb(false);
+        return () => authoritySubs.delete(hash);
+      }
+    ),
+    subscribe: vi.fn(async (hash: string, cb: (e: Emission) => void, _o?: unknown) => {
+      subs.set(hash, cb);
+      return () => {
+        subs.delete(hash);
+        unsubscribed.push(hash);
+      };
+    }),
+    subscribeQueryStatus: vi.fn(
+      (hash: string, cb: (s: string) => void, o?: { immediate?: boolean }) => {
+        statusSubs.set(hash, cb);
+        if (o?.immediate) cb('idle');
+        return () => statusSubs.delete(hash);
+      }
+    ),
+    deregisterQuery: vi.fn((hash: string) => deregistered.push(hash)),
+    reportFrontendTiming: vi.fn(),
+  };
+  const db = Object.create(SyncedDb.prototype) as SyncedDb<any>;
+  (db as any).getSp00ky = () => sp00ky;
+  return {
+    db,
+    sp00ky,
+    emit: (hash: string, e: Emission) => subs.get(hash)?.(e),
+    setStatus: (hash: string, s: string) => statusSubs.get(hash)?.(s),
+    setAuthority: (hash: string, known: boolean) => authoritySubs.get(hash)?.(known),
+    unsubscribed,
+    deregistered,
+    hasSub: (hash: string) => subs.has(hash),
+  };
+}
+
+function mockQuery(hash: string, isOne = false) {
+  return {
+    hash,
+    isOne,
+    run: async () => ({ hash }),
+  } as any;
+}
+
+describe('createQuery', () => {
+  it('serves empty data immediately, then live emissions with row identity kept', async () => {
+    const eng = mockEngine();
+    await createRoot(async (dispose) => {
+      const q = createQuery<any, any, any, any, false, any>(eng.db, mockQuery('h1'));
+      createEffect(
+        () => q.data(),
+        () => {}
+      );
+      flush();
+
+      expect(q.data()).toEqual([]); // committed empty, no suspension
+      expect(q.isLoading()).toBe(true);
+
+      await settle();
+      eng.emit('h1', [
+        { id: 'a', n: 1 },
+        { id: 'b', n: 2 },
+      ]);
+      await settle();
+
+      expect(q.data().map((r: any) => r.id)).toEqual(['a', 'b']);
+      expect(q.isLoading()).toBe(false);
+      // Rows alone do not settle a query; the server's membership does.
+      expect(q.isSettled()).toBe(false);
+      eng.setAuthority('h1', true);
+      await settle();
+      expect(q.isSettled()).toBe(true);
+
+      const rowA = q.data()[0];
+      eng.emit('h1', [
+        { id: 'a', n: 99 },
+        { id: 'b', n: 2 },
+      ]);
+      await settle();
+      expect(q.data()[0]).toBe(rowA); // identity preserved via keyed reconcile
+      expect(q.data()[0].n).toBe(99);
+
+      dispose();
+      await settle();
+      expect(eng.unsubscribed).toContain('h1');
+    });
+  });
+
+  it('an empty emission before the server answers keeps loading', async () => {
+    // Nothing cached and nothing heard from the server: the only honest state
+    // is "loading". A second `[]` does not change that; only authority does.
+    const eng = mockEngine();
+    await createRoot(async (dispose) => {
+      const q = createQuery<any, any, any, any, false, any>(eng.db, mockQuery('h1'));
+      createEffect(
+        () => q.data(),
+        () => {}
+      );
+      flush();
+      await settle();
+
+      eng.emit('h1', []);
+      eng.emit('h1', []);
+      await settle();
+      expect(q.isLoading()).toBe(true);
+      expect(q.hasData()).toBe(false);
+      expect(q.isEmpty()).toBe(false);
+      expect(q.isAuthoritative()).toBe(false);
+      dispose();
+    });
+  });
+
+  it('the server answering with no rows ends loading as empty', async () => {
+    const eng = mockEngine();
+    await createRoot(async (dispose) => {
+      const q = createQuery<any, any, any, any, false, any>(eng.db, mockQuery('h1'));
+      createEffect(
+        () => q.data(),
+        () => {}
+      );
+      flush();
+      await settle();
+
+      eng.emit('h1', []);
+      eng.setAuthority('h1', true);
+      await settle();
+      expect(q.isLoading()).toBe(false);
+      expect(q.isEmpty()).toBe(true);
+      expect(q.isAuthoritative()).toBe(true);
+      expect(q.data()).toEqual([]);
+      dispose();
+    });
+  });
+
+  it('cached rows end loading before the server answers, without settling', async () => {
+    // Local-first paint: rows from the store are shown at once. They are not
+    // authoritative yet, so a windowed list must not read them as the end.
+    const eng = mockEngine();
+    await createRoot(async (dispose) => {
+      const q = createQuery<any, any, any, any, false, any>(eng.db, mockQuery('h1'));
+      createEffect(
+        () => q.data(),
+        () => {}
+      );
+      flush();
+      await settle();
+
+      eng.emit('h1', [{ id: 'a' }]);
+      await settle();
+      expect(q.isLoading()).toBe(false);
+      expect(q.hasData()).toBe(true);
+      expect(q.isAuthoritative()).toBe(false);
+      expect(q.isSettled()).toBe(false);
+      expect(q.isEmpty()).toBe(false);
+
+      eng.setAuthority('h1', true);
+      await settle();
+      expect(q.isSettled()).toBe(true);
+      dispose();
+    });
+  });
+
+  it('a one() query the server answered as absent is empty, not loading', async () => {
+    const eng = mockEngine();
+    await createRoot(async (dispose) => {
+      const q = createQuery<any, any, any, any, true, any>(eng.db, mockQuery('h1', true));
+      createEffect(
+        () => q.data(),
+        () => {}
+      );
+      flush();
+      await settle();
+
+      eng.emit('h1', []);
+      eng.setAuthority('h1', true);
+      await settle();
+      expect(q.isLoading()).toBe(false);
+      expect(q.isEmpty()).toBe(true);
+      expect(q.data()).toBeNull();
+      dispose();
+    });
+  });
+
+  it('losing authority with no rows (a bucket switch) returns to loading', async () => {
+    const eng = mockEngine();
+    await createRoot(async (dispose) => {
+      const q = createQuery<any, any, any, any, false, any>(eng.db, mockQuery('h1'));
+      createEffect(
+        () => q.data(),
+        () => {}
+      );
+      flush();
+      await settle();
+
+      eng.emit('h1', [{ id: 'a' }]);
+      eng.setAuthority('h1', true);
+      await settle();
+      expect(q.isLoading()).toBe(false);
+
+      // The rebind empties the rows and resets authority for the new principal.
+      eng.emit('h1', []);
+      eng.setAuthority('h1', false);
+      await settle();
+      expect(q.isLoading()).toBe(true);
+      expect(q.isEmpty()).toBe(false);
+      dispose();
+    });
+  });
+
+  it('one() queries yield the row or null', async () => {
+    const eng = mockEngine();
+    await createRoot(async (dispose) => {
+      const q = createQuery<any, any, any, any, true, any>(eng.db, mockQuery('h1', true));
+      createEffect(
+        () => q.data(),
+        () => {}
+      );
+      flush();
+      await settle();
+
+      expect(q.data()).toBe(null);
+      eng.emit('h1', [{ id: 'a', n: 1 }]);
+      await settle();
+      expect(q.data()?.n).toBe(1);
+      expect(q.isLoading()).toBe(false);
+      dispose();
+    });
+  });
+
+  it('isFetching mirrors query status; isSettled composes both', async () => {
+    const eng = mockEngine();
+    await createRoot(async (dispose) => {
+      const q = createQuery<any, any, any, any, false, any>(eng.db, mockQuery('h1'));
+      createEffect(
+        () => q.data(),
+        () => {}
+      );
+      flush();
+      await settle();
+
+      eng.setStatus('h1', 'fetching');
+      flush();
+      expect(q.isFetching()).toBe(true);
+
+      eng.emit('h1', [{ id: 'a' }]);
+      eng.setAuthority('h1', true);
+      await settle();
+      expect(q.isSettled()).toBe(false); // authoritative but still fetching
+
+      eng.setStatus('h1', 'idle');
+      flush();
+      expect(q.isSettled()).toBe(true);
+      dispose();
+    });
+  });
+
+  it('registration failure surfaces via error(), resolving isLoading', async () => {
+    const eng = mockEngine();
+    const failing = {
+      hash: 'hx',
+      isOne: false,
+      run: async () => {
+        throw new Error('SSP NOT_READY');
+      },
+    } as any;
+    await createRoot(async (dispose) => {
+      const q = createQuery<any, any, any, any, false, any>(eng.db, failing);
+      createEffect(
+        () => q.data(),
+        () => {}
+      );
+      flush();
+      await settle();
+
+      expect(q.error()?.message).toBe('SSP NOT_READY');
+      expect(q.isLoading()).toBe(false); // spinner must resolve
+      expect(q.data()).toEqual([]);
+      dispose();
+    });
+  });
+
+  it('reactive query thunk: identity change re-subscribes and clears state', async () => {
+    const eng = mockEngine();
+    await createRoot(async (dispose) => {
+      const [id, setId] = createSignal('h1');
+      const q = createQuery<any, any, any, any, false, any>(eng.db, () => mockQuery(id()));
+      createEffect(
+        () => q.data(),
+        () => {}
+      );
+      flush();
+      await settle();
+
+      eng.emit('h1', [{ id: 'a' }]);
+      await settle();
+      expect(q.data().map((r: any) => r.id)).toEqual(['a']);
+
+      setId('h2');
+      flush();
+      await settle();
+      await settle();
+
+      expect(eng.unsubscribed).toContain('h1'); // superseded subscription torn down
+      expect(eng.hasSub('h2')).toBe(true);
+      expect(q.isLoading()).toBe(true); // reset for the new identity
+
+      eng.emit('h2', [{ id: 'z' }]);
+      await settle();
+      expect(q.data().map((r: any) => r.id)).toEqual(['z']);
+      dispose();
+    });
+  });
+
+  it('enabled=false runs no query; flipping true starts it', async () => {
+    const eng = mockEngine();
+    await createRoot(async (dispose) => {
+      const [enabled, setEnabled] = createSignal(false);
+      const q = createQuery<any, any, any, any, false, any>(eng.db, mockQuery('h1'), {
+        enabled,
+      });
+      createEffect(
+        () => q.data(),
+        () => {}
+      );
+      flush();
+      await settle();
+      expect(eng.sp00ky.subscribe).not.toHaveBeenCalled();
+
+      setEnabled(true);
+      flush();
+      await settle();
+      expect(eng.hasSub('h1')).toBe(true);
+      dispose();
+    });
+  });
+
+  it('deregisterOnCleanup deregisters the active hash on dispose', async () => {
+    const eng = mockEngine();
+    await createRoot(async (dispose) => {
+      const q = createQuery<any, any, any, any, false, any>(eng.db, mockQuery('h1'), {
+        deregisterOnCleanup: true,
+      });
+      createEffect(
+        () => q.data(),
+        () => {}
+      );
+      flush();
+      await settle();
+      expect(eng.hasSub('h1')).toBe(true);
+
+      dispose();
+      await settle();
+      expect(eng.unsubscribed).toContain('h1');
+      expect(eng.deregistered).toEqual(['h1']);
+    });
+  });
+
+  it('reports frontend timing per emission', async () => {
+    const eng = mockEngine();
+    await createRoot(async (dispose) => {
+      const q = createQuery<any, any, any, any, false, any>(eng.db, mockQuery('h1'));
+      createEffect(
+        () => q.data(),
+        () => {}
+      );
+      flush();
+      await settle();
+      eng.emit('h1', [{ id: 'a' }]);
+      await settle();
+      expect(eng.sp00ky.reportFrontendTiming).toHaveBeenCalledWith('h1', expect.any(Number));
+      dispose();
+    });
+  });
+});