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}