TransferEngine

Defined in: src/transfers/TransferEngine.ts:121

Executes transfer jobs and produces audit-friendly receipts.

The engine is the lowest-level entry point in the transfer stack: it owns retry policy, attempt history, abort propagation, progress event normalization, and receipt construction. Most callers reach the engine indirectly through runRoute, uploadFile, downloadFile, copyBetween, or TransferQueue; instantiate it directly when you need full control over execution semantics.

Example

import { TransferEngine, type TransferExecutor, type TransferJob } from "@zero-transfer/sdk";

const engine = new TransferEngine();

const executor: TransferExecutor = async ({ job, signal, onProgress }) => {
  onProgress?.({ jobId: job.id, bytesTransferred: 0 });
  // … perform the bytes here, honoring `signal` …
  return { jobId: job.id, bytesTransferred: 1234, completedAt: new Date() };
};

const job: TransferJob = {
  id: "manual-1",
  operation: "upload",
  source: { profile: localProfile, path: "./data.bin" },
  destination: { profile: s3Profile, path: "/data/data.bin" },
};

const receipt = await engine.execute(job, executor, {
  retry: { maxAttempts: 3, baseDelayMs: 250 },
});
console.log(receipt.attempts.length); // 1 on success

Constructors

Constructor

new TransferEngine(options?: TransferEngineOptions): TransferEngine;

Defined in: src/transfers/TransferEngine.ts:129

Creates a transfer engine.

Parameters

Parameter	Type	Description
options	TransferEngineOptions	Optional clock override for deterministic tests.

Returns

TransferEngine

Methods

execute()

execute(
   job: TransferJob,
   executor: TransferExecutor,
options?: TransferEngineExecuteOptions): Promise<TransferReceipt>;

Defined in: src/transfers/TransferEngine.ts:143

Executes a transfer job through a caller-supplied operation.

Parameters

Parameter	Type	Description
job	TransferJob	Job metadata used for correlation and receipts.
executor	TransferExecutor	Concrete transfer operation implementation.
options	TransferEngineExecuteOptions	Optional abort, retry, and progress hooks.

Returns

Promise<TransferReceipt>

Receipt for the completed transfer.

Throws

AbortError When execution is cancelled.

Throws

TransferError When all attempts fail.