A Node.js module for generating random data. Built for usage with mock servers, testing, and data generation pipelines.
npm install random-worldimport random from 'random-world';
// Generate names
random.names.fullname(); // "Jennifer Martinez"
random.names.email(); // "john.smith@example.com"
// 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"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 -uUsage:
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
| Format | Description |
|---|---|
text |
Plain text, one value per line |
json |
JSON array |
csv |
Comma-separated values with header |
sql |
SQL INSERT statements |
# 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- Names
- Network
- Numbers
- Strings
- Places
- Dates
- Geography
- Money
- Files
- Phone
- Company
- Colors
- Internet
- Collections
- Truth
- Object Parser
Generate random names, titles, and email addresses.
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"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"Generate a full name (first + last). Accepts same options as firstname().
random.names.fullname(); // "Michael Davis"
random.names.fullname({ gender: 'female' }); // "Sarah Thompson"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"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"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"Generate a random middle name. Accepts same options as firstname().
random.names.middleName(); // "Elizabeth"
random.names.middleName({ gender: 'male' }); // "Robert"Generate random network-related data.
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"Generate a random IPv6 address.
random.network.ipv6(); // "2001:0db8:85a3:0000:0000:8a2e:0370:7334"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"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' }); // 52341Generate random numbers.
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"Alias for integer().
Generate a random float. Same options as integer() but round defaults to false.
random.numbers.float({ min: 0, max: 1 }); // 0.7423891Generate 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]Generate random strings, words, and UUIDs.
Generate a UUID v4.
random.strings.uuid(); // "550e8400-e29b-41d4-a716-446655440000"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"Generate a random sentence from Lorem Ipsum text.
random.strings.sentence(); // "Lorem ipsum dolor sit amet"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"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"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 stringGenerate 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"Generate random location data.
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"Generate a random country name.
random.places.country(); // "Canada"Generate a random ISO 2-letter country code.
random.places.countrycode(); // "US"Generate a random street address.
random.places.street(); // "42 Oak Avenue"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"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"Generate a complete address string.
| Option | Type | Description |
|---|---|---|
country |
string |
Country code (default: 'US') |
random.places.fullAddress(); // "42 Oak Avenue, Springfield, IL, 62701"Generate random dates and times.
Get the current date/time.
random.dates.now(); // Date objectGenerate 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' });Generate a Unix timestamp.
random.dates.unixtimestamp(); // 1704067200Generate a random year. Accepts same options as date().
random.dates.year(); // 2019Generate a random month name.
| Option | Type | Description |
|---|---|---|
short |
boolean |
Return 3-character format |
random.dates.month(); // "September"
random.dates.month({ short: true }); // "Sep"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"Generate a random day of the month (1-31). Accepts same options as date().
random.dates.day(); // 15Generate 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"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 }); // 9Generate a random minute (0-59).
random.dates.minute(); // 42Generate a random second (0-59).
random.dates.second(); // 17Generate 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"Generate a random timezone identifier.
random.dates.timezone(); // "America/New_York"Generate random geographical coordinates.
Generate a random latitude/longitude pair.
random.geo.latlong(); // { lat: 45.123456, long: -93.654321 }Generate a random latitude.
random.geo.lat(); // 45.123456Generate a random longitude.
random.geo.long(); // -93.654321Generate random credit card and financial data.
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 numberSupported 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 |
Generate a random card type name.
random.money.cctype(); // "MasterCard"Generate a random expiry date (MM/YY).
random.money.ccexpiry(); // "09/27"Generate a random start date (MM/YY).
random.money.ccstart(); // "03/22"Generate a random 3-digit CVV.
random.money.cvv(); // "847"Alias for cvv().
Generate random file-related data.
Generate a random file extension.
| Option | Type | Description |
|---|---|---|
includeDot |
boolean |
Include leading dot |
random.files.extension(); // "png"
random.files.extension({ includeDot: true }); // ".jpg"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"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"Generate random phone-related data.
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"Generate a random area code.
| Option | Type | Description |
|---|---|---|
country |
string |
Country code (default: 'US') |
random.phone.areaCode(); // "415"
random.phone.areaCode({ country: 'US' }); // "212"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"Generate a random 15-digit IMEI number with valid Luhn checksum.
random.phone.imei(); // "353456789012345"Generate random company and business data.
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"Generate a random company suffix.
random.company.suffix(); // "LLC"Generate a random industry/sector name.
random.company.industry(); // "Healthcare"Generate a random department name.
random.company.department(); // "Engineering"Generate a random business catch phrase.
random.company.catchPhrase(); // "Leverage scalable synergies"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"Generate random color data.
Generate a random hex color.
| Option | Type | Description |
|---|---|---|
includeHash |
boolean |
Include # prefix (default: true) |
random.colors.hex(); // "#FF5733"
random.colors.hex({ includeHash: false }); // "A1B2C3"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)"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%)"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" }Generate random internet-related data (application layer).
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"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"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"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"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"Generate a random browser user agent string.
random.internet.userAgent(); // "Mozilla/5.0 (Windows NT 10.0; Win64; x64)..."Convenience alias for network.port(). See network.port for full documentation.
random.internet.port(); // 8080
random.internet.port({ type: 'common' }); // 443Generate a random HTTP method.
random.internet.httpMethod(); // "POST"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" }Generate a random MIME type.
random.internet.mimeType(); // "application/json"Generate random arrays and pick from lists.
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]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"Generate random boolean values.
Generate a random boolean.
random.truth.boolean(); // trueGenerate data from object templates with placeholder tokens.
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: "jane@example.com", active: true }Use $$ prefix to lock a value across multiple references in the same record.
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
);- Node.js >= 18.0.0
npm testMIT