random-pie

A lightweight TypeScript/JavaScript library providing Python-style random number generation and randomization utilities. This utility module implements the most common functions from Python's random module, making it intuitive for Python developers working with TypeScript or 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

  • JavaScript (CommonJS)
  • TypeScript

• Examples

  • Example Directory Structure
  • Running the Examples
    • JavaScript Examples
    • TypeScript Examples

• 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

JavaScript (CommonJS)

// Import the Random class as a named export
const { Random } = require("random-pie");

// OR import Random as the default export
const Random = require("random-pie").default;

// OR import the entire module (both approaches work)
const randomPie = require("random-pie");
const Random = randomPie.Random; // Named export
// OR
const Random = randomPie.default; // Default export

// Import specific functions
const { rand, randInt, choice } = require("random-pie");

TypeScript / ESM

// Import Random as the default export
import Random from "random-pie";

// OR import Random as a named export
import { Random } from "random-pie";

// OR import specific functions
import {
  rand,
  uniform,
  randInt,
  randRange,
  choice,
  choices,
  shuffle,
  shuffled,
  sample,
} from "random-pie";

// Type-safe usage examples
const randomNumber: number = rand();
const items: string[] = ["apple", "banana", "orange"];
const selectedItem: string = choice(items);

Examples

The package includes a variety of examples to help you get started. These examples demonstrate different ways to use random-pie in both JavaScript and TypeScript.

Example Directory Structure

examples/
├── javascript/
│   ├── basic-usage.js    - Basic usage with CommonJS imports
│   └── advanced-usage.js - Advanced features with CommonJS
├── typescript/
│   ├── basic-usage.ts    - Basic usage with TypeScript/ESM
│   └── advanced-usage.ts - Advanced features with TypeScript
└── README.md             - Detailed instructions

Running the Examples

JavaScript Examples

# Run the basic JavaScript example
node examples/javascript/basic-usage.js

# Run the advanced JavaScript example
node examples/javascript/advanced-usage.js

TypeScript Examples

# Run the basic TypeScript example
npx ts-node examples/typescript/basic-usage.ts

# Run the advanced TypeScript example
npx ts-node examples/typescript/advanced-usage.ts

For more details about the examples and what they demonstrate, see the examples/README.md file.

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 (inclusive) and max (exclusive). Min and max values can be floating point numbers.

// 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 contains the relative weight for each element in the first argument. Optional and defaults to null. Values must be non-negative and at least one value must be non-zero.
• cumWeights: Similar to weights, except the array should contain cumulative weights. Optional and defaults to null. Values must be non-negative, non-decreasing, and have a final total greater than zero.
• k: The number of elements to select from the array. Optional and is default to 1.

If neither weights nor cumWeights are provided, array elements are selected with equal probability. If both weights and cumWeights are provided, a TypeError will be thrown. Both weights and cumWeights must be arrays with the same 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 (without replacement). If multiple repeated values are present in the first argument array, each occurrence of the repeated value is possible to be sampled.

The function accepts a third optional argument counts, which is an array of integers that correspond to each element in the input array. It effectively expands the population by repeating each element counts[i] times before sampling.

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

// Sample with counts (population becomes ["a", "a", "b"])
const countsSample = sample(["a", "b"], 3, [2, 1]); // ['a', 'a', 'b'] (in any order)

Class Interface

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

JavaScript

// Using default export
const Random = require("random-pie").default;

// OR using named export
const { Random } = require("random-pie");

// Static methods
Random.randInt(1, 10);
Random.choice(["heads", "tails"]);
Random.shuffle([1, 2, 3, 4, 5]);

TypeScript

// Using default export
import Random from "random-pie";

// OR using named export
import { Random } from "random-pie";

// Type-safe operations
const randomInt: number = Random.randInt(1, 10);
const selection: string = Random.choice<string>(["heads", "tails"]);
const numbers: number[] = [1, 2, 3, 4, 5];
Random.shuffle(numbers);

API Reference Table

Number Functions

| Function | Description | | ------------------ | ----------------------------- | | rand() | Returns float between 0 and 1 | | uniform(min, max) | Returns float in [min, max) | | randInt(...args) | Returns integer from range | | randRange(...args) | Returns number from range |

Array Functions

| Function | Description | | ---------------------- | ------------------------------ | | choice(arr) | Returns random item from array | | choices(arr, options) | Returns multiple random items | | shuffle(arr) | Shuffles array in place | | shuffled(arr) | Returns a shuffled array | | sample(arr, k, counts) | Returns k random items |