Opejson 🩺🏴‍☠️

The Ultimate Surgical Instruments for JSON in Rust.

Forged as a byproduct of the Cognitive OS architecture.

opejson is a powerful macro library that allows you to manipulate serde_json::Value with surgical precision. It brings Perl-like Auto-vivification to Rust's JSON handling, overcoming strict type system barriers. It offers dynamic-language-like flexibility while maintaining absolute safety and zero-overhead performance.

"I'll sever those chaotic JSON paths... and stitch them back together."

📦 Installation

Add this to your Cargo.toml:

[dependencies]
opejson = "0.2.0"
serde_json = "1.0"

🏴‍☠️ Unlock "Law Mode"

If you want to use the Ope Ope no Mi interface (Anime-inspired aliases), enable the law_mode feature.

[dependencies]
opejson = { version = "0.2.0", features = ["law_mode"] }

🚀 Usage

opejson provides three distinct modes of operation:

1. Genesis Mode: The Creator. Auto-vivification, merging, and pre-allocation.
2. Strict Mode: The Surgeon. Safe, validated operations on existing data.
3. Law Mode: The "Ope Ope no Mi" Interface. (Requires feature flag).

use serde_json::json; is required for all examples.

1. Genesis Mode (Creation & Growth)

Automatically creates objects, expands arrays, and structurally merges JSON trees.

use opejson::genesis::*;

fn main() {
    let mut data = json!({});

    // 1. Mesh (Pre-allocation)
    // Deploys a multi-dimensional array instantly.
    mesh!(data, [10][20][5], serde_json::Value::Null);

    // 2. Suture (Safe Auto-vivification)
    // Creates paths safely. Stops and preserves if it hits an existing scalar.
    suture!(data, . "users" [0] . "name" = "Luffy");
    
    // 3. Force Suture (Destructive Auto-vivification)
    // Crushes existing scalars in the path to FORCIBLY build the new structure.
    force_suture!(data, . "users" [0] . "name" . "first" = "Monkey"); 

    // 4. Graft (Anatomical Merge / Shambles)
    // Surgically merges Objects or concatenates Arrays at the target joint.
    graft!(data, . "users" [0] = json!({"role": "Captain", "bounty": 3000000000u64}));
    
    // 5. Implant (Void Filler / Default Injection)
    // Injects data ONLY if the target is Null (Void). Preserves healthy data.
    implant!(data, . "users" [0] . "status" = "Alive");
    
    // 6. Acquire (Heart Extraction)
    // Safe read, returns Result<&Value, Error>.
    let name_res = acquire!(data, . "users" [0] . "name" . "first").unwrap();
    assert_eq!(name_res.as_str().unwrap(), "Monkey");
}

2. Strict Mode (Precision Surgery)

Strictly operates on existing paths. Returns Option. Safe for data validation and probing unknown JSON.

use opejson::strict::{biopsy, incise, excise};

fn main() {
    let mut data = json!({ "id": 101, "meta": { "active": true } });

    // 1. Biopsy (Probe / Read) -> Option<&Value>
    let is_active = biopsy!(data, . "meta" . "active");

    // 2. Incise (Inject / Write) -> Option<()>
    // Only succeeds if the path ALREADY exists.
    let res = incise!(data, . "id" = 102); 
    assert!(res.is_some());
    
    let fail = incise!(data, . "unknown" = 999); 
    assert!(fail.is_none());

    // 3. Excise (Remove / Delete) -> Option<Value>
    // cleanly cuts out the target node.
    let removed = excise!(data, . "meta");
}

🎯 Dynamic Keys & Indices

You can use variables (expressions) for keys and indices by wrapping them in parentheses ( ).

let key = "stats";
let idx = 5;

// Strict Read
biopsy!(data, . (key) [idx]); 

// Genesis Write
suture!(data, . (key) [idx] = "Updated");

3. Law Mode (The Ope Ope no Mi) 🏴‍☠️

For those who possess the ultimate power. This mode maps surgical operations to the abilities of the "Ope Ope no Mi".

(Requires features = ["law_mode"])

use opejson::law::*;

fn main() {
    let mut target = json!(null);

    // "ROOM." (Expand N-dimensional Space)
    room!(target, [3][3][3]);

    // "TAKT." (Auto-vivify structure)
    takt!(target, [1][1][1] = "Heart");

    // "SHAMBLES." (Merge / Append)
    let switch_obj = json!(["New Limb"]);
    shambles!(target, [0] = switch_obj);
    
    // "MES." (Extract)
    let heart = mes!(target, [1][1][1]).unwrap();
}

🧪 Error Types

acquire! (Genesis Read) returns a Result<&Value, opejson::Error>:

• PathNotFound(String): The specified JSON path does not exist.

Note: Strict Mode (biopsy!) returns Option<&Value> instead, following the idiomatic "silent probe" pattern.

⚠️ Surgical Precision Required

opejson is designed as a sharp scalpel, prioritizing performance and brevity over restrictive safety barriers.

• Indices are Cast Raw: Array indices are cast using as usize. Passing negative values will wrap to huge numbers, potentially causing massive allocations (OOM) in Genesis Mode.
• Handle with Care: You are the surgeon. Verify your dynamic inputs before operating.

🧠 Design Philosophy: Minimal Intervention

opejson is a precision instrument, not a safety-guarded machine. It follows a "Zero-Overhead" doctrine.

1. Performance First

Macros expand at compile time. Adding complex, hidden validation inside expansion would increase branching and reduce throughput. opejson prioritizes raw execution speed, compiling down to purely physical memory operations (inline matching, extend, append).

2. Explicit Responsibility

Error handling should be visible and under the caller’s control. Macros are a sealed environment; they should not silently reinterpret or absorb structural errors. Responsibility belongs to the surgeon (the programmer).

3. "Programmer Errors" are not "Library Errors"

Misusing indices (e.g., negative wrapping via as usize) or logical flaws in your loops are treated as programmer mistakes. Rust provides the tools to prevent these; opejson will not add runtime bloat to compensate for them.

4. Genesis vs. Strict

• Genesis Mode: Permissive, creative, and dangerously fast (Auto-vivification).
• Strict Mode: Safe, non-destructive, and explicit.

Choose your instrument according to the risk of the operation.

⚡ Comparison: The Pain vs. Opejson

Without Opejson (Standard Serde):

// The "Option Hell"
if let Some(users) = data.get_mut("users") {
    if let Some(user) = users.get_mut(0) {
        if let Some(obj) = user.as_object_mut() {
            obj.insert("name".to_string(), json!("Chopper"));
        }
    }
}

With Opejson:

// Surgical Precision (Auto-vivification)
suture!(data, . "users" [0] . "name" = "Chopper");

📊 Testing & Performance

Comprehensive Validation

• 133 test cases covering all macro patterns, dynamic keys, Auto-vivification logic, and structural edge cases.
• Validated up to 100 levels of deep nesting with zero runtime overhead.

Performance Benchmark

Measurements taken from tests/performance_limit.rs (Release mode on standard hardware):

• 256-Level Deep Penetration: ~366µs
• 100,000 Massive Sutures: ~28ms
• Overall Throughput: ~3,560,000 operations/sec

Zero runtime overhead for path parsing. > The macro expands directly into raw pointer access and pattern matching during compilation, making complex JSON manipulation as fast as native struct access.

License

MIT