effect-ts

Files (24)

• SKILL.md
• gotchas.md
• metadata.json
• _sections.md · references/
• ai-integration.md · references/
• code-style.md · references/
• conc-concurrency.md · references/
• core-concepts.md · references/
• data-types.md · references/
• error-management.md · references/
• getting-paradigm.md · references/
• getting-started.md · references/
• micro-module.md · references/
• migration-guides.md · references/
• obs-observability.md · references/
• plat-platform.md · references/
• req-management.md · references/
• resource-management.md · references/
• sched-scheduling.md · references/
• schema-advanced.md · references/
• schema-basics.md · references/
• state-management.md · references/
• streams-and-sinks.md · references/
• test-testing.md · references/

SKILL.md (first lines)

# 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)

From pproenca/dot-skills, MIT.

More from pproenca/dot-skills