fortune-js

    2.2.0 • Public • Published

    Welcome to Fortune-JS 👋

    Version License: MIT

    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 st.lyn4@gmail.com

    🤝 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 st.lyn4@gmail.com.
    This project is MIT licensed.

    Install

    npm i fortune-js

    DownloadsWeekly Downloads

    5

    Version

    2.2.0

    License

    MIT

    Unpacked Size

    82.8 kB

    Total Files

    4

    Last publish

    Collaborators

    • st.lyn4