just-my-luck

    3.0.0 • Public • Published

    JustMyLuck

    A collection of utility functions for working with randomness.

    setup

    npm

    npm i just-my-luck

    ES module

    import JustMyLuck from 'just-my-luck';

    Node

    let JustMyLuck = require('just-my-luck');

    browser

    <script src="https://unpkg.com/just-my-luck"></script>

    The module is globally available as JustMyLuck.

    members

    static properties

    .random = Math.random


    .MersenneTwister(seed)

    The implementation of the Mersenne Twister pseudo-random number generator.

    argument description
    seed A number as the initial seed.

    Returns the pseudo-random number generator as a function.

    let random = JustMyLuck.MersenneTwister(835);
    console.log(random()); // => 0.7212939869047637
    console.log(random()); // => 0.2532498844651273

    .lowerCasedAlphabetic = 'abcdefghijklmnopqrstuvwxyz'


    .upperCasedAlphabetic = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'


    .alphabetic = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'


    .numeric = '0123456789'


    .lowerCasedAlphanumeric = 'abcdefghijklmnopqrstuvwxyz0123456789'


    .upperCasedAlphanumeric = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'


    .alphanumeric = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'

    constructor

    new JustMyLuck(random)

    argument description
    random A function that returns a float greater than or equal to 0 and less than 1.
    let seed = Date.now();
    let luck1 = new JustMyLuck(JustMyLuck.MersenneTwister(seed));
    let luck2 = new JustMyLuck(JustMyLuck.MersenneTwister(seed));
    let integer1 = luck1.integer(-2, 2, true);
    let integer2 = luck2.integer(-2, 2, true);
    console.log(integer1 === integer2); // => true;

    instance properties

    .random

    The pseudo-random number generator.

    static and instance methods

    .chance(p)

    Tests the chance with a probability.

    argument description
    p A number as the probability.

    Returns a boolean.

    let x = JustMyLuck.chance(0.38);
    // => either true (38%) or false (62%)
    console.log(JustMyLuck.chance(-Infinity)); // => false
    console.log(JustMyLuck.chance(-1.57)); // => false
    console.log(JustMyLuck.chance(0)); // => false
     
    console.log(JustMyLuck.chance(1)); // => true
    console.log(JustMyLuck.chance(42)); // => true
    console.log(JustMyLuck.chance(Infinity)); // => true

    .boolean()

    Generates a boolean.

    Returns the generated boolean.

    let boolean = JustMyLuck.boolean();
    // => either true or false

    .booleanWeighted(weight)

    Generates a boolean using a weighted probability.

    argument description
    weight A number as the weighted probability.

    Returns the generated boolean.

    let boolean = JustMyLuck.booleanWeighted(3);
    // => either true (75%) or false (25%)
    console.log(JustMyLuck.booleanWeighted(-1.57)); // => false
    console.log(JustMyLuck.booleanWeighted(0)); // => false
     
    console.log(JustMyLuck.booleanWeighted(Infinity)); // => true

    .float(min, max, inclusive = false)

    Generates a float within a range.

    argument description
    min A number as the inclusive minimum.
    max A number as the exclusive maximum.
    inclusive If true, the maximum is inclusive.

    Returns the generated float.

    let float = JustMyLuck.float(0.4, 2.7);
    // => a float greater than or equal to 0.4 and less than 2.7
    let float = JustMyLuck.float(0.4, 2.7, true);
    // => a float greater than or equal to 0.4 and less than or equal to 2.7
    let float = 6.5;
    console.log(JustMyLuck.float(float, float, true) === float); // => true

    .integer(min, max, inclusive = false)

    Generates an integer within a range.

    argument description
    min A number as the inclusive minimum.
    max A number as the exclusive maximum.
    inclusive If true, the maximum is inclusive.

    Returns the generated integer.

    let integer = JustMyLuck.integer(2, 11);
    // => an integer greater than or equal to 2 and less than 11
    let integer = JustMyLuck.integer(2, 11, true);
    // => an integer greater than or equal to 2 and less than or equal to 11
    console.log(JustMyLuck.integer(4.3, 6.5) === 5); // => true

    .string(alphabet, length)

    Generates a string using an alphabet.

    argument description
    alphabet An array-like or iterable object of characters as the alphabet.
    length A number as the length of the string to generate.

    Returns the generated string.

    let string = JustMyLuck.string(JustMyLuck.alphabetic, JustMyLuck.integer(8, 16, true));
    // => e.g. 'eFEgkjWzTsTmA'

    .date(min, max, inclusive = false)

    Generates a Date instance within a range.

    argument description
    min A Date instance as the inclusive minimum.
    max A Date instance as the exclusive maximum.
    inclusive If true, the maximum is inclusive.

    Returns the generated Date instance.

    let date = JustMyLuck.date(new Date('01 Jan 1970'), new Date('04 Dec 1995'));
    // => e.g. '1989-08-26T01:02:17.622Z'
    let date = new Date('04 Dec 1995');
    console.log(JustMyLuck.date(date, date, true).getTime() === date.getTime()); // => true

    .pick(collection)

    Picks a value from a collection.

    argument description
    collection An array-like or iterable object to pick from.

    Returns the picked value.

    let value = JustMyLuck.pick(['a', 'b', 'c']);
    // => either 'a', 'b' or 'c'

    .pickWeighted(weightedCollection)

    Picks a value from a collection using a weighted probability.

    argument description
    weightedCollection An array-like or iterable object of value-weight pairs. A value-weight pair is an array where the first item is the value and the second item is a number as the weighted probability for this value to be picked.

    Returns the picked value.

    let value = JustMyLuck.pickWeighted([['a', 3.3], ['b', 0.7], ['c', 1]]);
    // => either 'a' (66%), 'b' (14%) or 'c' (20%)
    let value = JustMyLuck.pickWeighted([['a', Infinity], ['b', 1], ['c', 1]]);
    // => always 'a'
    let value = JustMyLuck.pickWeighted([['a', 0], ['b', 1], ['c', 1]]);
    // => either 'b' or 'c'

    .pickIndex(array)

    Picks an index from an array.

    argument description
    array An array-like object to pick the index from.

    Returns the picked index.

    let index = JustMyLuck.pickIndex(['a', 'b', 'c']);
    // => either 0, 1 or 2

    .pickCombination(collection, count)

    Picks a combination of values without repetition from a collection. Preserves the order of the values.

    argument description
    collection An array-like or iterable object to pick from.
    count A number as the count of the values to pick.

    Returns the picked values as an array.

    let values = JustMyLuck.pickCombination(['a', 'b', 'c', 'd', 'e'], 3);
    // => e.g. ['a', 'b', 'd']

    .pickCombinationWeighted(weightedCollection, count)

    Picks a combination of values without repetition from a collection using a weighted probability. Preserves the order of the values.

    argument description
    weightedCollection An array-like or iterable object of value-weight pairs. A value-weight pair is an array where the first item is the value and the second item is a number as the weighted probability for this value to be picked.
    count A number as the count of the values to pick.

    Returns the picked values as an array.

    let values = JustMyLuck.pickCombinationWeighted([['a', 2], ['b', 7], ['c', 8], ['d', 5], ['e', 8]], 3);
    // => e.g. ['a', 'c', 'e']
    let values = JustMyLuck.pickCombinationWeighted([['a', Infinity], ['b', 1], ['c', 0], ['d', 1], ['e', Infinity]], 3);
    // => 'a' and 'e' are always included, 'c' is never included

    .pickPermutation(collection, count)

    Picks a permutation of values without repetition from a collection.

    argument description
    collection An array-like or iterable object to pick from.
    count A number as the count of the values to pick.

    Returns the picked values as an array.

    let values = JustMyLuck.pickPermutation(['a', 'b', 'c', 'd', 'e'], 3);
    // => e.g. ['b', 'd', 'a']

    .pickPermutationWeighted(weightedCollection, count)

    Picks a permutation of values without repetition from a collection using a weighted probability.

    argument description
    weightedCollection An array-like or iterable object of value-weight pairs. A value-weight pair is an array where the first item is the value and the second item is a number as the weighted probability for this value to be picked.
    count A number as the count of the values to pick.

    Returns the picked values as an array.

    let values = JustMyLuck.pickPermutationWeighted([['a', 2], ['b', 7], ['c', 8], ['d', 5], ['e', 8]], 3);
    // => e.g. ['c', 'e', 'a']
    let values = JustMyLuck.pickPermutationWeighted([['a', Infinity], ['b', 1], ['c', 0], ['d', 1], ['e', Infinity]], 3);
    // => 'a' and 'e' are always included, 'c' is never included

    .pickMulticombination(collection, count)

    Picks a combination of values with repetition from a collection. Preserves the order of the values.

    argument description
    collection An array-like or iterable object to pick from.
    count A number as the count of the values to pick.

    Returns the picked values as an array.

    let values = JustMyLuck.pickMulticombination(['a', 'b'], 8);
    // => e.g. ['a', 'a', 'a', 'a', 'a', 'b', 'b', 'b']

    .pickMulticombinationWeighted(weightedCollection, count)

    Picks a combination of values with repetition from a collection using a weighted probability. Preserves the order of the values.

    argument description
    weightedCollection An array-like or iterable object of value-weight pairs. A value-weight pair is an array where the first item is the value and the second item is a number as the weighted probability for this value to be picked.
    count A number as the count of the values to pick.

    Returns the picked values as an array.

    let values = JustMyLuck.pickMulticombinationWeighted([['a', 1], ['b', 3]], 8);
    // => e.g. ['a', 'b', 'b', 'b', 'b', 'b', 'b', 'b']
    let values = JustMyLuck.pickMulticombinationWeighted([['a', Infinity], ['b', 1]], 4);
    // => ['a', 'a', 'a', 'a']
    let values = JustMyLuck.pickMulticombinationWeighted([['a', 0], ['b', 1]], 4);
    // => ['b', 'b', 'b', 'b']

    .pickMultipermutation(collection, count)

    Picks a permutation of values with repetition from a collection.

    argument description
    collection An array-like or iterable object to pick from.
    count A number as the count of the values to pick.

    Returns the picked values as an array.

    let values = JustMyLuck.pickMultipermutation(['a', 'b'], 8);
    // => e.g. ['a', 'a', 'b', 'b', 'a', 'a', 'b', 'a']

    .pickMultipermutationWeighted(weightedCollection, count)

    Picks a permutation of values with repetition from a collection using a weighted probability.

    argument description
    weightedCollection An array-like or iterable object of value-weight pairs. A value-weight pair is an array where the first item is the value and the second item is a number as the weighted probability for this value to be picked.
    count A number as the count of the values to pick.

    Returns the picked values as an array.

    let values = JustMyLuck.pickMultipermutationWeighted([['a', 1], ['b', 3]], 8);
    // => e.g. ['b', 'b', 'b', 'a', 'b', 'b', 'b', 'b']
    let values = JustMyLuck.pickMultipermutationWeighted([['a', Infinity], ['b', 1]], 4);
    // => ['a', 'a', 'a', 'a']
    let values = JustMyLuck.pickMultipermutationWeighted([['a', 0], ['b', 1]], 4);
    // => ['b', 'b', 'b', 'b']

    .shuffle(collection)

    Shuffles a collection.

    argument description
    collection An array-like or iterable object to shuffle.

    Returns the shuffled collection as an array.

    let values = JustMyLuck.shuffle([1, 2, 3, 4, 5]);
    // => e.g. [4, 3, 2, 5, 1]

    .shuffleInPlace(array)

    Shuffles an array in place.

    argument description
    array An array-like object to shuffle.

    Returns the same array but shuffled.

    plugins

    Write your own plugins to extend the library.

    import JustMyLuck from 'just-my-luck';
     
    JustMyLuck.extend({
      color() {
        return `rgb(${[0, 0, 0].map(() => this.integer(0, 255, true)).join(',')})`;
      },
    });

    Install

    npm i just-my-luck

    DownloadsWeekly Downloads

    673

    Version

    3.0.0

    License

    MIT

    Unpacked Size

    24.5 kB

    Total Files

    4

    Last publish

    Collaborators

    • seregpie