Features

Installation

npm install @jsonjoy.com/json-random

Quick Start

import{RandomJson,TemplateJson,randomString,deterministic}from'@jsonjoy.com/json-random';// Generate random JSONconstrandomData=RandomJson.generate();// Generate structured JSON from templateconstuserData=TemplateJson.gen(['obj',[['id',['int',1,1000]],['name',['str',['list',['pick','John','Jane','Bob'],' ',['pick','Doe','Smith']]]],['active','bool']]]);// Generate random strings with patternsconstemail=randomString(['list',['pick','user','admin','test'],'@',['pick','example.com','test.org']]);

API Reference

RandomJson

RandomJson.generate(options?: RandomJsonOptions): unknown

interfaceRandomJsonOptions{rootNode?:'object'|'array'|'string';nodeCount?:number;odds?:NodeOdds;strings?:Token;}interfaceNodeOdds{null:number;boolean:number;number:number;string:number;binary:number;array:number;object:number;}

// Basic random JSON (default: object with ~32 nodes)constbasic=RandomJson.generate();// Smaller JSON with 5 nodesconstsmall=RandomJson.generate({nodeCount:5});// Force root to be an arrayconstarrayRoot=RandomJson.generate({rootNode:'array',nodeCount:3});// Customize node type probabilitiesconststringHeavy=RandomJson.generate({nodeCount:10,odds:{null:1,boolean:1,number:2,string:20,// Much higher probability for stringsbinary:0,array:2,object:5}});// Use custom string patternsconstcustomStrings=RandomJson.generate({nodeCount:5,strings:['pick','alpha','beta','gamma','delta']});

Static Generation Methods

// Generate random string (default length: 1-16 chars)conststr=RandomJson.genString();constlongStr=RandomJson.genString(50);// Generate random numberconstnum=RandomJson.genNumber();// Generate random booleanconstbool=RandomJson.genBoolean();// Generate random arrayconstarr=RandomJson.genArray();constcustomArr=RandomJson.genArray({nodeCount:3,odds:{string:10,number:5,boolean:1,null:0,array:0,object:0,binary:0}});// Generate random objectconstobj=RandomJson.genObject();constcustomObj=RandomJson.genObject({nodeCount:4,odds:{string:8,number:8,boolean:2,null:1,array:1,object:1,binary:0}});// Generate random binary dataconstbinary=RandomJson.genBinary();constlargeBinary=RandomJson.genBinary(100);

TemplateJson

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

interfaceTemplateJsonOpts{maxNodes?:number;// Soft limit on total nodes generated (default: 100)}

Template Types

Basic Types

// Shorthand templatesTemplateJson.gen('str');// Random stringTemplateJson.gen('int');// Random integerTemplateJson.gen('int64');// Random 64-bit integer (bigint)TemplateJson.gen('float');// Random floatTemplateJson.gen('num');// Random number (int or float)TemplateJson.gen('bool');// Random booleanTemplateJson.gen('bin');// Random binary data (Uint8Array)TemplateJson.gen('nil');// null value// Type-specific templatesTemplateJson.gen(['str',tokenPattern]);// String with patternTemplateJson.gen(['int',min,max]);// Integer in rangeTemplateJson.gen(['int64',min,max]);// 64-bit integer in range (bigint)TemplateJson.gen(['float',min,max]);// Float in rangeTemplateJson.gen(['bool',fixedValue]);// Fixed or random booleanTemplateJson.gen(['bin',min,max,omin,omax]);// Binary with length and octet rangeTemplateJson.gen(['lit',anyValue]);// Literal value (cloned)

// Strings with patternsconstgreeting=TemplateJson.gen(['str',['list',['pick','Hello','Hi','Hey'],' ',['pick','World','There']]]);// Numbers in rangesconstage=TemplateJson.gen(['int',18,100]);constprice=TemplateJson.gen(['float',0.01,999.99]);constscore=TemplateJson.gen(['num',0,100]);// 64-bit integers (bigint)constlargeId=TemplateJson.gen(['int64',BigInt('1000000000000'),BigInt('9999999999999')]);consttimestamp=TemplateJson.gen(['int64',BigInt('1640000000000'),BigInt('1700000000000')]);// Binary data (Uint8Array)consthash=TemplateJson.gen(['bin',32,32]);// 32-byte hashconstkey=TemplateJson.gen(['bin',16,16,0,255]);// 16-byte key with full octet rangeconstrandomBytes=TemplateJson.gen(['bin',1,10]);// 1-10 random bytes// Fixed valuesconstisActive=TemplateJson.gen(['bool',true]);constuserId=TemplateJson.gen(['lit','user_12345']);

64-bit Integer Templates

// Basic 64-bit integerconstid=TemplateJson.gen('int64');// Random bigint in safe range// 64-bit integer with rangeconsttimestamp=TemplateJson.gen(['int64',BigInt('1640000000000'),// Min valueBigInt('1700000000000')// Max value]);// Large database IDsconstdbId=TemplateJson.gen(['int64',BigInt('1000000000000000000'),BigInt('9999999999999999999')]);// Fixed bigint valueconstconstant=TemplateJson.gen(['int64',BigInt('42'),BigInt('42')]);

Binary Data Templates

// Basic binary data (0-5 bytes)constdata=TemplateJson.gen('bin');// Binary with specific length rangeconsthash=TemplateJson.gen(['bin',32,32]);// Exactly 32 bytesconstkey=TemplateJson.gen(['bin',16,64]);// 16-64 bytes// Binary with octet value constraintsconstrestrictedData=TemplateJson.gen(['bin',8,// Min length: 8 bytes16,// Max length: 16 bytes32,// Min octet value: 32126// Max octet value: 126 (printable ASCII range)]);// Cryptographic examplesconstaesKey=TemplateJson.gen(['bin',32,32]);// 256-bit AES keyconstiv=TemplateJson.gen(['bin',16,16]);// 128-bit IVconstsalt=TemplateJson.gen(['bin',16,32]);// 16-32 byte saltconstsignature=TemplateJson.gen(['bin',64,64,0,255]);// 64-byte signature

Array Templates

typeArrayTemplate=['arr',min?,// Minimum length (default: 0)max?,// Maximum length (default: 5)template?,// Template for itemshead?,// Fixed items at starttail?// Fixed items at end];

// Basic arraysconstnumbers=TemplateJson.gen(['arr',2,5,'int']);constmixed=TemplateJson.gen(['arr',1,3]);// Arrays with head/tailconstcoords=TemplateJson.gen(['arr',0,0,null,[['float',-180,180],['float',-90,90]],// head: [longitude, latitude][['lit','WGS84']]// tail: coordinate system]);// Nested arraysconstmatrix=TemplateJson.gen(['arr',2,3,['arr',2,3,['int',0,10]]]);

Object Templates

typeObjectTemplate=['obj',fields?// Array of field definitions];typeObjectTemplateField=[key,// Key name (string or Token)valueTemplate,// Template for the valueoptionality?// Probability of omission (0 = required, 1 = always omit)];

// User profileconstuser=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 ResponseconstapiResponse=TemplateJson.gen(['obj',[['status',['pick','success','error']],['timestamp',['int',1640000000,1700000000]],['data',['arr',0,10,['obj',[['id','int'],['value','str']]]]]]]);

Map Templates

typeMapTemplate=['map',keyToken?,// Token for generating keysvalueTemplate?,// Template for valuesmin?,// Minimum entries (default: 0)max?// Maximum entries (default: 5)];

// Configuration mapconstconfig=TemplateJson.gen(['map',['pick','timeout','retries','cache_ttl','max_connections'],['int',1,3600],3,5]);// User permissionsconstpermissions=TemplateJson.gen(['map',['list','can_',['pick','read','write','delete','admin']],'bool',2,6]);// Localization stringsconsttranslations=TemplateJson.gen(['map',['pick','welcome','goodbye','error','success','loading'],['str',['repeat',5,20,['char',32,126]]],3,8]);

Union Templates (Or)

// Mixed data typesconstmixedValue=TemplateJson.gen(['or','str','int','bool']);// Different user typesconstuser=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

// Tree structureconsttree=():Template=>['obj',[['value','int'],['left',tree,0.3],// 30% chance of left child['right',tree,0.3]// 30% chance of right child]];consttreeData=TemplateJson.gen(tree);// Nested commentsconstcomment=():Template=>['obj',[['id','int'],['text','str'],['author','str'],['replies',['arr',0,3,comment,[],[]],0.4]// 40% chance of replies]];constcommentThread=TemplateJson.gen(comment);

String Token System

randomString(token: Token): string

typeToken=TokenLiteral|TokenPick|TokenRepeat|TokenChar|TokenList;

Token Types

TokenLiteral - Static strings

randomString('Hello');// Always returns "Hello"

TokenPick - Choose randomly from options

randomString(['pick','red','green','blue']);// Returns one of: "red", "green", "blue"randomString(['pick','small','medium','large','extra-large']);

TokenRepeat - Repeat patterns

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

randomString(['char',65,90]);// Single random A-ZrandomString(['char',97,122,5]);// 5 random a-z charsrandomString(['char',48,57,3]);// 3 random digits// Unicode rangesrandomString(['char',0x1F600,0x1F64F]);// Random emoji

TokenList - Concatenate tokens

randomString(['list','user_',['char',48,57,4],// 4 digits'_',['pick','active','inactive']]);// Example: "user_1234_active"// Email generationrandomString(['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

// Phone numbersconstphone=randomString(['list','+1-',['char',50,57,3],// Area code (2-9)'-',['char',48,57,3],// Exchange'-',['char',48,57,4]// Number]);// Product codesconstproductCode=randomString(['list',['pick','PRD','ITM','SKU'],'-',['char',65,90,2],// 2 uppercase letters['char',48,57,6]// 6 digits]);// URLsconsturl=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

import{deterministic,RandomJson,TemplateJson}from'@jsonjoy.com/json-random';// Generate the same data every timeconstdata1=deterministic(42,()=>RandomJson.generate({nodeCount:5}));constdata2=deterministic(42,()=>RandomJson.generate({nodeCount:5}));// data1 and data2 are identical// Different seeds produce different but deterministic resultsconstdataA=deterministic(123,()=>TemplateJson.gen('str'));constdataB=deterministic(456,()=>TemplateJson.gen('str'));// Use custom random number generatorconstcustomRng=rnd(999);constdata3=deterministic(customRng,()=>RandomJson.generate());

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

import{rnd}from'@jsonjoy.com/json-random';constrandomFn=rnd(12345);console.log(randomFn());// 0.00002...console.log(randomFn());// 0.77271...console.log(randomFn());// 0.32429...

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

import{int}from'@jsonjoy.com/json-random';constdice=int(1,6);// 1-6constpercentage=int(0,100);// 0-100constid=int(1000,9999);// 4-digit ID

Use Cases

Testing & Development

// Generate test user dataconsttestUsers=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 dataconstmockApiResponse=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]]]]]]]]);// Generate cryptographic test dataconstcryptoData=TemplateJson.gen(['obj',[['userId',['int64',BigInt('1000000000000'),BigInt('9999999999999')]],['sessionId',['str',['list','sess_',['repeat',32,32,['pick', ...'0123456789abcdef'.split('')]]]]],['publicKey',['bin',32,32]],// 256-bit public key['signature',['bin',64,64]],// 512-bit signature['nonce',['bin',16,16]],// 128-bit nonce['timestamp',['int64',BigInt(Date.now()),BigInt(Date.now()+86400000)]]]]);

Load Testing

// Generate large datasets for performance testingconstloadTestData=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

// Generate service configurationsconstserviceConfig=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]]]]],['security',['obj',[['api_key',['bin',32,32]],// 256-bit API key['session_timeout',['int64',BigInt('3600'),BigInt('86400')]],// 1 hour to 1 day in seconds['max_request_size',['int64',BigInt('1048576'),BigInt('104857600')]]// 1MB to 100MB]]],['features',['map',['pick','feature_a','feature_b','feature_c','feature_d'],'bool',2,5]]]]);

Helper Methods for Easy Generation

import{genUser,genAddress,genProduct,genOrder,genRandomExample}from'@jsonjoy.com/json-random/lib/examples';// Generate common data types quicklyconstuser=genUser();constaddress=genAddress();constproduct=genProduct();constorder=genOrder();// Generate random example from any templateconstrandomData=genRandomExample();

Available Helper Methods

Usage Examples

// Generate test user data for API testingconsttestUser=genUser();console.log(testUser);// Output: { id: 4829, username: "user_7432", email: "alice@gmail.com", ...}// Generate address for form testingconstshippingAddress=genAddress();console.log(shippingAddress);// Output: { street: "123 Main St", city: "Springfield", state: "CA", ... }// Generate product catalogconstproducts=Array.from({length:10},()=>genProduct());// Generate random test dataconstrandomTestData=Array.from({length:5},()=>genRandomExample());

Demos

# Random JSON generationnpx ts-node src/__demos__/json-random.ts# Template-based generationnpx ts-node src/__demos__/map-demo.ts

TypeScript Support

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

License