[dan-garden]

What changed

The first version of json-cursor: a strict JSON pull cursor. It reads keys, strings, numbers, booleans and null one at a time, straight from your bytes, so a caller builds its own types with no tree in between. It is part of FusionVault/streams#397, where it becomes the tokenizer under the streams JSON-to-Arrow decoder.

• Strict. Every byte is checked against RFC 8259, in skipped values too. skip keeps its own stack, with a depth limit of 128 by default, so no nesting can overflow the call stack.
• Exact. A Number keeps its text as written. as_i64 gives the exact whole value however it is written (7.0, 1e3), and as_f64 always the nearest double.
• Fast. It reads every value faster than serde_json, sonic-rs, simd-json and jiter, on bids, events and GeoJSON. It validates fastest on bids and GeoJSON, and level with jiter on events, where jiter skips the UTF-8 check inside strings.
• Light. No dependencies, no unsafe code, no_std with alloc, Rust 1.85 or later.

benchmarks/ races it against the other parsers and checks strictness and number exactness. Its results (benchmarks/results/*.csv) and charts back the README.

Results

Median CPU time per message, in nanoseconds, on one idle core of a Ryzen 9 5950X:

Message	Job	json-cursor	best of the others
Bids, 248 bytes	read every value	178	sonic-rs 199
Bids	validate	111	serde_json 153
Events, 723 bytes	read every value	282	jiter 372
Events	validate	203	jiter 201
GeoJSON, 3,246 bytes	read every value	4,160	sonic-rs 4,384
GeoJSON	validate	2,119	serde_json 2,725

Strictness and exactness:

• json-cursor gives RFC 8259's answer on all 26 cases of the strictness test. jiter and serde_json accept bad UTF-8 in the strings they validate, simd-json refuses 1e400 and a 30-digit integer, and sonic-rs crashes on a million nested arrays.
• On a million random long decimals, serde_json's default float parse misses the nearest double 319,907 times. json-cursor, jiter, simd-json and sonic-rs never do.

How it is tested

• RFC 8259 case by case, with each error's kind and position.
• All 318 JSONTestSuite cases, vendored under its MIT license (see NOTICE).
• A differential test against serde_json: two million random documents in CI, some of them damaged. Locally: 1,112,640 read alike, 887,072 refused by both, and 288 past a double's range, which serde_json refuses and json-cursor keeps as text.
• as_f64 bit for bit against Rust's own parser, and as_i64 against a 128-bit reference, on every edge of the fast paths and 300,000 random numbers.
• The bit tricks against plain byte loops, at every position.
• Mutation testing: 32 rules broken one at a time, and a test failed for every one.
• Rust 1.85, clippy with -D warnings, and the docs with -D warnings, all clean.

The last commit is a structure pass with no change in behaviour. Every function compiles to the same machine code as before it (4,008 instructions compared). The strictness, exactness and rounding results are byte-identical, and the random tests draw the same cases.

Docs checklist

Docs ship with the code, in the same pull request:

• CHANGELOG.md has a line for this change (CI fails without one when src/ changes)
• README updated where users will see it
• Every new public item has a doc comment with an example. Every public item has a doc comment, but the examples live in the crate docs and the README, both run as doctests, not yet on Cursor, Number and Error themselves.
• cargo test passes (the README examples are doctests)

🤖 Generated with Claude Code