Timing Out

Timeout operators race an Effect against a duration. If the timeout wins, the source Effect is interrupted before the timeout outcome is produced.

timeout

Effect.timeout represents a timeout as a typed Cause.TimeoutError.

Example (Failing with TimeoutError)

1
import { Effect } from "effect"
2

3
const program = Effect.never.pipe(Effect.timeout(0))
4
const error = await Effect.runPromise(Effect.flip(program))
5

6
error._tag // => "TimeoutError"

If the source fails before the timeout, its original error is preserved. If it succeeds in time, its success value is returned unchanged.

1
import { Effect } from "effect"
2

3
const program = Effect.succeed("result").pipe(Effect.timeout("1 second"))
4

5
Effect.runSync(program) // => "result"

timeoutOption

Effect.timeoutOption represents only the timeout case as Option.none(). A timely success becomes Option.some(value), while a typed failure from the source remains in the error channel.

Example (Returning None on Timeout)

1
import { Effect, Option } from "effect"
2

3
const timedOut = await Effect.runPromise(
4
  Effect.never.pipe(Effect.timeoutOption(0)),
5
)
6

7
timedOut // => Option.none()
8

9
const completed = Effect.runSync(
10
  Effect.succeed("result").pipe(Effect.timeoutOption("1 second")),
11
)
12

13
completed // => Option.some("result")

Use this operator only when a timeout genuinely means absence. It does not discard ordinary failures from the source Effect.

timeoutOrElse

Effect.timeoutOrElse switches to a lazily constructed fallback Effect when the timeout wins. The fallback may introduce its own success, error, and requirement types.

Example (Using Cached Data on Timeout)

1
import { Effect } from "effect"
2

3
const program = Effect.never.pipe(
4
  Effect.timeoutOrElse({
5
    duration: 0,
6
    orElse: () => Effect.succeed("cached result"),
7
  }),
8
)
9

10
await Effect.runPromise(program) // => "cached result"

Producing a Custom Error

Return Effect.fail from the fallback when the timeout should use a domain-specific error.

1
import { Data, Effect, Exit } from "effect"
2

3
class RequestTimeout extends Data.TaggedError("RequestTimeout")<{
4
  readonly endpoint: string
5
}> {}
6

7
const program = Effect.never.pipe(
8
  Effect.timeoutOrElse({
9
    duration: 0,
10
    orElse: () => Effect.fail(new RequestTimeout({ endpoint: "/users" })),
11
  }),
12
)
13

14
await Effect.runPromiseExit(program) // => Exit.fail(new RequestTimeout({ endpoint: "/users" }))

Returning Effect.die or Effect.failCause(Cause.die(...)) from the fallback instead makes the timeout a defect. This should be reserved for situations where timing out violates an invariant.

Interruption and Uninterruptible Work

The timeout fiber interrupts the source when the duration expires. Most Effects respond immediately. An uninterruptible region defers that interruption until it becomes interruptible again, so the caller may wait longer than the configured duration.

If work is intentionally allowed to outlive the caller, model that lifecycle explicitly by forking it into an appropriately supervised or detached fiber. Do not use detachment merely to make a timeout return early: detached work continues consuming resources after the caller has moved on.