Building RandBox from Scratch: A Powerful JavaScript Random Data Generation Library (2/5) - Technical Architecture and Core Implementation

Preface
In the previous article, we explored the origin and overall planning of the RandBox project. Today, I will delve into technical details, sharing the design approach and key implementations of RandBox’s core architecture. From the selection of random number generators to the design of the TypeScript type system, every technical decision carries deep consideration for developer experience and performance.
Core Architecture Design
Layered Architecture Pattern
RandBox adopts a classic layered architecture to ensure code maintainability and extensibility:
┌─────────────────────────────────────────┐
│ API Layer │
├─────────────────────────────────────────┤
│ Module Layer │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Person │ │Location │ │Finance │ ...│
│ └─────────┘ └─────────┘ └─────────┘ │
├─────────────────────────────────────────┤
│ Core Layer │
│ RNG | Utils | Type Definitions │
├─────────────────────────────────────────┤
│ Runtime Layer │
│ Node.js | Browser | Mini-app │
└─────────────────────────────────────────┘Core Module Details
1. Core Module - Infrastructure
The Core module is the foundation of RandBox, providing basic random number generation capabilities and utility functions:
// src/core.ts Core class design
export class RandBox {
private mt: MersenneTwister;
private seed: string | number | undefined;
constructor(seed?: string | number) {
this.seed = seed;
this.mt = new MersenneTwister(this.getSeedValue(seed));
}
// Core random number generation method
random(): number {
return this.mt.random();
}
// Utility method: range check
testRange(test: boolean, message: string): void {
if (test) {
throw new RangeError(message);
}
}
// Utility method: initialize options
initOptions<T>(options: T | undefined, defaultOptions: T): T {
return { ...defaultOptions, ...options };
}
}Why Choose Mersenne Twister?
- High-Quality Randomness: Period up to 2^19937-1, almost no repetition
- Excellent Performance: High computational efficiency, suitable for large-scale data generation
- Predictability: Supports seed configuration for easy testing and debugging
- Widely Recognized: Adopted by many programming languages and libraries
2. Type System Design
The TypeScript type system is one of RandBox’s core advantages, with complete type definitions:
// src/types.ts Type definitions
export interface RandBoxOptions {
seed?: string | number;
}
// Option interfaces for basic data types
export interface IntegerOptions {
min?: number;
max?: number;
exclude?: number[];
}
export interface StringOptions {
length?: number;
pool?: string;
alpha?: boolean;
numeric?: boolean;
symbols?: boolean;
casing?: 'lower' | 'upper' | 'mixed';
}
// Option interfaces for complex types
export interface PersonOptions {
nationality?: 'zh' | 'en' | 'fr' | 'de';
gender?: 'male' | 'female' | 'mixed';
middle_initial?: boolean;
prefix?: boolean;
suffix?: boolean;
}
// Function overload support
export interface RandBoxInstance {
// Multiple call styles for integer method
integer(): number;
integer(max: number): number;
integer(min: number, max: number): number;
integer(options: IntegerOptions): number;
// Other methods...
name(options?: PersonOptions): string;
email(options?: EmailOptions): string;
}Type Design Principles:
- Progressive Complexity: Smooth transition from simple calls to complex configurations
- Smart Inference: TypeScript automatically infers return types
- Extensibility: Interface design facilitates future feature extensions
3. Modular Design Implementation
Each functional module is developed independently and organized through a unified pattern:
// src/person.ts Example module
import { RandBox } from './core';
// Name generation function
export function name(this: RandBox, options?: PersonOptions): string {
const opts = this.initOptions(options, {
nationality: 'zh',
gender: 'mixed',
middle_initial: false
});
const firstNames = DATA_SETS.firstNames[opts.nationality][opts.gender];
const lastNames = DATA_SETS.lastNames[opts.nationality];
const firstName = this.pickone(firstNames);
const lastName = this.pickone(lastNames);
return opts.nationality === 'zh'
? `${lastName}${firstName}`
: `${firstName} ${lastName}`;
}
// Email generation function
export function email(this: RandBox, options?: EmailOptions): string {
const opts = this.initOptions(options, {
domain: null,
length: null
});
const username = opts.length
? this.string({ length: opts.length, casing: 'lower' })
: this.first().toLowerCase();
const domain = opts.domain || this.pickone(COMMON_DOMAINS);
return `${username}@${domain}`;
}
// Export all functions
export const personFunctions = { name, email, age, birthday, gender };Data Management Strategy
1. Localized Data Organization
RandBox includes rich localized data supporting multiple languages and regions:
// src/datasets.ts Dataset organization
export const DATA_SETS = {
firstNames: {
zh: {
male: ['Wei', 'Qiang', 'Lei', 'Jun', 'Yang', 'Yong', 'Jie', 'Hua'],
female: ['Xiuying', 'Guiying', 'Xiulan', 'Yulan', 'Guilan', 'Xiuzhen', 'Li'],
mixed: [] // Combined male and female names
},
en: {
male: ['James', 'John', 'Robert', 'Michael', 'William'],
female: ['Mary', 'Patricia', 'Jennifer', 'Linda', 'Elizabeth']
}
},
lastNames: {
zh: ['Wang', 'Li', 'Zhang', 'Liu', 'Chen', 'Yang', 'Zhao', 'Huang', 'Wu'],
en: ['Smith', 'Johnson', 'Williams', 'Brown', 'Jones']
},
// Address data
addresses: {
zh: {
provinces: ['Beijing', 'Shanghai', 'Guangdong', 'Jiangsu'],
cities: {
'Beijing': ['Chaoyang', 'Haidian', 'Xicheng', 'Dongcheng'],
'Shanghai': ['Pudong', 'Huangpu', 'Xuhui', 'Changning']
}
}
},
// More datasets...
};2. Intelligent Caching Mechanism
To improve performance, RandBox implements intelligent caching:
class DataCache {
private cache = new Map<string, any>();
private maxSize = 1000;
get<T>(key: string, generator: () => T): T {
if (this.cache.has(key)) {
return this.cache.get(key);
}
const value = generator();
if (this.cache.size >= this.maxSize) {
// LRU eviction strategy
const firstKey = this.cache.keys().next().value;
this.cache.delete(firstKey);
}
this.cache.set(key, value);
return value;
}
}Algorithm Core Implementation
1. Mersenne Twister Implementation
class MersenneTwister {
private mt: number[] = new Array(624);
private mti: number = 625;
constructor(seed?: number) {
this.init_genrand(seed || Date.now());
}
private init_genrand(s: number): void {
this.mt[0] = s >>> 0;
for (this.mti = 1; this.mti < 624; this.mti++) {
s = this.mt[this.mti - 1] ^ (this.mt[this.mti - 1] >>> 30);
this.mt[this.mti] = (((((s & 0xffff0000) >>> 16) * 1812433253) << 16) +
(s & 0x0000ffff) * 1812433253) + this.mti;
this.mt[this.mti] >>>= 0;
}
}
genrand_int32(): number {
let y: number;
const mag01 = [0x0, 0x9908b0df];
if (this.mti >= 624) {
// Generate new random number sequence
let kk: number;
for (kk = 0; kk < 227; kk++) {
y = (this.mt[kk] & 0x80000000) | (this.mt[kk + 1] & 0x7fffffff);
this.mt[kk] = this.mt[kk + 397] ^ (y >>> 1) ^ mag01[y & 0x1];
}
// ... More implementation details
this.mti = 0;
}
y = this.mt[this.mti++];
// Tempering
y ^= y >>> 11;
y ^= (y << 7) & 0x9d2c5680;
y ^= (y << 15) & 0xefc60000;
y ^= y >>> 18;
return y >>> 0;
}
random(): number {
return this.genrand_int32() * (1.0 / 4294967296.0);
}
}2. Advanced Random Algorithms
Normal Distribution Implementation (Box-Muller Transform)
export function normal(this: RandBox, mean = 0, deviation = 1): number {
// Box-Muller transform for normal distribution
if (this.normal_cache !== null) {
const cached = this.normal_cache;
this.normal_cache = null;
return cached * deviation + mean;
}
const u1 = this.random();
const u2 = this.random();
const z0 = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
const z1 = Math.sqrt(-2 * Math.log(u1)) * Math.sin(2 * Math.PI * u2);
this.normal_cache = z1;
return z0 * deviation + mean;
}Weighted Random Selection Implementation
export function weighted<T>(
this: RandBox,
array: T[],
weights: number[]
): T {
if (array.length !== weights.length) {
throw new Error('Array and weights must have the same length');
}
// Calculate cumulative weights
const totalWeight = weights.reduce((sum, weight) => sum + weight, 0);
const cumulativeWeights: number[] = [];
let sum = 0;
for (let i = 0; i < weights.length; i++) {
sum += weights[i] / totalWeight;
cumulativeWeights[i] = sum;
}
// Random selection
const random = this.random();
for (let i = 0; i < cumulativeWeights.length; i++) {
if (random <= cumulativeWeights[i]) {
return array[i];
}
}
return array[array.length - 1];
}Build and Optimization
1. Rollup Configuration Optimization
// rollup.config.js
import typescript from '@rollup/plugin-typescript';
import { terser } from 'rollup-plugin-terser';
import resolve from '@rollup/plugin-node-resolve';
export default {
input: 'src/index.ts',
output: [
// ESM format (Tree Shaking support)
{
file: 'dist/index.esm.mjs',
format: 'es',
sourcemap: true
},
// CommonJS format
{
file: 'dist/index.cjs',
format: 'cjs',
sourcemap: true
},
// UMD format (direct browser use)
{
file: 'dist/index.umd.js',
format: 'umd',
name: 'RandBox',
sourcemap: true
}
],
plugins: [
resolve(),
typescript({
tsconfig: './tsconfig.json',
declaration: true,
declarationDir: 'dist'
}),
terser() // Code minification
],
// External configuration, support for on-demand imports
external: id => !id.startsWith('.') && !id.startsWith('/'),
// Multi-entry configuration
input: {
index: 'src/index.ts',
core: 'src/core.ts',
person: 'src/person.ts',
location: 'src/location.ts',
// ... Other modules
}
};2. Tree Shaking Optimization
To achieve the best Tree Shaking effect, we use a special export strategy:
// src/index.ts Main entry
export { RandBox as default } from './core';
export * from './types';
// Modular exports
export * as basics from './basics';
export * as person from './person';
export * as location from './location';
// ... Other modules
// src/person.ts Module exports
export const name = function(this: RandBox, options?: PersonOptions): string {
// Implementation
};
export const email = function(this: RandBox, options?: EmailOptions): string {
// Implementation
};
// Batch exports (for main class integration)
export const personFunctions = { name, email, age, birthday };This design allows users to use it in different ways:
// Method 1: Full import
import RandBox from 'randbox';
const randBox = new RandBox();
// Method 2: Module-based import
import * as person from 'randbox/dist/person';
console.log(person.name());
// Method 3: On-demand import
import { name, email } from 'randbox/dist/person';Performance Optimization Strategies
1. Lazy Loading Data Sets
class LazyDataSet<T> {
private _data: T | null = null;
private loader: () => T;
constructor(loader: () => T) {
this.loader = loader;
}
get data(): T {
if (this._data === null) {
this._data = this.loader();
}
return this._data;
}
}
// Usage example
const CHINESE_NAMES = new LazyDataSet(() =>
require('./datasets/chinese-names.json')
);2. Memory Pool Optimization
class ObjectPool<T> {
private pool: T[] = [];
private createFn: () => T;
private resetFn: (obj: T) => void;
constructor(createFn: () => T, resetFn: (obj: T) => void) {
this.createFn = createFn;
this.resetFn = resetFn;
}
get(): T {
if (this.pool.length > 0) {
return this.pool.pop()!;
}
return this.createFn();
}
release(obj: T): void {
this.resetFn(obj);
this.pool.push(obj);
}
}Error Handling and Debugging
1. User-Friendly Error Messages
export class RandBoxError extends Error {
constructor(message: string, public code: string) {
super(message);
this.name = 'RandBoxError';
}
}
export class ValidationError extends RandBoxError {
constructor(parameter: string, value: any, expected: string) {
super(
`Invalid parameter "${parameter}": expected ${expected}, got ${typeof value}`,
'VALIDATION_ERROR'
);
}
}
// Usage example
export function integer(this: RandBox, min?: number, max?: number): number {
if (min !== undefined && typeof min !== 'number') {
throw new ValidationError('min', min, 'number');
}
if (max !== undefined && typeof max !== 'number') {
throw new ValidationError('max', max, 'number');
}
if (min !== undefined && max !== undefined && min > max) {
throw new RandBoxError(
`Minimum value (${min}) cannot be greater than maximum value (${max})`,
'INVALID_RANGE'
);
}
// Implementation logic...
}2. Debugging Support
export class RandBox {
private debugMode = false;
private callHistory: Array<{ method: string; args: any[]; result: any }> = [];
enableDebug(): void {
this.debugMode = true;
}
getCallHistory(): ReadonlyArray<any> {
return this.callHistory;
}
private logCall(method: string, args: any[], result: any): void {
if (this.debugMode) {
this.callHistory.push({ method, args, result });
console.log(`RandBox.${method}(${JSON.stringify(args)}) -> ${result}`);
}
}
}What’s Next
In the next article, I will detail how to implement RandBox’s rich functional modules, including:
- Implementation details of data generation in various professional domains
- Application of complex algorithms (such as geographic coordinate generation, credit card number validation, etc.)
- Processing and optimization of localized data
- Implementation techniques for advanced features
Stay tuned for “Building RandBox from Scratch (3/5) - Feature Modules Deep Implementation”!
About RandBox
🏠 Website: https://randbox.top 📦 GitHub: https://github.com/027xiguapi/randbox 📚 Documentation: https://randbox.top/en/docs
If this project is helpful to you, please give us a ⭐ Star!