@bcts/rand 1.0.0-alpha.5

package/dist/index.d.cts

@@ -0,0 +1,315 @@
+//#region src/widening.d.ts
+/**
+ * Wide multiplication result type - returns (low, high) parts.
+ * For a multiplication of two N-bit values, the result is 2N bits
+ * split into two N-bit parts.
+ */
+type WideMulResult = [bigint, bigint];
+/**
+ * Performs wide multiplication for unsigned integers.
+ * Returns (low, high) parts of the full-width result.
+ *
+ * This is equivalent to Rust's widening_mul for unsigned types.
+ */
+declare function wideMul(a: bigint, b: bigint, bits: number): WideMulResult;
+/**
+ * Wide multiplication for 8-bit unsigned integers.
+ * @param a - First 8-bit value
+ * @param b - Second 8-bit value
+ * @returns Tuple of (low 8 bits, high 8 bits)
+ */
+declare function wideMulU8(a: number, b: number): [number, number];
+/**
+ * Wide multiplication for 16-bit unsigned integers.
+ * @param a - First 16-bit value
+ * @param b - Second 16-bit value
+ * @returns Tuple of (low 16 bits, high 16 bits)
+ */
+declare function wideMulU16(a: number, b: number): [number, number];
+/**
+ * Wide multiplication for 32-bit unsigned integers.
+ * @param a - First 32-bit value
+ * @param b - Second 32-bit value
+ * @returns Tuple of (low 32 bits, high 32 bits) as bigints
+ */
+declare function wideMulU32(a: number, b: number): [bigint, bigint];
+/**
+ * Wide multiplication for 64-bit unsigned integers.
+ * @param a - First 64-bit value as bigint
+ * @param b - Second 64-bit value as bigint
+ * @returns Tuple of (low 64 bits, high 64 bits) as bigints
+ */
+declare function wideMulU64(a: bigint, b: bigint): [bigint, bigint];
+//#endregion
+//#region src/magnitude.d.ts
+/**
+ * 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).
+ *
+ * This matches Rust's wrapping_abs() behavior.
+ */
+declare function toMagnitude(value: number, bits: 8 | 16 | 32): number;
+/**
+ * Converts a signed bigint to its unsigned magnitude for 64-bit values.
+ */
+declare function toMagnitude64(value: bigint): bigint;
+/**
+ * Converts an unsigned magnitude back to a signed value.
+ * Simply reinterprets the bits.
+ */
+declare function fromMagnitude(magnitude: number, bits: 8 | 16 | 32): number;
+/**
+ * Converts an unsigned 64-bit magnitude back to a signed bigint.
+ */
+declare function fromMagnitude64(magnitude: bigint): bigint;
+//#endregion
+//#region src/random-number-generator.d.ts
+/**
+ * Interface for random number generators.
+ * This is the TypeScript equivalent of Rust's RandomNumberGenerator trait
+ * which extends RngCore + CryptoRng.
+ *
+ * This is compatible with the RandomNumberGenerator Swift protocol used
+ * in MacOS and iOS, which is important for cross-platform testing.
+ */
+interface RandomNumberGenerator {
+  /**
+   * Returns the next random 32-bit unsigned integer.
+   */
+  nextU32(): number;
+  /**
+   * Returns the next random 64-bit unsigned integer as a bigint.
+   */
+  nextU64(): bigint;
+  /**
+   * Fills the given Uint8Array with random bytes.
+   */
+  fillBytes(dest: Uint8Array): void;
+  /**
+   * Returns a Uint8Array of random bytes of the given size.
+   */
+  randomData(size: number): Uint8Array;
+  /**
+   * Fills the given Uint8Array with random bytes.
+   * Alias for fillBytes for compatibility.
+   */
+  fillRandomData(data: Uint8Array): void;
+}
+/**
+ * Returns a Uint8Array of random bytes of the given size.
+ */
+declare function rngRandomData(rng: RandomNumberGenerator, size: number): Uint8Array;
+/**
+ * Fills the given Uint8Array with random bytes.
+ */
+declare function rngFillRandomData(rng: RandomNumberGenerator, data: Uint8Array): void;
+/**
+ * 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.
+ */
+declare function rngNextWithUpperBound(rng: RandomNumberGenerator, upperBound: bigint): bigint;
+/**
+ * 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).
+ */
+declare function rngNextWithUpperBoundU32(rng: RandomNumberGenerator, upperBound: number): number;
+/**
+ * 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
+ */
+declare function rngNextInRangeI32(rng: RandomNumberGenerator, start: number, end: number): number;
+/**
+ * Returns a random value within the specified range [start, end).
+ *
+ * @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
+ */
+declare function rngNextInRange(rng: RandomNumberGenerator, start: bigint, end: bigint): bigint;
+/**
+ * Returns a random value within the specified closed range [start, end].
+ *
+ * @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
+ */
+declare function rngNextInClosedRange(rng: RandomNumberGenerator, start: bigint, end: bigint): bigint;
+/**
+ * Returns a random value within the specified closed range [start, end] for i32 values.
+ * Convenience function that handles signed 32-bit integers.
+ *
+ * @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
+ */
+declare function rngNextInClosedRangeI32(rng: RandomNumberGenerator, start: number, end: number): number;
+/**
+ * Returns a fixed-size array of random bytes.
+ *
+ * @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
+ */
+declare function rngRandomArray(rng: RandomNumberGenerator, size: number): Uint8Array;
+/**
+ * Returns a random boolean value.
+ *
+ * @param rng - The random number generator to use
+ * @returns A random boolean
+ */
+declare function rngRandomBool(rng: RandomNumberGenerator): boolean;
+/**
+ * Returns a random 32-bit unsigned integer.
+ *
+ * @param rng - The random number generator to use
+ * @returns A random u32 value
+ */
+declare function rngRandomU32(rng: RandomNumberGenerator): number;
+//#endregion
+//#region src/secure-random.d.ts
+/**
+ * Generate a Uint8Array of cryptographically strong random bytes of the given size.
+ */
+declare function randomData(size: number): Uint8Array;
+/**
+ * Fill the given Uint8Array with cryptographically strong random bytes.
+ */
+declare function fillRandomData(data: Uint8Array): void;
+/**
+ * Returns the next cryptographically strong random 64-bit unsigned integer.
+ */
+declare function nextU64(): bigint;
+/**
+ * A random number generator that can be used as a source of
+ * cryptographically-strong randomness.
+ *
+ * Uses the Web Crypto API (crypto.getRandomValues) which is available
+ * in both browsers and Node.js >= 15.
+ */
+declare class SecureRandomNumberGenerator implements RandomNumberGenerator {
+  /**
+   * Returns the next random 32-bit unsigned integer.
+   */
+  nextU32(): number;
+  /**
+   * Returns the next random 64-bit unsigned integer as a bigint.
+   */
+  nextU64(): bigint;
+  /**
+   * Fills the given Uint8Array with random bytes.
+   */
+  fillBytes(dest: Uint8Array): void;
+  /**
+   * Returns a Uint8Array of random bytes of the given size.
+   */
+  randomData(size: number): Uint8Array;
+  /**
+   * Fills the given Uint8Array with random bytes.
+   */
+  fillRandomData(data: Uint8Array): void;
+}
+//#endregion
+//#region src/seeded-random.d.ts
+/**
+ * A random number generator that can be used as a source of deterministic
+ * pseudo-randomness for testing purposes.
+ *
+ * Uses the Xoshiro256** algorithm, which is the same algorithm used by
+ * rand_xoshiro in Rust. This ensures cross-platform compatibility with
+ * the Rust implementation.
+ *
+ * WARNING: This is NOT cryptographically secure and should only be used
+ * for testing purposes.
+ */
+declare class SeededRandomNumberGenerator implements RandomNumberGenerator {
+  private readonly state;
+  /**
+   * Creates a new seeded random number generator.
+   *
+   * The seed should be a 256-bit value, represented as an array of 4 64-bit
+   * integers (as bigints). For the output distribution to look random, the seed
+   * should not have any obvious patterns, like all zeroes or all ones.
+   *
+   * This is not cryptographically secure, and should only be used for
+   * testing purposes.
+   *
+   * @param seed - Array of 4 64-bit unsigned integers as bigints
+   */
+  constructor(seed: [bigint, bigint, bigint, bigint]);
+  /**
+   * 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: [bigint, bigint, bigint, bigint]): SeededRandomNumberGenerator;
+  /**
+   * Returns the next random 64-bit unsigned integer as a bigint.
+   */
+  nextU64(): bigint;
+  /**
+   * Returns the next random 32-bit unsigned integer.
+   */
+  nextU32(): number;
+  /**
+   * Fills the given Uint8Array with random bytes.
+   *
+   * Note: This implementation matches the Rust behavior exactly -
+   * it uses one nextU64() call per byte (taking only the low byte),
+   * which matches the Swift version's behavior.
+   */
+  fillBytes(dest: Uint8Array): void;
+  /**
+   * Returns a Uint8Array of random bytes of the given size.
+   *
+   * This might not be the most efficient implementation,
+   * but it works the same as the Swift version.
+   */
+  randomData(size: number): Uint8Array;
+  /**
+   * Fills the given Uint8Array with random bytes.
+   */
+  fillRandomData(data: Uint8Array): void;
+}
+/**
+ * The standard test seed used across all Blockchain Commons implementations.
+ */
+declare const TEST_SEED: [bigint, bigint, bigint, bigint];
+/**
+ * Creates a seeded random number generator with a fixed seed.
+ * This is useful for reproducible testing across different platforms.
+ */
+declare function makeFakeRandomNumberGenerator(): SeededRandomNumberGenerator;
+/**
+ * Creates a Uint8Array of random data with a fixed seed.
+ * This is useful for reproducible testing.
+ *
+ * @param size - The number of bytes to generate
+ * @returns A Uint8Array of pseudo-random bytes
+ */
+declare function fakeRandomData(size: number): Uint8Array;
+//#endregion
+export { type RandomNumberGenerator, SecureRandomNumberGenerator, SeededRandomNumberGenerator, TEST_SEED, type WideMulResult, fakeRandomData, fillRandomData, fromMagnitude, fromMagnitude64, makeFakeRandomNumberGenerator, nextU64, randomData, rngFillRandomData, rngNextInClosedRange, rngNextInClosedRangeI32, rngNextInRange, rngNextInRangeI32, rngNextWithUpperBound, rngNextWithUpperBoundU32, rngRandomArray, rngRandomBool, rngRandomData, rngRandomU32, toMagnitude, toMagnitude64, wideMul, wideMulU16, wideMulU32, wideMulU64, wideMulU8 };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/widening.ts","../src/magnitude.ts","../src/random-number-generator.ts","../src/secure-random.ts","../src/seeded-random.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/index.d.mts

@@ -0,0 +1,315 @@
+//#region src/widening.d.ts
+/**
+ * Wide multiplication result type - returns (low, high) parts.
+ * For a multiplication of two N-bit values, the result is 2N bits
+ * split into two N-bit parts.
+ */
+type WideMulResult = [bigint, bigint];
+/**
+ * Performs wide multiplication for unsigned integers.
+ * Returns (low, high) parts of the full-width result.
+ *
+ * This is equivalent to Rust's widening_mul for unsigned types.
+ */
+declare function wideMul(a: bigint, b: bigint, bits: number): WideMulResult;
+/**
+ * Wide multiplication for 8-bit unsigned integers.
+ * @param a - First 8-bit value
+ * @param b - Second 8-bit value
+ * @returns Tuple of (low 8 bits, high 8 bits)
+ */
+declare function wideMulU8(a: number, b: number): [number, number];
+/**
+ * Wide multiplication for 16-bit unsigned integers.
+ * @param a - First 16-bit value
+ * @param b - Second 16-bit value
+ * @returns Tuple of (low 16 bits, high 16 bits)
+ */
+declare function wideMulU16(a: number, b: number): [number, number];
+/**
+ * Wide multiplication for 32-bit unsigned integers.
+ * @param a - First 32-bit value
+ * @param b - Second 32-bit value
+ * @returns Tuple of (low 32 bits, high 32 bits) as bigints
+ */
+declare function wideMulU32(a: number, b: number): [bigint, bigint];
+/**
+ * Wide multiplication for 64-bit unsigned integers.
+ * @param a - First 64-bit value as bigint
+ * @param b - Second 64-bit value as bigint
+ * @returns Tuple of (low 64 bits, high 64 bits) as bigints
+ */
+declare function wideMulU64(a: bigint, b: bigint): [bigint, bigint];
+//#endregion
+//#region src/magnitude.d.ts
+/**
+ * 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).
+ *
+ * This matches Rust's wrapping_abs() behavior.
+ */
+declare function toMagnitude(value: number, bits: 8 | 16 | 32): number;
+/**
+ * Converts a signed bigint to its unsigned magnitude for 64-bit values.
+ */
+declare function toMagnitude64(value: bigint): bigint;
+/**
+ * Converts an unsigned magnitude back to a signed value.
+ * Simply reinterprets the bits.
+ */
+declare function fromMagnitude(magnitude: number, bits: 8 | 16 | 32): number;
+/**
+ * Converts an unsigned 64-bit magnitude back to a signed bigint.
+ */
+declare function fromMagnitude64(magnitude: bigint): bigint;
+//#endregion
+//#region src/random-number-generator.d.ts
+/**
+ * Interface for random number generators.
+ * This is the TypeScript equivalent of Rust's RandomNumberGenerator trait
+ * which extends RngCore + CryptoRng.
+ *
+ * This is compatible with the RandomNumberGenerator Swift protocol used
+ * in MacOS and iOS, which is important for cross-platform testing.
+ */
+interface RandomNumberGenerator {
+  /**
+   * Returns the next random 32-bit unsigned integer.
+   */
+  nextU32(): number;
+  /**
+   * Returns the next random 64-bit unsigned integer as a bigint.
+   */
+  nextU64(): bigint;
+  /**
+   * Fills the given Uint8Array with random bytes.
+   */
+  fillBytes(dest: Uint8Array): void;
+  /**
+   * Returns a Uint8Array of random bytes of the given size.
+   */
+  randomData(size: number): Uint8Array;
+  /**
+   * Fills the given Uint8Array with random bytes.
+   * Alias for fillBytes for compatibility.
+   */
+  fillRandomData(data: Uint8Array): void;
+}
+/**
+ * Returns a Uint8Array of random bytes of the given size.
+ */
+declare function rngRandomData(rng: RandomNumberGenerator, size: number): Uint8Array;
+/**
+ * Fills the given Uint8Array with random bytes.
+ */
+declare function rngFillRandomData(rng: RandomNumberGenerator, data: Uint8Array): void;
+/**
+ * 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.
+ */
+declare function rngNextWithUpperBound(rng: RandomNumberGenerator, upperBound: bigint): bigint;
+/**
+ * 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).
+ */
+declare function rngNextWithUpperBoundU32(rng: RandomNumberGenerator, upperBound: number): number;
+/**
+ * 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
+ */
+declare function rngNextInRangeI32(rng: RandomNumberGenerator, start: number, end: number): number;
+/**
+ * Returns a random value within the specified range [start, end).
+ *
+ * @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
+ */
+declare function rngNextInRange(rng: RandomNumberGenerator, start: bigint, end: bigint): bigint;
+/**
+ * Returns a random value within the specified closed range [start, end].
+ *
+ * @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
+ */
+declare function rngNextInClosedRange(rng: RandomNumberGenerator, start: bigint, end: bigint): bigint;
+/**
+ * Returns a random value within the specified closed range [start, end] for i32 values.
+ * Convenience function that handles signed 32-bit integers.
+ *
+ * @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
+ */
+declare function rngNextInClosedRangeI32(rng: RandomNumberGenerator, start: number, end: number): number;
+/**
+ * Returns a fixed-size array of random bytes.
+ *
+ * @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
+ */
+declare function rngRandomArray(rng: RandomNumberGenerator, size: number): Uint8Array;
+/**
+ * Returns a random boolean value.
+ *
+ * @param rng - The random number generator to use
+ * @returns A random boolean
+ */
+declare function rngRandomBool(rng: RandomNumberGenerator): boolean;
+/**
+ * Returns a random 32-bit unsigned integer.
+ *
+ * @param rng - The random number generator to use
+ * @returns A random u32 value
+ */
+declare function rngRandomU32(rng: RandomNumberGenerator): number;
+//#endregion
+//#region src/secure-random.d.ts
+/**
+ * Generate a Uint8Array of cryptographically strong random bytes of the given size.
+ */
+declare function randomData(size: number): Uint8Array;
+/**
+ * Fill the given Uint8Array with cryptographically strong random bytes.
+ */
+declare function fillRandomData(data: Uint8Array): void;
+/**
+ * Returns the next cryptographically strong random 64-bit unsigned integer.
+ */
+declare function nextU64(): bigint;
+/**
+ * A random number generator that can be used as a source of
+ * cryptographically-strong randomness.
+ *
+ * Uses the Web Crypto API (crypto.getRandomValues) which is available
+ * in both browsers and Node.js >= 15.
+ */
+declare class SecureRandomNumberGenerator implements RandomNumberGenerator {
+  /**
+   * Returns the next random 32-bit unsigned integer.
+   */
+  nextU32(): number;
+  /**
+   * Returns the next random 64-bit unsigned integer as a bigint.
+   */
+  nextU64(): bigint;
+  /**
+   * Fills the given Uint8Array with random bytes.
+   */
+  fillBytes(dest: Uint8Array): void;
+  /**
+   * Returns a Uint8Array of random bytes of the given size.
+   */
+  randomData(size: number): Uint8Array;
+  /**
+   * Fills the given Uint8Array with random bytes.
+   */
+  fillRandomData(data: Uint8Array): void;
+}
+//#endregion
+//#region src/seeded-random.d.ts
+/**
+ * A random number generator that can be used as a source of deterministic
+ * pseudo-randomness for testing purposes.
+ *
+ * Uses the Xoshiro256** algorithm, which is the same algorithm used by
+ * rand_xoshiro in Rust. This ensures cross-platform compatibility with
+ * the Rust implementation.
+ *
+ * WARNING: This is NOT cryptographically secure and should only be used
+ * for testing purposes.
+ */
+declare class SeededRandomNumberGenerator implements RandomNumberGenerator {
+  private readonly state;
+  /**
+   * Creates a new seeded random number generator.
+   *
+   * The seed should be a 256-bit value, represented as an array of 4 64-bit
+   * integers (as bigints). For the output distribution to look random, the seed
+   * should not have any obvious patterns, like all zeroes or all ones.
+   *
+   * This is not cryptographically secure, and should only be used for
+   * testing purposes.
+   *
+   * @param seed - Array of 4 64-bit unsigned integers as bigints
+   */
+  constructor(seed: [bigint, bigint, bigint, bigint]);
+  /**
+   * 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: [bigint, bigint, bigint, bigint]): SeededRandomNumberGenerator;
+  /**
+   * Returns the next random 64-bit unsigned integer as a bigint.
+   */
+  nextU64(): bigint;
+  /**
+   * Returns the next random 32-bit unsigned integer.
+   */
+  nextU32(): number;
+  /**
+   * Fills the given Uint8Array with random bytes.
+   *
+   * Note: This implementation matches the Rust behavior exactly -
+   * it uses one nextU64() call per byte (taking only the low byte),
+   * which matches the Swift version's behavior.
+   */
+  fillBytes(dest: Uint8Array): void;
+  /**
+   * Returns a Uint8Array of random bytes of the given size.
+   *
+   * This might not be the most efficient implementation,
+   * but it works the same as the Swift version.
+   */
+  randomData(size: number): Uint8Array;
+  /**
+   * Fills the given Uint8Array with random bytes.
+   */
+  fillRandomData(data: Uint8Array): void;
+}
+/**
+ * The standard test seed used across all Blockchain Commons implementations.
+ */
+declare const TEST_SEED: [bigint, bigint, bigint, bigint];
+/**
+ * Creates a seeded random number generator with a fixed seed.
+ * This is useful for reproducible testing across different platforms.
+ */
+declare function makeFakeRandomNumberGenerator(): SeededRandomNumberGenerator;
+/**
+ * Creates a Uint8Array of random data with a fixed seed.
+ * This is useful for reproducible testing.
+ *
+ * @param size - The number of bytes to generate
+ * @returns A Uint8Array of pseudo-random bytes
+ */
+declare function fakeRandomData(size: number): Uint8Array;
+//#endregion
+export { type RandomNumberGenerator, SecureRandomNumberGenerator, SeededRandomNumberGenerator, TEST_SEED, type WideMulResult, fakeRandomData, fillRandomData, fromMagnitude, fromMagnitude64, makeFakeRandomNumberGenerator, nextU64, randomData, rngFillRandomData, rngNextInClosedRange, rngNextInClosedRangeI32, rngNextInRange, rngNextInRangeI32, rngNextWithUpperBound, rngNextWithUpperBoundU32, rngRandomArray, rngRandomBool, rngRandomData, rngRandomU32, toMagnitude, toMagnitude64, wideMul, wideMulU16, wideMulU32, wideMulU64, wideMulU8 };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/widening.ts","../src/magnitude.ts","../src/random-number-generator.ts","../src/secure-random.ts","../src/seeded-random.ts"],"sourcesContent":[],"mappings":"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"}