Random World

A Node.js module for generating random data. Built for usage with mock servers, testing, and data generation pipelines.

Installation

npm install random-world

Quick Start

As a Library

import random from 'random-world';

// Generate names
random.names.fullname();         // "Jennifer Martinez"
random.names.email();            // "[email protected]"

// Generate numbers
random.numbers.integer({ min: 1, max: 100 });  // 42

// Generate network data
random.network.ip();             // "192.168.1.45"
random.network.mac();            // "a1:b2:c3:d4:e5:f6"

// Generate UUIDs
random.strings.uuid();           // "550e8400-e29b-41d4-a716-446655440000"

// Generate company data
random.company.name();           // "Global Technologies Inc"
random.company.jobTitle();       // "Senior Developer"

// Generate phone numbers
random.phone.number();           // "(555) 123-4567"
random.phone.imei();             // "353456789012345"

// Generate colors
random.colors.hex();             // "#FF5733"
random.colors.name();            // "cornflowerblue"

// Generate internet data
random.internet.url();           // "http://www.example.com"
random.internet.domain();        // "example.com"
random.internet.username();      // "cool_ninja42"

As a CLI

The CLI is built-in and replaces the old random-world-cli package.

# Generate 10 random names
random-world names.fullname -r 10

# Generate 5 IP addresses as JSON
random-world network.ip -r 5 -f json

# Generate integers with options
random-world numbers.integer -o '{"min":1,"max":100}' -r 10

# Generate unique values only
random-world names.firstname -r 20 -u

CLI Reference

Usage:
  random-world <method> [options]

Options:
  -r, --repeat <n>     Number of items to generate (default: 1)
  -f, --format <fmt>   Output format: text, json, csv, sql (default: text)
  -u, --unique         Generate unique values only
  -o, --options <json> JSON options to pass to the method
  -h, --help           Show help message
  -v, --version        Show version number

Output Formats

| Format | Description | |--------|-------------| | text | Plain text, one value per line | | json | JSON array | | csv | Comma-separated values with header | | sql | SQL INSERT statements |

Examples

# Generate CSV of 100 email addresses
random-world names.email -r 100 -f csv

# Generate SQL inserts for cities
random-world places.city -r 50 -f sql

# Generate JSON array of credit card numbers
random-world money.ccnumber -r 10 -f json

# Generate unique UUIDs
random-world strings.uuid -r 1000 -u -f json

# Generate company names
random-world company.name -r 20

# Generate phone numbers
random-world phone.number -r 10 -f json

# Generate hex colors
random-world colors.hex -r 5

# Generate passwords
random-world internet.password -o '{"length":24,"symbols":false}' -r 5

Modules

• Names
• Network
• Numbers
• Strings
• Places
• Dates
• Geography
• Money
• Files
• Phone
• Company
• Colors
• Internet
• Collections
• Truth
• Object Parser

Names

Generate random names, titles, and email addresses.

names.firstname(options)

Generate a random first name.

| Option | Type | Description | |--------|------|-------------| | gender | string | Limit to 'male', 'female', or 'nonbinary' | | startsWith | string | Filter names starting with substring | | charCase | string | Transform case: 'upper' or 'lower' |

random.names.firstname();                          // "Emma"
random.names.firstname({ gender: 'male' });        // "James"
random.names.firstname({ startsWith: 'Ch' });      // "Charlotte"

names.lastname(options)

Generate a random last name (surname).

| Option | Type | Description | |--------|------|-------------| | startsWith | string | Filter names starting with substring | | charCase | string | Transform case: 'upper' or 'lower' |

random.names.lastname();                           // "Johnson"
random.names.lastname({ charCase: 'upper' });      // "WILLIAMS"

names.fullname(options)

Generate a full name (first + last). Accepts same options as firstname().

random.names.fullname();                           // "Michael Davis"
random.names.fullname({ gender: 'female' });       // "Sarah Thompson"

names.title(options)

Generate a random title (Mr, Mrs, Dr, etc.).

| Option | Type | Description | |--------|------|-------------| | gender | string | Limit to 'male', 'female', or 'nonbinary' |

random.names.title();                              // "Dr"
random.names.title({ gender: 'nonbinary' });       // "Mx"

names.email(options)

Generate a random email address.

| Option | Type | Description | |--------|------|-------------| | hasDot | boolean | Include dot in name portion | | hasPlusAddress | boolean | Include plus addressing | | charCase | string | Transform case (defaults to 'lower') | | standard | boolean | Use standard TLDs only |

random.names.email();                              // "[email protected]"
random.names.email({ hasDot: true });              // "[email protected]"
random.names.email({ hasPlusAddress: true });      // "[email protected]"

names.suffix(options)

Generate a random post-nominal suffix (PhD, MBA, etc.).

| Option | Type | Description | |--------|------|-------------| | type | string | Limit to 'doctorate', 'masters', or 'bachelors' |

random.names.suffix();                             // "MBA"
random.names.suffix({ type: 'doctorate' });        // "PhD"
random.names.suffix({ type: 'masters' });          // "MSc"

names.middleName(options)

Generate a random middle name. Accepts same options as firstname().

random.names.middleName();                         // "Elizabeth"
random.names.middleName({ gender: 'male' });       // "Robert"

Network

Generate random network-related data.

network.ip(options)

Generate a random IPv4 address.

| Option | Type | Description | |--------|------|-------------| | mask | boolean | Include CIDR notation |

random.network.ip();                               // "192.168.45.12"
random.network.ip({ mask: true });                 // "10.0.0.1/24"

network.ipv6()

Generate a random IPv6 address.

random.network.ipv6();                             // "2001:0db8:85a3:0000:0000:8a2e:0370:7334"

network.mac(options)

Generate a random MAC address.

| Option | Type | Description | |--------|------|-------------| | separator | string | Separator character (default: ':') | | uppercase | boolean | Use uppercase hex (default: false) |

random.network.mac();                              // "a1:b2:c3:d4:e5:f6"
random.network.mac({ separator: '-' });            // "a1-b2-c3-d4-e5-f6"
random.network.mac({ uppercase: true });           // "A1:B2:C3:D4:E5:F6"

network.port(options)

Generate a random port number.

| Option | Type | Description | |--------|------|-------------| | type | string | Port type: 'random', 'common', 'registered', 'dynamic' | | includeService | boolean | Return object with service name (only for 'common') |

random.network.port();                             // 45123
random.network.port({ type: 'common' });           // 443
random.network.port({ type: 'common', includeService: true }); // { port: 22, service: 'SSH' }
random.network.port({ type: 'registered' });       // 8080
random.network.port({ type: 'dynamic' });          // 52341

Numbers

Generate random numbers.

numbers.integer(options)

Generate a random integer.

| Option | Type | Description | |--------|------|-------------| | min | number | Minimum value (default: 0) | | max | number | Maximum value (default: 10000000) | | round | boolean | Round the value (default: true) | | padding | number | Zero-pad to specified length | | asString | boolean | Return as string |

random.numbers.integer();                          // 4582391
random.numbers.integer({ min: 1, max: 10 });       // 7
random.numbers.integer({ padding: 5 });            // "00042"

numbers.number(options)

Alias for integer().

numbers.float(options)

Generate a random float. Same options as integer() but round defaults to false.

random.numbers.float({ min: 0, max: 1 });          // 0.7423891

numbers.sum(options)

Generate an array of numbers that sum to a target value.

| Option | Type | Description | |--------|------|-------------| | count | number | Number of values to generate | | max | number | Target sum |

random.numbers.sum({ count: 5, max: 100 });        // [23, 18, 31, 15, 13]

Strings

Generate random strings, words, and UUIDs.

strings.uuid()

Generate a UUID v4.

random.strings.uuid();                             // "550e8400-e29b-41d4-a716-446655440000"

strings.word(options)

Generate random dictionary word(s).

| Option | Type | Description | |--------|------|-------------| | limit | number | Number of words (default: 1) | | delimiter | string | Word separator (default: '-') | | charCase | string | Transform case: 'upper', 'lower', 'sentence' |

random.strings.word();                             // "apple"
random.strings.word({ limit: 3 });                 // "apple-banana-orange"
random.strings.word({ charCase: 'upper' });        // "EXAMPLE"

strings.sentence()

Generate a random sentence from Lorem Ipsum text.

random.strings.sentence();                         // "Lorem ipsum dolor sit amet"

strings.random(options)

Generate a random string of characters.

| Option | Type | Description | |--------|------|-------------| | len | number | String length (default: 16) | | chars | string | Character set to use |

random.strings.random();                           // "aB3kL9mN2pQrS5tU"
random.strings.random({ len: 8, chars: '0123456789' }); // "48293751"

strings.block(options)

Generate a block pattern string.

| Option | Type | Description | |--------|------|-------------| | blockSize | number | Pattern of block sizes (default: 333) | | delimiter | string | Block separator (default: '-') | | chars | string | Character set |

random.strings.block();                            // "ABC-DEF-GHI"
random.strings.block({ blockSize: 4444 });         // "ABCD-EFGH-IJKL-MNOP"

strings.hash(options)

Generate a random hash-like hex string.

| Option | Type | Description | |--------|------|-------------| | type | string | Hash type: 'md5', 'sha1', 'sha256', 'sha512' | | length | number | Custom length (overrides type) |

random.strings.hash();                             // 64-char SHA256-style hash
random.strings.hash({ type: 'md5' });              // 32-char MD5-style hash
random.strings.hash({ length: 40 });               // 40-char hex string

strings.slug(options)

Generate a random URL-friendly slug.

| Option | Type | Description | |--------|------|-------------| | wordCount | number | Number of words (default: random 2-5) | | separator | string | Word separator (default: '-') |

random.strings.slug();                             // "quick-brown-fox"
random.strings.slug({ wordCount: 3 });             // "hello-world-example"

Places

Generate random location data.

places.city(options)

Generate a random city name.

| Option | Type | Description | |--------|------|-------------| | country | string | Restrict to specific country |

random.places.city();                              // "New York"
random.places.city({ country: 'UK' });             // "Manchester"

places.country()

Generate a random country name.

random.places.country();                           // "Canada"

places.countrycode()

Generate a random ISO 2-letter country code.

random.places.countrycode();                       // "US"

places.street()

Generate a random street address.

random.places.street();                            // "42 Oak Avenue"

places.state(options)

Generate a random US state or Canadian province.

| Option | Type | Description | |--------|------|-------------| | country | string | 'US' (default) or 'CA' for Canada | | abbreviated | boolean | Return 2-letter abbreviation | | full | boolean | Return object with name and abbr |

random.places.state();                             // "California"
random.places.state({ abbreviated: true });        // "CA"
random.places.state({ country: 'CA' });            // "Ontario"

places.postalCode(options)

Generate a random postal/ZIP code.

| Option | Type | Description | |--------|------|-------------| | country | string | Country code (default: 'US') |

random.places.postalCode();                        // "90210"
random.places.postalCode({ country: 'CA' });       // "K1A 0B1"
random.places.postalCode({ country: 'GB' });       // "SW1 1AA"

places.fullAddress(options)

Generate a complete address string.

| Option | Type | Description | |--------|------|-------------| | country | string | Country code (default: 'US') |

random.places.fullAddress();                       // "42 Oak Avenue, Springfield, IL, 62701"

Dates

Generate random dates and times.

dates.now()

Get the current date/time.

random.dates.now();                                // Date object

dates.date(options)

Generate a random date.

| Option | Type | Description | |--------|------|-------------| | start | string | Minimum date (UK format: DD/MM/YYYY) | | end | string | Maximum date (UK format: DD/MM/YYYY) | | format | string | Date format (default: 'UK') |

random.dates.date();                               // Random Date object
random.dates.date({ start: '01/01/2020', end: '31/12/2025' });

dates.unixtimestamp()

Generate a Unix timestamp.

random.dates.unixtimestamp();                      // 1704067200

dates.year(options)

Generate a random year. Accepts same options as date().

random.dates.year();                               // 2019

dates.month(options)

Generate a random month name.

| Option | Type | Description | |--------|------|-------------| | short | boolean | Return 3-character format |

random.dates.month();                              // "September"
random.dates.month({ short: true });               // "Sep"

dates.dayofweek(options)

Generate a random day of the week.

| Option | Type | Description | |--------|------|-------------| | short | boolean | Return 3-character format |

random.dates.dayofweek();                          // "Wednesday"
random.dates.dayofweek({ short: true });           // "Wed"

dates.day(options)

Generate a random day of the month (1-31). Accepts same options as date().

random.dates.day();                                // 15

dates.time(options)

Generate a random time string in HH:MM:SS format.

| Option | Type | Description | |--------|------|-------------| | format24 | boolean | Use 24-hour format (default: true) |

random.dates.time();                               // "14:32:07"

dates.hour(options)

Generate a random hour.

| Option | Type | Description | |--------|------|-------------| | format24 | boolean | 24-hour format 0-23 (default: true) or 12-hour 1-12 |

random.dates.hour();                               // 14
random.dates.hour({ format24: false });            // 9

dates.minute()

Generate a random minute (0-59).

random.dates.minute();                             // 42

dates.second()

Generate a random second (0-59).

random.dates.second();                             // 17

dates.isoDate(options)

Generate a random date in ISO 8601 format.

| Option | Type | Description | |--------|------|-------------| | includeTime | boolean | Include time portion (default: true) |

random.dates.isoDate();                            // "2023-07-15T14:32:07.000Z"
random.dates.isoDate({ includeTime: false });      // "2023-07-15"

dates.timezone()

Generate a random timezone identifier.

random.dates.timezone();                           // "America/New_York"

Geography

Generate random geographical coordinates.

geo.latlong()

Generate a random latitude/longitude pair.

random.geo.latlong();                              // { lat: 45.123456, long: -93.654321 }

geo.lat()

Generate a random latitude.

random.geo.lat();                                  // 45.123456

geo.long()

Generate a random longitude.

random.geo.long();                                 // -93.654321

Money

Generate random credit card and financial data.

money.ccnumber(options)

Generate a valid credit card number (Luhn-checked).

| Option | Type | Description | |--------|------|-------------| | shortName | string | Card type code | | hasHyphens | boolean | Format with hyphens |

random.money.ccnumber();                           // "4532015112830366"
random.money.ccnumber({ hasHyphens: true });       // "4532-0151-1283-0366"
random.money.ccnumber({ shortName: 'V' });         // Visa card number

Supported Card Types:

| Card Type | Code | |-----------|------| | American Express | AE | | Diners Club - Carte Blanche | DC-CB | | Diners Club - International | DC-I | | Diners Club - USA & Canada | DC | | Discover | D | | InstaPayment | IP | | JCB | JCB | | Laser | L | | Maestro | MA | | MasterCard | MC | | Visa | V | | Visa Electron | VE |

money.cctype()

Generate a random card type name.

random.money.cctype();                             // "MasterCard"

money.ccexpiry()

Generate a random expiry date (MM/YY).

random.money.ccexpiry();                           // "09/27"

money.ccstart()

Generate a random start date (MM/YY).

random.money.ccstart();                            // "03/22"

money.cvv()

Generate a random 3-digit CVV.

random.money.cvv();                                // "847"

money.cv2()

Alias for cvv().

Files

Generate random file-related data.

files.extension(options)

Generate a random file extension.

| Option | Type | Description | |--------|------|-------------| | includeDot | boolean | Include leading dot |

random.files.extension();                          // "png"
random.files.extension({ includeDot: true });      // ".jpg"

files.filename(options)

Generate a random filename.

| Option | Type | Description | |--------|------|-------------| | extension | string | Specific extension to use | | includeExtension | boolean | Include extension (default: true) |

random.files.filename();                           // "report_2023.pdf"
random.files.filename({ extension: 'txt' });       // "notes.txt"
random.files.filename({ includeExtension: false }); // "document"

files.filepath(options)

Generate a random file path.

| Option | Type | Description | |--------|------|-------------| | platform | string | 'unix' (default) or 'windows' | | depth | number | Directory depth (default: random 1-5) |

random.files.filepath();                           // "/home/data/documents/report.pdf"
random.files.filepath({ platform: 'windows' });    // "C:\\Users\\data\\file.docx"
random.files.filepath({ depth: 2 });               // "/var/log/app.log"

Phone

Generate random phone-related data.

phone.number(options)

Generate a random phone number.

| Option | Type | Description | |--------|------|-------------| | country | string | Country code (default: 'US') | | formatted | boolean | Format with separators (default: true) | | length | number | Raw digit count when unformatted |

random.phone.number();                             // "(555) 123-4567"
random.phone.number({ country: 'GB' });            // "0207 123 4567"
random.phone.number({ formatted: false });         // "5551234567"

phone.areaCode(options)

Generate a random area code.

| Option | Type | Description | |--------|------|-------------| | country | string | Country code (default: 'US') |

random.phone.areaCode();                           // "415"
random.phone.areaCode({ country: 'US' });          // "212"

phone.countryCode(options)

Generate a random international dialing code.

| Option | Type | Description | |--------|------|-------------| | country | string | Specific country code |

random.phone.countryCode();                        // "+44"
random.phone.countryCode({ country: 'US' });       // "+1"
random.phone.countryCode({ country: 'JP' });       // "+81"

phone.imei()

Generate a random 15-digit IMEI number with valid Luhn checksum.

random.phone.imei();                               // "353456789012345"

Company

Generate random company and business data.

company.name(options)

Generate a random company name.

| Option | Type | Description | |--------|------|-------------| | includeSuffix | boolean | Include LLC, Inc, etc. (default: true) | | style | string | 'combined', 'prefix', 'root', or 'person' |

random.company.name();                             // "Global Technologies Inc"
random.company.name({ includeSuffix: false });     // "Apex Solutions"
random.company.name({ style: 'person' });          // "Smith & Associates"

company.suffix()

Generate a random company suffix.

random.company.suffix();                           // "LLC"

company.industry()

Generate a random industry/sector name.

random.company.industry();                         // "Healthcare"

company.department()

Generate a random department name.

random.company.department();                       // "Engineering"

company.catchPhrase()

Generate a random business catch phrase.

random.company.catchPhrase();                      // "Leverage scalable synergies"

company.jobTitle(options)

Generate a random job title.

| Option | Type | Description | |--------|------|-------------| | level | string | 'executive', 'management', or 'individual' | | includeDepartment | boolean | Include department context |

random.company.jobTitle();                         // "Senior Developer"
random.company.jobTitle({ level: 'executive' });   // "Chief Technology Officer"
random.company.jobTitle({ level: 'management' }); // "Director"

Colors

Generate random color data.

colors.hex(options)

Generate a random hex color.

| Option | Type | Description | |--------|------|-------------| | includeHash | boolean | Include # prefix (default: true) |

random.colors.hex();                               // "#FF5733"
random.colors.hex({ includeHash: false });         // "A1B2C3"

colors.rgb(options)

Generate a random RGB color.

| Option | Type | Description | |--------|------|-------------| | format | string | 'object' (default) or 'string' |

random.colors.rgb();                               // { r: 255, g: 128, b: 64 }
random.colors.rgb({ format: 'string' });           // "rgb(255, 128, 64)"

colors.hsl(options)

Generate a random HSL color.

| Option | Type | Description | |--------|------|-------------| | format | string | 'object' (default) or 'string' |

random.colors.hsl();                               // { h: 240, s: 50, l: 75 }
random.colors.hsl({ format: 'string' });           // "hsl(240, 50%, 75%)"

colors.name(options)

Generate a random CSS color name.

| Option | Type | Description | |--------|------|-------------| | includeHex | boolean | Return object with hex value |

random.colors.name();                              // "cornflowerblue"
random.colors.name({ includeHex: true });          // { name: "coral", hex: "#FF7F50" }

Internet

Generate random internet-related data (application layer).

internet.url(options)

Generate a random URL.

| Option | Type | Description | |--------|------|-------------| | protocol | string | Protocol to use (default: 'http') | | port | number\|string | Port number, 'common' for service port, or 'random' |

random.internet.url();                             // "http://www.example.com"
random.internet.url({ protocol: 'https' });        // "https://www.example.com"
random.internet.url({ port: 8080 });               // "http://www.example.com:8080"
random.internet.url({ port: 'common' });           // "http://www.example.com:443"
random.internet.url({ port: 'random' });           // "http://www.example.com:52341"

internet.domain(options)

Generate a random domain name.

| Option | Type | Description | |--------|------|-------------| | standard | boolean | Use standard TLDs only (default: true) |

random.internet.domain();                          // "example.com"
random.internet.domain({ standard: false });       // "example.photography"

internet.tld(options)

Generate a random top-level domain.

| Option | Type | Description | |--------|------|-------------| | standard | boolean | Standard TLDs only (default: true) | | includeDot | boolean | Include leading dot (default: true) |

random.internet.tld();                             // ".com"
random.internet.tld({ includeDot: false });        // "org"

internet.username(options)

Generate a random username.

| Option | Type | Description | |--------|------|-------------| | style | string | 'mixed', 'adjective_noun', 'name_number', or 'random' | | length | number | Length for random style |

random.internet.username();                        // "cool_ninja42"
random.internet.username({ style: 'adjective_noun' }); // "swift_eagle"
random.internet.username({ style: 'name_number' }); // "john4521"

internet.password(options)

Generate a random password.

| Option | Type | Description | |--------|------|-------------| | length | number | Password length (default: 16) | | uppercase | boolean | Include uppercase (default: true) | | lowercase | boolean | Include lowercase (default: true) | | numbers | boolean | Include numbers (default: true) | | symbols | boolean | Include symbols (default: true) |

random.internet.password();                        // "Kj8#mNp2$qRs5tUv"
random.internet.password({ length: 32 });          // 32-char password
random.internet.password({ symbols: false });      // "Kj8mNp2qRs5tUvWx"

internet.userAgent()

Generate a random browser user agent string.

random.internet.userAgent();                       // "Mozilla/5.0 (Windows NT 10.0; Win64; x64)..."

internet.port(options)

Convenience alias for network.port(). See network.port for full documentation.

random.internet.port();                            // 8080
random.internet.port({ type: 'common' });          // 443

internet.httpMethod()

Generate a random HTTP method.

random.internet.httpMethod();                      // "POST"

internet.httpStatusCode(options)

Generate a random HTTP status code.

| Option | Type | Description | |--------|------|-------------| | type | string | 'informational', 'success', 'redirection', 'clientError', 'serverError' | | includeMessage | boolean | Return object with message |

random.internet.httpStatusCode();                  // 200
random.internet.httpStatusCode({ type: 'clientError' }); // 404
random.internet.httpStatusCode({ includeMessage: true }); // { code: 200, message: "OK" }

internet.mimeType()

Generate a random MIME type.

random.internet.mimeType();                        // "application/json"

Collections

Generate random arrays and pick from lists.

collections.array(options)

Generate an array of random numbers.

| Option | Type | Description | |--------|------|-------------| | limit | number | Array length (default: random 1-12) |

random.collections.array();                        // [45, 123, 78, 201, 34]
random.collections.array({ limit: 5 });            // [12, 89, 156, 23, 67]

collections.pickone(options)

Pick a random item from a delimited string.

| Option | Type | Description | |--------|------|-------------| | items | string | Delimited list of items | | delimiter | string | Delimiter (default: '|') |

random.collections.pickone({ items: 'red|green|blue' });        // "green"
random.collections.pickone({ items: 'a,b,c', delimiter: ',' }); // "b"

Truth

Generate random boolean values.

truth.boolean()

Generate a random boolean.

random.truth.boolean();                            // true

Object Parser

Generate data from object templates with placeholder tokens.

object.fromObject(methods, template)

Parse an object template and replace placeholders with random values.

const template = {
  type: 'object',
  struct: {
    name: '$fullname',
    age: '$integer{"min": 18, "max": 65}',
    email: '$email',
    active: '$boolean'
  }
};

random.object.fromObject(random, template);
// { name: "John Smith", age: 34, email: "[email protected]", active: true }

Use $$ prefix to lock a value across multiple references in the same record.

Programmatic Bulk Generation

For generating multiple records programmatically:

import { generateBulk, generateRecords } from 'random-world/lib/bulk.js';
import random from 'random-world';

// Generate 100 names
const names = generateBulk(
  () => random.names.fullname(),
  100,
  { unique: true }
);

// Generate structured records
const users = generateRecords(
  {
    id: () => random.strings.uuid(),
    name: () => random.names.fullname(),
    email: () => random.names.email(),
    age: () => random.numbers.integer({ min: 18, max: 80 })
  },
  50
);

Requirements

• Node.js >= 18.0.0

Running Tests

npm test

License

MIT