Random Library API Documentation

Overview

The Random Library provides a collection of utilities for generating random values, including numbers, colors, strings, and more. It is organized into several modules, each offering specific functionality.

Modules

1. Core Utilities

CoreRandom

• random(n: number = 1, o: number | null = null): number

  • Generates a random number.
  • Parameters:
    • n: Upper limit or lower bound if o is provided.
    • o: Upper bound (optional).
  • Returns: A random number between n and o (or 0 and n if o is not provided).

• flip(t: number = 0.5): boolean

  • Simulates a coin flip with a given probability.
  • Parameters:
    • t: Probability of returning true (default is 0.5).
  • Returns: true or false.

• shuffle(arr: any[]): any[]

  • Shuffles an array randomly.
  • Parameters:
    • arr: The array to shuffle.
  • Returns: A new shuffled array.

• weightedRandom(choices: any[], weights: number[]): any

  • Selects a random item based on weights.
  • Parameters:
    • choices: Array of items to choose from.
    • weights: Array of weights corresponding to each choice.
  • Returns: A randomly selected item.

2. Dice Utilities

DiceRoller

• die(sides: number): number

  • Rolls a single die with the specified number of sides.
  • Parameters:
    • sides: Number of sides on the die.
  • Returns: A random number between 1 and sides.

• dieRoll(desc: string): number

  • Rolls dice based on a string description (e.g., 2d6+3).
  • Parameters:
    • desc: Dice roll description.
  • Returns: The total result of the roll.

• bestOfRolls(n: number, diceType: number, bestN: number): number

  • Rolls multiple dice and selects the best results.
  • Parameters:
    • n: Number of dice to roll.
    • diceType: Number of sides on each die.
    • bestN: Number of best rolls to sum.
  • Returns: The sum of the best rolls.

3. Format Utilities

RandomFormat

• uuid(): string

  • Generates a random UUID.
  • Returns: A string in UUID format.

• randomAlphaNumeric(length: number, charset: Charset = "alphanumeric"): string

  • Generates a random string of the specified length and charset.
  • Parameters:
    • length: Length of the string.
    • charset: Character set (alphanumeric, alphabetic, numeric, hexadecimal).
  • Returns: A random string.

• generatePassword(length: number = 12, uppercase: boolean, lowercase: boolean, numbers: boolean, symbols: boolean): string

  • Generates a random password.
  • Parameters:
    • length: Length of the password.
    • uppercase: Include uppercase letters.
    • lowercase: Include lowercase letters.
    • numbers: Include numbers.
    • symbols: Include symbols.
  • Returns: A random password.

• randomUsername(): string

  • Generates a random username.
  • Returns: A username in the format AdjectiveNounNumber.

4. Color Utilities

RandomColor

• randomColor(format: Format = "hex"): string

  • Generates a random color in the specified format.
  • Parameters:
    • format: Color format (hex, rgb, hsl).
  • Returns: A random color.

• randomColorPalette(count: number = 5, format: Format = "hex"): string[]

  • Generates a palette of random colors.
  • Parameters:
    • count: Number of colors to generate.
    • format: Color format (hex, rgb, hsl).
  • Returns: An array of random colors.

5. Distributions Utilities

RandomDistributions

• gaussian(mean: number = 0, stdDev: number = 1): number
  • Generates a random number following a Gaussian distribution.
  • Parameters:
    • mean: Mean of the distribution.
    • stdDev: Standard deviation of the distribution.
  • Returns: A random number.

Installation

npm install random-library

Usage

import { RandomUtils } from "random-library";

// Example: Generate a random UUID
const uuid = RandomUtils.format.uuid();
console.log(uuid);