houser-js-utils
Version:
A comprehensive collection of TypeScript utility functions for common development tasks including array manipulation, string processing, date handling, random number generation, validation, and much more.
238 lines (237 loc) • 8.71 kB
TypeScript
/**
* @module RandomUtils
* @description A comprehensive collection of utility functions for random number generation.
* Implements functionality proposed in TC39 Random API proposals including seeded pseudo-random
* number generation, various distribution methods, and utility functions for common randomness needs.
* @example
* ```typescript
* import { RandomUtils } from 'houser-js-utils';
*
* // Generate random integer in range
* const dice = RandomUtils.int(1, 6);
*
* // Create seeded generator for reproducible sequences
* const seeded = RandomUtils.Seeded.fromFixed(42);
* const value = seeded.random();
*
* // Generate random bytes
* const bytes = RandomUtils.bytes(16);
* ```
*/
/**
* A seeded pseudo-random number generator that produces reproducible sequences.
* Based on the TC39 Seeded Random proposal.
*/
export declare class SeededRandom {
private readonly prng;
/**
* Creates a new seeded random generator
* @param seed - Seed value or Uint8Array (up to 32 bytes)
*/
constructor(seed: number | Uint8Array);
/**
* Factory method that requires exact 32-byte seed
* @param seed - Exactly 32 bytes of seed data
* @returns New SeededRandom instance
*/
static fromSeed(seed: Uint8Array): SeededRandom;
/**
* Factory method that creates generator from state
* @param state - State data (simplified to number for this implementation)
* @returns New SeededRandom instance
*/
static fromState(state: number): SeededRandom;
/**
* Factory method for simple integer seeds
* @param byte - Integer between 0-255
* @returns New SeededRandom instance
*/
static fromFixed(byte: number): SeededRandom;
/**
* Generate a random number between 0 and 1 (exclusive)
* @returns Random number in [0,1)
*/
random(): number;
/**
* Generate a new seed for creating child PRNGs
* @returns 32-byte Uint8Array suitable for seeding
*/
seed(): Uint8Array;
/**
* Get current generator state
* @returns Current state as number
*/
getState(): number;
/**
* Set generator state
* @param state - State to set
* @returns This instance for chaining
*/
setState(state: number): this;
/**
* Generate random number in range
* @param lo - Lower bound
* @param hi - Upper bound
* @param step - Optional step size
* @returns Random number in specified range
*/
number(lo: number, hi: number, step?: number): number;
/**
* Generate random integer in range
* @param lo - Lower bound (inclusive)
* @param hi - Upper bound (inclusive)
* @param step - Optional step size
* @returns Random integer in specified range
*/
int(lo: number, hi: number, step?: number): number;
/**
* Generate random BigInt in range
* @param lo - Lower bound (inclusive)
* @param hi - Upper bound (inclusive)
* @param step - Optional step size
* @returns Random BigInt in specified range
*/
bigint(lo: bigint, hi: bigint, step?: bigint): bigint;
/**
* Generate random bytes
* @param n - Number of bytes to generate
* @returns Uint8Array of random bytes
*/
bytes(n: number): Uint8Array;
/**
* Fill buffer with random bytes
* @param buffer - Buffer to fill
* @param start - Start position (optional)
* @param end - End position (optional)
* @returns The filled buffer
*/
fillBytes<T extends ArrayBuffer | ArrayBufferView>(buffer: T, start?: number, end?: number): T;
}
/**
* Collection of random utility functions
*/
export declare const RandomUtils: {
/**
* The SeededRandom class for creating reproducible random sequences
*/
Seeded: typeof SeededRandom;
/**
* Generate a random number between 0 and 1 (exclusive)
* @returns Random number in [0,1)
*/
random(): number;
/**
* Generate a random number in a specified range
* @param lo - Lower bound
* @param hi - Upper bound
* @param step - Optional step size
* @param randomFn - Optional custom random function
* @returns Random number in specified range
*/
number(lo: number, hi: number, step?: number, randomFn?: () => number): number;
/**
* Generate a random integer in a specified range
* @param lo - Lower bound (inclusive)
* @param hi - Upper bound (inclusive)
* @param step - Optional step size
* @param randomFn - Optional custom random function
* @returns Random integer in specified range
*/
int(lo: number, hi: number, step?: number, randomFn?: () => number): number;
/**
* Generate a random BigInt in a specified range
* @param lo - Lower bound (inclusive)
* @param hi - Upper bound (inclusive)
* @param step - Optional step size
* @param randomFn - Optional custom random function
* @returns Random BigInt in specified range
*/
bigint(lo: bigint, hi: bigint, step?: bigint, randomFn?: () => number): bigint;
/**
* Generate random bytes
* @param n - Number of bytes to generate
* @param randomFn - Optional custom random function
* @returns Uint8Array of random bytes
*/
bytes(n: number, randomFn?: () => number): Uint8Array;
/**
* Fill a buffer with random bytes
* @param buffer - Buffer to fill (ArrayBuffer or TypedArray)
* @param start - Start position (optional)
* @param end - End position (optional)
* @param randomFn - Optional custom random function
* @returns The filled buffer
*/
fillBytes<T extends ArrayBuffer | ArrayBufferView>(buffer: T, start?: number, end?: number, randomFn?: () => number): T;
/**
* Generate a random boolean value
* @param probability - Probability of returning true (0-1, default: 0.5)
* @param randomFn - Optional custom random function
* @returns Random boolean
*/
boolean(probability?: number, randomFn?: () => number): boolean;
/**
* Choose a random element from an array
* @param array - Array to choose from
* @param randomFn - Optional custom random function
* @returns Random element from the array
*/
choice<T>(array: T[], randomFn?: () => number): T;
/**
* Choose multiple random elements from an array without replacement
* @param array - Array to choose from
* @param count - Number of elements to choose
* @param randomFn - Optional custom random function
* @returns Array of randomly chosen elements
*/
sample<T>(array: T[], count: number, randomFn?: () => number): T[];
/**
* Shuffle an array using Fisher-Yates algorithm
* @param array - Array to shuffle
* @param randomFn - Optional custom random function
* @returns New shuffled array
*/
shuffle<T>(array: T[], randomFn?: () => number): T[];
/**
* Generate a random string of specified length
* @param length - Length of the string to generate
* @param charset - Character set to use (default: alphanumeric)
* @param randomFn - Optional custom random function
* @returns Random string
*/
string(length: number, charset?: string, randomFn?: () => number): string;
/**
* Generate a random UUID v4
* @param randomFn - Optional custom random function
* @returns Random UUID string
*/
uuid(randomFn?: () => number): string;
/**
* Generate a weighted random choice
* @param items - Array of items to choose from
* @param weights - Array of weights corresponding to items
* @param randomFn - Optional custom random function
* @returns Randomly chosen item based on weights
*/
weightedChoice<T>(items: T[], weights: number[], randomFn?: () => number): T;
/**
* Generate a random number from normal distribution (Box-Muller transform)
* @param mean - Mean of the distribution (default: 0)
* @param stdDev - Standard deviation (default: 1)
* @param randomFn - Optional custom random function
* @returns Random number from normal distribution
*/
normal(mean?: number, stdDev?: number, randomFn?: () => number): number;
/**
* Generate a random number from exponential distribution
* @param rate - Rate parameter (lambda)
* @param randomFn - Optional custom random function
* @returns Random number from exponential distribution
*/
exponential(rate?: number, randomFn?: () => number): number;
/**
* Generate a random seed for seeding PRNGs
* @returns 32-byte Uint8Array suitable for seeding
*/
seed(): Uint8Array;
};