effect-foundations

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

Real-world snippet: Branching with Match and TaggedError

import { Effect, Match, Data } from "effect"

class UnsupportedPlatformError extends Data.TaggedError("UnsupportedPlatformError")<{
  readonly platform: string
  readonly arch: string
}>{}

const detectPlatform = (rawPlatform: string, rawArch: string) => Effect.gen(function* () {
  const platform = yield* Match.value(rawPlatform).pipe(
    Match.when("darwin", () => Effect.succeed("darwin" as const)),
    Match.when("linux", () => Effect.succeed("linux" as const)),
    Match.orElse(() => Effect.fail(new UnsupportedPlatformError({ platform: rawPlatform, arch: rawArch })))
  )
  const arch = yield* Match.value(rawArch).pipe(
    Match.when("x64", () => Effect.succeed("x64" as const)),
    Match.when("arm64", () => Effect.succeed("aarch64" as const)),
    Match.when("aarch64", () => Effect.succeed("aarch64" as const)),
    Match.orElse(() => Effect.fail(new UnsupportedPlatformError({ platform: rawPlatform, arch: rawArch })))
  )
  return { platform, arch }
})

Recovery (Quick)

program.pipe(
  Effect.catchTag("DomainError", () => Effect.succeed(fallback)),
  Effect.catchAll((e) => Effect.fail(new WrappedError({ cause: e })))
)

Tooling Steps (with effect-engineer)

• Grep local examples: Effect.gen, Effect.all, .pipe(
• Search docs MCP for operator specifics when unsure
• Consult EffectPatterns for canonical idioms (https://github.com/PaulJPhilp/EffectPatterns)

Pitfalls

• Don't mix promises and effects—wrap with Effect.try/tryPromise
• Don't return raw values inside Effect.gen—always yield* an Effect
• Unsatisfied R requirements → provide layers or adjust architecture

Local Source Reference

CRITICAL: Search local Effect source before implementing

The full Effect source code is available at docs/effect-source/. Always search the actual implementation before writing Effect code.

Key Source Files

• Core Effect: docs/effect-source/effect/src/Effect.ts
• Layer: docs/effect-source/effect/src/Layer.ts
• Data: docs/effect-source/effect/src/Data.ts
• Match: docs/effect-source/effect/src/Match.ts

Example Searches

# Find Effect.gen implementation and patterns
grep -rF "Effect.gen" docs/effect-source/effect/src/

# Find all map/flatMap/andThen variants
grep -rF "export" docs/effect-source/effect/src/Effect.ts | grep -F "map"
grep -rF "export" docs/effect-source/effect/src/Effect.ts | grep -F "flatMap"
grep -rF "export" docs/effect-source/effect/src/Effect.ts | grep -F "andThen"

# Study error handling patterns
grep -rF "catchTag" docs/effect-source/effect/src/
grep -rF "catchAll" docs/effect-source/effect/src/
grep -rF "TaggedError" docs/effect-source/effect/src/

# Find Effect.all concurrency patterns
grep -rF "Effect.all" docs/effect-source/effect/src/

Workflow

1. Identify the API you need (e.g., Effect.gen, Effect.all)
2. Search docs/effect-source/effect/src/Effect.ts for the implementation
3. Study the types, overloads, and patterns
4. Look at test files in docs/effect-source/effect/test/ for usage examples
5. Write your code based on real implementations

Real source code > documentation > assumptions

References

• Agent Skills overview: https://www.anthropic.com/news/skills
• Skills guide: https://docs.claude.com/en/docs/claude-code/skills
• EffectPatterns: https://github.com/PaulJPhilp/EffectPatterns