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

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

@@ -85,15 +85,15 @@ describe('useSyncActivity', () => {
     });
   });
 
-  it('isUploading needs more than the threshold of queued writes', async () => {
+  it('turns isUploading on after the delay for any queued write, and off at once', async () => {
     const m = mockDb(0, 1);
     await createRoot(async (dispose) => {
-      const a = useSyncActivity(m.db);
+      const a = useSyncActivity(m.db, { uploadDelayMs: 150 });
       await settle();
       expect(a.pendingMutations()).toBe(1);
       expect(a.isUploading()).toBe(false);
-      m.setPending(2);
-      await settle();
+      await vi.advanceTimersByTimeAsync(200);
+      flush();
       expect(a.isUploading()).toBe(true);
       m.setPending(0);
       await settle();
@@ -101,4 +101,34 @@ describe('useSyncActivity', () => {
       dispose();
     });
   });
+
+  it('a write acknowledged inside the delay never shows', async () => {
+    const m = mockDb(0, 0);
+    await createRoot(async (dispose) => {
+      const a = useSyncActivity(m.db, { uploadDelayMs: 150 });
+      await settle();
+      m.setPending(1);
+      await settle();
+      await vi.advanceTimersByTimeAsync(80);
+      m.setPending(0);
+      await settle();
+      await vi.advanceTimersByTimeAsync(300);
+      flush();
+      expect(a.isUploading()).toBe(false);
+      dispose();
+    });
+  });
+
+  it('uploadThreshold holds the mark back until a backlog builds', async () => {
+    const m = mockDb(0, 1);
+    await createRoot(async (dispose) => {
+      const a = useSyncActivity(m.db, { uploadThreshold: 1, uploadDelayMs: 0 });
+      await settle();
+      expect(a.isUploading()).toBe(false);
+      m.setPending(2);
+      await settle();
+      expect(a.isUploading()).toBe(true);
+      dispose();
+    });
+  });
 });

package/src/lib/create-preload.ts

@@ -58,8 +58,9 @@ export function createPreload<
 /**
  * Reactive, fire-and-forget prewarm. Resolves the query (calling it if it's a
  * function so it tracks reactive deps), dedupes on the query's stable identity
- * hash, and warms it into the local cache via `db.preload`. No subscription and
- * no cleanup: preload registers nothing that needs tearing down.
+ * hash, and registers it via `db.preload`: a live query nobody subscribes to,
+ * evicted a ttl after it was registered unless a view mounts it first. Nothing
+ * to clean up here.
  *
  * Typical use: inside a list row, preload the detail query the user is likely
  * to open next, so navigation paints from cache instead of the network.
@@ -109,7 +110,7 @@ export function createPreload<
       if (!query) return;
       void db
         .getSp00ky()
-        .preload(query, { refresh: options?.refresh, staleTime: options?.staleTime });
+        .preload(query, { signal: options?.signal });
     }
   );
 }

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

@@ -13,10 +13,16 @@ export interface UseSyncActivityOptions {
   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.
+   * the outbox. Default 0: any unacknowledged write is upsync worth showing.
    */
   uploadThreshold?: number;
+  /**
+   * How long the outbox must stay above `uploadThreshold` before
+   * `isUploading()` turns on. The mirror of `downloadDelayMs`: a write the
+   * server acknowledges within a round trip never lights the indicator, a
+   * write that is actually waiting does. Default 150 ms.
+   */
+  uploadDelayMs?: number;
 }
 
 export interface UseSyncActivity {
@@ -26,7 +32,10 @@ export interface UseSyncActivity {
   pendingMutations: Accessor<number>;
   /** Fetching for longer than `downloadDelayMs`. Drives a "downloading" mark. */
   isDownloading: Accessor<boolean>;
-  /** More than `uploadThreshold` writes queued. Drives an "uploading" mark. */
+  /**
+   * More than `uploadThreshold` writes have been queued for longer than
+   * `uploadDelayMs`. Drives an "uploading" mark.
+   */
   isUploading: Accessor<boolean>;
 }
 
@@ -34,10 +43,10 @@ export interface UseSyncActivity {
  * 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
+ * not one per query; `pendingMutations` is the outbox depth. Both
+ * `isDownloading` and `isUploading` are debounced ON by their delay (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>(
@@ -51,7 +60,8 @@ export function useSyncActivity<S extends SchemaStructure = any>(
   const options = (explicitDb ? maybeOptions : (dbOrOptions as UseSyncActivityOptions)) ?? {};
   const db = explicitDb ?? useDb<S>();
   const downloadDelayMs = options.downloadDelayMs ?? 200;
-  const uploadThreshold = options.uploadThreshold ?? 1;
+  const uploadThreshold = options.uploadThreshold ?? 0;
+  const uploadDelayMs = options.uploadDelayMs ?? 150;
 
   const fetchingQueries = fromSubscription<number>(
     (cb) => db.subscribeToFetchActivity(cb),
@@ -62,38 +72,41 @@ export function useSyncActivity<S extends SchemaStructure = any>(
     db.pendingMutationCount
   );
 
-  // ON after the delay, OFF immediately. Written from a timer, hence ownedWrite.
-  const [isDownloading, setIsDownloading] = createSignal(false, { ownedWrite: true });
+  const isDownloading = delayedOn(() => fetchingQueries() > 0, downloadDelayMs);
+  const isUploading = delayedOn(() => pendingMutations() > uploadThreshold, uploadDelayMs);
+
+  return { fetchingQueries, pendingMutations, isDownloading, isUploading };
+}
+
+/**
+ * `busy` held for `delayMs`, dropped the instant it clears. Both directions of
+ * traffic use it, so a burst too short to see never flickers the indicator and
+ * neither one can latch on after the work is done.
+ */
+function delayedOn(busy: Accessor<boolean>, delayMs: number): Accessor<boolean> {
+  // Written from a timer, hence ownedWrite.
+  const [on, setOn] = 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);
+  createEffect(busy, (isBusy) => {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
     }
-  );
+    if (!isBusy) {
+      setOn(false);
+      return;
+    }
+    if (delayMs <= 0) {
+      setOn(true);
+      return;
+    }
+    timer = setTimeout(() => {
+      timer = undefined;
+      setOn(true);
+    }, delayMs);
+  });
   onCleanup(() => {
     if (timer !== undefined) clearTimeout(timer);
   });
-
-  return {
-    fetchingQueries,
-    pendingMutations,
-    isDownloading,
-    isUploading: () => pendingMutations() > uploadThreshold,
-  };
+  return on;
 }