Skip to content
Effect Days 2026 Get your ticket

Random

14 exports Added in v2.0.0 Source

Constructors

choice

Added in v3.6.0 Source

Get a random element from an iterable.

Signature

declare const choice: <Self extends Iterable<unknown>>(elements: Self) => Self extends NonEmptyIterable.NonEmptyIterable<infer A> ? Effect.Effect<A> : Self extends Array.NonEmptyReadonlyArray<infer A> ? Effect.Effect<A> : Self extends Iterable<infer A> ? Effect.Effect<A, Cause.NoSuchElementException> : never

Example

import { Effect, Random } from "effect"


Effect.gen(function* () {
  const randomItem = yield* Random.choice([1, 2, 3])
  console.log(randomItem)
})

fixed

Added in v3.11.0 Source

Constructs the Random service from an array of literal values. The service will cycle through the provided values in order when generating random values. This constructor is useful for creating deterministic sequences for testing or when specific values need to be returned.

Signature

declare const fixed: <T extends Array.NonEmptyArray<any>>(values: T) => Random

Example

import { Effect, Random } from "effect"


Effect.gen(function* () {
  console.log(yield* Random.next) // 0.2
  console.log(yield* Random.next) // 0.5
  console.log(yield* Random.next) // 0.8
  console.log(yield* Random.next) // 0.2 (cycles back)
}).pipe(Effect.withRandom(Random.fixed([0.2, 0.5, 0.8])))

Example

import { Effect, Random } from "effect"


Effect.gen(function* () {
  console.log(yield* Random.nextBoolean) // true
  console.log(yield* Random.nextBoolean) // false
  console.log(yield* Random.nextBoolean) // true
}).pipe(Effect.withRandom(Random.fixed([true, false, true])))

make

Added in v3.5.0 Source

Constructs the Random service, seeding the pseudo-random number generator with an hash of the specified seed. This constructor is useful for generating predictable sequences of random values for specific use cases.

Example uses:

  • Generating random UI data for visual tests.
  • Creating data that needs to change daily but remain the same throughout a single day, such as using a date as the seed.

Signature

declare const make: <A>(seed: A) => Random

Example

import * as assert from "node:assert"
import { Effect, Random } from "effect"


const random1 = Random.make("myseed")
const random2 = Random.make("myseed")


assert.equal(Effect.runSync(random1.next), Effect.runSync(random2.next))

next

Added in v2.0.0 Source

Returns the next numeric value from the pseudo-random number generator.

Signature

declare const next: Effect.Effect<number>

nextBoolean

Added in v2.0.0 Source

Returns the next boolean value from the pseudo-random number generator.

Signature

declare const nextBoolean: Effect.Effect<boolean>

nextInt

Added in v2.0.0 Source

Returns the next integer value from the pseudo-random number generator.

Signature

declare const nextInt: Effect.Effect<number>

nextIntBetween

Added in v2.0.0 Source

Returns the next integer value in the specified range from the pseudo-random number generator.

Signature

declare const nextIntBetween: (min: number, max: number) => Effect.Effect<number>

nextRange

Added in v2.0.0 Source

Returns the next numeric value in the specified range from the pseudo-random number generator.

Signature

declare const nextRange: (min: number, max: number) => Effect.Effect<number>

randomWith

Added in v2.0.0 Source

Retreives the Random service from the context and uses it to run the specified workflow.

Signature

declare const randomWith: <A, E, R>(f: (random: Random) => Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>

shuffle

Added in v2.0.0 Source

Uses the pseudo-random number generator to shuffle the specified iterable.

Signature

declare const shuffle: <A>(elements: Iterable<A>) => Effect.Effect<Chunk.Chunk<A>>

Context

Random

Added in v2.0.0 Source

Signature

declare const Random: Tag<Random, Random>

Models

Random interface

Added in v2.0.0 Source

Signature

interface Random {
  readonly [RandomTypeId]: typeof RandomTypeId;
  readonly next: Effect<number>;
  readonly nextBoolean: Effect<boolean>;
  readonly nextInt: Effect<number>;
  nextIntBetween(min: number, max: number): Effect<number>;
  nextRange(min: number, max: number): Effect<number>;
  shuffle<A>(elements: Iterable<A>): Effect<Chunk<A>>;
}

Symbols

RandomTypeId

Added in v2.0.0 Source

Signature

declare const RandomTypeId: unique symbol

RandomTypeId type

Added in v2.0.0 Source

Signature

type RandomTypeId = typeof RandomTypeId