#json

Source: quickjs-json.c — module exports JsonParser, JsonPushParser, JsonSerializer, JsonWriter and a function list.

A streaming/extended JSON reader plus simple read/write helpers.

#Module functions

#JsonParser

An incremental JSON tokenizer, built on Reader/Location from stream-utils.h. Each call to .parse() either advances one token (a state change), signals that the reader ran dry before a token was complete ("NEED_DATA"), or throws a SyntaxError (with the offending line:column) on malformed input.

new JsonParser(input, filename?)   // length 1; filename is optional, reflected in .location.file

input may be:

• a buffer (string, ArrayBuffer, or typed array) holding the whole document, or
• a pull function (buf, len) => bytesRead, called as needed to fill buf (up to len bytes), or
• an object exposing such a function as its read method — called with the object as this, e.g. a file wrapper: { read(buf, len) { return f.read(buf, 0, len); } }.

The function/method forms let the parser pull raw bytes on demand (e.g. from an fd) instead of requiring the whole document up front.

import { JsonParser } from 'json';

let p = new JsonParser('{"a":1,"b":[2,3]}');
let t;

while((t = p.parse()) !== 'NEED_DATA') console.log(t, JSON.stringify(p.token));
// OBJECT "{"  KEY "a"  NUMBER "1"  KEY "b"  ARRAY "["  NUMBER "2"  NUMBER "3"  ARRAY_END "]"  OBJECT_END "}"

"NEED_DATA" at the top level (after the root value is fully closed) simply means there's nothing left to parse — this class has no .write() to feed it more, unlike JsonPushParser.

#JsonPushParser

A "push" JSON parser: instead of pulling from an input, data is fed to it via .write(), at any byte boundary — including mid-string, mid-number, or mid-escape. It builds the parsed value incrementally into .root, and while a container is still open, .path reports the current nesting as an array of keys/indices (e.g. ["a", "b", 2]).

new JsonPushParser(callback?)   // length 0; optional callback function or options object

The optional argument may be:

• A single callback function (type, value) invoked for every token. type is a jr_type_t integer, value is the decoded JS value. The prototype's TYPE_* constants (see below) can be used to match against type.
• An options object with per-event callback methods. Recognized properties: error, value (for null/true/false/number/string), objectStart, objectEnd, arrayStart, arrayEnd, key. Each is invoked with a single decoded JS value argument. The options object is used as this for all callback invocations.

When no callbacks are given (or not all are present), the parser operates in builder mode: it builds the parsed value internally, retrievable via .root.

#Prototype constants

The following integer constants are exposed on the prototype for matching type values in callbacks:

import { JsonPushParser } from 'json';

let p = new JsonPushParser();

p.write('{"a":{"b":[1,2,');
console.log(p.path); // ["a", "b", 2]

p.write('3]}}');
console.log(p.root); // { a: { b: [1, 2, 3] } }

#JsonSerializer

A "pull" JSON serializer: it traverses the value lazily, producing only as much text as requested per .read() call, rather than building the whole string up front.

new JsonSerializer(value, indent?)   // length 1; indent defaults to 0 (compact)

import { JsonSerializer } from 'json';

let s = new JsonSerializer({ a: 1, b: [2, 3] });
let out = '';
let chunk;

while((chunk = s.read(4)) !== '') out += chunk;

console.log(out); // {"a":1,"b":[2,3]}

// Zero-copy: write straight into a fixed-size buffer, e.g. for a socket.
let s = new JsonSerializer(bigValue);
let buf = new Uint8Array(4096);
let n;

while((n = s.read(buf)) > 0) socket.send(buf.subarray(0, n));

#JsonWriter

A push-based incremental JSON writer: instead of serializing a JS value tree, the caller drives output by calling objectStart(), arrayStart(), key(), value(), arrayEnd(), and objectEnd() in document order. Output goes to a Writer (from stream-utils.h) — a buffer, fd, or any writable sink. Handles comma separation, indentation, and key/value ordering automatically, and throws TypeError on structural mistakes (e.g. a key() outside an object, a missing value after a key, mismatched end calls).

new JsonWriter(output?, options?)   // output is a buffer or writer; options may be a number (indent) or {indent}

output may be:

• a writable buffer (ArrayBuffer, typed array), or
• an object exposing a write(buf, offset, length) method.

options is either a number (the indent width, default 0 = compact) or an object with an indent property.

import { JsonWriter } from 'json';

let buf = new Uint8Array(1024);
let w = new JsonWriter(buf, 2);

w.objectStart();
  w.key('name');   w.value('Alice');
  w.key('scores'); w.arrayStart();
    w.value(95);
    w.value(87);
    w.value(92);
  w.arrayEnd();
w.objectEnd();

let text = new TextDecoder().decode(buf.subarray(0, w.written));
console.log(text);
// {
//   "name": "Alice",
//   "scores": [
//     95,
//     87,
//     92
//   ]
// }