@arbidocs/sdk 0.3.45 → 0.3.47

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

@@ -605,10 +605,17 @@ type DocumentListFields = 'full' | 'lite';
  */
 interface ListPaginatedOptions {
     /**
-     * Number of documents per page.
+     * Number of documents per page (applies to every page after the first).
      * @default 5000
      */
     pageSize?: number;
+    /**
+     * Size of the first page only. When set, the initial request uses this
+     * smaller limit so the caller can render something on screen before the
+     * full `pageSize`-sized pages stream in. Subsequent pages fall back to
+     * `pageSize`. When unset, every page uses `pageSize`.
+     */
+    firstPageSize?: number;
     /**
      * Sort order for pagination.
      * @default 'id_asc'
@@ -625,6 +632,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 1
+     */
+    lookahead?: number;
 }
 /**
  * Options for `listAll` — collects all pages into a single array.
@@ -718,11 +732,24 @@ 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
+ * page while the consumer processes the current one. The default of 1 keeps
+ * one page in flight at a time (classic sequential pagination). Raise it when
+ * you want to pipeline — each extra slot adds one more concurrent backend
+ * scan and one more not-yet-consumed page held in memory.
+ *
+ * Pair `firstPageSize` with a larger `pageSize` when you need the initial
+ * page on screen fast: e.g. `firstPageSize: 500, pageSize: 2000` renders the
+ * first 500 rows in a fifth of the time of a single 2500-row request, then
+ * streams in 2000-row pages after.
  *
- * 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 +759,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-CtYFcHNd.d.ts}

@@ -605,10 +605,17 @@ type DocumentListFields = 'full' | 'lite';
  */
 interface ListPaginatedOptions {
     /**
-     * Number of documents per page.
+     * Number of documents per page (applies to every page after the first).
      * @default 5000
      */
     pageSize?: number;
+    /**
+     * Size of the first page only. When set, the initial request uses this
+     * smaller limit so the caller can render something on screen before the
+     * full `pageSize`-sized pages stream in. Subsequent pages fall back to
+     * `pageSize`. When unset, every page uses `pageSize`.
+     */
+    firstPageSize?: number;
     /**
      * Sort order for pagination.
      * @default 'id_asc'
@@ -625,6 +632,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 1
+     */
+    lookahead?: number;
 }
 /**
  * Options for `listAll` — collects all pages into a single array.
@@ -718,11 +732,24 @@ 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
+ * page while the consumer processes the current one. The default of 1 keeps
+ * one page in flight at a time (classic sequential pagination). Raise it when
+ * you want to pipeline — each extra slot adds one more concurrent backend
+ * scan and one more not-yet-consumed page held in memory.
+ *
+ * Pair `firstPageSize` with a larger `pageSize` when you need the initial
+ * page on screen fast: e.g. `firstPageSize: 500, pageSize: 2000` renders the
+ * first 500 rows in a fifth of the time of a single 2500-row request, then
+ * streams in 2000-row pages after.
  *
- * 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 +759,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,18 @@ 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,
+    firstPageSize,
+    order = "id_asc",
+    fields,
+    signal,
+    lookahead = 1
+  } = options;
+  const fetchPage = async (pageOffset, limit) => {
     const query = {
-      limit: pageSize,
-      offset,
+      limit,
+      offset: pageOffset,
       order
     };
     if (fields) query.fields = fields;
@@ -4177,16 +4182,42 @@ 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 limit = issued === 0 && firstPageSize !== void 0 ? firstPageSize : pageSize;
+      const promise = fetchPage(nextOffsetToIssue, limit);
+      promise.catch(() => {
+      });
+      queue.push({ limit, promise });
+      nextOffsetToIssue += limit;
+      issued++;
+    }
+  };
+  tryEnqueue();
+  while (queue.length > 0 && !signal?.aborted) {
+    const { limit, promise } = queue.shift();
+    const page = await promise;
     if (signal?.aborted) return;
-    const page = data ?? [];
+    const isShort = page.length < limit;
+    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.`
     );