json
Source: quickjs-json.c — module exports JsonBuilder, tee, JsonParser, JsonPushParser, JsonSerializer, JsonWriter and a function list.
A streaming/extended JSON reader and writer. One-shot parsing is JSON.parse, or JSON5/JSONC from
lib/json5.js and lib/jsonc.js, which compose these engines.
Comments: JsonParser and JsonPushParser are tolerant of C++ (// ... to end of
line) and C (/* ... */) comments wherever whitespace is allowed, including between a
value and its comma, and across write() chunk boundaries. Comment markers inside strings
are plain text. A / that doesn't start a comment is a syntax error. Set dialect: 'json' for
strict JSON without comments.
Set parser.comments = true on a JsonParser to get each comment back as a
JsonParser.COMMENT token (parser.token is the text including // or /* */) instead of
having it skipped. JsonPushParser always skips them.
Module functions
| Function | Args | Description |
|---|---|---|
tee(...sinks) | 1+ | A sink that forwards every event to each sink (see Connecting engines). |
read() and write() were removed: use JSON.parse / JSON5.parse and JSON.stringify / JsonSerializer.
Blob.prototype.json() parses with the strict JsonParser reader, so nesting depth is not limited.
What is serialized
JsonSerializer follows JSON.stringify rule for rule (tests/unittests/test-json.js
compares them on every case below):
| JS value | Written as |
|---|---|
toJSON() result | the result; called with the key as a string ('' at the root, '0' for an array item); runs before the replacer |
Date | an ISO string, through its toJSON() |
null, boolean, string, finite number | itself |
NaN, Infinity, -Infinity | null |
Number, String, Boolean object | its primitive |
undefined, function, symbol | skipped in an object (key and value); null in an array; the whole call returns undefined at the root |
| array hole | null |
| array | its indices only; other properties are ignored |
| object | its own enumerable string keys, integer keys first |
JSON.rawJSON(text) | text, as given |
bigint | throws TypeError |
| circular reference | throws TypeError (Converting circular structure to JSON) |
replacer is a function, called as replacer.call(holder, key, value) for every property
including the root (holder is { '': value } there), or an array whose string and number items
are the only keys written, in its order. space is a number (spaces per level, 0 to 10) or a
string (its first 10 characters per level, e.g. '\t'); no space writes no whitespace at all.
Strings are written with lone surrogates as \udXXX escapes. Nesting depth is not limited
(nothing recurses), so an object JSON.stringify rejects with a RangeError still serializes here.
import { JsonSerializer } from 'json';
function write(...args) {
const s = new JsonSerializer(...args);
let out, chunk;
while((chunk = s.read(4096)) !== undefined) out = (out ?? '') + chunk;
return out;
}
write({ when: new Date(0), skipped: undefined, n: NaN }); // '{"when":"1970-01-01T00:00:00.000Z","n":null}'
write([1, 2], null, '\t'); // '[\n\t1,\n\t2\n]'
write({ a: 1, b: 2 }, ['b']); // '{"b":2}'
write(1n); // TypeErrorJSONL
Moved to lib/jsonl.js, see doc/js/jsonl.md: import { JSONL } from './jsonl.js' (not an export of this module any more).
Connecting engines: pump(), connect(), tee, JsonBuilder
Every source runs into every sink in C. A sink is a JsonWriter, a JsonBuilder, a tee(...) or any object with the sink
methods (key, string, number, null, true, false, objectStart, objectEnd, arrayStart, arrayEnd, comment,
raw; a missing method drops the event, a method that throws stops the run and the exception propagates).
import { JsonParser, JsonPushParser, JsonBuilder, JsonWriter, tee } from 'json';
const b = new JsonBuilder(); // { plain: true }: objects get Object.prototype
new JsonParser('{"a":[1]}').pump(b, true); // 0 = ended, 1 = the reader has no data now
b.root; // {a: [1]}
const p = new JsonPushParser().connect(tee(b, new JsonWriter(sink)));
p.write('[1,'); p.write('2]'); p.close(); // events go to the sink, not to the constructor's callbacks| Member | Does |
|---|---|
parser.pump(sink, end?) | runs the pull parser into the sink; with end a dry reader ends the document. Throws the SyntaxError of the first error event |
pushParser.connect(sink) / .sink | write() and close() drive the sink; returns the parser |
tee(a, b, ...) | a sink that sends every event to each, in order |
new JsonBuilder(options?) | root, path, take() (completed top-level values), the sink methods |
[Symbol.for('qjs.jsonsink')]() | handshake of the native sinks: the address of their JsonEventSink, so another module needs no class id |
A native sink that refuses an event (a full buffer, a structural mistake) makes pump()/write() throw an Error with code = the
negative result; a JS-object sink throws its own exception.
JsonParser
next() returns the next event as { type, value?, loc: { line, column, offset } } and the parser is iterable
(for(const { type, value } of new JsonParser(text))); an error event throws the SyntaxError.
The iteration ends when the document is complete or the reader has no data now. A COMMENT event has its text as value, a NUMBER event
has its source text as raw (1.50, 12345678901234567890) next to the number in value.
Constructor options (second argument, a string is the file name): new JsonParser(input, { dialect, strict, comments, filename }).
dialect is 'json', 'jsonc', 'json5', 'jsonl' or 'legacy' (the default: lenient, skips bad input and goes on, but an unclosed array or object at the end of the input is still an unexpected-end error), strict: true
means 'json', comments: true delivers comments as COMMENT events. JsonPushParser({ dialect, strict, ... }) takes the same two
keys next to its callbacks. NUMBER text of every dialect (0x1F, +.5, Infinity) becomes the right number in a builder.
new JsonParser(input, filename?) // length 1; filename is optional, reflected in .location.fileinput may be:
- a buffer (string,
ArrayBuffer, or typed array) holding the whole document, or - a pull function
(buf, len) => bytesRead, called as needed to fillbuf(up tolenbytes), or - an object exposing such a function as its
readmethod — called with the object asthis, e.g. a file wrapper:{ read(buf, len) { return f.read(buf, 0, len); } }, or - a file descriptor number (e.g.
f.fileno()), read withread(2); the parser does not close it.
The function/method/fd forms let the parser pull raw bytes on demand instead of requiring the whole document up front. Input is pulled in blocks of up to 16384 bytes (len is 16384; a read may return fewer bytes, and returning 0 ends the iteration for now), so the parser can read past the end of the JSON document — don't share the source with another consumer.
| Member | Args | Kind | Description |
|---|---|---|---|
next() | 0 | method | The next event as an iterator result. Throws the SyntaxError of an error event. |
pump(sink, end?) | 1 | method | Runs the parser into a sink, returns 0 when the input ended, 1 when the reader has no data now. |
depth | — | getter | Current nesting depth (enumerable). |
location | — | getter | A Location reflecting the current input position (line/column/byte offset/filename); live, like JsonPushParser's (enumerable). |
comments | — | getter/setter | Boolean, default false. When true, each // or /* */ comment is a JsonParser.COMMENT event instead of being skipped. |
import { JsonParser } from 'json';
for(const { type, value } of new JsonParser('{"a":1,"b":[2,3]}')) console.log(type, value);
// OBJECT KEY a NUMBER 1 KEY b ARRAY NUMBER 2 NUMBER 3 ARRAY_END OBJECT_ENDJsonPushParser
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 objectThe optional argument may be:
- A single callback function
(type, value)invoked for every token.typeis aJsonEventTypeinteger,valueis the decoded JS value. The prototype'sTYPE_*constants (see below) can be used to match againsttype. - 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 asthisfor 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.
| Member | Args | Kind | Description |
|---|---|---|---|
write(chunk) | 1 | method | Feeds a chunk of input text (string or buffer). Throws a SyntaxError on malformed input, but the parser remains usable — it resyncs at the next structural boundary (a comma or a closing bracket) and subsequent .write() calls continue from there. |
close() | 0 | method | Signals end of input: flushes a trailing top-level scalar (e.g. a bare 42 with nothing after it) that couldn't otherwise be told apart from "more digits might follow". Throws if the document is incomplete (unclosed container, mid-token, or nothing written yet). |
root | — | getter | The value parsed so far. undefined until the top-level value is complete (enumerable). |
path | — | getter | Array of keys/indices describing where the next byte will land while a container is still open; empty once parsing is done (enumerable). |
Prototype constants
The following integer constants are exposed on the prototype for matching type values in callbacks:
| Constant | Description |
|---|---|
TYPE_ERROR | Parse error |
TYPE_NULL | null literal |
TYPE_TRUE | true literal |
TYPE_FALSE | false literal |
TYPE_NUMBER | Numeric value |
TYPE_STRING | String value |
TYPE_OBJECT / TYPE_OBJECT_START | Object opening { |
TYPE_OBJECT_END | Object closing } |
TYPE_ARRAY / TYPE_ARRAY_START | Array opening [ |
TYPE_ARRAY_END | Array closing ] |
TYPE_KEY | Object key |
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] } }Planned: lifting the module to standard shapes
> Spec, not yet implemented except where marked. Full table and order of work: TODO.md
> Tier 18. Nothing below changes JsonParser, JsonPushParser, JsonSerializer or
> JsonWriter today.
Other runtimes expose JSON through these names; the module converges on them:
| Name | Shape | Origin | Status |
|---|---|---|---|
JSONL.parse, JSONL.parseChunk | above | Bun | done |
JsonParseStream, ConcatenatedJsonParseStream, JsonStringifyStream | lib/jsonStreams.js | Deno @std/json | done |
Blob.prototype.json() | see the blob doc | Bun, web Body mixins | done |
JSON5.parse(text), JSON5.stringify(value, replacer?, space?) | Bun's Bun.JSON5 | Bun | planned |
JSONC.parse(text) | Bun's Bun.JSONC: comments and trailing commas | Bun | planned |
JsonPushParser onValue, paths, end() | npm @streamparser/json JSONParser | npm | planned |
read() and write() duplicate JSON.parse and JSON.stringify and are to be deprecated
once JSON5/JSONC exist; JsonParser, JsonSerializer and JsonWriter stay as the
engines behind the standard names, since no other runtime has a shape for them.
import { JSON5, JSONC } from 'json'; // planned
JSON5.parse("{a:'x', b:0x10, c:[1,],}"); // {a: 'x', b: 16, c: [1]}
JSON5.stringify({ a: 1, 'b-c': 'x' }); // "{a:1,'b-c':'x'}"
JSONC.parse('{/*c*/"a":1,}'); // {a: 1}Planned: streaming jread events into a JsonBuilder or a JsonWriter
> Not yet implemented, unsure if it ever will be. This section is a design sketch kept
> for reference. None of the names below exist; JsonPushParser today works as described
> above.
jr_read(cb, chunk, len, user_data, state) already reports every token through a callback.
The idea is two ready-made callbacks, so that the C parser can feed either sink directly,
chunk by chunk, with no JS value built in between.
Sinks
| Sink | Callback | user_data | Notes |
|---|---|---|---|
JsonBuilder (jbuilder.h) | jbuild_callback | the JsonBuilder* | The existing builder-mode callback, moved out of quickjs-json.c. Needs no new logic. |
JsonWriter (jwrite.h) | jwrite_callback | a JsonWriteSink* | New. Writes formatted JSON text as tokens arrive. |
typedef struct { JsonWriter* wr; ssize_t error; } JsonWriteSink; /* error: first -JWRITE_E_*, or 0 */
void jbuild_callback(JsonEventType, const jr_str_t*, void* user_data);
void jwrite_callback(JsonEventType, const jr_str_t*, void* user_data);jread.h itself stays generic and gains nothing: the callbacks sit next to their sinks.
The writer path
- No JS values, no
JSContext.jwrite.cis pure C: key and value tokens go straight tojwrite_key(wr, str, len),jwrite_string(wr, str, len)andjwrite_number(wr, str, len). They share the writer's ordering checks, commas and indentation, so the writer's options apply as usual (indent,bareKeys,singleQuotes,minify). - Number text passes through as written.
12345678901234567890and1e2are not re-formatted: the callback usesjwrite_number, which writes the text as given. WithhexNumbersset,jwrite_numberturns a plain integer (up to 18 digits) into hex and writes anything else as given. - Errors. A
jr_callbackreturnsvoid, so the first failure (a negativejwrite_*result,-JWRITE_E_*) is kept in the sink and later events are ignored.write()andclose()then throw, using the message fromjwrite_error_message().
JsonPushParser modes
| Mode | Chosen when | Callback | user_data |
|---|---|---|---|
| builder | default, as today | jbuild_callback | the parser's builder |
| writer | the constructor argument is a JsonWriter | jwrite_callback | the parser's JsonWriteSink |
| JS callbacks | a function or an options object, as today | jread_callback | the parser |
In writer mode the parser keeps a reference to the JsonWriter so it stays alive, and
write() and close() throw when the sink reports an error instead of swallowing it.
root is undefined and path is empty, since no tree is built.
const w = new JsonWriter(out, { indent: 2 });
const p = new JsonPushParser(w); // events go straight to the writer
p.write('{"a":[1,');
p.write('2]}');
p.close(); // out now holds the reformatted documentRelation to WalkInterface
WalkInterface (jwalk.h) is the generic sink shape used by the value walker. These two
callbacks are fast paths beside it that skip the JSValue round trip. A third adapter,
jread to WalkInterface, could serve arbitrary sinks later.
Steps, if it is ever built
- Move
jread_callback_buildtojbuilder.casjbuild_callback; the existingJsonPushParsertests must still pass. - Add
JsonWriteSinkandjwrite_callback, built on the existing purejwrite_*events; test with a C harness feeding chunked input. - Add the constructor mode and the
write()/close()error checks. Tests: reformatting equalsJSON.stringify(JSON.parse(s), null, 2); large integers survive; a too-small output buffer throws.
Open question
Pass number tokens through as written (1e2 stays 1e2), or normalize them as
JSON.parse followed by a write would (100)? Pass-through is the recommendation.
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, replacer?, space?) // the arguments of JSON.stringify
new JsonSerializer(value, indent) // a number or string alone is the space; default: compactIt serializes by the rules in What is serialized: read() returns exactly
the text JSON.stringify() returns, in pieces. A value with no JSON form (undefined) gives no text at
all, so the first read() is undefined. toJSON() and the replacer run once per property, as
the walk reaches it, and an error they throw comes out of the read() that reached it; after an
error the serializer is finished.
| Member | Args | Kind | Description |
|---|---|---|---|
read(n) | 1 | method | Returns a string of up to n characters of serialized JSON; once exhausted it returns undefined (not ''), so loop on truthiness. |
read(buffer, offset?, length?) | 1–3 | method | Writes serialized bytes directly into the given ArrayBuffer/TypedArray (no intermediate copy), starting at offset for up to length bytes — or the whole buffer if omitted. Returns the number of bytes written, 0 once exhausted. Suited to chunking output straight into e.g. a network buffer. |
location | — | getter | A Location reflecting how far into the output stream production has advanced (enumerable). |
indent | — | getter/setter | The space in effect: spaces per level (0 to 10), or the length of a string space. Setting it takes a number or string and applies from the next event. |
path | — | getter | The keys from the root to the property being written. |
finished, started, error | — | getter | Whether production is complete, has begun, or failed in the last read(). blocked is always false: a step never waits for room. |
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), and an Error when the output buffer is full.
new JsonWriter(output?, options?) // output is a buffer or writer; options may be a number (indent) or {indent, bareKeys, singleQuotes, hexNumbers, minify}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 any of these keys (all default off). They are read once, when the writer is constructed; the writer has no properties for them.
| Key | Effect |
|---|---|
indent | Spaces per nesting level; 0 writes no newlines. |
bareKeys | Write keys that are plain identifiers ([A-Za-z_$][A-Za-z0-9_$]*) unquoted: id: 1. Other keys stay quoted. JSON5. |
singleQuotes | Write strings and quoted keys in '...'; ' is escaped, " is not. JSON5. |
hexNumbers | Write integral numbers (|n| up to 2^53-1) as 0xff / -0x1f; other numbers are unchanged. JSON5. |
minify | No whitespace at all (no newlines, indentation or space after :), whatever indent says. |
| Member | Args | Kind | Description |
|---|---|---|---|
objectStart() | 0 | method | Writes { and opens a new object context. Increments the nesting level. Returns bytes written. |
objectEnd() | 0 | method | Writes }, closing the current object. Throws if not inside an object, or if the last key has no value. Returns bytes written. |
arrayStart() | 0 | method | Writes [ and opens a new array context. Increments the nesting level. Returns bytes written. |
arrayEnd() | 0 | method | Writes ], closing the current array. Throws if not inside an array. Returns bytes written. |
key(name) | 1 | method | Writes "name": inside the current object. Throws if not inside an object, or if the previous key still expects a value. Returns bytes written. |
value(val) | 1 | method | Writes a JSON primitive (string, number, boolean, null). Inside an object, must follow a key(). Inside an array, writes the next element. Returns bytes written. |
written | — | getter | Total number of bytes written so far, counting every byte of output. |
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
// ]
// }Export list
Generated by utilities/doc-api.js from the json dump of utilities/api-surface.sh: 111 members. Edit the text above this block, not the block.
Functions: tee()
JsonBuilder
class, constructible
- methods:
arrayEnd(),arrayStart(),comment(),error(),false(),key(),null(),number(),objectEnd(),objectStart(),raw(),string(),take(),true(),[Symbol.for('qjs.jsonsink')]() - properties:
path (get),root (get),[Symbol.toStringTag]
JsonParser
class, constructible
- static values:
ARRAY = 6,ARRAY_END = 7,COMMENT = 11,FALSE = 3,KEY = 10,NULL = 1,NUMBER = 4,OBJECT = 8,OBJECT_END = 9,STRING = 5,TRUE = 2 - methods:
next(),pump(),[Symbol.iterator]() - properties:
ARRAY = 6,ARRAY_END = 7,COMMENT = 11,FALSE = 3,KEY = 10,NULL = 1,NUMBER = 4,OBJECT = 8,OBJECT_END = 9,STRING = 5,TRUE = 2,comments (get/set),depth (get),location (get),[Symbol.toStringTag]
JsonPushParser
class, constructible
- methods:
close(),connect(),write() - properties:
TYPE_ARRAY = 6,TYPE_ARRAY_END = 7,TYPE_ARRAY_START = 6,TYPE_ERROR = 0,TYPE_FALSE = 3,TYPE_KEY = 10,TYPE_NULL = 1,TYPE_NUMBER = 4,TYPE_OBJECT = 8,TYPE_OBJECT_END = 9,TYPE_OBJECT_START = 8,TYPE_STRING = 5,TYPE_TRUE = 2,error (get),location (get),path (get),root (get),sink (get),[Symbol.toStringTag]
JsonSerializer
class, constructible
- methods:
next(),read(),[Symbol.iterator]() - properties:
blocked (get),error (get),finished (get),indent (get/set),location (get),path (get),root (get),started (get),[Symbol.toStringTag]
JsonWriter
class, constructible
- methods:
arrayEnd(),arrayStart(),comment(),error(),false(),key(),null(),number(),objectEnd(),objectStart(),raw(),string(),true(),value(),[Symbol.for('qjs.jsonsink')]() - properties:
depth (get),stack (get),written (get),[Symbol.toStringTag]