Effect-TS Developer Guide

Guidelines, patterns, and best practices for Effect-TS in this project.

Reference Documents

Read the relevant reference before writing code. references/core-patterns.md is the master index.

Reference	Topics
references/foundations.md	Setup, imports, TypeScript config
references/construction-and-style.md	Effect.gen, pipe, Effect.fn, Effect.fnUntraced
references/schema-errors-config.md	Schema modeling, errors, config, retry
references/pattern-matching.md	Match.type, Match.value, Match.tag, Match.exhaustive — mandatory for tagged unions
references/control-flow-and-runtime.md	Effect.if, Effect.when, loops, runSync, runPromise, ManagedRuntime
references/data-types.md	All data types: Option, Either, Data, Exit, Cause, Duration, DateTime, BigDecimal, Chunk, HashSet, Redacted
references/data-and-testing.md	Option/Either/Array quick ref, @effect/vitest setup
references/concurrency-and-resources.md	Concurrency, Scope, finalizers, resources
references/streams-deep-dive.md	Creating, operations, grouping, partitioning, broadcasting, buffering, throttling, error handling
references/sink.md	Sink constructors, collecting, folding, operations, concurrency, leftovers, Stream.transduce
references/batching-and-caching.md	Request batching (RequestResolver), cachedWithTTL
references/schema-transforms-and-filters.md	Schema.transform, Schema.filter, refinements
references/api-platform-observability.md	HttpApi, logging, tracing, spans
references/class-patterns.md	Context.Tag service pattern, layers, memoization, testing
references/error-handling-patterns.md	Data.TaggedError, Schema.TaggedError, error composition, recovery
references/library-development-patterns.md	Forbidden patterns, Effect.fn vs Effect.fnUntraced, resource management
references/testing-patterns.md	@effect/vitest with assert, TestClock, service mocking
references/quality-tooling-and-resources.md	Anti-patterns, validation checklist, packages

Core Principles

1. Effect is not just for async — Use Effect for any fallible operation
2. Immutability — Use Effect's immutable data structures (Data, Chunk, HashSet)
3. Type Safety — Track errors in types. No any or unknown in error channels
4. Composition — Build programs by composing small Effects
5. Schema-First — Define data models using Schema with branded types
6. Pattern Matching — Use Match for all branching over tagged unions (never switch/if-else on _tag)
7. Effect Data Types — Use Option (not null), Either (not ad-hoc), Duration (not raw ms), DateTime (not Date), BigDecimal (not floats), Redacted (for secrets). See references/data-types.md

Quick Reference

Import Convention

import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Schema from "effect/Schema";
import * as Match from "effect/Match";
import * as Option from "effect/Option";
import * as Either from "effect/Either";
import * as Data from "effect/Data";
import * as Duration from "effect/Duration";
import { pipe } from "effect/Function";
// Also: DateTime, BigDecimal, Chunk, HashSet, Exit, Cause, Redacted

Effect.gen vs pipe vs Effect.fn

// Effect.gen — complex logic with branching
Effect.gen(function* () {
  const user = yield* fetchUser(id);
  if (user.isAdmin) yield* logAdminAccess(user);
  return user;
});

// pipe — linear transformations
pipe(fetchData(), Effect.map(transform), Effect.flatMap(save));

// Effect.fn — traced reusable functions (public API)
const processUser = Effect.fn("processUser")(function* (userId: string) {
  const user = yield* getUser(userId);
  return yield* processData(user);
});

Error Handling

Data.TaggedError for in-process discrimination, Schema.TaggedError for serializable errors. See references/error-handling-patterns.md.

export class NotFoundError extends Data.TaggedError("NotFoundError")<{
  id: string;
}> {}

// Recovery
pipe(riskyOp, Effect.catchTag("NotFoundError", (e) => Effect.succeed(null)));

Pattern Matching (Mandatory for Tagged Unions)

Always use Match — Match.exhaustive catches missing cases at compile time. See references/pattern-matching.md.

// Match.type — reusable matcher function
const handle = Match.type<Status>().pipe(
  Match.tag("Pending", (s) => `Pending since ${s.requestedAt}`),
  Match.tag("Approved", (s) => `Approved by ${s.approvedBy}`),
  Match.exhaustive // Compile error if any variant is missing
);

// Match.valueTags — shorthand for immediate matching
Match.valueTags(status, {
  Pending: (s) => `Pending since ${s.requestedAt}`,
  Approved: (s) => `Approved by ${s.approvedBy}`,
});

Service Pattern (Context.Tag)

See references/class-patterns.md for full pattern with factory methods and layers.

export class MyService extends Context.Tag("@myapp/MyService")<
  MyService,
  { readonly find: (id: string) => Effect.Effect<Result, NotFoundError> }
>() {
  static readonly layer = Layer.effect(MyService, Effect.gen(function* () {
    const db = yield* Database;
    return MyService.of({ find: MyService.createFind(db) });
  }));
}

Testing

CRITICAL: Use assert from @effect/vitest for it.effect. Never expect with it.effect. See references/testing-patterns.md.

import { assert, describe, it } from "@effect/vitest";

it.effect("processes data", () =>
  Effect.gen(function* () {
    const result = yield* processData("input");
    assert.strictEqual(result, "expected");
  }).pipe(Effect.provide(MyService.testLayer))
);

Forbidden Patterns

// NEVER: try-catch in Effect.gen — use Effect.exit instead
Effect.gen(function* () {
  try { yield* someEffect } catch (e) { } // WRONG — will never catch
});

// NEVER: Type assertions
const value = something as any;   // FORBIDDEN
const value = something as never; // FORBIDDEN

// NEVER: Missing return on terminal yield
Effect.gen(function* () {
  if (bad) { yield* Effect.fail("err") } // Missing return!
});

// NEVER: switch/if-else on _tag — use Match instead
switch (status._tag) { /* no exhaustiveness checking! */ }

// NEVER: Effect.runSync inside Effects
Effect.gen(function* () { Effect.runSync(sideEffect) }); // Loses error tracking

// NEVER: Native JS where Effect data types exist
const x: string | null = null;              // Use Option<string>
const delay = 5000;                         // Use Duration.seconds(5)
const now = new Date();                     // Use DateTime.now or DateTime.unsafeNow()
const price = 0.1 + 0.2;                   // Use BigDecimal for precision
const secret = "sk-1234";                   // Use Redacted.make("sk-1234")

// NEVER: expect with it.effect
it.effect("test", () => Effect.gen(function* () {
  expect(result).toBe(value) // WRONG — use assert.strictEqual
}));

// NEVER: Inline layers (breaks memoization)
Layer.provide(Postgres.layer({ url })) // Store in constant instead

Validation Checklist

• Imports use import * as Module from "effect/Module"
• Effect.gen for complex logic, pipe for linear, Effect.fn for public API
• Match for all _tag branching with Match.exhaustive
• Branded types for domain primitives (IDs, Emails)
• Errors: Data.TaggedError (discrimination) or Schema.TaggedError (serializable)
• No any/unknown in error channels, no type assertions
• No try-catch in Effect.gen — use Effect.exit
• return yield* for terminal effects (Effect.fail, Effect.interrupt)
• Services: Context.Tag with static factory methods and Effect.fn tracing
• Layers: Layer.merge/Layer.provide, parameterized layers in constants
• Resources: Effect.acquireRelease or Effect.scoped
• Option for nullable values, Either for sync success/failure
• Duration for time values, DateTime for dates (not Date)
• BigDecimal for financial/precise math, Redacted for secrets
• Data.struct/Data.Class for structural equality, HashSet for sets
• Clock.currentTimeMillis instead of Date.now()
• Tests: assert from @effect/vitest (not expect) with it.effect
• Run pnpm run typecheck and pnpm run test

Reference Implementation

See /packages/looper/src/data/api-client/api-client.ts for Context.Tag service pattern.

Effect Solutions CLI

pnpm exec effect-solutions list              # List all topics
pnpm exec effect-solutions show <slug...>    # Read topics
pnpm exec effect-solutions search <term>     # Search by keyword