Random (TypeScript / JavaScript)

A lightweight, validated wrapper around Math.random() with a clean API for bounded floats/ints, coin flips, array selection, and bulk generation.

Note: all draws use half-open intervals [min, max) for floats and integers.

Table of Contents

• Introduction
• Installation
• Quick Start
• API
  • class Random
  • Utilities
• Error Handling
• Testing
• Roadmap
• Contributing
• License

Introduction

JavaScript’s Math.random() is seedless and returns a float in [0, 1). This library wraps it with a small, well-typed class and a few utilities so you can easily:

• generate bounded floats and integers,
• flip a bit (0 | 1),
• pick a random element from an array, and
• populate arrays efficiently.

Runtime validation guards catch invalid inputs early.

Installation

npm i @skreieweydo/random

Install from npm:

npm i @skreio/random

Quick Start

// If consumed directly from the repo:
import { Random, utils } from "@skreio/random";
utils.range, utils.seqℕ, utils.isFloat, utils.validateNumber

const rng = new Random(0, 10);

const f = rng.randomNumber();   // float in [0, 10)
const i = rng.randomInteger();  // integer in [0, 10)  (degenerate case min===max yields that exact value)
const b = rng.zeroOrOne();      // 0 or 1

const chosen = rng.choice([2, 4, 6, 8]);

// Bulk generation
const ints  = Random.populate(5, 1, 6);         // e.g., [1,2,3,2,5]
const fracs = Random.populate(5, 0, 100, true); // floats ~ [0, 1)

API

class Random

new Random(minimum = 0, maximum = 1)

• Validates types, finiteness, and ordering at construction.

• Throws:

  • TypeError("Minimum and maximum must be numbers.")
  • TypeError("Minimum and maximum must be finite numbers.")
  • Error("Minimum cannot be greater than maximum.")

Instance methods

| Method | Signature | Description | | ------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | randomNumber() | () => number | Uniform float in [min, max). | | randomInteger() | () => number | Uniform integer in [min, max). If min === max, returns that exact value. | | zeroOrOne() | () => 0 \| 1 | Random bit. | | choice | (arr: number[]) => number | Returns random element. Throws if the array is empty. | | static populate() | (n, start=0, end=100, frac=false) => number[] | Array of length n. Integers in [start, end) by default; when frac=true, returns integer / end (≈ [0,1) if start=0). |

Error Handling

• Constructor / Setters (min, max):

  • TypeError if values are not numbers or not finite.
  • Error if ordering is invalid (min > max / max < min).

• choice([]) → Error("Array cannot be empty.")

• populate(n <= 0) → Error("Count must be a positive number.")

• populate(frac=true, end=0) → Error("Division by zero error or invalid range.")

Utilities

If you export these from src/utils.ts, the library includes:

• validateNumber(name: string, value: number): void Throws if not a finite number.

• isFloat(n: number): boolean true for finite non-integers.

• seqℕ(n: number, options?: { includeZero?: boolean }): number[] Generates a length-n sequence starting at 0 (or 1 when includeZero=false).

• range(...) Python-like numeric range with overloads:

  • range(stop)
  • range(start, stop)
  • range(start, stop, step) Validates types/finiteness, disallows step=0, and returns [] on direction mismatch.

See inline JSDoc for exact signatures and behavior.

Testing

npm test

• Uses Jest with TypeScript/Babel transform.
• High coverage across Random and utilities (thresholds configurable in jest.config.js).

Roadmap

• Phase 2: Seeded PRNG interface (deterministic mode).
• Phase 3: Distributions (normal, exponential, etc.).
• Phase 4: CSPRNG option (Node/browser).
• Phase 5: Publish to npm + CI badges + typed examples.

Contributing

1. Fork the repo
2. Create a feature branch: git checkout -b feat/your-feature
3. Commit: git commit -m "feat: add X"
4. Push: git push origin feat/your-feature
5. Open a Pull Request

License

MIT — see LICENSE.