@arbidocs/sdk 0.3.44 → 0.3.46

package/dist/{browser-MSSje4v8.d.cts → browser-HVCa8Ph5.d.cts}

@@ -625,6 +625,13 @@ interface ListPaginatedOptions {
      * AbortSignal to cancel iteration mid-stream.
      */
     signal?: AbortSignal;
+    /**
+     * Number of pages kept in flight concurrently. A higher value hides more
+     * backend + network latency between pages but increases peak backend load
+     * and memory for not-yet-consumed pages. Clamped to `[1, MAX_PAGES]`.
+     * @default 3
+     */
+    lookahead?: number;
 }
 /**
  * Options for `listAll` — collects all pages into a single array.
@@ -718,11 +725,19 @@ declare function listDocuments(arbi: ArbiClient): Promise<{
     } | null | undefined;
 }[]>;
 /**
- * Async iterator that yields pages of documents sequentially.
+ * Async iterator that yields pages of documents with a configurable lookahead.
+ *
+ * Uses `limit`/`offset` pagination. A FIFO queue of up to `lookahead` requests
+ * is kept in flight: as soon as a page is awaited off the queue the next
+ * request is enqueued, so the backend is continuously working on the next few
+ * pages while the consumer processes the current one. The default of 3 keeps
+ * three pages in flight, which hides the backend scan + network latency
+ * behind the consumer's per-page work (cache writes, rendering) even on
+ * workspaces large enough for the consumer to be faster than a single page.
  *
- * Fetches pages one at a time using `limit`/`offset` pagination. Sequential
- * (not parallel) because the backend decrypt step is CPU-bound on a shared
- * thread pool — parallel requests contend and don't finish meaningfully faster.
+ * Iteration stops at the first short page (length < `pageSize`) — in-flight
+ * requests past that point are discarded. `MAX_PAGES` is a hard cap on the
+ * number of requests issued.
  *
  * @example
  * ```ts
@@ -732,7 +747,7 @@ declare function listDocuments(arbi: ArbiClient): Promise<{
  * ```
  *
  * @param arbi - Authenticated ArbiClient
- * @param options - Pagination options (pageSize, order, fields, signal)
+ * @param options - Pagination options (pageSize, order, fields, signal, lookahead)
  * @yields Pages of documents until the backend returns a short page or signal is aborted
  */
 declare function listPaginated(arbi: ArbiClient, options?: ListPaginatedOptions): AsyncGenerator<DocResponse[]>;

package/dist/{browser-MSSje4v8.d.ts → browser-HVCa8Ph5.d.ts}

@@ -625,6 +625,13 @@ interface ListPaginatedOptions {
      * AbortSignal to cancel iteration mid-stream.
      */
     signal?: AbortSignal;
+    /**
+     * Number of pages kept in flight concurrently. A higher value hides more
+     * backend + network latency between pages but increases peak backend load
+     * and memory for not-yet-consumed pages. Clamped to `[1, MAX_PAGES]`.
+     * @default 3
+     */
+    lookahead?: number;
 }
 /**
  * Options for `listAll` — collects all pages into a single array.
@@ -718,11 +725,19 @@ declare function listDocuments(arbi: ArbiClient): Promise<{
     } | null | undefined;
 }[]>;
 /**
- * Async iterator that yields pages of documents sequentially.
+ * Async iterator that yields pages of documents with a configurable lookahead.
+ *
+ * Uses `limit`/`offset` pagination. A FIFO queue of up to `lookahead` requests
+ * is kept in flight: as soon as a page is awaited off the queue the next
+ * request is enqueued, so the backend is continuously working on the next few
+ * pages while the consumer processes the current one. The default of 3 keeps
+ * three pages in flight, which hides the backend scan + network latency
+ * behind the consumer's per-page work (cache writes, rendering) even on
+ * workspaces large enough for the consumer to be faster than a single page.
  *
- * Fetches pages one at a time using `limit`/`offset` pagination. Sequential
- * (not parallel) because the backend decrypt step is CPU-bound on a shared
- * thread pool — parallel requests contend and don't finish meaningfully faster.
+ * Iteration stops at the first short page (length < `pageSize`) — in-flight
+ * requests past that point are discarded. `MAX_PAGES` is a hard cap on the
+ * number of requests issued.
  *
  * @example
  * ```ts
@@ -732,7 +747,7 @@ declare function listDocuments(arbi: ArbiClient): Promise<{
  * ```
  *
  * @param arbi - Authenticated ArbiClient
- * @param options - Pagination options (pageSize, order, fields, signal)
+ * @param options - Pagination options (pageSize, order, fields, signal, lookahead)
  * @yields Pages of documents until the backend returns a short page or signal is aborted
  */
 declare function listPaginated(arbi: ArbiClient, options?: ListPaginatedOptions): AsyncGenerator<DocResponse[]>;

package/dist/browser.cjs

@@ -4160,13 +4160,11 @@ async function listDocuments(arbi) {
   return requireData(await arbi.fetch.GET("/v1/document/list"), "Failed to fetch documents");
 }
 async function* listPaginated(arbi, options = {}) {
-  const { pageSize = 5e3, order = "id_asc", fields, signal } = options;
-  let offset = 0;
-  let pagesFetched = 0;
-  while (!signal?.aborted && pagesFetched < MAX_PAGES) {
+  const { pageSize = 5e3, order = "id_asc", fields, signal, lookahead = 3 } = options;
+  const fetchPage = async (pageOffset) => {
     const query = {
       limit: pageSize,
-      offset,
+      offset: pageOffset,
       order
     };
     if (fields) query.fields = fields;
@@ -4177,16 +4175,40 @@ async function* listPaginated(arbi, options = {}) {
     if (error) {
       throw new Error(typeof error === "string" ? error : JSON.stringify(error));
     }
+    return data ?? [];
+  };
+  if (signal?.aborted) return;
+  const depth = Math.max(1, Math.min(lookahead, MAX_PAGES));
+  let issued = 0;
+  let pagesYielded = 0;
+  let nextOffsetToIssue = 0;
+  let done = false;
+  const queue = [];
+  const tryEnqueue = () => {
+    while (!done && queue.length < depth && issued < MAX_PAGES) {
+      const p2 = fetchPage(nextOffsetToIssue);
+      p2.catch(() => {
+      });
+      queue.push(p2);
+      nextOffsetToIssue += pageSize;
+      issued++;
+    }
+  };
+  tryEnqueue();
+  while (queue.length > 0 && !signal?.aborted) {
+    const page = await queue.shift();
     if (signal?.aborted) return;
-    const page = data ?? [];
+    const isShort = page.length < pageSize;
+    if (isShort) done = true;
+    tryEnqueue();
     if (page.length > 0) {
       yield page;
-      offset += page.length;
-      pagesFetched++;
+      pagesYielded++;
     }
-    if (page.length < pageSize) return;
+    if (isShort) return;
+    if (pagesYielded >= MAX_PAGES) break;
   }
-  if (pagesFetched >= MAX_PAGES) {
+  if (!signal?.aborted && !done && pagesYielded >= MAX_PAGES) {
     console.warn(
       `[arbi-sdk] listPaginated hit MAX_PAGES (${MAX_PAGES}) \u2014 stopped. Workspace may have more than ${MAX_PAGES * pageSize} documents.`
     );