A TypeScript npm package for generating random numbers with cryptographically strong PRNGs. This is a port of the Meteor.js random package with full TypeScript support, comprehensive unit testing, and modern npm packaging.
🌐 Live Examples & Documentation
Interactive examples and complete API documentation are available at the link above.
- Cryptographically Strong: Uses
crypto.randomBytes()on Node.js andwindow.crypto.getRandomValues()in browsers - Fallback Support: Falls back to Alea PRNG when cryptographic randomness is not available
- Cross-Platform: Works in Node.js, browsers, and other JavaScript environments
- TypeScript: Full TypeScript support with complete type definitions
- Deterministic Testing: Supports seeded random generation for reproducible tests
- Zero Dependencies: No external runtime dependencies
npm install @bluehive/random💡 Try it online! Check out the interactive examples and documentation to see the library in action.
import { Random } from '@bluehive/random';
// Generate a unique identifier (default length: 17)
const id = Random.id(); // "Jjwjg6gouWLXhMGKW"
// Generate a unique identifier with custom length
const shortId = Random.id(10); // "3kRtz8fGd2"
// Generate a cryptographically secure secret (default length: 43)
const secret = Random.secret(); // "dWx8fQ_kNZ4..."
// Generate a secure secret with custom length
const shortSecret = Random.secret(20); // "mK3oT9qZ..."
// Generate a random number between 0 and 1
const fraction = Random.fraction(); // 0.7851294...
// Generate a random hex string
const hex = Random.hexString(8); // "a1b2c3d4"
// Choose a random element from an array
const colors = ['red', 'green', 'blue'];
const color = Random.choice(colors); // "green"
// Choose a random character from a string
const char = Random.choice('abcdef'); // "c"For testing or when you need reproducible sequences:
import { Random } from '@bluehive/random';
// Create a seeded generator for reproducible results
const seededRandom = Random.createWithSeeds(42);
// These will always produce the same sequence with seed 42
console.log(seededRandom.id()); // Always the same result
console.log(seededRandom.fraction()); // Always the same result
// Multiple seeds can be used
const multiSeeded = Random.createWithSeeds('test', 123, 'more-entropy');When you need speed over security:
import { Random } from '@bluehive/random';
// Use the fast, non-cryptographic generator
const fastId = Random.insecure.id();
const fastFraction = Random.insecure.fraction();
const fastHex = Random.insecure.hexString(16);For advanced use cases, you can directly instantiate specific generators:
import {
NodeRandomGenerator,
BrowserRandomGenerator,
AleaRandomGenerator
} from '@bluehive/random';
// Force Node.js crypto (server-side only)
const nodeGen = new NodeRandomGenerator();
// Force browser crypto (client-side only)
const browserGen = new BrowserRandomGenerator();
// Use Alea PRNG with specific seeds
const aleaGen = new AleaRandomGenerator({ seeds: ['custom', 'seeds'] });Returns a unique identifier that is likely to be unique in the whole world.
n(optional): Length of the identifier in characters (default: 17)- Returns: String using characters that avoid confusion (excludes 0, 1, I, l, O)
Returns a random string of printable characters with 6 bits of entropy per character. Use for security-critical secrets intended for machine consumption.
n(optional): Length of the secret string (default: 43, which provides 256 bits of entropy)- Returns: String using base64 characters (a-z, A-Z, 0-9, -, _)
Returns a number between 0 and 1, like Math.random().
- Returns: Number in the range [0, 1)
Returns a random string of hexadecimal digits.
n: Length of the hex string- Returns: String of lowercase hex characters (0-9, a-f)
Returns a random element from the given array or string.
arrayOrString: Array or string to choose from- Returns: Random element from array, or random character from string
Creates a deterministic random generator using the Alea algorithm.
...seeds: One or more seed values (any type, will be converted to strings)- Returns: New RandomGenerator instance that produces deterministic sequences
A pre-instantiated fast random generator that's not cryptographically secure but suitable for non-security-critical applications.
The package automatically detects the environment and uses the most appropriate random source:
- Node.js: Uses
crypto.randomBytes()for cryptographically strong randomness - Modern Browsers: Uses
window.crypto.getRandomValues()for cryptographically strong randomness - Fallback: Uses Alea PRNG seeded with various entropy sources (date, Math.random, window dimensions, user agent)
- ID Generation: Uses "unmistakable" characters:
23456789ABCDEFGHJKLMNPQRSTWXYZabcdefghijkmnopqrstuvwxyz- Excludes: 0, 1, I, l, O (to avoid confusion)
- Secret Generation: Uses base64 characters:
abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_ - Hex Strings: Uses lowercase hex:
0123456789abcdef
The package includes comprehensive tests covering all functionality:
# Run tests
npm test
# Run tests with coverage
npm run test:coverage
# Run tests in watch mode
npm run test:watchThis package maintains API compatibility with Meteor's random package:
// Meteor code
import { Random } from 'meteor/random';
// Equivalent with this package
import { Random } from '@bluehive/random';
// All the same methods work identically
const id = Random.id();
const seeded = Random.createWithSeeds(0);The deterministic sequences generated by seeded generators are identical to those produced by Meteor's implementation.
- Use
Random.secret()for cryptographically secure secrets - Use
Random.id()for unique identifiers that don't need to be secret - Use
Random.createWithSeeds()only for testing or when reproducibility is required - The
Random.insecuregenerator should not be used for security-critical applications
MIT License. See LICENSE file for details.
If you're migrating from Meteor's random package:
- Install this package:
npm install @bluehive/random - Replace imports:
import { Random } from 'meteor/random'→import { Random } from '@bluehive/random' - All existing code should work without changes
For interactive examples and live demos, visit: https://bluehive-health.github.io/meteor-random/
# Clone and install dependencies
git clone https://github.com/bluehive-health/meteor-random.git
cd meteor-random
npm install
# Build TypeScript
npm run build
# Run tests
npm test
# Build and watch for changes
npm run devContributions are welcome! Please feel free to submit a Pull Request.