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

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

@@ -941,6 +941,8 @@ var SyncManager = class {
   localData = {};
   aborted = false;
   lastFromCache = false;
+  /** True once {@link seedFromCache} has successfully seeded localData from the cache. */
+  seeded = false;
   constructor(options) {
     this.client = options.client;
     this.pullPath = options.pullPath;
@@ -962,6 +964,24 @@ var SyncManager = class {
   getData() {
     return { ...this.localData };
   }
+  /**
+   * Returns true when `pull()` / `ingest()` should merge against the current
+   * `localData` rather than replace it wholesale.
+   *
+   * Two situations establish a merge baseline:
+   * - A successful prior pull/ingest advanced `lastCheckpoint` beyond 0 (the
+   *   normal steady-state case, unchanged since alpha.36).
+   * - A cache seed painted `localData` via {@link seedFromCache} AND the store
+   *   uses a custom conflict resolver (i.e. NOT the default `deepMerge`). For a
+   *   union/custom resolver the seeded snapshot is a real baseline that must not
+   *   be clobbered by a short first live response (a cache-fallback on 429/5xx
+   *   or a momentarily-short concurrent server snapshot). For the default
+   *   `deepMerge` resolver we keep the pre-fix wholesale-replace behaviour so
+   *   non-union stores are byte-identical to alpha.36.
+   */
+  hasMergeBaseline() {
+    return this.lastCheckpoint > 0 || this.seeded && this.onConflict !== deepMerge;
+  }
   /**
    * Merge a remote snapshot with local (optimistic) data using this manager's
    * conflict resolver — the same resolver the push-conflict path uses. A plain
@@ -996,7 +1016,19 @@ var SyncManager = class {
    * WITHOUT touching the network, decrypting in memory for E2E collections.
    * Returns whether anything was seeded (false on a miss, an expired entry, or
    * a decrypt failure — e.g. keyring skew). Call once on store creation before
-   * the initial live {@link pull}, which then supersedes the seeded snapshot.
+   * the initial live {@link pull}.
+   *
+   * `lastCheckpoint` is intentionally left at 0 so the first live pull sends a
+   * full (re)sync request to the server, not a delta. However, for stores with
+   * a custom conflict resolver (e.g. `createUnionMerge`) the seeded snapshot is
+   * treated as a merge baseline: {@link hasMergeBaseline} returns true, so the
+   * first pull/ingest merges against the seed rather than replacing it wholesale.
+   * This closes the bootstrap window where a short first-pull response (a cache-
+   * fallback on 429/5xx or a momentarily-short concurrent snapshot) would
+   * silently drop items the resolver was configured to preserve. For the default
+   * `deepMerge` resolver the first pull still takes the snapshot wholesale —
+   * behaviour is byte-identical to alpha.36.
+   *
    * Requires the client to have been built with a `cache`.
    */
   async seedFromCache() {
@@ -1012,6 +1044,7 @@ var SyncManager = class {
     if (this.aborted) return false;
     this.localData = data;
     this.lastHash = cached.hash;
+    this.seeded = true;
     this.lastFromCache = true;
     return true;
   }
@@ -1025,12 +1058,15 @@ var SyncManager = class {
    * {@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.
+   * established baseline via `this.onConflict` when a merge baseline exists
+   * ({@link hasMergeBaseline}) — 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 baseline is established by either a prior
+   * pull/ingest that advanced `lastCheckpoint`, or by a successful
+   * {@link seedFromCache} for a store with a custom resolver. The first ingest
+   * without such a baseline takes the snapshot wholesale (default `deepMerge`
+   * stores are byte-identical to alpha.36). 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
@@ -1049,7 +1085,7 @@ var SyncManager = class {
     } else {
       incoming = result.data;
     }
-    this.localData = this.lastCheckpoint > 0 ? this.onConflict(this.localData, incoming) : incoming;
+    this.localData = this.hasMergeBaseline() ? this.onConflict(this.localData, incoming) : incoming;
     this.lastHash = result.hash;
     this.lastCheckpoint = result.timestamp;
     this.lastFromCache = false;
@@ -1069,7 +1105,7 @@ var SyncManager = class {
       } else {
         incoming = result.data;
       }
-      this.localData = this.lastCheckpoint > 0 ? this.onConflict(this.localData, incoming) : incoming;
+      this.localData = this.hasMergeBaseline() ? this.onConflict(this.localData, incoming) : incoming;
       result.data = this.localData;
       this.lastHash = result.hash;
       this.lastCheckpoint = result.timestamp;
@@ -1365,6 +1401,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,
@@ -1425,7 +1464,7 @@ function useLastSynced(store) {
   }, [store, computeLabel]);
   useEffect(() => {
     const timer = setInterval(() => {
-      setLabel(computeLabel());
+      if (!document.hidden) setLabel(computeLabel());
     }, 5e3);
     return () => clearInterval(timer);
   }, [computeLabel]);
@@ -1670,6 +1709,7 @@ export {
   useStarfishData,
   useStarfishLog,
   useStarfishLogItems,
+  useStarfishState,
   useSyncInit,
   useSyncStatus
 };