@drakkar.software/starfish-client 3.0.0-alpha.31 → 3.0.0-alpha.36

package/README.md

@@ -211,7 +211,8 @@ Pass a `cache` (a `PullCache`: `{ get(k): Promise<string|null>; set(k, v): Promi
 - **Write-through:** a successful pull stores the raw `{data, hash, timestamp}` keyed by document path.
 - **Offline fallback (without a persist-backed store):** a pull that fails because the **transport** is unreachable returns the last cached snapshot, tagged so callers can tell it's stale (`pullWasFromCache(result)`).
 - **Real HTTP errors propagate:** 404/403 are genuine server answers — the cache is *not* consulted, so "no document yet" and "access denied" keep their meaning. 429 and 5xx can optionally be caught via `cacheFallbackStatuses` (see below).
-- **Stale-while-revalidate:** set `cacheFallbackStatuses: [429, 500, 502, 503, 504]` to make transient server failures serve the last-synced snapshot immediately and retry in the background (honoring `Retry-After`). When the live response arrives, the cache is updated and `onRevalidated` fires. No snapshot → the error propagates as usual. Do NOT include 403/404 — they are genuine answers, not transient failures.
+- **Error-triggered stale-while-revalidate:** set `cacheFallbackStatuses: [429, 500, 502, 503, 504]` to make transient server failures serve the last-synced snapshot immediately and retry in the background (honoring `Retry-After`). When the live response arrives, the cache is updated and `onRevalidated` fires. No snapshot → the error propagates as usual. Do NOT include 403/404 — they are genuine answers, not transient failures.
+- **Proactive stale-while-revalidate (`staleWhileRevalidate` pull option):** pass `{ staleWhileRevalidate: true }` to `client.pull(path, { staleWhileRevalidate: true })` to serve the cached snapshot immediately and revalidate in the background on every read (not just on errors). On a cache hit the cached result is returned at once (tagged via `pullWasFromCache`) and the background fetch fires immediately (no initial delay). On a miss it falls through to a normal network-first pull. `onRevalidated` fires on success with the fresh `PullResult`. Both SWR paths share the same dedup loop — a concurrent error-triggered loop and an SWR-on-read loop for the same document collapse to one.
 - **`cacheMaxAgeMs`:** an entry older than this is treated as a miss (both cache-first paint and offline fallback); omit for entries that never expire (recommended for offline-first, where any last-synced data beats none).
 - **Ciphertext-at-rest by construction:** the cache stores the raw server payload, which for E2E (`delegated`) collections is the sealed ciphertext the server holds — never the decrypted form. Decryption happens in memory on read (see `SyncManager.seedFromCache`).
 - **`client.peekCache(path)`** reads the cached snapshot *without* a network round-trip — the basis for cache-first paint.
@@ -233,6 +234,9 @@ new SyncManager({
 - `encryptor` is the only encryption option — the v2 single-secret `encryptionSecret`/`encryptionSalt` shorthand was removed in v3.
 - `onConflict` resolves write conflicts on push *and* reconciles a pull against un-pushed local writes. On a zustand-bound store, a `pull()` while the store is `dirty` merges the fetched snapshot with the local data through this resolver (rather than overwriting it), so an optimistic write isn't lost when a pull races a `set()`. Use a union/CRDT-style resolver (`createUnionMerge`) for append-style collections so both the local and remote writes survive; `SyncManager.resolve(local, remote)` exposes the same merge for callers that need it.
 - **Offline-first:** Zustand stores backed by `storage` are offline-first without any client `cache` — a transport failure during `pull()` preserves the persisted data and sets `stale: true` on the store. When a client `cache` is also configured, `seedFromCache()` additionally populates `localData` from the ciphertext cache without a network round-trip (decrypting in memory for E2E collections); `getLastPullFromCache()` reports whether the latest `pull()`/seed came from that cache. On a zustand store, the `stale` flag tracks both sources: it is set by an offline `pull()` (no cache needed) and by `seed()` (cache-first paint before the initial live pull).
+- **`SyncManager.ingest(result: PullResult)`** applies an externally-delivered `PullResult` to the manager's state (decrypting for E2E, updating `localData`/`lastHash`/`lastCheckpoint`, clearing `lastFromCache`) without a network call. Used by the zustand binding's `mergeResult` action to absorb background revalidation results.
+
+**Auto-merge on revalidation:** when `cacheFallbackStatuses` or `staleWhileRevalidate` triggers a background revalidation, `useSyncInit` and `acquireSyncStore` automatically push the fresh `PullResult` into the bound store via `mergeResult` — the store repaints without waiting for the next explicit `pull()`. The consumer's own `onRevalidated` callback is still called after the store update. The `mergeResult` store action is also available for manual use when a caller holds a fresh `PullResult` it wants to push into the store without an extra round-trip.
 
 ## `AppendLogCursor`
 

package/dist/bindings/zustand.d.ts

@@ -1,7 +1,7 @@
 import { type StoreApi } from "zustand/vanilla";
 import { type StateStorage } from "zustand/middleware";
 import type { DevtoolsOptions } from "zustand/middleware";
-import type { Encryptor } from "@drakkar.software/starfish-protocol";
+import type { Encryptor, PullResult } from "@drakkar.software/starfish-protocol";
 import { SyncManager } from "../sync.js";
 import { AppendLogCursor, type AppendElement } from "../append-log.js";
 import type { StarfishClientOptions, StarfishCapProvider, ConflictResolver, PullCache } from "../types.js";
@@ -39,6 +39,18 @@ export interface StarfishActions {
      * pull; the live pull then supersedes the seeded snapshot.
      */
     seed: () => Promise<void>;
+    /**
+     * Apply a freshly-fetched `PullResult` to the store WITHOUT firing a network
+     * request. Decrypts in memory for E2E collections, conflict-merges against
+     * any local optimistic writes (same logic as a live pull), and clears `stale`.
+     *
+     * Primarily called automatically by the binding when
+     * {@link StarfishClientOptions.onRevalidated} fires (background revalidation
+     * delivered a fresh snapshot after a 429/5xx hit or an SWR-on-read). Also
+     * available for manual use when a caller holds a fresh `PullResult` it wants
+     * to push into the store without a second network round-trip.
+     */
+    mergeResult: (result: PullResult) => Promise<void>;
 }
 export type StarfishStore = StarfishState & StarfishActions;
 export interface CreateStarfishStoreOptions {

package/dist/bindings/zustand.js

@@ -335,6 +335,12 @@ var StarfishClient = class {
   cacheFallbackStatuses;
   onRevalidated;
   revalidating = /* @__PURE__ */ new Set();
+  /**
+   * In-memory mirror of the latest document timestamp written to each cache
+   * key via {@link writeCache}. Updated synchronously so {@link revalidateLoop}
+   * can guard against stale overwrites without an extra async cache read.
+   */
+  latestCacheTimestamp = /* @__PURE__ */ new Map();
   /**
    * Installed client-side plugins. Currently stored as inert data; no
    * hooks fire yet. Extensions can inspect this list if needed.
@@ -451,11 +457,12 @@ var StarfishClient = class {
   async pull(path, checkpointOrOptions) {
     let pathAndQuery = this.applyNamespace(path);
     let appendField;
+    let swr = false;
     if (typeof checkpointOrOptions === "number") {
       if (checkpointOrOptions) pathAndQuery += `?checkpoint=${checkpointOrOptions}`;
     } else if (checkpointOrOptions != null) {
       const opts = checkpointOrOptions;
-      const isPullOptions = opts.withKeyring !== void 0 || opts.checkpoint !== void 0;
+      const isPullOptions = opts.withKeyring !== void 0 || opts.checkpoint !== void 0 || opts.staleWhileRevalidate !== void 0;
       const params = new URLSearchParams();
       if (isPullOptions) {
         if (opts.checkpoint != null && opts.checkpoint > 0) {
@@ -464,6 +471,7 @@ var StarfishClient = class {
         if (opts.withKeyring) {
           params.set("withKeyring", "1");
         }
+        swr = opts.staleWhileRevalidate === true;
       } else {
         appendField = opts.appendField ?? APPEND_DEFAULT_FIELD;
         if (opts.full && (opts.since != null || opts.limit != null || opts.last != null)) {
@@ -490,6 +498,19 @@ var StarfishClient = class {
     const url = `${this.baseUrl}${pathAndQuery}`;
     const authHeaders = await this.buildAuthHeaders("GET", pathAndQuery, void 0);
     const cacheKey = this.cache && appendField === void 0 ? pullCacheKey(pathAndQuery) : void 0;
+    if (swr && cacheKey) {
+      const cached = await this.readCache(cacheKey);
+      if (cached) {
+        this.scheduleRevalidate(
+          cacheKey,
+          pathAndQuery,
+          null,
+          /* immediate */
+          true
+        );
+        return cached;
+      }
+    }
     let res;
     try {
       res = await this.fetch(url, {
@@ -521,67 +542,87 @@ var StarfishClient = class {
       const list = result.data?.[appendField];
       return Array.isArray(list) ? list : [];
     }
-    if (cacheKey) {
-      const snapshot = {
-        data: result.data,
-        hash: result.hash,
-        timestamp: result.timestamp,
-        cachedAt: Date.now()
-      };
-      void this.cache.set(cacheKey, JSON.stringify(snapshot)).catch(() => {
-      });
-    }
+    if (cacheKey) this.writeCache(cacheKey, result);
     return result;
   }
-  /** Deduplicated fire-and-forget: starts one revalidation loop per cacheKey. */
-  scheduleRevalidate(cacheKey, pathAndQuery, retryAfterHeader) {
+  /**
+   * Write a pull snapshot to the cache. Fire-and-forget; errors are swallowed
+   * so a failing cache never blocks the caller. No-op when no cache is configured.
+   */
+  writeCache(cacheKey, result) {
+    if (!this.cache) return;
+    if (result.timestamp > (this.latestCacheTimestamp.get(cacheKey) ?? -1)) {
+      this.latestCacheTimestamp.set(cacheKey, result.timestamp);
+    }
+    const snapshot = {
+      data: result.data,
+      hash: result.hash,
+      timestamp: result.timestamp,
+      cachedAt: Date.now()
+    };
+    void this.cache.set(cacheKey, JSON.stringify(snapshot)).catch(() => {
+    });
+  }
+  /** Build the URL + auth headers for one revalidation GET. Shared between
+   *  {@link pull} and {@link revalidateLoop} to avoid duplicated fetch setup. */
+  async revalidateFetch(pathAndQuery) {
+    const url = `${this.baseUrl}${pathAndQuery}`;
+    const authHeaders = await this.buildAuthHeaders("GET", pathAndQuery, void 0);
+    return this.fetch(url, {
+      method: "GET",
+      headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders }
+    });
+  }
+  /**
+   * Deduplicated fire-and-forget: starts one revalidation loop per cacheKey.
+   * Used by both the {@link cacheFallbackStatuses} error path (delayed first
+   * attempt, honoring `Retry-After`) and the {@link PullOptions.staleWhileRevalidate}
+   * read path (`immediate: true` — no initial delay on the first attempt). The
+   * `revalidating` set deduplicates across both triggers so a concurrent
+   * error-triggered loop and an SWR-on-read loop for the same key collapse to one.
+   */
+  scheduleRevalidate(cacheKey, pathAndQuery, retryAfterHeader, immediate = false) {
     if (this.revalidating.has(cacheKey)) return;
     this.revalidating.add(cacheKey);
-    void this.revalidateLoop(cacheKey, pathAndQuery, retryAfterHeader).finally(() => {
+    void this.revalidateLoop(cacheKey, pathAndQuery, retryAfterHeader, immediate).finally(() => {
       this.revalidating.delete(cacheKey);
     });
   }
   /**
-   * Background revalidation loop for a {@link cacheFallbackStatuses} hit.
-   * Retries the pull (honoring `Retry-After`) up to {@link MAX_REVALIDATE_ATTEMPTS}
-   * times. On a live 2xx response the fresh snapshot is written through to the
-   * cache and {@link onRevalidated} fires. Stops early on a non-fallback HTTP
-   * status (e.g. 404/403 — the server gave a genuine answer).
+   * Background revalidation loop shared by both {@link cacheFallbackStatuses}
+   * hits and {@link PullOptions.staleWhileRevalidate} reads.
+   *
+   * Retries (honoring `Retry-After`) up to {@link MAX_REVALIDATE_ATTEMPTS} times.
+   * When `immediate` is true the first attempt fires without any initial delay
+   * (SWR-on-read path). On a live 2xx the fresh snapshot is written to cache and
+   * {@link onRevalidated} fires. Stops early on a non-fallback status (403/404).
    */
-  async revalidateLoop(cacheKey, pathAndQuery, firstRetryAfter) {
+  async revalidateLoop(cacheKey, pathAndQuery, firstRetryAfter, immediate = false) {
     let retryAfterHeader = firstRetryAfter;
+    const fallbackSet = this.cacheFallbackStatuses ? new Set(this.cacheFallbackStatuses) : null;
     for (let attempt = 0; attempt < MAX_REVALIDATE_ATTEMPTS; attempt++) {
-      const delay = parseRetryAfterMs(retryAfterHeader, {
-        fallbackMs: Math.min(
-          REVALIDATE_INITIAL_DELAY_MS * Math.pow(2, attempt),
-          REVALIDATE_MAX_DELAY_MS
-        ),
-        maxMs: REVALIDATE_MAX_DELAY_MS
-      });
-      await sleep(delay);
-      try {
-        const url = `${this.baseUrl}${pathAndQuery}`;
-        const authHeaders = await this.buildAuthHeaders("GET", pathAndQuery, void 0);
-        const res = await this.fetch(url, {
-          method: "GET",
-          headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders }
+      if (!immediate || attempt > 0) {
+        const delay = parseRetryAfterMs(retryAfterHeader, {
+          fallbackMs: Math.min(
+            REVALIDATE_INITIAL_DELAY_MS * Math.pow(2, attempt),
+            REVALIDATE_MAX_DELAY_MS
+          ),
+          maxMs: REVALIDATE_MAX_DELAY_MS
         });
+        await sleep(delay);
+      }
+      try {
+        const res = await this.revalidateFetch(pathAndQuery);
         if (res.ok) {
           const result = await res.json();
-          if (this.cache) {
-            const snapshot = {
-              data: result.data,
-              hash: result.hash,
-              timestamp: result.timestamp,
-              cachedAt: Date.now()
-            };
-            void this.cache.set(cacheKey, JSON.stringify(snapshot)).catch(() => {
-            });
+          const latestTs = this.latestCacheTimestamp.get(cacheKey) ?? -1;
+          if (result.timestamp >= latestTs) {
+            this.writeCache(cacheKey, result);
+            this.onRevalidated?.(pathAndQuery, result);
           }
-          this.onRevalidated?.(pathAndQuery, result);
           return;
         }
-        if (!this.cacheFallbackStatuses?.includes(res.status)) {
+        if (!fallbackSet?.has(res.status)) {
           return;
         }
         retryAfterHeader = res.headers.get("Retry-After");
@@ -703,15 +744,7 @@ var StarfishClient = class {
     const result = await res.json();
     if (this.cache) {
       const pullPath = sendPath.replace("/push/", "/pull/");
-      const cacheKey = pullCacheKey(pullPath);
-      const snapshot = {
-        data,
-        hash: result.hash,
-        timestamp: result.timestamp,
-        cachedAt: Date.now()
-      };
-      void this.cache.set(cacheKey, JSON.stringify(snapshot)).catch(() => {
-      });
+      this.writeCache(pullCacheKey(pullPath), { data, hash: result.hash, timestamp: result.timestamp });
     }
     return result;
   }
@@ -985,6 +1018,42 @@ var SyncManager = class {
   getCheckpoint() {
     return this.lastCheckpoint;
   }
+  /**
+   * Apply a freshly-fetched `PullResult` to this manager's state WITHOUT
+   * firing a network request. Used by the zustand binding's `mergeResult`
+   * action to absorb a background revalidation result (delivered via
+   * {@link StarfishClientOptions.onRevalidated}) into the store.
+   *
+   * Like {@link pull}, `ingest` conflict-merges the snapshot against the
+   * established baseline via `this.onConflict` when a checkpoint exists — so a
+   * union-merge store does not lose array items when a revalidation result
+   * (e.g. a stale cache-fallback on 429/5xx) is a shorter snapshot. The first
+   * ingest (no checkpoint yet) takes the snapshot wholesale. Sets
+   * `lastFromCache = false` (a revalidation is a live response) so the binding
+   * can clear its `stale` flag.
+   *
+   * **Staleness guard**: if a `push()` advanced `lastCheckpoint` between the
+   * time the revalidation request was sent and the time it resolves, the
+   * result is from an older document version. Ingesting it would clobber the
+   * user's just-saved edit and reset `lastHash` to a stale server hash
+   * (causing a spurious 409 on the next push). We silently drop the result in
+   * that case — the store's post-push state is already correct.
+   */
+  async ingest(result) {
+    if (this.aborted) return;
+    if (result.timestamp < this.lastCheckpoint) return;
+    let incoming;
+    if (this.encryptor) {
+      incoming = await this.encryptor.decrypt(result.data);
+      if (this.aborted) return;
+    } else {
+      incoming = result.data;
+    }
+    this.localData = this.lastCheckpoint > 0 ? this.onConflict(this.localData, incoming) : incoming;
+    this.lastHash = result.hash;
+    this.lastCheckpoint = result.timestamp;
+    this.lastFromCache = false;
+  }
   async pull() {
     if (this.aborted) throw new AbortError();
     this.logger?.pullStart(this.loggerName);
@@ -993,17 +1062,15 @@ var SyncManager = class {
       const result = await this.client.pull(this.pullPath, this.lastCheckpoint);
       if (this.aborted) throw new AbortError();
       this.lastFromCache = pullWasFromCache(result);
+      let incoming;
       if (this.encryptor) {
-        const decrypted = await this.encryptor.decrypt(result.data);
+        incoming = await this.encryptor.decrypt(result.data);
         if (this.aborted) throw new AbortError();
-        this.localData = decrypted;
-        result.data = decrypted;
-      } else if (this.lastCheckpoint > 0) {
-        this.localData = deepMerge(this.localData, result.data);
-        result.data = this.localData;
       } else {
-        this.localData = result.data;
+        incoming = result.data;
       }
+      this.localData = this.lastCheckpoint > 0 ? this.onConflict(this.localData, incoming) : incoming;
+      result.data = this.localData;
       this.lastHash = result.hash;
       this.lastCheckpoint = result.timestamp;
       this.logger?.pullSuccess(this.loggerName, Math.round(performance.now() - start));
@@ -1183,6 +1250,14 @@ function createStarfishStore(options) {
       retryTimer = void 0;
       retryAttempt = 0;
     };
+    const commitRemote = (label) => {
+      const remote = syncManager.getData();
+      const newData = get().dirty ? syncManager.resolve(get().data, remote) : remote;
+      set({ data: newData, syncing: false, hash: syncManager.getHash(), stale: syncManager.getLastPullFromCache() }, false, label);
+      if (get().online && get().dirty) get().flush().catch(() => {
+      });
+      options.onRemoteUpdate?.(newData);
+    };
     return {
       data: {},
       syncing: false,
@@ -1201,15 +1276,10 @@ function createStarfishStore(options) {
         }
       },
       pull: async () => {
-        set({ syncing: true, error: null }, false, "pull/start");
+        set(get().stale ? { error: null } : { syncing: true, error: null }, false, "pull/start");
         try {
           await syncManager.pull();
-          const remote = syncManager.getData();
-          const newData = get().dirty ? syncManager.resolve(get().data, remote) : remote;
-          set({ data: newData, syncing: false, hash: syncManager.getHash(), stale: syncManager.getLastPullFromCache() }, false, "pull/success");
-          if (get().online && get().dirty) get().flush().catch(() => {
-          });
-          options.onRemoteUpdate?.(newData);
+          commitRemote("pull/success");
         } catch (err) {
           if (classifyError(err) === "network") {
             set({ syncing: false, stale: true }, false, "pull/offline");
@@ -1218,6 +1288,10 @@ function createStarfishStore(options) {
           set({ syncing: false, error: err instanceof Error ? err.message : String(err) }, false, "pull/error");
         }
       },
+      mergeResult: async (result) => {
+        await syncManager.ingest(result);
+        commitRemote("merge/success");
+      },
       set: (modifier) => {
         try {
           const next = options.produce ? options.produce(get().data, modifier) : modifier(get().data);
@@ -1362,10 +1436,7 @@ function useSyncInit(config) {
   const onDataRef = useRef(config?.onData);
   onDataRef.current = config?.onData;
   useEffect(() => {
-    if (!config) {
-      setStore(null);
-      return;
-    }
+    if (!config) return;
     const client = new StarfishClient({
       baseUrl: config.serverUrl,
       namespace: config.namespace,
@@ -1374,7 +1445,15 @@ function useSyncInit(config) {
       cache: config.cache,
       cacheMaxAgeMs: config.cacheMaxAgeMs,
       cacheFallbackStatuses: config.cacheFallbackStatuses,
-      onRevalidated: config.onRevalidated
+      // Auto-merge: when a background revalidation delivers a fresh snapshot,
+      // push it into the store so the UI heals without waiting for the next pull.
+      // newStore is referenced by closure — safe because onRevalidated only fires
+      // asynchronously, well after the store is created below.
+      onRevalidated: (path, result) => {
+        newStore.getState().mergeResult(result).catch(() => {
+        });
+        config.onRevalidated?.(path, result);
+      }
     });
     const syncManager = new SyncManager({
       client,
@@ -1416,7 +1495,7 @@ function useSyncInit(config) {
     config?.encryptor,
     config?.storeName
   ]);
-  return store;
+  return config ? store : null;
 }
 var _syncStoreRegistry = /* @__PURE__ */ new Map();
 function acquireSyncStore(config) {
@@ -1433,7 +1512,14 @@ function acquireSyncStore(config) {
     cache: config.cache,
     cacheMaxAgeMs: config.cacheMaxAgeMs,
     cacheFallbackStatuses: config.cacheFallbackStatuses,
-    onRevalidated: config.onRevalidated
+    // Auto-merge: push fresh revalidated snapshots into the store.
+    // store is referenced by closure — safe because onRevalidated only fires
+    // asynchronously, well after the store is created below.
+    onRevalidated: (path, result) => {
+      store.getState().mergeResult(result).catch(() => {
+      });
+      config.onRevalidated?.(path, result);
+    }
   });
   const syncManager = new SyncManager({
     client,
@@ -1475,10 +1561,7 @@ function useSharedSyncStore(config) {
   const configRef = useRef(config);
   configRef.current = config;
   useEffect(() => {
-    if (!storeName) {
-      setStore(null);
-      return;
-    }
+    if (!storeName) return;
     const acquired = acquireSyncStore(configRef.current);
     setStore(acquired);
     return () => {
@@ -1486,7 +1569,7 @@ function useSharedSyncStore(config) {
       setStore(null);
     };
   }, [storeName]);
-  return store;
+  return storeName ? store : null;
 }
 function createStarfishLog(options) {
   const { cursor } = options;