@bcts/rand 1.0.0-alpha.9 → 1.0.0-beta.0

package/LICENSE

@@ -1,5 +1,6 @@
-Copyright © 2023 Blockchain Commons, LLC
-Copyright © 2025 Leonardo Amoroso Custodio
+Copyright © 2023-2026 Blockchain Commons, LLC
+Copyright © 2025-2026 Parity Technologies
+
 
 Redistribution and use in source and binary forms, with or without modification,
 are permitted provided that the following conditions are met:

package/dist/index.cjs

@@ -1,4 +1,4 @@
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/widening.ts
 /**
 * Performs wide multiplication for unsigned integers.
@@ -52,10 +52,14 @@ function wideMulU64(a, b) {
 	const wide = (a & mask64) * (b & mask64);
 	return [wide & mask64, wide >> 64n];
 }
-
 //#endregion
 //#region src/magnitude.ts
 /**
+* Copyright © 2023-2026 Blockchain Commons, LLC
+* Copyright © 2025-2026 Parity Technologies
+*
+*/
+/**
 * Converts a signed integer to its unsigned magnitude.
 * For positive numbers, returns the number unchanged.
 * For negative numbers, returns the absolute value (wrapping for MIN values).
@@ -108,10 +112,14 @@ function fromMagnitude64(magnitude) {
 	if ((maskedMag & signBit) !== 0n) return maskedMag - (1n << 64n);
 	return maskedMag;
 }
-
 //#endregion
 //#region src/random-number-generator.ts
 /**
+* Copyright © 2023-2026 Blockchain Commons, LLC
+* Copyright © 2025-2026 Parity Technologies
+*
+*/
+/**
 * Returns a Uint8Array of random bytes of the given size.
 */
 function rngRandomData(rng, size) {
@@ -126,121 +134,231 @@ function rngFillRandomData(rng, data) {
 	rng.fillRandomData(data);
 }
 /**
-* Returns a random value that is less than the given upper bound.
-*
-* Uses Lemire's "nearly divisionless" method for generating random
-* integers in an interval. For a detailed explanation, see:
-* https://arxiv.org/abs/1805.10941
-*
-* @param rng - The random number generator to use
-* @param upperBound - The upper bound for the randomly generated value. Must be non-zero.
-* @returns A random value in the range [0, upperBound). Every value in the range is equally likely.
+* Returns a random `u8` value strictly less than `upperBound`.
 */
-function rngNextWithUpperBound(rng, upperBound) {
-	if (upperBound === 0n) throw new Error("upperBound must be non-zero");
-	const bitmask = 18446744073709551615n;
-	let random = rng.nextU64() & bitmask;
-	let m = wideMulU64(random, upperBound);
-	if (m[0] < upperBound) {
-		const t = (bitmask + 1n - upperBound & bitmask) % upperBound;
+function rngNextWithUpperBoundU8(rng, upperBound) {
+	if (upperBound === 0) throw new Error("upperBound must be non-zero");
+	const ub = upperBound & 255;
+	let random = Number(rng.nextU64() & 255n);
+	let m = wideMulU8(random, ub);
+	if (m[0] < ub) {
+		const t = (256 - ub & 255) % ub;
 		while (m[0] < t) {
-			random = rng.nextU64() & bitmask;
-			m = wideMulU64(random, upperBound);
+			random = Number(rng.nextU64() & 255n);
+			m = wideMulU8(random, ub);
 		}
 	}
 	return m[1];
 }
 /**
-* Returns a random 32-bit value that is less than the given upper bound.
-* This matches Rust's behavior when called with u32 type.
-*
-* Uses Lemire's "nearly divisionless" method with 32-bit arithmetic.
-*
-* @param rng - The random number generator to use
-* @param upperBound - The upper bound for the randomly generated value. Must be non-zero and fit in u32.
-* @returns A random u32 value in the range [0, upperBound).
+* Returns a random `u16` value strictly less than `upperBound`.
+*/
+function rngNextWithUpperBoundU16(rng, upperBound) {
+	if (upperBound === 0) throw new Error("upperBound must be non-zero");
+	const ub = upperBound & 65535;
+	let random = Number(rng.nextU64() & 65535n);
+	let m = wideMulU16(random, ub);
+	if (m[0] < ub) {
+		const t = (65536 - ub & 65535) % ub;
+		while (m[0] < t) {
+			random = Number(rng.nextU64() & 65535n);
+			m = wideMulU16(random, ub);
+		}
+	}
+	return m[1];
+}
+/**
+* Returns a random `u32` value strictly less than `upperBound`.
 */
 function rngNextWithUpperBoundU32(rng, upperBound) {
 	if (upperBound === 0) throw new Error("upperBound must be non-zero");
-	const upperBoundU32 = upperBound >>> 0;
-	const bitmask = 4294967295;
-	let random = Number(rng.nextU64() & BigInt(bitmask));
-	let m = wideMulU32(random, upperBoundU32);
-	if (Number(m[0]) < upperBoundU32) {
-		const t = (bitmask + 1 - upperBoundU32 >>> 0) % upperBoundU32;
+	const ub = upperBound >>> 0;
+	let random = Number(rng.nextU64() & 4294967295n);
+	let m = wideMulU32(random, ub);
+	if (Number(m[0]) < ub) {
+		const t = (4294967296 - ub >>> 0) % ub;
 		while (Number(m[0]) < t) {
-			random = Number(rng.nextU64() & BigInt(bitmask));
-			m = wideMulU32(random, upperBoundU32);
+			random = Number(rng.nextU64() & 4294967295n);
+			m = wideMulU32(random, ub);
 		}
 	}
 	return Number(m[1]);
 }
 /**
-* Returns a random value within the specified range [start, end) using 32-bit arithmetic.
-* This matches Rust's behavior when called with i32 types.
-*
-* @param rng - The random number generator to use
-* @param start - The lower bound (inclusive) as i32
-* @param end - The upper bound (exclusive) as i32
-* @returns A random i32 value within the bounds
+* Returns a random `u64` value strictly less than `upperBound`.
 */
-function rngNextInRangeI32(rng, start, end) {
-	if (start >= end) throw new Error("start must be less than end");
-	const startI32 = start | 0;
-	const delta = toMagnitude((end | 0) - startI32, 32);
-	if (delta === 4294967295) return rng.nextU32() | 0;
-	return startI32 + rngNextWithUpperBoundU32(rng, delta) | 0;
+function rngNextWithUpperBoundU64(rng, upperBound) {
+	if (upperBound === 0n) throw new Error("upperBound must be non-zero");
+	const mask64 = 18446744073709551615n;
+	const ub = upperBound & mask64;
+	let random = rng.nextU64() & mask64;
+	let m = wideMulU64(random, ub);
+	if (m[0] < ub) {
+		const t = (mask64 + 1n - ub & mask64) % ub;
+		while (m[0] < t) {
+			random = rng.nextU64() & mask64;
+			m = wideMulU64(random, ub);
+		}
+	}
+	return m[1];
 }
 /**
-* Returns a random value within the specified range [start, end).
+* Alias of `rngNextWithUpperBoundU64`. Kept for API backwards compatibility.
 *
-* @param rng - The random number generator to use
-* @param start - The lower bound (inclusive)
-* @param end - The upper bound (exclusive)
-* @returns A random value within the bounds of the range
+* @deprecated Prefer the explicit-width name `rngNextWithUpperBoundU64`.
 */
-function rngNextInRange(rng, start, end) {
+const rngNextWithUpperBound = rngNextWithUpperBoundU64;
+function fromU64ThrowsIfAbove(value, max) {
+	if (value > max) throw new Error("from_u64 conversion overflow");
+	return value;
+}
+/** Random `u8` in the half-open range [start, end). */
+function rngNextInRangeU8(rng, start, end) {
+	if (start >= end) throw new Error("start must be less than end");
+	const lo = start & 255;
+	const delta = (end & 255) - lo & 255;
+	if (delta === 255) return Number(fromU64ThrowsIfAbove(rng.nextU64(), 255n));
+	return lo + rngNextWithUpperBoundU8(rng, delta) & 255;
+}
+/** Random `u16` in the half-open range [start, end). */
+function rngNextInRangeU16(rng, start, end) {
+	if (start >= end) throw new Error("start must be less than end");
+	const lo = start & 65535;
+	const delta = (end & 65535) - lo & 65535;
+	if (delta === 65535) return Number(fromU64ThrowsIfAbove(rng.nextU64(), 65535n));
+	return lo + rngNextWithUpperBoundU16(rng, delta) & 65535;
+}
+/** Random `u32` in the half-open range [start, end). */
+function rngNextInRangeU32(rng, start, end) {
 	if (start >= end) throw new Error("start must be less than end");
-	const delta = end - start;
-	if (delta === 18446744073709551615n) return rng.nextU64();
-	return start + rngNextWithUpperBound(rng, delta);
+	const lo = start >>> 0;
+	const delta = (end >>> 0) - lo >>> 0;
+	if (delta === 4294967295) return Number(fromU64ThrowsIfAbove(rng.nextU64(), 4294967295n));
+	return lo + rngNextWithUpperBoundU32(rng, delta) >>> 0;
+}
+/** Random `u64` in the half-open range [start, end). */
+function rngNextInRangeU64(rng, start, end) {
+	if (start >= end) throw new Error("start must be less than end");
+	const mask64 = 18446744073709551615n;
+	const delta = end - start & mask64;
+	if (delta === mask64) return rng.nextU64();
+	return start + rngNextWithUpperBoundU64(rng, delta) & mask64;
 }
 /**
-* Returns a random value within the specified closed range [start, end].
+* Alias of `rngNextInRangeU64`. Kept for API backwards compatibility.
 *
-* @param rng - The random number generator to use
-* @param start - The lower bound (inclusive)
-* @param end - The upper bound (inclusive)
-* @returns A random value within the bounds of the range
+* @deprecated Prefer the explicit-width name `rngNextInRangeU64`.
 */
-function rngNextInClosedRange(rng, start, end) {
+const rngNextInRange = rngNextInRangeU64;
+/** Random `i8` in the half-open range [start, end). */
+function rngNextInRangeI8(rng, start, end) {
+	if (start >= end) throw new Error("start must be less than end");
+	const lo = start << 24 >> 24;
+	const delta = toMagnitude((end << 24 >> 24) - lo, 8);
+	if (delta === 255) return Number(fromU64ThrowsIfAbove(rng.nextU64(), 127n));
+	return lo + rngNextWithUpperBoundU8(rng, delta) << 24 >> 24;
+}
+/** Random `i16` in the half-open range [start, end). */
+function rngNextInRangeI16(rng, start, end) {
+	if (start >= end) throw new Error("start must be less than end");
+	const lo = start << 16 >> 16;
+	const delta = toMagnitude((end << 16 >> 16) - lo, 16);
+	if (delta === 65535) return Number(fromU64ThrowsIfAbove(rng.nextU64(), 32767n));
+	return lo + rngNextWithUpperBoundU16(rng, delta) << 16 >> 16;
+}
+/** Random `i32` in the half-open range [start, end). */
+function rngNextInRangeI32(rng, start, end) {
+	if (start >= end) throw new Error("start must be less than end");
+	const lo = start | 0;
+	const delta = toMagnitude((end | 0) - lo, 32);
+	if (delta === 4294967295) return Number(fromU64ThrowsIfAbove(rng.nextU64(), 2147483647n));
+	return lo + rngNextWithUpperBoundU32(rng, delta) | 0;
+}
+/** Random `i64` in the half-open range [start, end). */
+function rngNextInRangeI64(rng, start, end) {
+	if (start >= end) throw new Error("start must be less than end");
+	const delta = toMagnitude64(end - start);
+	const mask64 = 18446744073709551615n;
+	if (delta === mask64) return fromU64ThrowsIfAbove(rng.nextU64(), 9223372036854775807n);
+	const random = rngNextWithUpperBoundU64(rng, delta);
+	return fromMagnitude64(toMagnitude64(start) + random & mask64);
+}
+/** Random `u8` in the closed range [start, end]. */
+function rngNextInClosedRangeU8(rng, start, end) {
+	if (start > end) throw new Error("start must be less than or equal to end");
+	const lo = start & 255;
+	const delta = (end & 255) - lo & 255;
+	if (delta === 255) return Number(fromU64ThrowsIfAbove(rng.nextU64(), 255n));
+	return lo + rngNextWithUpperBoundU8(rng, delta + 1) & 255;
+}
+/** Random `u16` in the closed range [start, end]. */
+function rngNextInClosedRangeU16(rng, start, end) {
+	if (start > end) throw new Error("start must be less than or equal to end");
+	const lo = start & 65535;
+	const delta = (end & 65535) - lo & 65535;
+	if (delta === 65535) return Number(fromU64ThrowsIfAbove(rng.nextU64(), 65535n));
+	return lo + rngNextWithUpperBoundU16(rng, delta + 1) & 65535;
+}
+/** Random `u32` in the closed range [start, end]. */
+function rngNextInClosedRangeU32(rng, start, end) {
+	if (start > end) throw new Error("start must be less than or equal to end");
+	const lo = start >>> 0;
+	const delta = (end >>> 0) - lo >>> 0;
+	if (delta === 4294967295) return Number(fromU64ThrowsIfAbove(rng.nextU64(), 4294967295n));
+	return lo + rngNextWithUpperBoundU32(rng, delta + 1) >>> 0;
+}
+/** Random `u64` in the closed range [start, end]. */
+function rngNextInClosedRangeU64(rng, start, end) {
 	if (start > end) throw new Error("start must be less than or equal to end");
-	const delta = end - start;
-	if (delta === 18446744073709551615n) return rng.nextU64();
-	return start + rngNextWithUpperBound(rng, delta + 1n);
+	const mask64 = 18446744073709551615n;
+	const delta = end - start & mask64;
+	if (delta === mask64) return rng.nextU64();
+	return start + rngNextWithUpperBoundU64(rng, delta + 1n) & mask64;
 }
 /**
-* Returns a random value within the specified closed range [start, end] for i32 values.
-* Convenience function that handles signed 32-bit integers.
+* Alias of `rngNextInClosedRangeU64`. Kept for API backwards compatibility.
 *
-* @param rng - The random number generator to use
-* @param start - The lower bound (inclusive) as i32
-* @param end - The upper bound (inclusive) as i32
-* @returns A random i32 value within the bounds of the range
+* @deprecated Prefer the explicit-width name `rngNextInClosedRangeU64`.
 */
+const rngNextInClosedRange = rngNextInClosedRangeU64;
+/** Random `i8` in the closed range [start, end]. */
+function rngNextInClosedRangeI8(rng, start, end) {
+	if (start > end) throw new Error("start must be less than or equal to end");
+	const lo = start << 24 >> 24;
+	const delta = toMagnitude((end << 24 >> 24) - lo, 8);
+	if (delta === 255) return Number(fromU64ThrowsIfAbove(rng.nextU64(), 127n));
+	return lo + rngNextWithUpperBoundU8(rng, delta + 1) << 24 >> 24;
+}
+/** Random `i16` in the closed range [start, end]. */
+function rngNextInClosedRangeI16(rng, start, end) {
+	if (start > end) throw new Error("start must be less than or equal to end");
+	const lo = start << 16 >> 16;
+	const delta = toMagnitude((end << 16 >> 16) - lo, 16);
+	if (delta === 65535) return Number(fromU64ThrowsIfAbove(rng.nextU64(), 32767n));
+	return lo + rngNextWithUpperBoundU16(rng, delta + 1) << 16 >> 16;
+}
+/** Random `i32` in the closed range [start, end]. */
 function rngNextInClosedRangeI32(rng, start, end) {
 	if (start > end) throw new Error("start must be less than or equal to end");
-	const startI32 = start | 0;
-	const delta = toMagnitude((end | 0) - startI32, 32);
-	if (delta === 4294967295) return rng.nextU32() | 0;
-	return startI32 + rngNextWithUpperBoundU32(rng, delta + 1) | 0;
+	const lo = start | 0;
+	const delta = toMagnitude((end | 0) - lo, 32);
+	if (delta === 4294967295) return Number(fromU64ThrowsIfAbove(rng.nextU64(), 2147483647n));
+	return lo + rngNextWithUpperBoundU32(rng, delta + 1) | 0;
+}
+/** Random `i64` in the closed range [start, end]. */
+function rngNextInClosedRangeI64(rng, start, end) {
+	if (start > end) throw new Error("start must be less than or equal to end");
+	const delta = toMagnitude64(end - start);
+	const mask64 = 18446744073709551615n;
+	if (delta === mask64) return fromU64ThrowsIfAbove(rng.nextU64(), 9223372036854775807n);
+	const random = rngNextWithUpperBoundU64(rng, delta + 1n);
+	return fromMagnitude64(toMagnitude64(start) + random & mask64);
 }
 /**
-* Returns a fixed-size array of random bytes.
+* Returns a random fixed-size byte array.
 *
-* @param rng - The random number generator to use
-* @param size - The size of the array to return
-* @returns A Uint8Array of the specified size filled with random bytes
+* Mirrors Rust's `rng_random_array<const N: usize>()` but takes the size at
+* runtime since JavaScript lacks const generics.
 */
 function rngRandomArray(rng, size) {
 	const data = new Uint8Array(size);
@@ -248,33 +366,26 @@ function rngRandomArray(rng, size) {
 	return data;
 }
 /**
-* Returns a random boolean value.
-*
-* @param rng - The random number generator to use
-* @returns A random boolean
+* Returns a random boolean. Mirrors Rust's `rng_random_bool` which tests
+* whether `next_u32()` is a multiple of 2.
 */
 function rngRandomBool(rng) {
 	return (rng.nextU32() & 1) === 0;
 }
 /**
 * Returns a random 32-bit unsigned integer.
-*
-* @param rng - The random number generator to use
-* @returns A random u32 value
 */
 function rngRandomU32(rng) {
 	return rng.nextU32();
 }
-
 //#endregion
 //#region src/secure-random.ts
 /**
-* Detects the crypto API available in the current environment.
-* Works in both Node.js and browser environments.
+* Returns the Web Crypto API for the current environment. Available natively
+* in browsers and in Node.js >= 15 via `globalThis.crypto`.
 */
 function getCrypto() {
-	if (typeof globalThis !== "undefined" && globalThis.crypto !== null && globalThis.crypto !== void 0) return globalThis.crypto;
-	if (typeof globalThis.crypto !== "undefined") return globalThis.crypto;
+	if (typeof globalThis !== "undefined" && globalThis.crypto != null) return globalThis.crypto;
 	throw new Error("No crypto API available in this environment");
 }
 /**
@@ -293,6 +404,9 @@ function fillRandomData(data) {
 }
 /**
 * Returns the next cryptographically strong random 64-bit unsigned integer.
+*
+* This mirrors Rust's module-private `secure_random::next_u64()` and is not
+* re-exported from the package surface (matches Rust `lib.rs` behavior).
 */
 function nextU64() {
 	const data = new Uint8Array(8);
@@ -309,11 +423,12 @@ function nextU64() {
 var SecureRandomNumberGenerator = class {
 	/**
 	* Returns the next random 32-bit unsigned integer.
+	*
+	* Mirrors Rust's `next_u32` impl which returns `next_u64() as u32` —
+	* the low 32 bits of a 64-bit draw.
 	*/
 	nextU32() {
-		const data = new Uint8Array(4);
-		fillRandomData(data);
-		return new DataView(data.buffer).getUint32(0, true) >>> 0;
+		return Number(this.nextU64() & 4294967295n) >>> 0;
 	}
 	/**
 	* Returns the next random 64-bit unsigned integer as a bigint.
@@ -340,7 +455,15 @@ var SecureRandomNumberGenerator = class {
 		fillRandomData(data);
 	}
 };
-
+/**
+* Returns a thread-local cryptographically-strong RNG. Mirrors Rust's
+* `thread_rng()`. In TypeScript there are no thread-locals, so this returns
+* a fresh `SecureRandomNumberGenerator` — every instance backs onto the
+* same Web Crypto source, so the effect is equivalent.
+*/
+function threadRng() {
+	return new SecureRandomNumberGenerator();
+}
 //#endregion
 //#region src/seeded-random.ts
 /**
@@ -376,7 +499,7 @@ function xoshiro256StarStar(state) {
 * WARNING: This is NOT cryptographically secure and should only be used
 * for testing purposes.
 */
-var SeededRandomNumberGenerator = class SeededRandomNumberGenerator {
+var SeededRandomNumberGenerator = class {
 	state;
 	/**
 	* Creates a new seeded random number generator.
@@ -399,15 +522,6 @@ var SeededRandomNumberGenerator = class SeededRandomNumberGenerator {
 		};
 	}
 	/**
-	* Creates a new seeded random number generator from a seed array.
-	* Convenience method that accepts numbers and converts to bigints.
-	*
-	* @param seed - Array of 4 64-bit unsigned integers
-	*/
-	static fromSeed(seed) {
-		return new SeededRandomNumberGenerator(seed);
-	}
-	/**
 	* Returns the next random 64-bit unsigned integer as a bigint.
 	*/
 	nextU64() {
@@ -448,7 +562,8 @@ var SeededRandomNumberGenerator = class SeededRandomNumberGenerator {
 	}
 };
 /**
-* The standard test seed used across all Blockchain Commons implementations.
+* Standard test seed for `makeFakeRandomNumberGenerator`. Module-private to
+* mirror Rust where the equivalent constant lives inside `mod tests`.
 */
 const TEST_SEED = [
 	17295166580085024720n,
@@ -473,29 +588,44 @@ function makeFakeRandomNumberGenerator() {
 function fakeRandomData(size) {
 	return makeFakeRandomNumberGenerator().randomData(size);
 }
-
 //#endregion
 exports.SecureRandomNumberGenerator = SecureRandomNumberGenerator;
 exports.SeededRandomNumberGenerator = SeededRandomNumberGenerator;
-exports.TEST_SEED = TEST_SEED;
 exports.fakeRandomData = fakeRandomData;
 exports.fillRandomData = fillRandomData;
 exports.fromMagnitude = fromMagnitude;
 exports.fromMagnitude64 = fromMagnitude64;
 exports.makeFakeRandomNumberGenerator = makeFakeRandomNumberGenerator;
-exports.nextU64 = nextU64;
 exports.randomData = randomData;
 exports.rngFillRandomData = rngFillRandomData;
 exports.rngNextInClosedRange = rngNextInClosedRange;
+exports.rngNextInClosedRangeI16 = rngNextInClosedRangeI16;
 exports.rngNextInClosedRangeI32 = rngNextInClosedRangeI32;
+exports.rngNextInClosedRangeI64 = rngNextInClosedRangeI64;
+exports.rngNextInClosedRangeI8 = rngNextInClosedRangeI8;
+exports.rngNextInClosedRangeU16 = rngNextInClosedRangeU16;
+exports.rngNextInClosedRangeU32 = rngNextInClosedRangeU32;
+exports.rngNextInClosedRangeU64 = rngNextInClosedRangeU64;
+exports.rngNextInClosedRangeU8 = rngNextInClosedRangeU8;
 exports.rngNextInRange = rngNextInRange;
+exports.rngNextInRangeI16 = rngNextInRangeI16;
 exports.rngNextInRangeI32 = rngNextInRangeI32;
+exports.rngNextInRangeI64 = rngNextInRangeI64;
+exports.rngNextInRangeI8 = rngNextInRangeI8;
+exports.rngNextInRangeU16 = rngNextInRangeU16;
+exports.rngNextInRangeU32 = rngNextInRangeU32;
+exports.rngNextInRangeU64 = rngNextInRangeU64;
+exports.rngNextInRangeU8 = rngNextInRangeU8;
 exports.rngNextWithUpperBound = rngNextWithUpperBound;
+exports.rngNextWithUpperBoundU16 = rngNextWithUpperBoundU16;
 exports.rngNextWithUpperBoundU32 = rngNextWithUpperBoundU32;
+exports.rngNextWithUpperBoundU64 = rngNextWithUpperBoundU64;
+exports.rngNextWithUpperBoundU8 = rngNextWithUpperBoundU8;
 exports.rngRandomArray = rngRandomArray;
 exports.rngRandomBool = rngRandomBool;
 exports.rngRandomData = rngRandomData;
 exports.rngRandomU32 = rngRandomU32;
+exports.threadRng = threadRng;
 exports.toMagnitude = toMagnitude;
 exports.toMagnitude64 = toMagnitude64;
 exports.wideMul = wideMul;
@@ -503,4 +633,5 @@ exports.wideMulU16 = wideMulU16;
 exports.wideMulU32 = wideMulU32;
 exports.wideMulU64 = wideMulU64;
 exports.wideMulU8 = wideMulU8;
+
 //# sourceMappingURL=index.cjs.map