{"id":29703076,"url":"https://github.com/matthewoestreich/js-randomness-predictor","last_synced_at":"2026-01-20T17:57:26.668Z","repository":{"id":299500251,"uuid":"1003249117","full_name":"matthewoestreich/js-randomness-predictor","owner":"matthewoestreich","description":"Predict Math.random output in Node, Chrome, Firefox, and Safari","archived":false,"fork":false,"pushed_at":"2025-07-19T03:31:23.000Z","size":338,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-19T07:52:17.475Z","etag":null,"topics":["chrome","cli","firefox","javascript","math-random","node","npm","predict-math-random","prediction","predictions","predictor","safari","typescript","v8","v8-engine","z3","z3-smt-solver"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matthewoestreich.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-16T21:22:33.000Z","updated_at":"2025-07-19T03:31:27.000Z","dependencies_parsed_at":"2025-07-17T20:31:25.363Z","dependency_job_id":"5fe4266a-a7b0-41a9-9d18-10a302efbfaf","html_url":"https://github.com/matthewoestreich/js-randomness-predictor","commit_stats":null,"previous_names":["matthewoestreich/js-randomness-predictor"],"tags_count":37,"template":false,"template_full_name":null,"purl":"pkg:github/matthewoestreich/js-randomness-predictor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewoestreich%2Fjs-randomness-predictor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewoestreich%2Fjs-randomness-predictor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewoestreich%2Fjs-randomness-predictor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewoestreich%2Fjs-randomness-predictor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matthewoestreich","download_url":"https://codeload.github.com/matthewoestreich/js-randomness-predictor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewoestreich%2Fjs-randomness-predictor/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266682463,"owners_count":23967827,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chrome","cli","firefox","javascript","math-random","node","npm","predict-math-random","prediction","predictions","predictor","safari","typescript","v8","v8-engine","z3","z3-smt-solver"],"created_at":"2025-07-23T13:01:34.334Z","updated_at":"2026-01-20T17:57:26.639Z","avatar_url":"https://github.com/matthewoestreich.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003ca href=\"https://matthewoestreich.github.io/js-randomness-predictor-demos/\"\u003eLive Demo\u003c/a\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/js-randomness-predictor\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/js-randomness-predictor.svg?logo=npm\u0026color=cb0000\" alt=\"npm version\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n# How Does it Work?\n\n[You can read more about how a Predictor works under the hood here.](https://github.com/matthewoestreich/js-randomness-predictor/blob/main/.github/HOW_DOES_IT_WORK.md)\n\n# Important Info\n\n- Having trouble? [See all known issues here](https://github.com/matthewoestreich/js-randomness-predictor/blob/main/.github/KNOWN_ISSUES.md)\n- Use the predictor that matches the environment where the sequence was originally generated. **Meaning, if it came from Chrome, use the Chrome predictor, etc...**.\n- We recommend at least **6 numbers** in the **initial sequence** for **Bun and Safari**, and at least **4 numbers** for **Node, Chrome, Firefox, and Deno**.\n- **Breaking changes in `v2.0.0`!** The V8 Predictor was deprecated! Use the predictor that matches your runtime instead.\n- **In `v3.0.0`, native runtime support for Bun and Deno was added!** You can run the Bun predictor natively in Bun, and the Deno predictor natively in Deno!\n\n# Installation\n\n**Node**\n\n```bash\nnpm i js-randomness-predictor\nyarn add js-randomness-predictor\npnpm add js-randomness-predictor\n# etc...\n```\n\n**Bun**\n\n```bash\nbun add js-randomness-predictor\n```\n\n**Deno**\n\n```bash\ndeno add npm:js-randomness-predictor\n```\n\n# Usage\n\n**ESM**\n\n```js\nimport JSRandomnessPredictor from \"js-randomness-predictor\";\n```\n\n**CJS**\n\n```js\nconst JSRandomnessPredictor = require(\"js-randomness-predictor\");\n```\n\n**Deno**\n\n```js\nimport JSRandomnessPredictor from \"npm:js-randomness-predictor\";\n```\n\n## Frontend/Browser\n\nBrowser usage is a little painful. :grimacing: [Please see here for more info](https://github.com/matthewoestreich/js-randomness-predictor/blob/main/.github/BROWSER_USAGE.md) **THIS GUIDE INCUDES dev servers, eg. the dev servers that `vite`, `webpack`, etc.. offer.**\n\n# Node Predictor\n\n**[See known Node issues here](https://github.com/matthewoestreich/js-randomness-predictor/blob/main/.github/KNOWN_ISSUES.md#node)**\n\nSince 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.**\n\u003cbr/\u003e\n\n## Provide Your Own Sequence\n\n\u003c!-- prettier-ignore --\u003e\n```js\nconst sequence = Array.from({ length: 4 }, Math.random);\nconst nodePredictor = JSRandomnessPredictor.node(sequence);\nconst nextPrediction = await nodePredictor.predictNext();\n// We can programmatically verify since we are running in Node.\nconst isAccurate = nextPrediction === Math.random();\n```\n\n## Automatically Generate Sequence\n\n```js\n// Automatically creates sequence behind the scenes\nconst nodePredictor = JSRandomnessPredictor.node();\nconst nextPrediction = await nodePredictor.predictNext();\n// We can programmatically verify since we are running in Node.\nconst isAccurate = nextPrediction === Math.random();\n```\n\n## Targeting a Different Node.js Version\n\nYou can target Node.js versions that are either **older or newer** than your current version.\n\nFor example:\n\n- If you're currently running Node.js `v24.x.x` but want to predict values generated in `v22.x.x`\n- Or if you're on Node.js `v18.x.x` and want to predict values from a newer version like `v20.x.x`\n\nYou can do this via the `setNodeVersion(version)` method.  \nEssentially, setting the Node.js version tells the predictor: **\"The sequence I provided was generated using Node.js version X.\"**\n\n⚠️ The provided sequence (and expected sequence) must be generated in the matching Node.js version used in `setNodeVersion(...)`!\n\n\u003c!-- prettier-ignore --\u003e\n```js\n// Current Node.js: v24.x.x\nconst nodePredictor = JSRandomnessPredictor.node(sequenceFromNodeV22);\nnodePredictor.setNodeVersion({ major: 22, minor: 0, patch: 0 });\n\nconst expectedPredictionsFromNodeV22 = [/* Copied from Node.js v22 */];\nconst nextPrediction = await nodePredictor.predictNext();\nconst isCorrect = expectedPredictionsFromNodeV22[0] === nextPrediction;\n```\n\n# Bun Predictor\n\n[See known Bun issues here](https://github.com/matthewoestreich/js-randomness-predictor/blob/main/.github/KNOWN_ISSUES.md#bun)\n\n:fire: As of `v3.0.0`, you can run the Bun predictor natively in Bun! :fire:\n\n:construction: Only use \"standalone\" `Math.random()` calls in Bun (for now) - [see here for more info](https://github.com/matthewoestreich/js-randomness-predictor/blob/main/.github/KNOWN_ISSUES.md#bun) :construction:\n\n**If you are running natively in Bun**, you can either provide your own initial sequence, or allow us to create one behind the scenes for you. **If you are using the Bun Predictor outside of Bun**, you must provide a sequence that was generated in Bun and copied over!\n\n## Provide Your Own Sequence\n\n:exclamation: The initial sequence must contain at least 6 elements! :exclamation:\n\n\u003c!-- prettier-ignore --\u003e\n```js\n// Sequence must contain at least 6 elements!\nconst sequence = [\n  Math.random(), Math.random(), Math.random(),\n  Math.random(), Math.random(), Math.random()\n];\nconst bunPredictor = JSRandomnessPredictor.bun(sequence);\nconst nextPrediction = await bunPredictor.predictNext();\n// We can programmatically verify since we are running in Bun.\nconst isAccurate = nextPrediction === Math.random();\n```\n\n## Automatically Generate Sequence\n\n**IMPORTANT** : must be running natively in Bun for this to work!\n\n```js\n// Automatically creates sequence behind the scenes\nconst bunPredictor = JSRandomnessPredictor.bun();\nconst nextPrediction = await bunPredictor.predictNext();\n// We can programmatically verify since we are running in Bun.\nconst isAccurate = nextPrediction === Math.random();\n```\n\n# Deno Predictor\n\n:fire: As of `v3.0.0`, you can run the Deno predictor natively in Deno! :fire:\n\n**If you are running natively in Deno**, you can either provide your own initial sequence, or allow us to create one behind the scenes for you. **If you are using the Deno Predictor outside of Deno**, you must provide a sequence that was generated in Deno and copied over!\n\n## Provide Your Own Sequence\n\n\u003c!-- prettier-ignore --\u003e\n```js\nconst sequence = Array.from({ length: 4 }, Math.random);\nconst denoPredictor = JSRandomnessPredictor.deno(sequence);\nconst nextPrediction = await denoPredictor.predictNext();\n// We can programmatically verify since we are running in Deno.\nconst isAccurate = nextPrediction === Math.random();\n```\n\n## Automatically Generate Sequence\n\n**IMPORTANT** : must be running natively in Deno for this to work!\n\n```js\n// Automatically creates sequence behind the scenes\nconst denoPredictor = JSRandomnessPredictor.deno();\nconst nextPrediction = await denoPredictor.predictNext();\n// We can programmatically verify since we are running in Deno.\nconst isAccurate = nextPrediction === Math.random();\n```\n\n# Chrome Predictor\n\n**[See known Chrome issues here](https://github.com/matthewoestreich/js-randomness-predictor/blob/main/.github/KNOWN_ISSUES.md#chrome)**\n\n```js\nconst chromePredictor = JSRandomnessPredictor.chrome([...]);\nconst nextPrediction = await chromePredictor.predictNext();\n// You'll need to manually verify accuracy.\n```\n\n# Firefox Predictor\n\n**[See known Firefox issues here](https://github.com/matthewoestreich/js-randomness-predictor/blob/main/.github/KNOWN_ISSUES.md#firefox)**\n\n```js\nconst firefoxPredictor = JSRandomnessPredictor.firefox([...]);\nconst nextPrediction = await firefoxPredictor.predictNext();\n// You'll need to manually verify accuracy.\n```\n\n# Safari Predictor\n\n**[See known Safari issues here](https://github.com/matthewoestreich/js-randomness-predictor/blob/main/.github/KNOWN_ISSUES.md#safari)**\n\n:exclamation: The initial sequence must contain at least 6 elements! :exclamation:\n\n:construction: Only use \"standalone\" `Math.random()` calls in Safari (for now) - [see here for more info](https://github.com/matthewoestreich/js-randomness-predictor/blob/main/.github/KNOWN_ISSUES.md#safari) :construction:\n\n```js\n// MUST HAVE AT LEAST 6 ELEMENTS IN SEQUENCE!\nconst sequence = [...];\nconst safariPredictor = JSRandomnessPredictor.safari(sequence);\nconst nextPrediction = await safariPredictor.predictNext();\n// You'll need to manually verify accuracy.\n```\n\n# Command Line Interface\n\n## Important info\n\n- Each number in the sequence should be separated by a space\n- Each flag has a shorthand equivalent\n\n```bash\n# To get full list of options\njs-randomness-predictor --help\n\n# You can use shorthand for flags.\njs-randomness-predictor\n  -e \u003cenvironment\u003e\n  [-v \u003cenvironment_version\u003e]\n  [-s \u003csequence...\u003e]\n  [-p \u003cnum_predictions\u003e]\n  [-x \u003cexport_path\u003e]\n  [-f \u003cforce_overwrite_export_file_or_export_path_creation\u003e]\n```\n\n## Global Usage\n\nTo make the CLI accessible system-wide, install this package globally using the appropriate global flag for your package manager.\n\n```bash\nnpm i -g js-randomness-predictor\n```\n\n## Non-Global Usage\n\nYou'll need to manually specify the path within a project that has this package installed.\n\n```bash\n# Pretend we are in a project that has this package installed.\n$ node_modules/.bin/js-randomness-predictor [options]\n```\n\n## Choosing a Runtime\n\nBy default, we execute the CLI in Node. If you would like, you can choose to execcute the CLI in Bun or Deno as well.\n\n- If you choose to run the CLI in Bun, you are not required to provide a `--sequence` if `--environment bun` as well\n- If you choose to run the CLI in Deno, you are not required to provide a `--sequence` if `--environment deno` as well\n- You'll need to set an env variable called `JSRP_RUNTIME` to be `bun`, `deno`, or `node` (is `node` by default)\n\n```bash\n# This will use the Bun runtime to run the CLI\n$ JSRP_RUNTIME=bun js-randomness-predictor -e bun # `--sequence` not required\n$ JSRP_RUNTIME=bun js-randomness-predictor -e deno # ERROR `--sequence` IS required\n\n# This will use the Deno runtime to run the CLI\n$ JSRP_RUNTIME=deno js-randomness-predictor -e deno # `--sequence` not required\n$ JSRP_RUNTIME=deno js-randomness-predictor -e bun # ERROR `--sequence` IS required\n\n# This will use the Node runtime to run the CLI\n$ js-randomness-predictor [args]\n```\n\n**Windows is a little different**\n\n```shell\n# Via 'cmd'\nC:\\\u003eset JSRP_RUNTIME=bun \u0026\u0026 js-randomness-predictor [...]\n```\n\n```powershell\n# Via 'PowerShell'\nPS C:\\\u003e $env:JSRP_RUNTIME = \"bun\" ; js-randomness-predictor [...]\n```\n\n## Export Predictor Results\n\nIf you want to export results to a file you can use the `--export` (or `-x`) switch. to provide an export path.\n\n- Export path is **relative to the current working directory** (the directory where you are currently running the CLI from)\n- The **provided path** must be to a **.json file**\n- If the **provided file already exists** we do not overwrite it, **unless the `--force` switch is used**\n- If the **full path** you provided **does not exist,** we do not create it, **unless the `--force` switch is used**\n\n## CLI Examples\n\n### Node\n\nWhen no `--sequence` is provided, a sequence will be generated automatically based on the current runtime.\n\n```bash\n# Auto-generate sequence\n$ js-randomness-predictor --environment node\n\n# Provide your own sequence and prediction count\n$ js-randomness-predictor --environment node --sequence 1 2 3 4\n$ js-randomness-predictor --environment node --sequence 1 2 3 4 --predictions 15\n```\n\n#### Targeting a Different Node.js Version\n\nYou can target Node.js versions that are either **older or newer** than your current version.\n\nFor example:\n\n- If you're currently running Node.js `v24.x.x` but want to predict values generated in `v22.x.x`\n- Or if you're on Node.js `v18.x.x` and want to predict values from a newer version like `v20.x.x`\n\nYou can do this using the `--env-version` (or `-v`) flag.  \nEssentially, this flag tells the predictor: **\"The sequence I provided was generated using Node.js version X.\"**\n\n⚠️ Only the **major version number is needed** for `--env-version` value.\n\n```bash\n# Specify environment version explicitly\n$ js-randomness-predictor --environment node --env-version 22 --sequence 1 2 3 4\n\n# Shorthand version\n$ js-randomness-predictor -e node -v 22 -s 1 2 3 4\n```\n\n⚠️ If you use `--env-version` with a version different from your current Node.js version, the `--sequence` flag is **required**:\n\n```bash\n# Current Node.js: v24.2.0\n$ js-randomness-predictor -e node -v 22 # ERROR!\n```\n\n### Chrome\n\nIf the `--env-version` flag is provided and the `--environment` flag is not `node`, the `--env-version` flag is ignored!\n\n```bash\n# Output 10 predictions by default\n$ js-randomness-predictor --environment chrome --sequence 1 2 3 4\n# Output 5 predictions\n$ js-randomness-predictor --environment chrome --sequence 1 2 3 4 --predictions 5\n# --env-version (-v) ignored\n$ js-randomness-predictor -e chrome -v 23 -s 1 2 3 4\n```\n\n### Firefox\n\nIf the `--env-version` flag is provided and the `--environment` flag is not `node`, the `--env-version` flag is ignored!\n\n```bash\n# Output 10 predictions by default\n$ js-randomness-predictor --environment firefox --sequence 1 2 3 4\n# Output 5 predictions\n$ js-randomness-predictor --environment firefox --sequence 1 2 3 4 --predictions 5\n# --env-version (-v) ignored\n$ js-randomness-predictor -e firefox -v 23 -s 1 2 3 4\n```\n\n### Safari\n\nIf the `--env-version` flag is provided and the `--environment` flag is not `node`, the `--env-version` flag is ignored!\n\n```bash\n# Output 10 predictions by default\n$ js-randomness-predictor --environment safari --sequence 1 2 3 4\n# Output 5 predictions\n$ js-randomness-predictor --environment safari --sequence 1 2 3 4 --predictions 5\n# --env-version (-v) ignored\n$ js-randomness-predictor -e safari -v 23 -s 1 2 3 4\n```\n\n### Bun\n\nIf the `--env-version` flag is provided and the `--environment` flag is not `node`, the `--env-version` flag is ignored!\n\n```bash\n# Output 10 predictions by default\n$ js-randomness-predictor --environment bun --sequence 1 2 3 4\n# Output 5 predictions\n$ js-randomness-predictor --environment bun --sequence 1 2 3 4 --predictions 5\n# --env-version (-v) ignored\n$ js-randomness-predictor -e bun -v 23 -s 1 2 3 4\n```\n\n### Deno\n\nIf the `--env-version` flag is provided and the `--environment` flag is not `node`, the `--env-version` flag is ignored!\n\n```bash\n# Output 10 predictions by default\n$ js-randomness-predictor --environment deno --sequence 1 2 3 4\n# Output 5 predictions\n$ js-randomness-predictor --environment deno --sequence 1 2 3 4 --predictions 5\n# --env-version (-v) ignored\n$ js-randomness-predictor -e deno -v 23 -s 1 2 3 4\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatthewoestreich%2Fjs-randomness-predictor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatthewoestreich%2Fjs-randomness-predictor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatthewoestreich%2Fjs-randomness-predictor/lists"}