Overview

The surface is small: a Files instance with ten methods, plus files.file(key) for a key-bound handle. Each method takes one key (or an array, where bulk applies), accepts the shared signal / timeout / retries options, and throws a normalized FilesError. Each method has its own page; this page covers the pieces that cut across all of them.

Functions

• upload - write a body to a key, one or many.
• download - read an object as a StoredFile or a stream.
• head - fetch metadata without materializing the body.
• exists - check whether a key exists.
• delete - remove one object or many.
• copy - server-side copy with a read + write fallback.
• move - rename a key, native where the provider supports it.
• list - cursor-paginated listing, or listAll to walk every page.
• url - a direct or signed URL to fetch a key.
• signedUploadUrl - a presigned PUT/POST contract for direct browser uploads.
• file - a FileHandle bound to one key.

Two global functions stand apart from the instance methods — they take two Files instances and move objects between backends, built entirely on the methods above:

• transfer - stream every object from one instance to another.
• sync - mirror one instance onto another (skip-unchanged, prune, dry-run).

Scoping keys with a prefix

Pass prefix to the constructor and every key is resolved relative to it — prepended on the way in, stripped on the way out — so application code works in its own namespace. See Prefixes for the full behavior, including slash normalization and how list() scopes to a path boundary.

Read-only instances

Pass readonly: true to new Files(...), or call files.readonly(), to create a view that still allows reads (download, head, exists, list, listAll, url) but rejects writes (upload, delete, copy, move, signedUploadUrl) with FilesError { code: "ReadOnly" }.

Per-operation options

Every method accepts signal, timeout, and retries. Set them once on the constructor as defaults, then override per call - a per-call value wins over the constructor default for that operation.

const files = new Files({
  adapter: s3({ bucket: "uploads" }),
  timeout: 10_000, // default per-attempt timeout for every call
  retries: { max: 3, backoff: ({ attempt }) => attempt * 500 },
});

// A per-call value wins over the constructor default.
await files.head("avatars/abc.png", { timeout: 2_000 });

See Timeouts, Retries, and Cancellation for how each behaves, and Hooks to observe operations as they run.

The StoredFile type

download, head, and list all return StoredFile — a type that mirrors native File's shape and adds the key, etag, and metadata that storage carries.