effect-ts

# Effect TypeScript Best Practices Effect is a TypeScript library for building complex, type-safe applications with structured error handling, dependency injection via services/layers, fiber-based concurrency, and resource safety. ## When to Apply - Writing or reviewing TypeScript code that imports from `effect`, `@effect/schema`, or `@effect/platform` - Implementing typed error handling with `Effect<Success, Error, Requirements>` - Building services and layers for dependency injection - Working with Schema for data validation, decoding, and transformation - Using fiber-based concurrency (queues, semaphores, PubSub, deferred) - Processing data with Stream and Sink - Migrating from Promises, fp-ts, neverthrow, or ZIO to Effect ## How to Use This skill is organized by domain. Read the relevant reference file for the area you're working in. ### Read First: The Paradigm **Always read this before diving into API references**, especially when refactoring existing code to use Effect or writing new Effect services: | Reference | When to Read | |-----------|-------------| | [**Think in Effect: The Paradigm Shift**](references/getting-paradigm.md) | **Before any other reference.** Mental model shifts, refactoring recipes, anti-patterns, application architecture. Read this to understand HOW to think in Effect — the other files teach WHAT to type. | ### Core Foundations | Reference | When to Read | |-----------|-------------| | [Getting Started](references/getting-started.md) | Creating the Effect type, pipelines, generators, running effects | | [Error Management](references/error-management.md) | Typed errors, recovery, retrying, timeouts, sandboxing | | [Core Concepts](references/core-concepts.md) | Request batching, configuration management, runtime system | ### Data & Validation | Reference | When to Read | |-----------|-------------| | [Data Types](references/data-types.md) | Option, Either, Cause, Chunk, DateTime, Duration, Exit, Data | | [Schema Basics](references/schema-basics.md) | Schema intro, basic usage, classes, constructors, effect data types | | [Schema Advanced](references/schema-advanced.md) | Transformations, filters, annotations, error formatting, JSON Schema output | ### Architecture & Dependencies | Reference | When to Read | |-----------|-------------| | [Requirements Management](references/req-management.md) | Services, Layers, dependency injection, layer memoization | | [Resource Management](references/resource-management.md) | Scope, safe resource acquisition/release, caching | | [State Management](references/state-management.md) | Ref, SubscriptionRef, SynchronizedRef for concurrent state | ### Concurrency & Streaming | Reference | When to Read | |-----------|-------------| | [Concurrency](references/conc-concurrency.md) | Fibers, Deferred, Latch, PubSub, Queue, Semaphore | | [Streams and Sinks](references/streams-and-sinks.md) | Creating, consuming, transforming streams; sink operations | | [Scheduling](references/sched-scheduling.md) | Built-in schedules, cron, combinators, repetition | ### Platform & Observability | Reference | When to Read | |-----------|-------------| | [Platform](references/plat-platform.md) | FileSystem, Command, Terminal, KeyValueStore, Path | | [Observability](references/obs-observability.md) | Logging, metrics, tracing, Supervisor | | [Testing](references/test-testing.md) | TestClock for time simulation; for service mocking and layer testing, see [Requirements Management](references/req-management.md) | ### Style, AI & Migration | Reference | When to Read | |-----------|-------------| | [Code Style](references/code-style.md) | Branded types, pattern matching, dual APIs, guidelines, traits | | [AI Integration](references/ai-integration.md) | Effect AI packages for LLM tool use and execution planning | | [Micro](references/micro-module.md) | Lightweight Effect alternative for smaller bundles | | [Migration Guides](references/migration-guides.md) | Coming from Promises, fp-ts, neverthrow, or ZIO | ## Quick Reference — Common Patterns ### The Effect Type ```ts // ┌─── Success type // │ ┌─── Error type // │ │ ┌─── Required dependencies // ▼ ▼ ▼ Effect<Success, Error, Requirements> ``` ### Creating Effects ```ts import { Effect } from "effect" // From sync values const succeed = Effect.succeed(42) const fail = Effect.fail(new Error("oops")) // From sync code that may throw const sync = Effect.try(() => JSON.parse(data)) // From promises const async = Effect.tryPromise(() => fetch(url)) // From generators (recommended for complex flows) const program = Effect.gen(function* () { const user = yield* getUser(id) const todos = yield* getTodos(user.id) return { user, todos } }) ``` ### Running Effects ```ts // Async (returns Promise) Effect.runPromise(program) // With full Exit information Effect.runPromiseExit(program) // Sync (throws on async) Effect.runSync(program) ``` ### Typed Errors ```ts import { Data, Effect } from "effect" class NotFound extends Data.TaggedError("NotFound")<{ readonly id: string }> {} class Unauthorized extends Data.TaggedError("Unauthorized")<{}> {} // Error type is tracked: Effect<User, NotFound | Unauthorized> const getUser = (id: string) => Effect.gen(function* () { // ... }) ``` ### Services and Layers ```ts import { Context, Effect, Layer } from "effect" // Define a service class UserRepo extends Context.Tag("UserRepo")< UserRepo, { readonly findById: (id: string) => Effect.Effect<User, NotFound> } >() {} // Use in effects — adds to Requirements channel const program = Effect.gen(function* () { const repo = yield* UserRepo return yield* repo.findById("1") }) // Implement with a Layer const UserRepoLive = Layer.succeed(UserRepo, { findById: (id) => Effect.succeed({ id, name: "Alice" }) }) // Provide and run program.pipe(Effect.provide(UserRepoLive), Effect.runPromise) ``` ### Schema Validation ```ts import { Schema } from "effect" const User = Schema.Struct({ id: Schema.Number, name: Schema.String, email: Schema.String.pipe(Schema.pattern(/@/)) }) type User = typeof User.Type // Decode (parse + validate) const decode = Schema.decodeUnknownSync(User) const user = decode({ id: 1, name: "Alice", email: "a@b.com" }) ``` ### Pipelines ```ts import { Effect, pipe } from "effect" // Data-last (pipe style) const result = pipe( getTodos, Effect.map((todos) => todos.filter((t) => !t.done)), Effect.flatMap((active) => sendNotification(active.length)), Effect.catchTag("NetworkError", () => Effect.succeed("offline")) ) // Fluent (method style) const result2 = getTodos.pipe( Effect.map((todos) => todos.filter((t) => !t.done)), Effect.flatMap((active) => sendNotification(active.length)) ) ``` ## Gotchas See [gotchas.md](gotchas.md) for known failure points.