Cloud APIs, distilled into Effect.

Typed errors

S3.getObject({ Bucket, Key }).pipe(
  Effect.catchTags({
    NoSuchKey:          () => Effect.succeed(null),
    InvalidObjectState: (e) => Effect.fail(new Archived(e)),
  }),
  Effect.catchIf(isThrottlingError, () => backOff),
)

Match an exact error or a whole category with the Effect functions you already know, like Effect.catchTags and Effect.catchIf. Each SDK is patched with the errors and details its API spec never documents, so nothing comes back as unknown and your types stay accurate.

Retries and backoff

const write = Effect.all([
  // throttled → waits as long as S3 asks, forever
  S3.putObject({ Bucket, Key, Body }),
  // no retry of its own; only the outer loop can bring it back
  S3.deleteObject({ Bucket, Key }).pipe(AWS.Retry.none),
]).pipe(AWS.Retry.throttling)

// around both: 5xx, timeouts, dropped sockets — 4 tries, then fail
write.pipe(Effect.retry({
  while: isTransientError,
  times: 3,
  schedule: Schedule.exponential("250 millis"),
}))

The API's own Retry-After is respected, and you can define your own retry policies and stack them.

Streaming pagination

// Paginated: pages fetch themselves, on demand.
const stale = Lambda.listFunctions.items({}).pipe(
  Stream.filter((fn) => fn.Runtime === "nodejs16.x"),
  Stream.take(50),
  Stream.runCollect,
)

// Bodies stream in and out — nothing is buffered.
const copy = S3.getObject({ Bucket: src, Key }).pipe(
  Effect.flatMap((o) =>
    S3.putObject({ Bucket: dst, Key, Body: o.Body! })),
)

Every paginated operation has .items() and .pages(), so you pull items from an Effect Stream and pages load as you go.Large binary bodies stream in and out without being held in memory. Cancel the Effect and the requests stop.

Layered configuration

const AwsLive = Layer.mergeAll(
  FetchHttpClient.layer,
  Region.fromEnv(),
  Credentials.fromChain(),   // env → ~/.aws → SSO → IMDS
)

// the region comes from the layer…
const head = S3.headObject({ Bucket, Key })

// ...unless one call says otherwise
const eu = head.pipe(Effect.provide(Region.of("eu-central-1")))

Effect.all([head, eu]).pipe(Effect.provide(AwsLive))

Your code just calls S3.headObject. Credentials and regions come from layers: provide them once at the root of your program and override them wherever you need to.

Lazy GraphQL

// at runtime `yield* load()` is a single GraphQL query
const load = Query.fn(() => {
  const me = Railway.me()
  const page = Railway.projects({ first: 20 })
  return {
    email: me.email,
    names: page.pipe(
      Query.map((project) => project.name),
    ),
  }
})

GraphQL queries are abstracted away, just reference the fields you need and a query is generated at runtime.

OpenTelemetry spans

// Effect's HttpClient opens a span per request with the
// standard http.* and server.* attributes.
program.pipe(
  Effect.withSpan("provision-bucket"),
  Effect.provide(OtlpTracer.layer({
    url: "http://collector:4318/v1/traces",
  })),
)

Operations are ordinary Effects, so they get Effect's built-in OpenTelemetry support.

Strict responses

import { ResponseValidation } from "@distilled.cloud/core"

// every SDK checks each response against its schema
// (additionalProperties: allow fields the spec does not list)
program.pipe(Effect.provide(ResponseValidation.strict))

// a response that drifted from the spec is a typed error
Neon.getProject({ project_id }).pipe(
  Effect.catchTag("NeonParseError", (e) => ...),
)

Responses are lenient by default and come back as the API sent them. Provide one layer and every SDK in your program checks each response against its schema: strict also rejects fields the spec does not list, additionalProperties lets them through. When an API changes shape, the call fails with a typed ParseError instead of handing you the wrong type.

Per-operation imports

// the bundle keeps getObject — not the other 111 S3 ops
import { getObject } from "@distilled.cloud/aws/s3"

gzipped, one S3 operation

118.4 KB

gzipped, one Workers operation

61.7 KB

Every operation is its own export, so the bundler keeps only the ones you call — 1 of 112 S3 operations survives in the measured build. Runs on Node, Bun and Workers. See all the numbers →