Expand description
jshift — Schema-guided, safe in-place JSON path reader and mutator.
This crate provides a 100% safe Rust engine to selectively read, mutate, upsert,
and delete values inside raw JSON byte buffers (&[u8] and Vec<u8>) without
building a full AST. Path scans return zero-copy slices; mutations resize the
buffer and shift the tail with safe slice rotations.
§Features
- Zero-copy reads: Find values as slices into the raw buffer.
- In-place mutations: Safe byte-shifting (including resize) via slice rotations.
- Macro-generated schemas:
#[derive(JsonMutatorSchema)]for typed readers and mutators. - Array and object CRUD: Insert, update, append, and delete dynamically.
- JSON string escaping:
ToJsonBytesand key upserts escape special characters.
§Quick Start
use jshift::{find_value, mutate_value, parse_path};
let mut json = b"{\"user\": \"farmer\", \"score\": 9.5}".to_vec();
let path = parse_path("score");
// Read value
let score_bytes = find_value(&json, &path).unwrap();
assert_eq!(score_bytes, b"9.5");
// Mutate in-place
mutate_value(&mut json, &path, b"10.0").unwrap();
assert_eq!(json, b"{\"user\": \"farmer\", \"score\": 10.0}".to_vec());§High-Impact Real-World Use Case: LLM Dataset Processing (JSONL)
In AI training pipelines (e.g., LoRA finetuning), datasets are stored as JSONL files. You can inspect token lengths and mark records as skipped or cleaned in-place:
use jshift::JsonMutatorSchema;
#[derive(JsonMutatorSchema)]
struct TrainingRecord {
#[json(path = "tokens")]
tokens: usize,
#[json(path = "status")]
status: String,
}
let mut line = b"{\"instruction\": \"Translate...\", \"tokens\": 1024, \"status\": \"pending\"}".to_vec();
// Parse selectively
let record = TrainingRecord::read_from_json(&line).unwrap();
// Skip long contexts in-place!
if record.tokens > 512 {
let mut mutator = TrainingRecord::mutator(&mut line);
mutator.set_status("skipped").unwrap();
}
assert_eq!(
line,
b"{\"instruction\": \"Translate...\", \"tokens\": 1024, \"status\": \"skipped\"}".to_vec()
);Structs§
- Path
- Owned, reusable JSON path.
Enums§
- Error
- Errors returned by scanning and mutating operations.
- Owned
Path Segment - Owned path segment (see
Path). - Path
Segment - Represents a segment in a JSON path (either a string key or a zero-indexed array index).
Traits§
- From
Json Slice - Trait implemented by types that can be parsed directly from a raw JSON byte slice.
- ToJson
Bytes - Trait implemented by types that can be serialized directly into a JSON byte representation.
Functions§
- append_
to_ array - Appends a new value to the end of a JSON array located at the specified path.
- array_
len - Returns the number of elements in the array located at the specified path.
- delete_
index - Deletes an element from a JSON array located at the specified path by its index.
- delete_
key - Deletes a key-value pair from a JSON object located at the specified path.
- escape_
json_ key - Escape
sas it would appear inside a JSON string (no surrounding quotes). - escape_
json_ string - Serialize
sas a JSON string literal (including surrounding quotes). - find_
value - Locates a JSON value byte-slice within a raw JSON buffer by its path.
- from_
json_ string - Parse a JSON string literal (including surrounding quotes) into an unescaped
String. - mutate_
value - Mutates a JSON value in-place inside a
Vec<u8>buffer by its path. - mutate_
value_ checked - Like
mutate_value, but requiresnew_valueto parse as exactly one complete JSON value (object, array, string, number,true/false/null) with no trailing junk after optional whitespace. - parse_
path - Parses a dot-and-bracket notation path string into zero-copy path segments.
- try_
parse_ path - Strict path parser. Returns
Error::InvalidPathfor malformed path syntax instead of silently dropping segments. - upsert_
at_ path - Upsert
new_valueatpath, creating missing object parents as{}. - upsert_
object_ key - Upserts (inserts or updates) a key-value pair in a JSON object located at the specified path.
- write_
json_ string - Append a JSON string literal (including surrounding quotes) for
sintoout. - write_
json_ string_ content - Append the escaped form of
s(content only, no surrounding quotes) intoout.