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

package/dist/sync.d.ts

@@ -71,10 +71,28 @@ export declare class SyncManager {
     private localData;
     private aborted;
     private lastFromCache;
+    /** True once {@link seedFromCache} has successfully seeded localData from the cache. */
+    private seeded;
     constructor(options: SyncManagerOptions);
     abort(): void;
     get isAborted(): boolean;
     getData(): Record<string, unknown>;
+    /**
+     * 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.
+     */
+    private hasMergeBaseline;
     /**
      * Merge a remote snapshot with local (optimistic) data using this manager's
      * conflict resolver — the same resolver the push-conflict path uses. A plain
@@ -101,7 +119,19 @@ export declare class SyncManager {
      * 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`.
      */
     seedFromCache(): Promise<boolean>;
@@ -113,12 +143,15 @@ export declare class SyncManager {
      * {@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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakkar.software/starfish-client",
-  "version": "3.0.0-alpha.37",
+  "version": "3.0.0-alpha.39",
   "repository": {
     "type": "git",
     "url": "https://github.com/Drakkar-Software/starfish.git",
@@ -69,7 +69,7 @@
     }
   },
   "dependencies": {
-    "@drakkar.software/starfish-protocol": "3.0.0-alpha.37"
+    "@drakkar.software/starfish-protocol": "3.0.0-alpha.39"
   },
   "devDependencies": {
     "@legendapp/state": "^2.0.0",