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

Effect is not just for async — Use
```
Effect
```
for any fallible operation
Immutability — Use Effect's immutable data structures (
```
Data
```
,
```
Chunk
```
,
```
HashSet
```
)
Type Safety — Track errors in types. No
```
any
```
or
```
unknown
```
in error channels
Composition — Build programs by composing small Effects
Schema-First — Define data models using
```
Schema
```
with branded types
Pattern Matching — Use
```
Match
```
for all branching over tagged unions (never
```
switch
```
/
```
if-else
```
on
```
_tag
```
)
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

typescript

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

typescript

// 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

typescript

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

typescript

// 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.

typescript

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

typescript

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

typescript

// 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

bash

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

effect-ts

NPX Install

Tags

SKILL.md Content

Effect-TS Developer Guide

Reference Documents

Core Principles

Quick Reference

Import Convention

Effect.gen vs pipe vs Effect.fn

Error Handling

Pattern Matching (Mandatory for Tagged Unions)

Service Pattern (Context.Tag)

Testing

Forbidden Patterns

Validation Checklist

Reference Implementation

Effect Solutions CLI