Quick Start

Always use the predictor that matches the environment where the original sequence was generated.

import JSRandomnessPredictor from "js-randomness-predictor";

const predictor = JSRandomnessPredictor.node();
const nextPrediction = await predictor.predictNext();

console.log(nextPrediction);

Installation

Node

npm i js-randomness-predictor
yarn add js-randomness-predictor
pnpm add js-randomness-predictor

Bun

bun add js-randomness-predictor

Deno

deno add npm:js-randomness-predictor

Usage

ESM

import JSRandomnessPredictor from "js-randomness-predictor";

CJS

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

Deno

import JSRandomnessPredictor from "npm:js-randomness-predictor";

Browser

Browser usage requires additional setup: browser usage guide.

Predictors

| Runtime | Auto Generate Sequence | Sequence Length | Known Issues | | ------------------- | ---------------------- | :-------------: | :-----------------------------------------------------------------------------------------------------------: | | Node | ✅ | 5 | Link | | Bun | ✅ Native Bun only | 6 | Link | | Deno | ✅ Native Deno only | 4 | - | | Chrome | ❌ | 4 | Link | | Firefox | ❌ | 4 | Link | | Safari | ❌ | 6 | Link |

Node

Generate a sequence automatically:

const predictor = JSRandomnessPredictor.node();
const prediction = await predictor.predictNext();
const isAccurate = prediction === Math.random();

Provide your own sequence:

const sequence = Array.from({ length: 5 }, Math.random);
const predictor = JSRandomnessPredictor.node(sequence);
const prediction = await predictor.predictNext();
const isAccurate = prediction === Math.random();

Bun

• If running natively in Bun, a sequence can be generated automatically.
• If using the Bun predictor outside of Bun, you must provide a sequence that was originally generated in Bun.

const predictor = JSRandomnessPredictor.bun();
const prediction = await predictor.predictNext();
const isAccurate = prediction === Math.random();

Provide your own sequence:

const sequence = [Math.random(), Math.random(), Math.random(), Math.random(), Math.random(), Math.random()];
const predictor = JSRandomnessPredictor.bun(sequence);
const prediction = await predictor.predictNext();
const isAccurate = prediction === Math.random();

Deno

• If running natively in Deno, a sequence can be generated automatically.
• If using the Deno predictor outside of Deno, you must provide a sequence that was originally generated in Deno.

const predictor = JSRandomnessPredictor.deno();
const prediction = await predictor.predictNext();
const isAccurate = prediction === Math.random();

Provide your own sequence:

const sequence = Array.from({ length: 4 }, Math.random);
const predictor = JSRandomnessPredictor.deno(sequence);
const prediction = await predictor.predictNext();
const isAccurate = prediction === Math.random();

Chrome

const predictor = JSRandomnessPredictor.chrome(sequence);
const prediction = await predictor.predictNext();

Firefox

const predictor = JSRandomnessPredictor.firefox(sequence);
const prediction = await predictor.predictNext();

Safari

const predictor = JSRandomnessPredictor.safari(sequence);
const prediction = await predictor.predictNext();

Command Line Interface

Installation

Global

# Install globally (system wide)
npm i -g js-randomness-predictor

# Use from anywhere
js-randomness-predictor [options]

Local

# Add as a local project dependency
npm i js-randomness-predictor

# Manually 'path' to CLI
node_modules/.bin/js-randomness-predictor [options]

Basic Usage

# Options
js-randomness-predictor
  -e <environment>
  [-s <sequence...>]
  [-p <num_predictions>]
  [-x <export_path>]
  [-f <force_export>]

# Help
js-randomness-predictor --help

# Version
js-randomness-predictor --version

Runtime Selection

• By default, the CLI executes in Node.js.
• Set environment variable JSRP_RUNTIME to run the CLI in Bun or Deno.

Bun

JSRP_RUNTIME=bun js-randomness-predictor -e bun
JSRP_RUNTIME=bun js-randomness-predictor -e deno --sequence ...

Deno

JSRP_RUNTIME=deno js-randomness-predictor -e deno
JSRP_RUNTIME=deno js-randomness-predictor -e bun --sequence ...

Windows

cmd:

set JSRP_RUNTIME=bun && js-randomness-predictor [...]

PowerShell:

$env:JSRP_RUNTIME = "bun" ; js-randomness-predictor [...]

Exporting Results

Use --export (or -x) to write results to a JSON file.

• Path is relative to the current working directory.
• File must have a .json extension.
• Existing files are not overwritten unless --force is used.
• Missing directories are not created unless --force is used.

Examples

Node

js-randomness-predictor -e node
js-randomness-predictor -e node -s 1 2 3 4 5
js-randomness-predictor -e node -s 1 2 3 4 5 -p 15

Chrome

js-randomness-predictor -e chrome -s 1 2 3 4
js-randomness-predictor -e chrome -s 1 2 3 4 -p 5

Firefox

js-randomness-predictor -e firefox -s 1 2 3 4

Safari

js-randomness-predictor -e safari -s 1 2 3 4 5 6

Bun

js-randomness-predictor -e bun -s 1 2 3 4 5 6

Deno

js-randomness-predictor -e deno -s 1 2 3 4

Contributing

Commit Messages

We follow the Angular style commit message convention. The main commit types are:

| Type | Description | | ---------- | ------------------------- | | feat | New feature | | fix | Bug fix | | perf | Performance improvement | | build | Build system changes | | ci | CI configuration changes | | revert | Revert a previous commit | | docs | Documentation changes | | style | Formatting-only changes | | refactor | Code restructuring | | test | Test changes | | chore | Miscellaneous maintenance |

Important Notes

• Breaking Changes: Must be noted in the commit footer as BREAKING CHANGE: to appear in the changelog.
• Visibility: By default, only feat, fix, perf, and BREAKING CHANGE appear prominently in generated changelogs. Other types are typically ignored unless configured otherwise.

Examples

Feature with scope

feat(cli): add runtime field

Bug fix

fix(core): handle edge case in sequence generation

Breaking change

feat(cli): change output format

BREAKING CHANGE: removed 'actual' field from CLI output

JavaScript Engine Sources

• V8 Source Code
  • V8 source code is part of the Chromium repo
  • Used by Node, Chrome, Deno
• SpiderMonkey Source Code
  • SpiderMonkey source code is part of the Firefox repo
  • Used by Firefox
• JavaScriptCore Source Code
  • JavaScriptCore source code is part of the WebKit repo
  • Used by Safari, Bun