@granular-software/sdk 0.4.19 → 0.4.20

package/dist/index.mjs

@@ -11229,6 +11229,28 @@ var STANDARD_MODULES_OPERATIONS = [
 var BUILTIN_MODULES = {
   "standard_modules": STANDARD_MODULES_OPERATIONS
 };
+var DEFAULT_DIRECT_RECORD_OBJECTS_REQUEST_BATCH_SIZE = 100;
+var MAX_RECORD_OBJECTS_CONCURRENCY = 16;
+var DEFAULT_DIRECT_RECORD_OBJECTS_RETRY_COUNT = 3;
+var DEFAULT_DIRECT_RECORD_OBJECTS_RETRY_DELAY_MS = 1e3;
+function planRecordObjectsChunks(records, batchSize) {
+  const total = records.length;
+  const size = Math.max(1, Math.min(batchSize, total));
+  const chunkCount = Math.ceil(total / size);
+  const plans = [];
+  for (let offset = 0, chunkIndex = 0; offset < total; offset += size, chunkIndex += 1) {
+    const slice = records.slice(offset, offset + size);
+    plans.push({ chunkIndex, chunkCount, offset, slice });
+  }
+  return plans;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRetryableRecordObjectsError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return /worker restarted mid-request|econnreset|network|socket connection was closed unexpectedly|timed out/i.test(message);
+}
 function computeEffectKey2(effect) {
   const attachedClass = effect.className?.trim();
   if (!attachedClass) {
@@ -12186,24 +12208,101 @@ var Environment = class extends Session {
   /**
    * Batch version of `recordObject()`.
    *
-   * Sends several upserts through the control-plane batch endpoint so the
-   * server can collapse the graph mutations into far fewer round trips.
+   * Sends rows through the control-plane **`/records/batch`** endpoint in **chunks** (default
+   * **100** records per HTTP request) so individual requests stay bounded and gateway timeouts are
+   * unlikely. Each chunk is retried on transient network / worker errors.
+   *
+   * Use the optional second argument to:
+   * - **`batchSize`** — rows per POST (smaller = more progress events; larger = fewer round trips).
+   * - **`concurrency`** — run up to N chunk POSTs in parallel (capped at 16) when you want lower wall time.
+   * - **`onChunkComplete`** — hook for UIs after each chunk succeeds (row order in the returned array
+   *   always matches `records`; chunk **completion** order may differ when `concurrency > 1`).
+   *
+   * For **asynchronous** ingestion with worker-side batching and aggregate counters (`queued`,
+   * `completed`, …), use **`enqueueRecordImport`** and poll **`getRecordImport`** /
+   * **`getRecordImportSummary`** — best for very large fire-and-forget loads when immediate
+   * synchronous commit of every row is not required.
    */
-  async recordObjects(records) {
+  async recordObjects(records, options) {
     if (!Array.isArray(records) || records.length === 0) {
       return [];
     }
-    const response = await this.controlPlaneRequest(
-      `/control/environments/${this.environmentId}/records/batch`,
-      {
-        method: "POST",
-        body: JSON.stringify({ records })
-      }
+    const batchSize = Math.max(
+      1,
+      Math.min(
+        records.length,
+        options?.batchSize ?? DEFAULT_DIRECT_RECORD_OBJECTS_REQUEST_BATCH_SIZE
+      )
     );
-    return Array.isArray(response.items) ? response.items : [];
+    const concurrency = Math.min(
+      MAX_RECORD_OBJECTS_CONCURRENCY,
+      Math.max(1, options?.concurrency ?? 1)
+    );
+    const plans = planRecordObjectsChunks(records, batchSize);
+    const total = records.length;
+    const results = new Array(total);
+    const onChunk = options?.onChunkComplete;
+    for (let waveStart = 0; waveStart < plans.length; waveStart += concurrency) {
+      const wave = plans.slice(waveStart, waveStart + concurrency);
+      await Promise.all(
+        wave.map(async (plan) => {
+          const { items, durationMs } = await this.executeRecordObjectsChunk(plan.slice);
+          if (items.length !== plan.slice.length) {
+            throw new Error(
+              `recordObjects: chunk ${plan.chunkIndex + 1} returned ${items.length} results, expected ${plan.slice.length}`
+            );
+          }
+          for (let index = 0; index < items.length; index += 1) {
+            results[plan.offset + index] = items[index];
+          }
+          if (onChunk) {
+            const info = {
+              chunkIndex: plan.chunkIndex,
+              totalChunks: plan.chunkCount,
+              offset: plan.offset,
+              recordCount: plan.slice.length,
+              durationMs,
+              results: items
+            };
+            await onChunk(info);
+          }
+        })
+      );
+    }
+    return results;
+  }
+  async executeRecordObjectsChunk(chunk) {
+    const wallStart = Date.now();
+    let lastError;
+    for (let attempt = 1; attempt <= DEFAULT_DIRECT_RECORD_OBJECTS_RETRY_COUNT; attempt += 1) {
+      try {
+        const response = await this.controlPlaneRequest(
+          `/control/environments/${this.environmentId}/records/batch`,
+          {
+            method: "POST",
+            body: JSON.stringify({ records: chunk })
+          }
+        );
+        const items = Array.isArray(response.items) ? response.items : [];
+        return { items, durationMs: Date.now() - wallStart };
+      } catch (error) {
+        lastError = error;
+        if (!isRetryableRecordObjectsError(error) || attempt === DEFAULT_DIRECT_RECORD_OBJECTS_RETRY_COUNT) {
+          throw error;
+        }
+        await sleep(DEFAULT_DIRECT_RECORD_OBJECTS_RETRY_DELAY_MS * attempt);
+      }
+    }
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
   }
   /**
-   * Queue a background record import for this environment.
+   * Queue a background record import for this environment (async worker pipeline).
+   *
+   * **vs `recordObjects`:** this path accepts the full payload in one request, returns an
+   * **`importId`**, and processes rows in the background — use **`getRecordImport`** /
+   * **`getRecordImportSummary`** for progress. Choose it for large bulk loads where you do not
+   * need every row committed before the HTTP call returns. Use **`recordObjects`** when you need
+   * synchronous upserts and fine-grained chunk progress via **`onChunkComplete`**.
    */
   async enqueueRecordImport(records, options = {}) {
     return this.controlPlaneRequest(