0.5.1-pre.002

ks-store/src/contracts/pagination.rs

@@ -0,0 +1,74 @@
+// file: ks-store/src/contracts/pagination.rs
+// version: 2
+
+//! Backend-neutral pagination and sorting contracts for repository operations.
+
+/// Default page size for repository list operations.
+pub const DEFAULT_PAGE_SIZE: u16 = 100;
+/// Maximum page size for repository list operations.
+pub const MAX_PAGE_SIZE: u16 = 1000;
+
+/// Sort direction for repository list operations.
+#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub enum SortDirection {
+    /// Sort values in ascending order.
+    Asc,
+    /// Sort values in descending order.
+    Desc,
+}
+
+/// Page request contract for repository list operations.
+#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct PageRequest {
+    /// Maximum number of rows to return.
+    pub limit: u16,
+    /// Zero-based row offset.
+    pub offset: u64,
+}
+
+impl PageRequest {
+    /// Builds a page request after minimal bounds validation.
+    pub fn new(limit: u16, offset: u64) -> ks_core::Result<Self> {
+        if limit == 0 {
+            return std::result::Result::Err(ks_core::Error::db(
+                "page limit must be greater than zero",
+            ));
+        }
+        if limit > crate::MAX_PAGE_SIZE {
+            return std::result::Result::Err(ks_core::Error::db(
+                "page limit exceeds maximum page size",
+            ));
+        }
+        return std::result::Result::Ok(Self { limit, offset });
+    }
+
+    /// Builds the default first page request.
+    pub fn first_page() -> Self {
+        return Self {
+            limit: crate::DEFAULT_PAGE_SIZE,
+            offset: 0,
+        };
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn page_request_rejects_zero_limit() {
+        let result = crate::PageRequest::new(0, 0);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn page_request_rejects_limit_above_maximum() {
+        let result = crate::PageRequest::new(crate::MAX_PAGE_SIZE + 1, 0);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn first_page_uses_default_limit() {
+        let request = crate::PageRequest::first_page();
+        assert_eq!(request.limit, crate::DEFAULT_PAGE_SIZE);
+        assert_eq!(request.offset, 0);
+    }
+}