Go Random

Random value generation utilities

• version: 1.0.3
• license: GNU LGPLv3

Installation

npm i go-random

or

yarn add go-random

Usage

ES6

import { randInt } from "go-random"

randInt(3); // => generates an integer between 0 - 3
randInt(1, 3); // => generates an integer between 1 - 3

Node

const { randInt } = require("go-random");

randInt(3); // => generates an integer between 0 - 3
randInt(1, 3); // => generates an integer between 1 - 3

Web browser

<script src="dist/go-random.min.js"></script>
<script>
    const { randInt } = Random;

	randInt(3); // => generates an integer between 0 - 3
	randInt(1, 3); // => generates an integer between 1 - 3
</script>

Documentation

Table of Contents

• randBool
  • Examples
• randInt
  • Parameters
  • Examples
• randFloat
  • Parameters
  • Examples
• randStr
  • Parameters
  • Examples
• randDate
  • Parameters
  • Examples
• randIndex
  • Parameters
  • Examples
• randPick
  • Parameters
  • Examples

randBool

Generates a random boolean value, either true or false.

Examples

randBool(); // => true or false

Returns boolean The randomly generated boolean value.

Meta

• since: 1.0.0

randInt

Generates a random integer between the inclusive min and max bounds. If only one argument is provided, an integer between 0 and the given number is returned. If min or max is not a number, the value is first coerced to a number.

Parameters

• min number The lower bound (inclusive). (optional, default 0)
• max number The upper bound (inclusive). (optional, default Number.MAX_SAFE_INTEGER)

Examples

randInt(); // => an integer between 0 and 9007199254740991

randInt(2); // => an integer between 0 and 2 (0, 1 or 2)

randInt(-1, 2); // => an integer between -1 and 2 (-1, 0, 1 or 2)

• Throws TypeError if min or max is not a valid numeric value (NaN).

Returns number The randomly generated integer.

Meta

• since: 1.0.0

randFloat

Generates a random number between the inclusvie min and max bounds. If only one argument is provided, a number between 0 and the given number is returned. If min or max is not a number, the value is first coerced to a number.

Parameters

• min number The lower bound (inclusive). (optional, default 0)
• max number The upper bound (inclusive). (optional, default Number.MAX_VALUE)
• decimalPlaces number The number of decimal places to have. (optional, default 2)

Examples

randFloat(); // => a number between 0 and 1.7976931348623157E+308

randFloat(2.3); // => a number between 0 and 2.3

randFloat(-1.2, 2.3); // => a number between -1.2 and 2.3

randFloat(-1.2, 2.3, 2); // => a number between -1.2 and 2.3 truncated to 2 decimal places

• Throws TypeError if min or max is not a valid numeric value (NaN).

Returns number The randomly generated floating point number.

Meta

• since: 1.0.0

randStr

Generates a random string of the specified length, optionally using the characters provided. If no characters can be obtained from chars, an empty string is returned. If length is not a number, the value is first coerced to a number.

Parameters

• length number The length of the string. (optional, default DEFAULT_STRING_LENGTH)
• chars (string | Array<string>) The characters to use to construct the random string. (optional, default DEFAULT_STRING_CHARS)

Examples

randStr(); // => a string that has 8 alphanumeric characters 

randStr(5); // => a string that has 5 alphanumeric characters

randStr(5, "0123456789"); // => a string that has 5 digits

• Throws TypeError if length is not a valid numeric value (NaN).
• Throws RangeError if length is a negative number.

Returns string The randomly generated string.

Meta

• since: 1.0.0

randDate

Generates a Date object whose time is between the inclusive min and max bounds. If only one argument is provided, a date between January 1, 1970 UTC and the given date is returned.

Parameters

• min (Date | number | string) The lower bound (inclusive). (optional, default 0)
• max (Date | number | string) The upper bound (inclusive). (optional, default Date.now())

Examples

randDate(); // => a date/time between 1970-01-01 and now

randDate("2012-01-01"); // => a date/time between 1970-01-01 and 2012-01-01

randDate(Date.now(), Date.now() + 3600000); // => a date/time between now and 1 hour from now.

• Throws TypeError if min or max is a not valid date/time value.

Returns Date The randomly selected date within the date range.

Meta

• since: 1.0.0

randIndex

Randomly picks an index of the given collection. The probability of each index being picked can be defined with the ratios. A higher ratio value means a higher probability of being picked.

Parameters

• collection (Array | Object | Iterable | string) The collection to randomly pick an index from.
• ratios (Array<number> | Object<string, number>)? The ratio values that define the probability of the corresponding index is likely to be picked.

Examples

Without ratios - equal probability

// 0, 1 and 2 are all equally likely to be picked.
randIndex(["a", "b", "c"]);

randIndex({1: "a", 2: "b", 3: "c"});

With ratios - defined probabilities

// 0 is twice as likely to be picked than 1 or 2.
randIndex(["a", "b", "c"], [2, 1, 1]);

randIndex({a: "a", b: "b", c: "c"}, {a: 2, b: 1, c: 1});

Returns any The randomly picked index.

Meta

• since: 1.0.0

randPick

Randomly picks an item from the given collection. The probability of each item being picked can be defined with the ratios. A higher ratio value means a higher probability of being picked.

Parameters

• collection (Array | Object | Iterable | string) The collection to randomly pick an item from.
• ratios (Array<number> | Object<string, number>)? The ratio values that define the probability of each item at the corresponding index is likely to be picked.

Examples

Without ratios - equal probability

// "a", "b" and "c" are all equally likely to be picked.
randPick(["a", "b", "c"]);

randPick({1: "a", 2: "b", 3: "c"});

With ratios - defined probabilities

// "a" is twice as likely to be returned than "b" or "c".
randPick(["a", "b", "c"], [2, 1, 1]);

randPick({a: "a", b: "b", c: "c"}, {a: 2, b: 1, c: 1});

Returns any The randomly picked item.

Meta

• since: 1.0.0