jshift 0.7.0

Schema-guided typed JSON on raw bytes: path get/mutate, open views, project — without a Value tree.
Documentation
//! Byte-level **flatten** (serde-style field spreading) without a `Value` tree.
//!
//! # Idea
//!
//! Serde’s `#[serde(flatten)]` lifts nested struct fields into the parent object.
//! jshift does the same on **raw buffers**:
//!
//! * **Read** — decode the child [`JsonView`] from the **same parent object bytes**
//!   (child paths are relative to the parent root; unknowns stay unread).
//! * **Write** — [`JsonView::write_into`] the child into the parent buffer
//!   (open upsert of the child’s named paths only).
//! * **Schema emit** — copy child object **members as raw spans** into an
//!   [`ObjectBuilder`] (no re-escape of unescaped keys, no re-encode of values).
//!
//! ```
//! # #[cfg(feature = "derive")]
//! # {
//! use jshift::JsonView;
//!
//! #[derive(Debug, PartialEq, JsonView)]
//! struct Meta {
//!     #[json(path = "created_at")]
//!     created_at: String,
//!     #[json(path = "source")]
//!     source: String,
//! }
//!
//! #[derive(Debug, PartialEq, JsonView)]
//! struct Event {
//!     #[json(path = "id")]
//!     id: u64,
//!     #[json(flatten)]
//!     meta: Meta,
//! }
//!
//! let raw = br#"{"id":7,"created_at":"t0","source":"api","noise":true}"#;
//! let e = Event::read_from(raw).unwrap();
//! assert_eq!(e.id, 7);
//! assert_eq!(e.meta.source, "api");
//! // schema emit is flat (no nested "meta" key):
//! let out = e.to_schema_bytes().unwrap();
//! assert!(out.windows(4).any(|w| w == b"\"id\""));
//! assert!(out.windows(8).any(|w| w == b"\"source\""));
//! assert!(!out.windows(6).any(|w| w == b"\"meta\""));
//! # }
//! ```
//!
//! # Multiple flattens & key collisions
//!
//! Several `#[json(flatten)]` fields are allowed. Each child only **reads its own
//! paths**. On write, later fields overwrite earlier ones for the same key
//! (declaration order). Prefer non-overlapping child schemas.
//!
//! # Not the same as nesting
//!
//! | Attribute | Wire shape |
//! | --- | --- |
//! | `#[json(path = "meta")]` + nested type | `{"meta":{...}}` (not auto today; path to object) |
//! | `#[json(flatten)]` | `{"created_at":...,"source":...}` at parent |

use crate::error::Error;
use crate::scan::{find_string_end, skip_value, skip_whitespace};
use crate::typed_doc::ObjectEntries;
use crate::view::JsonView;

/// Decode `T` from the parent object buffer (paths relative to that root).
///
/// Zero extra copy: this is [`JsonView::read_from`] with clear flatten intent.
#[inline]
pub fn read_flattened<T: JsonView>(parent_object: &[u8]) -> Result<T, Error> {
    T::read_from(parent_object)
}

/// Decode `Option<T>`: `None` when a required path is missing (`PathNotFound`).
///
/// Other errors (type mismatch, syntax) still fail. Use when a flattened block
/// may be entirely absent.
#[inline]
pub fn read_flattened_opt<T: JsonView>(parent_object: &[u8]) -> Result<Option<T>, Error> {
    match T::read_from(parent_object) {
        Ok(v) => Ok(Some(v)),
        Err(Error::PathNotFound) => Ok(None),
        Err(e) => Err(e),
    }
}

/// Open-upsert a flattened child into `parent` (preserves unknown parent keys).
#[inline]
pub fn write_flattened<T: JsonView>(parent: &mut Vec<u8>, child: &T) -> Result<(), Error> {
    child.write_into(parent)
}

/// Open-upsert when `Some`; no-op when `None` (does not delete child keys).
#[inline]
pub fn write_flattened_opt<T: JsonView>(
    parent: &mut Vec<u8>,
    child: Option<&T>,
) -> Result<(), Error> {
    if let Some(c) = child {
        write_flattened(parent, c)?;
    }
    Ok(())
}

/// Spread every member of `child_object` into `parent` (root object) by
/// shallow upsert of each key.
///
/// Prefer [`write_flattened`] when the child is a typed view (only named paths).
/// This helper is for raw object JSON (e.g. dynamic pockets).
pub fn merge_flatten_object(parent: &mut Vec<u8>, child_object: &[u8]) -> Result<(), Error> {
    crate::mutate::merge_object_shallow(parent, &[], child_object)
}

/// Append all members of a JSON **object** into an open object buffer mid-build.
///
/// Used by [`crate::ObjectBuilder::flatten_object`]. Copies **on-wire** key
/// bytes (already escaped) and value spans — no string re-escape, no value
/// re-encode. That is the “smart byte flatten” for schema emit.
///
/// `dest` must already contain a leading `{` and any previous members; this
/// writes `,` separators as needed via `first`.
///
/// Returns the updated `first` flag (`false` after any member written).
pub fn append_object_members_raw(
    dest: &mut Vec<u8>,
    first: &mut bool,
    child_object: &[u8],
) -> Result<(), Error> {
    let start = skip_whitespace(child_object, 0);
    if start >= child_object.len() || child_object[start] != b'{' {
        return Err(Error::TypeMismatch {
            expected: "object (flatten source)",
            found: "non-object",
        });
    }
    let end = skip_value(child_object, start)?;
    let mut pos = skip_whitespace(child_object, start + 1);
    while pos < end {
        pos = skip_whitespace(child_object, pos);
        if pos >= end || child_object[pos] == b'}' {
            break;
        }
        if child_object[pos] != b'"' {
            return Err(Error::InvalidJsonSyntax {
                pos,
                msg: "Expected object key in flatten source",
            });
        }
        let key_open = pos;
        let key_start = pos + 1;
        let key_end = find_string_end(child_object, key_start)?;
        pos = skip_whitespace(child_object, key_end + 1);
        if pos >= end || child_object[pos] != b':' {
            return Err(Error::InvalidJsonSyntax {
                pos,
                msg: "Expected colon after key in flatten source",
            });
        }
        pos = skip_whitespace(child_object, pos + 1);
        let vs = pos;
        let ve = skip_value(child_object, vs)?;
        // Copy `"key":value` with on-wire key (including escapes).
        if !*first {
            dest.push(b',');
        }
        *first = false;
        dest.extend_from_slice(&child_object[key_open..=key_end]); // "key"
        dest.push(b':');
        dest.extend_from_slice(&child_object[vs..ve]);
        pos = skip_whitespace(child_object, ve);
        if pos < end && child_object[pos] == b',' {
            pos += 1;
        }
    }
    Ok(())
}

/// Collect keep-list paths for project plans: own paths + each flattened
/// child's `FIELD_PATHS` (derive convention).
///
/// `child_path_lists` is typically `&[Meta::FIELD_PATHS, Tags::FIELD_PATHS]`.
pub fn merge_field_paths<'a>(
    own: &[&'a str],
    child_path_lists: &[&[&'a str]],
) -> Vec<&'a str> {
    let mut out = Vec::with_capacity(
        own.len()
            + child_path_lists
                .iter()
                .map(|c| c.len())
                .sum::<usize>(),
    );
    out.extend_from_slice(own);
    for c in child_path_lists {
        out.extend_from_slice(c);
    }
    out
}

/// Build a [`crate::ProjectPlan`] from own paths plus flattened children’s
/// `FIELD_PATHS` slices.
pub fn project_plan_with_flatten(
    own_paths: &[&str],
    child_field_paths: &[&[&str]],
) -> Result<crate::ProjectPlan, Error> {
    let merged = merge_field_paths(own_paths, child_field_paths);
    crate::ProjectPlan::from_paths(&merged)
}

/// Count members in an object (for tests / diagnostics).
pub fn object_member_count(object_json: &[u8]) -> Result<usize, Error> {
    let mut n = 0usize;
    for e in ObjectEntries::open(object_json)? {
        let _ = e?;
        n += 1;
    }
    Ok(n)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{
        find_value, parse_path, upsert_at_path, FromJsonSlice, ObjectBuilder, ProjectPlan,
        ToJsonBytes,
    };

    struct Meta {
        source: String,
    }

    impl JsonView for Meta {
        fn read_from(json: &[u8]) -> Result<Self, Error> {
            let s = find_value(json, &parse_path("source"))?;
            Ok(Self {
                source: String::from_json_slice(s).unwrap(),
            })
        }
        fn write_into(&self, json: &mut Vec<u8>) -> Result<(), Error> {
            upsert_at_path(json, &parse_path("source"), &self.source.to_json_bytes())
        }
        fn project_plan() -> ProjectPlan {
            ProjectPlan::from_paths(&["source"]).unwrap()
        }
    }

    impl Meta {
        const FIELD_PATHS: &'static [&'static str] = &["source"];
    }

    #[test]
    fn read_write_flattened() {
        let raw = br#"{"id":1,"source":"api","x":true}"#;
        let m = read_flattened::<Meta>(raw).unwrap();
        assert_eq!(m.source, "api");
        let mut buf = raw.to_vec();
        write_flattened(
            &mut buf,
            &Meta {
                source: "web".into(),
            },
        )
        .unwrap();
        assert_eq!(find_value(&buf, &parse_path("source")).unwrap(), br#""web""#);
        assert!(find_value(&buf, &parse_path("x")).is_ok());
    }

    #[test]
    fn append_object_members_preserves_raw_spans() {
        let mut dest = vec![b'{'];
        dest.extend_from_slice(br#""id":1"#);
        let mut first = false;
        append_object_members_raw(&mut dest, &mut first, br#"{"source":"api","n":2}"#).unwrap();
        dest.push(b'}');
        assert_eq!(dest, br#"{"id":1,"source":"api","n":2}"#);
    }

    #[test]
    fn object_builder_flatten_object() {
        let b = ObjectBuilder::new()
            .field("id", &7u64)
            .flatten_object(br#"{"source":"api"}"#)
            .unwrap();
        assert_eq!(b.finish(), br#"{"id":7,"source":"api"}"#);
    }

    #[test]
    fn project_plan_merges_child_paths() {
        let plan = project_plan_with_flatten(&["id"], &[Meta::FIELD_PATHS]).unwrap();
        let out = crate::project(br#"{"id":1,"source":"a","noise":9}"#, &plan).unwrap();
        assert!(out.windows(4).any(|w| w == b"\"id\""));
        assert!(out.windows(8).any(|w| w == b"\"source\""));
        assert!(!out.windows(7).any(|w| w == b"\"noise\""));
    }

    #[test]
    fn optional_flatten_absent_paths() {
        assert!(super::read_flattened_opt::<Meta>(br#"{"other":1}"#)
            .unwrap()
            .is_none());
        assert!(super::read_flattened_opt::<Meta>(br#"{"source":"x"}"#)
            .unwrap()
            .is_some());
    }
}