Streaming JSON Parsing: jsonparse vs stream-json

When dealing with large JSON payloads — think multi-gigabyte log dumps, real-time telemetry feeds, or massive API responses — loading everything into memory with JSON.parse() isn’t feasible. Both jsonparse and stream-json solve this by parsing JSON as it streams in, using minimal memory. But they take very different approaches. Let’s compare how they work in practice.

🔧 Core Architecture: Token Emitter vs Streaming Pipeline

jsonparse is a low-level SAX-style tokenizer. It reads a stream and emits raw parsing events like "key", "string", "number", "startObject", etc. You’re responsible for tracking nesting depth and reconstructing meaningful data structures.

// jsonparse: manual token handling
const JSONStream = require('jsonparse');
const parser = new JSONStream();

let currentKey = null;
let inTargetObject = false;

parser.onValue = (value) => {
  if (inTargetObject && currentKey === 'email') {
    console.log('Found email:', value);
  }
};

parser.onToken = (token, value) => {
  if (token === 'key') {
    currentKey = value;
  } else if (token === 'startObject') {
    // Track object depth manually if needed
  }
};

process.stdin.pipe(parser);

stream-json treats parsing as a composable pipeline. It provides stream transformers like StreamArray (for top-level arrays), Filter (to keep only certain paths), and WithParser (which wraps jsonparse internally). You chain these together like Unix pipes.

// stream-json: declarative pipeline
const { streamArray } = require('stream-json/streamers/StreamArray');
const { filter } = require('stream-json/filters/Filter');

process.stdin
  .pipe(streamArray())        // breaks [ {...}, {...} ] into individual objects
  .pipe(filter({ path: ['*', 'email'] })) // only pass items with an 'email' field
  .on('data', ({ value }) => {
    console.log('Found email:', value.email);
  });

📂 Handling Nested Structures

Parsing flat JSON is easy. The real test is navigating deep, nested objects without loading everything.

jsonparse forces you to track state manually. For example, to extract user.profile.email, you’d maintain a stack of current keys and check the path on every token.

// jsonparse: manual path tracking
const parser = new (require('jsonparse'))();
const path = [];

parser.onToken = (token, value) => {
  if (token === 'key') {
    path.push(value);
  } else if (token === 'endObject' || token === 'endArray') {
    path.pop();
  }
};

parser.onValue = (value) => {
  if (path.join('.') === 'user.profile.email') {
    console.log('Email:', value);
  }
};

stream-json handles paths declaratively. Its Filter and Pick utilities understand JSON paths natively, so you just specify what you want.

// stream-json: built-in path support
const { withParser } = require('stream-json');
const { pick } = require('stream-json/filters/Pick');

process.stdin
  .pipe(withParser())
  .pipe(pick({ filter: 'user.profile.email' }))
  .on('data', ({ value }) => {
    console.log('Email:', value);
  });

⚙️ Error Handling and Robustness

Both libraries stop parsing on malformed JSON, but their error reporting differs.

jsonparse throws errors directly on the stream. You must attach an 'error' listener to avoid crashing your process.

// jsonparse: basic error handling
const parser = new (require('jsonparse'))();
parser.on('error', (err) => {
  console.error('Parse error:', err.message);
});

stream-json follows standard Node.js stream error conventions. Errors propagate through the pipeline, so you can handle them at the end.

// stream-json: pipeline error handling
const pipeline = require('stream').pipeline;

pipeline(
  process.stdin,
  streamArray(),
  (err) => {
    if (err) console.error('Stream failed:', err.message);
  }
);

🛠️ Real-World Use Cases

Case 1: Processing a 10GB JSON Array of User Records

You only need the id and email fields.

• jsonparse: Possible but tedious. You’d track whether you’re inside a user object, then capture those two keys.
• stream-json: Clean and concise:

const { streamArray } = require('stream-json/streamers/StreamArray');
const { pick } = require('stream-json/filters/Pick');

fs.createReadStream('huge-users.json')
  .pipe(streamArray())
  .pipe(pick({ filter: ['id', 'email'] }))
  .on('data', ({ value }) => {
    // value = { id: 123, email: '...' }
  });

Case 2: Validating JSON Structure in Real Time

You’re receiving JSON line-by-line and need to reject invalid entries immediately.

• jsonparse: Better fit here because you get immediate token feedback and can reset the parser per line.
• stream-json: Designed for single JSON documents, not NDJSON (newline-delimited). You’d need extra glue code.

🔄 Maintenance and Ecosystem

As of 2024, jsonparse is stable but minimally maintained. Its API hasn’t changed in years because it solves one problem well: tokenizing JSON streams. No deprecation notices exist, but don’t expect new features.

stream-json is actively maintained with regular updates. It’s part of a broader ecosystem (stream-chain, stream-object) and integrates cleanly with modern Node.js streams (including async iterators).

📊 Summary Table

💡 Final Recommendation

• Reach for jsonparse when you’re building infrastructure — like a custom JSON validator, a protocol decoder, or when every byte of memory counts. You’ll trade convenience for control.

• Choose stream-json for application-level data processing — like ETL jobs, log analysis, or API integrations where you need to pluck values from huge JSON responses. It saves you from reinventing stream composition.

Both avoid the memory pitfalls of JSON.parse(), but stream-json gets you to a working solution faster for most real-world tasks, while jsonparse gives you the raw materials to build something specialized.