Skip to main content

jshift/
view.rs

1//! Schema projections over JSON bytes (prost-inspired trait surface).
2//!
3//! A [`JsonView`] is a **partial** Rust type: only the paths you name are read or
4//! written. Everything else in the buffer is ignored on read and preserved on write
5//! (open-document / "unknown fields" semantics).
6//!
7//! This is **not** a full JSON DOM. Together with [`crate::TypedDoc`], it is the
8//! protocol surface for "this Rust type talks to JSON bytes," enabling generic
9//! pipelines:
10//!
11//! ```
12//! use jshift::{
13//!     find_value, parse_path, upsert_at_path, FromJsonSlice, JsonView, ToJsonBytes, Error,
14//! };
15//!
16//! struct IdOnly {
17//!     id: u64,
18//! }
19//!
20//! impl JsonView for IdOnly {
21//!     fn read_from(json: &[u8]) -> Result<Self, Error> {
22//!         let slice = find_value(json, &parse_path("id"))?;
23//!         let id = u64::from_json_slice(slice).ok_or(Error::TypeMismatch {
24//!             expected: "u64",
25//!             found: "invalid format",
26//!         })?;
27//!         Ok(Self { id })
28//!     }
29//!
30//!     fn write_into(&self, json: &mut Vec<u8>) -> Result<(), Error> {
31//!         upsert_at_path(json, &parse_path("id"), &self.id.to_json_bytes())
32//!     }
33//! }
34//!
35//! fn ingest<T: JsonView>(buf: &[u8]) -> Result<T, Error> {
36//!     T::read_from(buf)
37//! }
38//!
39//! let json = br#"{"id":1,"extra":true}"#;
40//! let v: IdOnly = ingest(json).unwrap();
41//! assert_eq!(v.id, 1);
42//! ```
43//!
44//! With the `derive` feature (default), prefer `#[derive(JsonView)]` /
45//! `JsonMutatorSchema` instead of hand-written impls.
46
47use crate::error::Error;
48use crate::index::IndexedDocument;
49use crate::project::{project, ProjectPlan};
50
51/// A Rust type that is a **projection** of JSON bytes along named paths.
52///
53/// # Open documents
54///
55/// Fields (and whole subtrees) you do not name are:
56///
57/// * **unread** on [`read_from`](Self::read_from): never validated or allocated;
58/// * **preserved byte-for-byte** on [`write_into`](Self::write_into): only named
59///   paths are upserted.
60///
61/// That is intentional and first-class: use partial "view structs" the way prost
62/// users use messages, not 1:1 mirrors of every JSON key.
63///
64/// # Nested fields (serde-like)
65///
66/// With `#[derive(JsonView)]`, a field whose type is **not** a known scalar /
67/// `HashMap` / `BTreeMap` is treated as a **nested** [`JsonView`] at `path`
68/// (wire: `"meta": { … }`), matching serde’s default nested-struct behavior.
69///
70/// * The nested type **must** implement [`JsonView`] (usually via derive) —
71///   enforced at **compile time**.
72/// * Custom `FromJsonSlice` newtypes that are not in the built-in scalar list
73///   need `#[json(from_slice)]` so the derive does not treat them as nested views.
74/// * Spread into the parent object: `#[json(flatten)]` (not nested).
75///
76/// # Indexing
77///
78/// Prefer [`read_from_indexed`](Self::read_from_indexed) or
79/// [`read_from_doc`](Self::read_from_doc) when paths cross large arrays and you have
80/// already built (or can build) schema-guided side-tables.
81///
82/// Indexes bind to a fixed byte snapshot. After in-place mutate/delete, rebuild or
83/// drop the index (see [`IndexedDocument`]).
84#[diagnostic::on_unimplemented(
85    message = "`{Self}` cannot be used as a nested jshift JSON field",
86    label = "`JsonView` is not implemented for `{Self}`",
87    note = "serde users: nested structs need `#[derive(JsonView)]` on the nested type (like `Deserialize`). \
88            Wire shape is `{{\"field\": {{...}} }}`. For flatten into the parent object use `#[json(flatten)]`. \
89            For a custom scalar newtype implementing `FromJsonSlice`, mark the field `#[json(from_slice)]`. \
90            Built-in scalars (`String`, integers, `bool`, …) and `HashMap`/`BTreeMap<String, V>` are not nested views."
91)]
92pub trait JsonView: Sized {
93    /// Read this projection from raw JSON bytes (linear path scans).
94    fn read_from(json: &[u8]) -> Result<Self, Error>;
95
96    /// Read using a schema-guided index plan (array side-tables + optional Stage-1).
97    ///
98    /// Default implementation falls back to [`read_from`](Self::read_from). Derive
99    /// implementations build a minimal index from path analysis.
100    fn read_from_indexed(json: &[u8]) -> Result<Self, Error> {
101        Self::read_from(json)
102    }
103
104    /// Read using a pre-built [`IndexedDocument`] (reuses index across views/tasks).
105    ///
106    /// Default: linear scan of `doc.as_bytes()`.
107    fn read_from_doc(doc: &IndexedDocument<'_>) -> Result<Self, Error> {
108        Self::read_from(doc.as_bytes())
109    }
110
111    /// Upsert this projection's fields into `json`.
112    ///
113    /// Unmentioned paths in the buffer are left alone. Missing parents for named
114    /// paths may be created (see [`crate::upsert_at_path`]).
115    fn write_into(&self, json: &mut Vec<u8>) -> Result<(), Error>;
116
117    /// Schema keep-list as a [`ProjectPlan`] (default: empty object selection).
118    ///
119    /// Derive implementations build this from `FIELD_PATHS` (including `[]` wildcards
120    /// when present in path attributes).
121    fn project_plan() -> ProjectPlan {
122        ProjectPlan::from_paths(&[]).unwrap_or_else(|_| ProjectPlan::identity())
123    }
124
125    /// Project `json` down to this view's keep-list (new buffer).
126    fn project_bytes(json: &[u8]) -> Result<Vec<u8>, Error> {
127        project(json, &Self::project_plan())
128    }
129
130    /// Build a **new** document containing only this schema’s fields (0.6).
131    ///
132    /// Default implementation:
133    /// 1. open-upsert onto a fresh `{}` via [`write_into`](Self::write_into);
134    /// 2. [`project_bytes`](Self::project_bytes) to strip accidental parents /
135    ///    keep only the schema plan.
136    ///
137    /// That is two passes but correct for nested paths. Derive can override with
138    /// a single-pass field-order writer for flat schemas. Prefer this when you
139    /// need a closed card without `serde_json::Value`.
140    fn to_schema_bytes(&self) -> Result<Vec<u8>, Error> {
141        // Small seed; write_into grows via upsert. Avoid double-zero of large bufs.
142        let mut buf = Vec::with_capacity(64);
143        buf.extend_from_slice(br#"{"#);
144        buf.push(b'}');
145        self.write_into(&mut buf)?;
146        Self::project_bytes(&buf)
147    }
148
149    /// [`to_schema_bytes`](Self::to_schema_bytes) into a [`crate::TypedDoc`].
150    fn to_schema_doc(&self) -> Result<crate::typed_doc::TypedDoc, Error> {
151        Ok(crate::typed_doc::TypedDoc::from_vec(self.to_schema_bytes()?))
152    }
153}
154
155/// Build schema-only bytes from any [`JsonView`] (roadmap build-from-schema).
156#[inline]
157pub fn build_schema_bytes<T: JsonView>(view: &T) -> Result<Vec<u8>, Error> {
158    view.to_schema_bytes()
159}
160
161/// Stream each element of the array at `array_path` as `T: JsonView`.
162///
163/// Single-pass, no intermediate `Vec<T>`. Prefer over full deserialize when
164/// processing rows one at a time.
165///
166/// ```
167/// use jshift::{project_view_each, FromJsonSlice, JsonView, find_value, parse_path};
168///
169/// struct Id { n: u64 }
170/// impl JsonView for Id {
171///     fn read_from(json: &[u8]) -> Result<Self, jshift::Error> {
172///         let s = find_value(json, &parse_path("id"))?;
173///         Ok(Self { n: u64::from_json_slice(s).unwrap() })
174///     }
175///     fn write_into(&self, _: &mut Vec<u8>) -> Result<(), jshift::Error> { Ok(()) }
176/// }
177///
178/// let json = br#"{"items":[{"id":1},{"id":2}]}"#;
179/// let mut sum = 0u64;
180/// project_view_each::<Id, _>(json, "items", |c| {
181///     sum += c.n;
182///     Ok(())
183/// }).unwrap();
184/// assert_eq!(sum, 3);
185/// ```
186pub fn project_view_each<T, F>(json: &[u8], array_path: &str, mut f: F) -> Result<(), Error>
187where
188    T: JsonView,
189    F: FnMut(T) -> Result<(), Error>,
190{
191    use crate::view_list::ViewList;
192    let doc = crate::typed_doc::TypedDocRef::from_slice(json);
193    let list = ViewList::<T>::from_doc(&doc, array_path)?;
194    list.each(|v| f(v))
195}
196
197/// Collect array elements as `Vec<T: JsonView>` (explicit owned collect).
198#[inline]
199pub fn project_view_collect<T: JsonView>(json: &[u8], array_path: &str) -> Result<Vec<T>, Error> {
200    let mut out = Vec::new();
201    project_view_each(json, array_path, |v| {
202        out.push(v);
203        Ok(())
204    })?;
205    Ok(out)
206}
207
208/// Shared helper: read any [`JsonView`] from bytes.
209#[inline]
210pub fn read_view<T: JsonView>(json: &[u8]) -> Result<T, Error> {
211    T::read_from(json)
212}
213
214/// Read nested `T: JsonView` at a path (child value becomes the view’s root).
215///
216/// Wire shape is the serde default nested object: `"meta": { … }`.
217/// Used by `#[json(path = "meta")] meta: Meta` where `Meta: JsonView`.
218///
219/// If `T` does not implement [`JsonView`], the compiler error points here
220/// (see the trait’s `on_unimplemented` note).
221///
222/// # Errors
223///
224/// Propagates path/scan errors and `T::read_from` failures.
225#[inline]
226pub fn read_view_at<T: JsonView>(
227    json: &[u8],
228    path: &[crate::path::PathSegment],
229) -> Result<T, Error> {
230    let slice = crate::scan::find_value(json, path)?;
231    T::read_from(slice)
232}
233
234/// Optional nested view: missing path or JSON `null` → [`None`].
235///
236/// Other type/syntax errors still fail (same spirit as `Option` + path scalars).
237pub fn read_view_at_opt<T: JsonView>(
238    json: &[u8],
239    path: &[crate::path::PathSegment],
240) -> Result<Option<T>, Error> {
241    match crate::scan::find_value(json, path) {
242        Ok(slice) => {
243            if is_json_null(slice) {
244                return Ok(None);
245            }
246            Ok(Some(T::read_from(slice)?))
247        }
248        Err(Error::PathNotFound) => Ok(None),
249        Err(e) => Err(e),
250    }
251}
252
253/// **Open** nested write: apply `view.write_into` on the child value at `path`.
254///
255/// Unknown keys **inside** the existing child object are preserved (prost-like).
256/// This is what `#[derive(JsonView)]` uses for parent `write_into`.
257///
258/// Steps:
259/// 1. Locate the value at `path` (create `{}` if missing).
260/// 2. If the value is not an object, replace it with `{}`.
261/// 3. Copy that span into a temporary buffer, run [`JsonView::write_into`],
262/// 4. Splice the result back into the parent document.
263///
264/// # Closed card instead
265///
266/// Use [`write_view_at_closed`] / [`JsonView::to_schema_bytes`] when you want to
267/// **replace** the child with only schema fields (e.g. building a thin response).
268///
269/// # Errors
270///
271/// Path/upsert failures, or errors from `T::write_into`.
272pub fn write_view_at<T: JsonView>(
273    json: &mut Vec<u8>,
274    path: &[crate::path::PathSegment],
275    view: &T,
276) -> Result<(), Error> {
277    write_view_at_open(json, path, view)
278}
279
280/// Open nested write when `Some`; no-op when `None` (does **not** delete the path).
281#[inline]
282pub fn write_view_at_opt<T: JsonView>(
283    json: &mut Vec<u8>,
284    path: &[crate::path::PathSegment],
285    view: Option<&T>,
286) -> Result<(), Error> {
287    if let Some(v) = view {
288        write_view_at_open(json, path, v)?;
289    }
290    Ok(())
291}
292
293/// Open nested write (same as [`write_view_at`]; explicit name for call sites).
294pub fn write_view_at_open<T: JsonView>(
295    json: &mut Vec<u8>,
296    path: &[crate::path::PathSegment],
297    view: &T,
298) -> Result<(), Error> {
299    use crate::mutate::upsert_at_path;
300    use crate::scan::{find_value_offsets, skip_whitespace};
301
302    // Ensure a value exists at path.
303    if find_value_offsets(json, path).is_err() {
304        upsert_at_path(json, path, b"{}")?;
305    }
306
307    let (start, end) = find_value_offsets(json, path)?;
308    // Non-object (null, array, primitive) → start a fresh open object.
309    let s = skip_whitespace(&json[start..end], 0);
310    let mut nested = if s < (end - start) && json[start + s] == b'{' {
311        json[start..end].to_vec()
312    } else {
313        b"{}".to_vec()
314    };
315
316    view.write_into(&mut nested)?;
317    // Splice child bytes back (preserves parent keys outside `path`).
318    json.splice(start..end, nested);
319    Ok(())
320}
321
322/// **Closed** nested write: replace the value at `path` with `view.to_schema_bytes()`.
323///
324/// Unknown keys inside a previous child object are **dropped**. Prefer this for
325/// thin cards / API responses; prefer [`write_view_at`] for open documents.
326#[inline]
327pub fn write_view_at_closed<T: JsonView>(
328    json: &mut Vec<u8>,
329    path: &[crate::path::PathSegment],
330    view: &T,
331) -> Result<(), Error> {
332    let bytes = view.to_schema_bytes()?;
333    crate::mutate::upsert_at_path(json, path, &bytes)
334}
335
336/// Closed nested write when `Some`; no-op when `None`.
337#[inline]
338pub fn write_view_at_closed_opt<T: JsonView>(
339    json: &mut Vec<u8>,
340    path: &[crate::path::PathSegment],
341    view: Option<&T>,
342) -> Result<(), Error> {
343    if let Some(v) = view {
344        write_view_at_closed(json, path, v)?;
345    }
346    Ok(())
347}
348
349#[inline]
350fn is_json_null(slice: &[u8]) -> bool {
351    use crate::scan::skip_whitespace;
352    let s = skip_whitespace(slice, 0);
353    let mut e = slice.len();
354    while e > s && matches!(slice[e - 1], b' ' | b'\t' | b'\n' | b'\r') {
355        e -= 1;
356    }
357    &slice[s..e] == b"null"
358}
359
360/// Happy-path alias: bytes → `T: JsonView` (roadmap adoption surface).
361///
362/// Same as [`read_view`] / [`JsonView::read_from`]. Prefer this name in
363/// migration guides (`from_jshift_bytes` vs `serde_json::from_slice`).
364#[inline]
365pub fn from_jshift_bytes<T: JsonView>(json: &[u8]) -> Result<T, Error> {
366    T::read_from(json)
367}
368
369/// Project `json` down to `T`'s keep-list, then decode as `T`.
370///
371/// Typed project → T (roadmap query/transform): thin bytes intermediate, no
372/// `Value` tree. Useful when the source is huge but the view is sparse.
373///
374/// ```
375/// # #[cfg(feature = "derive")] {
376/// use jshift::{project_as_view, JsonView};
377///
378/// #[derive(JsonView)]
379/// struct Card {
380///     #[json(path = "id")]
381///     id: u64,
382/// }
383///
384/// let json = br#"{"id":7,"blob":[1,2,3],"title":"x"}"#;
385/// let card: Card = project_as_view(json).unwrap();
386/// assert_eq!(card.id, 7);
387/// # }
388/// ```
389#[inline]
390pub fn project_as_view<T: JsonView>(json: &[u8]) -> Result<T, Error> {
391    let thin = T::project_bytes(json)?;
392    T::read_from(&thin)
393}
394
395/// Shared helper: write any [`JsonView`] into a buffer.
396#[inline]
397pub fn write_view<T: JsonView>(view: &T, json: &mut Vec<u8>) -> Result<(), Error> {
398    view.write_into(json)
399}