Aller au contenu

Services · Référence

S3 Service

An Effect service wrapping Bun's S3 client for object reads, writes, metadata, presigned URLs, listing, and deletion with typed service errors.

Dernière mise à jour le 8 octobre 2026

Overview

service-s3 provides an Effect service around Bun's built-in S3 client. It reads S3 configuration from environment variables, exposes a reusable S3Service.layer, and maps client failures into S3ServiceError values.

Install

shell
bunx shadcn@latest add @krak-stack/service-s3

Included Files

  • services/s3/index.ts - S3 config service, S3 client service, production layer, and test layer helper
  • services/s3/schema.ts - Typed S3ServiceError schema

Usage

ts
import { Effect } from "effect";
import { S3Service } from "@/services/s3";

const program = Effect.gen(function* () {
  const s3 = yield* S3Service;

  yield* s3.write("uploads/hello.txt", "Hello world", {
    type: "text/plain",
  });

  const text = yield* s3.text("uploads/hello.txt");
  const url = yield* s3.presign("uploads/hello.txt", { expiresIn: 60 });

  return { text, url };
});

const result = await Effect.runPromise(
  program.pipe(Effect.provide(S3Service.layer)),
);

Available Operations

  • file(path, options?) - Create a Bun S3File reference
  • write(path, data, options?) - Write object data
  • text(path), json(path), bytes(path), arrayBuffer(path), stream(path) - Read object data
  • exists(path), stat(path), size(path) - Read object metadata
  • delete(path) - Delete an object
  • presign(path, options?) - Create a presigned object URL
  • list(options?) - List bucket objects

Environment Variables

  • S3_ACCESS_KEY_ID - S3 access key ID
  • S3_SECRET_ACCESS_KEY - S3 secret access key
  • S3_BUCKET - S3 bucket name
  • S3_REGION - Optional S3 region
  • S3_ENDPOINT - Optional custom S3-compatible endpoint
  • S3_SESSION_TOKEN - Optional session token

This service uses Bun's S3Client, so it is intended for Bun runtimes or compatible S3-compatible deployments.

Dependencies
Packages and shadcn components required by this registry item.

Dependencies

Dev Dependencies