Random.choice — API

Random.choiceconsteffect/Random.ts:258

<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

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.

Example (Choosing a random value)

import { Effect, Random } from "effect"

const program = Effect.gen(function*() {
  const value = yield* Random.choice(["red", "green", "blue"] as const)
  console.log(value)
})

Random Number Generators

Source effect/Random.ts:25811 lines

export 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 = ((elements: Iterable<unknown>) => {
    const buffer = Array.from(elements)
    return buffer.length === 0
      ? Effect.fail(new Cause.NoSuchElementError("Cannot select a random element from an empty array"))
      : randomWith((r) => buffer[Math.min(buffer.length - 1, Math.floor(r.nextDoubleUnsafe() * buffer.length))]!)
  }) as any