fortune-js

Welcome to Fortune-JS 👋

About: The library that generates random numbers by 3 ways! Cryptographically strong Fortune? Fast XorShift+? Or maybe something mean? Fast and reliable Mersenne Twister? The choice is yours!

Install

yarn add fortune-js
# or
npm install fortune-js

Usage

const random = require('fortune-js');
// or
// import random from 'fortune-js';

// In real life, you will most likely need only one type generator
const Fortune = random('Fortune');
const MersenneTwister = random('MersenneTwister'); // Or just random();
const XorShift = random('XorShift');

async function main() {
  console.log(await Fortune.random()); // Prints a random number from 0 to 1
}

main();

Bonus

You can also use the randomBytes function to generate a buffer with the desired count of bytes generated by Fortune algorithm:

const randomBytes = require('fortune-js').randomBytes;
// or
// import { randomBytes } from 'fortune-js';

async function main() {
  console.log(await randomBytes(32)); // Prints a Buffer with 32 random bytes
}

main();

Wait... Async?! Really?!

Yes. Just yes. All random data generation functions are asynchronous.

The essence is that in browsers the library uses Web Crypto API (on the page with SSL). This is a native crypto library, like crypto in Node.js.

If you want to use the synchronous version of the library, then look at version 1.x.x. But note that it is supported only in Node.js.

For browsers

If you want to use this library in the browser, simply add the next element to the <header>:

<script src="https://unpkg.com/fortune-js@latest/dist/main.min.js"></script>

And write in your script the following:

const random = window.FortuneJS;

// And then everything is as in the example above

Where does the library work? Everywhere.

Node.js and browsers use native versions of some internal functions, which allows the library work very quickly. In any other environment that does not have a support for node.js Crypto, nor Web Crypto API will be used our implementations on pure JS.

Types of generators

How to choose the generator you need?

1. If you need cryptographic strong random, fast work (in fact, all 3 algorithms are very fast), then your choice is Fortune (this algorithm even uses by Apple since 2019).

2. If you need a faster job, with still a very random selection, you can use the MersenneTwister (default).

3. XorShift also shows even higher speed, but not recommended for use, since there are more interesting algorithms.

API

randomObj.random() - Generates a number between 0 and 1

randomObj.randInt([limit = (0xffffffff - 1)]) - Generates an integer between 0 and limit

randomObj.randFloat([limit = (0xffffffff - 1)]) - Generates a float number between 0 and limit

randomObj.randRange([from = 0], [to = (0xffffffff - 1)]) - Generates an integer between from and to

randomObj.randFloatRange([from = 0], [to = (0xffffffff - 1)]) - Generates a float number between from and to

randomObj.select(array, [n = 1]) - Select n unique (by index) array elements

randomObj.shuffle(array, [copy = true]) - Shuffle the contents of the array. If the copy is true, then the a new array is also created. Otherwise, all operations will be performed on the source array (default).

Fortune only

Fortune.randomBytes([size = 0]) - Get the Buffer with bytes generated by the Fortune algorithm.

Fortune.feed(poolIndex, bytes) - Makes random even more random and safe. The first argument is the index of the pool from 0 to 31. The second - buffer with bytes. Do not use it if you don't know what it is.

Author

👤 Vsevolod Volkov [e-mail]

• Github: @StLyn4

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page. You can also take a look at the contributing guide.

Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2021 Vsevolod Volkov [e-mail].
This project is MIT licensed.