Interface IOType<R, E, A>

IO<R, E, A> represents a lazy, composable effect.

interface IOType<R extends Type, E extends Type, A extends Type> {
 "[iterator]"(): Generator<IOType<R, E, A>, A, A>;
 catchAll<R2 extends unknown, E2 extends unknown, B extends unknown>(
 handler: (e: E) => IOType<R2, E2, B>,
 ): IOType<R | R2, E2, A | B>;
 catchTag<
 K extends string,
 R2 extends unknown,
 E2 extends unknown,
 B extends unknown,
 >(
 tag: K,
 handler: (e: Extract<E, { _tag: K }>) => IOType<R2, E2, B>,
 ): IOType<R | R2, E2 | Exclude<E, { _tag: K }>, A | B>;
 delay(ms: number): IOType<R, E, A>;
 flatMap<R2 extends unknown, E2 extends unknown, B extends unknown>(
 f: (a: A) => IOType<R2, E2, B>,
 ): IOType<R | R2, E | E2, B>;
 flatten<R2 extends unknown, E2 extends unknown, B extends unknown>(
 this: IOType<R, E, IOType<R2, E2, B>>,
 ): IOType<R | R2, E | E2, B>;
 fold(
 onFailure: (e: E) => B,
 onSuccess: (a: A) => B,
 ): IOType<R, never, B>;
 map(f: (a: A) => B): IOType<R, E, B>;
 mapError<E2 extends unknown>(f: (e: E) => E2): IOType<R, E2, A>;
 match(
 patterns: { failure: (e: E) => B; success: (a: A) => B },
 ): IOType<R, never, B>;
 pipe(f: (self: IOType<R, E, A>) => B): B;
 provideContext<R2 extends unknown>(
 context: ContextType<R2>,
 ): IOType<Exclude<R, R2>, E, A>;
 provideLayer<RIn extends unknown, E2 extends unknown, ROut extends unknown>(
 layer: LayerType<RIn, E2, ROut>,
 ): IOType<RIn | Exclude<R, ROut>, E | E2, A>;
 provideService<S extends unknown>(
 tag: TagType<S>,
 service: S,
 ): IOType<Exclude<R, S>, E, A>;
 recover(fallback: B): IOType<R, never, A | B>;
 recoverWith<R2 extends unknown, E2 extends unknown, B extends unknown>(
 f: (e: E) => IOType<R2, E2, B>,
 ): IOType<R | R2, E2, A | B>;
 retry(n: number): IOType<R, E, A>;
 retryWithDelay(n: number, delayMs: number): IOType<R, E, A>;
 run(this: IOType<never, E, A>): Promise<Either<E, A>>;
 runExit(this: IOType<never, E, A>): Promise<ExitType<E, A>>;
 runOption(this: IOType<never, E, A>): Promise<Option<A>>;
 runOrThrow(this: IOType<never, E, A>): Promise<A>;
 runSync(this: IOType<never, E, A>): Either<E, A>;
 runSyncOrThrow(this: IOType<never, E, A>): A;
 runTry(this: IOType<never, E, A>): Promise<Try<A>>;
 tap(f: (a: A) => void): IOType<R, E, A>;
 tapEffect<R2 extends unknown, E2 extends unknown, B extends unknown>(
 f: (a: A) => IOType<R2, E2, B>,
 ): IOType<R | R2, E | E2, A>;
 tapError(f: (e: E) => void): IOType<R, E, A>;
 timeout(ms: number): IOType<R, E | TimeoutError, A>;
 timeoutTo(ms: number, fallback: B): IOType<R, E, A | B>;
 toJSON(): { _tag: string; effect: unknown };
 toString(): string;
 zip<R2 extends unknown, E2 extends unknown, B extends unknown>(
 that: IOType<R2, E2, B>,
 ): IOType<R | R2, E | E2, readonly [A, B]>;
 zipLeft<R2 extends unknown, E2 extends unknown, B extends unknown>(
 that: IOType<R2, E2, B>,
 ): IOType<R | R2, E | E2, A>;
 zipRight<R2 extends unknown, E2 extends unknown, B extends unknown>(
 that: IOType<R2, E2, B>,
 ): IOType<R | R2, E | E2, B>;
}

Type Parameters

R extends Type
Requirements (environment/dependencies needed to run)
E extends Type
Error type (typed failures)
A extends Type
Success type (value produced on success)

Methods

[iterator]

"[iterator]"(): Generator<IOType<R, E, A>, A, A>
Makes IO iterable for generator do-notation (yield* syntax). Yields the IO itself, allowing IO.gen to extract the value.

Returns Generator<IOType<R, E, A>, A, A>

catchAll

catchAll<R2 extends unknown, E2 extends unknown, B extends unknown>(
handler: (e: E) => IOType<R2, E2, B>,
): IOType<R | R2, E2, A | B>
Catches all errors (alias for recoverWith).
Type Parameters
- R2 extends unknown
- E2 extends unknown
- B extends unknown
Parameters
- handler: (e: E) => IOType<R2, E2, B>
Returns IOType<R | R2, E2, A | B>

catchTag

catchTag<
 K extends string,
 R2 extends unknown,
 E2 extends unknown,
 B extends unknown,
>(
 tag: K,
 handler: (e: Extract<E, { _tag: K }>) => IOType<R2, E2, B>,
): IOType<R | R2, E2 | Exclude<E, { _tag: K }>, A | B>
Catches errors with a specific tag and handles them.
Type Parameters
- K extends string
- R2 extends unknown
- E2 extends unknown
- B extends unknown
Parameters
- tag: K
 The error tag to catch
- handler: (e: Extract<E, { _tag: K }>) => IOType<R2, E2, B>
 Handler for the caught error
Returns IOType<R | R2, E2 | Exclude<E, { _tag: K }>, A | B>

delay

delay(ms: number): IOType<R, E, A>
Delays execution by the specified milliseconds.
Parameters
- ms: number
Returns IOType<R, E, A>

flatMap

flatMap<R2 extends unknown, E2 extends unknown, B extends unknown>(
f: (a: A) => IOType<R2, E2, B>,
): IOType<R | R2, E | E2, B>
Chains another IO effect based on the success value.
Type Parameters
- R2 extends unknown
- E2 extends unknown
- B extends unknown
Parameters
- f: (a: A) => IOType<R2, E2, B>
 Function returning next IO effect
Returns IOType<R | R2, E | E2, B>
New IO with combined effects

flatten

flatten<R2 extends unknown, E2 extends unknown, B extends unknown>(
this: IOType<R, E, IOType<R2, E2, B>>,
): IOType<R | R2, E | E2, B>
Flattens a nested IO.
Type Parameters
- R2 extends unknown
- E2 extends unknown
- B extends unknown
Parameters
- this: IOType<R, E, IOType<R2, E2, B>>
Returns IOType<R | R2, E | E2, B>

fold

fold(
onFailure: (e: E) => B,
onSuccess: (a: A) => B,
): IOType<R, never, B>
Pattern matches on success and failure.
Type Parameters
- B extends unknown
Parameters
- onFailure: (e: E) => B
 Handler for failures
- onSuccess: (a: A) => B
 Handler for successes
Returns IOType<R, never, B>
New IO with handled result

map

map(f: (a: A) => B): IOType<R, E, B>
Transforms the success value.
Type Parameters
- B extends unknown
Parameters
- f: (a: A) => B
 Function to apply to the success value
Returns IOType<R, E, B>
New IO with transformed value

mapError

mapError<E2 extends unknown>(f: (e: E) => E2): IOType<R, E2, A>
Transforms the error value.
Type Parameters
- E2 extends unknown
Parameters
- f: (e: E) => E2
 Function to apply to the error
Returns IOType<R, E2, A>
New IO with transformed error

match

match(
patterns: { failure: (e: E) => B; success: (a: A) => B },
): IOType<R, never, B>
Pattern matches with object pattern syntax.
Type Parameters
- B extends unknown
Parameters
- patterns: { failure: (e: E) => B; success: (a: A) => B }
Returns IOType<R, never, B>

pipe

pipe(f: (self: IOType<R, E, A>) => B): B
Pipes the IO through a function.
Type Parameters
- B
Parameters
- f: (self: IOType<R, E, A>) => B
Returns B

provideContext

provideContext<R2 extends unknown>(
context: ContextType<R2>,
): IOType<Exclude<R, R2>, E, A>
Provides a context to satisfy the requirements of this effect.
Type Parameters
- R2 extends unknown
Parameters
- context: ContextType<R2>
 The context containing required services
Returns IOType<Exclude<R, R2>, E, A>

provideLayer

provideLayer<RIn extends unknown, E2 extends unknown, ROut extends unknown>(
layer: LayerType<RIn, E2, ROut>,
): IOType<RIn | Exclude<R, ROut>, E | E2, A>
Provides services using a layer.
Type Parameters
- RIn extends unknown
- E2 extends unknown
- ROut extends unknown
Parameters
- layer: LayerType<RIn, E2, ROut>
 The layer that provides services
Returns IOType<RIn | Exclude<R, ROut>, E | E2, A>

provideService

provideService<S extends unknown>(
tag: TagType<S>,
service: S,
): IOType<Exclude<R, S>, E, A>
Provides a single service to satisfy part of the requirements.
Type Parameters
- S extends unknown
Parameters
- tag: TagType<S>
 The service tag
- service: S
 The service implementation
Returns IOType<Exclude<R, S>, E, A>

recover

recover(fallback: B): IOType<R, never, A | B>
Recovers from any error with a fallback value.
Type Parameters
- B extends unknown
Parameters
- fallback: B
 Value to use on error
Returns IOType<R, never, A | B>
New IO that never fails

recoverWith

recoverWith<R2 extends unknown, E2 extends unknown, B extends unknown>(
f: (e: E) => IOType<R2, E2, B>,
): IOType<R | R2, E2, A | B>
Recovers from error by running another effect.
Type Parameters
- R2 extends unknown
- E2 extends unknown
- B extends unknown
Parameters
- f: (e: E) => IOType<R2, E2, B>
 Function returning recovery effect
Returns IOType<R | R2, E2, A | B>
New IO with error handling

retry

retry(n: number): IOType<R, E, A>
Retries the effect up to n times on failure.
Parameters
- n: number
 Maximum number of retries
Returns IOType<R, E, A>

retryWithDelay

retryWithDelay(n: number, delayMs: number): IOType<R, E, A>
Retries the effect with a delay between attempts.
Parameters
- n: number
 Maximum number of retries
- delayMs: number
 Delay between retries in milliseconds
Returns IOType<R, E, A>

run

run(this: IOType<never, E, A>): Promise<Either<E, A>>
Runs the effect and returns an Either. Never throws. This is the safe default - all errors become Left. Requires R = never.
Parameters
- this: IOType<never, E, A>
Returns Promise<Either<E, A>>

runExit

runExit(this: IOType<never, E, A>): Promise<ExitType<E, A>>
Runs the effect and returns an Exit.
Parameters
- this: IOType<never, E, A>
Returns Promise<ExitType<E, A>>

runOption

runOption(this: IOType<never, E, A>): Promise<Option<A>>
Runs the effect and returns an Option. Some(value) on success, None on failure.
Parameters
- this: IOType<never, E, A>
Returns Promise<Option<A>>

runOrThrow

runOrThrow(this: IOType<never, E, A>): Promise<A>
Runs the effect and returns a Promise of the value. Throws on any error (typed E, defect, or interrupt). Requires R = never.
Parameters
- this: IOType<never, E, A>
Returns Promise<A>

runSync

runSync(this: IOType<never, E, A>): Either<E, A>
Runs a sync effect and returns an Either. Never throws. This is the safe default - all errors become Left. Throws only if the effect is async (cannot be made safe synchronously). Requires R = never.
Parameters
- this: IOType<never, E, A>
Returns Either<E, A>

runSyncOrThrow

runSyncOrThrow(this: IOType<never, E, A>): A
Runs a sync effect and returns the value. Throws on any error or if the effect is async. Requires R = never.
Parameters
- this: IOType<never, E, A>
Returns A

runTry

runTry(this: IOType<never, E, A>): Promise<Try<A>>
Runs the effect and returns a Try. Success(value) on success, Failure(error) on failure.
Parameters
- this: IOType<never, E, A>
Returns Promise<Try<A>>

tap

tap(f: (a: A) => void): IOType<R, E, A>
Applies a side effect without changing the value.
Parameters
- f: (a: A) => void
 Side effect function
Returns IOType<R, E, A>
Same IO for chaining

tapEffect

tapEffect<R2 extends unknown, E2 extends unknown, B extends unknown>(
f: (a: A) => IOType<R2, E2, B>,
): IOType<R | R2, E | E2, A>
Applies an effectful side effect without changing the value.
Type Parameters
- R2 extends unknown
- E2 extends unknown
- B extends unknown
Parameters
- f: (a: A) => IOType<R2, E2, B>
 Function returning IO for side effect
Returns IOType<R | R2, E | E2, A>
Same value after running side effect

tapError

tapError(f: (e: E) => void): IOType<R, E, A>
Executes a side effect on the error without changing it. Useful for logging errors while preserving the error chain.
Parameters
- f: (e: E) => void
 Side effect function to run on error
Returns IOType<R, E, A>
Same IO with the side effect attached
Example
```
const io = IO.asyncResult(() => query(), toError)
 .tapError(err => console.error('Query failed:', err))
 .map(data => transform(data))
```

timeout

timeout(ms: number): IOType<R, E | TimeoutError, A>
Fails with TimeoutError if the effect doesn't complete within the specified duration.
Parameters
- ms: number
 Maximum time in milliseconds
Returns IOType<R, E | TimeoutError, A>

timeoutTo

timeoutTo(ms: number, fallback: B): IOType<R, E, A | B>
Returns a fallback value if the effect doesn't complete within the specified duration.
Type Parameters
- B extends unknown
Parameters
- ms: number
 Maximum time in milliseconds
- fallback: B
 Value to return on timeout
Returns IOType<R, E, A | B>

toJSON

toJSON(): { _tag: string; effect: unknown }
Converts to JSON representation.

Returns { _tag: string; effect: unknown }

toString

toString(): string
Converts to string representation.

Returns string

zip

zip<R2 extends unknown, E2 extends unknown, B extends unknown>(
that: IOType<R2, E2, B>,
): IOType<R | R2, E | E2, readonly [A, B]>
Zips two IOs into a tuple.
Type Parameters
- R2 extends unknown
- E2 extends unknown
- B extends unknown
Parameters
- that: IOType<R2, E2, B>
Returns IOType<R | R2, E | E2, readonly [A, B]>

zipLeft

zipLeft<R2 extends unknown, E2 extends unknown, B extends unknown>(
that: IOType<R2, E2, B>,
): IOType<R | R2, E | E2, A>
Sequences two IOs, keeping the first value.
Type Parameters
- R2 extends unknown
- E2 extends unknown
- B extends unknown
Parameters
- that: IOType<R2, E2, B>
Returns IOType<R | R2, E | E2, A>

zipRight

zipRight<R2 extends unknown, E2 extends unknown, B extends unknown>(
that: IOType<R2, E2, B>,
): IOType<R | R2, E | E2, B>
Sequences two IOs, keeping the second value.
Type Parameters
- R2 extends unknown
- E2 extends unknown
- B extends unknown
Parameters
- that: IOType<R2, E2, B>
Returns IOType<R | R2, E | E2, B>

Interface IOType<R, E, A>

Type Parameters

Index

Methods

Methods

[iterator]

Returns Generator<IOType<R, E, A>, A, A>

catchAll

Type Parameters

Parameters

Returns IOType<R | R2, E2, A | B>

catchTag

Type Parameters

Parameters

Returns IOType<R | R2, E2 | Exclude<E, { _tag: K }>, A | B>

delay

Parameters

Returns IOType<R, E, A>

flatMap

Type Parameters

Parameters

Returns IOType<R | R2, E | E2, B>

flatten

Type Parameters

Parameters

Returns IOType<R | R2, E | E2, B>

fold

Type Parameters

Parameters

Returns IOType<R, never, B>

map

Type Parameters

Parameters

Returns IOType<R, E, B>

mapError

Type Parameters

Parameters

Returns IOType<R, E2, A>

match

Type Parameters

Parameters

Returns IOType<R, never, B>

pipe

Type Parameters

Parameters

Returns B

provideContext

Type Parameters

Parameters

Returns IOType<Exclude<R, R2>, E, A>

provideLayer

Type Parameters

Parameters

Returns IOType<RIn | Exclude<R, ROut>, E | E2, A>

provideService

Type Parameters

Parameters

Returns IOType<Exclude<R, S>, E, A>

recover

Type Parameters

Parameters

Returns IOType<R, never, A | B>

recoverWith

Type Parameters

Parameters

Returns IOType<R | R2, E2, A | B>

retry

Parameters

Returns IOType<R, E, A>

retryWithDelay

Parameters

Returns IOType<R, E, A>

run

Parameters

Returns Promise<Either<E, A>>

runExit

Parameters

Returns Promise<ExitType<E, A>>

runOption

Parameters