nx-mock-data-generator

A TypeScript library and CLI tool for generating mock data with valid foreign key relationships. Ensures 100% referential integrity by using dependency graph resolution and ID pool management.

Features

• 🔗 Valid Relationships: Generates foreign keys that always reference existing records
• 📊 Dependency Resolution: Automatically determines generation order using topological sort
• 🎯 Flexible Field Types: Support for UUIDs, entity names, numbers, strings, booleans, dates
• 📁 File Output: Writes collections to separate JSON files
• 🛠️ CLI & Library: Use as a command-line tool or import as a TypeScript library
• ✅ Type Safety: Full TypeScript support with comprehensive type definitions

Installation

npm install nx-mock-data-generator

Quick Start

CLI Usage

1. Create a configuration file:

{
  "collections": [
    {
      "name": "users",
      "count": 5,
      "fields": [
        { "name": "_id", "type": "uuid" },
        { "name": "username", "type": "entityName", "options": { "entityType": "User" } }
      ]
    },
    {
      "name": "orders",
      "count": 20,
      "fields": [
        { "name": "_id", "type": "uuid" },
        { "name": "orderNumber", "type": "entityName", "options": { "entityType": "Order" } },
        { "name": "userId", "type": "foreignKey", "options": { "references": "users" } },
        { "name": "amount", "type": "number", "options": { "min": 10, "max": 1000 } }
      ]
    }
  ]
}

2. Generate mock data:

nx-mock-gen --config config.json --output ./mock-data

Library Usage

import { generateMockData } from 'nx-mock-data-generator';

const config = {
  collections: [
    {
      name: 'users',
      count: 5,
      fields: [
        { name: '_id', type: 'uuid' },
        { name: 'username', type: 'entityName', options: { entityType: 'User' } }
      ]
    },
    {
      name: 'orders',
      count: 20,
      fields: [
        { name: '_id', type: 'uuid' },
        { name: 'userId', type: 'foreignKey', options: { references: 'users' } },
        { name: 'amount', type: 'number', options: { min: 10, max: 1000 } }
      ]
    }
  ]
};

const data = await generateMockData(config);
console.log(data.users); // Array of user records
console.log(data.orders); // Array of order records

Field Types

UUID/ID

{ "name": "_id", "type": "uuid" }

Entity Name

{ 
  "name": "username", 
  "type": "entityName", 
  "options": { 
    "entityType": "User",
    "numberFormat": "sequential"  // or "random"
  } 
}

Foreign Key

{ 
  "name": "userId", 
  "type": "foreignKey", 
  "options": { 
    "references": "users",
    "nullable": true,
    "nullProbability": 0.1
  } 
}

Number

{ 
  "name": "price", 
  "type": "number", 
  "options": { 
    "min": 10, 
    "max": 1000, 
    "decimal": true 
  } 
}

String

{ 
  "name": "description", 
  "type": "string", 
  "options": { 
    "length": 50 
  } 
}

Boolean

{ "name": "isActive", "type": "boolean" }

Date

{ 
  "name": "createdAt", 
  "type": "date", 
  "options": { 
    "startDate": "2020-01-01", 
    "endDate": "2024-01-01" 
  } 
}

Advanced Features

Manual Generation Order

Override automatic dependency resolution:

{
  "name": "users",
  "generateOrder": 1,
  "count": 5,
  "fields": [...]
}

Nullable Foreign Keys

Generate some null foreign keys for realistic data:

{
  "name": "parentId",
  "type": "foreignKey",
  "options": {
    "references": "categories",
    "nullable": true,
    "nullProbability": 0.3
  }
}

Random Entity Names

Generate random entity names instead of sequential:

{
  "name": "productCode",
  "type": "entityName",
  "options": {
    "entityType": "PROD",
    "numberFormat": "random",
    "numberRange": { "min": 1000, "max": 9999 }
  }
}

CLI Options

nx-mock-gen [options] <config-file>

Options:
  -c, --config <file>    Configuration file path (required)
  -o, --output <dir>     Output directory (default: ./output)
  -h, --help            Show help message

How It Works

1. Dependency Analysis: Analyzes foreign key relationships to build a dependency graph
2. Topological Sort: Determines the correct generation order using Kahn's algorithm
3. ID Pool Management: Maintains pools of valid IDs for each collection
4. Sequential Generation: Generates collections in dependency order
5. Referential Integrity: Every foreign key references a real, existing record

Example Output

users.json:

[
  { "_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "username": "User 1" },
  { "_id": "b2c3d4e5-f6g7-8901-bcde-f23456789012", "username": "User 2" }
]

orders.json:

[
  { "_id": "c3d4e5f6-g7h8-9012-cdef-345678901234", "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "amount": 245.67 },
  { "_id": "d4e5f6g7-h8i9-0123-def0-456789012345", "userId": "b2c3d4e5-f6g7-8901-bcde-f23456789012", "amount": 89.32 }
]

Notice how every userId in orders references a valid user ID!

Error Handling

The generator provides clear error messages for common issues:

• Circular dependencies
• Missing referenced collections
• Invalid field configurations
• File write errors

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.