@jsonjoy.com/json-random/README.md

Random JSON generation, structured JSON by schema generation, no dependencies.

# `json-random`

A fast, flexible random JSON generation library with zero dependencies. Generate random JSON data for testing, development, and prototyping with powerful template-based schemas or simple randomization.

## Features

- **Fast & Lightweight**: Zero dependencies, optimized for performance
- **Template-Based Generation**: Create structured JSON following schemas
- **Flexible Randomization**: Control probabilities, types, and structure
- **Deterministic Mode**: Reproducible random generation with seeds
- **String Token System**: Powerful pattern-based string generation
- **TypeScript Support**: Full type definitions included

## Installation

```bash
npm install @jsonjoy.com/json-random
```

## Quick Start

```typescript
import { RandomJson, TemplateJson, randomString, deterministic } from '@jsonjoy.com/json-random';

// Generate random JSON
const randomData = RandomJson.generate();

// Generate structured JSON from template
const userData = TemplateJson.gen(['obj', [
  ['id', ['int', 1, 1000]],
  ['name', ['str', ['list', ['pick', 'John', 'Jane', 'Bob'], ' ', ['pick', 'Doe', 'Smith']]]],
  ['active', 'bool']
]]);

// Generate random strings with patterns
const email = randomString(['list', 
  ['pick', 'user', 'admin', 'test'], 
  '@', 
  ['pick', 'example.com', 'test.org']
]);
```

## API Reference

### RandomJson

The `RandomJson` class provides methods for generating random JSON data with configurable options.

#### `RandomJson.generate(options?: RandomJsonOptions): unknown`

Generates a random JSON object with the specified options.

```typescript
interface RandomJsonOptions {
  rootNode?: 'object' | 'array' | 'string';
  nodeCount?: number;
  odds?: NodeOdds;
  strings?: Token;
}

interface NodeOdds {
  null: number;
  boolean: number;
  number: number;
  string: number;
  binary: number;
  array: number;
  object: number;
}
```

**Examples:**

```typescript
// Basic random JSON (default: object with ~32 nodes)
const basic = RandomJson.generate();

// Smaller JSON with 5 nodes
const small = RandomJson.generate({ nodeCount: 5 });

// Force root to be an array
const arrayRoot = RandomJson.generate({ 
  rootNode: 'array',
  nodeCount: 3 
});

// Customize node type probabilities
const stringHeavy = RandomJson.generate({
  nodeCount: 10,
  odds: {
    null: 1,
    boolean: 1,
    number: 2,
    string: 20,    // Much higher probability for strings
    binary: 0,
    array: 2,
    object: 5
  }
});

// Use custom string patterns
const customStrings = RandomJson.generate({
  nodeCount: 5,
  strings: ['pick', 'alpha', 'beta', 'gamma', 'delta']
});
```

#### Static Generation Methods

Generate specific JSON types directly:

```typescript
// Generate random string (default length: 1-16 chars)
const str = RandomJson.genString();
const longStr = RandomJson.genString(50);

// Generate random number
const num = RandomJson.genNumber();

// Generate random boolean
const bool = RandomJson.genBoolean();

// Generate random array
const arr = RandomJson.genArray();
const customArr = RandomJson.genArray({
  nodeCount: 3,
  odds: { string: 10, number: 5, boolean: 1, null: 0, array: 0, object: 0, binary: 0 }
});

// Generate random object
const obj = RandomJson.genObject();
const customObj = RandomJson.genObject({
  nodeCount: 4,
  odds: { string: 8, number: 8, boolean: 2, null: 1, array: 1, object: 1, binary: 0 }
});

// Generate random binary data
const binary = RandomJson.genBinary();
const largeBinary = RandomJson.genBinary(100);
```

### TemplateJson

The `TemplateJson` class generates JSON data following structured templates, perfect for creating realistic test data.

#### `TemplateJson.gen(template?: Template, opts?: TemplateJsonOpts): unknown`

Generates JSON following the specified template.

```typescript
interface TemplateJsonOpts {
  maxNodes?: number; // Soft limit on total nodes generated (default: 100)
}
```

#### Template Types

Templates define the structure and type of generated data:

##### Basic Types

```typescript
// Shorthand templates
TemplateJson.gen('str');    // Random string
TemplateJson.gen('int');    // Random integer
TemplateJson.gen('float');  // Random float
TemplateJson.gen('num');    // Random number (int or float)
TemplateJson.gen('bool');   // Random boolean
TemplateJson.gen('nil');    // null value

// Type-specific templates
TemplateJson.gen(['str', tokenPattern]);           // String with pattern
TemplateJson.gen(['int', min, max]);              // Integer in range
TemplateJson.gen(['float', min, max]);            // Float in range
TemplateJson.gen(['bool', fixedValue]);           // Fixed or random boolean
TemplateJson.gen(['lit', anyValue]);              // Literal value (cloned)
```

**Examples:**

```typescript
// Strings with patterns
const greeting = TemplateJson.gen(['str', ['list', 
  ['pick', 'Hello', 'Hi', 'Hey'], 
  ' ', 
  ['pick', 'World', 'There']
]]);

// Numbers in ranges
const age = TemplateJson.gen(['int', 18, 100]);
const price = TemplateJson.gen(['float', 0.01, 999.99]);
const score = TemplateJson.gen(['num', 0, 100]);

// Fixed values
const isActive = TemplateJson.gen(['bool', true]);
const userId = TemplateJson.gen(['lit', 'user_12345']);
```

##### Array Templates

```typescript
type ArrayTemplate = [
  'arr',
  min?,        // Minimum length (default: 0)
  max?,        // Maximum length (default: 5)  
  template?,   // Template for items
  head?,       // Fixed items at start
  tail?        // Fixed items at end
];
```

**Examples:**

```typescript
// Basic arrays
const numbers = TemplateJson.gen(['arr', 2, 5, 'int']);
const mixed = TemplateJson.gen(['arr', 1, 3]);

// Arrays with head/tail
const coords = TemplateJson.gen(['arr', 0, 0, null, 
  [['float', -180, 180], ['float', -90, 90]], // head: [longitude, latitude]
  [['lit', 'WGS84']]                          // tail: coordinate system
]);

// Nested arrays
const matrix = TemplateJson.gen(['arr', 2, 3, 
  ['arr', 2, 3, ['int', 0, 10]]
]);
```

##### Object Templates

```typescript
type ObjectTemplate = [
  'obj',
  fields?  // Array of field definitions
];

type ObjectTemplateField = [
  key,           // Key name (string or Token)
  valueTemplate, // Template for the value
  optionality?   // Probability of omission (0 = required, 1 = always omit)
];
```

**Examples:**

```typescript
// User profile
const user = TemplateJson.gen(['obj', [
  ['id', ['int', 1, 10000]],
  ['username', ['str', ['list', 
    ['pick', 'user', 'admin', 'guest'], 
    ['char', 48, 57, 4] // 4 digits
  ]]],
  ['email', ['str', ['list',
    ['repeat', 3, 10, ['char', 97, 122]], // 3-10 lowercase letters
    '@',
    ['pick', 'example.com', 'test.org', 'demo.net']
  ]]],
  ['age', ['int', 18, 120]],
  ['isActive', 'bool'],
  ['profile', ['obj', [
    ['bio', ['str', ['repeat', 10, 50, ['char', 32, 126]]]],
    ['avatar', ['str', ['list', 'https://avatar.example.com/', ['char', 48, 57, 8]]], 0.3]  // 30% chance to omit
  ]]]
]]);

// API Response
const apiResponse = TemplateJson.gen(['obj', [
  ['status', ['pick', 'success', 'error']],
  ['timestamp', ['int', 1640000000, 1700000000]],
  ['data', ['arr', 0, 10, ['obj', [
    ['id', 'int'],
    ['value', 'str']
  ]]]]
]]);
```

##### Map Templates

Generate key-value maps where all values follow the same template:

```typescript
type MapTemplate = [
  'map',
  keyToken?,    // Token for generating keys
  valueTemplate?, // Template for values
  min?,         // Minimum entries (default: 0)
  max?          // Maximum entries (default: 5)
];
```

**Examples:**

```typescript
// Configuration map
const config = TemplateJson.gen(['map',
  ['pick', 'timeout', 'retries', 'cache_ttl', 'max_connections'],
  ['int', 1, 3600],
  3, 5
]);

// User permissions
const permissions = TemplateJson.gen(['map',
  ['list', 'can_', ['pick', 'read', 'write', 'delete', 'admin']],
  'bool',
  2, 6
]);

// Localization strings
const translations = TemplateJson.gen(['map',
  ['pick', 'welcome', 'goodbye', 'error', 'success', 'loading'],
  ['str', ['repeat', 5, 20, ['char', 32, 126]]],
  3, 8
]);
```

##### Union Templates (Or)

Choose randomly from multiple template options:

```typescript
// Mixed data types
const mixedValue = TemplateJson.gen(['or', 'str', 'int', 'bool']);

// Different user types
const user = TemplateJson.gen(['or',
  ['obj', [['type', ['lit', 'admin']], ['permissions', ['lit', 'all']]]],
  ['obj', [['type', ['lit', 'user']], ['level', ['int', 1, 5]]]],
  ['obj', [['type', ['lit', 'guest']], ['expires', 'int']]]
]);
```

##### Recursive Templates

Create self-referencing structures:

```typescript
// Tree structure
const tree = (): Template => ['obj', [
  ['value', 'int'],
  ['left', tree, 0.3],   // 30% chance of left child
  ['right', tree, 0.3]   // 30% chance of right child
]];

const treeData = TemplateJson.gen(tree);

// Nested comments
const comment = (): Template => ['obj', [
  ['id', 'int'],
  ['text', 'str'],
  ['author', 'str'],
  ['replies', ['arr', 0, 3, comment, [], []], 0.4] // 40% chance of replies
]];

const commentThread = TemplateJson.gen(comment);
```

### String Token System

The `randomString` function and string templates use a powerful token system for pattern-based string generation.

#### `randomString(token: Token): string`

```typescript
type Token = TokenLiteral | TokenPick | TokenRepeat | TokenChar | TokenList;
```

#### Token Types

##### `TokenLiteral` - Static strings
```typescript
randomString('Hello');  // Always returns "Hello"
```

##### `TokenPick` - Choose randomly from options
```typescript
randomString(['pick', 'red', 'green', 'blue']);
// Returns one of: "red", "green", "blue"

randomString(['pick', 
  'small', 'medium', 'large', 'extra-large'
]);
```

##### `TokenRepeat` - Repeat patterns
```typescript
randomString(['repeat', 3, 5, 'X']);
// Returns 3-5 X's: "XXX", "XXXX", or "XXXXX"

randomString(['repeat', 2, 4, ['pick', 'A', 'B']]);
// Returns 2-4 random A's or B's: "AB", "BAA", "ABBA", etc.
```

##### `TokenChar` - Character ranges
```typescript
randomString(['char', 65, 90]);     // Single random A-Z
randomString(['char', 97, 122, 5]); // 5 random a-z chars
randomString(['char', 48, 57, 3]);  // 3 random digits

// Unicode ranges
randomString(['char', 0x1F600, 0x1F64F]); // Random emoji
```

##### `TokenList` - Concatenate tokens
```typescript
randomString(['list', 
  'user_',
  ['char', 48, 57, 4],              // 4 digits
  '_',
  ['pick', 'active', 'inactive']
]);
// Example: "user_1234_active"

// Email generation
randomString(['list',
  ['repeat', 3, 12, ['char', 97, 122]], // 3-12 lowercase letters
  ['pick', '.', '_', '-', ''],          // Optional separator
  ['repeat', 0, 5, ['char', 97, 122]],  // 0-5 more letters
  '@',
  ['pick', 'gmail.com', 'yahoo.com', 'example.org']
]);
```

#### Complex String Examples

```typescript
// Phone numbers
const phone = randomString(['list',
  '+1-',
  ['char', 50, 57, 3],  // Area code (2-9)
  '-',
  ['char', 48, 57, 3],  // Exchange
  '-',
  ['char', 48, 57, 4]   // Number
]);

// Product codes
const productCode = randomString(['list',
  ['pick', 'PRD', 'ITM', 'SKU'],
  '-',
  ['char', 65, 90, 2],    // 2 uppercase letters
  ['char', 48, 57, 6]     // 6 digits
]);

// URLs
const url = randomString(['list',
  'https://',
  ['repeat', 3, 15, ['char', 97, 122]], // Domain name
  ['pick', '.com', '.org', '.net', '.io'],
  ['pick', '', '/', '/api/', '/v1/'],
  ['repeat', 0, 10, ['char', 97, 122]] // Optional path
]);
```

### Utility Functions

#### `deterministic(seed: number | (() => number), callback: () => T): T`

Execute code with deterministic random number generation.

```typescript
import { deterministic, RandomJson, TemplateJson } from '@jsonjoy.com/json-random';

// Generate the same data every time
const data1 = deterministic(42, () => RandomJson.generate({ nodeCount: 5 }));
const data2 = deterministic(42, () => RandomJson.generate({ nodeCount: 5 }));
// data1 and data2 are identical

// Different seeds produce different but deterministic results
const dataA = deterministic(123, () => TemplateJson.gen('str'));
const dataB = deterministic(456, () => TemplateJson.gen('str'));

// Use custom random number generator
const customRng = rnd(999);
const data3 = deterministic(customRng, () => RandomJson.generate());
```

#### `rnd(seed: number): () => number`

Create a deterministic random number generator function.

```typescript
import { rnd } from '@jsonjoy.com/json-random';

const randomFn = rnd(12345);
console.log(randomFn()); // 0.00002...
console.log(randomFn()); // 0.77271...
console.log(randomFn()); // 0.32429...
```

#### `int(min: number, max: number): number`

Generate a random integer between min and max (inclusive).

```typescript
import { int } from '@jsonjoy.com/json-random';

const dice = int(1, 6);        // 1-6
const percentage = int(0, 100); // 0-100
const id = int(1000, 9999);   // 4-digit ID
```

## Use Cases

### Testing & Development

```typescript
// Generate test user data
const testUsers = Array.from({ length: 10 }, () => 
  TemplateJson.gen(['obj', [
    ['id', ['int', 1, 10000]],
    ['name', ['str', ['list', 
      ['pick', 'John', 'Jane', 'Bob', 'Alice', 'Charlie'],
      ' ',
      ['pick', 'Doe', 'Smith', 'Johnson', 'Brown']
    ]]],
    ['email', ['str', ['list',
      ['repeat', 3, 10, ['char', 97, 122]],
      '@test.com'
    ]]],
    ['age', ['int', 18, 65]],
    ['active', 'bool']
  ]])
);

// Generate API response mock data
const mockApiResponse = TemplateJson.gen(['obj', [
  ['success', ['lit', true]],
  ['timestamp', ['lit', Date.now()]],
  ['data', ['arr', 5, 15, ['obj', [
    ['id', 'int'],
    ['status', ['pick', 'pending', 'completed', 'failed']],
    ['value', ['float', 0, 1000]]
  ]]]]
]]);
```

### Load Testing

```typescript
// Generate large datasets for performance testing
const loadTestData = deterministic(42, () => 
  Array.from({ length: 1000 }, () => 
    RandomJson.generate({ 
      nodeCount: 50,
      odds: {
        null: 1,
        boolean: 2,
        number: 10,
        string: 8,
        binary: 0,
        array: 3,
        object: 5
      }
    })
  )
);
```

### Configuration Generation

```typescript
// Generate service configurations
const serviceConfig = TemplateJson.gen(['obj', [
  ['database', ['obj', [
    ['host', ['str', ['list', 'db-', ['char', 48, 57, 2], '.example.com']]],
    ['port', ['int', 3000, 6000]],
    ['timeout', ['int', 1000, 30000]],
    ['pool_size', ['int', 5, 50]]
  ]]],
  ['cache', ['obj', [
    ['enabled', 'bool'],
    ['ttl', ['int', 60, 3600]],
    ['max_size', ['int', 100, 10000]]
  ]]],
  ['features', ['map',
    ['pick', 'feature_a', 'feature_b', 'feature_c', 'feature_d'],
    'bool',
    2, 5
  ]]
]]);
```

## Helper Methods for Easy Generation

The library provides convenient helper methods for generating common data types without needing to construct templates manually. These methods are available in the `examples` module:

```typescript
import { 
  genUser, 
  genAddress, 
  genProduct, 
  genOrder,
  genRandomExample 
} from '@jsonjoy.com/json-random/lib/examples';

// Generate common data types quickly
const user = genUser();
const address = genAddress();
const product = genProduct();
const order = genOrder();

// Generate random example from any template
const randomData = genRandomExample();
```

### Available Helper Methods

| Method | Description |
|--------|-------------|
| `genUser()` | Generate comprehensive user profile with details |
| `genUserBasic()` | Generate basic user with essential information |
| `genAddress()` | Generate address with street, city, state, etc. |
| `genProduct()` | Generate product with name, price, category |
| `genOrder()` | Generate order with items and customer info |
| `genTransaction()` | Generate financial transaction data |
| `genBankAccount()` | Generate bank account information |
| `genSocialPost()` | Generate social media post |
| `genSocialProfile()` | Generate social media profile |
| `genLocation()` | Generate location with coordinates |
| `genApiResponse()` | Generate API response with data array |
| `genApiResponseDetailed()` | Generate comprehensive API response |
| `genServiceConfig()` | Generate service configuration |
| `genPatient()` | Generate medical patient record |
| `genMedicalRecord()` | Generate comprehensive medical record |
| `genStudent()` | Generate student profile |
| `genCourse()` | Generate course information |
| `genSensorReading()` | Generate IoT sensor reading |
| `genIotDevice()` | Generate IoT device profile |
| `genLogEntry()` | Generate log entry for monitoring |
| `genMetricData()` | Generate metric data for monitoring |
| `genRandomExample()` | Generate random data from any available template |

### Usage Examples

```typescript
// Generate test user data for API testing
const testUser = genUser();
console.log(testUser);
// Output: { id: 4829, username: "user_7432", email: "alice@gmail.com", ... }

// Generate address for form testing
const shippingAddress = genAddress();
console.log(shippingAddress);
// Output: { street: "123 Main St", city: "Springfield", state: "CA", ... }

// Generate product catalog
const products = Array.from({ length: 10 }, () => genProduct());

// Generate random test data
const randomTestData = Array.from({ length: 5 }, () => genRandomExample());
```

## Demos

Run the included demos to see the library in action:

```bash
# Random JSON generation
npx ts-node src/__demos__/json-random.ts

# Template-based generation  
npx ts-node src/__demos__/map-demo.ts
```

## TypeScript Support

The library includes full TypeScript definitions:

```typescript
import type { 
  RandomJsonOptions, 
  NodeOdds,
  Template,
  TemplateJsonOpts,
  Token,
  ArrayTemplate,
  ObjectTemplate,
  MapTemplate
} from '@jsonjoy.com/json-random';
```

## License

Apache-2.0