@spooky-sync/client-solid2 0.0.1-canary.238 → 0.0.1-canary.240

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/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,
+  };
+}