effect

The missing standard library for TypeScript, for writing production-grade software.

weekly downloads7.0M

versionv3.19.18

licenseMIT

categoryutility

Overview

Effect is a TypeScript framework that provides a structured approach to handling side effects—asynchronous operations, I/O, error handling, and resource management—through a functional programming paradigm. Rather than scattering error handling, dependency injection, and async logic throughout your codebase, Effect offers a unified system where these concerns are encoded in the type system itself.

The package serves as both a runtime and a collection of abstractions for building production applications. At its core is a fiber-based concurrency model that manages asynchronous tasks efficiently, along with utilities for composition, error handling, and dependency management. With over 7 million weekly downloads, Effect has gained traction among teams building complex TypeScript applications that require predictable behavior and strong type guarantees.

Effect is designed for developers working on applications where reliability matters—backend services, data pipelines, CLI tools, and any system where you need to trace dependencies, handle failures gracefully, and maintain type safety across async boundaries. The learning curve is steeper than traditional Promise-based code, but the payoff comes in maintainability and compile-time confidence.

As of version 4, the ecosystem has consolidated core functionality into the main effect package while maintaining separate packages for platform-specific implementations (@effect/platform-node, @effect/platform-bun), database drivers (@effect/sql-*), and other integrations. This architecture lets you start with just the core and add capabilities as needed.

Quick Start

typescript

import { Effect, Context, Console } from "effect";

// Define a service for database operations
class Database extends Context.Tag("Database")<
  Database,
  { query: (sql: string) => Effect.Effect<unknown[], Error> }
>() {}

// Define application logic that depends on database
const getUsers = Effect.gen(function* () {
  const db = yield* Database;
  const users = yield* db.query("SELECT * FROM users");
  yield* Console.log(`Found ${users.length} users`);
  return users;
});

// Provide implementation and handle errors
const program = getUsers.pipe(
  Effect.provide(
    Database.of({
      query: (sql) =>
        Effect.tryPromise({
          try: () => Promise.resolve([{ id: 1, name: "Alice" }]),
          catch: (error) => new Error(String(error)),
        }),
    })
  ),
  Effect.retry({ times: 3 }),
  Effect.timeout("5 seconds"),
  Effect.catchAll((error) =>
    Console.error(`Failed to fetch users: ${error.message}`).pipe(
      Effect.as([])
    )
  )
);

// Run the effect
Effect.runPromise(program).then((users) => {
  console.log("Result:", users);
});

Use Cases

Building HTTP APIs with dependency injection: Effect's Context system allows you to define services (database connections, logging, configuration) as dependencies that are provided at runtime, making testing and environment-specific behavior straightforward without manual mocking.

CLI applications with structured error handling: The @effect/cli package combined with Effect's error management lets you build command-line tools with proper argument parsing, validation, and graceful error reporting that distinguishes between different failure types.

Data processing pipelines with retries and timeouts: Effect provides built-in operators for retry logic, timeouts, and fallback strategies, making it ideal for ETL jobs, API integrations, or any workflow where transient failures need sophisticated handling beyond simple try-catch blocks.

Concurrent task orchestration: The fiber runtime enables fine-grained control over parallel operations—running multiple API calls concurrently, racing tasks against each other, or implementing cooperative cancellation—all with type-safe error aggregation.

Type-safe configuration and validation: Combined with @effect/schema, Effect enables runtime validation of configuration, environment variables, or external data with automatic TypeScript type inference, ensuring your application fails fast with clear errors rather than at arbitrary runtime points.

Pros & Cons

Pros

+Comprehensive type safety: errors, dependencies, and async operations are all tracked in the type system, catching entire classes of bugs at compile time
+Unified abstractions: consistent patterns for error handling, retries, timeouts, concurrency, and resource management across your entire application
+Testability: dependency injection through Context makes unit testing straightforward without complex mocking frameworks
+Performance: the rewritten v4 fiber runtime is optimized for low memory overhead and fast execution with minimal bundle impact
+Ecosystem integration: seamless interop with platform APIs, SQL databases, HTTP servers, and AI services through official packages

Cons

−Steep learning curve: functional programming concepts and Effect-specific patterns require significant upfront investment compared to Promise-based code
−Breaking changes: v4 is in beta with unstable modules that may receive breaking changes in minor versions, requiring careful dependency management
−Abstraction overhead: simple operations require more boilerplate than vanilla async/await, which may feel excessive for small projects
−Community size: while growing, the ecosystem is smaller than mainstream approaches, meaning fewer third-party tutorials and Stack Overflow answers
−Runtime dependency: adds a non-trivial dependency to your project, which may be a concern for library authors or bundle-size-sensitive applications

Alternatives

ioredisv5.9.3

A robust, performance-focused and full-featured Redis client for Node.js.

backendrediscluster

12.6M / week

neverthrowv8.2.0

Stop throwing errors, and instead return Results!

utilitytypescriptfunctional

1.2M / week

rxjsv7.8.2

Reactive Extensions for modern JavaScript

utilityRxRxJS

71.6M / week

zodv4.3.6

TypeScript-first schema declaration and validation library with static type inference

validationtypescriptschema

85.3M / week

Comparisons

Install

bash

npm install effect

bash

pnpm add effect

bash

bun add effect

Overview

Quick Start

typescript

import { Effect, Context, Console } from "effect";

// Define a service for database operations
class Database extends Context.Tag("Database")<
  Database,
  { query: (sql: string) => Effect.Effect<unknown[], Error> }
>() {}

// Define application logic that depends on database
const getUsers = Effect.gen(function* () {
  const db = yield* Database;
  const users = yield* db.query("SELECT * FROM users");
  yield* Console.log(`Found ${users.length} users`);
  return users;
});

// Provide implementation and handle errors
const program = getUsers.pipe(
  Effect.provide(
    Database.of({
      query: (sql) =>
        Effect.tryPromise({
          try: () => Promise.resolve([{ id: 1, name: "Alice" }]),
          catch: (error) => new Error(String(error)),
        }),
    })
  ),
  Effect.retry({ times: 3 }),
  Effect.timeout("5 seconds"),
  Effect.catchAll((error) =>
    Console.error(`Failed to fetch users: ${error.message}`).pipe(
      Effect.as([])
    )
  )
);

// Run the effect
Effect.runPromise(program).then((users) => {
  console.log("Result:", users);
});

Use Cases

Pros & Cons

Pros

+Comprehensive type safety: errors, dependencies, and async operations are all tracked in the type system, catching entire classes of bugs at compile time
+Unified abstractions: consistent patterns for error handling, retries, timeouts, concurrency, and resource management across your entire application
+Testability: dependency injection through Context makes unit testing straightforward without complex mocking frameworks
+Performance: the rewritten v4 fiber runtime is optimized for low memory overhead and fast execution with minimal bundle impact
+Ecosystem integration: seamless interop with platform APIs, SQL databases, HTTP servers, and AI services through official packages

Cons

−Steep learning curve: functional programming concepts and Effect-specific patterns require significant upfront investment compared to Promise-based code
−Breaking changes: v4 is in beta with unstable modules that may receive breaking changes in minor versions, requiring careful dependency management
−Abstraction overhead: simple operations require more boilerplate than vanilla async/await, which may feel excessive for small projects
−Community size: while growing, the ecosystem is smaller than mainstream approaches, meaning fewer third-party tutorials and Stack Overflow answers
−Runtime dependency: adds a non-trivial dependency to your project, which may be a concern for library authors or bundle-size-sensitive applications