jshift
jshift is a schema-guided, 100% safe Rust JSON path reader and in-place mutator.
It is built for high-performance middleboxes, API gateways, webhook routers, and data pipelines that need to selectively query and modify JSON documents without the full AST allocate / serialize cycle of traditional parsers.
Key Features
- Path-selective scans: Read and write targeted fields on raw bytes without deserializing the whole document.
- 100% Safe Rust:
#![forbid(unsafe_code)]. Resizes use optimized safe slice rotations (compiles down tomemmove-class moves). - Zero-copy reads:
find_valuereturns a slice into the original buffer. - Type-safe derive macros:
#[derive(JsonMutatorSchema)]generates readers and in-place mutators. - Object & array CRUD: Update, upsert, delete keys; append, index, and delete array elements.
- Correct string encoding:
ToJsonBytesand key upserts escape",\, and control characters.
Contract: jshift is a non-validating path engine. It assumes mostly well-formed JSON along the path you traverse. Callers must supply complete JSON value bytes for raw mutations (or use
ToJsonBytesfor primitives/strings).
Performance (illustrative)
Benchmarks on a ~10MB document where the target key sits after a large array, comparing jshift path scan/mutate vs full serde_json parse + (for writes) re-serialize:
| Benchmark | Engine | Mean | vs serde_json |
|---|---|---|---|
| Find Value | serde_json |
~239 ms | baseline |
jshift |
~12 ms | ~20× | |
| Mutate Value | serde_json |
~211 ms | baseline |
jshift |
~11 ms | ~19× |
These numbers reflect that workload and machine; they are not a claim that jshift is always faster than serde for every JSON task. For full typed deserialization, use serde.
Installation
[]
= "0.1"
Quick Start: AI dataset cleaning (JSONL)
In pipelines that filter or tag training samples, records are often JSON Lines. Instead of parse → allocate → re-serialize millions of lines, update fields in-place on raw bytes.
1. Define a schema
use JsonMutatorSchema;
2. Selective reads
let mut line = b"{\"instruction\": \"Translate...\", \"tokens\": 1024, \"status\": \"pending\", \"tags\": [\"llm\"]}".to_vec;
let record = read_from_json.unwrap;
assert_eq!;
assert_eq!;
3. In-place mutations & array append
let mut mutator = mutator;
if record.tokens > 512
let updated = read_from_json.unwrap;
assert_eq!;
assert_eq!;
Low-level API
use ;
let mut json = b"{\"user\": \"farmer\", \"score\": 9.5}".to_vec;
let path = parse_path;
assert_eq!;
mutate_value.unwrap;
assert_eq!;
// Strings are escaped for you:
mutate_value.unwrap;
How mutations work
When a replacement changes size, jshift resizes the Vec<u8> and rotates the tail:
Upsize: resize → tail.rotate_right(delta) → write new value
Downsize: tail.rotate_left(delta) → truncate
Capabilities
Object operations
mutate_value— overwrite a value at a pathupsert_object_key— insert or update a key (keys are JSON-escaped)delete_key— remove a key/value and fix commas
Array operations
append_to_array— append with comma injectionarray_len— count elements without allocating an arraydelete_index— remove an element and fix commas
Paths
Dot and bracket paths, e.g. metadata.tags[0].name.
Related crates
| Crate | Role |
|---|---|
serde_json |
Full AST / typed serde |
gjson |
Fast path reads |
simd-json / sonic-rs |
High-performance parsers |
| jshift | Path scan + in-place buffer mutate + schema derive |
License
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.