Generating random values

Since this package attempts to reduce the biases involved, APIs can be comparatively slow. APIs that require a secure random source require an RandomReader implementation as its parameter. See Defining a RandomReader.

Random integers

Use generateRandomInteger() or generateRandomIntegerNumber() to generate random integers between 0 (inclusive) and maximum (exclusive).

import { generateRandomInteger, generateRandomIntegerNumber } from "oslo/crypto";

// random number from 0 to 9
const num: bigint = generateRandomInteger(random, 10n);
const num: number = generateRandomIntegerNumber(random, 10);

Random strings

Use generateRandomString() to generate random strings with a predefined set of characters. This also requires a RandomReader function.

import { generateRandomString } from "oslo/crypto";

// 10-characters long string consisting of upper case letters
const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
generateRandomString(random, alphabet, 10);

Defining a RandomReader

RandomReader should use a cryptographically secure random source.

Using the global Web Crypto API

The Web Crypto API is globally available in most modern runtimes, including Node.js 20+, Bun, Deno, and Cloudflare Workers.

import type { RandomReader } from "@oslojs/crypto/random";

const random: RandomReader = {
	read(bytes: Uint8Array): void {
		crypto.getRandomValues(bytes);
	}
};

Using Node's Crypto module

An implementation of the Web Crypto API can be imported in Node.js 18+.

import { webcrypto } from "node:crypto";

import type { RandomReader } from "@oslojs/crypto/random";

const random: RandomReader = {
	read(bytes: Uint8Array): void {
		webcrypto.getRandomValues(bytes);
	}
};

import { getRandomValues } from "node:crypto";

import type { RandomReader } from "@oslojs/crypto/random";

const random: RandomReader = {
	read(bytes: Uint8Array): void {
		getRandomValues(bytes);
	}
};

Use fillRandomSync() for older versions of Node.js.

import { fillRandomSync } from "node:crypto";

import type { RandomReader } from "@oslojs/crypto/random";

const random: RandomReader = {
	read(bytes: Uint8Array) {
		fillRandomSync(bytes);
	}
};