Randomness Method & Limitations

/**
 * Stable identifier for result metadata and exported experiment data.
 * Increment the version whenever the source or outcome mapping changes.
 */
export const RANDOM_METHOD_ID = 'web-crypto-getRandomValues-v1' as const;
export const RANDOM_METHOD_VERSION = 1 as const;

export type RandomBit = 0 | 1;

/** A replaceable byte source keeps boundary tests deterministic. */
export interface RandomByteSource {
  fill(target: Uint8Array): void;
}

export class RandomSourceUnavailableError extends Error {
  constructor() {
    super(
      'Cryptographically strong randomness is unavailable. This tool requires Web Crypto and does not fall back to Math.random().',
    );
    this.name = 'RandomSourceUnavailableError';
  }
}

export function isWebCryptoAvailable(): boolean {
  return Boolean(
    globalThis.crypto &&
      typeof globalThis.crypto.getRandomValues === 'function',
  );
}

/**
 * The production source is resolved lazily so server rendering can import this
 * module without requiring a browser global.
 */
export const webCryptoByteSource: RandomByteSource = {
  fill(target) {
    const cryptoApi = globalThis.crypto;

    if (!isWebCryptoAvailable() || !cryptoApi) {
      throw new RandomSourceUnavailableError();
    }

    cryptoApi.getRandomValues(target);
  },
};

const UINT32_RANGE = 0x1_0000_0000;
const WEB_CRYPTO_MAX_BYTES_PER_CALL = 65_536;

function fillBytes(target: Uint8Array, source: RandomByteSource): void {
  for (
    let offset = 0;
    offset < target.length;
    offset += WEB_CRYPTO_MAX_BYTES_PER_CALL
  ) {
    source.fill(
      target.subarray(
        offset,
        Math.min(offset + WEB_CRYPTO_MAX_BYTES_PER_CALL, target.length),
      ),
    );
  }
}

function readUint32LittleEndian(bytes: Uint8Array): number {
  return (
    bytes[0] +
    bytes[1] * 0x100 +
    bytes[2] * 0x1_0000 +
    bytes[3] * 0x100_0000
  );
}

/** Return an unbiased binary value. */
export function randomBit(
  source: RandomByteSource = webCryptoByteSource,
): RandomBit {
  const bytes = new Uint8Array(1);
  fillBytes(bytes, source);
  return (bytes[0] & 1) as RandomBit;
}

/**
 * Return an integer in [0, maxExclusive) without modulo bias.
 *
 * Values in the incomplete upper portion of the uint32 range are rejected, so
 * every accepted output has exactly the same number of source values.
 */
export function randomInt(
  maxExclusive: number,
  source: RandomByteSource = webCryptoByteSource,
): number {
  if (
    !Number.isSafeInteger(maxExclusive) ||
    maxExclusive < 1 ||
    maxExclusive > UINT32_RANGE
  ) {
    throw new RangeError(
      `maxExclusive must be an integer from 1 through ${UINT32_RANGE}.`,
    );
  }

  const acceptanceLimit =
    UINT32_RANGE - (UINT32_RANGE % maxExclusive);
  const bytes = new Uint8Array(4);

  while (true) {
    fillBytes(bytes, source);
    const value = readUint32LittleEndian(bytes);

    if (value < acceptanceLimit) {
      return value % maxExclusive;
    }
  }
}

/**
 * Return 1 with probability `favourableOutcomes / totalOutcomes`, and 0
 * otherwise, with no bias beyond that configured ratio.
 *
 * The ratio is exact because it is applied to an unbiased bounded integer
 * rather than to a floating-point value: a threshold comparison on
 * `randomInt(totalOutcomes)` cannot round a probability the way `< 0.3` on a
 * float can.
 */
export function randomWeightedBit(
  favourableOutcomes: number,
  totalOutcomes: number,
  source: RandomByteSource = webCryptoByteSource,
): RandomBit {
  if (!Number.isSafeInteger(totalOutcomes) || totalOutcomes < 1) {
    throw new RangeError('totalOutcomes must be a positive safe integer.');
  }
  if (
    !Number.isSafeInteger(favourableOutcomes) ||
    favourableOutcomes < 0 ||
    favourableOutcomes > totalOutcomes
  ) {
    throw new RangeError(
      'favourableOutcomes must be an integer from 0 through totalOutcomes.',
    );
  }

  // Certain outcomes must not consume randomness, so that a 0% or 100%
  // configuration is exactly certain rather than merely overwhelmingly likely.
  if (favourableOutcomes === 0) return 0;
  if (favourableOutcomes === totalOutcomes) return 1;

  return randomInt(totalOutcomes, source) < favourableOutcomes ? 1 : 0;
}

/**
 * Sample many independent binary values with one packed byte allocation and
 * the minimum practical number of Web Crypto calls.
 */
export function sampleMany(
  count: number,
  source: RandomByteSource = webCryptoByteSource,
): Uint8Array {
  if (!Number.isSafeInteger(count) || count < 0) {
    throw new RangeError('count must be a non-negative safe integer.');
  }

  if (count === 0) {
    return new Uint8Array();
  }

  const packedBytes = new Uint8Array(Math.ceil(count / 8));
  const samples = new Uint8Array(count);
  fillBytes(packedBytes, source);

  for (let index = 0; index < count; index += 1) {
    samples[index] =
      (packedBytes[index >> 3] >> (index & 7)) & 1;
  }

  return samples;
}