atelier-typescript-effect-ts_skill

Overview

This skill introduces type-safe functional effects using Effect-TS to build robust TypeScript applications. It focuses on typed errors, dependency injection with Context.Tag and Layer, resource safety, and composable effect patterns. Use it to write predictable, testable, and maintainable async code with compile-time guarantees.

How this skill works

The skill inspects common Effect-TS patterns and provides practical guidance: creating and running Effect values, composing flows with Effect.gen and combinators, modeling typed failures, and wiring services with Layer and Context.Tag. It explains resource management with acquireRelease and Scope, data validation via Schema, and runtime strategies like retries, timeouts, and parallelism.

When to use it

• Building async workflows that must preserve error types and avoid lost error information
• Injecting and composing services with explicit, type-checked dependencies
• Managing resources that require deterministic cleanup (DB connections, file handles, sockets)
• Validating and decoding external data (HTTP payloads, DB rows) with schema-driven types
• Coordinating retries, backoff, concurrency limits, and timeouts in a predictable way

Best practices

• Prefer Effect.gen for readable, sequential effect code and Effect.flatMap for combinators
• Model recoverable failures with typed error classes (use _tag for catchTag)
• Declare services with Context.Tag and provide implementations via Layer for testability
• Use Schema.decodeUnknown / decodeUnknownSync for external inputs and keep validation in the effect channel
• Wrap resources with acquireRelease and use Scope or scoped effects to guarantee cleanup
• Run effects at the application boundary (runPromise / runSync) to keep effects pure inside the app logic

Example use cases

• Fetch and enrich data from multiple services sequentially using Effect.gen and typed network errors
• Provide a Database service via Layer, run queries in effects, and replace with a mock layer in tests
• Acquire a connection with acquireRelease, run transactions inside Scope, and ensure release on failure or interruption
• Decode and validate incoming JSON with Schema.decodeUnknown, returning typed errors on failure
• Retry flaky remote calls with Schedule.exponential and jitter, and apply a timeout guard