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

package/dist/client.d.ts

@@ -95,6 +95,25 @@ export interface BatchPullOptions {
      *  omit the collection from `params` entirely (an unlisted collection reads one
      *  auto-filled doc). Results come back under the same name in request order. */
     params?: Record<string, Record<string, string>[]>;
+    /**
+     * Per-collection append options, index-aligned to `params`. Makes the batch
+     * request **append/checkpoint-aware**: each entry returns the bounded tail of
+     * that collection's append-only log rather than the full document.
+     *
+     * Serialized as URL-encoded JSON alongside `params`. Server ignores it for
+     * collections that are not append-only (returns `{ error: "append_params_not_supported" }`
+     * for those entries). `full` is disallowed in batch (`full_not_allowed` per entry).
+     *
+     * Example — read the last 5 events for two rooms and the newest item for a third:
+     * ```ts
+     * await client.batchPull(["events"], {
+     *   params: { events: [{ room: "a" }, { room: "b" }, { room: "c" }] },
+     *   appendParams: { events: [{ last: 5 }, { last: 5 }, { last: 1 }] },
+     * })
+     * ```
+     * Each `data[appendField]` in the result is the filtered array for that entry.
+     */
+    appendParams?: Record<string, AppendPullOptions[]>;
 }
 /**
  * Low-level HTTP client for the Starfish sync protocol.
@@ -239,8 +258,7 @@ export declare class StarfishClient {
      *
      * For the common "many docs of one collection" case prefer {@link batchPullMany}.
      *
-     * Note: not append/checkpoint-aware — for incremental append-only reads use
-     * `pull(path, { since })` (or `AppendLogCursor`) per collection.
+     * Pass `appendParams` per entry for append-only bounded-tail reads (see {@link batchPullManyAppend}).
      */
     batchPull(collections: string[], opts?: BatchPullOptions): Promise<BatchPullResult>;
     /**
@@ -251,6 +269,33 @@ export declare class StarfishClient {
      * issues no request and returns `[]`.
      */
     batchPullMany(collection: string, paramsList: Record<string, string>[]): Promise<BatchPullEntry[]>;
+    /**
+     * Convenience over {@link batchPull} for reading append-only bounded tails from
+     * MANY entries of ONE collection in a single round-trip.
+     *
+     * Each request in `requests` carries optional `params` (path params) and
+     * `options` (append bounds: `since`/`last`/`limit`/`appendField`). An empty
+     * `requests` issues no request and returns `[]`.
+     *
+     * Returns an array aligned to `requests` by index. Each element is either:
+     * - the filtered array `T[]` extracted from `entry.data[appendField]`, or
+     * - `{ error: string }` if the server returned a per-entry error.
+     *
+     * The `appendField` used for extraction defaults to `"items"` and can be
+     * overridden per request via `options.appendField`.
+     *
+     * The `appendField` option is client-side only (used for result extraction, not sent to the server).
+     * It must match the collection's server-configured append field and defaults to `"items"`.
+     *
+     * Note: `full: true` is not supported in batch and is rejected client-side
+     * before the request is sent.
+     */
+    batchPullManyAppend<T = unknown>(collection: string, requests: {
+        params?: Record<string, string>;
+        options: AppendPullOptions;
+    }[]): Promise<(T[] | {
+        error: string;
+    })[]>;
     /**
      * Push synced data to the server.
      * @param path - The push endpoint path (e.g. "/push/users/abc/settings")

package/dist/index.js

@@ -446,8 +446,7 @@ var StarfishClient = class {
    *
    * For the common "many docs of one collection" case prefer {@link batchPullMany}.
    *
-   * Note: not append/checkpoint-aware — for incremental append-only reads use
-   * `pull(path, { since })` (or `AppendLogCursor`) per collection.
+   * Pass `appendParams` per entry for append-only bounded-tail reads (see {@link batchPullManyAppend}).
    */
   async batchPull(collections, opts = {}) {
     const search = new URLSearchParams();
@@ -455,6 +454,27 @@ var StarfishClient = class {
     if (opts.params && Object.keys(opts.params).length > 0) {
       search.set("params", JSON.stringify(opts.params));
     }
+    if (opts.appendParams && Object.keys(opts.appendParams).length > 0) {
+      for (const [col, optsArr] of Object.entries(opts.appendParams)) {
+        for (const ap of optsArr) {
+          if (ap.full) {
+            throw new Error(
+              `batchPull: appendParams["${col}"] contains full:true \u2014 full is not supported in batch pull`
+            );
+          }
+          if (ap.since != null && (!Number.isInteger(ap.since) || ap.since < 0)) {
+            throw new Error(`batchPull: appendParams["${col}"].since must be a non-negative integer`);
+          }
+          if (ap.last != null && (!Number.isInteger(ap.last) || ap.last < 0)) {
+            throw new Error(`batchPull: appendParams["${col}"].last must be a non-negative integer`);
+          }
+          if (ap.limit != null && (!Number.isInteger(ap.limit) || ap.limit < 0)) {
+            throw new Error(`batchPull: appendParams["${col}"].limit must be a non-negative integer`);
+          }
+        }
+      }
+      search.set("appendParams", JSON.stringify(opts.appendParams));
+    }
     const pathAndQuery = `${this.applyNamespace("/batch/pull")}?${search.toString()}`;
     const url = `${this.baseUrl}${pathAndQuery}`;
     const authHeaders = await this.buildAuthHeaders("GET", pathAndQuery, void 0);
@@ -479,6 +499,44 @@ var StarfishClient = class {
     const res = await this.batchPull([collection], { params: { [collection]: paramsList } });
     return res.collections[collection] ?? [];
   }
+  /**
+   * Convenience over {@link batchPull} for reading append-only bounded tails from
+   * MANY entries of ONE collection in a single round-trip.
+   *
+   * Each request in `requests` carries optional `params` (path params) and
+   * `options` (append bounds: `since`/`last`/`limit`/`appendField`). An empty
+   * `requests` issues no request and returns `[]`.
+   *
+   * Returns an array aligned to `requests` by index. Each element is either:
+   * - the filtered array `T[]` extracted from `entry.data[appendField]`, or
+   * - `{ error: string }` if the server returned a per-entry error.
+   *
+   * The `appendField` used for extraction defaults to `"items"` and can be
+   * overridden per request via `options.appendField`.
+   *
+   * The `appendField` option is client-side only (used for result extraction, not sent to the server).
+   * It must match the collection's server-configured append field and defaults to `"items"`.
+   *
+   * Note: `full: true` is not supported in batch and is rejected client-side
+   * before the request is sent.
+   */
+  async batchPullManyAppend(collection, requests) {
+    if (requests.length === 0) return [];
+    const paramsList = requests.map((r) => r.params ?? {});
+    const appendParamsList = requests.map(({ options: { appendField: _af, ...wireOpts } }) => wireOpts);
+    const res = await this.batchPull([collection], {
+      params: { [collection]: paramsList },
+      appendParams: { [collection]: appendParamsList }
+    });
+    const entries = res.collections[collection] ?? [];
+    return entries.map((entry, i) => {
+      if (entry.error) return { error: entry.error };
+      const appendField = requests[i]?.options.appendField ?? APPEND_DEFAULT_FIELD;
+      const data = entry.data;
+      const items = data?.[appendField];
+      return Array.isArray(items) ? items : [];
+    });
+  }
   /**
    * Push synced data to the server.
    * @param path - The push endpoint path (e.g. "/push/users/abc/settings")
@@ -723,6 +781,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;
@@ -744,6 +804,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
@@ -778,7 +856,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() {
@@ -794,6 +884,7 @@ var SyncManager = class {
     if (this.aborted) return false;
     this.localData = data;
     this.lastHash = cached.hash;
+    this.seeded = true;
     this.lastFromCache = true;
     return true;
   }
@@ -807,12 +898,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
@@ -831,7 +925,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;
@@ -851,7 +945,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;