Skip to Content
🎲 Welcome to RandBox - Powerful JavaScript Random Data Generation Library! Learn More

Building RandBox from Scratch: A Powerful JavaScript Random Data Generation Library (3/5) - Feature Modules Deep Implementation

randbox-home

Preface

In the previous two articles, we explored RandBox’s project planning and core architecture. Today, I will dive deep into the implementation details of each feature module, sharing how to build rich and diverse random data generation functionality. From basic number and string generation to complex geographic coordinate calculations, each module has its unique challenges and clever solutions.

Module Design Philosophy

Before diving into specific implementations, I want to share the core philosophy behind RandBox’s module design:

1. Progressive Complexity

Each feature supports multiple calling methods from simple to complex:

// Simple call randBox.name(); // "John Smith" // Medium complexity randBox.name({ nationality: 'en' }); // "John Smith" // Fully custom randBox.name({ nationality: 'zh', gender: 'female', prefix: true, suffix: false }); // "Ms. Wang"

2. Smart Defaults

Each feature has reasonable default behavior, usable without configuration:

// These all produce reasonable default results randBox.integer(); // Integer between 0-100 randBox.email(); // Properly formatted email randBox.phone(); // Current region's phone format

3. Consistency Principle

All modules follow the same API design pattern to reduce learning cost.

Basic Data Type Module (basics.ts)

The basics module is the foundation of the entire RandBox, implementing the most core random data generation functionality.

1. Multiple Implementation Methods for Integer Generation

export function integer(this: RandBox): number; export function integer(this: RandBox, max: number): number; export function integer(this: RandBox, min: number, max: number): number; export function integer(this: RandBox, options: IntegerOptions): number; export function integer( this: RandBox, minOrOptions?: number | IntegerOptions, max?: number ): number { // Parameter parsing logic let min: number, maxVal: number, exclude: number[] = []; if (typeof minOrOptions === 'object') { // Object-form parameters const opts = this.initOptions(minOrOptions, { min: -9007199254740991, // Number.MIN_SAFE_INTEGER max: 9007199254740991, // Number.MAX_SAFE_INTEGER exclude: [] }); min = opts.min; maxVal = opts.max; exclude = opts.exclude; } else if (typeof minOrOptions === 'number') { if (max === undefined) { // integer(max) form min = 0; maxVal = minOrOptions; } else { // integer(min, max) form min = minOrOptions; maxVal = max; } } else { // integer() form, use default values min = 0; maxVal = 100; } // Parameter validation this.testRange( !Number.isInteger(min) || !Number.isInteger(maxVal), 'Min and max must be integers' ); this.testRange(min > maxVal, 'Min cannot be greater than max'); // Generate random integer let result: number; const range = maxVal - min + 1; do { result = Math.floor(this.random() * range) + min; } while (exclude.includes(result) && exclude.length < range); if (exclude.includes(result) && exclude.length >= range) { throw new Error('All possible values are excluded'); } return result; }

2. High-Quality String Generation

String generation is a feature that seems simple but is actually complex, requiring consideration of multiple character sets and encodings:

interface StringOptions { length?: number; pool?: string; alpha?: boolean; numeric?: boolean; symbols?: boolean; casing?: 'lower' | 'upper' | 'mixed'; exclude?: string[]; } export function string(this: RandBox, options?: StringOptions): string { const opts = this.initOptions(options, { length: 10, pool: null, alpha: true, numeric: false, symbols: false, casing: 'mixed', exclude: [] }); // Build character pool let pool = opts.pool; if (!pool) { pool = ''; if (opts.alpha) { pool += 'abcdefghijklmnopqrstuvwxyz'; if (opts.casing === 'upper' || opts.casing === 'mixed') { pool += 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'; } } if (opts.numeric) { pool += '0123456789'; } if (opts.symbols) { pool += '!@#$%^&*()_+-=[]{}|;:,.<>?'; } } // Remove excluded characters if (opts.exclude.length > 0) { for (const char of opts.exclude) { pool = pool.replace(new RegExp(char, 'g'), ''); } } this.testRange(pool.length === 0, 'Character pool cannot be empty'); // Generate string let result = ''; for (let i = 0; i < opts.length; i++) { result += pool.charAt(Math.floor(this.random() * pool.length)); } // Casing handling if (opts.casing === 'lower') { result = result.toLowerCase(); } else if (opts.casing === 'upper') { result = result.toUpperCase(); } return result; }

3. Floating-Point Precision Control

Floating-point generation requires special attention to precision control:

export function floating( this: RandBox, min = 0, max = 1, fixed?: number ): number { this.testRange(min > max, 'Min cannot be greater than max'); const result = this.random() * (max - min) + min; if (fixed !== undefined) { this.testRange( !Number.isInteger(fixed) || fixed < 0, 'Fixed must be a non-negative integer' ); return Number(result.toFixed(fixed)); } return result; }

Personal Information Module (person.ts)

The personal information module is one of the most complex modules in RandBox, requiring handling of names, genders, and other data across multiple cultural contexts.

1. Smart Name Generation

interface PersonOptions { nationality?: 'zh' | 'en' | 'fr' | 'de' | 'jp'; gender?: 'male' | 'female' | 'mixed'; middle_initial?: boolean; prefix?: boolean; suffix?: boolean; } export function name(this: RandBox, options?: PersonOptions): string { const opts = this.initOptions(options, { nationality: 'zh', gender: 'mixed', middle_initial: false, prefix: false, suffix: false }); // Select gender const selectedGender = opts.gender === 'mixed' ? this.pickone(['male', 'female']) : opts.gender; // Get corresponding dataset const firstNames = DATASETS.firstNames[opts.nationality][selectedGender]; const lastNames = DATASETS.lastNames[opts.nationality]; let result = ''; // Add prefix if (opts.prefix) { const prefixes = DATASETS.prefixes[opts.nationality][selectedGender]; result += this.pickone(prefixes) + ' '; } // Generate name const firstName = this.pickone(firstNames); const lastName = this.pickone(lastNames); if (opts.nationality === 'zh') { // Chinese: surname + given name result += lastName + firstName; } else { // Western: given name + surname result += firstName; // Add middle initial if (opts.middle_initial) { result += ' ' + this.character({ alpha: true, casing: 'upper' }) + '.'; } result += ' ' + lastName; } // Add suffix if (opts.suffix) { const suffixes = DATASETS.suffixes[opts.nationality]; result += ' ' + this.pickone(suffixes); } return result.trim(); }

2. Age and Birthday Correlation Generation

interface AgeOptions { type?: 'child' | 'teen' | 'adult' | 'senior' | 'any'; min?: number; max?: number; } export function age(this: RandBox, options?: AgeOptions): number { const opts = this.initOptions(options, { type: 'any', min: null, max: null }); let min: number, max: number; if (opts.min !== null && opts.max !== null) { min = opts.min; max = opts.max; } else { // Determine range based on type switch (opts.type) { case 'child': min = 1; max = 12; break; case 'teen': min = 13; max = 19; break; case 'adult': min = 20; max = 64; break; case 'senior': min = 65; max = 100; break; default: min = 1; max = 100; } } return this.integer(min, max); } export function birthday(this: RandBox, options?: { type?: 'child' | 'teen' | 'adult' | 'senior'; format?: 'date' | 'string' | 'iso'; }): Date | string { const opts = this.initOptions(options, { type: 'any', format: 'date' }); const ageValue = this.age({ type: opts.type }); const currentYear = new Date().getFullYear(); const birthYear = currentYear - ageValue; const birthDate = new Date( birthYear, this.integer(0, 11), // Months 0-11 this.integer(1, 28) // Days 1-28 (avoid month day issues) ); switch (opts.format) { case 'string': return birthDate.toLocaleDateString(); case 'iso': return birthDate.toISOString(); default: return birthDate; } }

Geographic Location Module (location.ts)

The geographic location module involves complex geographic calculations and multiple coordinate systems.

1. Precise Coordinate Generation

interface CoordinatesOptions { min_lat?: number; max_lat?: number; min_lng?: number; max_lng?: number; precision?: number; } export function coordinates( this: RandBox, options?: CoordinatesOptions ): { lat: number; lng: number } { const opts = this.initOptions(options, { min_lat: -90, max_lat: 90, min_lng: -180, max_lng: 180, precision: 6 }); // Validate coordinate range this.testRange( opts.min_lat < -90 || opts.max_lat > 90, 'Latitude must be between -90 and 90' ); this.testRange( opts.min_lng < -180 || opts.max_lng > 180, 'Longitude must be between -180 and 180' ); const lat = Number( this.floating(opts.min_lat, opts.max_lat).toFixed(opts.precision) ); const lng = Number( this.floating(opts.min_lng, opts.max_lng).toFixed(opts.precision) ); return { lat, lng }; } // Generate real coordinate ranges based on country export function coordinatesInCountry( this: RandBox, country: string ): { lat: number; lng: number } { const countryBounds = COUNTRY_BOUNDS[country.toUpperCase()]; if (!countryBounds) { throw new Error(`Country bounds not found for: ${country}`); } return this.coordinates({ min_lat: countryBounds.minLat, max_lat: countryBounds.maxLat, min_lng: countryBounds.minLng, max_lng: countryBounds.maxLng }); }

2. Address Generation System

export function address(this: RandBox, options?: { country?: string; full?: boolean; }): string { const opts = this.initOptions(options, { country: 'CN', full: true }); const countryData = ADDRESS_DATA[opts.country]; if (!countryData) { throw new Error(`Address data not available for country: ${opts.country}`); } let result = ''; if (opts.country === 'CN') { // Chinese address format const province = this.pickone(countryData.provinces); const city = this.pickone(countryData.cities[province]); const district = this.pickone(countryData.districts[city]); const street = this.pickone(countryData.streets); const number = this.integer(1, 999); if (opts.full) { result = `${province}${city}${district}${street}${number}号`; } else { result = `${street}${number}号`; } } else { // Western address format const number = this.integer(1, 9999); const street = this.pickone(countryData.streets); const streetType = this.pickone(countryData.streetTypes); result = `${number} ${street} ${streetType}`; } return result; }

Finance Module (finance.ts)

The finance module needs to generate financial data that meets real-world standards, especially credit card numbers with Luhn algorithm validation.

1. Luhn Algorithm Implementation

function luhnChecksum(number: string): number { let sum = 0; let alternate = false; // Process each digit from right to left for (let i = number.length - 1; i >= 0; i--) { let digit = parseInt(number.charAt(i), 10); if (alternate) { digit *= 2; if (digit > 9) { digit = (digit % 10) + 1; } } sum += digit; alternate = !alternate; } return sum % 10; } function luhnValid(number: string): boolean { return luhnChecksum(number) === 0; } function generateLuhnValid(prefix: string, length: number): string { // Generate all digits except the last one let number = prefix; while (number.length < length - 1) { number += Math.floor(Math.random() * 10).toString(); } // Calculate check digit const checksum = luhnChecksum(number + '0'); const checkDigit = checksum === 0 ? 0 : 10 - checksum; return number + checkDigit.toString(); }

2. Credit Card Number Generation

interface CreditCardOptions { type?: 'visa' | 'mastercard' | 'amex' | 'discover' | 'any'; formatted?: boolean; } export function cc(this: RandBox, options?: CreditCardOptions): string { const opts = this.initOptions(options, { type: 'any', formatted: false }); // Credit card type configuration const cardTypes = { visa: { prefix: ['4'], length: [16] }, mastercard: { prefix: ['51', '52', '53', '54', '55'], length: [16] }, amex: { prefix: ['34', '37'], length: [15] }, discover: { prefix: ['6011'], length: [16] } }; let selectedType: string; if (opts.type === 'any') { selectedType = this.pickone(Object.keys(cardTypes)); } else { selectedType = opts.type; } const typeConfig = cardTypes[selectedType]; const prefix = this.pickone(typeConfig.prefix); const length = this.pickone(typeConfig.length); // Generate card number that complies with Luhn algorithm let cardNumber = generateLuhnValid(prefix, length); // Format output if (opts.formatted) { if (selectedType === 'amex') { // American Express: 4-6-5 format cardNumber = cardNumber.replace(/(\d{4})(\d{6})(\d{5})/, '$1 $2 $3'); } else { // Others: 4-4-4-4 format cardNumber = cardNumber.replace(/(\d{4})/g, '$1 ').trim(); } } return cardNumber; }

Web Module (web.ts)

The web module generates various internet-related data and needs to comply with relevant RFC standards.

1. Smart Email Generation

export function email(this: RandBox, options?: { domain?: string; username?: string; length?: number; }): string { const opts = this.initOptions(options, { domain: null, username: null, length: null }); // Generate username let username = opts.username; if (!username) { if (opts.length) { username = this.string({ length: opts.length, alpha: true, numeric: true, casing: 'lower' }); } else { // Generate based on real name const firstName = this.first().toLowerCase(); const lastName = this.last().toLowerCase(); // Multiple combination patterns const patterns = [ `${firstName}.${lastName}`, `${firstName}${lastName}`, `${firstName.charAt(0)}${lastName}`, `${firstName}${this.integer(10, 99)}` ]; username = this.pickone(patterns); } } // Clean username (remove illegal characters) username = username.replace(/[^a-z0-9.-]/g, ''); // Generate domain let domain = opts.domain; if (!domain) { const commonDomains = [ 'gmail.com', 'outlook.com', 'yahoo.com', 'hotmail.com', '163.com', 'qq.com', '126.com', 'sina.com' ]; domain = this.pickone(commonDomains); } return `${username}@${domain}`; }

2. IP Address Generation

export function ip(this: RandBox, options?: { version?: 4 | 6; private?: boolean; }): string { const opts = this.initOptions(options, { version: 4, private: false }); if (opts.version === 4) { if (opts.private) { // Generate private IP address const privateRanges = [ { start: [10, 0, 0, 0], end: [10, 255, 255, 255] }, { start: [172, 16, 0, 0], end: [172, 31, 255, 255] }, { start: [192, 168, 0, 0], end: [192, 168, 255, 255] } ]; const range = this.pickone(privateRanges); return [ this.integer(range.start[0], range.end[0]), this.integer(range.start[1], range.end[1]), this.integer(range.start[2], range.end[2]), this.integer(range.start[3], range.end[3]) ].join('.'); } else { // Generate public IP address (avoid private and reserved ranges) let octets: number[]; do { octets = [ this.integer(1, 255), this.integer(0, 255), this.integer(0, 255), this.integer(1, 255) ]; } while (isPrivateIP(octets) || isReservedIP(octets)); return octets.join('.'); } } else { // IPv6 address generation const groups = []; for (let i = 0; i < 8; i++) { groups.push(this.string({ length: 4, pool: '0123456789abcdef' })); } return groups.join(':'); } } function isPrivateIP(octets: number[]): boolean { return ( octets[0] === 10 || (octets[0] === 172 && octets[1] >= 16 && octets[1] <= 31) || (octets[0] === 192 && octets[1] === 168) ); } function isReservedIP(octets: number[]): boolean { return ( octets[0] === 0 || // This network octets[0] === 127 || // Loopback address octets[0] === 224 || // Multicast address octets[0] >= 240 // Reserved addresses ); }

Performance Optimization Techniques

1. Data Preprocessing

// Pre-compute commonly used data const COMMON_PATTERNS = { chinesePhoneFormats: [ '13#########', '15#########', '18#########' ].map(pattern => pattern.replace(/#/g, () => Math.floor(Math.random() * 10).toString() )) };

2. Caching Mechanism

class ModuleCache { private static cache = new Map<string, any>(); static get<T>(key: string, generator: () => T): T { if (!this.cache.has(key)) { this.cache.set(key, generator()); } return this.cache.get(key); } } // Usage example export function getCountryData(country: string) { return ModuleCache.get(`country_${country}`, () => loadCountryData(country) ); }

Next Article Preview

In the next article, I will dive deep into RandBox’s testing system and quality assurance, including:

  • Complete unit test design
  • Performance testing and benchmark comparisons
  • Multi-environment compatibility testing
  • Continuous integration process setup

Stay tuned for “Building RandBox from Scratch (4/5) - Testing System and Quality Assurance”!


About RandBox

🏠 Homepage: https://randbox.top  📦 GitHub: https://github.com/027xiguapi/randbox  📚 Documentation: https://randbox.top/zh/docs 

If this project is helpful to you, please give us a ⭐ Star!