@santi100/random-lib

Santi's Random Number Library

• 📘 Comes with built-in TypeScript definitions
• 🌐 Includes a UMD build
• 🚀 Lightweight and fast
• 👴 Compliant with ECMAScript 3
• 📑 Split in different files (under cjs/) to import just what you need
• 🎨 Includes a wide variety of randomizer functions

API

• function random(max: number, min: number = 0): number; Generate a random integer between min (0 by default) and max.

  Name	Type	Description	Optional?
  max	number	The maximum value.	No
  min?	number	The minimum value. Defaults to 0.	Yes

  Returns a pseudo-random integer between min and max.

• function randomFloat(max: number, min: number = 0): number; Generate a random floating-point number between min (0 by default) and max. Generate a random integer between min (0 by default) and max.

  Name	Type	Description	Optional?	Default
  max	number	The maximum value.	No	N/A
  min?	number	The minimum value. Defaults to 0.	Yes	0

  Returns a pseudo-random floating-point number between min and max.

• function randomFromArray<T = unknown>(array: T[]): T; Returns a random item of array.

  Name	Type	Description	Optional?	Default
  array	number	The maximum value.	No	N/A
  T	type param	The minimum value. Defaults to 0.	Yes	unknown

• function randomIntegers(amount?: number, opts?: RandomArraysOptions): number[]; Returns an array with amount random integers.

  Name	Type	Description	Optional?	Default
  amount	number	The amount of random integers to fill the array with.	Yes	4
  opts	RandomArraysOptions	The shape of the options passed to randomIntegers and randomFloats.	Yes	{}
  opts.max?	number	The maximum value.	Yes	300
  opts.min?	number	The minimum value.	Yes	0

• function randomFloats(amount?: number, opts?: RandomArraysOptions): number[]; Returns an array with amount random floating-point numbers.

  Name	Type	Description	Optional?	Default
  amount	number	The amount of random floating-point numbers to fill the array with.	Yes	4
  opts	RandomArraysOptions	The shape of the options passed to randomIntegers and randomFloats.	Yes	{}
  opts.max?	number	The maximum value.	Yes	300
  opts.min?	number	The minimum value.	Yes	0

• function randomLower(): string; Returns a random lowercase letter.

• function randomUpper(): string; Returns a random uppercase letter.

• function randomLetter(): string; Returns a random letter.

• function randomLowers(amount: number): string[]; Returns amount random lowercase letters.

  Name	Type	Description	Optional?	Default
  amount	number	How many random lowercase letters to return.	No	N/A

• function randomUppers(amount: number): string[]; Returns amount random uppercase letters.

  Name	Type	Description	Optional?	Default
  amount	number	How many random uppercase letters to return.	No	N/A

• function randomLetters(amount: number): string[]; Returns amount random letters.

  Name	Type	Description	Optional?	Default
  amount	number	How many random letters to return.	No	N/A

• function randomDate(minDate: Date, maxDate: Date): Date; Generates a random date between minDate and maxDate.

  Name	Type	Description	Optional?	Default
  minDate	Date	The minimum date to generate a random date from.	No	N/A
  maxDate	Date	The maximum date to generate a random date from.	No	N/A

• function randomDates(minDate: Date, maxDate: Date, amount: number): Date[];

  Generates amount random dates between minDate and maxDate.

  Name	Type	Description	Optional?	Default
  minDate	Date	The minimum date to generate a random date from.	No	N/A
  maxDate	Date	The maximum date to generate a random date from.	No	N/A
  amount	number	The amount of dates to generate.	No	N/A

• function randomBoolean(): boolean; NEW! (since 1.1.5)

  Generates a random boolean value.

• function randomHexColor(): string; NEW! (since 1.1.5)

  Generates a random hex colorcode.

• function randomHexColor(shorthand: boolean): string; NEW! (since 1.1.5)

  Generates a random hex colorcode.

  Name	Type	Description	Optional?	Default
  shorthand	boolean	Whether or not use a 3-character code instead of a 6-character one.	No	N/A

• function randomPhrase(): string; NEW! (since 1.1.5) Generate a random 6-word phrase.

  Keep in mind these phrases have NO GRAMATICAL sense and are generated from a list of random words.

• function randomPhrase(wordCount: number): string; NEW! (since 1.1.5)

  Generate a random phrase with wordCount words.

  Keep in mind these phrases have NO GRAMATICAL sense and are generated from a list of random words.

  Name	Type	Description	Optional?	Default
  wordCount	number	The amount of words to use in the phrase.	No	N/A

• function randomUUID(): string; NEW! (since 1.1.5)

  Generates a pseudo-random UUID v4.

• function randomPhone(countryCode: number): string; NEW! (since 1.1.7)

  Generates a 10-digit random phone number of the form +xx xxx xxxxxxx, where x is a digit.

  Name	Type	Description	Optional?
  countryCode	number	The code of the country to which the number would belong to. Must be between 1 and 999.	No

• function randomPhone(countryCode: number, digitCount: number): string; NEW! (since 1.1.7)

  Generates a random phone number of the form +xx xxx x..., where x is a digit.

  Name	Type	Description	Optional?
  countryCode	number	The code of the country to which the number would belong to. Must be between 1 and 999.	No
  digitCount	number	The amount of digits the phone number must have beside the country code. If bigger than 10, the extra digits will be added to the x... block.	No

Usage

// Import the most basic function...
const { 'default': random } = require('@santi100/random-lib'); // CJS
import random from '@santi100/random-lib'; // ESM/TypeScript

// Or import only the functions you need from the files you need...

// CJS
const random = require('@santi100/random-lib/cjs/random'); 
const randomFromArray = require('@santi100/random-lib/cjs/random-from-array'); 
const randomIntegers = require('@santi100/random-lib/cjs/random-integers'); 
const randomFloats = require('@santi100/random-lib/cjs/random-floats'); 

// TypeScript
import random = require('@santi100/random-lib/cjs/random'); 
import randomFromArray = require('@santi100/random-lib/cjs/random-from-array'); 
import randomIntegers = require('@santi100/random-lib/cjs/random-integers'); 
import randomFloats = require('@santi100/random-lib/cjs/random-floats'); 

// ESM
import random from '@santi100/random-lib/cjs/random'; 
import randomFromArray from '@santi100/random-lib/cjs/random-from-array'; 
import randomIntegers from '@santi100/random-lib/cjs/random-integers'; 
import randomFloats from '@santi100/random-lib/cjs/random-floats'; 

// Or import only the functions you need...
import {
	random,
	randomFromArray,
	randomIntegers,
	randomFloats,
} from '@santi100/random-lib'; // ESM/TypeScript
const {
	random,
	randomFromArray,
	randomIntegers,
	randomFloats,
} = require('@santi100/random-lib'); // CJS

// Or import everything
import * as randomLib from '@santi100/random-lib'; // ESM/TypeScript
const randomLib = require('@ssanti100/random-lib'); // CJS

// Generate a random integer between 1 and 10
const randomInt = random(10, 1);

// Generate a random floating-point number between -5.0 and 5.0
const randomFloat = randomFloat(-5.0, 5.0);

// Get a random item from an array
const fruits = ['apple', 'banana', 'orange'];
const randomFruit = randomFromArray(fruits);

// Get three random integers between 1 and 100
const randomIntegers = randomIntegers(3, { max: 100, min: 1 });

// Get four random floating-point numbers between -10.0 and 10.0
const randomFloats = randomFloats(4, { max: 10.0, min: -10.0 });

const myRandomLowercaseLetter = randomLower();
console.log(myRandomLowercaseLetter); // outputs a random lowercase letter (e.g. 'c')

const myRandomUppercaseLetter = randomUpper();
console.log(myRandomUppercaseLetter); // outputs a random uppercase letter (e.g. 'H')

const myRandomLetter = randomLetter();
console.log(myRandomLetter); // outputs a random letter (either lowercase or uppercase, e.g. 'J')

const myRandomLowercaseLetters = randomLowers(5);
console.log(myRandomLowercaseLetters); // outputs an array of 5 random lowercase letters (e.g. ['d', 's', 't', 'a', 'f'])

const myRandomUppercaseLetters = randomUppers(10);
console.log(myRandomUppercaseLetters); // outputs an array of 10 random uppercase letters (e.g. ['A', 'B', 'F', 'G', 'K', 'R', 'Q', 'Z', 'X', 'N'])

const myRandomLetters = randomLetters(3);
console.log(myRandomLetters); // outputs an array of 3 random letters (either lowercase or uppercase, e.g. ['e', 'W', 'T'])

---

_{This library doesn't generate cryptographically safe random numbers, due to its reliance on `Math.random()`. This library is designed to be portable across the browser and Node.js, to the expense of security.}