Interface IOType<R, E, A>

interface IOType<in out R extends Type, out E extends Type, out A extends Type> {
 "[toStringTag]": string;
 "[iterator]"(): Generator<IOType<R, E, A>, A, unknown>;
 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>;
 repeatUntil(
 done: (a: A) => boolean,
 opts: { delayMs?: number; max: number },
 ): IOType<R, E | RepeatExhausted<A>, A>;
 repeatWhile(
 cont: (a: A) => boolean,
 opts: { delayMs?: number; max: number },
 ): IOType<R, E | RepeatExhausted<A>, A>;
 retry(n: number): IOType<R, E, A>;
 retryWhile(
 opts: {
 delayMs?: number;
 n: number;
 while: (error: E, attempt: number) => boolean;
 },
 ): IOType<R, E, A>;
 retryWithBackoff(
 opts: {
 baseMs: number;
 factor?: number;
 jitter?: boolean;
 maxMs?: number;
 n: number;
 while?: (error: E, attempt: number) => boolean;
 },
 ): 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

in out R extends Type
out E extends Type
out A extends Type

Properties

`Readonly`[toStringTag]

"[toStringTag]": string

Methods

[iterator]

"[iterator]"(): Generator<IOType<R, E, A>, A, unknown>

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, unknown>

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

repeatUntil

repeatUntil(
done: (a: A) => boolean,
opts: { delayMs?: number; max: number },
): IOType<R, E | RepeatExhausted<A>, A>
Re-runs the effect until its output satisfies done, or the max bound is hit.

Value-channel dual of retryWhile: this repeats on success values that haven't yet met the predicate, whereas the retry* family repeats on failure. The first failure short-circuits and propagates unchanged. Compose the two axes when both matter:
Parameters
- done: (a: A) => boolean
 Pure sync predicate. Loop stops (successfully) when this returns true.
- opts: { delayMs?: number; max: number }
 - Optional ReadonlydelayMs?: number
 
 Optional fixed delay between iterations.
 - Readonlymax: number
 
 Maximum iterations before exhaustion is signaled.
Returns IOType<R, E | RepeatExhausted<A>, A>
The satisfying value, or RepeatExhausted<A> in the error channel (carrying the last observed value) if the bound is reached first.
Example
```
pollJob
 .retry(3) // error axis
 .repeatUntil((job) => job.done, { max: 20, delayMs: 500 }) // value axis
```

repeatWhile

repeatWhile(
cont: (a: A) => boolean,
opts: { delayMs?: number; max: number },
): IOType<R, E | RepeatExhausted<A>, A>
Re-runs the effect while cont holds, or until the max bound is hit.

Symmetric sibling of repeatUntil — mirrors the naming of retryWhile. repeatWhile(cont) is equivalent to repeatUntil((a) => !cont(a)); the loop stops successfully as soon as cont returns false.
Parameters
- cont: (a: A) => boolean
 Pure sync predicate. Loop continues while this returns true.
- opts: { delayMs?: number; max: number }
 - Optional ReadonlydelayMs?: number
 
 Optional fixed delay between iterations.
 - Readonlymax: number
 
 Maximum iterations before exhaustion is signaled.
Returns IOType<R, E | RepeatExhausted<A>, A>

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>

retryWhile

retryWhile(
 opts: {
 delayMs?: number;
 n: number;
 while: (error: E, attempt: number) => boolean;
 },
): IOType<R, E, A>
Retries the effect only while a predicate over the error holds.

Useful for selective retry policies — e.g. retry HTTP 5xx but not 4xx, retry network errors but not validation errors. The predicate is evaluated BEFORE each retry; returning false short-circuits and re-fails with the original error.
Parameters
- opts: { delayMs?: number; n: number; while: (error: E, attempt: number) => boolean }
 - Optional ReadonlydelayMs?: number
 
 Optional fixed delay between attempts.
 - Readonlyn: number
 
 Maximum number of retry attempts.
 - Readonlywhile: (error: E, attempt: number) => boolean
 
 Predicate (error, attempt) => boolean (attempt is 1-indexed for the first retry; if the predicate returns false, the retry is skipped).
Returns IOType<R, E, A>
Example
```
Http.get("/api/users", { decode })
 .retryWhile({
 n: 3,
 while: (e) => e._tag === "HttpStatusError" && e.status >= 500,
 delayMs: 250,
 })
```

retryWithBackoff

retryWithBackoff(
 opts: {
 baseMs: number;
 factor?: number;
 jitter?: boolean;
 maxMs?: number;
 n: number;
 while?: (error: E, attempt: number) => boolean;
 },
): IOType<R, E, A>
Retries the effect with exponential backoff and optional full jitter.

Delay schedule: min(maxMs, baseMs * factor^(attempt-1)). With jitter enabled, the actual delay is computed * (0.5 + Math.random() * 0.5) (full jitter, 50–100% of the computed value) — prevents thundering herd.
Parameters
- opts: {
 baseMs: number;
 factor?: number;
 jitter?: boolean;
 maxMs?: number;
 n: number;
 while?: (error: E, attempt: number) => boolean;
 }
 - ReadonlybaseMs: number
 
 Initial delay before the first retry.
 - Optional Readonlyfactor?: number
 
 Backoff multiplier per attempt. Defaults to 2.
 - Optional Readonlyjitter?: boolean
 
 Apply full jitter (50–100% of computed delay). Defaults to true.
 - Optional ReadonlymaxMs?: number
 
 Cap on per-attempt delay. Defaults to 30_000.
 - Readonlyn: number
 
 Maximum number of retry attempts.
 - Optional Readonlywhile?: (error: E, attempt: number) => boolean
 
 Optional predicate (error, attempt) => boolean gating each retry.
Returns IOType<R, E, A>
Example
```
const isRetryable = (e: HttpError): boolean =>
 e._tag === "NetworkError" ||
 (e._tag === "HttpStatusError" && (e.status >= 500 || e.status === 429))

Http.get("/api/users", { decode })
 .retryWithBackoff({ n: 3, baseMs: 250, while: isRetryable })
 .timeout(10_000)
```

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

Properties

Methods

Properties

Readonly[toStringTag]

Methods

[iterator]

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

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>

repeatUntil

Parameters

Optional ReadonlydelayMs?: number

Readonlymax: number

Returns IOType<R, E | RepeatExhausted<A>, A>

Example

repeatWhile

Parameters

Optional ReadonlydelayMs?: number

Readonlymax: number

Returns IOType<R, E | RepeatExhausted<A>, A>

`Readonly`[toStringTag]

`Optional` `Readonly`delayMs?: number

`Readonly`max: number

`Optional` `Readonly`delayMs?: number

`Readonly`max: number

`Optional` `Readonly`delayMs?: number

`Readonly`n: number

`Readonly`while: (error: E, attempt: number) => boolean

`Readonly`baseMs: number

`Optional` `Readonly`factor?: number

`Optional` `Readonly`jitter?: boolean

`Optional` `Readonly`maxMs?: number

`Readonly`n: number

`Optional` `Readonly`while?: (error: E, attempt: number) => boolean