Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

Random

14 exports Since v2.0.0 Source

Constructors

choice

Since v3.6.0

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

Since v3.11.0

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

Since v3.5.0

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

Since v2.0.0

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

Signature

declare const next: Effect.Effect<number>

nextBoolean

Since v2.0.0

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

Signature

declare const nextBoolean: Effect.Effect<boolean>

nextInt

Since v2.0.0

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

Signature

declare const nextInt: Effect.Effect<number>

nextIntBetween

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

Signature

declare const Random: Tag<Random, Random>

Models

Random

interface
Since v2.0.0

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

Since v2.0.0

Signature

declare const RandomTypeId: unique symbol

RandomTypeId

type
Since v2.0.0

Signature

type RandomTypeId = typeof RandomTypeId