Big JSON streams for JS without creating big objects
JavaScript
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
test
README.md
json-builder.js
package.json

README.md

JSON Builder

This is a small API helping you to write long JSON values to a stream without constructing their entire content in memory first.

Why?! There is JSON.stringify()

The JSON Builder is nice if you want to dump ten thousand records from your database to a JSON output, because it saves on memory and cuts down on blocking buffer allocations. Also, it helps you to send still-incomplete data to clients so they can start processing while you prepare the rest for them.

How do I use it?

var stream = ... // something with write(str), e.g. an HTTP response
  , jsonBuilder = require('json-builder')
  , out = jsonBuilder.stream(stream)
out.map()
   .key('title-row')
   .list()
   .val({a: 'an object'})
   .val(['a', 'list!', 1, 11])
   .json('{"some JSON": "as well"}')
    
for (record in database) {// usually this would spill out values async
  out.key(record.id)
     .val(record.items)
}
out.close()

// minus whitespace, this will produce something like:
//
// {"title-row": [{"a": "an object"}, ["a", "list!", 1, 11], 
//                {"some JSON": "as well"}],
// ... the db rows
// }

What about encoding?!

JSON Builder does not care about the fact that there might be encodings different from UTF-8 (yet). If you need to specify your encoding for a value, you can always use the .json(...) method and pass in you prepared item.