xoshiro-js

Modern pure-JavaScript implementation of the XoShiRo family of pseudo-random number generators. This library is TypeScript-native, ESM-only, and has zero dependencies.

The implementation and interfaces here are ported directly from the Zig standard library. The unit tests assert identical behavior to Zig's Random interface for generating values, ranges, etc.

Table of Contents

• Install
• Usage
• API
• Testing
• Contributing
• License

Install

npm i xoshiro-js

Usage

import PRNG from "xoshiro-js" // default export is XoShiRo256PlusPlus

const prng = new PRNG(0n)

console.log(prng.range(5, 25)) // 11
console.log(prng.range(5, 25)) // 13
console.log(prng.range(5, 25)) // 12
console.log(prng.range(5, 25)) // 5

API

interface PRNG {
  fill(buffer: Uint8Array): void

  /** random integer 0 <= x < 2^8 */
  getUint8(): number

  /** random integer 0 <= x < 2^16 */
  getUint16(): number

  /** random integer 0 <= x < 2^32 */
  getUint32(): number

  /** random integer 0 <= x < 2^64 */
  getBigUint64(): bigint

  /** Generate a uniformly distributed f32 value in the range [0, 1) */
  getFloat32(): number

  /** Generate a uniformly distributed f64 value in the range [0, 1) */
  getFloat64(): number

  /** random integer min <= x <= max */
  range(min: number, max: number): number
  rangeBigInt(min: bigint, max: bigint): bigint

  /** select a random element of the provided array */
  select<T>(array: readonly T[]): T

  /** shuffle the provided array in-place */
  shuffle<T>(array: T[]): void
}

declare class XoShiRo128Plus implements PRNG {
  constructor(seed?: bigint | number[])
}

declare class XoShiRo128PlusPlus implements PRNG {
  constructor(seed?: bigint | number[])
}

declare class XoShiRo128StarStar implements PRNG {
  constructor(seed?: bigint | number[])
}

declare class XoShiRo256Plus implements PRNG {
  constructor(seed?: bigint | bigint[])
}

declare class XoShiRo256PlusPlus implements PRNG {
  constructor(seed?: bigint | bigint[])
}

declare class XoShiRo256StarStar implements PRNG {
  constructor(seed?: bigint | bigint[])
}

Testing

Tests use AVA and live in the test directory.

npm run test

Contributing

If you have suggestions for additional PRNG interface methods, find a bug, or would like to add more tests, please open an issue to discuss it!

License

MIT © 2025 Joel Gustafson