random-pie v1.0.0

random-pie

A lightweight JavaScript library providing Python-style random number generation and randomization utilities. This lightweight utility module implements the most common functions from Python's random module, making it intuitive for Python developers working with JavaScript.

⚠️ Security Notice: This module is not suitable for cryptographic or security-sensitive applications. For cryptographically secure operations, use Node.js's crypto module or other third-party alternatives instead.

Table of Contents

• Installation
• Basic Usage

• API Reference

  • Number Generation

    • rand()
    • uniform()
    • randInt()
    • randRange()

  • Array Operations

    • choice()
    • choices()
    • shuffle()
    • shuffled()
    • sample()

• Class Interface

• API Reference Table

  • Number Functions
  • Array Functions

Installation

npm install random-pie

Basic Usage

const { Random } = require('random-pie');
// or
const Random = require('random-pie');
// or import specific functions
const { rand, randInt, choice } = require('random-pie');

API Reference

Number Generation

rand()

Similar to random.rand() in Python, which returns a random float value between 0 (inclusive) and 1 (exclusive). This function is equivalent to Math.random().

// Generate float between 0 and 1
rand(); // 0.7249081475312897

uniform()

Similar to random.uniform(min, max) in Python, which returns a random float value between min and max (both inclusive). Min and max values can be a floating point number.

// Generate float in range
uniform(1.5, 3.8); // 2.341829378123

uniform(1, 5); // 3

randInt()

Similar to random.randint(min, max) in Python. Returns a random integer such that min <= number <= max. Different from the Python's random.randint() function, the randInt() function supports a third argument, which is the step size.

// Random integer from 0 to 10
randInt(10); // 7

// Random integer from 1 (start) to 10 (stop)
randInt(1, 10); // 5

// Random integer with step
randInt(0, 10, 2); // 0, 2, 4, 6, 8, or 10

randRange()

Similar to random.randrange(start, stop[, step]) in Python and the randInt function. Returns a random integer such that start <= number < stop (exclusive at stop).

// Random integer from 0 to 4 (stop - 1)
randRange(5); // 3

randRange(1, 10); // 7

randRange(0, 10, 2); // 0, 2, 4, 6, 8

Array Operations

choice()

Similar to random.choice() in Python, which returns a random element from the input array.

// Select a random item from the array
const randomFruit = choice(['apple', 'banana', 'orange']); // 'banana'

choices()

Similar to random.choices(). This function accepts two arguments, the first one being an array to choose from, and the second one being an object that contains configuration to the choices function. The object at the second argument can contain the following properties:

• weights: An array that contain the weight the given array in the first argument. Optional and is default to null.
• cumWeights: Similar to weights, except the array given to this property should be the cumulative weights. Optional and is default to null.
• k: The number of elements to select from the array. Optional and is default to 1.

If neither weights or cumWeights are provided, the array element is selected on based on equal probability. If both weights and cumWeights are provided, an TypeError will the thrown. Both weights or cumWeights should be an array with equal length as the array in the first argument.

// Multiple random selections with weights
const randomColors = choices(['red', 'green', 'blue'], {
    weights: [2, 1, 1],
    k: 3
}); // ['red', 'red', 'blue']

shuffle()

Similar to random.shuffle() in Python. This function does not return the shuffled array, but shuffles it in place and modify the original array.

// Shuffle array in place
const arr = [1, 2, 3, 4, 5];
shuffle(arr); // [3, 1, 5, 2, 4]

shuffled()

Works the same way as the `shuffle' function, but return a new, shuffled array. It does not modify the original array.

// Shuffle array in place
const arr = [1, 2, 3, 4, 5];
const shuffledArr = shuffled(arr); // [3, 1, 5, 2, 4]

sample()

Similar to random.sample() in Python.

Different from the choices function, this function does not select repeated values. If multiple repeated values are present in the first argument array, each occurrence of the repeated value is possible to be sampled.

// Sample k items from array
const randSample = sample(['a', 'b', 'c', 'd'], 2); // ['b', 'd']

Class Interface

Use the Random class for a more object-oriented approach:

const random = new Random();

random.randInt(1, 10);
random.choice(['heads', 'tails']);
random.shuffle([1, 2, 3, 4, 5]);

API Reference Table

Number Functions

Array Functions