js-mock-object

The most intuitive, type-safe mock data generator for Node.js.

js-mock-object allows you to generate realistic test data using a clean, expressive builder API. It features localized dictionaries, smart address correlation, and technical generators for modern development.

✨ Features

• 🧠 Type-safe API: Full TypeScript inference out of the box.
• 🌍 Smart Addresses: Automatically correlates City, ZIP, and Country. Supports localized street patterns (e.g., "Lisa-Müller-Straße" vs "Church Square").
• 📖 Dictionary Support: Real words and sentences via gen.word() (localized).
• 🛠️ OCP Architecture: Every generator is a self-contained class, making it easy to extend.
• 📦 Zero Dependencies: Tiny footprint, maximum speed.

📦 Installation

npm install js-mock-object

🧱 Builder API Reference

Primitive Types

• gen.string(): Random alphanumeric string.
• gen.int(): Random integer.
• gen.float(): Random floating point number.
• gen.bool(): Random boolean (true/false).
• gen.uuid(): RFC4122 compliant UUID (do not use this UUID for productive use!).
• gen.binary(): Random bit string (e.g., "10101100").
• gen.rgb(): Random CSS-ready color string (e.g., "rgb(12, 255, 0)").

Date & Time

• gen.date(): Returns a native JavaScript Date object.
• gen.timestamp(): Returns a Unix timestamp in milliseconds.

Text & Dictionary (Locale-aware)

• gen.word(): Returns a single real word from the localized dictionary.
• gen.sentence(): Returns a chain of words built from random dictionary words.

Personal Data

• gen.firstName(): A random first name.
• gen.lastName(): A random last name.
• gen.fullName(): Combines first and last name.
• gen.email(): A random example email address.
• gen.phone(): A localized phone number string.

Location (Smart & Correlated)

• gen.address(countryCode?): Generates a full object:

  {
    street: string,  
    city: string,    
    zip: string,     
    country: string  
  }
  

🎯 Constraints

Chain methods to refine your requirements:

• .min(number) / .max(number)
• .length(number)
• .oneOf([...values])

🚀 Examples

Standard Usage

import { mock, gen } from "js-mock-object";

const user = mock({
  id: gen.uuid(),
  name: gen.fullName(),
  email: gen.email(),
});

The "Everything" Mock

const bigMock = mock({
  id: gen.uuid(),
  binaryCode: gen.binary().length(12),
  themeColor: gen.rgb(),
  timestamp: gen.timestamp(),
  createdAt: gen.date(),
  appointment: gen.time(),
  user: {
    fullName: gen.fullName(),
    email: gen.email(),
    phone: gen.phone()
  },
  content: {
    favoriteWord: gen.word(),
    shortBio: gen.sentence(),
  },
  locationDe: gen.address("de"),
  locationJp: gen.address("jp"),
  settings: {
    age: gen.int().min(18).max(99),
    status: gen.string().oneOf(["active", "pending", "banned"]),
    tags: [gen.string().length(5)] 
  }
}, { locale: "de" });

console.log(JSON.stringify(bigMock, null, 2));

🔁 Deterministic Seeding

One of the core strengths of js-mock-object is its ability to produce consistent results. By providing a seed, the generator will always produce the exact same data in the same order. This is essential for:

• 🧪 Reproducible Tests: Ensure your tests don't fail randomly.
• 📸 Snapshot Testing: Keep your UI snapshots consistent.
• 🐛 Bug Hunting: Recreate the exact dataset that caused an error.

How to use a Seed

Simply pass a seed (any number) into the mock options:

import { mock, gen } from "js-mock-object";

const schema = { id: gen.uuid(), name: gen.fullName() };

// This will always produce the same user
const userA = mock(schema, { seed: 12345 });
const userB = mock(schema, { seed: 12345 });

// userA and userB are now identical!