Important Info

Use the predictor that matches the environment where the sequence was originally generated. Meaning, if it came from Chrome, use the Chrome predictor, etc….
We recommend at least 4 numbers in the initial sequence.
Breaking changes in v2.0.0! The V8 Predictor was deprecated - please use the Node Predictor instead.
See all known issues here

Installation

Use your favorite package manager.

npm i js-randomness-predictor
yarn add js-randomness-predictor
pnpm add js-randomness-predictor
# etc...

Usage

ESM

import JSRandomnessPredictor from "js-randomness-predictor";

CJS

const JSRandomnessPredictor = require("js-randomness-predictor");

V8 Predictor

Deprecated in v2.0. Please use the Node Predictor instead - it works just like the V8 Predictor.

Node Predictor

See known Node issues here

Since we’re running in Node, you can dynamically generate the initial sequence by calling the node() method without any parameters. This will automatically produce a sequence behind the scenes. Alternatively, you can manually provide a sequence if you prefer.

Provide Your Own Sequence

const providedSequence = Array.from({ length: 4 }, Math.random);
// Or...
const providedSequence = [/* copy & paste from REPL */];

const nodePredictor = JSRandomnessPredictor.node(providedSequence);
const nextPrediction = await nodePredictor.predictNext();
// We can programmatically verify since we are running in Node.
const isAccurate = nextPrediction === Math.random();

Automatically Generate Sequence

// Automatically creates sequence behind the scenes
const nodePredictor = JSRandomnessPredictor.node();
const nextPrediction = await nodePredictor.predictNext();
// We can programmatically verify since we are running in Node.
const isAccurate = nextPrediction === Math.random();

Targeting a Different Node.js Version

You can target Node.js versions that are either older or newer than your current version.

For example:

If you’re currently running Node.js v24.x.x but want to predict values generated in v22.x.x
Or if you’re on Node.js v18.x.x and want to predict values from a newer version like v20.x.x

You can do this via the setNodeVersion(version) method.
Essentially, setting the Node.js version tells the predictor: “The sequence I provided was generated using Node.js version X.”

⚠️ The provided sequence (and expected sequence) must be generated in the matching Node.js version used in setNodeVersion(...)!

// Current Node.js: v24.x.x
const nodePredictor = JSRandomnessPredictor.node(sequenceFromNodeV22);
nodePredictor.setNodeVersion({ major: 22, minor: 0, patch: 0 });

const expectedPredictionsFromNodeV22 = [/* Copied from Node.js v22 */];
const nextPrediction = await nodePredictor.predictNext();
const isCorrect = expectedPredictionsFromNodeV22[0] === nextPrediction;

Bun Predictor

Cannot use the Bun predictor natively in Bun because Bun does not support Z3

const bunPredictor = JSRandomnessPredictor.bun([...]);
const nextPrediction = await bunPredictor.predictNext();
// You'll need to manually verify accuracy.

Deno Predictor

Cannot use the Deno predictor natively in Deno because Deno does not support Z3

const denoPredictor = JSRandomnessPredictor.deno([...]);
const nextPrediction = await denoPredictor.predictNext();
// You'll need to manually verify accuracy.

Chrome Predictor

See known Chrome issues here

const chromePredictor = JSRandomnessPredictor.chrome([...]);
const nextPrediction = await chromePredictor.predictNext();
// You'll need to manually verify accuracy.

Firefox Predictor

See known Firefox issues here

const firefoxPredictor = JSRandomnessPredictor.firefox([...]);
const nextPrediction = await firefoxPredictor.predictNext();
// You'll need to manually verify accuracy.

Safari Predictor

See known Safari issues here

const safariPredictor = JSRandomnessPredictor.safari([...]);
const nextPrediction = await safariPredictor.predictNext();
// You'll need to manually verify accuracy.

Command Line Interface

Important info

Each number in the sequence should be separated by a space
Each flag has a shorthand equivalent

# To get full list of options
js-randomness-predictor --help

# You can use shorthand for flags.
js-randomness-predictor
  -e <environment>
  [-v <environment_version>]
  [-s <sequence...>]
  [-p <num_predictions>]
  [-x <export_path>]
  [-f <force_overwrite_export_file_or_export_path_creation>]

Global Usage

To make the CLI accessible system-wide, install this package globally using the appropriate global flag for your package manager.

npm i -g js-randomness-predictor

Non-Global Usage

You’ll need to manually specify the path within a project that has this package installed.

# Pretend we are in a project that has this package installed.
node_modules/.bin/js-randomness-predictor [options]

Export Predictor Results

If you want to export results to a file you can use the --export (or -x) switch. to provide an export path.

Export path is relative to the current working directory (the directory where you are currently running the CLI from)
The provided path must be to a .json file
If the provided file already exists we do not overwrite it, unless the --force switch is used
If the full path you provided does not exist, we do not create it, unless the --force switch is used

CLI Examples

Node

When no --sequence is provided, a sequence will be generated automatically based on the current runtime.

# Auto-generate sequence
js-randomness-predictor --environment node

# Provide your own sequence and prediction count
js-randomness-predictor --environment node --sequence 1 2 3 4
js-randomness-predictor --environment node --sequence 1 2 3 4 --predictions 15

Targeting a Different Node.js Version

You can target Node.js versions that are either older or newer than your current version.

For example:

If you’re currently running Node.js v24.x.x but want to predict values generated in v22.x.x
Or if you’re on Node.js v18.x.x and want to predict values from a newer version like v20.x.x

You can do this using the --env-version (or -v) flag.
Essentially, this flag tells the predictor: “The sequence I provided was generated using Node.js version X.”

⚠️ Only the major version number is needed for --env-version value.

# Specify environment version explicitly
js-randomness-predictor --environment node --env-version 22 --sequence 1 2 3 4

# Shorthand version
js-randomness-predictor -e node -v 22 -s 1 2 3 4

⚠️ If you use --env-version with a version different from your current Node.js version, the --sequence flag is required:

# Current Node.js: v24.2.0
js-randomness-predictor -e node -v 22 # ERROR!