Effect-TS Core Library

Common errors

• TypeError: Effect.runPromise is not a function

  cause Attempting to call `runPromise` (or other runners) on a non-Effect value, or `Effect` itself, rather than an instance.
  fix Ensure you are calling `Effect.runPromise` on an actual `Effect` instance, e.g., `Effect.runPromise(myEffect)`. Also, check your imports for `Effect` to ensure it's not a `require` import if your project is ESM-first.

• Type 'Effect<unknown, never, any>' is not assignable to type 'Effect<R, E, A>'

  cause Often arises from type inference issues, particularly when an effect is created without explicitly defining its R, E, or A parameters, or when composing effects with incompatible types.
  fix Explicitly specify the type parameters (`Effect<A, E, R>`) for effects, especially when defining functions that return them. Use `Effect.mapError`, `Effect.provide`, `Effect.catchAll` to adjust error and requirement types. When composing, ensure the types align or are handled.

• TS2345: Argument of type 'Promise<any>' is not assignable to parameter of type 'Effect<any, never, never>'

  cause Mixing `async/await` (Promises) directly with `Effect` values without proper conversion.
  fix Convert Promises to Effects using `Effect.promise`, `Effect.tryPromise`, or `Effect.async` (for more complex async operations). Do not `await` Effect values directly; use `yield*` within `Effect.gen`.

• TS2349: This expression is not callable.

  cause Attempting to call a method like `Effect.succeed(value)()` or using `pipe` incorrectly, e.g., `Effect.pipe(...)` instead of `value.pipe(Effect.method(...))` or `pipe(value, Effect.method(...))`.
  fix Ensure methods are called correctly. If using the fluent `.pipe()` syntax, ensure it's on an Effect instance (`myEffect.pipe(Effect.map(...))`). If using the global `pipe` function, ensure it takes the value as its first argument (`pipe(myEffect, Effect.map(...))`).

Warnings

• breaking Major versions (e.g., v2 to v3) introduce significant breaking changes, including module reorganizations, API renames (e.g., `Either` to `Result`), and changes to `Layer` and `Service` definitions.
  Fix: Consult the official migration guide for the specific major version upgrade. For v3, update imports, service definitions, Effect.gen usage, and error types.
• gotcha Effects are 'cold' and lazy; they describe a computation but do not execute until explicitly 'run' using functions like `Effect.runPromise`, `Effect.runSync`, or `Effect.runFork`. Forgetting to run an effect means its encapsulated logic (e.g., logging, side effects) will never occur.
  Fix: Always ensure your Effect computation is eventually passed to a runner function, typically at the 'edge' of your application or within a specific execution context.
• gotcha Understanding the `Effect<A, E, R>` type parameters (Success, Error, Requirements) is crucial for type safety, especially 'R' (Requirements/Context). Incorrectly managing or providing dependencies (Services/Layers) can lead to compile-time type errors related to missing `R` or runtime failures if services are not provided.
  Fix: Familiarize yourself with Effect's dependency injection system (Services and Layers). Ensure all required dependencies are correctly provided to your Effect computations via `Effect.provide` or `Layer.provide`.
• gotcha When using `Effect.gen`, it's critical to use `yield*` (yield-star) for yielding other Effect values, not `await`. Using `await` directly within `Effect.gen` will often lead to unexpected behavior or type errors because it does not properly unwrap the Effect context.
  Fix: Always use `yield*` when composing Effect values inside an `Effect.gen` block. `yield*` performs the unwrapping and error propagation within the Effect runtime.
• gotcha A recently fixed defect in `RequestResolver.makeBatched` could cause consumer fibers to hang indefinitely if the resolver died with a defect, because cleanup logic was not correctly handling failures.
  Fix: Update to `effect@3.21.1` or later to include the fix that ensures request `Deferred`s are completed even if the resolver dies with a defect.

Install

• npm install effect npm
• yarn add effect yarn
• pnpm add effect pnpm

Imports

• Effect
  wrong:

  const { Effect } = require('effect')

  correct:

  import { Effect } from 'effect'

  Effect is the core data type representing a computation. The library is primarily ESM-first, especially in modern versions.
• Layer
  wrong:

  import { Layer } from '@effect/data/Layer'

  correct:

  import { Layer } from 'effect'

  Layer is used for dependency injection. In v3+, all core modules are exported from the single 'effect' package, consolidating imports.
• pipe
  wrong:

  import { pipe } from '@fp-ts/core'

  correct:

  import { pipe } from 'effect'

  The `pipe` function is fundamental for functional composition. While `fp-ts` also uses `pipe`, `effect`'s version is integrated within its ecosystem. `pipe` is also often available as a method on `Effect` and other data types.
• Effect.gen
  wrong:

  const program = Effect.gen(async function () { /* ... */ });

  correct:

  import { Effect } from 'effect'; const program = Effect.gen(function* () { /* ... */ });

  Effect.gen uses generator functions with `yield*` for an imperative, async/await-like coding style, not regular async/await.

Quickstart

This quickstart demonstrates creating and composing Effects, handling different types of errors with custom error classes, using `pipe` for composition, applying retry logic, and running the Effect to a Promise, including a simulated database defect.

import { Effect, Console, pipe, Duration, Schedule } from 'effect';

interface User {
  id: number;
  name: string;
  email: string;
}

// Define a custom error type for better type safety
class UserNotFoundError extends Effect.Error('UserNotFoundError')<{ userId: number }> {}
class DatabaseConnectionError extends Effect.Error('DatabaseConnectionError')<{ message: string }> {}

// Simulate fetching a user from a database
const fetchUserFromDB = (userId: number): Effect.Effect<User, UserNotFoundError | DatabaseConnectionError, never> =>
  Effect.sync(() => {
    if (userId === 1) {
      return { id: 1, name: 'Alice', email: 'alice@example.com' };
    } else if (userId === 99) {
      throw new Error('Failed to connect to DB'); // Simulate a defect
    }
    return Effect.fail(new UserNotFoundError({ userId }));
  }).pipe(
    Effect.catchAllDefect((error) =>
      Effect.fail(new DatabaseConnectionError({ message: String(error) }))
    )
  );

const program = pipe(
  fetchUserFromDB(1), // Try to fetch user with ID 1
  Effect.tap((user) => Console.log(`Fetched user: ${user.name}`)),
  Effect.flatMap(() => fetchUserFromDB(2)), // Try to fetch user with ID 2 (will fail)
  Effect.tapError((error) =>
    error._tag === 'UserNotFoundError'
      ? Console.error(`Error: User with ID ${error.userId} not found.`)
      : Console.error(`Critical Error: ${error.message}`)
  ),
  Effect.retry(Schedule.exponential(Duration.seconds(1), 3)), // Retry failed operations with exponential backoff
  Effect.matchEffect({ // Handle both success and failure paths explicitly
    onFailure: (error) => Console.error(`Final failure: ${error._tag}`),
    onSuccess: (user) => Console.log(`Final success (should not happen for user 2, unless retries succeed): ${user.name}`),
  })
);

// Run the Effect program
Effect.runPromise(program).then(() => Console.log('Program finished.')).catch(console.error);