Mock JSON Data Generator

Generate millions to billions of records with constant memory usage - no crashes, no limits.

A zero-dependency mock data generator with a simple CLI and powerful schema-based generation. Generate realistic test data with 12+ built-in data types, support for 100+ million records, and a simple CLI tool.

💡 What makes this different?

Most mock libraries generate one object at a time.

This generator is designed for:

• Bulk data generation (millions to billions of records)
• Streaming without memory overhead
• CLI-first workflows for quick dataset creation

If you need realistic data at scale — this is built for that.

✨ Features

• 🎯 12+ Built-in Data Types - string, number, boolean, email, date, uuid, phone, url, address, name, color, lorem
• 🚀 CLI Tool - Generate data from command line
• 📦 Zero Dependencies - Lightweight (~15KB)
• 💪 TypeScript Support - Full type definitions
• ⚡ High Performance - 100K records in ~500ms
• 🌊 Memory Efficient - Handle millions of records with constant memory

📦 Installation

npm install mock-json-data-generator

🚀 Quick Start

Generate 10 million users without crashing your system

Using CLI (command: mockgen)

1. Create a schema file schema.json:

{
  "id": "uuid",
  "name": "string",
  "email": "email",
  "age": {
    "type": "number",
    "options": { "min": 18, "max": 80 }
  }
}

2. Generate data:

# Generate 1000 records
npx mockgen schema.json --count 1000 --out data.json

# Generate CSV
npx mockgen schema.json --count 500 --out users.csv --format csv

# Pretty JSON
npx mockgen schema.json --count 100 --out users.json --pretty

# Generate 10 million records (memory efficient!)
npx mockgen schema.json --count 10000000 --out users.json

Using in Code

const { generateMock } = require('mock-json-data-generator');

// Generate a single user
const user = generateMock({
  id: 'uuid',
  name: 'string',
  email: 'email',
  age: { type: 'number', options: { min: 18, max: 80 } }
});

// Generate 100 users
const users = generateMock({
  id: 'uuid',
  name: 'string',
  email: 'email'
}, 100);

🤔 Why not Faker?

| Feature | This Package | Faker | |--------|--------------------------|-------| | Schema-based generation | ✅ | ⚠️ Limited | | CLI support | ✅ | ❌ | | Streaming large datasets | ✅ | ❌ | | Memory efficient | ✅ | ⚠️ Requires custom handling | | Generate 100M+ records | ✅ | ❌ |

📖 Table of Contents

• CLI Usage
• Basic Data Types
• Simple Examples
• Data Type Options
• Advanced Features
• Large Datasets
• API Reference
• Performance

🖥️ CLI Usage

Installation

# Global installation
npm install -g mock-json-data-generator

# Or use with npx (no installation needed)
npx mockgen schema.json --count 1000

Commands

# Basic usage
mockgen <schema-file> [options]

# Options:
--count <n>      Number of records (default: 1)
--out <file>     Output file (default: output.json)
--format <type>  Format: json, csv, ndjson (default: json)
--pretty         Pretty print JSON
--help           Show help

Examples

# Generate 1 record
mockgen schema.json

# Generate 1000 records to data.json
mockgen schema.json --count 1000 --out data.json

# Generate CSV file
mockgen schema.json --count 500 --out users.csv --format csv

# Generate with pretty JSON
mockgen schema.json --count 100 --pretty

# Generate NDJSON (newline-delimited JSON)
mockgen schema.json --count 1000 --out data.ndjson --format ndjson

Schema File Format

Create a JSON file with your data structure:

{
  "id": "uuid",
  "username": "string",
  "email": "email",
  "age": {
    "type": "number",
    "options": { "min": 18, "max": 80 }
  },
  "isActive": "boolean",
  "createdAt": {
    "type": "date",
    "options": { "format": "iso" }
  }
}

🎨 Basic Data Types

String

{ name: 'string' }
// Output: "Alex", "Emma", "John", etc.

Number

{ age: 'number' }
// Output: 42, 17, 89, etc. (0-100)

Boolean

{ isActive: 'boolean' }
// Output: true or false

Email

{ email: 'email' }
// Output: "[email protected]"

UUID

{ id: 'uuid' }
// Output: "550e8400-e29b-41d4-a716-446655440000"

Date

{ createdAt: 'date' }
// Output: "2024-04-10T15:30:00.000Z"

Phone

{ phone: 'phone' }
// Output: "555-123-4567"

URL

{ website: 'url' }
// Output: "https://example.com"

Address

{ address: 'address' }
// Output: "123 Main St, New York, NY 10001"

Name

{ fullName: 'name' }
// Output: "John Smith"

Color

{ color: 'color' }
// Output: "#ff5733"

Lorem (Text)

{ description: 'lorem' }
// Output: "lorem ipsum dolor sit amet..."

💡 Simple Examples

User Profile

const user = generateMock({
  id: 'uuid',
  name: 'string',
  email: 'email',
  age: { type: 'number', options: { min: 18, max: 80 } },
  isActive: 'boolean'
});

/* Output:
{
  id: "550e8400-e29b-41d4-a716-446655440000",
  name: "Alex",
  email: "[email protected]",
  age: 42,
  isActive: true
}
*/

Product

const product = generateMock({
  id: 'uuid',
  name: 'string',
  price: { type: 'number', options: { min: 10, max: 1000, decimals: 2 } },
  inStock: 'boolean'
});

Blog Post

const post = generateMock({
  id: 'uuid',
  title: 'string',
  content: { type: 'lorem', options: { sentences: 3 } },
  author: 'string',
  publishedAt: 'date'
});

Multiple Records

// Generate 100 users
const users = generateMock({
  id: 'uuid',
  name: 'string',
  email: 'email'
}, 100);

// Returns array of 100 users

⚙️ Data Type Options

String Options

// Custom length
{ password: { type: 'string', options: { length: 16 } } }

// Character set
{ code: { type: 'string', options: { charset: 'alphanumeric' } } }
// Charsets: 'alpha', 'numeric', 'alphanumeric', 'hex', 'special'

// Pick from list
{ status: { type: 'string', options: { pool: ['active', 'inactive'] } } }

Number Options

// Min and max
{ age: { type: 'number', options: { min: 18, max: 80 } } }

// Decimals
{ price: { type: 'number', options: { min: 10, max: 1000, decimals: 2 } } }

Boolean Options

// Probability (0-1)
{ isPremium: { type: 'boolean', options: { probability: 0.2 } } }
// 20% chance of true

Email Options

// Custom domain
{ email: { type: 'email', options: { domain: 'mycompany.com' } } }

Date Options

// Date range
{ birthDate: { 
  type: 'date', 
  options: { 
    min: '1990-01-01', 
    max: '2005-12-31',
    format: 'date'  // 'iso', 'date', 'time', 'timestamp'
  } 
} }

Phone Options

// Country format
{ phone: { type: 'phone', options: { format: 'us' } } }
// Formats: 'us', 'uk', 'india'

// With country code
{ phone: { type: 'phone', options: { includeCountryCode: true } } }

Name Options

// First name only
{ firstName: { type: 'name', options: { format: 'first' } } }

// Last name only
{ lastName: { type: 'name', options: { format: 'last' } } }

// Full name
{ fullName: { type: 'name', options: { format: 'full' } } }

Color Options

// Hex color
{ color: { type: 'color', options: { format: 'hex' } } }
// Output: "#ff5733"

// RGB
{ color: { type: 'color', options: { format: 'rgb' } } }
// Output: "rgb(255, 87, 51)"

// Formats: 'hex', 'rgb', 'rgba', 'name'

Lorem Options

// Number of words
{ text: { type: 'lorem', options: { words: 5 } } }

// Number of sentences
{ description: { type: 'lorem', options: { sentences: 2 } } }

// Number of paragraphs
{ content: { type: 'lorem', options: { paragraphs: 3 } } }

🔥 Advanced Features

Nested Objects

const user = generateMock({
  id: 'uuid',
  name: 'string',
  profile: {
    bio: { type: 'lorem', options: { sentences: 2 } },
    settings: {
      theme: 'string',
      notifications: 'boolean'
    }
  }
});

Arrays

const post = generateMock({
  id: 'uuid',
  title: 'string',
  tags: ['string']  // Array of strings
});

Pick from List (oneOf)

const product = generateMock({
  name: 'string',
  category: { type: 'string', oneOf: ['Electronics', 'Clothing', 'Food'] },
  status: { type: 'string', oneOf: ['active', 'inactive', 'pending'] }
});

Transform Values

const user = generateMock({
  firstName: { type: 'name', options: { format: 'first' } },
  username: {
    type: 'name',
    options: { format: 'first' },
    transform: (name) => name.toLowerCase() + Math.floor(Math.random() * 1000)
  }
});
// username: "john742"

Nullable Fields

const user = generateMock({
  name: 'string',
  middleName: {
    type: 'string',
    nullable: true,
    nullProbability: 0.5  // 50% chance of null
  }
});

Conditional Fields

const user = generateMock({
  isPremium: 'boolean',
  premiumFeatures: {
    type: 'string',
    oneOf: ['feature1', 'feature2'],
    condition: (context) => context.isPremium === true
  }
}, 10);

// premiumFeatures only exists if isPremium is true

Unique Values

const users = generateMock({
  id: { type: 'uuid', unique: true },
  email: { type: 'email', unique: true }
}, 100);
// All IDs and emails will be unique

Custom Generator

const { registerGenerator, generateMock } = require('mock-json-data-generator');

registerGenerator('customId', (options) => {
  const { prefix = 'ID' } = options;
  return `${prefix}-${Date.now()}-${Math.floor(Math.random() * 1000)}`;
});

const data = generateMock({
  id: { type: 'customId', options: { prefix: 'USER' } }
});
// id: "USER-1234567890-742"

📊 Large Datasets

For Small Datasets (< 100K records)

const users = generateMock(schema, 100000);
// Fast, stores all in memory

For Large Datasets (100K - 100M+ records)

const { generateMockIterator } = require('mock-json-data-generator');

// Memory-efficient iterator
const iterator = generateMockIterator(schema, 10000000);

for (const user of iterator) {
  // Process one at a time
  console.log(user);
}

For Async Operations

const { generateMockStream } = require('mock-json-data-generator');

const stream = generateMockStream(schema, {
  count: 5000000,
  batchSize: 1000,
  onBatch: async (batch) => {
    await db.insertMany(batch);
  }
});

for await (const batch of stream) {
  // Process batches
}

Write to Files

const { generateMockIterator, writeToJSONFile, writeToCSVFile } = require('mock-json-data-generator');

// Write to JSON
const iterator = generateMockIterator(schema, 1000000);
await writeToJSONFile('output.json', iterator, {
  pretty: true,
  onProgress: (count) => console.log(`Written ${count} records`)
});

// Write to CSV
const iterator2 = generateMockIterator(schema, 1000000);
await writeToCSVFile('output.csv', iterator2);

📚 API Reference

generateMock(schema, count?)

Generate mock data based on schema.

const data = generateMock(schema, 100);

Parameters:

• schema - Data structure definition
• count - Number of items (default: 1)

Returns: Single object or array

generateMockIterator(schema, count?)

Memory-efficient generator for large datasets.

const iterator = generateMockIterator(schema, 1000000);
for (const item of iterator) {
  // Process item
}

Parameters:

• schema - Data structure definition
• count - Number of items (default: 1)

Returns: Generator that yields items one at a time

generateMockStream(schema, options?)

Async stream with batching.

const stream = generateMockStream(schema, {
  count: 1000000,
  batchSize: 1000,
  onBatch: async (batch) => {
    await processBatch(batch);
  }
});

Parameters:

• schema - Data structure definition
• options.count - Number of items
• options.batchSize - Items per batch (default: 1000)
• options.onBatch - Async callback for each batch

Returns: Async iterable

writeToJSONFile(filePath, iterator, options?)

Write data to JSON file with streaming.

await writeToJSONFile('output.json', iterator, {
  pretty: true,
  onProgress: (count) => console.log(count)
});

writeToCSVFile(filePath, iterator, options?)

Write data to CSV file with streaming.

await writeToCSVFile('output.csv', iterator, {
  headers: ['id', 'name', 'email']
});

writeToNDJSONFile(filePath, iterator, options?)

Write data to NDJSON file with streaming.

await writeToNDJSONFile('output.ndjson', iterator);

registerGenerator(name, generatorFn)

Register custom data generator.

registerGenerator('customType', (options) => {
  return 'custom-value';
});

⚡ Performance

| Records | Method | Time | Memory | |---------|--------|------|--------| | 1,000 | Standard | ~4ms | 5 MB | | 50,000 | Standard | ~110ms | 27 MB | | 100,000 | Standard | ~500ms | 50 MB | | 500,000 | Iterator | ~700ms | 24 MB | | 1,000,000 | Iterator | ~5s | 15 MB | | 10,000,000 | Iterator | ~50s | 15 MB | | 100,000,000 | Iterator | ~8 min | 15 MB |

Recommendations:

• Use generateMock() for < 100K records
• Use generateMockIterator() for 100K - 100M+ records
• Use generateMockStream() for async operations
• Use CLI or file writers for exporting data

💻 TypeScript

Full TypeScript support included:

import { generateMock } from 'mock-json-data-generator';

interface User {
  id: string;
  name: string;
  email: string;
}

const users = generateMock<User[]>({
  id: 'uuid',
  name: 'string',
  email: 'email'
}, 100);

📄 License

MIT License - see LICENSE file for details.

Made for developers who need realistic mock data fast 🚀