@distilled.cloud/aws

@distilled.cloud/aws

Effect-native AWS SDK generated from Smithy models with full protocol support. Covers S3, Lambda, DynamoDB, SQS, IAM, EC2, and 200+ services with exhaustive error typing.

Installation

npm install @distilled.cloud/aws effect

Quick Start

import { Effect, Layer } from "effect";
import * as Stream from "effect/Stream";
import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
import * as Lambda from "@distilled.cloud/aws/lambda";
import * as S3 from "@distilled.cloud/aws/s3";
import { Credentials, Region } from "@distilled.cloud/aws";

const program = Effect.gen(function* () {
  yield* S3.putObject({
    Bucket: "my-bucket",
    Key: "hello.txt",
    Body: "Hello, World!",
  });

  const result = yield* S3.getObject({
    Bucket: "my-bucket",
    Key: "hello.txt",
  });

  const functions = yield* Lambda.listFunctions
    .items({})
    .pipe(Stream.take(10), Stream.runCollect);

  return result.ContentType;
});

const AwsLive = Layer.mergeAll(
  FetchHttpClient.layer,
  Region.fromEnv(),
  Credentials.fromChain(),
);

program.pipe(Effect.provide(AwsLive), Effect.runPromise);

Configuration

Region

Region.fromEnv() reads from the AWS_REGION environment variable (falls back to AWS_DEFAULT_REGION):

AWS_REGION=us-east-1

Credentials

Credentials.fromChain() uses the standard AWS credential provider chain, which tries each source in order until one succeeds:

• Environment variables — AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optionally AWS_SESSION_TOKEN
• Shared credentials file — ~/.aws/credentials (supports multiple profiles via AWS_PROFILE)
• SSO — aws sso login --profile your-profile (reads cached SSO tokens)
• Container metadata — ECS task role credentials
• EC2 instance metadata — IMDS instance profile credentials
• Token file — AWS_WEB_IDENTITY_TOKEN_FILE for OIDC federation (EKS)

You can also use a specific provider directly:

// Environment variables only
Credentials.fromEnv()

// SSO profile (run `aws sso login` first)
Credentials.fromSSO("my-profile")

// Shared credentials file (~/.aws/credentials)
Credentials.fromIni()

// Static credentials
Credentials.fromCredentials({
  accessKeyId: "AKIA...",
  secretAccessKey: "...",
})

Credentials are cached and automatically refreshed 5 minutes before expiration.

Error Handling

All operations return typed errors for pattern matching:

S3.getObject({ Bucket: "my-bucket", Key: "missing.txt" }).pipe(
  Effect.catchTags({
    NoSuchKey: () => Effect.succeed(null),
    AccessDenied: (e) => Effect.fail(new Error(`Access denied: ${e.message}`)),
  }),
);

Protocols

Supports all AWS protocols: REST-XML (S3), REST-JSON (Lambda), AWS JSON 1.0/1.1 (DynamoDB, KMS), AWS Query (IAM, STS), and EC2 Query.

License

MIT

Similar packages

Other packages similar to @distilled.cloud/aws

@aws-sdk/client-s3

The official modular AWS SDK for JavaScript v3 client for Amazon S3. It is a service-specific package with documented command-based APIs; it is narrower in scope than an all-AWS package.

aws-sdk

The older, monolithic AWS SDK for JavaScript v2, covering many AWS services through a single package. Unlike modular service clients, it bundles a broad surface area and is the predecessor to v3.

aws-cdk-lib

The AWS Cloud Development Kit library for defining cloud infrastructure as code. It overlaps in the AWS domain, but focuses on synthesizing and deploying infrastructure rather than directly calling service APIs.