1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
//! Schema projections over JSON bytes (prost-inspired trait surface).
//!
//! A [`JsonView`] is a **partial** Rust type: only the paths you name are read or
//! written. Everything else in the buffer is ignored on read and preserved on write
//! (open-document / "unknown fields" semantics).
//!
//! This is **not** a full JSON DOM. Together with [`crate::TypedDoc`], it is the
//! protocol surface for "this Rust type talks to JSON bytes," enabling generic
//! pipelines:
//!
//! ```
//! use jshift::{
//! find_value, parse_path, upsert_at_path, FromJsonSlice, JsonView, ToJsonBytes, Error,
//! };
//!
//! struct IdOnly {
//! id: u64,
//! }
//!
//! impl JsonView for IdOnly {
//! fn read_from(json: &[u8]) -> Result<Self, Error> {
//! let slice = find_value(json, &parse_path("id"))?;
//! let id = u64::from_json_slice(slice).ok_or(Error::TypeMismatch {
//! expected: "u64",
//! found: "invalid format",
//! })?;
//! Ok(Self { id })
//! }
//!
//! fn write_into(&self, json: &mut Vec<u8>) -> Result<(), Error> {
//! upsert_at_path(json, &parse_path("id"), &self.id.to_json_bytes())
//! }
//! }
//!
//! fn ingest<T: JsonView>(buf: &[u8]) -> Result<T, Error> {
//! T::read_from(buf)
//! }
//!
//! let json = br#"{"id":1,"extra":true}"#;
//! let v: IdOnly = ingest(json).unwrap();
//! assert_eq!(v.id, 1);
//! ```
//!
//! With the `derive` feature (default), prefer `#[derive(JsonView)]` /
//! `JsonMutatorSchema` instead of hand-written impls.
use crateError;
use crateIndexedDocument;
use crate;
/// A Rust type that is a **projection** of JSON bytes along named paths.
///
/// # Open documents
///
/// Fields (and whole subtrees) you do not name are:
///
/// * **unread** on [`read_from`](Self::read_from): never validated or allocated;
/// * **preserved byte-for-byte** on [`write_into`](Self::write_into): only named
/// paths are upserted.
///
/// That is intentional and first-class: use partial "view structs" the way prost
/// users use messages, not 1:1 mirrors of every JSON key.
///
/// # Indexing
///
/// Prefer [`read_from_indexed`](Self::read_from_indexed) or
/// [`read_from_doc`](Self::read_from_doc) when paths cross large arrays and you have
/// already built (or can build) schema-guided side-tables.
///
/// Indexes bind to a fixed byte snapshot. After in-place mutate/delete, rebuild or
/// drop the index (see [`IndexedDocument`]).
/// Build schema-only bytes from any [`JsonView`] (roadmap build-from-schema).
/// Stream each element of the array at `array_path` as `T: JsonView`.
///
/// Single-pass, no intermediate `Vec<T>`. Prefer over full deserialize when
/// processing rows one at a time.
///
/// ```
/// use jshift::{project_view_each, FromJsonSlice, JsonView, find_value, parse_path};
///
/// struct Id { n: u64 }
/// impl JsonView for Id {
/// fn read_from(json: &[u8]) -> Result<Self, jshift::Error> {
/// let s = find_value(json, &parse_path("id"))?;
/// Ok(Self { n: u64::from_json_slice(s).unwrap() })
/// }
/// fn write_into(&self, _: &mut Vec<u8>) -> Result<(), jshift::Error> { Ok(()) }
/// }
///
/// let json = br#"{"items":[{"id":1},{"id":2}]}"#;
/// let mut sum = 0u64;
/// project_view_each::<Id, _>(json, "items", |c| {
/// sum += c.n;
/// Ok(())
/// }).unwrap();
/// assert_eq!(sum, 3);
/// ```
/// Collect array elements as `Vec<T: JsonView>` (explicit owned collect).
/// Shared helper: read any [`JsonView`] from bytes.
/// Happy-path alias: bytes → `T: JsonView` (roadmap adoption surface).
///
/// Same as [`read_view`] / [`JsonView::read_from`]. Prefer this name in
/// migration guides (`from_jshift_bytes` vs `serde_json::from_slice`).
/// Project `json` down to `T`'s keep-list, then decode as `T`.
///
/// Typed project → T (roadmap query/transform): thin bytes intermediate, no
/// `Value` tree. Useful when the source is huge but the view is sparse.
///
/// ```
/// # #[cfg(feature = "derive")] {
/// use jshift::{project_as_view, JsonView};
///
/// #[derive(JsonView)]
/// struct Card {
/// #[json(path = "id")]
/// id: u64,
/// }
///
/// let json = br#"{"id":7,"blob":[1,2,3],"title":"x"}"#;
/// let card: Card = project_as_view(json).unwrap();
/// assert_eq!(card.id, 7);
/// # }
/// ```
/// Shared helper: write any [`JsonView`] into a buffer.