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

package/dist/client.d.ts

@@ -110,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.

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.
@@ -320,6 +326,9 @@ var StarfishClient = class {
    */
   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,
@@ -381,8 +390,11 @@ var StarfishClient = class {
         const res = await this.revalidateFetch(pathAndQuery);
         if (res.ok) {
           const result = await res.json();
-          this.writeCache(cacheKey, result);
-          this.onRevalidated?.(pathAndQuery, result);
+          const latestTs = this.latestCacheTimestamp.get(cacheKey) ?? -1;
+          if (result.timestamp >= latestTs) {
+            this.writeCache(cacheKey, result);
+            this.onRevalidated?.(pathAndQuery, result);
+          }
           return;
         }
         if (!fallbackSet?.has(res.status)) {
@@ -794,20 +806,32 @@ var SyncManager = class {
    * action to absorb a background revalidation result (delivered via
    * {@link StarfishClientOptions.onRevalidated}) into the store.
    *
-   * Unlike {@link pull}, `ingest` never does a deep-merge with the previous
-   * checkpoint — the revalidated result is always a full fresh snapshot. It
-   * sets `lastFromCache = false` (a revalidation is a live response) so the
-   * binding can clear its `stale` flag.
+   * 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) {
-      const decrypted = await this.encryptor.decrypt(result.data);
+      incoming = await this.encryptor.decrypt(result.data);
       if (this.aborted) return;
-      this.localData = decrypted;
     } else {
-      this.localData = result.data;
+      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;
@@ -820,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));