Resumable uploads
Pause, resume, and abort a large upload via a control handle, or resume it in a later process from a serializable session token. A per-call option on upload.
A long upload over a flaky connection shouldn’t have to start over when it’s interrupted. Pass an UploadControl to upload and you can pause() it, resume() it, or abort() it — and, because the control holds a serializable session token, you can persist it and resume the upload in a later process, after a crash, or on the next page load.
import { Files, UploadControl } from "files-sdk";
const control = new UploadControl();
const result = files.upload("backups/db.tar", file, {
control,
multipart: { partSize: 16 * 1024 * 1024 },
onProgress: ({ loaded, total }) =>
console.log(total ? `${Math.round((loaded / total) * 100)}%` : `${loaded}`),
});
control.pause(); // in-flight parts settle; `result` stays pending
control.resume(); // pick up where it left off
await result;
It’s an AbortSignal-style handle: a plain object you construct and hand in, then drive from the outside. The upload call returns its usual promise, which resolves when the upload completes (and stays pending while paused).
Resuming across processes
control.toJSON() returns a small JSON-serializable token describing the provider-side session. Persist it wherever you like — a file on disk, a database row keyed by the user’s upload. Later, rebuild a control from it with UploadControl.from(token) and call upload again with the same body: the SDK discovers what already landed server-side and uploads only the rest.
import { readFile, writeFile } from "node:fs/promises";
// First run — pause and persist.
const control = new UploadControl();
files.upload("backups/db.tar", file, { control }).catch(() => {});
// …once a session exists, control.toJSON() is populated…
await writeFile("upload.json", JSON.stringify(control.toJSON()));
// Later — a new process, after a crash.
const token = JSON.parse(await readFile("upload.json", "utf8"));
const result = await files.upload("backups/db.tar", file, {
control: UploadControl.from(token),
});
Because resuming re-reads the bytes, control requires a body with a known length — a File, Blob, ArrayBuffer, typed array, or string. A bare ReadableStream is rejected: a consumed stream can’t be replayed.
Pause, abort, and the session
pause()stops dispatching new parts. Parts already in flight finish, then the upload waits. The session is preserved, so this is the moment totoJSON()and persist.resume()continues a paused upload.abort()cancels the upload and discards the provider-side session — the partial upload a provider might otherwise bill or retain is cleaned up. It’s terminal: the token can no longer be resumed.
Aborting via the signal option instead cancels the call but keeps the session, so you can resume it later. control.status ("idle", "uploading", "paused", "completed", "aborted", "error") and control.loaded / control.total track progress for a UI.
Discarding a persisted session
abort() discards the session through the adapter, and a control only has one while upload() is driving it. A control rebuilt with UploadControl.from(token) that you never pass to upload() can’t reach the provider: its abort() only marks it aborted, and the session stays behind. To give up on a persisted upload, pass its key and token to files.abortUpload() instead:
const token = JSON.parse(await readFile("upload.json", "utf8"));
await files.abortUpload("backups/db.tar", token);
It does what abort() does mid-upload. The key and token must match (the same logical key the upload targeted, on an instance with the same adapter and prefix), or it throws before discarding anything. A session that’s already gone, because the upload completed or was discarded, isn’t an error, but a cancel the provider refuses rejects: on GCS, Firebase Storage, Google Drive, OneDrive, SharePoint, and Supabase, any response other than a 2xx, 404, 410, or 499 fails the call instead of resolving. Like other writes, it throws ReadOnly on a read-only instance, and it throws Unsupported on an adapter without resumable uploads. It reports through the hooks as type: "abortUpload", but plugin wraps don’t see it.
What each adapter does
The token maps onto whatever resumable primitive the provider exposes. Most adapters resume across processes — persist the token, resume after a crash:
- S3 and the S3-compatible adapters (incl. R2 over HTTP with the
"aws-sdk"client) drive S3’s native multipart API directly — the token carries theUploadId, resume lists already-uploaded parts withListParts, andabort()issuesAbortMultipartUpload. (This is a separate path from themultipartflag’s@aws-sdk/lib-storageupload, which doesn’t expose the upload id.) - GCS, Firebase Storage, and Google Drive resume against a stored resumable-session URI.
- Azure Blob stages blocks and commits them, skipping blocks already staged on resume.
- OneDrive and SharePoint drive a Graph upload session and read
nextExpectedRangesto resume. A retried chunk Graph already holds (416) continues from the session’s next expected range, and a session that has expired or refuses a chunk fails withNotFound/Unauthorized/Conflictinstead of being retried. - Dropbox drives an upload session, tracking the byte offset in the token. When Dropbox reports the session is further along (
incorrect_offset, after a chunk landed but its reply was lost), the upload continues from Dropbox’s offset and the token follows. - Vercel Blob drives its native multipart API; the token carries the completed parts (it exposes no server-side list).
- The local filesystem writes a
.fls-parttemp file and resumes from its size, renaming it into place on completion. - FTP and SFTP, like the local filesystem, append to a
.fls-partstaging file next to the key and resume from its size, renaming it over the key on completion. A paused or aborted upload never exposes a partial object, andlist()hides the staging files. - Supabase drives the resumable TUS endpoint; Appwrite and Cloudinary drive their chunked
Content-Rangeuploads.
A few providers expose no serializable session, so they support pause/resume in-process only — control.toJSON() can’t be resumed in a new process: Box (its commit requires a whole-file digest), bun-s3, and memory (no upload id). They buffer the body in the running process and upload on completion.
What abort() and files.abortUpload() discard also depends on the provider. S3 and the S3-compatible adapters abort the multipart upload; GCS, Firebase Storage, Google Drive, OneDrive, SharePoint, and Supabase cancel the session URL; the local filesystem, FTP, and SFTP delete the .fls-part file; and Appwrite deletes the partially uploaded file (never one whose upload has completed). Azure, Dropbox, Cloudinary, and Vercel Blob have no way to cancel a session, so it expires on its own (Azure drops uncommitted blocks after about 7 days), and the in-process sessions above end with their process.
Every remaining adapter — Netlify Blobs, UploadThing, PocketBase, Bunny, Convex, WebDAV, the R2 Workers binding, the fetch S3 engine (s3Fetch() and client: "fetch"), and the rest — throws an Unsupported FilesError when control is passed, the same way an unsupported range download does. Check files.capabilities.resumable to branch up front. control is a single-key option; it isn’t available in the array form of upload.
The Supabase (TUS), Appwrite, and Cloudinary drivers are built to each provider’s documented chunked-upload protocol and covered by mocked tests, but haven’t been exercised against a live account — verify them end-to-end before relying on them in production.
Parts, retries, and progress
partSize and concurrency come from the multipart option and tune the same trade-off; both must be positive integers, or the upload throws an Invalid FilesError before a session opens. Each part (or chunk) is retried on its own under the call’s retry policy, so a transient failure mid-upload doesn’t restart the whole transfer. onProgress fires as parts confirm, and on resume it starts from the bytes already uploaded.
Opening the session, checking it on resume, and finalizing it follow the same rules as the parts: each attempt gets the per-attempt timeout, stops on the caller’s signal or control.abort(), and is retried on a transient provider error. A session that opens after its attempt timed out or was aborted is discarded as soon as it lands, since no one holds its token. If a finalize attempt fails and its retry finds the session already gone, the first attempt may have committed the object: the error says so (with the first failure as its cause), so check with head before uploading again.
The SDK also refuses to finalize a body it didn’t fully send. A chunk the provider acknowledges without moving its offset forward counts as a failed attempt (retried within the budget) rather than being re-sent forever, and a part list that doesn’t add up to the whole body is never committed.