@arbidocs/sdk 0.3.46 → 0.3.47

package/dist/{browser-HVCa8Ph5.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'
@@ -629,7 +636,7 @@ interface ListPaginatedOptions {
      * 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
+     * @default 1
      */
     lookahead?: number;
 }
@@ -729,11 +736,16 @@ declare function listDocuments(arbi: ArbiClient): Promise<{
  *
  * 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.
+ * 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.
  *
  * 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

package/dist/{browser-HVCa8Ph5.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'
@@ -629,7 +636,7 @@ interface ListPaginatedOptions {
      * 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
+     * @default 1
      */
     lookahead?: number;
 }
@@ -729,11 +736,16 @@ declare function listDocuments(arbi: ArbiClient): Promise<{
  *
  * 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.
+ * 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.
  *
  * 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

package/dist/browser.cjs

@@ -4160,10 +4160,17 @@ 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, lookahead = 3 } = options;
-  const fetchPage = async (pageOffset) => {
+  const {
+    pageSize = 5e3,
+    firstPageSize,
+    order = "id_asc",
+    fields,
+    signal,
+    lookahead = 1
+  } = options;
+  const fetchPage = async (pageOffset, limit) => {
     const query = {
-      limit: pageSize,
+      limit,
       offset: pageOffset,
       order
     };
@@ -4186,19 +4193,21 @@ async function* listPaginated(arbi, options = {}) {
   const queue = [];
   const tryEnqueue = () => {
     while (!done && queue.length < depth && issued < MAX_PAGES) {
-      const p2 = fetchPage(nextOffsetToIssue);
-      p2.catch(() => {
+      const limit = issued === 0 && firstPageSize !== void 0 ? firstPageSize : pageSize;
+      const promise = fetchPage(nextOffsetToIssue, limit);
+      promise.catch(() => {
       });
-      queue.push(p2);
-      nextOffsetToIssue += pageSize;
+      queue.push({ limit, promise });
+      nextOffsetToIssue += limit;
       issued++;
     }
   };
   tryEnqueue();
   while (queue.length > 0 && !signal?.aborted) {
-    const page = await queue.shift();
+    const { limit, promise } = queue.shift();
+    const page = await promise;
     if (signal?.aborted) return;
-    const isShort = page.length < pageSize;
+    const isShort = page.length < limit;
     if (isShort) done = true;
     tryEnqueue();
     if (page.length > 0) {