effect-foundations

Effect Foundations & Style

Purpose: Provide a compact, go-to checklist for writing idiomatic Effect TypeScript with data-first pipe style, minimal imperative code, and strong typing. Optimized for a coding agent with limited context.

Triggers

• New Effect implementation or refactor
• Selecting map/flatMap/andThen/tap operators
• Converting promise/callback to Effect

When to use

• You’re unsure which operator to pick (map vs flatMap vs andThen vs tap)
• You need a minimal template for sequential vs parallel code
• You want to keep error and context channels explicit (Effect<E, A, R>)

Checklist (Do First)

1. Prefer data-first .pipe() style for readability
2. Use Effect.gen for sequential logic; Effect.all for parallelism
3. Lift values with Effect.succeed, failures with Effect.fail
4. Declare errors as Data.TaggedError and recover with catchTag(s)
5. Keep effects small, composable, and typed—avoid any
6. If R (requirements) is not never, provide layers explicitly

Minimal Patterns

• Creation

const value = Effect.succeed(42)
const failure = Effect.fail(new MyError())

• Transform

const result = value.pipe(
  Effect.map((n) => n * 2),
  Effect.tap((n) => Effect.log(`n=${n}`))
)

• Sequential

const program = Effect.gen(function* () {
  const a = yield* getA()
  const b = yield* getB(a)
  return b
})

• Parallel

const both = yield* Effect.all([left(), right()], { concurrency: "unbounded" })

Operator Selection Guide

• Map value: Effect.map
• Chain effect: Effect.flatMap
• Ignore previous result: Effect.andThen
• Side-effect only: Effect.tap
• Provide context: Effect.provide/layers (see layers skill)
• Combine layers: Layer.merge, Layer.provide

Key APIs (intuition)

• Effect.gen: write sequential code with yield* for each Effect
• Effect.all(values, { concurrency }): run independent Effects concurrently
• Effect.catchTags(...): recover only specific typed errors
• Layer.merge(a, b): compose dependencies once, reuse everywhere
• Effect.runPromise(...): bridge Effects to async workflows