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
//! 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`]).
/// 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.