Skip to main content

Crate jshift

Crate jshift 

Source
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: ToJsonBytes and 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.
OwnedPathSegment
Owned path segment (see Path).
PathSegment
Represents a segment in a JSON path (either a string key or a zero-indexed array index).

Traits§

FromJsonSlice
Trait implemented by types that can be parsed directly from a raw JSON byte slice.
ToJsonBytes
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 s as it would appear inside a JSON string (no surrounding quotes).
escape_json_string
Serialize s as 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 requires new_value to 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::InvalidPath for malformed path syntax instead of silently dropping segments.
upsert_at_path
Upsert new_value at path, 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 s into out.
write_json_string_content
Append the escaped form of s (content only, no surrounding quotes) into out.

Derive Macros§

JsonMutatorSchema