jshift 0.7.0

Schema-guided typed JSON on raw bytes: path get/mutate, open views, project — without a Value tree.
Documentation
//! Byte-level `#[json(flatten)]` vs serde `#[serde(flatten)]`.
//!
//! ```sh
//! cargo run --release --example flatten_bench --features "derive,serde"
//! ```
//!
//! Fairness:
//! - **Small object**: same fields; jshift path scans vs full serde flatten visitor.
//! - **Fat object**: jshift still only reads named paths; serde still materializes
//!   the whole typed graph (and must visit every key for flatten bookkeeping).
//! - **Open mutate**: jshift upsert one flattened field in place vs serde
//!   from_slice → change → to_vec.
//! - **Schema emit**: closed card (flat keys) vs `serde_json::to_vec`.

use std::time::Instant;

use jshift::{JsonView, ObjectBuilder};

const WARMUP: usize = 5;

fn mean_ns(iters: usize, mut body: impl FnMut()) -> f64 {
    for _ in 0..WARMUP {
        body();
    }
    let t0 = Instant::now();
    for _ in 0..iters {
        body();
    }
    t0.elapsed().as_secs_f64() * 1e9 / iters as f64
}

fn fmt_time(ns: f64) -> String {
    if ns < 1_000.0 {
        format!("{ns:.0} ns")
    } else if ns < 1_000_000.0 {
        format!("{:.1} µs", ns / 1_000.0)
    } else {
        format!("{:.2} ms", ns / 1_000_000.0)
    }
}

fn ratio(serde_ns: f64, j_ns: f64) -> String {
    if j_ns <= 0.0 {
        "∞".into()
    } else {
        format!("{:.1}×", serde_ns / j_ns)
    }
}

fn row(name: &str, j: f64, s: f64) {
    println!(
        "  {:<52}  jshift {:>12}   serde {:>12}   serde/jshift {:>8}",
        name,
        fmt_time(j),
        fmt_time(s),
        ratio(s, j)
    );
}

// ── jshift ──────────────────────────────────────────────────────────────────

#[derive(Debug, Clone, PartialEq, JsonView)]
struct Meta {
    #[json(path = "created_at")]
    created_at: String,
    #[json(path = "source")]
    source: String,
}

#[derive(Debug, Clone, PartialEq, JsonView)]
struct Event {
    #[json(path = "id")]
    id: u64,
    #[json(flatten)]
    meta: Meta,
}

#[derive(Debug, Clone, PartialEq, JsonView)]
struct Tags {
    #[json(path = "env")]
    env: String,
    #[json(path = "region")]
    region: String,
}

#[derive(Debug, Clone, PartialEq, JsonView)]
struct DualEvent {
    #[json(path = "id")]
    id: u64,
    #[json(flatten)]
    meta: Meta,
    #[json(flatten)]
    tags: Tags,
}

// ── serde ───────────────────────────────────────────────────────────────────

#[derive(Debug, Clone, PartialEq, serde::Deserialize, serde::Serialize)]
struct SerMeta {
    created_at: String,
    source: String,
}

#[derive(Debug, Clone, PartialEq, serde::Deserialize, serde::Serialize)]
struct SerEvent {
    id: u64,
    #[serde(flatten)]
    meta: SerMeta,
}

#[derive(Debug, Clone, PartialEq, serde::Deserialize, serde::Serialize)]
struct SerTags {
    env: String,
    region: String,
}

#[derive(Debug, Clone, PartialEq, serde::Deserialize, serde::Serialize)]
struct SerDualEvent {
    id: u64,
    #[serde(flatten)]
    meta: SerMeta,
    #[serde(flatten)]
    tags: SerTags,
}

fn small_event_json() -> Vec<u8> {
    br#"{"id":7,"created_at":"2026-07-22T00:00:00Z","source":"api"}"#.to_vec()
}

fn fat_event_json(noise_keys: usize) -> Vec<u8> {
    let mut b = ObjectBuilder::with_capacity(64 + noise_keys * 24)
        .field("id", &7u64)
        .field("created_at", "2026-07-22T00:00:00Z")
        .field("source", "api");
    for i in 0..noise_keys {
        let n = i as u64;
        b = b.field(&format!("noise_{i}"), &n);
    }
    // large string blob serde must still parse as a value when walking the object
    b = b.field("blob", &"x".repeat(256));
    b.finish()
}

fn dual_event_json(noise_keys: usize) -> Vec<u8> {
    let mut b = ObjectBuilder::with_capacity(96 + noise_keys * 24)
        .field("id", &1u64)
        .field("created_at", "t0")
        .field("source", "api")
        .field("env", "prod")
        .field("region", "us-east-1");
    for i in 0..noise_keys {
        b = b.field(&format!("k{i}"), &true);
    }
    b.finish()
}

fn main() {
    println!("jshift byte-level flatten vs serde #[serde(flatten)]\n");

    // ── Small object decode ─────────────────────────────────────────────────
    let small = small_event_json();
    let j = mean_ns(200_000, || {
        let e = Event::read_from(&small).unwrap();
        std::hint::black_box(e.id + e.meta.source.len() as u64);
    });
    let s = mean_ns(200_000, || {
        let e: SerEvent = serde_json::from_slice(&small).unwrap();
        std::hint::black_box(e.id + e.meta.source.len() as u64);
    });
    row("decode small Event (id+flatten meta)", j, s);

    // ── Fat object decode (noise keys) ──────────────────────────────────────
    for &n in &[16usize, 64, 256] {
        let fat = fat_event_json(n);
        let j = mean_ns(50_000, || {
            let e = Event::read_from(&fat).unwrap();
            std::hint::black_box(e.id + e.meta.source.len() as u64);
        });
        let s = mean_ns(50_000, || {
            let e: SerEvent = serde_json::from_slice(&fat).unwrap();
            std::hint::black_box(e.id + e.meta.source.len() as u64);
        });
        row(
            &format!("decode Event on fat obj (+{n} noise keys +256B blob)"),
            j,
            s,
        );
    }

    // ── Dual flatten ────────────────────────────────────────────────────────
    let dual = dual_event_json(64);
    let j = mean_ns(50_000, || {
        let e = DualEvent::read_from(&dual).unwrap();
        std::hint::black_box(e.id + e.tags.env.len() as u64);
    });
    let s = mean_ns(50_000, || {
        let e: SerDualEvent = serde_json::from_slice(&dual).unwrap();
        std::hint::black_box(e.id + e.tags.env.len() as u64);
    });
    row("decode DualEvent flatten×2 (+64 noise)", j, s);

    // ── Encode / schema emit ────────────────────────────────────────────────
    let event = Event {
        id: 7,
        meta: Meta {
            created_at: "2026-07-22T00:00:00Z".into(),
            source: "api".into(),
        },
    };
    let ser_event = SerEvent {
        id: 7,
        meta: SerMeta {
            created_at: "2026-07-22T00:00:00Z".into(),
            source: "api".into(),
        },
    };
    let j = mean_ns(200_000, || {
        let _ = event.to_schema_bytes().unwrap();
    });
    let s = mean_ns(200_000, || {
        let _ = serde_json::to_vec(&ser_event).unwrap();
    });
    row("encode Event (schema / to_vec)", j, s);

    let dual_v = DualEvent {
        id: 1,
        meta: Meta {
            created_at: "t0".into(),
            source: "api".into(),
        },
        tags: Tags {
            env: "prod".into(),
            region: "us-east-1".into(),
        },
    };
    let ser_dual = SerDualEvent {
        id: 1,
        meta: SerMeta {
            created_at: "t0".into(),
            source: "api".into(),
        },
        tags: SerTags {
            env: "prod".into(),
            region: "us-east-1".into(),
        },
    };
    let j = mean_ns(100_000, || {
        let _ = dual_v.to_schema_bytes().unwrap();
    });
    let s = mean_ns(100_000, || {
        let _ = serde_json::to_vec(&ser_dual).unwrap();
    });
    row("encode DualEvent (flatten×2)", j, s);

    // ── Open mutate one flattened field ─────────────────────────────────────
    let fat = fat_event_json(128);
    let j = mean_ns(20_000, || {
        let mut buf = fat.clone();
        let mut e = Event::read_from(&buf).unwrap();
        e.meta.source = "web".into();
        e.write_into(&mut buf).unwrap();
        std::hint::black_box(buf.len());
    });
    let s = mean_ns(20_000, || {
        let mut e: SerEvent = serde_json::from_slice(&fat).unwrap();
        e.meta.source = "web".into();
        let out = serde_json::to_vec(&e).unwrap();
        std::hint::black_box(out.len());
    });
    row("open mutate source on fat (+128 noise)", j, s);

    // ── Project thin card ───────────────────────────────────────────────────
    let fat = fat_event_json(128);
    let j = mean_ns(20_000, || {
        let _ = Event::project_json(&fat).unwrap();
    });
    let s = mean_ns(20_000, || {
        // serde has no project: full deserialize + re-serialize flattened struct
        let e: SerEvent = serde_json::from_slice(&fat).unwrap();
        let _ = serde_json::to_vec(&e).unwrap();
    });
    row("project thin Event card vs serde roundtrip", j, s);

    // ── Builder flatten_object micro ────────────────────────────────────────
    let child = br#"{"created_at":"t0","source":"api"}"#;
    let j = mean_ns(200_000, || {
        let b = ObjectBuilder::new()
            .field("id", &7u64)
            .flatten_object(child)
            .unwrap();
        std::hint::black_box(b.finish());
    });
    let s = mean_ns(200_000, || {
        let _ = serde_json::to_vec(&ser_event).unwrap();
    });
    row("ObjectBuilder.flatten_object vs serde to_vec", j, s);

    // ── Hand flatten free-fn vs derive ──────────────────────────────────────
    let small = small_event_json();
    let j_fn = mean_ns(200_000, || {
        let m = jshift::read_flattened::<Meta>(&small).unwrap();
        std::hint::black_box(m.source.len());
    });
    let j_der = mean_ns(200_000, || {
        let e = Event::read_from(&small).unwrap();
        std::hint::black_box(e.meta.source.len());
    });
    println!(
        "\n  {:<52}  free-fn {:>12}   derive {:>12}   free/derive {:>8}",
        "read_flattened Meta only vs full Event",
        fmt_time(j_fn),
        fmt_time(j_der),
        ratio(j_der, j_fn)
    );

    println!("\nNotes:");
    println!("  • On tiny objects serde flatten is already strong (full parse is cheap).");
    println!("  • jshift pulls ahead as noise grows: only named paths are scanned/decoded.");
    println!("  • Open mutate is the headline win — splice one field, keep the rest of the buffer.");
    println!("  • Schema emit uses raw member copy for flattened children (no re-escape).");
}