@spooky-sync/client-solid2 0.0.1-canary.237 → 0.0.1-canary.239

package/src/index.ts

@@ -47,6 +47,11 @@ export { createQuery, useQuery, type CreateQueryResult, type QueryOptions } from
 export { createPreload } from './lib/create-preload';
 export type { PreloadOptions, PreloadRefresh } from '@spooky-sync/core';
 export { useSyncStatus, type UseSyncStatus } from './lib/use-sync-status';
+export {
+  useSyncActivity,
+  type UseSyncActivity,
+  type UseSyncActivityOptions,
+} from './lib/use-sync-activity';
 export type {
   SyncHealth,
   SyncHealthStatus,
@@ -345,6 +350,21 @@ export class SyncedDb<S extends SchemaStructure> {
     return this.sp00ky.subscribeToPendingMutations(cb);
   }
 
+  /** Queries mid-fetch right now. See {@link useSyncActivity}. */
+  get fetchingQueryCount(): number {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.fetchingQueryCount;
+  }
+
+  /**
+   * Observe how many queries are fetching from the server. Fires immediately
+   * and on every change. Prefer the `useSyncActivity` hook in components.
+   */
+  subscribeToFetchActivity(cb: (fetching: number) => void): () => void {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.subscribeToFetchActivity(cb);
+  }
+
   /** Current sync-health snapshot. See {@link useSyncStatus}. */
   get syncHealth(): SyncHealth {
     if (!this.sp00ky) throw new Error('SyncedDb not initialized');

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

@@ -15,9 +15,17 @@ 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 () => {
@@ -42,6 +50,7 @@ function mockEngine() {
     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),
@@ -79,6 +88,10 @@ describe('createQuery', () => {
 
       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];
@@ -96,7 +109,55 @@ describe('createQuery', () => {
     });
   });
 
-  it('first empty emission does not mark fetched; second does', async () => {
+  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'));
@@ -107,13 +168,64 @@ describe('createQuery', () => {
       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(true); // still loading: local DB likely not synced
+      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(false); // a later empty emission is authoritative
+      expect(q.isLoading()).toBe(true);
+      expect(q.isEmpty()).toBe(false);
       dispose();
     });
   });
@@ -154,8 +266,9 @@ describe('createQuery', () => {
       expect(q.isFetching()).toBe(true);
 
       eng.emit('h1', [{ id: 'a' }]);
+      eng.setAuthority('h1', true);
       await settle();
-      expect(q.isSettled()).toBe(false); // fetched but still fetching
+      expect(q.isSettled()).toBe(false); // authoritative but still fetching
 
       eng.setStatus('h1', 'idle');
       flush();

package/src/lib/__tests__/use-sync-activity.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { createRoot, flush } from 'solid-js';
+import { useSyncActivity } from '../use-sync-activity';
+import { SyncedDb } from '../../index';
+
+const tick = () => new Promise<void>((r) => setTimeout(r, 0));
+const settle = async () => {
+  await tick();
+  flush();
+  await tick();
+};
+
+/** A SyncedDb double exposing just the two channels the hook subscribes to. */
+function mockDb(initialFetching = 0, initialPending = 0) {
+  let fetchingCb: ((n: number) => void) | undefined;
+  let pendingCb: ((n: number) => void) | undefined;
+  const db = Object.create(SyncedDb.prototype) as SyncedDb<any>;
+  Object.defineProperty(db, 'fetchingQueryCount', { get: () => initialFetching });
+  Object.defineProperty(db, 'pendingMutationCount', { get: () => initialPending });
+  (db as any).subscribeToFetchActivity = vi.fn((cb: (n: number) => void) => {
+    fetchingCb = cb;
+    cb(initialFetching);
+    return () => {
+      fetchingCb = undefined;
+    };
+  });
+  (db as any).subscribeToPendingMutations = vi.fn((cb: (n: number) => void) => {
+    pendingCb = cb;
+    cb(initialPending);
+    return () => {
+      pendingCb = undefined;
+    };
+  });
+  return {
+    db,
+    setFetching: (n: number) => fetchingCb?.(n),
+    setPending: (n: number) => pendingCb?.(n),
+  };
+}
+
+describe('useSyncActivity', () => {
+  beforeEach(() => vi.useFakeTimers({ shouldAdvanceTime: true }));
+  afterEach(() => vi.useRealTimers());
+
+  it('turns isDownloading on only after the delay, and off at once', async () => {
+    const m = mockDb();
+    await createRoot(async (dispose) => {
+      const a = useSyncActivity(m.db, { downloadDelayMs: 200 });
+      await settle();
+      expect(a.fetchingQueries()).toBe(0);
+      expect(a.isDownloading()).toBe(false);
+
+      m.setFetching(2);
+      await settle();
+      expect(a.fetchingQueries()).toBe(2);
+      expect(a.isDownloading()).toBe(false);
+      await vi.advanceTimersByTimeAsync(150);
+      flush();
+      expect(a.isDownloading()).toBe(false);
+      await vi.advanceTimersByTimeAsync(60);
+      flush();
+      expect(a.isDownloading()).toBe(true);
+
+      m.setFetching(0);
+      await settle();
+      expect(a.isDownloading()).toBe(false);
+      dispose();
+    });
+  });
+
+  it('a fetch shorter than the delay never shows', async () => {
+    const m = mockDb();
+    await createRoot(async (dispose) => {
+      const a = useSyncActivity(m.db, { downloadDelayMs: 200 });
+      await settle();
+      m.setFetching(1);
+      await settle();
+      await vi.advanceTimersByTimeAsync(100);
+      m.setFetching(0);
+      await settle();
+      await vi.advanceTimersByTimeAsync(300);
+      flush();
+      expect(a.isDownloading()).toBe(false);
+      dispose();
+    });
+  });
+
+  it('isUploading needs more than the threshold of queued writes', async () => {
+    const m = mockDb(0, 1);
+    await createRoot(async (dispose) => {
+      const a = useSyncActivity(m.db);
+      await settle();
+      expect(a.pendingMutations()).toBe(1);
+      expect(a.isUploading()).toBe(false);
+      m.setPending(2);
+      await settle();
+      expect(a.isUploading()).toBe(true);
+      m.setPending(0);
+      await settle();
+      expect(a.isUploading()).toBe(false);
+      dispose();
+    });
+  });
+});

package/src/lib/create-query.ts

@@ -59,13 +59,35 @@ export type CreateQueryResult<TData> = {
    */
   ready: Accessor<TData>;
   error: Accessor<Error | undefined>;
+  /**
+   * True only on a COLD first load: nothing has painted for this identity,
+   * the server has not answered yet, and registration has not failed. A query
+   * that painted from the local cache is not loading, however long the server
+   * takes; a query the server answered with zero rows is not loading either
+   * (see `isEmpty`). Resets when the query identity changes.
+   */
   isLoading: Accessor<boolean>;
+  /** True while a fetch cycle is in flight (registration, a sync round). */
   isFetching: Accessor<boolean>;
   /**
-   * True once the query has delivered a result AND no fetch cycle is in
-   * flight (registration + initial sync included). While settled, results are
-   * authoritative: a windowed query returning fewer rows than its LIMIT
-   * really is the end of the list. Resets when the query identity changes.
+   * True once server membership is known for this identity: a registration or
+   * poll landed, or the durable membership of a previous session was read on
+   * boot. From then on `data()` is the server's answer, not a cache guess.
+   * Latched until the identity changes (or a bucket switch resets it).
+   */
+  isAuthoritative: Accessor<boolean>;
+  /** Whether `data()` currently holds anything: rows for a list, a row for `one()`. */
+  hasData: Accessor<boolean>;
+  /**
+   * The server answered and the answer is "no rows". The signal to render an
+   * empty state on; a bare `!hasData()` cannot tell empty from not-yet-loaded.
+   */
+  isEmpty: Accessor<boolean>;
+  /**
+   * True once server membership is known AND no fetch cycle is in flight.
+   * While settled, results are authoritative: a windowed query returning fewer
+   * rows than its LIMIT really is the end of the list. Not monotonic: a later
+   * sync round re-enters `isFetching`; latch it if a verdict must stick.
    */
   isSettled: Accessor<boolean>;
 };
@@ -132,7 +154,12 @@ export function createQuery<
   // continuations, which run outside any tracking scope — `ownedWrite` opts
   // these signals out of Solid 2's owned-scope write guard.
   const [error, setError] = createSignal<Error | undefined>(undefined, { ownedWrite: true });
-  const [isFetched, setIsFetched] = createSignal(false, { ownedWrite: true });
+  // Server membership known for the current identity (core `membershipKnown`).
+  const [isAuthoritative, setIsAuthoritative] = createSignal(false, { ownedWrite: true });
+  // An emission WITH data has been applied for the current identity. Together
+  // with `isAuthoritative` this is what ends the cold-load state: a cached
+  // paint ends it without the server, a server answer ends it without rows.
+  const [hasPainted, setHasPainted] = createSignal(false, { ownedWrite: true });
   const [isFetching, setIsFetching] = createSignal(false, { ownedWrite: true });
 
   // The hash of the currently-installed subscription, for opt-in deregister on
@@ -180,7 +207,8 @@ export function createQuery<
       const myRun = ++runId;
       // A new identity starts clean: a previous identity's failure must not
       // keep this one out of its loading state.
-      setIsFetched(false);
+      setIsAuthoritative(false);
+      setHasPainted(false);
       setError(undefined);
       if (!enabled || !query) return;
 
@@ -224,24 +252,43 @@ export function createQuery<
             })
           );
 
-          let isFirstCall = true;
+          // Mirror whether the server's membership is known. This is the
+          // channel that ends a cold load for a query whose honest answer is
+          // zero rows: the core emits no second `[]` for it, but it does flip
+          // authority once the registration (or a poll) has landed. A flip
+          // back to false is a bucket switch (a different principal), whose
+          // rebind also empties the rows, so the paint latch goes with it.
+          addCleanup(
+            sp00ky.subscribeQueryAuthority(
+              hash,
+              (known) => {
+                if (disposed || myRun !== runId) return;
+                setIsAuthoritative(known);
+                if (known) wakeReady();
+                else setHasPainted(false);
+              },
+              { immediate: true }
+            )
+          );
+
           addCleanup(
             sp00ky.subscribe(
               hash,
               (rows: Record<string, any>[]) => {
                 if (disposed || myRun !== runId) return;
                 const queryData = (query.isOne ? (rows[0] ?? null) : rows) as TData;
-                // The first (immediate) callback with no data likely means the
-                // local DB has not synced yet — don't mark as fetched, so the
-                // UI keeps showing its loading state.
-                const hasData = query.isOne
+                // Every emission is applied as-is: the core only emits what
+                // it has decided the query holds (cached rows on mount, the
+                // server's set once membership is known), and it never emits
+                // a wrongful `[]` for a lost or still-publishing view. An
+                // emission WITH data ends the cold-load state on its own.
+                const hasRows = query.isOne
                   ? queryData !== null && queryData !== undefined
                   : rows.length > 0;
-                if (!isFirstCall || hasData) {
-                  setIsFetched(true);
+                if (hasRows) {
+                  setHasPainted(true);
                   wakeReady();
                 }
-                isFirstCall = false;
 
                 const t0 = performance.now();
                 setStore((s) => {
@@ -290,10 +337,10 @@ export function createQuery<
   // async node stays PENDING, every queue flush carries pending nodes forward,
   // and a navigation transition waits on them. Lazy means only a query whose
   // `ready()` is read creates the node at all, and the deferred below is
-  // settled by the same emission that flips `isFetched`.
+  // settled by the same emission (or authority flip) that ends `isLoading`.
   const readyGate = createMemo(
     async (): Promise<true> => {
-      if (isFetched() || error()) return true;
+      if (isAuthoritative() || hasPainted() || error()) return true;
       await new Promise<void>((resolve) => readyWaiters.push(resolve));
       return true;
     },
@@ -316,8 +363,13 @@ export function createQuery<
     }
   });
 
-  const isLoading = () => !isFetched() && error() === undefined;
-  const isSettled = () => isFetched() && !isFetching();
+  const hasData = () => {
+    const v = store.value as unknown;
+    return Array.isArray(v) ? v.length > 0 : v !== null && v !== undefined;
+  };
+  const isLoading = () => !isAuthoritative() && !hasPainted() && error() === undefined;
+  const isEmpty = () => isAuthoritative() && !hasData();
+  const isSettled = () => isAuthoritative() && !isFetching();
 
   return {
     data,
@@ -325,6 +377,9 @@ export function createQuery<
     error,
     isLoading,
     isFetching,
+    isAuthoritative,
+    hasData,
+    isEmpty,
     isSettled,
   };
 }

package/src/lib/use-sync-activity.ts

@@ -0,0 +1,99 @@
+import { createEffect, createSignal, onCleanup, type Accessor } from 'solid-js';
+import { useDb } from './context';
+import { fromSubscription } from './from-subscription';
+import type { SyncedDb } from '../index';
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+
+export interface UseSyncActivityOptions {
+  /**
+   * How long queries must be fetching before `isDownloading()` turns on.
+   * Filters the sub-frame fetches a warm cache produces, so the indicator only
+   * shows work the user could notice. Default 200 ms.
+   */
+  downloadDelayMs?: number;
+  /**
+   * `isUploading()` turns on once MORE than this many mutations are waiting in
+   * the outbox. Default 1: a single write acknowledged within a round trip is
+   * not worth an animation; a backlog is.
+   */
+  uploadThreshold?: number;
+}
+
+export interface UseSyncActivity {
+  /** Queries inside a fetch cycle right now (core `fetchingQueryCount`). */
+  fetchingQueries: Accessor<number>;
+  /** Locally committed writes the server has not acknowledged yet. */
+  pendingMutations: Accessor<number>;
+  /** Fetching for longer than `downloadDelayMs`. Drives a "downloading" mark. */
+  isDownloading: Accessor<boolean>;
+  /** More than `uploadThreshold` writes queued. Drives an "uploading" mark. */
+  isUploading: Accessor<boolean>;
+}
+
+/**
+ * The two directions of sync traffic, for an indicator in the app chrome.
+ *
+ * `fetchingQueries` is one subscription on the engine's aggregate fetch count,
+ * not one per query; `pendingMutations` is the outbox depth. `isDownloading`
+ * is the fetch count debounced ON by `downloadDelayMs` (and off at once), so a
+ * local-first page that answers from cache and confirms with the server in a
+ * few milliseconds never flickers. Must be used within a `<Sp00kyProvider>`, or
+ * pass the `SyncedDb` explicitly.
+ */
+export function useSyncActivity<S extends SchemaStructure = any>(
+  dbOrOptions?: SyncedDb<S> | UseSyncActivityOptions,
+  maybeOptions?: UseSyncActivityOptions
+): UseSyncActivity {
+  const explicitDb =
+    dbOrOptions && typeof (dbOrOptions as SyncedDb<S>).subscribeToFetchActivity === 'function'
+      ? (dbOrOptions as SyncedDb<S>)
+      : undefined;
+  const options = (explicitDb ? maybeOptions : (dbOrOptions as UseSyncActivityOptions)) ?? {};
+  const db = explicitDb ?? useDb<S>();
+  const downloadDelayMs = options.downloadDelayMs ?? 200;
+  const uploadThreshold = options.uploadThreshold ?? 1;
+
+  const fetchingQueries = fromSubscription<number>(
+    (cb) => db.subscribeToFetchActivity(cb),
+    db.fetchingQueryCount
+  );
+  const pendingMutations = fromSubscription<number>(
+    (cb) => db.subscribeToPendingMutations(cb),
+    db.pendingMutationCount
+  );
+
+  // ON after the delay, OFF immediately. Written from a timer, hence ownedWrite.
+  const [isDownloading, setIsDownloading] = createSignal(false, { ownedWrite: true });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  createEffect(
+    () => fetchingQueries() > 0,
+    (busy) => {
+      if (timer !== undefined) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+      if (!busy) {
+        setIsDownloading(false);
+        return;
+      }
+      if (downloadDelayMs <= 0) {
+        setIsDownloading(true);
+        return;
+      }
+      timer = setTimeout(() => {
+        timer = undefined;
+        setIsDownloading(true);
+      }, downloadDelayMs);
+    }
+  );
+  onCleanup(() => {
+    if (timer !== undefined) clearTimeout(timer);
+  });
+
+  return {
+    fetchingQueries,
+    pendingMutations,
+    isDownloading,
+    isUploading: () => pendingMutations() > uploadThreshold,
+  };
+}