CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-pure-rand

Pure pseudorandom number generators with immutable state management and uniform distribution functions

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

distributions.mddocs/

Distribution Functions

Pure Rand provides uniform distribution functions that ensure equal probability across value ranges. These functions convert the raw output from generators into useful ranges for integers, bigints, and arbitrary precision numbers.

Capabilities

Integer Distributions

Generate uniform random integers within specified ranges using standard JavaScript numbers.

uniformIntDistribution

Pure function that returns a distribution function or immediately generates a value with a new generator.

/**
 * Generate uniform random integers between from and to (inclusive)
 * @param from - Minimum value (inclusive)
 * @param to - Maximum value (inclusive)
 * @returns Distribution function for deferred execution
 */
function uniformIntDistribution(from: number, to: number): Distribution<number>;

/**
 * Generate uniform random integers between from and to (inclusive) immediately
 * @param from - Minimum value (inclusive)
 * @param to - Maximum value (inclusive)
 * @param rng - RandomGenerator instance
 * @returns Tuple of [generated value, new generator]
 */
function uniformIntDistribution(from: number, to: number, rng: RandomGenerator): [number, RandomGenerator];

Usage Examples:

import { uniformIntDistribution, xoroshiro128plus } from 'pure-rand';

const rng = xoroshiro128plus(42);

// Deferred execution pattern
const diceRoll = uniformIntDistribution(1, 6);
const [value1, rng2] = diceRoll(rng);
const [value2, rng3] = diceRoll(rng2);

// Immediate execution pattern
const [directValue, nextRng] = uniformIntDistribution(1, 100, rng);

// Range examples
const [coinFlip, rng4] = uniformIntDistribution(0, 1, rng3); // 0 or 1
const [percentage, rng5] = uniformIntDistribution(0, 100, rng4); // 0 to 100
const [negativeRange, rng6] = uniformIntDistribution(-10, 10, rng5); // -10 to 10

unsafeUniformIntDistribution

Unsafe function that mutates the generator for maximum performance.

/**
 * Generate uniform random integers, mutating the generator for performance
 * @param from - Minimum value (inclusive)
 * @param to - Maximum value (inclusive)
 * @param rng - RandomGenerator instance (will be mutated)
 * @returns Generated random integer
 */
function unsafeUniformIntDistribution(from: number, to: number, rng: RandomGenerator): number;

Usage Examples:

import { unsafeUniformIntDistribution, xoroshiro128plus } from 'pure-rand';

const rng = xoroshiro128plus(42);

// Multiple values with same generator (mutates rng)
const dice1 = unsafeUniformIntDistribution(1, 6, rng);
const dice2 = unsafeUniformIntDistribution(1, 6, rng);
const dice3 = unsafeUniformIntDistribution(1, 6, rng);

// High-performance usage
const results: number[] = [];
for (let i = 0; i < 1000; i++) {
  results.push(unsafeUniformIntDistribution(1, 1000, rng));
}

BigInt Distributions

Generate uniform random BigInt values for arbitrary precision integers beyond JavaScript's safe integer range.

uniformBigIntDistribution

Pure function for BigInt value generation.

/**
 * Generate uniform random bigints between from and to (inclusive)
 * @param from - Minimum bigint value (inclusive)
 * @param to - Maximum bigint value (inclusive)
 * @returns Distribution function for deferred execution
 */
function uniformBigIntDistribution(from: bigint, to: bigint): Distribution<bigint>;

/**
 * Generate uniform random bigints between from and to (inclusive) immediately
 * @param from - Minimum bigint value (inclusive)
 * @param to - Maximum bigint value (inclusive)
 * @param rng - RandomGenerator instance
 * @returns Tuple of [generated bigint, new generator]
 */
function uniformBigIntDistribution(from: bigint, to: bigint, rng: RandomGenerator): [bigint, RandomGenerator];

Usage Examples:

import { uniformBigIntDistribution, xoroshiro128plus } from 'pure-rand';

const rng = xoroshiro128plus(42);

// Large number ranges
const [largeInt, rng2] = uniformBigIntDistribution(
  BigInt("123456789012345678901234567890"),
  BigInt("999999999999999999999999999999"),
  rng
);

// Deferred pattern with BigInt
const bigIntGen = uniformBigIntDistribution(0n, 1000000n);
const [value, nextRng] = bigIntGen(rng2);

unsafeUniformBigIntDistribution

Unsafe function for high-performance BigInt generation.

/**
 * Generate uniform random bigints, mutating the generator for performance
 * @param from - Minimum bigint value (inclusive)
 * @param to - Maximum bigint value (inclusive)
 * @param rng - RandomGenerator instance (will be mutated)
 * @returns Generated random bigint
 */
function unsafeUniformBigIntDistribution(from: bigint, to: bigint, rng: RandomGenerator): bigint;

Array Integer Distributions

Generate uniform random values using arbitrary precision integers represented as arrays. Useful for cryptographic applications or when working with extremely large numbers.

ArrayInt Type

type ArrayInt = {
  /** Sign of the represented number */
  sign: -1 | 1;
  /** Value of the number, must only contain numbers in the range [0, 0xffffffff] */
  data: number[];
};

The ArrayInt type represents integers larger than what can be represented in standard JavaScript numbers. Examples:

  • { sign: 1, data: [42] } represents 42
  • { sign: -1, data: [42] } represents -42
  • { sign: -1, data: [5, 42] } represents -1 * (5 * 2^32 + 42)

ArrayInt Construction Examples:

import { uniformArrayIntDistribution, xoroshiro128plus } from 'pure-rand';

// ArrayInt type is used for arbitrary precision integers
type ArrayInt = {
  sign: -1 | 1;
  data: number[];
};

const rng = xoroshiro128plus(42);

// Simple positive number
const smallPositive: ArrayInt = { sign: 1, data: [123] };

// Simple negative number  
const smallNegative: ArrayInt = { sign: -1, data: [456] };

// Large positive number (larger than 2^32)
const largePositive: ArrayInt = { sign: 1, data: [1, 2147483647] }; // 1 * 2^32 + 2147483647

// Very large number using multiple components
const veryLarge: ArrayInt = { 
  sign: 1, 
  data: [0x12345678, 0x9abcdef0, 0x11111111] 
}; // Multi-precision representation

// Generate random ArrayInt values
const [randomArrayInt, nextRng] = uniformArrayIntDistribution(
  smallPositive,
  largePositive,
  rng
);

uniformArrayIntDistribution

Pure function for arbitrary precision integer generation.

/**
 * Generate uniform random ArrayInt values for arbitrary precision integers
 * @param from - Minimum ArrayInt value (inclusive)
 * @param to - Maximum ArrayInt value (inclusive)
 * @returns Distribution function for deferred execution
 */
function uniformArrayIntDistribution(from: ArrayInt, to: ArrayInt): Distribution<ArrayInt>;

/**
 * Generate uniform random ArrayInt values immediately
 * @param from - Minimum ArrayInt value (inclusive)
 * @param to - Maximum ArrayInt value (inclusive)
 * @param rng - RandomGenerator instance
 * @returns Tuple of [generated ArrayInt, new generator]
 */
function uniformArrayIntDistribution(from: ArrayInt, to: ArrayInt, rng: RandomGenerator): [ArrayInt, RandomGenerator];

unsafeUniformArrayIntDistribution

Unsafe function for high-performance arbitrary precision generation.

/**
 * Generate uniform random ArrayInt values, mutating the generator for performance
 * @param from - Minimum ArrayInt value (inclusive)
 * @param to - Maximum ArrayInt value (inclusive)
 * @param rng - RandomGenerator instance (will be mutated)
 * @returns Generated random ArrayInt
 */
function unsafeUniformArrayIntDistribution(from: ArrayInt, to: ArrayInt, rng: RandomGenerator): ArrayInt;

Distribution Patterns

Deferred Execution

Create a distribution function once and reuse it multiple times:

import { uniformIntDistribution, xoroshiro128plus } from 'pure-rand';

const rng = xoroshiro128plus(42);
const diceRoll = uniformIntDistribution(1, 6);

// Reuse the same distribution
const [roll1, rng2] = diceRoll(rng);
const [roll2, rng3] = diceRoll(rng2);
const [roll3, rng4] = diceRoll(rng3);

Immediate Execution

Generate values directly when you don't need to reuse the distribution:

import { uniformIntDistribution, xoroshiro128plus } from 'pure-rand';

const rng = xoroshiro128plus(42);

const [roll1, rng2] = uniformIntDistribution(1, 6, rng);
const [roll2, rng3] = uniformIntDistribution(1, 6, rng2);
const [roll3, rng4] = uniformIntDistribution(1, 6, rng3);

Performance Optimization with Unsafe Functions

When maximum performance is needed and you don't require immutability:

import { unsafeUniformIntDistribution, xoroshiro128plus } from 'pure-rand';

const rng = xoroshiro128plus(42);

// High-performance generation (mutates rng)
const results: number[] = [];
for (let i = 0; i < 10000; i++) {
  results.push(unsafeUniformIntDistribution(0, 100, rng));
}

Range Considerations

  • Inclusive bounds: All distribution functions include both from and to values in the possible outcomes
  • Order independence: uniformIntDistribution(10, 1, rng) works the same as uniformIntDistribution(1, 10, rng)
  • Single value: When from === to, the function always returns that value
  • Type safety: BigInt distributions require BigInt parameters, regular int distributions use numbers

Performance Notes

  • Pure functions: Create new generator instances, safe for concurrent use
  • Unsafe functions: Modify generators in-place, highest performance but not thread-safe
  • Deferred patterns: Slight overhead for function creation but enable reusable distributions
  • Immediate patterns: Most direct approach when distribution is used only once

Install with Tessl CLI

npx tessl i tessl/npm-pure-rand

docs

distributions.md

generators.md

index.md

utilities.md

tile.json