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

package/dist/bindings/zustand.js

@@ -671,8 +671,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();
@@ -680,6 +679,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);
@@ -704,6 +724,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")