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

package/dist/sync.d.ts

@@ -106,6 +106,28 @@ export declare class SyncManager {
      */
     seedFromCache(): Promise<boolean>;
     getCheckpoint(): number;
+    /**
+     * 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.
+     */
+    ingest(result: PullResult): Promise<void>;
     pull(): Promise<PullResult>;
     push(data: Record<string, unknown>): Promise<{
         hash: string;

package/dist/types.d.ts

@@ -144,15 +144,21 @@ export interface StarfishClientOptions {
      */
     cacheFallbackStatuses?: number[];
     /**
-     * Called after a background revalidation succeeds following a
-     * {@link cacheFallbackStatuses} hit: the server returned a live response and
-     * the fresh snapshot has been written through to the cache.
+     * Called after a background revalidation delivers a fresh snapshot to the
+     * cache. Fires for two revalidation paths:
      *
-     * Use this to signal to the host app that the server is reachable again (e.g.
-     * call `reportReachability(true)`) so any stale views can re-pull and recover.
+     * 1. **Error-triggered** ({@link cacheFallbackStatuses} hit): the server
+     *    returned a transient error (429/5xx), `pull()` served the stale cache,
+     *    and the background retry loop eventually got a live response.
+     * 2. **SWR-on-read** ({@link PullOptions.staleWhileRevalidate}): `pull()`
+     *    served the cache immediately and the background fetch completed.
      *
-     * `path` is the namespaced document path sent to the server (namespace prefix
-     * + path + query string, matching the key under which the snapshot was cached).
+     * In both cases `result` is the fresh `PullResult` just written to cache.
+     * Use this to signal reachability recovery and/or push the fresh data into
+     * any store that is showing the stale snapshot.
+     *
+     * `path` is the namespaced document path (namespace prefix + path + query
+     * string, matching the cache key written by {@link StarfishClient.pull}).
      */
     onRevalidated?: (path: string, result: PullResult) => void;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakkar.software/starfish-client",
-  "version": "3.0.0-alpha.31",
+  "version": "3.0.0-alpha.36",
   "repository": {
     "type": "git",
     "url": "https://github.com/Drakkar-Software/starfish.git",
@@ -64,7 +64,7 @@
     }
   },
   "dependencies": {
-    "@drakkar.software/starfish-protocol": "3.0.0-alpha.31"
+    "@drakkar.software/starfish-protocol": "3.0.0-alpha.36"
   },
   "devDependencies": {
     "@legendapp/state": "^2.0.0",
@@ -78,7 +78,7 @@
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "typescript": "^5.5.0",
-    "vitest": "^3.0.0",
+    "vitest": "^3.2.6",
     "zustand": "^5.0.11"
   },
   "files": [