oboe

What is oboe?

The oboe npm package is a library for streaming JSON over HTTP. It allows you to parse JSON as it is being received, which can be useful for handling large JSON responses or for real-time data processing.

What are oboe's main functionalities?

Streaming JSON Parsing

This feature allows you to parse JSON data as it is being streamed from an HTTP source. The `node` method is used to handle individual nodes as they are parsed, and the `done` method is called when the entire JSON has been parsed.

const oboe = require('oboe');

oboe('http://example.com/big.json')
  .node('!.*', function(node) {
    console.log('Parsed node:', node);
  })
  .done(function(parsedJson) {
    console.log('Finished parsing:', parsedJson);
  });

Pattern Matching

Oboe allows you to use pattern matching to extract specific parts of the JSON data as it is being parsed. In this example, the `node` method is used to match the `author.name` pattern and log the author's name.

const oboe = require('oboe');

oboe('http://example.com/big.json')
  .node('!author.name', function(name) {
    console.log('Author name:', name);
  });

Error Handling

Oboe provides error handling capabilities to manage issues that may arise during the JSON parsing process. The `fail` method is used to handle any errors that occur.

const oboe = require('oboe');

oboe('http://example.com/big.json')
  .fail(function(error) {
    console.error('Failed to parse JSON:', error);
  });

Other packages similar to oboe

stream-json

The stream-json package is another library for streaming JSON parsing. It provides a more modular approach, allowing you to build a custom pipeline for processing JSON data. Compared to oboe, stream-json offers more flexibility and control over the parsing process.

JSONStream

JSONStream is a library for parsing and stringifying large JSON data streams. It is similar to oboe in that it allows for streaming JSON parsing, but it is more focused on providing a simple and efficient way to handle large JSON data sets.

event-stream

event-stream is a toolkit for working with streams in Node.js. It includes utilities for creating and manipulating streams, including JSON parsing. While not specifically focused on JSON, it provides a versatile set of tools for stream processing, making it a more general-purpose alternative to oboe.

README

Archive note (2024)

This project is now archived. As of 2024, no code changes have been made in 5 years, and I (Jim) have not had the time to port it to new technology, or maintain it in a way that it deserves.

For existing projects using this code, it should continue to work, but I would recommend looking for other solutions.

I (Jim) still think there is a clear gap in the market for a streaming-first JSON parser that doesn't wait for responses to finish before it starts using them. For anyone who is interested in making that project, reach out and I'd be happy to discuss. Today, with modern javascript and typescript (ie async iterators), a much nicer modern API could be made than the one I created in 2013.

Many thanks to JuanCaicedo and Aigeec in particular for continuing to contribute fixes and modernise this project through to ~2020.

The Oboe.js website has been ported to a static site Github Pages, and the plan is to keep it online with a deprecation notice.

The original README follows below.

---

Oboe.js is an open source Javascript library for loading JSON using streaming, combining the convenience of DOM with the speed and fluidity of SAX.

It can parse any JSON as a stream, is small enough to be a micro-library, doesn't have dependencies, and doesn't care which other libraries you need it to speak to.

We can load trees larger than the available memory. Or we can instantiate classical OOP models from JSON, or completely transform your JSON while it is being read.

Oboe makes it really easy to start using json from a response before the ajax request completes. Or even if it never completes.

Where next?

• The website
• Visualise faster web applications through streaming
• Visit the project homepage
• Browse code examples
• Learn the Oboe.js API
• Download the library
• Discuss Oboe.js