Skip to main content


The bucket primitive provides an object store backed by S3.

Creating a Bucket

import { bucket } from "@eventual/core";

export const files = bucket("files");

Get Object

const object = await files.get("/path/to/file.txt");
// if the object doesn't exist, then undefined is returned
if (object !== undefined) {
object.body; // the body is available as a Readable

// get the body as a string (convenience)
const bodyString = await object?.getBodyString();

The get method accepts an optional options argument. Use this to specify the etag of an object if you need.

const object = await files.get("path/to/file.txt", {
etag: yourEtag,

Head (Get Object Metadata)

The head object provides a way to get an object's metadata without fetching the content:

const response = await files.head("path/to/file.txt");

response?.metadata; // key-value pairs of metadata

Put Object

Upload an object with the put method. It accepts data as a string, Buffer or Readable.

await files.put("path/to/file.txt", "data");
await files.put("path/to/file.txt", buffer);
await files.put("path/to/file.txt", readable);

The response provides the etag if needed:

const response = await files.put("path/to/file.txt", "data");

const etag = response.etag;

You can provide key-value pairs of object metadata in the third options argument:

await files.put("path/to/file.txt", "data", {
metadata: {
key: "value",

Delete Object

await files.delete("path/to/file.txt");

List Objects

Use the list method to list objects in a bucket by prefix.

const response = await files.list({
prefix: "key/",

Use the response's nextToken to page through results. When there are no more objects left, it will be undefined.

await files.list({
prefix: "key/",
nextToken: response.nextToken,

Specify maxKeys to limit the number of returned objects. Default and max is 1000.

await files.list({
prefix: "key/",
maxKeys: 10,

Specify a key for startAfter to start the list from a specific key:

await files.list({
prefix: "key/",
startAfter: "key/some/obj.txt",

Copy Object

The copyTo method provides a way to copy an object from one location to another without downloading and re-uploading (the operation is performed server-side).

await files.copyTo("path/to/destination.txt", "path/to/source.txt");

By default, the object is coped to the same bucket. You can optionally specify a different bucket as the third argument.

await files.copyTo(

Generate Pre-Signed URL

It is often useful to generate pre-signed URLs that allow an external, trusted partner to call delete/get/put/head on an object. You can do this with the generatePresignedUrl method.

const response = await myBucket.generatePresignedUrl("path/to/file.txt", "get");

Supported operations are:

  • delete
  • get
  • put
  • head

Bucket Listener

Buckets emit events whenever objects are created or deleted. You can subscribe to these events for processing with the on handler.

This will create a Lambda Function and subscribe it to the Bucket's events.

export const onFileChanged = files.on("all", "onFileChanged", async (item) => {
const obj = await myBucket.get(item.key);

The event property defines the operation that was performed - one of copy, delete or put.

if (item.event === "copy") {
} else if (item.event === "delete") {
} else if (item.event === "put") {

To subscribe to a specific type of event, specify the event type in the first argument:

export const onFileChanged = files.on("put", "onFileChanged", async (item) => {
const obj = await myBucket.get(item.key);

Allowed values are:

  • all - all events
  • put - only receive events when an object is put to the bucket
  • delete - only receive events when an object is deleted
  • copy - only receive events when an object is copied

To subscribe to multiple events, use an array:

files.on(["put", "delete"], ..)

You can also provide options to filter the keys by key prefix or override the default handlerTimeout or memorySize.

handlerTimeout: duration(1, "minute"),
memorySize: 512,
filters: [
prefix: "key/",
async (item) => {