vrandom

vrandom

An easy-to-use library to make your life easier when working with random numbers or random choices in javascript.

Table of contents

• Installation & Usage
• Docs
• Tests
• Contributing to vrandom
• Creators & Contributors

Installation & Usage

Install the package with npm

npm i vrandom

Import the package where you need it (both commonjs and module syntax supported)

import vrandom from "vrandom"

or

const vrandom = require("vrandom")

Use the function you need by accessing it through the vrandom object

vrandom.flip()

Docs

• flip
• int
• float
• pick
• pickFromStr
• shuffle
• string
• words
• letter
• uppercaseLetter
• lowercaseLetter

flip

Usage:

vrandom.flip()

// possible output: true

It doesn't take any arguments, it returns true 50% of the time and false 50% of the time.

int

Usage:

vrandom.int(min, max, ?inclusive = true);

It takes three arguments: min, max and inclusive

If no third argument is provided inclusive defaults to true.

The first two arguments both HAVE to be integers and max HAS to be greater than min, or it will throw an error.

It returns a random integer between min and max - min and max included IF inclusive is set to true (or not provided).

It returns a random integer between min and max - max excluded IF inclusive is set to false.

Example:

vrandom.int(1, 10)
// will return an integer between 1 and 10 - 10 included
// possible output: 10

vrandom.int(1, 10, false)
// will return an integer between 1 and 10 - 10 NOT included
// possible output: 9
// non-possible output: 10

float

Usage:

vrandom.float(min, max, ?decimals = 2);

It takes 2 arguments, plus 1 optional argument if only two arguments are provided the third argument defaults to 2.

The first and second arguments have to be numbers (floats or ints) the third argument has to be an integer.

The function will return a random floating point number between min and max - min and max INCLUDED. The returned floating point number will have a maximum of 2 decimal places if no third argument is specified.

If a third argument is passed, that will be the maximum number of decimals that the returned floating point number will have. Maximum of 15.

Note: the returned floating point number might have LESS decimals than the number specified but not more.

The function will return an error if: less than 2 arguments are passed, the third argument is greater than 15 or less than 0, if min is greater or equal to max, the third argument is not an integer.

Example:

vrandom.float(0.5, 10.1, 5)
// possible output: 2.47185
// possible output: 10.1
// possible output: 0.5427

pick

Usage:

vrandom.pick(array)

It takes one argument, and it HAS to be an array, if not it will throw an error.

It will return a random element from that array.

Example:

const arr = [1, 2, 3, 4, "hello", "world", true, false]
vrandom.pick(arr)

// possible output: 1

Will return a random element from the array 'arr'

pickFromStr

Usage:

vrandom.pickFromStr(string)

Same as pick, but it takes a string as an argument and returns a random character from that string.

Takes 1 argument, and it needs to be a string, or it will throw an error.

If provided string is empty, it will return an empty string.

Example:

const string = "hello"
vrandom.pickFromStr(string)

// possible output: "e"

Returns random character from a string.

shuffle

Usage:

vrandom.shuffle(array)

It takes one argument, and it HAS to be an array.

It will make a shallow copy of the provided array, and return a new array with the same elements as the provided array, but in (possibly) a different order, every element is shuffled and is assigned a new position (the initial position of the element is included in the possible positions where the element ends up). The original array remains unchanged.

Example:

const arr = [1, 2, "hello", "world", true, false]
vrandom.shuffle(arr)

// possible output: [1, "hello", true, false, 2, "world"]

console.log(arr) // [1, 2, "hello", "world", true, false]

string

Usage:

vrandom.string(size, ?charset = "alphanumeric");

It takes 2 arguments. First argument is the length of the desired output. It needs to be an integer greater than 0, or it will throw an error. Second argument is a string representing the type of charset that should be used to generate output. At the moment there is only 2 possible values:

• "alphanumeric" [0-9a-zA-Z]
• "alphabetic" [a-zA-Z]

If the second argument is omitted it will default to "alphanumeric".

Example:

vrandom.string(5)
// possible output: "Zd5r3"

vrandom.string(5, "alphanumeric")
// possible output: "1zZ3L"

vrandom.string(5, "alphabetic")
// possible output: "LzkAm"
// non-possible output: "1oLL4"

words

Usage:

vrandom.words(size, ?format = "lowercase")

Takes 2 arguments, it return an array of random words.

First argument is the size of the array that will be returned (the number of random words in the output). It needs to be a positive integer, or it will throw an error.

Second argument is optional (it will default to "lowercase" if not passed in). It's the desired format of the individual strings in the returned array. At the moment there is possible options:

• "lowercase"
• "uppercase"
• "capitalized"

If the second argument is passed in, but it doesn't match any of the possible options, it will throw an error.

Example:

vrandom.words(5)
// possible output: ["ability", "main", "farm", "took", "current"]

vrandom.words(5, "lowercase")
// possible output: ["ability", "main", "farm", "took", "current"]

vrandom.words(5, "uppercase")
// possible output: ["ABILITY", "MAIN", "FARM", "TOOK", "CURRENT"]

vrandom.words(5, "capitalized")
// possible output: ["Ability", "Main", "Farm", "Took", "Current"]

letter

Usage:

vrandom.letter()

It doesn't take any arguments, it returns a random letter from the english alphabet. The returned letter can be lowercase OR uppercase.

Example:

vrandom.letter()
// possible output: "a"
// possible output: "A"
// possible output: "m"
// possible output: "Z"

uppercaseLetter

Usage:

vrandom.uppercaseLetter()

It doesn't take any arguments, it returns a random uppercase letter from the english alphabet.

Example:

vrandom.uppercaseLetter()
// possible output: "A"
// possible output: "M"
// possible output: "Z"

lowercaseLetter

Usage:

vrandom.lowercaseLetter()

It doesn't take any arguments, it returns a random lowercase letter from the english alphabet.

Example:

vrandom.lowercaseLetter()
// possible output: "a"
// possible output: "m"
// possible output: "z"

Tests

The library is fully tested. If you are contributing and you are creating a new feature please add tests to it.

How to run tests:

• Clone the repo locally
• Install dependencies

npm i

• run tests

npm t

• run tests and see test coverage

npm run test-coverage

Contributing to vrandom

Steps to contributing:

• Fork the repo and create your branch from master.
• If you've added code that should be tested, add tests.
• If you've changed APIs, update the documentation.
• Ensure the test suite passes npm t
• Make sure your code lints npm run lint
• Issue pull request

The library is fully tested and uses standardjs to format javascript files.

On every pull request two GitHub actions will run:

• Checks if all tests pass
• Checks if js files are formatted correctly

If any of those two Actions fail, the merge won't be possible.

If you want to check if your tests pass run npm t

If you want to check if your files have the right formatting run npm run lint

If your files aren't formatted correctly run npm run lint-fix and standardjs will do the job for you.

Now you are ready to issue that pull request.

Creators & Contributors

• Valerio Cipolla
• kennarddh
• crayola-eater