icydb_core/db/query/fluent/load/
pagination.rs

1//! Module: query::fluent::load::pagination
2//! Responsibility: fluent paged-query wrapper APIs and cursor continuation terminals.
3//! Does not own: planner semantic validation or runtime execution internals.
4//! Boundary: exposes paged execution surfaces over fluent load query contracts.
5
6use crate::{
7    db::{
8        PagedGroupedExecutionWithTrace, PagedLoadExecution, PagedLoadExecutionWithTrace,
9        query::fluent::load::FluentLoadQuery,
10        query::intent::{Query, QueryError},
11    },
12    traits::{EntityKind, EntityValue},
13};
14
15///
16/// PagedLoadQuery
17///
18/// Session-bound cursor pagination wrapper.
19/// This wrapper only exposes cursor continuation and paged execution.
20///
21
22pub struct PagedLoadQuery<'a, E>
23where
24    E: EntityKind,
25{
26    inner: FluentLoadQuery<'a, E>,
27}
28
29impl<'a, E> FluentLoadQuery<'a, E>
30where
31    E: EntityKind,
32{
33    /// Enter typed cursor-pagination mode for this query.
34    ///
35    /// Cursor pagination requires:
36    /// - explicit `order_by(...)`
37    /// - explicit `limit(...)`
38    ///
39    /// Requests are deterministic under canonical ordering, but continuation is
40    /// best-effort and forward-only over live state.
41    /// No snapshot/version is pinned across requests, so concurrent writes may
42    /// shift page boundaries.
43    pub fn page(self) -> Result<PagedLoadQuery<'a, E>, QueryError> {
44        self.ensure_paged_mode_ready()?;
45
46        Ok(PagedLoadQuery { inner: self })
47    }
48
49    /// Execute this query as cursor pagination and return items + next cursor.
50    ///
51    /// The returned cursor token is opaque and must be passed back via `.cursor(...)`.
52    pub fn execute_paged(self) -> Result<PagedLoadExecution<E>, QueryError>
53    where
54        E: EntityValue,
55    {
56        self.page()?.execute()
57    }
58
59    /// Execute one grouped query page with optional grouped continuation cursor.
60    ///
61    /// This grouped entrypoint is intentionally separate from scalar load
62    /// execution to keep grouped response shape explicit.
63    pub fn execute_grouped(self) -> Result<PagedGroupedExecutionWithTrace, QueryError>
64    where
65        E: EntityValue,
66    {
67        self.session
68            .execute_grouped(self.query(), self.cursor_token.as_deref())
69    }
70}
71
72impl<E> PagedLoadQuery<'_, E>
73where
74    E: EntityKind,
75{
76    // ------------------------------------------------------------------
77    // Intent inspection
78    // ------------------------------------------------------------------
79
80    #[must_use]
81    pub const fn query(&self) -> &Query<E> {
82        self.inner.query()
83    }
84
85    // ------------------------------------------------------------------
86    // Cursor continuation
87    // ------------------------------------------------------------------
88
89    /// Attach an opaque continuation token for the next page.
90    #[must_use]
91    pub fn cursor(mut self, token: impl Into<String>) -> Self {
92        self.inner = self.inner.cursor(token);
93        self
94    }
95
96    // ------------------------------------------------------------------
97    // Execution
98    // ------------------------------------------------------------------
99
100    /// Execute in cursor-pagination mode and return items + next cursor.
101    ///
102    /// Continuation is best-effort and forward-only over live state:
103    /// deterministic per request under canonical ordering, with no
104    /// snapshot/version pinned across requests.
105    pub fn execute(self) -> Result<PagedLoadExecution<E>, QueryError>
106    where
107        E: EntityValue,
108    {
109        self.execute_with_trace()
110            .map(PagedLoadExecutionWithTrace::into_execution)
111    }
112
113    /// Execute in cursor-pagination mode and return items, next cursor,
114    /// and optional execution trace details when session debug mode is enabled.
115    ///
116    /// Trace collection is opt-in via `DbSession::debug()` and does not
117    /// change query planning or result semantics.
118    pub fn execute_with_trace(self) -> Result<PagedLoadExecutionWithTrace<E>, QueryError>
119    where
120        E: EntityValue,
121    {
122        self.inner.ensure_paged_mode_ready()?;
123
124        self.inner.session.execute_load_query_paged_with_trace(
125            self.inner.query(),
126            self.inner.cursor_token.as_deref(),
127        )
128    }
129}
icydb_core/db/query/fluent/load/pagination.rs

icydb_core/db/query/fluent/load/
pagination.rs
