FuncType - v1.21.0
    Preparing search index...

    Interface IO<R, E, A>

    interface IO<in out R extends Type, out E extends Type, out A extends Type> {
        "[toStringTag]": string;
        "[iterator]"(): Generator<IO<R, E, A>, A, unknown>;
        catchAll<R2 extends unknown, E2 extends unknown, B extends unknown>(
            handler: (e: E) => IO<R2, E2, B>,
        ): IO<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 }>) => IO<R2, E2, B>,
        ): IO<R | R2, E2 | Exclude<E, { _tag: K }>, A | B>;
        delay(ms: number): IO<R, E, A>;
        flatMap<R2 extends unknown, E2 extends unknown, B extends unknown>(
            f: (a: A) => IO<R2, E2, B>,
        ): IO<R | R2, E | E2, B>;
        flatten<R2 extends unknown, E2 extends unknown, B extends unknown>(
            this: IO<R, E, IO<R2, E2, B>>,
        ): IO<R | R2, E | E2, B>;
        fold<B extends unknown>(
            onFailure: (e: E) => B,
            onSuccess: (a: A) => B,
        ): IO<R, never, B>;
        interruptOn(signal: AbortSignal): IO<R, E | InterruptedError, A>;
        map<B extends unknown>(f: (a: A) => B): IO<R, E, B>;
        mapError<E2 extends unknown>(f: (e: E) => E2): IO<R, E2, A>;
        match<B extends unknown>(
            patterns: { failure: (e: E) => B; success: (a: A) => B },
        ): IO<R, never, B>;
        pipe<B>(f: (self: IO<R, E, A>) => B): B;
        provideContext<R2 extends unknown>(
            context: Context<R2>,
        ): IO<Exclude<R, R2>, E, A>;
        provideLayer<RIn extends unknown, E2 extends unknown, ROut extends unknown>(
            layer: Layer<RIn, E2, ROut>,
        ): IO<RIn | Exclude<R, ROut>, E | E2, A>;
        provideService<S extends unknown>(
            tag: Tag<S>,
            service: S,
        ): IO<Exclude<R, S>, E, A>;
        recover<B extends unknown>(fallback: B): IO<R, never, A | B>;
        recoverWith<R2 extends unknown, E2 extends unknown, B extends unknown>(
            f: (e: E) => IO<R2, E2, B>,
        ): IO<R | R2, E2, A | B>;
        repeatUntil(
            done: (a: A) => boolean,
            opts: { delayMs?: number; max: number },
        ): IO<R, E | RepeatExhausted<A>, A>;
        repeatWhile(
            cont: (a: A) => boolean,
            opts: { delayMs?: number; max: number },
        ): IO<R, E | RepeatExhausted<A>, A>;
        retry(n: number): IO<R, E, A>;
        retryWhile(
            opts: {
                delayMs?: number;
                n: number;
                while: (error: E, attempt: number) => boolean;
            },
        ): IO<R, E, A>;
        retryWithBackoff(
            opts: {
                baseMs: number;
                factor?: number;
                jitter?: boolean;
                maxMs?: number;
                n: number;
                while?: (error: E, attempt: number) => boolean;
            },
        ): IO<R, E, A>;
        retryWithDelay(n: number, delayMs: number): IO<R, E, A>;
        run(this: IO<never, E, A>): Promise<Either<E, A>>;
        runCancellable(
            this: IO<never, E, A>,
        ): { cancel: () => void; result: Promise<Either<E | InterruptedError, A>> };
        runExit(
            this: IO<never, E, A>,
            options?: { signal?: AbortSignal },
        ): Promise<Exit<E, A>>;
        runOption(this: IO<never, E, A>): Promise<Option<A>>;
        runOrThrow(this: IO<never, E, A>): Promise<A>;
        runSync(this: IO<never, E, A>): Either<E, A>;
        runSyncOrThrow(this: IO<never, E, A>): A;
        runTry(this: IO<never, E, A>): Promise<Try<A>>;
        tap(f: (a: A) => void): IO<R, E, A>;
        tapEffect<R2 extends unknown, E2 extends unknown, B extends unknown>(
            f: (a: A) => IO<R2, E2, B>,
        ): IO<R | R2, E | E2, A>;
        tapError(f: (e: E) => void): IO<R, E, A>;
        timeout(ms: number): IO<R, E | TimeoutError, A>;
        timeoutTo<B extends unknown>(ms: number, fallback: B): IO<R, E, A | B>;
        toJSON(): { _tag: string; effect: unknown };
        toString(): string;
        zip<R2 extends unknown, E2 extends unknown, B extends unknown>(
            that: IO<R2, E2, B>,
        ): IO<R | R2, E | E2, readonly [A, B]>;
        zipLeft<R2 extends unknown, E2 extends unknown, B extends unknown>(
            that: IO<R2, E2, B>,
        ): IO<R | R2, E | E2, A>;
        zipRight<R2 extends unknown, E2 extends unknown, B extends unknown>(
            that: IO<R2, E2, B>,
        ): IO<R | R2, E | E2, B>;
    }

    Type Parameters

    • in out R extends Type
    • out E extends Type
    • out A extends Type
    Index
    "[toStringTag]": string
    • Makes IO iterable for generator do-notation (yield* syntax). Yields the IO itself, allowing IO.gen to extract the value.

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

    • Catches all errors (alias for recoverWith).

      Type Parameters

      • R2 extends unknown
      • E2 extends unknown
      • B extends unknown

      Parameters

      Returns IO<R | R2, E2, 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 }>) => IO<R2, E2, B>

        Handler for the caught error

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

    • Delays execution by the specified milliseconds.

      Parameters

      • ms: number

      Returns IO<R, E, A>

    • Chains another IO effect based on the success value.

      Type Parameters

      • R2 extends unknown
      • E2 extends unknown
      • B extends unknown

      Parameters

      • f: (a: A) => IO<R2, E2, B>

        Function returning next IO effect

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

      New IO with combined effects

    • Flattens a nested IO.

      Type Parameters

      • R2 extends unknown
      • E2 extends unknown
      • B extends unknown

      Parameters

      Returns IO<R | R2, E | E2, 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 IO<R, never, B>

      New IO with handled result

    • Makes this effect cancellable by an AbortSignal, such as the one React Query or a request handler provides.

      Once the signal aborts, no further step starts. The effect stops at the next step boundary (between flatMaps, retries, repeat iterations and IO.gen yields), and no map, recover or other callback inside it runs after that. The result is a failure with InterruptedError, which catchTag("InterruptedError", …) can handle outside this call. Inside it, retry, recover and catchAll cannot swallow the cancellation.

      • bracket / acquireRelease cleanup still runs, to completion: acquire and release are not interruptible.
      • A promise already in flight can't be stopped (JavaScript has no way to). The cancellation is seen at the next step after it settles, so if that promise was the effect's last step, the effect succeeds with its result. IO.never() under interruptOn never resolves for the same reason. IO.async and IO.tryPromise thunks receive the region's signal as their argument, so IO.async((signal) => fetch(url, { signal })) aborts the request itself; its rejection is reported as the cancellation. IO(() => …) thunks get no signal. IO.sleep is not woken early.
      • A defect (a bug) that happens after the abort is still reported as a defect.
      • runSync only sees a signal that was already aborted when this effect starts.
      • When E is unknown (effects from IO.async or IO(...)), the union collapses to unknown; use InterruptedError.is(e) to recognise the cancellation.

      Parameters

      • signal: AbortSignal

      Returns IO<R, E | InterruptedError, A>

      const poll = checkStatus.repeatUntil((s) => s.done, { max: 60, delayMs: 500 })
      const result = await poll.interruptOn(signal).run()
      // Left(InterruptedError) if the signal aborts first, and polling has stopped
    • Transforms the success value.

      Type Parameters

      • B extends unknown

      Parameters

      • f: (a: A) => B

        Function to apply to the success value

      Returns IO<R, E, B>

      New IO with transformed value

    • Transforms the error value.

      Type Parameters

      • E2 extends unknown

      Parameters

      • f: (e: E) => E2

        Function to apply to the error

      Returns IO<R, E2, A>

      New IO with transformed error

    • Pattern matches with object pattern syntax.

      Type Parameters

      • B extends unknown

      Parameters

      • patterns: { failure: (e: E) => B; success: (a: A) => B }

      Returns IO<R, never, B>

    • Pipes the IO through a function.

      Type Parameters

      • B

      Parameters

      Returns B

    • Provides a context to satisfy the requirements of this effect.

      Type Parameters

      • R2 extends unknown

      Parameters

      • context: Context<R2>

        The context containing required services

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

    • Provides services using a layer.

      Type Parameters

      • RIn extends unknown
      • E2 extends unknown
      • ROut extends unknown

      Parameters

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

    • Provides a single service to satisfy part of the requirements.

      Type Parameters

      • S extends unknown

      Parameters

      • tag: Tag<S>

        The service tag

      • service: S

        The service implementation

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

    • Recovers from any error with a fallback value.

      Type Parameters

      • B extends unknown

      Parameters

      • fallback: B

        Value to use on error

      Returns IO<R, never, A | B>

      New IO that never fails

    • Recovers from error by running another effect.

      Type Parameters

      • R2 extends unknown
      • E2 extends unknown
      • B extends unknown

      Parameters

      • f: (e: E) => IO<R2, E2, B>

        Function returning recovery effect

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

      New IO with error handling

    • 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 IO<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.

      pollJob
      .retry(3) // error axis
      .repeatUntil((job) => job.done, { max: 20, delayMs: 500 }) // value axis
    • 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 IO<R, E | RepeatExhausted<A>, A>

    • Retries the effect up to n times on failure.

      Parameters

      • n: number

        Maximum number of retries

      Returns IO<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 IO<R, E, A>

      Http.get("/api/users", { decode })
      .retryWhile({
      n: 3,
      while: (e) => e._tag === "HttpStatusError" && e.status >= 500,
      delayMs: 250,
      })
    • 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 IO<R, E, A>

      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)
    • Retries the effect with a delay between attempts.

      Parameters

      • n: number

        Maximum number of retries

      • delayMs: number

        Delay between retries in milliseconds

      Returns IO<R, 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: IO<never, E, A>

      Returns Promise<Either<E, A>>

    • Starts the effect and returns a handle that cancels it, with IO.interruptOn semantics: after cancel(), no further step runs and result resolves to Left(InterruptedError). Calling cancel() after the effect finished does nothing. Requires R = never.

      Parameters

      • this: IO<never, E, A>

      Returns { cancel: () => void; result: Promise<Either<E | InterruptedError, A>> }

      const { result, cancel } = loadReport.runCancellable()
      onUnmount(cancel)
      const report = await result
    • Runs the effect and returns an Exit.

      With options.signal, the run stops at the next step once the signal aborts and returns an Interrupted Exit, with the same rules as IO.interruptOn: no further step or callback runs, recovery can't swallow it, and cleanup completes. Unlike interruptOn, E is not widened: the cancellation is reported as Interrupted, not as a typed InterruptedError. This suits runners (React hooks, query adapters) that discard a cancelled result rather than handle it.

      Parameters

      • this: IO<never, E, A>
      • Optionaloptions: { signal?: AbortSignal }

      Returns Promise<Exit<E, A>>

    • Runs the effect and returns an Option. Some(value) on success, None on failure.

      Parameters

      • this: IO<never, E, A>

      Returns Promise<Option<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: IO<never, E, A>

      Returns Promise<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: IO<never, E, A>

      Returns Either<E, A>

    • Runs a sync effect and returns the value. Throws on any error or if the effect is async. Requires R = never.

      Parameters

      • this: IO<never, E, A>

      Returns A

    • Runs the effect and returns a Try. Success(value) on success, Failure(error) on failure.

      Parameters

      • this: IO<never, E, A>

      Returns Promise<Try<A>>

    • Applies a side effect without changing the value.

      Parameters

      • f: (a: A) => void

        Side effect function

      Returns IO<R, E, A>

      Same IO for chaining

    • Applies an effectful side effect without changing the value.

      Type Parameters

      • R2 extends unknown
      • E2 extends unknown
      • B extends unknown

      Parameters

      • f: (a: A) => IO<R2, E2, B>

        Function returning IO for side effect

      Returns IO<R | R2, E | E2, A>

      Same value after running side effect

    • 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 IO<R, E, A>

      Same IO with the side effect attached

      const io = IO.asyncResult(() => query(), toError)
      .tapError(err => console.error('Query failed:', err))
      .map(data => transform(data))
    • Fails with TimeoutError if the effect doesn't complete within the specified duration.

      Parameters

      • ms: number

        Maximum time in milliseconds

      Returns IO<R, E | TimeoutError, A>

    • 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 IO<R, E, A | B>

    • Converts to JSON representation.

      Returns { _tag: string; effect: unknown }

    • Converts to string representation.

      Returns string

    • Zips two IOs into a tuple.

      Type Parameters

      • R2 extends unknown
      • E2 extends unknown
      • B extends unknown

      Parameters

      Returns IO<R | R2, E | E2, readonly [A, B]>

    • Sequences two IOs, keeping the first value.

      Type Parameters

      • R2 extends unknown
      • E2 extends unknown
      • B extends unknown

      Parameters

      Returns IO<R | R2, E | E2, A>

    • Sequences two IOs, keeping the second value.

      Type Parameters

      • R2 extends unknown
      • E2 extends unknown
      • B extends unknown

      Parameters

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