JSONPullParser

Introduction

JSONPullParser is a dropin replacement for JSON.parse and also provides a pull based api.

Usage

let parser  = new JSONPullParser(json);
let builder = new JSONPullParser.ObjectBuilder();

for (let token of parser) builder.handle(token);

See live demo!

Getting started

JSONPullParser provides a simple API for iterating over the tokens in JSON data.

If your JavaScript engine supports Symbol.iterator then your parser is iterable.

let parser  = new JSONPullParser(json);

for (let token of parser) {
  // use token
}

Otherwise you have to get an iterator from parser.tokens()

var parser = new JSONPullParser(json);
var it     = parser.tokens();

while (true) {
  var step = it.next();
  if (step.done) break;
  var token = step.value;
  // use token
}

JSONPullParser ensures that the tokens are valid and delivered in a valid sequence. StartObject and StartArray will always have a matching EndObject and EndArray at the correct depth.

Installation

Node (CommonJS)

$ npm install json-pull-parser

const JSONPullParser = require('json-pull-parser')

Browser

<script src="https://unpkg.com/json-pull-parser/dist/json-pull-parser.js"></script>

ObjectBuilder

ObjectBuilder builds the resulting JavaScript object from the tokens. Its value property is either undefined or a valid object/array/boolean or null.

JSON.parse could be implemented by simply feeding all the tokens to ObjectBuilder.

JSON.parse = function (source)
{
  let parser = new JSONPullParser(source);
  let builder = new JSONPullParser.ObjectBuilder();
  for (let token of parser) builder.handle(token);
  return builder.value;
}

Custom handling of events

let parser = new JSONPullParser(json);

for (let token of parser) {
  switch (token.type) {
    case JSONPullParser.StartObject:
      break;
    case JSONPullParser.EndObject:
      break;
    case JSONPullParser.StartArray:
      break;
    case JSONPullParser.EndArray:
      break;
    case JSONPullParser.String:
      break;
    case JSONPullParser.Number:
      break;
    case JSONPullParser.TrueLiteral:
      break;
    case JSONPullParser.FalseLiteral:
      break;
    case JSONPullParser.NullLiteral:
      break;
    case JSONPullParser.Error:
      break;
  }
}

Conformance

JSONPullParser tries to conform to ECMA 404.

JSON-Schema-Test-Suite and JSON_checker are both used to validate the parser as well as comparing the output from JSON.parse with JSONPullParser.parse on a number of real life testcases.

JSONPullParser currently delegates string and number parsing is delegated to JSON.parse.

Results

JSONPullParser will obviously be slower than using native JSON.parse. However it is mainly intended to be used when a constant frame rate or not freezing the user interface is more important than performance.

json.length:          17.53mb
JSON.parse:           188ms
JSONPullParser.parse: 316ms
Equality:             true
JSON.parse done in 170ms
JSON.parse done in 184ms
JSONPullParser parsed 1M tokens in 480ms using 1001 fragments
JSONPullParser parsed 1M tokens in 396ms using 1001 fragments
  

See live demo!