Random
Provides pseudo-random generation through an Effect service.
This module exposes effectful generators for booleans, doubles, safe integers, bounded numbers, shuffling, and deterministic seeded runs. Because random generation is a service, tests and applications can replace the generator used by Effect programs.
Generators
Gets a random element from an iterable.
When to use
Use to select one value uniformly from a collection using the active Random
service.
Details
If the input type is known to be non-empty, the returned effect cannot fail.
Otherwise, empty iterables fail with Cause.NoSuchElementError.
Signature
declare const choice: <Self extends Iterable<unknown>>(elements: Self) => Self extends NonEmptyIterable.NonEmptyIterable<infer A> ? Effect.Effect<A> : Self extends Arr.NonEmptyReadonlyArray<infer A> ? Effect.Effect<A> : Self extends Iterable<infer A> ? Effect.Effect<A, Cause.NoSuchElementError> : neverExample Choosing a random value
import { Effect, Random } from "effect"
await Effect.runPromise(Random.choice(["red", "green", "blue"] as const).pipe(Random.withSeed("example"))) // => "red"Generates a random number between 0 (inclusive) and 1 (exclusive).
When to use
Use to generate a pseudo-random floating-point number in the standard
[0, 1) range.
Signature
declare const next: Effect.Effect<number>Example Generating a random number
import { Effect, Random } from "effect"
await Effect.runPromise(Random.next.pipe(Random.withSeed("example"))) // => 0.1633802591287037Generates a random number between min (inclusive) and max (exclusive).
When to use
Use to generate a pseudo-random floating-point number within a numeric range.
Signature
declare function nextBetween(min: number, max: number): Effect<number>Example Generating a bounded random number
import { Effect, Random } from "effect"
await Effect.runPromise(Random.nextBetween(0, 1).pipe(Random.withSeed("example"))) // => 0.1633802591287037Generates a random boolean value.
When to use
Use to make a pseudo-random true-or-false choice.
Signature
declare const nextBoolean: Effect.Effect<boolean>Example Generating a random boolean
import { Effect, Random } from "effect"
await Effect.runPromise(Random.nextBoolean.pipe(Random.withSeed("example"))) // => falseGenerates a random integer between Number.MIN_SAFE_INTEGER (inclusive)
and Number.MAX_SAFE_INTEGER (inclusive).
When to use
Use to generate a pseudo-random safe integer across the full safe-integer range.
Signature
declare const nextInt: Effect.Effect<number>Example Generating a random integer
import { Effect, Random } from "effect"
await Effect.runPromise(Random.nextInt.pipe(Random.withSeed("example"))) // => -6064002158214091Generates a random integer between min and max.
When to use
Use to generate a pseudo-random integer within a rounded numeric range.
Details
The lower bound is rounded up with Math.ceil and the upper bound is
rounded down with Math.floor. By default the range is inclusive; set
options.halfOpen: true to exclude the upper bound.
Signature
declare function nextIntBetween(min: number, max: number, options?: { readonly halfOpen?: boolean;}): Effect<number>Example Generating a bounded random integer
import { Effect, Random } from "effect"
const program = Effect.gen(function*() { const diceRoll1 = yield* Random.nextIntBetween(1, 6) const diceRoll2 = yield* Random.nextIntBetween(1, 6, { halfOpen: true }) const diceRoll3 = yield* Random.nextIntBetween(0, 10) return [diceRoll1, diceRoll2, diceRoll3]})
await Effect.runPromise(program.pipe(Random.withSeed("example"))) // => [1, 4, 0]Uses the pseudo-random number generator to shuffle the specified iterable.
When to use
Use to randomly reorder an iterable using the active Random service.
Signature
declare function shuffle<A>(elements: Iterable<A>): Effect<Array<A>>Example Shuffling values
import { Effect, Random } from "effect"
await Effect.runPromise(Random.shuffle([1, 2, 3, 4, 5]).pipe(Random.withSeed("example"))) // => [4, 2, 5, 3, 1]Providing Services
Seeds the pseudo-random number generator with the specified value.
When to use
Use to run an effect with a deterministic pseudo-random sequence.
Details
Using the same seed produces the same random sequence, which is useful for tests and reproducible simulations.
Gotchas
Use an unpredictable seed when uniqueness or unpredictability matters.
Signature
declare const withSeed: { (seed: string | number): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>; <A, E, R>(self: Effect<A, E, R>, seed: string | number): Effect<A, E, R>;}Example Seeding random generation
import { Effect, Random } from "effect"
const program = Effect.gen(function*() { const value1 = yield* Random.next const value2 = yield* Random.next return [value1, value2]})
await Effect.runPromise(Effect.all([ program.pipe(Random.withSeed("my-seed")), program.pipe(Random.withSeed("my-seed"))])) // => [[0.018368576514773527, 0.4010840628128671], [0.018368576514773527, 0.4010840628128671]]Services
Represents a service for generating pseudo-random numbers.
When to use
Use to access or provide the random-number generator service used by Effect programs.
Gotchas
The default implementation is based on Math.random and is not
cryptographically secure. Replace the service with a cryptographically secure
implementation before using these generators for security-sensitive values.
Signature
declare const Random: Reference<Random>Example Accessing the random service
import { Effect, Random } from "effect"
const program = Effect.gen(function*() { const float = yield* Random.next const integer = yield* Random.nextInt const inRange = yield* Random.nextIntBetween(1, 100) return [float, integer, inRange] as const})
await Effect.runPromise(program.pipe(Random.withSeed("example"))) // => [0.1633802591287037, 3434461687501127, 1]The service used to generate pseudo-random numbers.
Signature
interface Random { nextDoubleUnsafe(): number; nextIntUnsafe(): number;}