paginate_core/lib.rs
1//! # paginate-core
2//!
3//! Pure, language-agnostic engine behind the [`pypaginate`] (Python) and
4//! [`@cyblow/paginate`] (TypeScript) packages. It owns the computational heart
5//! of the library — cursor encoding, offset math, text normalization,
6//! filtering, sorting and search — with **zero binding dependencies** so the
7//! exact same crate links natively into Python (via PyO3) and Node/TypeScript
8//! (via napi-rs), and compiles unchanged to WebAssembly for an optional
9//! browser/edge target.
10//!
11//! ## Design rules
12//!
13//! * **Plain data only.** Everything crosses the boundary as [`value::Value`],
14//! a small JSON-like enum. No host objects, no framework types.
15//! * **Deterministic & side-effect free.** Same input, same output — which is
16//! what lets the shared property-based invariants double as every binding's
17//! conformance suite.
18//! * **Behaviour parity.** Each binding wraps this one engine, so results match
19//! across languages (e.g. the cursor wire format is byte-identical, so cursors
20//! minted by any implementation decode in the others).
21//!
22//! [`pypaginate`]: https://github.com/CybLow/paginate
23//! [`@cyblow/paginate`]: https://www.npmjs.com/package/@cyblow/paginate
24
25#![forbid(unsafe_code)]
26#![warn(missing_docs)]
27
28// Internal-only modules: shared helpers and the error type. `CoreError`/`Result`
29// reach the public API through the flat re-exports below, never `core::error::`.
30mod accessor;
31mod coerce;
32mod error;
33
34pub mod columnar;
35pub mod cursor;
36pub mod filter;
37pub mod json;
38pub mod keyset;
39pub mod normalize;
40pub mod pagination;
41pub mod pipeline;
42pub mod resident;
43pub mod search;
44pub mod sort;
45pub mod validate;
46pub mod value;
47
48// Wire-form DTOs + JSON Schema export — the cross-language type contract. Behind
49// the `schema` feature so the default build carries no schemars dependency.
50#[cfg(feature = "schema")]
51pub mod schema;
52
53// Flat re-export of the public surface: callers (and the PyO3 / napi bindings)
54// write `paginate_core::FilterSpec`, never `paginate_core::filter::types::...`,
55// so the module layout can change without breaking them. This is the single,
56// canonical home of the domain contract the language bindings wrap.
57pub use columnar::Columns;
58pub use cursor::{decode_cursor, encode_cursor};
59pub use error::{CoreError, ErrorKind, Result};
60pub use filter::{FilterGroup, FilterInput, FilterLogic, FilterNode, FilterOp, FilterSpec};
61pub use normalize::normalize_text;
62pub use pagination::Limit;
63pub use pipeline::{offset_page, offset_page_searched, Page, SearchStage};
64pub use search::{FuzzyMode, SearchFieldMode, SearchSpec, TrigramIndex};
65pub use sort::{NullsPosition, SortDirection, SortSpec};
66pub use validate::MAX_LIMIT;
67pub use value::Value;