icydb_core/db/response/
mod.rs

1//! Module: response
2//! Responsibility: materialized query/write response payload contracts.
3//! Does not own: execution routing, planning policy, or cursor token protocol.
4//! Boundary: Tier-2 db API DTO surface returned by session execution.
5//! Architecture: `Response<R>` is transport-only and row-shape-agnostic.
6//! Query semantics (for example cardinality checks) must live in query/session
7//! extension traits rather than inherent response DTO methods.
8
9mod grouped;
10mod paged;
11mod private;
12
13use crate::{
14    db::data::{DataRow, PersistedRow, decode_data_rows_into_entity_response},
15    prelude::*,
16    traits::EntityValue,
17    types::Id,
18    value::Value,
19};
20use thiserror::Error as ThisError;
21
22pub use grouped::{GroupedRow, PagedGroupedExecution, PagedGroupedExecutionWithTrace};
23pub use paged::{PagedLoadExecution, PagedLoadExecutionWithTrace};
24
25///
26/// ResponseRow
27///
28/// Marker trait for row-shape DTOs that are valid payloads for `Response<R>`.
29/// This trait is sealed to keep row-shape admission local to the response layer.
30///
31
32pub trait ResponseRow: private::Sealed {}
33
34impl ResponseRow for GroupedRow {}
35
36impl private::Sealed for GroupedRow {}
37
38///
39/// Row
40///
41/// Materialized entity row with explicit identity and payload accessors.
42///
43
44#[derive(Clone, Debug, Eq, PartialEq)]
45pub struct Row<E: EntityKind> {
46    id: Id<E>,
47    entity: E,
48}
49
50impl<E: EntityKind> Row<E> {
51    /// Construct one row from identity and entity payload.
52    #[must_use]
53    pub const fn new(id: Id<E>, entity: E) -> Self {
54        Self { id, entity }
55    }
56
57    /// Borrow this row's identity.
58    #[must_use]
59    pub const fn id(&self) -> Id<E> {
60        self.id
61    }
62
63    /// Consume and return this row's entity payload.
64    #[must_use]
65    pub fn entity(self) -> E {
66        self.entity
67    }
68
69    /// Borrow this row's entity payload.
70    #[must_use]
71    pub const fn entity_ref(&self) -> &E {
72        &self.entity
73    }
74
75    /// Consume and return `(id, entity)` parts.
76    #[must_use]
77    pub fn into_parts(self) -> (Id<E>, E) {
78        (self.id, self.entity)
79    }
80}
81
82impl<E: EntityKind> From<(Id<E>, E)> for Row<E> {
83    fn from(value: (Id<E>, E)) -> Self {
84        Self::new(value.0, value.1)
85    }
86}
87
88impl<E: EntityKind> private::Sealed for Row<E> {}
89
90impl<E: EntityKind> ResponseRow for Row<E> {}
91
92///
93/// ProjectedRow
94///
95/// One scalar projection output row emitted in planner declaration order.
96/// `values` carries evaluated expression outputs for this row.
97///
98
99#[derive(Clone, Debug, Eq, PartialEq)]
100pub struct ProjectedRow<E: EntityKind> {
101    id: Id<E>,
102    values: Vec<Value>,
103}
104
105impl<E: EntityKind> ProjectedRow<E> {
106    /// Construct one projected scalar row.
107    #[must_use]
108    pub const fn new(id: Id<E>, values: Vec<Value>) -> Self {
109        Self { id, values }
110    }
111
112    /// Borrow the source row identifier.
113    #[must_use]
114    pub const fn id(&self) -> Id<E> {
115        self.id
116    }
117
118    /// Borrow projected scalar values in declaration order.
119    #[must_use]
120    pub const fn values(&self) -> &[Value] {
121        self.values.as_slice()
122    }
123
124    /// Consume and return `(id, projected_values)`.
125    #[must_use]
126    pub fn into_parts(self) -> (Id<E>, Vec<Value>) {
127        (self.id, self.values)
128    }
129}
130
131impl<E: EntityKind> private::Sealed for ProjectedRow<E> {}
132
133impl<E: EntityKind> ResponseRow for ProjectedRow<E> {}
134
135///
136/// ResponseError
137///
138
139#[derive(Debug, ThisError)]
140pub enum ResponseError {
141    #[error("expected exactly one row, found 0 (entity {entity})")]
142    NotFound { entity: &'static str },
143
144    #[error("expected exactly one row, found {count} (entity {entity})")]
145    NotUnique { entity: &'static str, count: u32 },
146}
147
148impl ResponseError {
149    /// Construct one response not-found cardinality error.
150    #[must_use]
151    pub const fn not_found(entity: &'static str) -> Self {
152        Self::NotFound { entity }
153    }
154
155    /// Construct one response not-unique cardinality error.
156    #[must_use]
157    pub const fn not_unique(entity: &'static str, count: u32) -> Self {
158        Self::NotUnique { entity, count }
159    }
160}
161
162///
163/// Response
164///
165/// Generic response transport container for one row shape `R`.
166///
167
168#[derive(Debug)]
169pub struct Response<R: ResponseRow>(Vec<R>);
170
171///
172/// EntityResponse
173///
174/// Entity-row response transport alias.
175///
176
177pub type EntityResponse<E> = Response<Row<E>>;
178
179///
180/// ProjectionResponse
181///
182/// Scalar projection response transport alias.
183///
184
185pub type ProjectionResponse<E> = Response<ProjectedRow<E>>;
186
187impl<R: ResponseRow> Response<R> {
188    /// Construct one response from ordered rows.
189    #[must_use]
190    pub const fn new(rows: Vec<R>) -> Self {
191        Self(rows)
192    }
193
194    /// Construct one response from rows convertible into `R`.
195    #[must_use]
196    pub fn from_rows<T>(rows: Vec<T>) -> Self
197    where
198        T: Into<R>,
199    {
200        Self(rows.into_iter().map(Into::into).collect())
201    }
202
203    /// Return the number of rows.
204    #[must_use]
205    pub const fn len(&self) -> usize {
206        self.0.len()
207    }
208
209    /// Return the number of rows as a u32 API contract count.
210    #[must_use]
211    #[expect(clippy::cast_possible_truncation)]
212    pub const fn count(&self) -> u32 {
213        self.0.len() as u32
214    }
215
216    /// Return whether this response has no rows.
217    #[must_use]
218    pub const fn is_empty(&self) -> bool {
219        self.0.is_empty()
220    }
221
222    /// Consume and return all rows in response order.
223    #[must_use]
224    pub fn rows(self) -> Vec<R> {
225        self.0
226    }
227
228    /// Borrow an iterator over rows in response order.
229    pub fn iter(&self) -> std::slice::Iter<'_, R> {
230        self.0.iter()
231    }
232}
233
234impl<R: ResponseRow> AsRef<[R]> for Response<R> {
235    fn as_ref(&self) -> &[R] {
236        self.0.as_slice()
237    }
238}
239
240impl<R: ResponseRow> std::ops::Deref for Response<R> {
241    type Target = [R];
242
243    fn deref(&self) -> &Self::Target {
244        self.0.as_slice()
245    }
246}
247
248impl<E: EntityKind> Response<Row<E>> {
249    /// Decode ordered persisted data rows into one typed entity response.
250    #[inline(never)]
251    pub(in crate::db) fn from_data_rows(
252        rows: Vec<DataRow>,
253    ) -> Result<Self, crate::error::InternalError>
254    where
255        E: PersistedRow + EntityValue,
256    {
257        decode_data_rows_into_entity_response::<E>(rows)
258    }
259
260    /// Return the first row identifier, if present.
261    #[must_use]
262    pub fn id(&self) -> Option<Id<E>> {
263        self.0.first().map(Row::id)
264    }
265
266    /// Consume and return all entities in response order.
267    #[must_use]
268    pub fn entities(self) -> Vec<E> {
269        self.0.into_iter().map(Row::entity).collect()
270    }
271
272    /// Borrow an iterator over row identifiers in response order.
273    pub fn ids(&self) -> impl Iterator<Item = Id<E>> + '_ {
274        self.0.iter().map(Row::id)
275    }
276
277    /// Check whether the response contains the provided identifier.
278    pub fn contains_id(&self, id: &Id<E>) -> bool {
279        self.0.iter().any(|row| row.id() == *id)
280    }
281}
282
283impl<R: ResponseRow> IntoIterator for Response<R> {
284    type Item = R;
285    type IntoIter = std::vec::IntoIter<Self::Item>;
286
287    fn into_iter(self) -> Self::IntoIter {
288        self.0.into_iter()
289    }
290}
291
292impl<'a, R: ResponseRow> IntoIterator for &'a Response<R> {
293    type Item = &'a R;
294    type IntoIter = std::slice::Iter<'a, R>;
295
296    fn into_iter(self) -> Self::IntoIter {
297        self.iter()
298    }
299}
300
301///
302/// WriteBatchResponse
303///
304/// Result of a batch write operation.
305/// Provides explicit access to stored entities and their identifiers.
306///
307
308#[derive(Debug)]
309pub struct WriteBatchResponse<E> {
310    entities: Vec<E>,
311}
312
313impl<E> WriteBatchResponse<E> {
314    /// Construct a batch response from stored entities.
315    #[must_use]
316    pub const fn new(entities: Vec<E>) -> Self {
317        Self { entities }
318    }
319
320    /// Return the number of entries.
321    #[must_use]
322    pub const fn len(&self) -> usize {
323        self.entities.len()
324    }
325
326    /// Returns `true` if the batch is empty.
327    #[must_use]
328    pub const fn is_empty(&self) -> bool {
329        self.entities.is_empty()
330    }
331
332    /// Return all stored entities.
333    #[must_use]
334    pub fn entities(self) -> Vec<E> {
335        self.entities
336    }
337
338    /// Borrow an iterator over primary keys in stable batch order.
339    pub fn ids(&self) -> impl Iterator<Item = Id<E>> + '_
340    where
341        E: EntityValue,
342    {
343        self.entities.iter().map(EntityValue::id)
344    }
345
346    /// Borrow an iterator over write entries in stable batch order.
347    pub fn iter(&self) -> std::slice::Iter<'_, E> {
348        self.entities.iter()
349    }
350}
351
352impl<E> IntoIterator for WriteBatchResponse<E> {
353    type Item = E;
354    type IntoIter = std::vec::IntoIter<E>;
355
356    fn into_iter(self) -> Self::IntoIter {
357        self.entities.into_iter()
358    }
359}
360
361impl<'a, E> IntoIterator for &'a WriteBatchResponse<E> {
362    type Item = &'a E;
363    type IntoIter = std::slice::Iter<'a, E>;
364
365    fn into_iter(self) -> Self::IntoIter {
366        self.iter()
367    }
368}
icydb_core/db/response/mod.rs

icydb_core/db/response/
mod.rs
