@portable/random

Functions

Random.bytes

Returns length random bytes. Unlike crypto.getRandomValues, it allocates the array and has no 65,536-byte limit.

function bytes(length: number): Uint8Array<ArrayBuffer>;

import * as Random from '@portable/random';
 
const key = Random.bytes(32);

Random.float

Returns a random number from 0 up to but not including 1, made from 53 random bits, so every multiple of 2^-53 in that range is equally likely.

function float(): number;

import * as Random from '@portable/random';
 
if (Random.float() < 0.1) {
  console.log('sampled');
}

Random.int

Returns a random integer from min to max, both included. min and max must be safe integers, and the range can hold up to 2^53 integers, such as 0 to Number.MAX_SAFE_INTEGER.

Every integer in the range is equally likely. When a random value is at or above the largest multiple of the range size, int draws a new one instead of reducing it with a modulo.

function int(min: number, max: number): number;

import * as Random from '@portable/random';
 
const die = Random.int(1, 6);

Random.pick

Returns a random element of array. Throws a RangeError if array is empty.

function pick<value>(array: readonly value[]): value;

import * as Random from '@portable/random';
 
const color = Random.pick(['red', 'green', 'blue']);

Random.shuffle

Returns a shuffled copy of array, made with a Fisher-Yates shuffle, so every order is equally likely. array is not changed.

function shuffle<value>(array: readonly value[]): value[];

import * as Random from '@portable/random';
 
const deck = Random.shuffle(['A', 'K', 'Q', 'J']);

Random.string

Returns a random string of length characters, each picked with equal chance from alphabet. The default alphabet is the 64 URL-safe characters A-Z, a-z, 0-9, - and _, so 21 characters hold 126 random bits, as in a nanoid.

alphabet is split into code points, so it can hold emoji. A character listed twice is picked twice as often.

function string(length: number, options: string.Options = {}): string;

import * as Random from '@portable/random';
 
const id = Random.string(21);
const pin = Random.string(6, { alphabet: '0123456789' });

Random.seeded

Returns the package's functions backed by a deterministic generator, so the same seed gives the same results in every runtime. Use it for tests and reproducible simulations. It is not for secrets: anyone who sees a few outputs can predict the rest.

The generator is xoshiro128** 1.1, seeded with two SplitMix64 outputs as its authors recommend. Its first 32-bit outputs match Rust's Xoshiro128StarStar::seed_from_u64(seed) from rand_xoshiro. seed is a safe integer, and a negative seed is read as its 64-bit two's complement.

function seeded(seed: number): Seeded;

import * as Random from '@portable/random';
 
const random = Random.seeded(42);
const sizes = Array.from({ length: 10 }, () => random.int(1, 64));

Types

Random.Seeded

The functions of @portable/random, drawing from a seeded generator instead of crypto.getRandomValues.

type Seeded = {
  readonly int: (min: number, max: number) => number;
  readonly float: () => number;
  readonly string: (
    length: number,
    options?: {
      alphabet?: string | undefined;
    },
  ) => string;
  readonly shuffle: <value>(array: readonly value[]) => value[];
  readonly pick: <value>(array: readonly value[]) => value;
  readonly bytes: (length: number) => Uint8Array<ArrayBuffer>;
};