Random

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.

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> : never

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.

declare const next: Effect.Effect<number>

import { Effect, Random } from "effect"

await Effect.runPromise(Random.next.pipe(Random.withSeed("example"))) // => 0.1633802591287037

Generates 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.

declare function nextBetween(min: number, max: number): Effect<number>

import { Effect, Random } from "effect"

await Effect.runPromise(Random.nextBetween(0, 1).pipe(Random.withSeed("example"))) // => 0.1633802591287037

Generates a random boolean value.

When to use

Use to make a pseudo-random true-or-false choice.

declare const nextBoolean: Effect.Effect<boolean>

import { Effect, Random } from "effect"

await Effect.runPromise(Random.nextBoolean.pipe(Random.withSeed("example"))) // => false

Generates 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.

declare const nextInt: Effect.Effect<number>

import { Effect, Random } from "effect"

await Effect.runPromise(Random.nextInt.pipe(Random.withSeed("example"))) // => -6064002158214091

Generates 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.

declare function nextIntBetween(min: number, max: number, options?: {
  readonly halfOpen?: boolean;
}): Effect<number>

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.

declare function shuffle<A>(elements: Iterable<A>): Effect<Array<A>>

import { Effect, Random } from "effect"

await Effect.runPromise(Random.shuffle([1, 2, 3, 4, 5]).pipe(Random.withSeed("example"))) // => [4, 2, 5, 3, 1]

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.

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>;
}

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]]

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.

declare const Random: Context.Reference<{
  nextDoubleUnsafe(): number;
  nextIntUnsafe(): number;
}>

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]