Listing & metadata

Three methods let you inspect what's in your bucket without downloading bytes: list() enumerates objects, getMetadata() inspects one, and exists() checks presence.

Listing objects

list() returns a single page of objects under an optional prefix. Call it with no arguments to list everything, or pass a prefix to scope it.

const page = await storage.list("avatars/");
for (const obj of page.objects) {
  console.log(obj.key, obj.size, obj.lastModified);
}

Each object is an ObjectSummary:

Pagination

list() never returns everything at once — providers cap page size (S3 at 1000). The result tells you whether there's more and how to get it:

Loop until hasMore is false, feeding cursor back in:

let cursor: string | undefined;
const all = [];

do {
  const page = await storage.list("uploads/", { limit: 500, cursor });
  all.push(...page.objects);
  cursor = page.cursor;
} while (cursor);

Folders with a delimiter

Object stores are flat — there are no real folders, just keys with slashes. A delimiter (usually "/") makes list() collapse everything below the next slash into a common prefix, so you can browse a hierarchy one level at a time.

const page = await storage.list("uploads/", { delimiter: "/" });

page.prefixes; // ["uploads/2025/", "uploads/2026/"] — the "folders"
page.objects;  // only keys directly under "uploads/", not inside sub-prefixes

getMetadata()

getMetadata() fetches everything about one object except its bytes — size, content type, timestamps, and your user metadata.

const meta = await storage.getMetadata("avatars/ada.png");
meta.size;             // bytes
meta.contentType;      // "image/png"
meta.lastModified;     // Date
meta.etag;             // entity tag
meta.cacheControl;     // stored Cache-Control, if any
meta.metadata;         // your user metadata, e.g. { customerId: "cus_123" }

exists()

exists() returns a plain boolean — true if an object is at that key, false otherwise. It never throws for a missing object.

if (await storage.exists("avatars/ada.png")) {
  // ...
}

Under the hood this is a HEAD request on the S3 family (cheap — no body), and the provider's nearest equivalent elsewhere.

Targeting a provider

Like every operation, list, getMetadata, and exists accept a { provider } option to override the default:

await storage.list("uploads/", { provider: "r2", limit: 100 });