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
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>
: never;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>;nextBetween
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.
Signature
declare function nextBetween(min: number, max: number): Effect<number>;nextBoolean
Generates a random boolean value.
When to use
Use to make a pseudo-random true-or-false choice.
Signature
declare const nextBoolean: Effect.Effect<boolean>;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.
Signature
declare const nextInt: Effect.Effect<number>;nextIntBetween
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.
Signature
declare function nextIntBetween(
min: number,
max: number,
options?: {
readonly halfOpen?: boolean;
},
): Effect<number>;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>>;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>;
};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: Context.Reference<{
nextDoubleUnsafe(): number;
nextIntUnsafe(): number;
}>;
Gets a random element from an iterable.
When to use
Use to select one value uniformly from a collection using the active
Randomservice.Details
If the input type is known to be non-empty, the returned effect cannot fail. Otherwise, empty iterables fail with
Cause.NoSuchElementError.