Bucket

Source: src/AWS/S3/Bucket.ts

An S3 bucket for storing objects in AWS.

A bucket name is auto-generated from the app, stage, and logical ID unless you provide one explicitly via bucketName. Enable forceDestroy to allow Alchemy to empty the bucket before deleting it.

Creating a Bucket

Basic Bucket

import * as S3 from "alchemy/AWS/S3";

const bucket = yield* S3.Bucket("my-bucket", {});

Bucket with a custom name

const bucket = yield* S3.Bucket("my-bucket", {
  bucketName: "my-company-assets",
});

Bucket with force destroy

const bucket = yield* S3.Bucket("my-bucket", {
  forceDestroy: true,
});

Runtime Operations

Bind S3 operations in the init phase and use them in runtime handlers. Bindings inject the bucket name and grant scoped IAM permissions automatically.

Read and write objects

// init
const getObject = yield* S3.GetObject.bind(bucket);
const putObject = yield* S3.PutObject.bind(bucket);

return {
  fetch: Effect.gen(function* () {
    // runtime
    yield* putObject({
      Key: "hello.txt",
      Body: "Hello, World!",
      ContentType: "text/plain",
    });
    const response = yield* getObject({ Key: "hello.txt" });
    return HttpServerResponse.text("OK");
  }),
};

Delete an object

// init
const deleteObject = yield* S3.DeleteObject.bind(bucket);

Event Notifications

Subscribe to bucket events from the init phase. The subscription and Lambda invoke permissions are created automatically.

// init
yield* S3.notifications(bucket, {
  events: ["s3:ObjectCreated:*"],
}).subscribe((stream) =>
  stream.pipe(
    Stream.runForEach((event) =>
      Effect.log(`New object: ${event.key}`),
    ),
  ),
);