json-spawn

Create JSON objects using the Partial Response query language.

var spawner = require('json-spawn')
var chance = require('chance').Chance()

var spawn = spawner(chance)
spawn('id:guid,profile(name,age,twitter,city,country)')

// returns
//   { id: 'b09a25ea-a251-5d6e-9225-e4fe56215368',
//     profile:
//       { name: 'Milton Taylor',
//         age: 50,
//         twitter: '@vevcohaf',
//         city: 'Ekpithi',
//         country: 'TJ' } }

Installation

$ npm install json-spawn

Quick Start

Spawning objects

var spawner = require('json-spawn')
var spawn = spawner(/* your generator */)

A generator is any object exposing a set of methods that will be used for populating the fields in the JSON object.

A nice example of a generator is Chance.js, the super cool library for random data of any type. Chance lets you do

chance.name() // 'Shane Chandler'
chance.mont() // 'December'
chance.ssn()  // '868-56-5059'

Let's use Chance.js as our generator for spawning JSON objects:

var chance = require('chance').Chance()
var spawn = spawner(chance)

That's it, now you are ready for generating objects by passing some queries to the spawn function! If you ever used some of the Google APIs in the past, the syntax will look familiar.

var address = spawn('address,city,state,zip,geo/coordinates')

// { address: '1262 Tefi Grove',
//   city: 'Lilafem',
//   state: 'CO',
//   zip: '27328',
//   geo: { coordinates: '19.2724, 164.16494' } }

What spawn does is to inspect each field in the query, looking for a method with the same name in the generator object.

For more information about the Partial Response query syntax, check out the documentation page.

Serving spawned objects from an API

It's easy to integrate JSON Spawn with Express:

app.get('/api/*', function (req, res) {
	res.status(200).json(spawn(req.query.fields))
})

There you go. Now you have a full-mocked API that you can use while writing your client app.

Advanced syntax

spawn('hashtag{3}')

// { hashtag: [ '#nocnata', '#omfimore', '#ot' ] }

spawn('folderId:guid,name:word,readOnly:bool')

// { folderId: '4c52b585-37a0-540a-84fa-083c30e71a96',
//   name: 'wusgo',
//   readOnly: false }

spawn('friends(name,birthday,link:url)')

// { friends:
//   { name: 'Winnie Copeland',
//     birthday: Tue Feb 10 1953 01:38:13 GMT-0300 (ART),
//     link: 'http://lut.edu/bil' } }

spawn('friends{1}(name,birthday,link:url)')

// { friends:
//   [ { name: 'Hulda Conner',
//       birthday: Wed May 18 1955 06:14:41 GMT-0300 (ART),
//       link: 'http://le.org/se' } ] }

spawn('friends{0}(name,birthday,link:url)')

// { friends: [] }

Pending features

• Parameters in generators (perhaps something like x:word{length:5}?)
• Implementation of *

Tests

$ npm test          // Runs tests with Mocha
$ npm run test-cov  // Runs coverage report with Istanbul

Credits

Thanks to @nemtsov for his JSON Mask library, which is pretty much the base of this work.

License

MIT