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

importrandomfrom'random-world';// Generate namesrandom.names.fullname();// "Jennifer Martinez"random.names.email();// "john.smith@example.com"// Generate numbersrandom.numbers.integer({min: 1,max: 100});// 42// Generate network datarandom.network.ip();// "192.168.1.45"random.network.mac();// "a1:b2:c3:d4:e5:f6"// Generate UUIDsrandom.strings.uuid();// "550e8400-e29b-41d4-a716-446655440000"// Generate company datarandom.company.name();// "Global Technologies Inc"random.company.jobTitle();// "Senior Developer"// Generate phone numbersrandom.phone.number();// "(555) 123-4567"random.phone.imei();// "353456789012345"// Generate colorsrandom.colors.hex();// "#FF5733"random.colors.name();// "cornflowerblue"// Generate internet datarandom.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();// "johnsmith@example.com"random.names.email({hasDot: true});// "john.smith@example.com"random.names.email({hasPlusAddress: true});// "john+tag@example.com"

`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();// 45123random.network.port({type: 'common'});// 443random.network.port({type: 'common',includeService: true});// { port: 22, service: 'SSH' }random.network.port({type: 'registered'});// 8080random.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();// 4582391random.numbers.integer({min: 1,max: 10});// 7random.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 hashrandom.strings.hash({type: 'md5'});// 32-char MD5-style hashrandom.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 objectrandom.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();// 14random.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 passwordrandom.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();// 8080random.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();// 200random.internet.httpStatusCode({type: 'clientError'});// 404random.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.

consttemplate={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: "jane@example.com", 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';importrandomfrom'random-world';// Generate 100 namesconstnames=generateBulk(()=>random.names.fullname(),100,{unique: true});// Generate structured recordsconstusers=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

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
bin		bin
lib		lib
tests		tests
types		types
.gitignore		.gitignore
.travis.yml		.travis.yml
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

Random World

Installation

Quick Start

As a Library

As a CLI

CLI Reference

Output Formats

Examples

Modules

Names

names.firstname(options)

names.lastname(options)

names.fullname(options)

names.title(options)

names.email(options)

names.suffix(options)

names.middleName(options)

Network

network.ip(options)

network.ipv6()

network.mac(options)

network.port(options)

Numbers

numbers.integer(options)

numbers.number(options)

numbers.float(options)

numbers.sum(options)

Strings

strings.uuid()

strings.word(options)

strings.sentence()

strings.random(options)

strings.block(options)

strings.hash(options)

strings.slug(options)