TxDeferred.ts

TxDeferred.ts overview

Transactional deferred values for coordinating Effect transactions.

A TxDeferred<A, E> is a write-once cell whose completion is a Result<A, E> stored in transactional state. Readers can wait for the value from inside a transaction: while the cell is empty the transaction retries, and when another transaction completes the deferred the waiting transaction can resume with either the success value or the typed failure.

Since v4.0.0

constructors

make

Creates a new empty TxDeferred.

When to use

Use to create a transactional deferred that can be completed exactly once.

Example (Creating a transactional deferred)

import { Effect, Option, TxDeferred } from "effect"

const program = Effect.gen(function* () {
  const deferred = yield* TxDeferred.make<string, Error>()
  const state = yield* TxDeferred.poll(deferred)
  console.log(Option.isNone(state)) // true
})

Signature

declare const make: <A, E = never>() => Effect.Effect<TxDeferred<A, E>>

Source

Since v2.0.0

getters

await

Reads the deferred value. Retries the transaction if the deferred has not been completed yet.

When to use

Use to read the success value of a TxDeferred while retrying until the deferred is completed.

See

poll for inspecting the current completion state without retrying the transaction

Signature

declare const await: <A, E>(self: TxDeferred<A, E>) => Effect.Effect<A, E>

Source

Since v4.0.0

poll

Reads the current state of the deferred without retrying. Returns None if not yet completed.

When to use

Use to inspect a TxDeferred without retrying when it is not completed yet.

Example (Polling a deferred)

import { Effect, Option, Result, TxDeferred } from "effect"

const program = Effect.gen(function* () {
  const deferred = yield* TxDeferred.make<number>()
  const before = yield* TxDeferred.poll(deferred)
  console.log(Option.isNone(before)) // true

  yield* TxDeferred.succeed(deferred, 42)
  const after = yield* TxDeferred.poll(deferred)
  console.log(after) // Some(Success(42))
})

Signature

declare const poll: <A, E>(self: TxDeferred<A, E>) => Effect.Effect<Option<Result<A, E>>>

Source

Since v2.0.0

guards

isTxDeferred

Determines if the provided value is a TxDeferred.

When to use

Use to narrow an unknown value before treating it as a transactional deferred.

Example (Checking transactional deferreds)

import { Effect, TxDeferred } from "effect"

const program = Effect.gen(function* () {
  const deferred = yield* TxDeferred.make<number>()
  console.log(TxDeferred.isTxDeferred(deferred)) // true
  console.log(TxDeferred.isTxDeferred("not a deferred")) // false
})

Signature

declare const isTxDeferred: (u: unknown) => u is TxDeferred<unknown, unknown>

Source

Since v4.0.0

models

TxDeferred (interface)

A transactional deferred is a write-once cell readable within transactions. Readers block (retry the transaction) until a value is committed, and writers succeed only on the first call; subsequent writes return false.

When to use

Use to coordinate transaction-local readers and one-time completion with a success or failure result.

Example (Completing a transactional deferred)

import { Effect, TxDeferred } from "effect"

const program = Effect.gen(function* () {
  const deferred = yield* TxDeferred.make<number>()

  // Complete the deferred
  const first = yield* TxDeferred.succeed(deferred, 42)
  console.log(first) // true

  // Second write is a no-op
  const second = yield* TxDeferred.succeed(deferred, 99)
  console.log(second) // false

  // Read the value
  const value = yield* TxDeferred.await(deferred)
  console.log(value) // 42
})

Signature

export interface TxDeferred<in out A, in out E = never> extends Inspectable, Pipeable {
  readonly [TypeId]: typeof TypeId
  readonly ref: TxRef.TxRef<Option<Result<A, E>>>
}

Source

Since v4.0.0

mutations

done

Completes the deferred with a Result. Returns true if this was the first completion, false if already completed.

When to use

Use to complete a TxDeferred with an already computed Result.

Example (Completing with a result)

import { Effect, Result, TxDeferred } from "effect"

const program = Effect.gen(function* () {
  const deferred = yield* TxDeferred.make<number, string>()
  const first = yield* TxDeferred.done(deferred, Result.succeed(42))
  console.log(first) // true
  const second = yield* TxDeferred.done(deferred, Result.succeed(99))
  console.log(second) // false
})

Signature

declare const done: {
  <A, E>(result: Result<A, E>): (self: TxDeferred<A, E>) => Effect.Effect<boolean>
  <A, E>(self: TxDeferred<A, E>, result: Result<A, E>): Effect.Effect<boolean>
}

Source

Since v2.0.0

fail

Completes the deferred with a failure. Returns true if this was the first completion, false if already completed.

When to use

Use to complete a TxDeferred with a typed failure value.

Example (Completing with a failure)

import { Effect, TxDeferred } from "effect"

const program = Effect.gen(function* () {
  const deferred = yield* TxDeferred.make<number, string>()
  const first = yield* TxDeferred.fail(deferred, "boom")
  console.log(first) // true
  const second = yield* TxDeferred.fail(deferred, "boom2")
  console.log(second) // false
})

Signature

declare const fail: {
  <E>(error: E): <A>(self: TxDeferred<A, E>) => Effect.Effect<boolean>
  <A, E>(self: TxDeferred<A, E>, error: E): Effect.Effect<boolean>
}

Source

Since v2.0.0

succeed

Completes the deferred with a success value. Returns true if this was the first completion, false if already completed.

When to use

Use to complete a TxDeferred with a successful value.

Example (Completing with a success value)

import { Effect, TxDeferred } from "effect"

const program = Effect.gen(function* () {
  const deferred = yield* TxDeferred.make<number>()
  const first = yield* TxDeferred.succeed(deferred, 42)
  console.log(first) // true
  const second = yield* TxDeferred.succeed(deferred, 99)
  console.log(second) // false
})

Signature

declare const succeed: {
  <A>(value: A): <E>(self: TxDeferred<A, E>) => Effect.Effect<boolean>
  <A, E>(self: TxDeferred<A, E>, value: A): Effect.Effect<boolean>
}

Source

Since v2.0.0