from https://github.com/illumincrotty/alea-random/tree/main

Alea Generator#

npm size-badge Types

A dead simple random number generator. Seedable, repeatable, and fast

📝 Table of Contents#

Alea Generator

🧐 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 #

npm i alea-generator

PNPM #

pnpm add alea-generator

Yarn #

yarn add alea-generator

CDN#

Skypack #

For Web and Deno, no install is required! Just put this line at the top of your file:

import { inflate } from 'https://cdn.skypack.dev/alea-generator';

If you want type support with skypack, follow the directions here

UNPKG #

<script src="https://unpkg.com/alea-generator"></script>

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, 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.

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

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 which was itself a packaged version of the implementation by Johannes Baagøe which you can read more about here

✍️ Authors#

Find me @illumincrotty on github or @illumincrotty on twitter

🔨 Similar Tools#

If this tool isn't working for you, try one of these:

Configure Feed