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

package/dist/bindings/zustand.d.ts

@@ -119,6 +119,8 @@ export declare function deriveSyncStatus(state: StarfishState): SyncStatus;
 export declare function aggregateSyncStatus(statuses: SyncStatus[]): SyncStatus;
 /** Use the full Starfish store state and actions. */
 export declare function useStarfish(store: StoreApi<StarfishStore>): StarfishStore;
+/** Subscribe to a fine-grained slice of Starfish store state. Avoids re-renders on unrelated field changes. */
+export declare function useStarfishState<T>(store: StoreApi<StarfishStore>, selector: (state: StarfishState) => T): T;
 /** Use only the synced data, with an optional selector for fine-grained subscriptions. */
 export declare function useStarfishData<T = Record<string, unknown>>(store: StoreApi<StarfishStore>, selector?: (data: Record<string, unknown>) => T): T;
 /** Use the derived sync status (synced | syncing | pending | error | offline). */

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.
@@ -545,6 +551,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,
@@ -606,8 +615,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)) {
@@ -1012,20 +1024,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;
@@ -1038,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));
@@ -1343,6 +1365,9 @@ function aggregateSyncStatus(statuses) {
 function useStarfish(store) {
   return useStore(store);
 }
+function useStarfishState(store, selector) {
+  return useStore(store, selector);
+}
 function useStarfishData(store, selector) {
   return useStore(
     store,
@@ -1403,7 +1428,7 @@ function useLastSynced(store) {
   }, [store, computeLabel]);
   useEffect(() => {
     const timer = setInterval(() => {
-      setLabel(computeLabel());
+      if (!document.hidden) setLabel(computeLabel());
     }, 5e3);
     return () => clearInterval(timer);
   }, [computeLabel]);
@@ -1648,6 +1673,7 @@ export {
   useStarfishData,
   useStarfishLog,
   useStarfishLogItems,
+  useStarfishState,
   useSyncInit,
   useSyncStatus
 };