dummy-json

Dummy JSON mock data generator for Node.js

Dummy JSON

Dummy JSON is a Node utility that allows you to generate random JSON data using Handlebars templates. It comes with a built-in collection of Handlebars helpers that return common data values, such as names, numbers, dates, and also allows you to write your own.

Please view the following example on the github page if it's not formatted correctly.

Template stringOutput string
{
  "users": [
    {{#repeat 2}}
    {
      "id": {{@index}},
      "name": "{{firstName}} {{lastName}}",
      "work": "{{company}}",
      "email": "{{email}}",
      "dob": "{{date '1900' '2000' 'DD/MM/YYYY'}}",
      "address": "{{int 1 100}} {{street}}",
      "city": "{{city}}",
      "optedin": {{boolean}}
    }
    {{/repeat}}
  ],
  "images": [
    {{#repeat 3}}
    "img{{@index}}.png"
    {{/repeat}}
  ],
  "coordinates": {
    "x": {{float -50 50 '0.00'}},
    "y": {{float -25 25 '0.00'}}
  },
  "price": "${{int 0 99999 '0,0'}}"
}
{
  "users": [
    {
      "id": 0,
      "name": "Adam Carter",
      "work": "Unilogic",
      "email": "adam.carter@unilogic.com",
      "dob": "24/11/1978",
      "address": "83 Warner Street",
      "city": "Boston",
      "optedin": true
    },
    {
      "id": 1,
      "name": "Leanne Brier",
      "work": "Connic",
      "email": "leanne.brier@connic.org",
      "dob": "13/05/1987",
      "address": "9 Coleman Avenue",
      "city": "Toronto",
      "optedin": false
    }
  ],
  "images": [
    "img0.png",
    "img1.png",
    "img2.png"
  ],
  "coordinates": {
  	"x": 35.12,
  	"y": -21.49
  },
  "price": "$59,395"
}

Install via npm:

npm install dummy-json

dummyjson.parse(template, {options}) Parses the given template and returns a string

var dummyjson = require('dummy-json');
var template = '{\
"name": {{firstName}},\
"age": {{int 18 65}}\
  }';
var result = dummyjson.parse(template); // Returns a string 

Instead of writing multi-line strings in Javascript you can load the template from a file using Node's fs utility:

var fs = require('fs');
var dummyjson = require('./dummy-json');
 
var template = fs.readFileSync('template.hbs', {encoding: 'utf8'});
var result = dummyjson.parse(template);

If the output string is properly formatted it can be parsed into a JavaScript object:

var result = dummyjson.parse(template);
var obj = JSON.parse(result);

A common use of Dummy JSON is to create a mock API service that returns random data. Here's a quick example using Express:

var fs = require('fs');
var express = require('express');
var dummyjson = require('./dummy-json');
 
var template = fs.readFileSync('template.hbs', {encoding: 'utf8'});
var app = express();
 
app.get('/people', function(reqres) {
  res.set('Content-Type', 'application/json');
  res.send(dummyjson.parse(template));
});
 
app.listen(3000);

If you install the utility globally with npm install -g dummy-json you can use it from the command line to parse files:

dummyjson template.hbs > output.json

{{#repeat count [comma=true]}} ... {{/repeat}}

  • count The number of times to repeat the content (required)
  • comma Adds or removes the separating comma between blocks of content (optional, default is true)

Repeats blocks of content, similar to Handlebars' built-in each. Can be used anywhere in your template, not just inside arrays. Automatically adds a comma and line break between blocks.

// Repeat the block 3 times, automatically adding a comma between blocks 
var messages = [
  {{#repeat 3}}
  "hello"
  {{/repeat}}
];
 
// Output 
var messages = [
  "hello",
  "hello",
  "hello"
];

You can omit the comma and line break by using comma=false, for example:

{{#repeat 3 comma=false}}hello{{/repeat}} // hellohellohello 

You can get the iteration position using the standard Handlebars variables @index, @first, @last. The total number of iterations is available using @total.

// Repeat the block 3 times using @index to modify the filename 
{{#repeat 3}}
"img{{@index}}.png"
{{/repeat}}
 
// Output 
"img0.png",
"img1.png",
"img2.png"

{{int min max [format] [round=1]}}

  • min Minimum value (required)
  • max Maximum value (required)
  • format Formatting string (optional, default is null)
  • round Rounds to the nearest multiple of the given value (optional, default is null - no rounding)

Generates a random integer from min (inclusive) up to and including max (inclusive). The optional round parameter will round the number to the nearest multiple of the given value.

The output can be formatted using a numeric format string, provided by numbro. For a complete list of formatting options see http://numbrojs.com/format.html.

// Generates a random integer between 0 and 100 
{{int 0 100}} // 43 
 
// Rounds the random integer to the nearest multiple of 5 
{{int 0 100 round=5}} // 65 
 
// Formats the random integer using numbro 
{{int 10000 50000 '0,0.00'}} // 23,462.00 

{{float min max [format] [round=1]}}

  • min Minimum value (required)
  • max Maximum value (required)
  • format Formatting string (optional, default is null)
  • round Rounds to the nearest multiple of the given value (optional, default is null - no rounding)

Generates a random floating point number from min (inclusive) up to but excluding max (exclusive). The optional round parameter will round the number to the nearest multiple of the given value.

The output can be formatted using a numeric format string, provided by numbro. For a complete list of formatting options see http://numbrojs.com/format.html.

// Generates a random float between 0 and 1 
{{float 0 1}} // 0.4319351462490857 
 
// Rounds the random float to the nearest multiple of 0.1 
{{float 0 1 round=0.1}} // 0.4 
 
// Formats the random float using numbro 
{{float 10000 50000 '0,0.00'}} // 33,127.39 

{{date min max [format]}}

  • min Minimum value (required)
  • max Maximum value (required)
  • format Formatting string (optional, default is null)

Generates a random date between the two values. Both min and max can be represented by any string that the Date.parse() method accepts.

By default the output uses Date.toString(). Alternatively the output can be formatted using a format string provided by fecha. For a complete list of formatting options see https://github.com/taylorhakes/fecha

// Generate a random date between midnight 2010-01-01 and midnight 2015-01-01 
{{date '2010' '2015'}} // Thu Jan 26 2012 03:04:15 GMT+0000 (GMT) 
 
// Generate a random date between more specific values 
{{date '2015-06-01' '2015-06-30'}} // Mon Jun 22 2015 01:02:36 GMT+0100 (BST) 
 
// Generate a random date between even more specific values (inc. time) 
{{date '2015-06-01T09:00' '2015-06-30T17:30'}} // Sun Jun 07 2015 23:55:16 GMT+0100 (BST) 
 
// Format the date using fecha 
{{date '2010' '2015' 'DD/MM/YYYY'}} // 16/06/2012 
 
// Format the date using a unix timestamp 
{{date '2010' '2015' 'unix'}} // 1340417344 

{{time min max [format]}}

  • min Minimum value (required)
  • max Maximum value (required)
  • format Formatting string (optional, default is null)

This is a shorthand helper for generating the time portion of a date, without needing to put the full date into the min and max values. Both min and max can be represented by any string in the 24h format HH:mm:ss, for example 17:48:34., or if you want to ignore seconds: 17:48

By default the output uses HH:mm. Alternatively the output can be formatted using a format string provided by fecha. For a complete list of formatting options see https://github.com/taylorhakes/fecha

// Generate a random time 
{{date '09:00' '17:30'}} // 14:08 
 
// Format the time using fecha 
{{date '09:00' '17:30' 'h:mm a'}} // 2:08 pm 

{{boolean}}

Generates a random true or false value.

{{title}}

Generates a random title prefix, from a predefined list, such as "Mr", "Mrs", "Dr", etc.

{{firstName}}

Generates a random first name, from a predefined list. This helper is kept in sync with other name-related helpers, such as username and email - see the section on Synchronized helpers for more information.

{{lastName}}

Generates a random last name, from a predefined list. This helper is kept in sync with other name-related helpers, such as username and email - see the section on Synchronized helpers for more information.

{{company}}

Generates a random company name, from a predefined list. This helper is kept in sync with the email and domain helpers, such as username and email - see the section on Synchronized helpers for more information.

{{domain}}

Generates a random domain name in the format "domain.tld", from a predefined list. This helper is kept in sync with the company and email helpers - see the section on Synchronized helpers for more information.

{{tld}}

Generates a random top-level domain name, from a predefined list. This helper is kept in sync with the email helper - see the section on Synchronized helpers for more information.

{{email}}

Generates a random email address. This helper is kept in sync with other name-related helpers, such as username and email - see the section on Synchronized helpers for more information.

{{street}}

Generates a random street name, from a predefined list.

{{city}}

Generates a random city name, from a predefined list.

{{country}}

Generates a random country name, from a predefined list based on ISO 3166-1. This helper is kept in sync with the country code helper - see the section on Synchronized helpers for more information.

If you want to export the entire list then you can use the following snippet in your template:

{{#each countries}}
"name": "{{this}}"
{{/each}}

{{countryCode}}

Generates a random 2-character country code, from a predefined list based on ISO 3166-1. This helper is kept in sync with the country helper - see the section on Synchronized helpers for more information.

If you want to export the entire list then you can use the following snippet in your template:

{{#each countryCodes}}
"code": "{{this}}"
{{/each}}

{{zipcode}}

Generates a random US-style 5 digit zipcode.

{{postcode}}

Generates a random UK-style postcode in the format AA9 9AA.

{{lat}}

Generates a random latitude from -90 to +90, to 6 decimal places (roughly 10cm of precision).

{{long}}

Generates a random longitude from -180 to +180, to 6 decimal places (roughly 10cm of precision).

{{phone [format]}}

  • format Formatting string (optional, default is xxx-xxx-xxxx)

Generates a random phone number in the format xxx-xxx-xxxx, for example "123-456-7890". To use a different format pass a string to the format parameter containing a series of lowercase "x" characters for each random integer.

// Generate a random phone number in the default format 
{{phone}} // 445-295-1044 
 
// Generate a random phone number with a custom format 
{{phone "+64 (x) xxx xxxx"}} // +64 (5) 883 4711 

{{color}}

Generates a random CSS color name, from a predefined list, such as "forestgreen", "black", etc

{{hexColor [websafe=false]}}

  • websafe Generates a websafe color if true (optional, default is false)

Generates a random hexadecimal color value with leading hash symbol.

// Generates a hex color with leading hash symbol 
{{hexColor}} // #34D92C 
 
// Generates a websafe hex color 
{{hexColor websafe=true}} // #33CC99 

{{guid}}

Generates a random 32 digit GUID.

{{ipv4}}

Generates a random IPv4 address.

{{ipv6}}

Generates a random IPv6 address.

{{lorem [wordCount]}}

  • wordcount Number of words to generate (optional, default is 25)

Generates random sentences of lorem ipsum text, with occasional punctuation (commas and periods/full-stops).

// Generates 25 words of lorem ipsum 
{{lorem}} // Amet vel aliquam laoreet accumsan adipiscing velit... etc... 
 
// Generates 5 words of lorem ipsum 
{{lorem 5}} //  Orci nisi laoreet maximus dictum. 

{{lowercase (helper)}}

  • helper Any helper that returns a string (required)

Converts the output of any string-based helper to lowercase. This uses the Handlebars' subexpression syntax.

// Change firstName to lowercase 
{{lowercase (firstName)}} // ivan 
 
// Change city to lowercase 
{{lowercase (city)}} // boston 

{{uppercase (helper)}}

  • helper Any helper that returns a string (required)

Converts the output of any string-based helper to uppercase. This uses the Handlebars' subexpression syntax.

// Change firstName to uppercase 
{{uppercase (firstName)}} // IVAN 
 
// Change city to uppercase 
{{uppercase (city)}} // BOSTON 

Several helpers, such as name and email, are linked together in order to synchronize their values. This gives the random data some continuity. Synchronization happens automatically and doesn't require any additional work, for example:

"firstName": "{{firstName}}", // Michael 
"lastName": "{{lastName}}",   // Turner 
"email": "{{email}}"          // michael.turner@unilogic.com 

The helpers can be placed in any order and will still synchronize:

"email": "{{email}}"          // michael.turner@unilogic.com 
"firstName": "{{firstName}}", // Michael 
"lastName": "{{lastName}}",   // Turner 

The synchronization is reset whenever the same helper is used twice, or in each iteration of a repeat block:

"email": "{{email}}"          // michael.turner@unilogic.com 
"firstName": "{{firstName}}", // Michael 
"lastName": "{{lastName}}",   // Turner 
"email": "{{email}}"          // grace.chapman@westgate.org (Syncing is reset here) 
"firstName": "{{firstName}}", // Grace 
"lastName": "{{lastName}}",   // Chapman 

The following helpers synchronize their values:

  • firstName, lastName, username, company, domain, tld, email
  • country, countryCode

To write your own helpers you need to create an object map of helper methods and pass it to the options param of parse(), for example:

var myHelpers = {
  directionfunction() {
    // Use dummyjson random to ensure the seeded random number generator is used 
    return dummyjson.utils.random() > 0.5 ? 'left' : 'right';
  }
};
var template = '{{direction}}';
var result = dummyjson.parse(template, {helpers: myHelpers}); // Returns "left" 

Your own helpers will be mixed with the built-in helpers, allowing you to use both in your template.

The helpers use the same syntax as regular Handlebars helpers, but instead of registering them with Handlebars.registerHelper() you pass them to dummyjson.parse(). For more information on writing helpers see the Handlebars documentation.

When generating data using random numbers you should use the dummyjson.utils module. This ensures you're using the seeded random number generator and means your results will be repeatable if you decide to use a seed. See the section on Seeded random data for more information and a complete list of methods.

One of the most common types of helper is one that pulls a random item from an array. You can use the following example as a basis for you own:

var myHelpers = {
  orientationfunction() {
    // Use randomArrayItem to ensure the seeded random number generator is used 
    return dummyjson.utils.randomArrayItem(['North', 'South', 'East', 'West']);
  }
};
var template = '{{orientation}}';
var result = dummyjson.parse(template, {helpers: myHelpers}); // Returns "East" 

If you need repeatable dummy data then you can set a global seed for the pseudo random number generator:

// Set the seed, can be any string value 
dummyjson.seed = 'helloworld';
 
// Every subsequent call to parse() will now generate the same values 
var result = dummyjson.parse(string);

Alternatively you can set a one-time seed for a specific parse() call:

var result = dummyjson.parse(string, {seed: 'abc123'});

A one-time seed will not overwrite the global dummyjson.seed, meaning subsequent calls to parse() without a seed will use the original dummyjson.seed value.

To ensure your own helpers use the random seed you must use the dummyjson.utils module whenever you want a random number, character, or array item. The following methods are available to you:

  • dummyjson.utils
    • .random() Generates a random float in the range [0, 1). Use this instead of Math.random()
    • .randomInt(min, max) Generates a random integer in the range [min, max]
    • .randomFloat(min, max) Generates a random float in the range [min, max)
    • .randomBoolean() Generates a random boolean (true or false)
    • .randomDate(min, max) Generates a random Date between the given min/max millisecond values
    • .randomArrayItem(array) Returns a random item from the given array
    • .randomChar(charset) Returns a random char from the given charset string

For example:

var myHelpers = {
  temperaturefunction() {
    return dummyjson.utils.randomInt(0, 100) + '°C';
  }
};

If you want to use a different set of names or addresses then you can override the built-in data using the mockdata option:

var myMockdata = {
  firstNames: ['Bob', 'Jane', 'Carl', 'Joan']
};
var result = dummyjson.parse(template, {mockdata: myMockdata});

The following arrays are available to override:

  • firstNames
  • lastNames
  • companies
  • tlds
  • streets
  • cities
  • countries
  • countryCodes
  • colors

Note: This technique is preferable to overriding the helpers (explained below) as it maintains the synchronization functionality of names, companies, emails, etc.

You can replace any of the built-in helpers by simply creating your own with the same name:

var myHelpers = {
  postcodefunction() {
    // This version of {{postcode}} will now be used instead of the built-in one 
    return 'helloworld';
  }
};
var result = dummyjson.parse(template, {helpers: myHelpers});

Note: If you replace any of the synchronized helpers then you will lose the syncing functionality. If you want to use a different set of names, addresses, etc, then use the technique described in Overriding built-in mock data.

The mockdata option can also be used to insert other data, for example:

var myMockdata = {
  copyright: 'Copyright Myself 2015'
};
var template = '{{copyright}}';
var result = dummyjson.parse(template, {mockdata: myMockdata}); // Returns "Copyright Myself 2015" 

All the built-in helpers are available for you to use in your own helpers. They are available in dummyjson.helpers:

var myHelpers = {
  fullnamefunction(options) {
    // You must always forward the options argument to built-in helpers 
    return dummyjson.helpers.firstName(options) + ' ' + dummyjson.helpers.lastName(options);
  }
};
var template = '{{fullname}}';
var result = dummyjson.parse(template, {helpers: myHelpers}); // Returns "Ivan Young" 

As mentioned in the comment above you must always forward the options argument to built-in helpers. The options argument is automatically given to all helpers by Handlebars, and is always passed as the last argument. See the Handlebars documentation for more information.

You can use Handlebars partials to encapsulate content into a reusable blocks. Partials are passed via the options param of parse().

var myPartials = {
  user: '{\
    "id": {{@index}},\
    "firstName": "{{firstName}}",\
    "lastName": "{{lastName}}",\
    "email": "{{email}}"\
  }'
};
 
var template = '{\
    "users": [\
      {{#repeat 3}}\
        {{> user}}\
      {{/repeat}}\
    ]\
  }';
 
var result = dummyjson.parse(template, {partials: myPartials});
  • The repeat helper no longer accepts an array, use the default Handlebars {{#each}} instead
  • Use {{@index}} instead of {{index}} inside repeat blocks, as per default Handlebars functionality
  • The {{number}} helper no longer exists and has been separated into {{int}} and {{float}}
  • The {{uniqueIndex}} helper no longer exists, consider using {{guid}} instead