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

package/dist/client.d.ts

@@ -54,6 +54,21 @@ export interface PullOptions {
     checkpoint?: number;
     /** Include the sibling `_keyring` document in the response. Defaults to false. */
     withKeyring?: boolean;
+    /**
+     * Serve the last-synced cached snapshot immediately (tagged via
+     * {@link pullWasFromCache}) and revalidate in the background. Requires a
+     * {@link StarfishClientOptions.cache} to be configured; without one the option
+     * is a no-op and the pull goes to the network as usual.
+     *
+     * On a cache hit: returns the stale snapshot at once, kicks a background fetch,
+     * and on success writes the fresh snapshot to cache and fires
+     * {@link StarfishClientOptions.onRevalidated}. Uses the same dedup set as the
+     * {@link StarfishClientOptions.cacheFallbackStatuses} revalidation path — a
+     * concurrent error-triggered loop for the same document is not duplicated.
+     *
+     * On a cache miss: falls through to the normal network-first pull unchanged.
+     */
+    staleWhileRevalidate?: boolean;
 }
 /** Per-collection result in a {@link BatchPullResult}: either the pulled
  *  document (`data`/`hash`/`timestamp`) or a per-collection `error` string. */
@@ -95,6 +110,12 @@ export declare class StarfishClient {
     private readonly cacheFallbackStatuses?;
     private readonly onRevalidated?;
     private readonly revalidating;
+    /**
+     * 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.
+     */
+    private readonly latestCacheTimestamp;
     /**
      * Installed client-side plugins. Currently stored as inert data; no
      * hooks fire yet. Extensions can inspect this list if needed.
@@ -167,14 +188,31 @@ export declare class StarfishClient {
     pull(path: string, options: PullOptions): Promise<PullResult>;
     /** Pull an append-only collection. Extracts and returns `data[appendField]` as `T[]`. */
     pull<T = unknown>(path: string, options: AppendPullOptions): Promise<T[]>;
-    /** Deduplicated fire-and-forget: starts one revalidation loop per cacheKey. */
+    /**
+     * 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.
+     */
+    private writeCache;
+    /** Build the URL + auth headers for one revalidation GET. Shared between
+     *  {@link pull} and {@link revalidateLoop} to avoid duplicated fetch setup. */
+    private revalidateFetch;
+    /**
+     * 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.
+     */
     private scheduleRevalidate;
     /**
-     * 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).
      */
     private revalidateLoop;
     /**

package/dist/index.js

@@ -110,6 +110,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.
@@ -226,11 +232,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) {
@@ -239,6 +246,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)) {
@@ -265,6 +273,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, {
@@ -296,67 +317,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");
@@ -478,15 +519,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;
   }
@@ -767,6 +800,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);
@@ -775,17 +844,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));
@@ -971,20 +1038,22 @@ var AppendLogCursor = class {
       const raw = await this.client.pull(this.pullPath, opts);
       const batch = [];
       const stored = [];
-      let maxTs = since;
       let skipped = 0;
-      for (const el of raw) {
-        if (since > 0 && el.ts <= since) continue;
-        if (el.ts > maxTs) maxTs = el.ts;
-        let decrypted = null;
+      const eligible = raw.filter((el) => !(since > 0 && el.ts <= since));
+      let maxTs = since;
+      for (const el of eligible) if (el.ts > maxTs) maxTs = el.ts;
+      const decryptResults = await Promise.all(eligible.map(async (el) => {
         try {
           this.verifyOne(el);
           const data = this.encryptor ? await this.encryptor.decrypt(el.data) : el.data;
-          decrypted = withAuthor(el.ts, data, el);
+          return { el, decrypted: withAuthor(el.ts, data, el) };
         } catch (err) {
           if (this.onElementError !== "skip") throw err;
           skipped++;
+          return { el, decrypted: null };
         }
+      }));
+      for (const { el, decrypted } of decryptResults) {
         if (this.persistEncrypted) {
           stored.push(withAuthor(el.ts, el.data, el));
         } else if (decrypted) {
@@ -1041,17 +1110,17 @@ var AppendLogCursor = class {
   async getDecryptedItems() {
     const snapshot = [...this.items];
     if (!this.encryptor || !this.persistEncrypted) return snapshot;
-    const out = [];
-    for (const el of snapshot) {
+    const results = await Promise.all(snapshot.map(async (el) => {
       try {
         this.verifyOne(el);
         const data = await this.encryptor.decrypt(el.data);
-        out.push(withAuthor(el.ts, data, el));
+        return withAuthor(el.ts, data, el);
       } catch (err) {
         if (this.onElementError !== "skip") throw err;
+        return null;
       }
-    }
-    return out;
+    }));
+    return results.filter((el) => el !== null);
   }
   /** The current checkpoint: the max `ts` held (the next pull's `since`). `0`
    *  when nothing has been pulled or seeded. */
@@ -1197,8 +1266,7 @@ function shallowEqual(a, b) {
   if (typeof a !== "object") return false;
   if (Array.isArray(a) !== Array.isArray(b)) return false;
   if (Array.isArray(a) && Array.isArray(b)) {
-    if (a.length !== b.length) return false;
-    return a.every((v, i) => shallowEqual(v, b[i]));
+    return a.length === b.length && a.every((v, i) => shallowEqual(v, b[i]));
   }
   const aObj = a;
   const bObj = b;
@@ -1740,12 +1808,8 @@ async function unregisterServiceWorkers() {
   if (!isServiceWorkerSupported()) return false;
   try {
     const registrations = await navigator.serviceWorker.getRegistrations();
-    let unregistered = false;
-    for (const registration of registrations) {
-      const result = await registration.unregister();
-      if (result) unregistered = true;
-    }
-    return unregistered;
+    const results = await Promise.all(registrations.map((r) => r.unregister()));
+    return results.some(Boolean);
   } catch {
     return false;
   }