stacksjs
ts-mocker
A performance-focused and lightweight faker library for TypeScript with comprehensive locale support.
Features
- ⚡️ Performance-focused - Built with speed and efficiency in mind
- 🌍 Multi-locale Support - Complete translations for 28 languages with 22+ regional variants:
- Afrikaans (af), Arabic (ar), Azerbaijani (az), Czech (cs), Danish (da), German (de), English (en), Esperanto (eo), Spanish (es), Persian/Farsi (fa), Finnish (fi), French (fr), Hebrew (he), Hindi (hi), Italian (it), Japanese (ja), Korean (ko), Dutch (nl), Norwegian (no), Polish (pl), Portuguese (pt), Swedish (sv), Filipino (tl), Turkish (tr), Ukrainian (uk), Chinese Simplified (zh-cn), Chinese Traditional (zh-tw), Zulu (zu)
- Plus regional variants:
en-us,en-gb,en-ca,en-ie,en-in,en-za,en-gh,en-ng,en-hk,fr-ca,fr-ch,fr-be,fr-lu,fr-sn,de-at,de-ch,es-mx,pt-mz,af-za,zu-za, and more!
- 📦 Lightweight - Minimal dependencies and small bundle size
- 💪 Fully Typed - Written in TypeScript with comprehensive type definitions
- 🎯 Comprehensive Data - 16+ data categories including:
- Person (names, job titles, genders)
- Address (streets, cities, countries)
- Company (names, industries, buzzwords)
- Internet (emails, domains)
- Phone numbers (numbers)
- Food (dishes, ingredients, cuisines)
- Animals (dogs, cats, birds, fish, etc.)
- Sports (teams, athletes)
- Music (genres, artists, songs)
- Commerce (products, colors, materials)
- Books (titles, authors, publishers)
- Vehicles (manufacturers, models, types)
- Words (adjectives, verbs, nouns, etc.)
- Hacker/Tech (abbreviations, phrases)
- System (file names, file types)
- Science (elements, units, constants)
Installation
# npm
npm install ts-mocker
# pnpm
pnpm add ts-mocker
# bun
bun add ts-mocker
# yarn
yarn add ts-mockerUsage
Basic Usage
import { faker } from 'ts-mocker'
// Generate random data with default locale (English)
const name = faker.person.fullName()
const email = faker.internet.email()
const address = faker.address.city()
console.log(name) // "John Doe"
console.log(email) // "john.doe@example.com"
console.log(address) // "New York"Advanced Features
ts-mocker includes powerful advanced data generation features:
import { faker, globalProviderRegistry, ValidationRules, WeightedSelections } from 'ts-mocker'
// Conditional generation with constraints
const maleName = faker.person.firstNameAdvanced({
constraints: { gender: 'male' }
})
// Weighted selection for realistic distribution
const commonName = faker.person.firstNameAdvanced({
weighted: WeightedSelections.commonFirstNames
})
// Data validation
const validatedName = faker.person.firstNameAdvanced({
validation: {
rules: [{ validator: ValidationRules.name }],
strict: false
}
})
// Realistic relationships
const family = faker.person.family({
constraints: { country: 'United States' },
size: 4
})
const customProvider = {
name: 'Tech Company Generator',
category: 'company',
version: '1.0.0',
generate: () => 'Cloud Tech Solutions'
}
globalProviderRegistry.register(customProvider)See Advanced Features Documentation for complete details.
Using Different Locales
import { faker } from 'ts-mocker'
// Set locale globally
faker.setLocale('es') // Spanish
console.log(faker.person.fullName()) // "María García"
// Or create a new instance with a specific locale
const spanishFaker = new Faker({ locale: 'es' })
const japaneseFaker = new Faker({ locale: 'ja' })
const chineseSimplifiedFaker = new Faker({ locale: 'zh-cn' })
const chineseTraditionalFaker = new Faker({ locale: 'zh-tw' })
console.log(spanishFaker.person.fullName()) // "Carlos López"
console.log(japaneseFaker.person.fullName()) // "田中太郎"
console.log(chineseSimplifiedFaker.person.fullName()) // "王伟"
console.log(chineseTraditionalFaker.person.fullName()) // "陳小明"
// Regional variants provide localized data
const usFaker = new Faker({ locale: 'en-us' })
const ukFaker = new Faker({ locale: 'en-gb' })
const canadianFrenchFaker = new Faker({ locale: 'fr-ca' })
console.log(usFaker.address.city()) // "New York"
console.log(ukFaker.address.city()) // "London"
console.log(canadianFrenchFaker.address.city()) // "Montréal"Available Locales
af- Afrikaansar- Arabicaz- Azerbaijanics- Czechda- Danishde- Germanen- Englisheo- Esperantoes- Spanishfa- Persian/Farsifi- Finnishfr- Frenchhe- Hebrewhi- Hindiit- Italianja- Japaneseko- Koreannl- Dutchno- Norwegianpl- Polishpt- Portuguesesv- Swedishtl- Filipinotr- Turkishuk- Ukrainianzh-cn- Chinese (Simplified)zh-tw- Chinese (Traditional)zu- Zulu
Regional Variants
Many languages also have regional variants with localized data for specific countries:
English Variants:
en-us- English (United States)en-gb- English (United Kingdom)en-ca- English (Canada)en-ie- English (Ireland)en-in- English (India)en-za- English (South Africa)en-gh- English (Ghana)en-ng- English (Nigeria)en-hk- English (Hong Kong)
French Variants:
fr-ca- French (Canada)fr-ch- French (Switzerland)fr-be- French (Belgium)fr-lu- French (Luxembourg)fr-sn- French (Senegal)
German Variants:
de-at- German (Austria)de-ch- German (Switzerland)
Spanish Variants:
es-mx- Spanish (Mexico)
Portuguese Variants:
pt-mz- Portuguese (Mozambique)
Afrikaans Variants:
af-za- Afrikaans (South Africa)
Zulu Variants:
zu-za- Zulu (South Africa)
These regional variants include country-specific data such as local cities, addresses, phone formats, and cultural references.
API Examples
import { faker } from 'ts-mocker'
// Person
faker.person.firstName() // Random first name
faker.person.firstName({ gender: 'male' }) // Random male first name
faker.person.firstName({ gender: 'female' }) // Random female first name
faker.person.firstName({ gender: 'neutral' }) // Random neutral first name
faker.person.firstNameMale() // Random male first name
faker.person.firstNameFemale() // Random female first name
faker.person.firstNameNeutral() // Random neutral first name
faker.person.lastName() // Random last name
faker.person.fullName() // Random full name
faker.person.fullName({ gender: 'male' }) // Random full name with male first name
faker.person.fullName({ gender: 'female' }) // Random full name with female first name
faker.person.fullName({ prefix: true }) // Random full name with prefix
faker.person.fullName({ suffix: true }) // Random full name with suffix
faker.person.gender() // Random gender
faker.person.jobTitle() // Random job title
faker.person.prefix() // Random prefix (Mr., Mrs., etc.)
faker.person.suffix() // Random suffix (Jr., Sr., etc.)
// Address
faker.address.street() // Random street name
faker.address.city() // Random city
faker.address.state() // Random state/province
faker.address.country() // Random country
faker.address.zipCode() // Random ZIP/postal code
faker.address.direction() // Random direction (North, South, etc.)
// Company
faker.company.name() // Random company name
faker.company.industry() // Random industry
faker.company.buzzword() // Random business buzzword
// Internet
faker.internet.email() // Random email address
faker.internet.domainName() // Random domain name
faker.internet.url() // Random URL
// Phone
faker.phone.number() // Random phone number
// Food
faker.food.dish() // Random dish name
faker.food.ingredient() // Random ingredient
faker.food.cuisine() // Random cuisine type
faker.food.dessert() // Random dessert
faker.food.fruit() // Random fruit
faker.food.vegetable() // Random vegetable
faker.food.meat() // Random meat
faker.food.spice() // Random spice
// Animal
faker.animal.dog() // Random dog breed
faker.animal.cat() // Random cat breed
faker.animal.bird() // Random bird species
faker.animal.fish() // Random fish species
faker.animal.horse() // Random horse breed
faker.animal.rabbit() // Random rabbit breed
faker.animal.insect() // Random insect
// Sport
faker.sport.sport() // Random sport name
faker.sport.team() // Random team name
faker.sport.athlete() // Random athlete name
// Music
faker.music.genre() // Random music genre
faker.music.artist() // Random artist name
faker.music.song() // Random song title
faker.music.instrument() // Random instrument
// Commerce
faker.commerce.product() // Random product name
faker.commerce.adjective() // Random product adjective
faker.commerce.material() // Random material
faker.commerce.department() // Random department
faker.commerce.color() // Random color
// Book
faker.book.title() // Random book title
faker.book.author() // Random author name
faker.book.publisher() // Random publisher
faker.book.genre() // Random book genre
faker.book.series() // Random book series
faker.book.review() // Random book review
// Vehicle
faker.vehicle.manufacturer() // Random vehicle manufacturer
faker.vehicle.model() // Random vehicle model
faker.vehicle.type() // Random vehicle type
faker.vehicle.fuel() // Random fuel type
faker.vehicle.bicycle() // Random bicycle type
// Word
faker.word.adjective() // Random adjective
faker.word.adverb() // Random adverb
faker.word.conjunction() // Random conjunction
faker.word.interjection() // Random interjection
faker.word.noun() // Random noun
faker.word.preposition() // Random preposition
faker.word.verb() // Random verb
// Hacker/Tech
faker.hacker.abbreviation() // Random tech abbreviation
faker.hacker.adjective() // Random tech adjective
faker.hacker.noun() // Random tech noun
faker.hacker.verb() // Random tech verb
faker.hacker.ingverb() // Random tech -ing verb
faker.hacker.phrase() // Random tech phrase
// System
faker.system.fileName() // Random file name
faker.system.fileType() // Random file type
// Science
faker.science.chemicalElement() // Random chemical element
faker.science.unit() // Random unit of measurement
faker.science.constant() // Random scientific constant
faker.science.field() // Random scientific fieldCommand Line Interface
ts-mocker includes a powerful CLI for generating fake data from the terminal.
Installation
# Global installation
npm install -g ts-mocker
# Or use with npx
npx ts-mocker [command]Quick Examples
# Generate a random name
ts-mocker generate person fullName
# Generate 5 emails in Spanish
ts-mocker generate internet email --locale es --count 5
# Generate 10 test users as JSON
ts-mocker batch 10
# List all available categories
ts-mocker categories
# List methods for a category
ts-mocker methods foodAvailable Commands
generate <category> <method>- Generate random databatch <count>- Generate multiple complete recordscategories- List all available categoriesmethods <category>- List methods for a categorylocales- List all supported localesseed <seed>- Generate reproducible data with a seedversion- Show version
Options
--locale <locale>- Use a specific locale (af, ar, az, cs, da, de, en, eo, es, fa, fi, fr, he, hi, it, ja, ko, nl, no, pl, pt, sv, tl, tr, uk, zh-cn, zh-tw, zu)--count <count>- Number of items to generate--seed <seed>- Seed for reproducible results--json- Output as JSON--template <template>- Template for batch: user, product, address, company
More Examples
# Reproducible data with seed
ts-mocker generate person fullName --seed 12345
# Generate products in JSON
ts-mocker batch 5 --template product --json
# Generate Japanese food items
ts-mocker generate food dish --locale ja --count 10
# Save to file
ts-mocker batch 100 --template user > users.jsonSee the CLI documentation for complete details.
Performance Benchmarks
ts-mocker is designed for performance and efficiency:
Performance:
- ✅ 9 out of 9 benchmarks won
- ⚡ 9.28x faster than @faker-js/faker on average
- 🚀 34.04M ops/s for country generation
- 🔑 20.50M ops/s for UUID generation (41.2x faster!)
- 📧 10.44M ops/s for email generation (15.5x faster!)
- 📊 6.90ms to generate 10,000 complex user objects
Package Size:
- 📦 174 KB published (core package only)
- 🎯 24.7x smaller than @faker-js/faker (4.29 MB)
- 🪶 38 files vs 231 in @faker-js/faker
- 🔌 Modular locales - install only what you need
Quick Comparison
| Operation | ts-mocker | @faker-js/faker | Speedup |
|---|---|---|---|
| UUID Generation | 20.50M ops/s | 497.69K ops/s | 41.2x faster |
| Full Name Generation | 24.76M ops/s | 678.37K ops/s | 36.5x faster |
| Country Generation | 34.04M ops/s | 1.05M ops/s | 32.4x faster |
| Email Generation | 10.44M ops/s | 674.02K ops/s | 15.5x faster |
| Complex Objects (10k) | 6.90ms | 64.04ms | 9.3x faster |
Running Benchmarks
# Run all benchmarks
bun run bench
# Results are compared against:
# - @faker-js/faker
# - chance
# - casual
# - @ngneat/falsoDetailed Documentation:
- 📊 BENCHMARKS.md - Complete performance results and methodology
Testing
bun testDevelopment
# Install dependencies
bun install
# Run tests
bun test
# Build the library
bun run build
# Lint code
bun run lintChangelog
Please see our releases page for more information on what has changed recently.
Contributing
We welcome contributions! Please see CONTRIBUTING for details.
Community
For help, discussion about best practices, or any other conversation that would benefit from being searchable:
For casual chit-chat with others using this package:
Join the Stacks Discord Server
Postcardware
“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.
Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎
Sponsors
We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.
License
The MIT License (MIT). Please see LICENSE for more information.
Made with 💙