@distilled.cloud/s3
v1.0.0-rc.20
Published
Effect-native Amazon S3 client for AWS and every S3-compatible store (Cloudflare R2, Tigris, MinIO, ...), with the restXml, SigV4 and endpoint-rules runtime it needs and nothing else. The base of @distilled.cloud/aws.
Keywords
Readme
@distilled.cloud/s3
Effect-native Amazon S3 client, generated from AWS's Smithy model with exhaustive error typing. It works with AWS S3 and every S3-compatible store: Cloudflare R2, Tigris, MinIO, Backblaze B2, Railway and Fly.io buckets.
The package holds the S3 client and only the runtime it needs: the restXml
protocol, SigV4 signing (@distilled.cloud/aws4signer), endpoint rules and
checksums. It reads no environment variable and no file, and it has no
credential providers. About 2.4 MB installed.
Installation
npm install @distilled.cloud/s3 effectUse it with your own keys
Provide Credentials with the keys, and Endpoint for a store other than
AWS:
import * as S3 from "@distilled.cloud/s3";
import { Credentials } from "@distilled.cloud/s3/Credentials";
import { Endpoint } from "@distilled.cloud/s3/Endpoint";
import * as Effect from "effect/Effect";
import * as FetchHttpClient from "effect/http/FetchHttpClient";
import * as Layer from "effect/Layer";
import * as Redacted from "effect/Redacted";
const program = Effect.gen(function* () {
yield* S3.putObject({ Bucket: "my-bucket", Key: "hello.txt", Body: "Hello!" });
const { Contents } = yield* S3.listObjectsV2({ Bucket: "my-bucket" });
return Contents?.map((object) => object.Key);
}).pipe(
// A bucket that does not exist fails with a typed error you can catch.
Effect.catchTag("NoSuchBucket", () => Effect.succeed([])),
);
const MinIO = Layer.mergeAll(
FetchHttpClient.layer,
Layer.succeed(Endpoint, Effect.succeed("http://localhost:9000")),
Layer.succeed(
Credentials,
Effect.succeed({
accessKeyId: Redacted.make(accessKeyId),
secretAccessKey: Redacted.make(secretAccessKey),
sessionToken: undefined,
// The region the keys sign for.
region: "us-east-1",
}),
),
);
program.pipe(Effect.provide(MinIO), Effect.runPromise);Use it through another distilled SDK
An SDK that already holds credentials provides the layer:
- AWS:
@distilled.cloud/aws's credential providers (Credentials.fromChain(),fromSSO,fromEnv, ...) provide this package'sCredentials.@distilled.cloud/aws/s3re-exports this package. - Cloudflare R2:
R2.layerS3()from@distilled.cloud/cloudflare/r2turns the Cloudflare API token in the CloudflareCredentialsinto R2 S3 keys, and pointsEndpointat the account's R2 endpoint. The account is the credentials'accountId(CLOUDFLARE_ACCOUNT_ID), or the one account the token reaches. Buckets in another jurisdiction: provideJurisdiction.of("eu")from@distilled.cloud/cloudflare/Jurisdiction.
import * as Cloudflare from "@distilled.cloud/cloudflare/Credentials";
import * as R2 from "@distilled.cloud/cloudflare/r2";
const R2Live = R2.layerS3().pipe(
Layer.provideMerge(Layer.mergeAll(Cloudflare.fromEnv(), FetchHttpClient.layer)),
);
program.pipe(Effect.provide(R2Live), Effect.runPromise);A layer that can fail adds its errors to every operation's error type
(see ProviderErrors in @distilled.cloud/s3/Credentials), so a program
that only passes keys sees none of them.
Generated code
src/services/s3.ts is generated by packages/aws/scripts/generate.ts from
the AWS spec mirror, with the patches in packages/aws/patches/s3.json.
Regenerate it with pnpm generate aws.
License
Apache-2.0
