///
/**
* Describes workflows that run only when executed by the Effect runtime.
*
* An `Effect` can succeed with an `A`, fail with an `E`, and require
* services `R`. Creating an effect does not perform the work; it builds a value
* that can be composed, provided with services, retried, interrupted, run
* concurrently, or inspected by the runtime. This module is the main API for
* creating effects, combining them, handling failures, managing resources, and
* running effect programs.
*
* @stability stable
* @since 2.0.0
*/
import type * as Arr from "./Array.ts"
import type * as Cause from "./Cause.ts"
import type { Clock } from "./Clock.ts"
import * as Context from "./Context.ts"
import * as Duration from "./Duration.ts"
import type * as ExecutionPlan from "./ExecutionPlan.ts"
import * as Exit from "./Exit.ts"
import type { Fiber } from "./Fiber.ts"
import type * as Filter from "./Filter.ts"
import { dual, type LazyArg } from "./Function.ts"
import type { TypeLambda } from "./HKT.ts"
import type { Inspectable } from "./Inspectable.ts"
import * as core from "./internal/core.ts"
import * as internal from "./internal/effect.ts"
import * as internalExecutionPlan from "./internal/executionPlan.ts"
import * as internalLayer from "./internal/layer.ts"
import * as InternalRecord from "./internal/record.ts"
import * as internalRequest from "./internal/request.ts"
import * as internalSchedule from "./internal/schedule.ts"
import type * as Layer from "./Layer.ts"
import type { Logger } from "./Logger.ts"
import type { Severity } from "./LogLevel.ts"
import * as Metric from "./Metric.ts"
import type { Option } from "./Option.ts"
import type { Pipeable } from "./Pipeable.ts"
import type * as Predicate from "./Predicate.ts"
import { CurrentLogAnnotations, CurrentLogSpans } from "./References.ts"
import type * as Request from "./Request.ts"
import type { RequestResolver } from "./RequestResolver.ts"
import type * as Result from "./Result.ts"
import type { Metadata as ScheduleMetadata, Schedule } from "./Schedule.ts"
import type { Scheduler } from "./Scheduler.ts"
import type { Scope } from "./Scope.ts"
import type {
AnySpan,
ParentSpan,
Span,
SpanLink,
SpanOptions,
SpanOptionsNoTrace,
TraceOptions,
Tracer
} from "./Tracer.ts"
import type { TxRef } from "./TxRef.ts"
import type {
Concurrency,
Covariant,
EqualsWith,
ExcludeReason,
ExcludeTag,
ExtractReason,
ExtractTag,
NarrowReason,
NoInfer,
OmitReason,
ReasonOf,
ReasonTags,
Simplify,
Tags,
unassigned
} from "./Types.ts"
import type * as Unify from "./Unify.ts"
/**
* Type-level identifier for `Effect` values.
*
* @stability stable
* @category type IDs
* @since 4.0.0
*/
export type TypeId = "~effect/Effect"
/**
* Runtime identifier used to recognize `Effect` values.
*
* @stability stable
* @category type IDs
* @since 4.0.0
*/
export const TypeId: TypeId = core.EffectTypeId
/**
* The `Effect` interface defines a value that lazily describes a workflow or
* job. The workflow requires some context `R`, and may fail with an error of
* type `E`, or succeed with a value of type `A`.
*
* **When to use**
*
* Use when you need to represent a lazy, composable workflow that can require
* services, fail with a typed error, or succeed with a typed value.
*
* **Details**
*
* `Effect` values model resourceful interaction with the outside world,
* including synchronous, asynchronous, concurrent, and parallel interaction.
* They use a fiber-based concurrency model, with built-in support for
* scheduling, fine-grained interruption, structured concurrency, and high
* scalability.
*
* To run an `Effect` value, you need a `Runtime`, which is a type that is
* capable of executing `Effect` values.
*
* @stability stable
* @category models
* @since 2.0.0
*/
export interface Effect extends Pipeable, Inspectable {
readonly [TypeId]: Variance
[Symbol.iterator](): EffectIterator>
[Unify.typeSymbol]?: unknown
[Unify.unifySymbol]?: EffectUnify
[Unify.ignoreSymbol]?: {}
}
/**
* Type-level unification support for `Effect` values.
*
* @stability stable
* @category models
* @since 2.0.0
*/
export interface EffectUnify {
Effect?: () => A[Unify.typeSymbol] extends
| Effect
| infer _ ? Effect
: never
}
/**
* Type lambda used to represent `Effect` in higher-kinded APIs.
*
* @stability stable
* @category utility types
* @since 2.0.0
*/
export interface EffectTypeLambda extends TypeLambda {
readonly type: Effect
}
/**
* Variance interface for Effect, encoding the type parameters' variance.
*
* @stability stable
* @category models
* @since 2.0.0
*/
export interface Variance {
_A: Covariant
_E: Covariant
_R: Covariant
}
/**
* Extracts the success type from an `Effect`.
*
* **When to use**
*
* Use to derive the value produced by an existing effect when declaring
* reusable type aliases, service interfaces, or function signatures.
*
* @see {@link Error} for extracting the failure type from the same `Effect`
* @see {@link Services} for extracting the required services from the same `Effect`
*
* @stability stable
* @category utility types
* @since 2.0.0
*/
export type Success = T extends Effect ? _A
: never
/**
* Extracts the error type from an `Effect`.
*
* **When to use**
*
* Use to derive the error type from an existing `Effect` type when declaring
* helper types, wrappers, or APIs that preserve the effect's failure channel.
*
* **Details**
*
* Non-`Effect` inputs resolve to `never`.
*
* @see {@link Success} for extracting the success value type instead
* @see {@link Services} for extracting the required services type instead
*
* @stability stable
* @category utility types
* @since 2.0.0
*/
export type Error = T extends Effect ? _E
: never
/**
* Extracts the required services type from an `Effect`.
*
* **When to use**
*
* Use to derive the context requirements of a generic or inferred `Effect`
* without restating its `R` type parameter.
*
* @see {@link Success} for extracting the success value type instead
* @see {@link Error} for extracting the failure type instead
*
* @stability stable
* @category utility types
* @since 4.0.0
*/
export type Services = T extends Effect ? _R
: never
/**
* Checks whether a value is an `Effect`.
*
* **Example** (Checking whether a value is an Effect)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* Effect.isEffect(Effect.succeed(1)) // => true
* Effect.isEffect("hello") // => false
* ```
*
* @stability stable
* @category guards
* @since 2.0.0
*/
export const isEffect: (u: unknown) => u is Effect = core.isEffect
/**
* Iterator interface for Effect generators, enabling Effect values to work with generator functions.
*
* **When to use**
*
* Use when defining or typing `[Symbol.iterator]()` for values typed as
* `Effect`s so `yield*` can pass their success type back into `Effect.gen`.
*
* @see {@link gen} for writing generator-based `Effect` programs that consume this iterator protocol
*
* @stability stable
* @category models
* @since 4.0.0
*/
export interface EffectIterator> {
next(
...args: ReadonlyArray
): IteratorResult>
}
// ========================================================================
// Collecting
// ========================================================================
/**
* Namespace containing type utilities for the `Effect.all` function, which handles
* collecting multiple effects into various output structures.
*
* @stability stable
* @category collecting
* @since 2.0.0
*/
export declare namespace All {
/**
* Alias for any `Effect` value accepted by `Effect.all`.
*
* @category utility types
* @since 2.0.0
*/
export type EffectAny = Effect
/**
* Computes the return type for `Effect.all` when collecting an iterable.
*
* @category utility types
* @since 2.0.0
*/
export type ReturnIterable<
T extends Iterable,
Discard extends boolean,
Mode extends boolean = false
> = [T] extends [Iterable>] ? Effect<
Discard extends true ? void : Array : A>,
Mode extends true ? never : E,
R
>
: never
/**
* Computes the return type for `Effect.all` when collecting a tuple.
*
* @category utility types
* @since 2.0.0
*/
export type ReturnTuple<
T extends ReadonlyArray,
Discard extends boolean,
Mode extends boolean = false
> = Effect<
Discard extends true ? void
: T[number] extends never ? []
: {
-readonly [K in keyof T]: T[K] extends Effect<
infer _A,
infer _E,
infer _R
> ? Mode extends true ? Result.Result<_A, _E> : _A
: never
},
Mode extends true ? never
: T[number] extends never ? never
: T[number] extends Effect ? _E
: never,
T[number] extends never ? never
: T[number] extends Effect ? _R
: never
> extends infer X ? X
: never
/**
* Computes the return type for `Effect.all` when collecting a record.
*
* @category utility types
* @since 2.0.0
*/
export type ReturnObject = [T] extends [
Record
] ? Effect<
Discard extends true ? void
: {
-readonly [K in keyof T]: [T[K]] extends [
Effect
] ? Mode extends true ? Result.Result<_A, _E> : _A
: never
},
Mode extends true ? never : Error>,
Services>
>
: never
/**
* Detects whether `Effect.all` should discard collected values.
*
* @category utility types
* @since 2.0.0
*/
export type IsDiscard = [Extract] extends [
never
] ? false
: true
/**
* Detects whether `Effect.all` should collect results in `Result` mode.
*
* @category utility types
* @since 4.0.0
*/
export type IsResult = [Extract] extends [never] ? false : true
/**
* Computes the return type for `Effect.all` from its input and options.
*
* @category utility types
* @since 2.0.0
*/
export type Return<
Arg extends Iterable | Record,
O extends {
readonly concurrency?: Concurrency | undefined
readonly discard?: boolean | undefined
readonly mode?: "default" | "result" | undefined
}
> = [Arg] extends [ReadonlyArray] ? ReturnTuple, IsResult>
: [Arg] extends [Iterable] ? ReturnIterable, IsResult>
: [Arg] extends [Record] ? ReturnObject, IsResult>
: never
type ObjectValues = T extends unknown ? T[keyof T] : never
}
/**
* Combines an iterable or record of effects into one effect whose success shape
* follows the input.
*
* **When to use**
*
* Use to run a known collection of effects and collect results in the same
* tuple, iterable, or record shape.
*
* **Details**
*
* Tuple and iterable inputs collect results in order. Record inputs collect
* results under the same keys. By default, the combined effect fails on the
* first failure; with concurrent execution, effects that have already started
* may be interrupted, while effects not yet started are skipped.
*
* Options:
*
* Use `concurrency` to control sequential or concurrent execution. Use
* `mode: "result"` to run every effect and collect each success or failure as a
* `Result` in the same output shape. Use `discard: true` to ignore successful
* values and return `void`.
*
* **Example** (Collecting tuple results in order)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* const tupleOfEffects = [
* Effect.succeed(42),
* Effect.succeed("Hello")
* ] as const
*
* // ┌─── Effect<[number, string], never, never>
* // ▼
* const resultsAsTuple = Effect.all(tupleOfEffects)
*
* await Effect.runPromise(resultsAsTuple) // => [42, "Hello"]
* ```
*
* **Example** (Collecting iterable results in order)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* const iterableOfEffects: Iterable> = [1, 2, 3].map(
* Effect.succeed
* )
*
* // ┌─── Effect
* // ▼
* const resultsAsArray = Effect.all(iterableOfEffects)
*
* await Effect.runPromise(resultsAsArray) // => [1, 2, 3]
* ```
*
* **Example** (Collecting struct results by key)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* const structOfEffects = {
* a: Effect.succeed(42),
* b: Effect.succeed("Hello")
* }
*
* // ┌─── Effect<{ a: number; b: string; }, never, never>
* // ▼
* const resultsAsStruct = Effect.all(structOfEffects)
*
* await Effect.runPromise(resultsAsStruct) // => { a: 42, b: "Hello" }
* ```
*
* **Example** (Collecting record results by key)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* const recordOfEffects: Record> = {
* key1: Effect.succeed(1),
* key2: Effect.succeed(2)
* }
*
* // ┌─── Effect<{ [x: string]: number; }, never, never>
* // ▼
* const resultsAsRecord = Effect.all(recordOfEffects)
*
* await Effect.runPromise(resultsAsRecord) // => { key1: 1, key2: 2 }
* ```
*
* **Example** (Stopping on the first failure)
*
* ```ts import.meta.vitest
* import { Effect, Exit } from "effect"
* const output: Array = []
* const record = (value: unknown) => Effect.sync(() => { output.push(value) })
*
* const program = Effect.all([
* Effect.succeed("Task1").pipe(Effect.tap(record)),
* Effect.fail("Task2: Oh no!").pipe(Effect.tap(record)),
* // Won't execute due to earlier failure
* Effect.succeed("Task3").pipe(Effect.tap(record))
* ])
*
* const outcome = await Effect.runPromiseExit(program)
* const observation = [output, outcome] // => [["Task1"], Exit.fail("Task2: Oh no!")]
* ```
*
* @see {@link forEach} for iterating over elements and applying an effect.
* @stability stable
* @category collecting
* @since 2.0.0
*/
export const all: <
const Arg extends
| Iterable>
| Record>,
O extends {
readonly concurrency?: Concurrency | undefined
readonly discard?: boolean | undefined
readonly mode?: "default" | "result" | undefined
}
>(
arg: Arg,
options?: O
) => All.Return = internal.all
/**
* Applies an effectful function to each element and partitions successes and
* failures.
*
* **Details**
*
* The returned tuple is `[passes, fails]`, where `passes` contains all
* successes and `fails` contains all failures.
*
* This function runs every effect and never fails. Use `concurrency` to control
* parallelism.
*
* **Example** (Separating successes and failures)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* const program = Effect.partition([0, 1, 2, 3], (n) =>
* n % 2 === 0 ? Effect.fail(`${n} is even`) : Effect.succeed(n)
* )
*
* await Effect.runPromise(program) // => [[1, 3], ['0 is even', '2 is even']]
* ```
*
* @stability stable
* @category collecting
* @since 2.0.0
*/
export const partition: {
/**
* Applies an effectful function to each element and partitions successes and
* failures.
*
* **Details**
*
* The returned tuple is `[passes, fails]`, where `passes` contains all
* successes and `fails` contains all failures.
*
* This function runs every effect and never fails. Use `concurrency` to control
* parallelism.
*
* **Example** (Separating successes and failures)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* const program = Effect.partition([0, 1, 2, 3], (n) =>
* n % 2 === 0 ? Effect.fail(`${n} is even`) : Effect.succeed(n)
* )
*
* await Effect.runPromise(program) // => [[1, 3], ['0 is even', '2 is even']]
* ```
*
* @stability stable
* @category collecting
* @since 2.0.0
*/
(
f: (a: A, i: number) => Effect,
options?: { readonly concurrency?: Concurrency | undefined }
): (elements: Iterable) => Effect<[passes: Array, fails: Array], never, R>
/**
* Applies an effectful function to each element and partitions successes and
* failures.
*
* **Details**
*
* The returned tuple is `[passes, fails]`, where `passes` contains all
* successes and `fails` contains all failures.
*
* This function runs every effect and never fails. Use `concurrency` to control
* parallelism.
*
* **Example** (Separating successes and failures)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* const program = Effect.partition([0, 1, 2, 3], (n) =>
* n % 2 === 0 ? Effect.fail(`${n} is even`) : Effect.succeed(n)
* )
*
* await Effect.runPromise(program) // => [[1, 3], ['0 is even', '2 is even']]
* ```
*
* @stability stable
* @category collecting
* @since 2.0.0
*/
(
elements: Iterable,
f: (a: A, i: number) => Effect,
options?: { readonly concurrency?: Concurrency | undefined }
): Effect<[passes: Array, fails: Array], never, R>
} = internal.partition
/**
* Reduces elements from left to right with an effectful accumulator function.
*
* **When to use**
*
* Use when each accumulation step is effectful and must run sequentially in
* iteration order.
*
* **Details**
*
* The accumulator function receives the current accumulator, the current
* element, and its zero-based index. The `zero` function is evaluated each
* time the effect runs. An empty iterable succeeds with its result. If a step
* fails, remaining elements are not processed.
*
* **Example** (Summing values sequentially)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
* const output: Array = []
*
* const program = Effect.reduce(
* [1, 2, 3],
* () => 0,
* (total, value, index) =>
* Effect.sync(() => { output.push(`Adding ${value} at index ${index}`) }).pipe(
* Effect.as(total + value)
* )
* )
*
* void output.push(await Effect.runPromise(program))
* output // => ["Adding 1 at index 0", "Adding 2 at index 1", "Adding 3 at index 2", 6]
* ```
*
* @stability stable
* @category collecting
* @since 2.0.0
*/
export const reduce: {
/**
* Reduces elements from left to right with an effectful accumulator function.
*
* **When to use**
*
* Use when each accumulation step is effectful and must run sequentially in
* iteration order.
*
* **Details**
*
* The accumulator function receives the current accumulator, the current
* element, and its zero-based index. The `zero` function is evaluated each
* time the effect runs. An empty iterable succeeds with its result. If a step
* fails, remaining elements are not processed.
*
* **Example** (Summing values sequentially)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
* const output: Array = []
*
* const program = Effect.reduce(
* [1, 2, 3],
* () => 0,
* (total, value, index) =>
* Effect.sync(() => { output.push(`Adding ${value} at index ${index}`) }).pipe(
* Effect.as(total + value)
* )
* )
*
* void output.push(await Effect.runPromise(program))
* output // => ["Adding 1 at index 0", "Adding 2 at index 1", "Adding 3 at index 2", 6]
* ```
*
* @stability stable
* @category collecting
* @since 2.0.0
*/
(zero: LazyArg, f: (z: Z, a: A, i: number) => Effect): (elements: Iterable) => Effect
/**
* Reduces elements from left to right with an effectful accumulator function.
*
* **When to use**
*
* Use when each accumulation step is effectful and must run sequentially in
* iteration order.
*
* **Details**
*
* The accumulator function receives the current accumulator, the current
* element, and its zero-based index. The `zero` function is evaluated each
* time the effect runs. An empty iterable succeeds with its result. If a step
* fails, remaining elements are not processed.
*
* **Example** (Summing values sequentially)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
* const output: Array = []
*
* const program = Effect.reduce(
* [1, 2, 3],
* () => 0,
* (total, value, index) =>
* Effect.sync(() => { output.push(`Adding ${value} at index ${index}`) }).pipe(
* Effect.as(total + value)
* )
* )
*
* void output.push(await Effect.runPromise(program))
* output // => ["Adding 1 at index 0", "Adding 2 at index 1", "Adding 3 at index 2", 6]
* ```
*
* @stability stable
* @category collecting
* @since 2.0.0
*/
(
elements: Iterable,
zero: LazyArg,
f: (z: Z, a: A, i: number) => Effect
): Effect
} = internal.reduce
/**
* Applies an effectful function to each element and accumulates all failures.
*
* **Details**
*
* This function always evaluates every element. If at least one effect fails,
* all failures are returned as a non-empty array and successes are discarded.
* If all effects succeed, it returns all collected successes.
*
* Use `discard: true` to ignore successful values while still validating all
* elements.
*
* **Example** (Validating every element)
*
* ```ts import.meta.vitest
* import { Effect, Exit } from "effect"
*
* const program = Effect.validate([0, 1, 2, 3], (n) =>
* n % 2 === 0 ? Effect.fail(`${n} is even`) : Effect.succeed(n)
* )
*
* await Effect.runPromiseExit(program) // => Exit.fail(["0 is even", "2 is even"])
* ```
*
* @stability stable
* @category collecting
* @since 2.0.0
*/
export const validate: {
/**
* Applies an effectful function to each element and accumulates all failures.
*
* **Details**
*
* This function always evaluates every element. If at least one effect fails,
* all failures are returned as a non-empty array and successes are discarded.
* If all effects succeed, it returns all collected successes.
*
* Use `discard: true` to ignore successful values while still validating all
* elements.
*
* **Example** (Validating every element)
*
* ```ts import.meta.vitest
* import { Effect, Exit } from "effect"
*
* const program = Effect.validate([0, 1, 2, 3], (n) =>
* n % 2 === 0 ? Effect.fail(`${n} is even`) : Effect.succeed(n)
* )
*
* await Effect.runPromiseExit(program) // => Exit.fail(["0 is even", "2 is even"])
* ```
*
* @stability stable
* @category collecting
* @since 2.0.0
*/
(
f: (a: A, i: number) => Effect,
options?: {
readonly concurrency?: Concurrency | undefined
readonly discard?: false | undefined
} | undefined
): (elements: Iterable) => Effect, Arr.NonEmptyArray, R>
/**
* Applies an effectful function to each element and accumulates all failures.
*
* **Details**
*
* This function always evaluates every element. If at least one effect fails,
* all failures are returned as a non-empty array and successes are discarded.
* If all effects succeed, it returns all collected successes.
*
* Use `discard: true` to ignore successful values while still validating all
* elements.
*
* **Example** (Validating every element)
*
* ```ts import.meta.vitest
* import { Effect, Exit } from "effect"
*
* const program = Effect.validate([0, 1, 2, 3], (n) =>
* n % 2 === 0 ? Effect.fail(`${n} is even`) : Effect.succeed(n)
* )
*
* await Effect.runPromiseExit(program) // => Exit.fail(["0 is even", "2 is even"])
* ```
*
* @stability stable
* @category collecting
* @since 2.0.0
*/
(
f: (a: A, i: number) => Effect,
options: {
readonly concurrency?: Concurrency | undefined
readonly discard: true
}
): (elements: Iterable) => Effect, R>
/**
* Applies an effectful function to each element and accumulates all failures.
*
* **Details**
*
* This function always evaluates every element. If at least one effect fails,
* all failures are returned as a non-empty array and successes are discarded.
* If all effects succeed, it returns all collected successes.
*
* Use `discard: true` to ignore successful values while still validating all
* elements.
*
* **Example** (Validating every element)
*
* ```ts import.meta.vitest
* import { Effect, Exit } from "effect"
*
* const program = Effect.validate([0, 1, 2, 3], (n) =>
* n % 2 === 0 ? Effect.fail(`${n} is even`) : Effect.succeed(n)
* )
*
* await Effect.runPromiseExit(program) // => Exit.fail(["0 is even", "2 is even"])
* ```
*
* @stability stable
* @category collecting
* @since 2.0.0
*/
(
elements: Iterable,
f: (a: A, i: number) => Effect,
options?: {
readonly concurrency?: Concurrency | undefined
readonly discard?: false | undefined
} | undefined
): Effect, Arr.NonEmptyArray, R>
/**
* Applies an effectful function to each element and accumulates all failures.
*
* **Details**
*
* This function always evaluates every element. If at least one effect fails,
* all failures are returned as a non-empty array and successes are discarded.
* If all effects succeed, it returns all collected successes.
*
* Use `discard: true` to ignore successful values while still validating all
* elements.
*
* **Example** (Validating every element)
*
* ```ts import.meta.vitest
* import { Effect, Exit } from "effect"
*
* const program = Effect.validate([0, 1, 2, 3], (n) =>
* n % 2 === 0 ? Effect.fail(`${n} is even`) : Effect.succeed(n)
* )
*
* await Effect.runPromiseExit(program) // => Exit.fail(["0 is even", "2 is even"])
* ```
*
* @stability stable
* @category collecting
* @since 2.0.0
*/
(
elements: Iterable,
f: (a: A, i: number) => Effect,
options: {
readonly concurrency?: Concurrency | undefined
readonly discard: true
}
): Effect, R>
} = internal.validate
/**
* Returns the first element that satisfies an effectful predicate.
*
* **Details**
*
* The predicate receives the element and its index. Evaluation short-circuits
* as soon as an element matches.
*
* **Example** (Finding the first successful match)
*
* ```ts import.meta.vitest
* import { Effect, Option } from "effect"
*
* const program = Effect.findFirst([1, 2, 3, 4], (n) => Effect.succeed(n > 2))
*
* await Effect.runPromise(program) // => Option.some(3)
* ```
*
* @stability stable
* @category collecting
* @since 2.0.0
*/
export const findFirst: {
/**
* Returns the first element that satisfies an effectful predicate.
*
* **Details**
*
* The predicate receives the element and its index. Evaluation short-circuits
* as soon as an element matches.
*
* **Example** (Finding the first successful match)
*
* ```ts import.meta.vitest
* import { Effect, Option } from "effect"
*
* const program = Effect.findFirst([1, 2, 3, 4], (n) => Effect.succeed(n > 2))
*
* await Effect.runPromise(program) // => Option.some(3)
* ```
*
* @stability stable
* @category collecting
* @since 2.0.0
*/
(predicate: (a: NoInfer, i: number) => Effect): (elements: Iterable) => Effect, E, R>
/**
* Returns the first element that satisfies an effectful predicate.
*
* **Details**
*
* The predicate receives the element and its index. Evaluation short-circuits
* as soon as an element matches.
*
* **Example** (Finding the first successful match)
*
* ```ts import.meta.vitest
* import { Effect, Option } from "effect"
*
* const program = Effect.findFirst([1, 2, 3, 4], (n) => Effect.succeed(n > 2))
*
* await Effect.runPromise(program) // => Option.some(3)
* ```
*
* @stability stable
* @category collecting
* @since 2.0.0
*/
(
elements: Iterable,
predicate: (a: NoInfer, i: number) => Effect
): Effect, E, R>
} = internal.findFirst
/**
* Returns the first value that passes an effectful `FilterEffect`.
*
* **When to use**
*
* Use when you need to find the first element that satisfies an effectful
* filter returning a `Result`, which also transforms the matching element.
*
* **Details**
*
* The filter receives the element and index. Evaluation short-circuits on the
* first `Result.succeed` and returns the transformed value in `Option.some`.
*
* @see {@link findFirst} for the simpler effectful predicate-based variant
*
* @stability stable
* @category collecting
* @since 4.0.0
*/
export const findFirstFilter: {
/**
* Returns the first value that passes an effectful `FilterEffect`.
*
* **When to use**
*
* Use when you need to find the first element that satisfies an effectful
* filter returning a `Result`, which also transforms the matching element.
*
* **Details**
*
* The filter receives the element and index. Evaluation short-circuits on the
* first `Result.succeed` and returns the transformed value in `Option.some`.
*
* @see {@link findFirst} for the simpler effectful predicate-based variant
*
* @stability stable
* @category collecting
* @since 4.0.0
*/
(
filter: (input: NoInfer, i: number) => Effect, E, R>
): (elements: Iterable) => Effect, E, R>
/**
* Returns the first value that passes an effectful `FilterEffect`.
*
* **When to use**
*
* Use when you need to find the first element that satisfies an effectful
* filter returning a `Result`, which also transforms the matching element.
*
* **Details**
*
* The filter receives the element and index. Evaluation short-circuits on the
* first `Result.succeed` and returns the transformed value in `Option.some`.
*
* @see {@link findFirst} for the simpler effectful predicate-based variant
*
* @stability stable
* @category collecting
* @since 4.0.0
*/
(
elements: Iterable,
filter: (input: NoInfer, i: number) => Effect, E, R>
): Effect, E, R>
} = internal.findFirstFilter
/**
* Executes an effectful operation for each element in an `Iterable`.
*
* **When to use**
*
* Use to traverse an iterable with an effectful function while preserving
* element order in the collected results.
*
* **Details**
*
* The `forEach` function applies a provided operation to each element in the
* iterable, producing a new effect that returns an array of results.
*
* If any effect fails, the iteration stops immediately (short-circuiting), and
* the error is propagated.
*
* Concurrency:
*
* The `concurrency` option controls how many operations are performed
* concurrently. By default, the operations are performed sequentially.
*
* Discarding Results:
*
* If the `discard` option is set to `true`, the intermediate results are not
* collected, and the final result of the operation is `void`.
*
* **Example** (Mapping over an iterable with effects)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
* const output: Array = []
*
* const result = Effect.forEach(
* [1, 2, 3, 4, 5],
* (n, index) =>
* Effect.sync(() => { output.push(`Currently at index ${index}`) }).pipe(Effect.as(n * 2))
* )
*
* void output.push(await Effect.runPromise(result))
* output // => ["Currently at index 0", "Currently at index 1", "Currently at index 2", "Currently at index 3", "Currently at index 4", [2, 4, 6, 8, 10]]
* ```
*
* **Example** (Running effects without collecting results)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
* const output: Array = []
*
* // Apply effects but discard the results
* const result = Effect.forEach(
* [1, 2, 3, 4, 5],
* (n, index) =>
* Effect.sync(() => { output.push(`Currently at index ${index}`) }).pipe(Effect.as(n * 2)),
* { discard: true }
* )
*
* void output.push(await Effect.runPromise(result))
* output // => ["Currently at index 0", "Currently at index 1", "Currently at index 2", "Currently at index 3", "Currently at index 4", undefined]
* ```
*
* @see {@link all} for combining multiple effects into one.
* @stability stable
* @category collecting
* @since 2.0.0
*/
export const forEach: {
/**
* Executes an effectful operation for each element in an `Iterable`.
*
* **When to use**
*
* Use to traverse an iterable with an effectful function while preserving
* element order in the collected results.
*
* **Details**
*
* The `forEach` function applies a provided operation to each element in the
* iterable, producing a new effect that returns an array of results.
*
* If any effect fails, the iteration stops immediately (short-circuiting), and
* the error is propagated.
*
* Concurrency:
*
* The `concurrency` option controls how many operations are performed
* concurrently. By default, the operations are performed sequentially.
*
* Discarding Results:
*
* If the `discard` option is set to `true`, the intermediate results are not
* collected, and the final result of the operation is `void`.
*
* **Example** (Mapping over an iterable with effects)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
* const output: Array = []
*
* const result = Effect.forEach(
* [1, 2, 3, 4, 5],
* (n, index) =>
* Effect.sync(() => { output.push(`Currently at index ${index}`) }).pipe(Effect.as(n * 2))
* )
*
* void output.push(await Effect.runPromise(result))
* output // => ["Currently at index 0", "Currently at index 1", "Currently at index 2", "Currently at index 3", "Currently at index 4", [2, 4, 6, 8, 10]]
* ```
*
* **Example** (Running effects without collecting results)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
* const output: Array = []
*
* // Apply effects but discard the results
* const result = Effect.forEach(
* [1, 2, 3, 4, 5],
* (n, index) =>
* Effect.sync(() => { output.push(`Currently at index ${index}`) }).pipe(Effect.as(n * 2)),
* { discard: true }
* )
*
* void output.push(await Effect.runPromise(result))
* output // => ["Currently at index 0", "Currently at index 1", "Currently at index 2", "Currently at index 3", "Currently at index 4", undefined]
* ```
*
* @see {@link all} for combining multiple effects into one.
* @stability stable
* @category collecting
* @since 2.0.0
*/
= Iterable, const Discard extends boolean = false>(
f: (a: A, i: number) => Effect,
options?: { readonly concurrency?: Concurrency | undefined; readonly discard?: Discard | undefined } | undefined
): (
self: [S] extends [never] ? Iterable : S
) => Effect : void, E, R>
/**
* Executes an effectful operation for each element in an `Iterable`.
*
* **When to use**
*
* Use to traverse an iterable with an effectful function while preserving
* element order in the collected results.
*
* **Details**
*
* The `forEach` function applies a provided operation to each element in the
* iterable, producing a new effect that returns an array of results.
*
* If any effect fails, the iteration stops immediately (short-circuiting), and
* the error is propagated.
*
* Concurrency:
*
* The `concurrency` option controls how many operations are performed
* concurrently. By default, the operations are performed sequentially.
*
* Discarding Results:
*
* If the `discard` option is set to `true`, the intermediate results are not
* collected, and the final result of the operation is `void`.
*
* **Example** (Mapping over an iterable with effects)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
* const output: Array = []
*
* const result = Effect.forEach(
* [1, 2, 3, 4, 5],
* (n, index) =>
* Effect.sync(() => { output.push(`Currently at index ${index}`) }).pipe(Effect.as(n * 2))
* )
*
* void output.push(await Effect.runPromise(result))
* output // => ["Currently at index 0", "Currently at index 1", "Currently at index 2", "Currently at index 3", "Currently at index 4", [2, 4, 6, 8, 10]]
* ```
*
* **Example** (Running effects without collecting results)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
* const output: Array = []
*
* // Apply effects but discard the results
* const result = Effect.forEach(
* [1, 2, 3, 4, 5],
* (n, index) =>
* Effect.sync(() => { output.push(`Currently at index ${index}`) }).pipe(Effect.as(n * 2)),
* { discard: true }
* )
*
* void output.push(await Effect.runPromise(result))
* output // => ["Currently at index 0", "Currently at index 1", "Currently at index 2", "Currently at index 3", "Currently at index 4", undefined]
* ```
*
* @see {@link all} for combining multiple effects into one.
* @stability stable
* @category collecting
* @since 2.0.0
*/
, const Discard extends boolean = false>(
self: S,
f: (a: Arr.ReadonlyArray.Infer, i: number) => Effect,
options?: { readonly concurrency?: Concurrency | undefined; readonly discard?: Discard | undefined } | undefined
): Effect : void, E, R>
} = internal.forEach
/**
* Returns the first element of the iterable produced by an effect, or fails
* with `NoSuchElementError` if the iterable is empty.
*
* **When to use**
*
* Use when an effect produces a collection that must contain at least one
* element and absence should be represented in the typed error channel.
*
* **Example** (Getting the first element)
*
* ```ts import.meta.vitest
* import { Effect, Option } from "effect"
*
* const first = await Effect.runPromise(Effect.head(Effect.succeed([1, 2, 3])))
* first // => 1
*
* const empty = Effect.head(Effect.succeed([] as Array)).pipe(Effect.catchNoSuchElement)
* await Effect.runPromise(empty) // => Option.none()
* ```
*
* @stability stable
* @category collecting
* @since 2.0.0
*/
export const head: (
self: Effect, E, R>
) => Effect = internal.head
/**
* Executes a body effect repeatedly while a condition holds true.
*
* **Example** (Repeating an effectful loop)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
* const output: Array = []
*
* let counter = 0
*
* const program = Effect.whileLoop({
* while: () => counter < 5,
* body: () => Effect.sync(() => ++counter),
* step: (n) => void output.push(`Current count: ${n}`)
* })
*
* await Effect.runPromise(program)
* output // => ["Current count: 1", "Current count: 2", "Current count: 3", "Current count: 4", "Current count: 5"]
* ```
*
* @stability stable
* @category repetition
* @since 2.0.0
*/
export const whileLoop: (options: {
readonly while: LazyArg
readonly body: LazyArg>
readonly step: (a: A) => void
}) => Effect = internal.whileLoop
// -----------------------------------------------------------------------------
// Creating Effects
// -----------------------------------------------------------------------------
/**
* Creates an `Effect` that represents an asynchronous computation guaranteed to
* succeed.
*
* **When to use**
*
* Use to convert a `Promise` into an `Effect` when the async operation is
* guaranteed to succeed and will not reject.
*
* **Details**
*
* If `evaluate` declares a parameter, it receives an `AbortSignal` that is
* aborted if the effect is interrupted. Zero-argument thunks do not allocate
* an `AbortController`.
*
* **Gotchas**
*
* The `Promise` must not reject. If it rejects, the rejection is treated as a
* defect, not as a typed failure. Use `tryPromise` when rejection is expected.
*
* Interruption aborts the provided `AbortSignal`, but the underlying
* asynchronous operation only stops if it observes that signal.
*
* The parameter check reads the `length` property of `evaluate`, which does
* not count a rest parameter or any parameter from the first default value
* onward. `(...args) => ...` and `(signal = fallback) => ...` therefore
* receive `undefined` instead of a signal, as do wrappers that forward
* arguments through rest parameters. Declare the signal as an ordinary
* parameter: `(signal) => ...`.
*
* **Example** (Wrapping a non-rejecting Promise)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* const succeedAsync = (message: string) =>
* Effect.promise(() => Promise.resolve(message))
*
* // ┌─── Effect
* // ▼
* const program = succeedAsync("Async operation completed successfully!")
* await Effect.runPromise(program) // => "Async operation completed successfully!"
* ```
*
* @see {@link tryPromise} for a version that can handle failures.
* @stability stable
* @category constructors
* @since 2.0.0
*/
export const promise: (
evaluate: (signal: AbortSignal) => PromiseLike
) => Effect = internal.promise
/**
* Creates an `Effect` from an asynchronous computation that may throw or
* reject, mapping failures into the error channel.
*
* **When to use**
*
* Use when you need to perform asynchronous operations that might fail, such
* as fetching data from an API, and want thrown exceptions or rejected promises
* captured as Effect errors.
*
* **Details**
*
* The promise thunk is evaluated when the effect runs. If it returns a promise
* that resolves, the resolved value becomes the success value. If the thunk
* throws before returning a promise, or if the returned promise rejects, the
* thrown or rejected value is mapped into the error channel.
*
* Passing the thunk directly maps failures to {@link Cause.UnknownError}.
* Passing `{ try, catch }` uses `catch` to map failures to an error of type
* `E`.
*
* If the thunk declares a parameter, it receives an `AbortSignal` that is
* aborted if the effect is interrupted. The underlying asynchronous operation
* only stops if it observes that signal. Zero-argument thunks do not allocate
* an `AbortController`.
*
* **Gotchas**
*
* If `catch` throws while mapping the error, that thrown value is treated as a
* defect. Return the error value you want in the error channel instead of
* throwing it.
*
* The parameter check reads the thunk's `length` property, which does not
* count a rest parameter or any parameter from the first default value
* onward. `(...args) => ...` and `(signal = fallback) => ...` therefore
* receive `undefined` instead of a signal, as do wrappers that forward
* arguments through rest parameters. Declare the signal as an ordinary
* parameter: `(signal) => ...`.
*
* **Example** (Wrapping a fetch request that may fail)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* const getTodo = (id: number) =>
* Effect.tryPromise(() => Promise.resolve({ id, completed: false }))
*
* // ┌─── Effect<{ id: number; completed: boolean }, UnknownError, never>
* // ▼
* const program = getTodo(1)
* await Effect.runPromise(program) // => { id: 1, completed: false }
* ```
*
* **Example** (Mapping Promise rejections to a tagged error)
*
* ```ts import.meta.vitest
* import { Data, Effect } from "effect"
*
* class TodoFetchError extends Data.TaggedError("TodoFetchError")<{ readonly cause: unknown }> {}
*
* const getTodo = (id: number) =>
* Effect.tryPromise({
* try: () => Promise.reject(`Todo ${id} is unavailable`),
* // remap the error
* catch: (cause) => new TodoFetchError({ cause })
* })
*
* // ┌─── Effect
* // ▼
* const program = Effect.flip(getTodo(1))
* const error = await Effect.runPromise(program)
* error._tag // => "TodoFetchError"
* ```
*
* @see {@link promise} if the effectful computation is asynchronous and does not throw errors.
* @stability stable
* @category constructors
* @since 2.0.0
*/
export const tryPromise: {
/**
* Creates an `Effect` from an asynchronous computation that may throw or
* reject, mapping failures into the error channel.
*
* **When to use**
*
* Use when you need to perform asynchronous operations that might fail, such
* as fetching data from an API, and want thrown exceptions or rejected promises
* captured as Effect errors.
*
* **Details**
*
* The promise thunk is evaluated when the effect runs. If it returns a promise
* that resolves, the resolved value becomes the success value. If the thunk
* throws before returning a promise, or if the returned promise rejects, the
* thrown or rejected value is mapped into the error channel.
*
* Passing the thunk directly maps failures to {@link Cause.UnknownError}.
* Passing `{ try, catch }` uses `catch` to map failures to an error of type
* `E`.
*
* If the thunk declares a parameter, it receives an `AbortSignal` that is
* aborted if the effect is interrupted. The underlying asynchronous operation
* only stops if it observes that signal. Zero-argument thunks do not allocate
* an `AbortController`.
*
* **Gotchas**
*
* If `catch` throws while mapping the error, that thrown value is treated as a
* defect. Return the error value you want in the error channel instead of
* throwing it.
*
* The parameter check reads the thunk's `length` property, which does not
* count a rest parameter or any parameter from the first default value
* onward. `(...args) => ...` and `(signal = fallback) => ...` therefore
* receive `undefined` instead of a signal, as do wrappers that forward
* arguments through rest parameters. Declare the signal as an ordinary
* parameter: `(signal) => ...`.
*
* **Example** (Wrapping a fetch request that may fail)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* const getTodo = (id: number) =>
* Effect.tryPromise(() => Promise.resolve({ id, completed: false }))
*
* // ┌─── Effect<{ id: number; completed: boolean }, UnknownError, never>
* // ▼
* const program = getTodo(1)
* await Effect.runPromise(program) // => { id: 1, completed: false }
* ```
*
* **Example** (Mapping Promise rejections to a tagged error)
*
* ```ts import.meta.vitest
* import { Data, Effect } from "effect"
*
* class TodoFetchError extends Data.TaggedError("TodoFetchError")<{ readonly cause: unknown }> {}
*
* const getTodo = (id: number) =>
* Effect.tryPromise({
* try: () => Promise.reject(`Todo ${id} is unavailable`),
* // remap the error
* catch: (cause) => new TodoFetchError({ cause })
* })
*
* // ┌─── Effect
* // ▼
* const program = Effect.flip(getTodo(1))
* const error = await Effect.runPromise(program)
* error._tag // => "TodoFetchError"
* ```
*
* @see {@link promise} if the effectful computation is asynchronous and does not throw errors.
* @stability stable
* @category constructors
* @since 2.0.0
*/
(options: (signal: AbortSignal) => PromiseLike): Effect
/**
* Creates an `Effect` from an asynchronous computation that may throw or
* reject, mapping failures into the error channel.
*
* **When to use**
*
* Use when you need to perform asynchronous operations that might fail, such
* as fetching data from an API, and want thrown exceptions or rejected promises
* captured as Effect errors.
*
* **Details**
*
* The promise thunk is evaluated when the effect runs. If it returns a promise
* that resolves, the resolved value becomes the success value. If the thunk
* throws before returning a promise, or if the returned promise rejects, the
* thrown or rejected value is mapped into the error channel.
*
* Passing the thunk directly maps failures to {@link Cause.UnknownError}.
* Passing `{ try, catch }` uses `catch` to map failures to an error of type
* `E`.
*
* If the thunk declares a parameter, it receives an `AbortSignal` that is
* aborted if the effect is interrupted. The underlying asynchronous operation
* only stops if it observes that signal. Zero-argument thunks do not allocate
* an `AbortController`.
*
* **Gotchas**
*
* If `catch` throws while mapping the error, that thrown value is treated as a
* defect. Return the error value you want in the error channel instead of
* throwing it.
*
* The parameter check reads the thunk's `length` property, which does not
* count a rest parameter or any parameter from the first default value
* onward. `(...args) => ...` and `(signal = fallback) => ...` therefore
* receive `undefined` instead of a signal, as do wrappers that forward
* arguments through rest parameters. Declare the signal as an ordinary
* parameter: `(signal) => ...`.
*
* **Example** (Wrapping a fetch request that may fail)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* const getTodo = (id: number) =>
* Effect.tryPromise(() => Promise.resolve({ id, completed: false }))
*
* // ┌─── Effect<{ id: number; completed: boolean }, UnknownError, never>
* // ▼
* const program = getTodo(1)
* await Effect.runPromise(program) // => { id: 1, completed: false }
* ```
*
* **Example** (Mapping Promise rejections to a tagged error)
*
* ```ts import.meta.vitest
* import { Data, Effect } from "effect"
*
* class TodoFetchError extends Data.TaggedError("TodoFetchError")<{ readonly cause: unknown }> {}
*
* const getTodo = (id: number) =>
* Effect.tryPromise({
* try: () => Promise.reject(`Todo ${id} is unavailable`),
* // remap the error
* catch: (cause) => new TodoFetchError({ cause })
* })
*
* // ┌─── Effect
* // ▼
* const program = Effect.flip(getTodo(1))
* const error = await Effect.runPromise(program)
* error._tag // => "TodoFetchError"
* ```
*
* @see {@link promise} if the effectful computation is asynchronous and does not throw errors.
* @stability stable
* @category constructors
* @since 2.0.0
*/
(
options: { readonly try: (signal: AbortSignal) => PromiseLike; readonly catch: (error: unknown) => E }
): Effect
} = internal.tryPromise
/**
* Creates an `Effect` that always succeeds with a given value.
*
* **When to use**
*
* Use when an effect should complete successfully with a specific value without any errors
* or external dependencies.
*
* **Example** (Creating a successful effect)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* // Creating an effect that represents a successful scenario
* //
* // ┌─── Effect
* // ▼
* const success = Effect.succeed(42)
* Effect.runSync(success) // => 42
* ```
*
* @see {@link fail} to create an effect that represents a failure.
* @stability stable
* @category constructors
* @since 2.0.0
*/
export const succeed: (value: A) => Effect = internal.succeed
/**
* Returns an effect which succeeds with `None`.
*
* **Example** (Succeeding with Option.none)
*
* ```ts import.meta.vitest
* import { Effect, Option } from "effect"
*
* const program = Effect.succeedNone
*
* Effect.runSync(program) // => Option.none()
* ```
*
* @stability stable
* @category constructors
* @since 2.0.0
*/
export const succeedNone: Effect> = internal.succeedNone
/**
* Returns an effect which succeeds with the value wrapped in a `Some`.
*
* **Example** (Succeeding with Option.some)
*
* ```ts import.meta.vitest
* import { Effect, Option } from "effect"
*
* const program = Effect.succeedSome(42)
*
* Effect.runSync(program) // => Option.some(42)
* ```
*
* @stability stable
* @category constructors
* @since 2.0.0
*/
export const succeedSome: (value: A) => Effect> = internal.succeedSome
/**
* Creates an `Effect` lazily, delaying construction until it is needed.
*
* **When to use**
*
* Use when you need to defer the evaluation of an effect until it is required.
*
* **Details**
*
* `suspend` takes a thunk that represents an effect and delays creating it
* until the suspended effect is evaluated. This is useful for optimizing
* expensive computations, managing circular dependencies such as recursive
* functions, and helping TypeScript unify return types when branches construct
* different effects. Any side effects or scoped captures inside the thunk are
* re-executed on each invocation.
*
* **Example** (Lazily evaluating side effects)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* let i = 0
*
* const bad = Effect.succeed(i++)
*
* const good = Effect.suspend(() => Effect.succeed(i++))
*
* Effect.runSync(bad) // => 0
* Effect.runSync(bad) // => 0
*
* Effect.runSync(good) // => 1
* Effect.runSync(good) // => 2
* ```
*
* **Example** (Suspending recursive Fibonacci evaluation)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* const blowsUp = (n: number): Effect.Effect =>
* n < 2
* ? Effect.succeed(1)
* : Effect.zipWith(blowsUp(n - 1), blowsUp(n - 2), (a, b) => a + b)
*
* // console.log(Effect.runSync(blowsUp(32)))
* // crash: JavaScript heap out of memory
*
* const allGood = (n: number): Effect.Effect =>
* n < 2
* ? Effect.succeed(1)
* : Effect.zipWith(
* Effect.suspend(() => allGood(n - 1)),
* Effect.suspend(() => allGood(n - 2)),
* (a, b) => a + b
* )
*
* Effect.runSync(allGood(16)) // => 1597
* ```
*
* **Example** (Helping TypeScript infer recursive effect types)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* // Without suspend, TypeScript may struggle with type inference.
* // Inferred type:
* // (a: number, b: number) =>
* // Effect | Effect
* const withoutSuspend = (a: number, b: number) =>
* b === 0
* ? Effect.fail(new Error("Cannot divide by zero"))
* : Effect.succeed(a / b)
*
* // Using suspend to unify return types.
* // Inferred type:
* // (a: number, b: number) => Effect
* const withSuspend = (a: number, b: number) =>
* Effect.suspend(() =>
* b === 0
* ? Effect.fail(new Error("Cannot divide by zero"))
* : Effect.succeed(a / b)
* )
*
* Effect.runSync(withSuspend(6, 2)) // => 3
* ```
*
* @stability stable
* @category constructors
* @since 2.0.0
*/
export const suspend: (
effect: LazyArg>
) => Effect = internal.suspend
/**
* Creates an `Effect` that represents a synchronous side-effectful computation.
*
* **When to use**
*
* Use when you need to wrap a synchronous side-effectful operation that is not
* expected to throw.
*
* **Details**
*
* The provided function is evaluated lazily when the effect runs.
*
* **Gotchas**
*
* The function must not throw. If it throws, the thrown value is treated as a
* defect, not as a typed failure. Use `try` when throwing is expected.
*
* **Example** (Capturing synchronous logging in an Effect)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
* const output: Array = []
*
* const log = (message: string) =>
* Effect.sync(() => {
* void output.push(message) // side effect
* })
*
* // ┌─── Effect
* // ▼
* const program = log("Hello, World!")
* Effect.runSync(program)
* output // => ["Hello, World!"]
* ```
*
* @see {@link try_ | try} for a version that can handle failures.
* @stability stable
* @category constructors
* @since 2.0.0
*/
export const sync: (thunk: LazyArg) => Effect = internal.sync
const void_: Effect = internal.void
export {
/**
* Returns an effect that succeeds with `void`.
*
* @stability stable
* @category constructors
* @since 2.0.0
*/
void_ as void
}
const undefined_: Effect = internal.undefined
export {
/**
* Returns an effect that succeeds with `undefined`.
*
* @stability stable
* @category constructors
* @since 4.0.0
*/
undefined_ as undefined
}
/**
* Creates an `Effect` from a callback-based asynchronous API.
*
* **When to use**
*
* Use when you need to integrate APIs that complete through callbacks instead
* of returning a `Promise`.
*
* **Details**
*
* The registration function receives a `resume` callback and, if it declares
* a second parameter, an `AbortSignal` that is aborted if the fiber is
* interrupted. Call `resume` at most once with the effect that should complete
* the fiber; later calls are ignored. Return an optional cleanup effect from
* the registration function to run if the fiber is interrupted.
*
* **Gotchas**
*
* The parameter check reads the registration function's `length` property,
* which must be at least `2` and does not count a rest parameter or any
* parameter from the first default value onward. `(...args) => ...` and
* `(resume, signal = fallback) => ...` therefore receive `undefined` instead
* of a signal, as do wrappers that forward arguments through rest parameters.
* Declare both as ordinary parameters: `(resume, signal) => ...`.
*
* **Example** (Integrating callback APIs)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
* const output: Array = []
*
* const fromCallback = (message: string) =>
* Effect.callback((resume) => {
* queueMicrotask(() => {
* void output.push(message)
* resume(Effect.void)
* })
* })
*
* await Effect.runPromise(fromCallback("callback completed"))
* output // => ["callback completed"]
* ```
*
* @stability stable
* @category constructors
* @since 4.0.0
*/
export const callback: (
register: (
this: Scheduler,
resume: (effect: Effect) => void,
signal: AbortSignal
) => void | Effect
) => Effect = internal.callback
/**
* Returns an effect that will never produce anything. The moral equivalent of
* `while(true) {}`, only without the wasted CPU cycles.
*
* **Example** (Creating a never-ending effect)
*
* ```ts import.meta.vitest
* import { Effect, Option } from "effect"
*
* const program = Effect.timeoutOption(Effect.never, 0)
* await Effect.runPromise(program) // => Option.none()
* ```
*
* @stability stable
* @category constructors
* @since 2.0.0
*/
export const never: Effect = internal.never
/**
* Effect that succeeds with an empty record `{}`, used as the starting point
* for do notation chains.
*
* **Example** (Starting do notation)
*
* ```ts import.meta.vitest
* import { Effect, pipe } from "effect"
*
* const program = pipe(
* Effect.Do,
* Effect.bind("x", () => Effect.succeed(2)),
* Effect.bind("y", ({ x }) => Effect.succeed(x + 1)),
* Effect.let("sum", ({ x, y }) => x + y)
* )
*
* Effect.runSync(program) // => { x: 2, y: 3, sum: 5 }
* ```
*
* @stability stable
* @category do notation
* @since 2.0.0
*/
export const Do: Effect<{}> = internal.Do
/**
* Gives a name to the success value of an `Effect`, creating a single-key
* record used in do notation pipelines.
*
* **When to use**
*
* Use to start a do-notation pipeline from an existing `Effect` when its
* success value should become the first named field in the accumulated record.
*
* @see {@link Do} for starting from an empty accumulated record
* @see {@link bind} for adding fields produced by effects
*
* @stability stable
* @category do notation
* @since 2.0.0
*/
export const bindTo: {
/**
* Gives a name to the success value of an `Effect`, creating a single-key
* record used in do notation pipelines.
*
* **When to use**
*
* Use to start a do-notation pipeline from an existing `Effect` when its
* success value should become the first named field in the accumulated record.
*
* @see {@link Do} for starting from an empty accumulated record
* @see {@link bind} for adding fields produced by effects
*
* @stability stable
* @category do notation
* @since 2.0.0
*/
(name: N): (self: Effect) => Effect<{ [K in N]: A }, E, R>
/**
* Gives a name to the success value of an `Effect`, creating a single-key
* record used in do notation pipelines.
*
* **When to use**
*
* Use to start a do-notation pipeline from an existing `Effect` when its
* success value should become the first named field in the accumulated record.
*
* @see {@link Do} for starting from an empty accumulated record
* @see {@link bind} for adding fields produced by effects
*
* @stability stable
* @category do notation
* @since 2.0.0
*/
(self: Effect, name: N): Effect<{ [K in N]: A }, E, R>
} = internal.bindTo
const let_: {
, B>(
name: N,
f: (a: NoInfer) => B
): (
self: Effect
) => Effect & Record>, E, R>
, E, R, B, N extends string>(
self: Effect,
name: N,
f: (a: NoInfer) => B
): Effect & Record>, E, R>
} = internal.let
export {
/**
* Adds a computed plain value to the do notation record.
*
* **When to use**
*
* Use to add a derived, synchronous value to a do-notation pipeline when it
* depends on fields already accumulated in the record and does not need to run
* another `Effect`.
*
* **Details**
*
* The new field is added with object spreading. If the name already exists in
* the record, the computed value replaces it in the returned type.
*
* @see {@link bind} for adding fields produced by effects
* @see {@link bindTo} for naming an existing success value
* @see {@link Do} for starting from an empty accumulated record
* @see {@link gen} for sequencing without accumulating a record
*
* @stability stable
* @category do notation
* @since 2.0.0
*/
let_ as let
}
/**
* Adds an `Effect` value to the do notation record under a given name.
*
* **When to use**
*
* Use to sequence an effectful step in a do-notation pipeline when that step
* depends on fields already accumulated in the record and its success value
* should be stored under a name.
*
* **Details**
*
* The function receives the current record, runs the returned effect after the
* input effect succeeds, and inserts its success value under `name`. The
* resulting effect combines the error and service requirements of both steps.
*
* **Gotchas**
*
* Binding a name that already exists replaces that field in the resulting
* record.
*
* @see {@link Do} for starting from an empty do-notation record
* @see {@link bindTo} for naming the success value of an existing effect
* @see {@link gen} for generator-based sequencing without accumulating a record
*
* @stability stable
* @category do notation
* @since 2.0.0
*/
export const bind: {
/**
* Adds an `Effect` value to the do notation record under a given name.
*
* **When to use**
*
* Use to sequence an effectful step in a do-notation pipeline when that step
* depends on fields already accumulated in the record and its success value
* should be stored under a name.
*
* **Details**
*
* The function receives the current record, runs the returned effect after the
* input effect succeeds, and inserts its success value under `name`. The
* resulting effect combines the error and service requirements of both steps.
*
* **Gotchas**
*
* Binding a name that already exists replaces that field in the resulting
* record.
*
* @see {@link Do} for starting from an empty do-notation record
* @see {@link bindTo} for naming the success value of an existing effect
* @see {@link gen} for generator-based sequencing without accumulating a record
*
* @stability stable
* @category do notation
* @since 2.0.0
*/
, B, E2, R2>(name: N, f: (a: NoInfer) => Effect): (
self: Effect
) => Effect & Record>, E | E2, R | R2>
/**
* Adds an `Effect` value to the do notation record under a given name.
*
* **When to use**
*
* Use to sequence an effectful step in a do-notation pipeline when that step
* depends on fields already accumulated in the record and its success value
* should be stored under a name.
*
* **Details**
*
* The function receives the current record, runs the returned effect after the
* input effect succeeds, and inserts its success value under `name`. The
* resulting effect combines the error and service requirements of both steps.
*
* **Gotchas**
*
* Binding a name that already exists replaces that field in the resulting
* record.
*
* @see {@link Do} for starting from an empty do-notation record
* @see {@link bindTo} for naming the success value of an existing effect
* @see {@link gen} for generator-based sequencing without accumulating a record
*
* @stability stable
* @category do notation
* @since 2.0.0
*/
, E, R, B, E2, R2, N extends string>(self: Effect, name: N, f: (a: NoInfer) => Effect): Effect & Record>, E | E2, R | R2>
} = internal.bind
/**
* Provides a way to write effectful code using generator functions, simplifying
* control flow and error handling.
*
* **When to use**
*
* Use when you want to write effectful code that looks and behaves like
* synchronous code, while still handling asynchronous tasks, errors, and complex
* control flow such as loops and conditions.
*
* Generator functions work similarly to `async/await` but keep errors,
* requirements, and interruption in the Effect type. You can `yield*` values
* from effects and return the final result at the end.
*
* **Example** (Sequencing effects with generators)
*
* ```ts import.meta.vitest
* import { Data, Effect } from "effect"
*
* class DiscountRateError extends Data.TaggedError("DiscountRateError")<{}> {}
*
* const addServiceCharge = (amount: number) => amount + 1
*
* const applyDiscount = (
* total: number,
* discountRate: number
* ): Effect.Effect =>
* discountRate === 0
* ? Effect.fail(new DiscountRateError())
* : Effect.succeed(total - (total * discountRate) / 100)
*
* const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))
*
* const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))
*
* export const program = Effect.gen(function*() {
* const transactionAmount = yield* fetchTransactionAmount
* const discountRate = yield* fetchDiscountRate
* const discountedAmount = yield* applyDiscount(
* transactionAmount,
* discountRate
* )
* const finalAmount = addServiceCharge(discountedAmount)
* return `Final amount to charge: ${finalAmount}`
* })
*
* await Effect.runPromise(program) // => "Final amount to charge: 96"
* ```
*
* @stability stable
* @category constructors
* @since 2.0.0
*/
export const gen: {
/**
* Provides a way to write effectful code using generator functions, simplifying
* control flow and error handling.
*
* **When to use**
*
* Use when you want to write effectful code that looks and behaves like
* synchronous code, while still handling asynchronous tasks, errors, and complex
* control flow such as loops and conditions.
*
* Generator functions work similarly to `async/await` but keep errors,
* requirements, and interruption in the Effect type. You can `yield*` values
* from effects and return the final result at the end.
*
* **Example** (Sequencing effects with generators)
*
* ```ts import.meta.vitest
* import { Data, Effect } from "effect"
*
* class DiscountRateError extends Data.TaggedError("DiscountRateError")<{}> {}
*
* const addServiceCharge = (amount: number) => amount + 1
*
* const applyDiscount = (
* total: number,
* discountRate: number
* ): Effect.Effect =>
* discountRate === 0
* ? Effect.fail(new DiscountRateError())
* : Effect.succeed(total - (total * discountRate) / 100)
*
* const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))
*
* const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))
*
* export const program = Effect.gen(function*() {
* const transactionAmount = yield* fetchTransactionAmount
* const discountRate = yield* fetchDiscountRate
* const discountedAmount = yield* applyDiscount(
* transactionAmount,
* discountRate
* )
* const finalAmount = addServiceCharge(discountedAmount)
* return `Final amount to charge: ${finalAmount}`
* })
*
* await Effect.runPromise(program) // => "Final amount to charge: 96"
* ```
*
* @stability stable
* @category constructors
* @since 2.0.0
*/
, AEff>(f: () => Generator): Effect<
AEff,
[Eff] extends [never] ? never
: [Eff] extends [Effect] ? E
: never,
[Eff] extends [never] ? never
: [Eff] extends [Effect] ? R
: never
>
/**
* Provides a way to write effectful code using generator functions, simplifying
* control flow and error handling.
*
* **When to use**
*
* Use when you want to write effectful code that looks and behaves like
* synchronous code, while still handling asynchronous tasks, errors, and complex
* control flow such as loops and conditions.
*
* Generator functions work similarly to `async/await` but keep errors,
* requirements, and interruption in the Effect type. You can `yield*` values
* from effects and return the final result at the end.
*
* **Example** (Sequencing effects with generators)
*
* ```ts import.meta.vitest
* import { Data, Effect } from "effect"
*
* class DiscountRateError extends Data.TaggedError("DiscountRateError")<{}> {}
*
* const addServiceCharge = (amount: number) => amount + 1
*
* const applyDiscount = (
* total: number,
* discountRate: number
* ): Effect.Effect =>
* discountRate === 0
* ? Effect.fail(new DiscountRateError())
* : Effect.succeed(total - (total * discountRate) / 100)
*
* const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))
*
* const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))
*
* export const program = Effect.gen(function*() {
* const transactionAmount = yield* fetchTransactionAmount
* const discountRate = yield* fetchDiscountRate
* const discountedAmount = yield* applyDiscount(
* transactionAmount,
* discountRate
* )
* const finalAmount = addServiceCharge(discountedAmount)
* return `Final amount to charge: ${finalAmount}`
* })
*
* await Effect.runPromise(program) // => "Final amount to charge: 96"
* ```
*
* @stability stable
* @category constructors
* @since 2.0.0
*/
, AEff>(
options: {
readonly self: Self
},
f: (this: Self) => Generator
): Effect<
AEff,
[Eff] extends [never] ? never
: [Eff] extends [Effect] ? E
: never,
[Eff] extends [never] ? never
: [Eff] extends [Effect] ? R
: never
>
} = internal.gen
/**
* Type helpers for `Effect.gen` generator return signatures.
*
* @stability stable
* @category constructors
* @since 2.0.0
*/
export declare namespace gen {
/**
* Generator return type accepted by `Effect.gen`.
*
* @category constructors
* @since 4.0.0
*/
export type Return = Generator, A, any>
}
/**
* Creates an `Effect` that represents a recoverable error.
*
* **When to use**
*
* Use to explicitly signal a recoverable error in an `Effect`.
*
* **Details**
*
* The error keeps propagating unless it is handled. You can handle tagged
* errors with functions like {@link catchTag} or {@link catchTags}.
*
* **Example** (Creating a failed effect)
*
* ```ts import.meta.vitest
* import { Data, Effect } from "effect"
*
* class OperationFailedError extends Data.TaggedError("OperationFailedError")<{}> {}
*
* // ┌─── Effect
* // ▼
* const failure = Effect.fail(
* new OperationFailedError()
* )
* Effect.runSync(Effect.flip(failure))._tag // => "OperationFailedError"
* ```
*
* @see {@link succeed} to create an effect that represents a successful value.
* @stability stable
* @category constructors
* @since 2.0.0
*/
export const fail: (error: E) => Effect = internal.fail
/**
* Creates an `Effect` that represents a recoverable error using a lazy evaluation.
*
* **When to use**
*
* Use to defer computing a recoverable error value until the effect is run.
*
* **Details**
*
* The error-producing function is evaluated each time the effect is executed.
*
* **Example** (Lazily creating failures)
*
* ```ts import.meta.vitest
* import { Data, Effect } from "effect"
*
* class ProgramError extends Data.TaggedError("ProgramError")<{ readonly operation: string }> {}
*
* const program = Effect.failSync(() => new ProgramError({ operation: "sync" }))
*
* Effect.runSync(Effect.flip(program)).operation // => "sync"
* ```
*
* @stability stable
* @category constructors
* @since 2.0.0
*/
export const failSync: (evaluate: LazyArg) => Effect = internal.failSync
/**
* Creates an `Effect` that represents a failure with a specific `Cause`.
*
* **When to use**
*
* Use when you already have a full `Cause` and need to preserve defects,
* interruptions, annotations, or combined failures in the effect's failure
* channel.
*
* **Details**
*
* This function allows you to create effects that fail with complex error
* structures, including multiple errors, defects, interruptions, and more.
*
* **Example** (Failing with a full Cause)
*
* ```ts import.meta.vitest
* import { Cause, Effect } from "effect"
*
* const program = Effect.failCause(
* Cause.fail("Network error")
* )
*
* Effect.runSync(Effect.flip(program)) // => "Network error"
* ```
*
* @stability stable
* @category constructors
* @since 2.0.0
*/
export const failCause: (cause: Cause.Cause) => Effect = internal.failCause
/**
* Creates an `Effect` that represents a failure with a `Cause` computed lazily.
*
* **When to use**
*
* Use to defer computing a full `Cause` until the effect is run.
*
* **Details**
*
* The cause-producing function is evaluated each time the effect is executed.
*
* **Example** (Lazily creating a Cause)
*
* ```ts import.meta.vitest
* import { Cause, Effect } from "effect"
*
* const program = Effect.failCauseSync(() =>
* Cause.fail("Error computed at runtime")
* )
*
* Effect.runSync(Effect.flip(program)) // => "Error computed at runtime"
* ```
*
* @stability stable
* @category constructors
* @since 2.0.0
*/
export const failCauseSync: (
evaluate: LazyArg>
) => Effect = internal.failCauseSync
/**
* Creates an effect that terminates a fiber with a specified error.
*
* **When to use**
*
* Use when you need an `Effect` to report an unrecoverable defect instead of a
* typed error.
*
* **Details**
*
* The `die` function is used to signal a defect, which represents a critical
* and unexpected error in the code. When invoked, it produces an effect that
* does not handle the error and instead terminates the fiber.
*
* The error channel of the resulting effect is of type `never`, indicating that
* it cannot recover from this failure.
*
* **Example** (Failing on division by zero)
*
* ```ts import.meta.vitest
* import { Effect, Exit } from "effect"
*
* const defect = new Error("Cannot divide by zero")
* const divide = (a: number, b: number) =>
* b === 0
* ? Effect.die(defect)
* : Effect.succeed(a / b)
*
* // ┌─── Effect
* // ▼
* const program = divide(1, 0)
*
* Effect.runSyncExit(program) // => Exit.die(defect)
* ```
*
* @stability stable
* @category constructors
* @since 2.0.0
*/
export const die: (defect: unknown) => Effect = internal.die
const try_: {
(options: LazyArg): Effect
(options: {
readonly try: LazyArg
readonly catch: (error: unknown) => E
}): Effect
} = internal.try
export {
/**
* Creates an `Effect` from a synchronous computation that may throw, mapping
* thrown values into the error channel.
*
* **When to use**
*
* Use when you need to perform synchronous operations that might throw, such
* as parsing JSON, and want thrown exceptions captured as Effect errors.
*
* **Details**
*
* The thunk is evaluated when the effect runs. If it returns normally, the
* returned value becomes the success value. If it throws, the thrown value is
* mapped into the error channel.
*
* Passing the thunk directly maps failures to {@link Cause.UnknownError}.
* Passing `{ try, catch }` uses `catch` to map failures to an error of type
* `E`.
*
* **Gotchas**
*
* If `catch` throws while mapping the error, that thrown value is treated as
* a defect. Return the error value you want in the error channel instead of
* throwing it.
*
* **Example** (Parsing JSON)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* const parseJSON = (input: string) =>
* Effect.try(() => JSON.parse(input))
*
* // Success case
* await Effect.runPromise(parseJSON("{\"name\": \"Alice\"}")) // => { name: 'Alice' }
*
* // Failure case maps the thrown value to UnknownError
* const exit = await Effect.runPromiseExit(parseJSON("invalid json"))
* exit._tag // => "Failure"
* ```
*
* **Example** (Mapping exceptions to a tagged error)
*
* ```ts import.meta.vitest
* import { Data, Effect } from "effect"
*
* class JsonParsingError extends Data.TaggedError("JsonParsingError")<{ readonly cause: unknown }> {}
*
* const parseJSON = (input: string) =>
* Effect.try({
* try: () => JSON.parse(input),
* catch: (cause) => new JsonParsingError({ cause })
* })
*
* const error = await Effect.runPromise(Effect.flip(parseJSON("invalid json")))
* error._tag // => "JsonParsingError"
* ```
*
* @see {@link sync} if the effectful computation is synchronous and does not
* throw errors.
* @stability stable
* @category constructors
* @since 2.0.0
*/
try_ as try
}
/**
* Yields control back to the Effect runtime, allowing other fibers to execute.
*
* **Example** (Yielding to other fibers)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
* const output: Array = []
*
* const program = Effect.gen(function*() {
* void output.push("Before yield")
* yield* Effect.yieldNow
* void output.push("After yield")
* })
*
* await Effect.runPromise(program)
* output // => ["Before yield", "After yield"]
* ```
*
* @stability stable
* @category constructors
* @since 2.0.0
*/
export const yieldNow: Effect = internal.yieldNow
/**
* Yields control back to the Effect runtime with a specified priority, allowing other fibers to execute.
*
* **Example** (Yielding with priority)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
* const output: Array = []
*
* const program = Effect.gen(function*() {
* void output.push("High priority task")
* yield* Effect.yieldNowWith(10) // Higher priority
* void output.push("Continued after yield")
* })
*
* await Effect.runPromise(program)
* output // => ["High priority task", "Continued after yield"]
* ```
*
* @stability stable
* @category constructors
* @since 4.0.0
*/
export const yieldNowWith: (priority?: number) => Effect = internal.yieldNowWith
/**
* Provides access to the current fiber within an effect computation.
*
* **Example** (Reading the current fiber)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* const program = Effect.withFiber((fiber) => Effect.succeed(typeof fiber.id))
*
* Effect.runSync(program) // => "number"
* ```
*
* @stability stable
* @category constructors
* @since 4.0.0
*/
export const withFiber: (
evaluate: (fiber: Fiber) => Effect
) => Effect = core.withFiber
/**
* Accesses the current fiber to compute a successful value.
*
* **Example** (Computing a value from the current fiber)
*
* ```ts import.meta.vitest
* import { Effect } from "effect"
*
* const program = Effect.withFiberSucceed((fiber) => typeof fiber.id)
*
* Effect.runSync(program) // => "number"
* ```
*
* @stability stable
* @category constructors
* @since 4.0.0
*/
export const withFiberSucceed: (
evaluate: (fiber: Fiber) => A
) => Effect = core.withFiberSucceed
// -----------------------------------------------------------------------------
// Conversions
// -----------------------------------------------------------------------------
/**
* Converts a `Result` to an `Effect`.
*
* **Example** (Converting a Result into an Effect)
*
* ```ts import.meta.vitest
* import { Effect, Result } from "effect"
* const output: Array = []
*
* const success = Result.succeed(42)
* const failure = Result.fail("Something went wrong")
*
* const effect1 = Effect.fromResult(success)
* const effect2 = Effect.fromResult(failure)
*
* void output.push(Effect.runSync(effect1))
* void output.push(Effect.runSync(Effect.flip(effect2)))
* output // => [42, "Something went wrong"]
* ```
*
* @stability stable
* @category converting
* @since 4.0.0
*/
export const fromResult: (result: Result.Result) => Effect = internal.fromResult
/**
* Converts an `Option` into an `Effect`.
*
* **When to use**
*
* Use when absence should become a typed `NoSuchElementError` in the effect error
* channel.
*
* **Details**
*
* `Option.some` becomes a successful effect with the contained value, while
* `Option.none` becomes a failed effect. By default the failure is a
* `NoSuchElementError`, but you can provide an `onNone` callback to customize
* the error value. For `Option.none`, `onNone` is evaluated on each execution,
* not when the effect is constructed. It is never called for `Option.some`.
* If `onNone` throws, the effect dies with the thrown value as a defect.
*
* **Example** (Converting an Option into an Effect)
*
* ```ts import.meta.vitest
* import { Effect, Option } from "effect"
* const output: Array