A dead simple random number generator. Seedable, repeatable, and fast
## π Table of Contents - [Alea Generator](#alea-generator) - [π Table of Contents](#-table-of-contents) - [π§ About](#-about) - [Install](#install) - [Package Manager](#package-manager) - [CDN](#cdn) - [π§ Running the tests](#-running-the-tests) - [π Usage](#-usage) - [π License and Shoutouts](#-license-and-shoutouts) - [βοΈ Authors](#οΈ-authors) - [π¨ Similar Tools](#-similar-tools) ## π§ About The default javascript random (Math.random()) is slow, inconsistent across browsers and platforms, and lack seedability, customizability, and state. This generator is a simple way to solve all these problems at once, and it manages that at the tiny cost of only a few hundred bytes. Not kilobytes, bytes. It's small, it's fast, and it's feature-rich. What more could you want? ## Install ### Package Manager #### NPM ```sh npm i alea-generator ``` #### PNPM ```sh pnpm add alea-generator ``` #### Yarn ```sh yarn add alea-generator ``` ### CDN #### Skypack For Web and Deno, no install is required! Just put this line at the top of your file: ```typescript import { inflate } from 'https://cdn.skypack.dev/alea-generator'; ``` If you want type support with skypack, follow the directions [here]('https://docs.skypack.dev/skypack-cdn/code/javascript#using-skypack-urls-in-typescript') #### UNPKG ```html ``` And use it like you would any other package from UNPKG ## π§ Running the tests The basic set of tests are in the test script and the coverage script. Just run those using your perferred package manager (npm, yarn, pnpm, etc.) if you want to make sure nothing has broken. ## π Usage Here's the great part: thanks to [microbundle](https://github.com/developit/microbundle), this package supports CJS, UMD, and ESM formats. That means that wherever and however you use this package β in browser or node, with import or require β you _should_ be set, no configuration required. There are two exports from this package: alea and aleaFactory. If you just want to use a higher quality drop in replacement for Math.random, alea is the pick. For the notably expanded functionality, use aleaFactory. ```typescript import { alea as random } from 'alea-generator'; console.log(random()); // 0.6198398587293923 console.log(random()); // 0.0231225231354864 console.log(random()); // 0.9802844453866831 // all outputs will be greater than or equal to 0 and less than 1 ``` ```typescript import { aleaFactory } from 'alea-generator'; /********************************************/ /* Seeding */ /********************************************/ // the aleaFactory is optionally seedable const randomGeneratorNoSeed = aleaFactory(); // the seed can be a number const randomGeneratorWithNumberSeed = aleaFactory(123); // or the seed can be a string const randomGeneratorWithTextSeed = aleaFactory('special seed'); // or any object with a toString method const objectSeed = { num: 45, num2: 47, toString: () => `${objectSeed.num} + ${objectSeed.num2}`, }; const randomGeneratorWithObjectSeed = aleaFactory(objectSeed); // be careful with this, if you haven't implemented a toString method // as it will inherit one from the prototype chain and default to [object Object] /********************************************/ /* Methods */ /********************************************/ const randomGenerator = aleaFactory('1277182878230'); // random is the drop in replacement for Math.random // it will generate numbers greater than or equal to 0 and less than 1 console.log(randomGenerator.random()); // 0.6198398587293923 console.log(randomGenerator.random()); // 0.8385338634252548 // uint32 will generate integers greater than or equal to 0 and less than 2^32 console.log(randomGenerator.uint32()); // 715789690 console.log(randomGenerator.uint32()); // 4250 // Fract53 will generate a 53 bit number between 0 and 1 (like random but higher precision) console.log(randomGenerator.fract53()); // 0.16665777435687268; console.log(randomGenerator.fract53()); // 0.00011322738143160205; // exportState and importState allow for exact state duplication const stateBeforeRunning = randomGenerator.exportState(); console.log(randomGenerator.random()); // 0.7692187615214618 console.log(randomGenerator.random()); // 0.2316584344522553 randomGenerator.importState(stateBeforeRunning); console.log(randomGenerator.random()); // 0.7692187615214618 console.log(randomGenerator.random()); // 0.2316584344522553 const otherGenerator = aleaFactory().importState(stateBeforeRunning); console.log(otherGenerator.random()); // 0.7692187615214618 console.log(otherGenerator.random()); // 0.2316584344522553 ``` ## π License and Shoutouts Distributed under the MIT License. See `LICENSE` for more information. This is a typescript port of an [alea generator for javascript](https://github.com/coverslide/node-alea/) which was itself a packaged version of the implementation by Johannes BaagΓΈe which you can read more about [here](https://web.archive.org/web/20120619002808/http://baagoe.org/en/wiki/Better_random_numbers_for_javascript) ## βοΈ Authors Find me [@illumincrotty](https://github.com/illumincrotty) on github or [@illumincrotty](https://twitter.com/illumincrotty) on twitter ## π¨ Similar Tools If this tool isn't working for you, try one of these: - [ISAAC, A cryptographically secure random number generator]("https://github.com/macmcmeans/isaacCSPRNG") - [The new standard crypto web api for cryptographically secure random numbers](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) - [Prando](https://www.npmjs.com/package/prando)