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        PagedLoadExecution, PagedLoadExecutionWithTrace, PersistedRow,
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: PersistedRow,
32{
33    /// Enter typed cursor-pagination mode for this query.
34    ///
35    /// Cursor pagination requires:
36    /// - explicit `order_term(...)`
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: PersistedRow + EntityValue,
55    {
56        self.page()?.execute()
57    }
58}
59
60impl<E> PagedLoadQuery<'_, E>
61where
62    E: PersistedRow,
63{
64    // ------------------------------------------------------------------
65    // Intent inspection
66    // ------------------------------------------------------------------
67
68    #[must_use]
69    pub const fn query(&self) -> &Query<E> {
70        self.inner.query()
71    }
72
73    // ------------------------------------------------------------------
74    // Cursor continuation
75    // ------------------------------------------------------------------
76
77    /// Attach an opaque continuation token for the next page.
78    #[must_use]
79    pub fn cursor(mut self, token: impl Into<String>) -> Self {
80        self.inner = self.inner.cursor(token);
81        self
82    }
83
84    // ------------------------------------------------------------------
85    // Execution
86    // ------------------------------------------------------------------
87
88    /// Execute in cursor-pagination mode and return items + next cursor.
89    ///
90    /// Continuation is best-effort and forward-only over live state:
91    /// deterministic per request under canonical ordering, with no
92    /// snapshot/version pinned across requests.
93    pub fn execute(self) -> Result<PagedLoadExecution<E>, QueryError>
94    where
95        E: PersistedRow + EntityValue,
96    {
97        self.execute_with_trace()
98            .map(PagedLoadExecutionWithTrace::into_execution)
99    }
100
101    /// Execute in cursor-pagination mode and return items, next cursor,
102    /// and optional execution trace details when session debug mode is enabled.
103    ///
104    /// Trace collection is opt-in via `DbSession::debug()` and does not
105    /// change query planning or result semantics.
106    pub fn execute_with_trace(self) -> Result<PagedLoadExecutionWithTrace<E>, QueryError>
107    where
108        E: PersistedRow + EntityValue,
109    {
110        // `PagedLoadQuery` can only be constructed through `FluentLoadQuery::page`,
111        // so the paged-mode validation already happened before this wrapper existed.
112        self.inner.session.execute_load_query_paged_with_trace(
113            self.inner.query(),
114            self.inner.cursor_token.as_deref(),
115        )
116    }
117}
icydb_core/db/query/fluent/load/pagination.rs

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