SDK storage and batching

The SDK batches remote calls for throughput, but batching is not a transaction. Use Storage upload sessions when bytes are too large for the JSON runtime batch or when a file must be assembled across calls. An upload session is a temporary durable control record, not a file. It stores the intended target, progress, lease, access, retention, metadata, schema, and compute policy. A readable storageEntryId exists only after the session reaches FINALIZED.

Automatic batching

Calls queued in the same microtask are grouped. Promise.all is the normal way to create a batch:

const [customers, agents] = await Promise.all([
  revo.api.getDatabaseData('Customers', { take: 100 }),
  revo.agents.list(),
]);

Sequential awaits naturally dispatch separate batches:

const customers = await revo.api.getDatabaseData('Customers', { take: 100 });
const agents = await revo.agents.list();

Configure batching before the first remote dispatch:

revo.batch.configure({
  failureMode: 'stop',
  maxCalls: 16,
  maxInFlight: 2,
});

Failure mode	Behavior
`independent`	Every valid call runs and its promise settles independently
`stop`	Calls run in order; entries after the first rejection fail with `BATCH_STOPPED`

The SDK defaults to 32 calls, 256 KiB per request, four in-flight batches, and 1,024 queued calls. Client configuration can only lower platform ceilings. The current server envelope allows up to 64 calls, a 1 MiB request, and a 4 MiB response.

Runtime batches are never retried automatically because they can contain mutations. A transport interruption after dispatch produces an indeterminate result; inspect durable state before retrying.

Small objects

Use putObject() when text or base64 data comfortably fits the runtime batch:

const object = await revo.storage.putObject({
  name: 'settings.json',
  data: JSON.stringify({ locale: 'pl-PL', enabled: true }),
  dataEncoding: 'utf8',
  mimeType: 'application/json',
});

console.log(object.storageEntryId);

Binary data must be base64-encoded when sent through this JSON path.

Large uploads with explicit parts

For data generated by the application, an incremental session gives each appended part the next number. Upload calls carry small text or base64 chunks through the SDK, while the durable entry appears only at finalization.

import type { RevoRuntime } from '@revoengine/sdk';

export async function uploadGeneratedCsv(
  runtime: Pick<RevoRuntime, 'storage'>,
  name: string,
  rows: AsyncIterable<string>,
) {
  const { session } = await runtime.storage.createUploadSession({
    name,
    contentTypeHint: 'text/csv',
    uploadMode: 'incremental',
    computeStats: 'sync',
    metadata: { kind: 'customer-export' },
    retention: { ttlSeconds: 30 * 24 * 60 * 60 },
  });

  const sessionId = session.storageUploadSessionId;

  try {
    await runtime.storage.uploadPart(sessionId, {
      data: 'customerId,balance\n',
      dataEncoding: 'utf8',
    });

    for await (const row of rows) {
      await runtime.storage.uploadPart(sessionId, {
        data: `${row}\n`,
        dataEncoding: 'utf8',
      });
    }

    const state = await runtime.storage.getUploadSession(sessionId);
    console.log({ uploadedParts: state.uploadedParts, uploadedBytes: state.uploadedBytes });

    const { entry } = await runtime.storage.finalizeUploadSession(sessionId, {
      computeStats: 'sync',
    });
    return entry;
  } catch (error) {
    await runtime.storage.abortUploadSession(sessionId).catch(() => undefined);
    throw error;
  }
}

For chunked, pass an explicit positive partNumber; re-uploading that number repairs a part. For incremental, omit the number during normal appends but you may still provide one to repair a known part. getUploadSession() exposes the manifest, uploaded bytes, part count, and next number. An active session has a lease: call extendUploadSession() while a long-running producer is still making progress.

Finalization is the durable boundary. A part acknowledged by uploadPart() is not yet a readable Storage entry and must not trigger downstream processing.

Direct browser or Node upload

Choose uploadMode: 'direct' when bytes should travel through the managed upload URL rather than through SDK JSON calls:

createUploadSession({ uploadMode: 'direct', ... })
  -> send bytes to upload.uploadUrl using the exact method and headers
  -> poll getUploadSession(storageUploadSessionId)
  -> continue only when status is FINALIZED and targetStorageEntryId is present

The platform’s managed completion flow finalizes a successful direct upload. Do not call finalization merely because fetch() returned success, and do not infer durable completion from the byte-transfer response alone. Poll the session or react to the resulting Storage event. When an instance returns another upload strategy, follow that strategy and its public completion contract. Upload URLs and headers are temporary credentials. Do not log, persist, or pass them to another principal. If byte transfer fails before completion, abort the active session as a best-effort cleanup.

Read structured files in pages

CSV, TSV, XLSX, NDJSON/JSONL, JSON arrays, and record-oriented XML return structured pages. Follow the opaque cursor instead of assuming the result is an array of text lines. This example reads a CSV file. For XML, pass recordPath to getFileData() and to any explicit getFileStats() call.

let cursor: string | undefined;

do {
  const page = await revo.storage.getFileData(storageEntryId, {
    cursor,
    limit: 25_000,
  });
  if (typeof page === 'string' || Array.isArray(page)) {
    throw new Error('Expected a structured file page');
  }
  await processRows(page.rows);
  cursor = page.nextCursor ?? undefined;
} while (cursor);

getFileData() builds missing structured statistics when needed. If the persisted mapping must be recomputed, call getFileStats(storageEntryId, { reloadStats: true }) first; reloadStats is not a getFileData() option. For XLSX, select sheet when the first visible worksheet is not the intended source. XML requires recordPath. CSV indexing validates quote syntax and source field counts before returning records. STORAGE_CSV_INVALID includes bounded location diagnostics without raw rows or cell values. Its per-record maxRecordBytes guard defaults to 64 MiB independently of read size. Set the same dialect for indexing and reading; quote: false deliberately keeps literal quotes and backslashes and ignores escape. See CSV validation and physical counts. For CSV/TSV, readers default to onError: 'abort'. Set onError: 'skipRow' on statistics and every page read to skip records with the wrong source field count. The returned csvReport contains the exact skipped count and bounded original-file locations for the whole source; do not sum it across pages. Invalid syntax and oversized records still abort. See CSV record error policy for upload settings, walkers, and diagnostic fields. Plain text can still be read through line windows. Explicit mode: 'lines' also reads a CSV as strings without interpreting its fields, preserving headers, blanks and the terminal empty element. That mode is for custom text processing, rather than automatic recovery from malformed CSV. Storage record/line batches are unrelated to SDK request batching. For binary data, getFileData() returns base64. Direct reads are limited to 10 MiB; use buffer: true with an explicit byte start and end for a bounded range.

Large data exports

For a CSV, TSV, NDJSON, or XLSX export of a Table, View, or Materialized View, use revo.api.exportDatabase(name, options) so the platform streams the selected rows directly into Storage. Use the following page-and-upload flow only when the output requires custom Node.js processing or an unsupported format:

request bounded pages rather than one unbounded result;
use a stable unique sort key;
advance pagination only when the previous page made progress;
use a snapshot/version filter if the source can change during export;
generate the file locally in Node.js, then upload it through a session.

For an HTTP source, use api.httpCall({ ... }, { responseType: 'storage', target: { ... } }) so the response is finalized directly into Storage. In Node.js, call this through revo.api or the hosted runtime.api. responseType: 'stream' means a byte/SSE iterator consumed inside low-code V8; the Node.js SDK does not transport those iterators and rejects this mode before dispatch. Use a Storage target or consume the stream inside a low-code execution and return a bounded result. For structured CSV or Excel generation, upload sessions accept rows and worksheet batches with one shared declared schema. See Structured files in Storage. Local Node.js generation remains useful when a report needs a format outside the supported structured-file contract. Callback-based transaction compatibility APIs are intentionally not part of the public SDK. If several remote operations require atomicity, implement that boundary in one RevoEngine component or library where the database transaction context exists. See Storage operations, Storage upload sessions, HTTP integrations, and the generated Storage method reference.

Integrate

Model Context Protocol

Node.js SDK

CLI

VS Code

SDK storage and batching

Automatic batching

Small objects

Large uploads with explicit parts

Direct browser or Node upload

Read structured files in pages

Large data exports

​Automatic batching

​Small objects

​Large uploads with explicit parts

​Direct browser or Node upload

​Read structured files in pages

​Large data exports

Automatic batching

Small objects

Large uploads with explicit parts

Direct browser or Node upload

Read structured files in pages

Large data exports