RevoEngine Documentation

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.

Automatic batching

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

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

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 large text in batches

Text statistics record detected encoding, separator, total line count, batch size, batch count, and the byte-offset map used for bounded reads.

const stats = await revo.storage.getFileStats(storageEntryId, {
  separator: '\n',
  batchSize: 25_000,
});

for (let batchNumber = 1; batchNumber <= (stats.batches ?? 0); batchNumber += 1) {
  const lines = await revo.storage.getFileData(storageEntryId, { batchNumber });
  await processLines(lines);
}

batchNumber is one-based. A batch is a bounded line window backed by cached statistics; it is unrelated to SDK request batching. If statistics are missing, getFileData() can build them before reading. Use reloadStats: true only when the cached mapping must be recomputed. 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

When exporting database rows:

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 that already exposes a stream, a RevoEngine Component can instead use api.httpCall({ ... }, { responseType: 'stream', target: { ... } }) so the response is finalized directly into Storage. 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, HTTP and Storage, and the generated Storage method reference.

Integrate

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 large text in batches

Large data exports

​Automatic batching

​Small objects

​Large uploads with explicit parts

​Direct browser or Node upload

​Read large text in batches

​Large data exports

Automatic batching

Small objects

Large uploads with explicit parts

Direct browser or Node upload

Read large text in batches

Large data exports