#![cfg(feature = "sqlite")]
use super::{OrderSubjects, SqlKeyset, SubjectShape, SubjectSlot, TermColumns};
use crate::{
At, Carrier, ComplexComparison, Cursor, CursorError, FieldName, OrderDirection, OrderTerm,
TermName, Walk,
comparison::sql::{
SqlConjunction, SqlOrder,
tests::{Probe, ROW},
},
};
const A: &TermName = TermName::new("a");
const B: &TermName = TermName::new("b");
const ID: &TermName = TermName::new("id");
fn required() -> [OrderTerm; 3] {
[
OrderTerm::new(A, FieldName::new("a"), OrderDirection::Asc),
OrderTerm::new(B, FieldName::new("b"), OrderDirection::Desc),
OrderTerm::new(ID, FieldName::new("id"), OrderDirection::Asc),
]
}
fn optional() -> [OrderTerm; 3] {
[
OrderTerm::nullable(A, FieldName::new("a"), OrderDirection::Asc),
OrderTerm::new(B, FieldName::new("b"), OrderDirection::Desc),
OrderTerm::new(ID, FieldName::new("id"), OrderDirection::Asc),
]
}
fn rendered_with(
terms: &[OrderTerm],
values: &[Option<i64>],
walk: Walk,
lead: &'static str,
) -> String {
let order = SqlOrder::<sqlx::Sqlite>::new(terms).expect("a renderable order");
let cursor = Cursor::at(terms, values.to_vec());
let keyset = SqlKeyset::resume(order, &cursor, walk).expect("this cursor is this order's");
let mut qb = sqlx::QueryBuilder::<sqlx::Sqlite>::default();
{
let accumulator = SqlConjunction::with_lead(&mut qb, lead);
assert_eq!(keyset.conjuncts(), 1);
keyset
.apply(At::new(&ROW), accumulator)
.expect("a constructed keyset cannot refuse");
}
qb.into_string()
}
fn rendered(terms: &[OrderTerm], values: &[Option<i64>], walk: Walk) -> String {
rendered_with(terms, values, walk, "")
}
fn rendered_over<S: OrderSubjects<sqlx::Sqlite>>(
terms: &[OrderTerm],
values: &[Option<i64>],
walk: Walk,
subjects: S,
) -> (String, usize) {
use sqlx::Execute;
let order = SqlOrder::<sqlx::Sqlite>::new(terms).expect("a renderable order");
let cursor = Cursor::at(terms, values.to_vec());
let keyset =
SqlKeyset::resume_with(order, &cursor, walk, subjects).expect("this cursor is this order's");
let mut qb = sqlx::QueryBuilder::<sqlx::Sqlite>::default();
{
let accumulator = SqlConjunction::with_lead(&mut qb, "");
assert_eq!(keyset.conjuncts(), 1);
keyset
.apply(At::new(&ROW), accumulator)
.expect("a constructed keyset cannot refuse");
}
let mut built = qb.build();
let binds = match built.take_arguments() {
Ok(Some(arguments)) => sqlx::Arguments::len(&arguments),
Ok(None) | Err(_) => 0,
};
(built.sql().as_str().to_owned(), binds)
}
struct CoverTitle<'a> {
bound: &'a core::cell::RefCell<Vec<i64>>,
}
impl OrderSubjects<sqlx::Sqlite> for CoverTitle<'_> {
fn push_subject(
&self,
slot: SubjectSlot<'_, sqlx::Sqlite>,
at: At<'_>,
terms: &[OrderTerm],
level: usize,
) {
if level > 0 {
TermColumns.push_subject(slot, at, terms, level);
return;
}
slot.write(|qb| {
qb.push("SELECT \"title\" FROM \"keyframe\" WHERE \"id\" = ");
Probe {
value: 9,
bound: self.bound,
}
.push_bind(qb);
});
}
fn shape(&self, _: &[OrderTerm], level: usize) -> SubjectShape {
if level > 0 {
return SubjectShape::Column;
}
SubjectShape::SubSelect
}
}
#[test]
fn the_column_expansion_is_the_seam_at_its_default() {
let values = [Some(1), Some(2), Some(3)];
assert_eq!(
rendered_over(&required(), &values, Walk::Forward, TermColumns),
(
rendered(&required(), &values, Walk::Forward),
5
)
);
}
#[test]
fn an_expression_subject_renders_the_whole_expansion_around_it() {
let bound = core::cell::RefCell::new(Vec::new());
assert_eq!(
rendered_over(
&required(),
&[Some(1), Some(2), Some(3)],
Walk::Forward,
CoverTitle { bound: &bound }
),
(
"((SELECT \"title\" FROM \"keyframe\" WHERE \"id\" = ?) > ? \
OR ((SELECT \"title\" FROM \"keyframe\" WHERE \"id\" = ?) = ? \
AND (\"b\" < ? OR (\"b\" = ? AND (\"id\" > ?)))))"
.to_owned(),
7
)
);
assert_eq!(*bound.borrow(), [9, 9]);
}
#[test]
fn a_descending_nullable_expression_subject_is_written_at_every_occurrence() {
let bound = core::cell::RefCell::new(Vec::new());
assert_eq!(
rendered_over(
&optional(),
&[Some(1), Some(2), Some(3)],
Walk::Backward,
CoverTitle { bound: &bound }
),
(
"((SELECT \"title\" FROM \"keyframe\" WHERE \"id\" = ?) < ? \
OR (SELECT \"title\" FROM \"keyframe\" WHERE \"id\" = ?) IS NULL \
OR ((SELECT \"title\" FROM \"keyframe\" WHERE \"id\" = ?) = ? \
AND (\"b\" > ? OR (\"b\" = ? AND (\"id\" < ?)))))"
.to_owned(),
8
)
);
assert_eq!(*bound.borrow(), [9, 9, 9]);
}
#[test]
fn the_forward_expansion_follows_each_column_s_own_direction() {
assert_eq!(
rendered(&required(), &[Some(1), Some(2), Some(3)], Walk::Forward),
"(\"a\" > ? OR (\"a\" = ? AND (\"b\" < ? OR (\"b\" = ? AND (\"id\" > ?)))))"
);
}
#[test]
fn the_backward_expansion_inverts_every_comparator() {
assert_eq!(
rendered(&required(), &[Some(1), Some(2), Some(3)], Walk::Backward),
"(\"a\" < ? OR (\"a\" = ? AND (\"b\" > ? OR (\"b\" = ? AND (\"id\" < ?)))))"
);
}
#[test]
fn an_ascending_nullable_term_with_a_value_needs_no_extra_arm() {
assert_eq!(
rendered(&optional(), &[Some(1), Some(2), Some(3)], Walk::Forward),
"(\"a\" > ? OR (\"a\" = ? AND (\"b\" < ? OR (\"b\" = ? AND (\"id\" > ?)))))"
);
}
#[test]
fn a_descending_nullable_term_with_a_value_admits_the_nulls_after_it() {
assert_eq!(
rendered(&optional(), &[Some(1), Some(2), Some(3)], Walk::Backward),
"(\"a\" < ? OR \"a\" IS NULL OR (\"a\" = ? AND (\"b\" > ? OR (\"b\" = ? AND (\"id\" < ?)))))"
);
}
#[test]
fn a_null_cursor_value_under_an_ascending_term_admits_every_value_and_ties_on_the_rest() {
assert_eq!(
rendered(&optional(), &[None, Some(2), Some(3)], Walk::Forward),
"(\"a\" IS NOT NULL OR (\"a\" IS NULL AND (\"b\" < ? OR (\"b\" = ? AND (\"id\" > ?)))))"
);
}
#[test]
fn a_null_cursor_value_under_a_descending_term_has_no_arm_and_still_ties() {
assert_eq!(
rendered(&optional(), &[None, Some(2), Some(3)], Walk::Backward),
"((\"a\" IS NULL AND (\"b\" > ? OR (\"b\" = ? AND (\"id\" < ?)))))"
);
}
#[test]
fn a_one_term_order_is_the_general_form_degenerating() {
let terms = [OrderTerm::new(
ID,
FieldName::new("id"),
OrderDirection::Asc,
)];
assert_eq!(rendered(&terms, &[Some(3)], Walk::Forward), "(\"id\" > ?)");
}
#[test]
fn a_cursor_no_row_can_be_after_renders_the_empty_page() {
let terms = [
OrderTerm::nullable(A, FieldName::new("a"), OrderDirection::Desc),
OrderTerm::nullable(B, FieldName::new("b"), OrderDirection::Desc),
];
assert_eq!(rendered(&terms, &[None, None], Walk::Forward), "1 = 0");
}
#[test]
fn the_expansion_is_one_conjunct_beside_a_filter_s_own() {
assert_eq!(
rendered_with(
&required(),
&[Some(1), Some(2), Some(3)],
Walk::Forward,
" AND "
),
" AND (\"a\" > ? OR (\"a\" = ? AND (\"b\" < ? OR (\"b\" = ? AND (\"id\" > ?)))))"
);
}
#[test]
fn a_cursor_from_another_order_never_becomes_a_predicate() {
let terms = required();
let other = [
OrderTerm::new(B, FieldName::new("b"), OrderDirection::Asc),
OrderTerm::new(ID, FieldName::new("id"), OrderDirection::Asc),
];
let order = SqlOrder::<sqlx::Sqlite>::new(&terms).expect("a renderable order");
let cursor = Cursor::at(&other, [Some(2i64), Some(3)]);
assert!(matches!(
SqlKeyset::resume(order, &cursor, Walk::Forward),
Err(CursorError::Order(_))
));
}
#[test]
fn a_column_is_bracketed_by_the_seam_that_already_brackets_one() {
let terms = [OrderTerm::new(
ID,
FieldName::new("a\"b"),
OrderDirection::Asc,
)];
assert_eq!(
rendered(&terms, &[Some(3)], Walk::Forward),
"(\"a\"\"b\" > ?)"
);
}
#[cfg(feature = "postgres")]
mod collection_boundary {
use super::{A, ID};
use crate::{
At, Carrier, ComplexComparison, Cursor, CursorError, CursorValue, FieldName, OrderDirection,
OrderTerm, TermSubject, Walk,
comparison::sql::{SqlConjunction, SqlKeyset, SqlOrder, tests::ROW},
query::{CollectionBoundary, OrderCapability, partition},
};
fn ascending() -> [OrderTerm; 2] {
[
OrderTerm::array(A, FieldName::new("tags"), OrderDirection::Asc),
OrderTerm::new(ID, FieldName::new("id"), OrderDirection::Asc),
]
}
fn descending() -> [OrderTerm; 2] {
[
OrderTerm::array(A, FieldName::new("tags"), OrderDirection::Desc),
OrderTerm::new(ID, FieldName::new("id"), OrderDirection::Desc),
]
}
#[derive(Debug, Clone, PartialEq)]
enum Slot {
Tags(Vec<String>),
Id(i64),
}
impl CursorValue for Slot {
fn write_cursor(&self, out: &mut Vec<u8>) {
match self {
Self::Tags(value) => {
out.push(0);
value.write_cursor(out);
}
Self::Id(value) => {
out.push(1);
value.write_cursor(out);
}
}
}
fn read_cursor(bytes: &[u8]) -> Option<Self> {
let (tag, rest) = bytes.split_first()?;
match *tag {
0 => <Vec<String> as CursorValue>::read_cursor(rest).map(Self::Tags),
1 => <i64 as CursorValue>::read_cursor(rest).map(Self::Id),
_ => None,
}
}
}
impl Carrier<sqlx::Postgres> for Slot {
fn push_bind(&self, qb: &mut sqlx::QueryBuilder<sqlx::Postgres>) {
match self {
Self::Tags(value) => value.push_bind(qb),
Self::Id(value) => value.push_bind(qb),
}
}
}
fn rendered(terms: &[OrderTerm], values: Vec<Option<Slot>>, walk: Walk) -> (String, usize) {
use sqlx::Execute;
let order = SqlOrder::<sqlx::Postgres>::new(terms).expect("a renderable order");
let cursor = Cursor::at(terms, values);
let keyset = SqlKeyset::resume(order, &cursor, walk).expect("this cursor is this order's");
let mut qb = sqlx::QueryBuilder::<sqlx::Postgres>::default();
{
let accumulator = SqlConjunction::with_lead(&mut qb, "");
keyset
.apply(At::new(&ROW), accumulator)
.expect("a constructed keyset cannot refuse");
}
let mut built = qb.build();
let binds = match built.take_arguments() {
Ok(Some(args)) => sqlx::Arguments::len(&args),
Ok(None) | Err(_) => 0,
};
(built.sql().as_str().to_owned(), binds)
}
fn boundary(tags: &[&str], id: i64) -> Vec<Option<Slot>> {
vec![
Some(Slot::Tags(
tags.iter().map(|tag| (*tag).to_owned()).collect(),
)),
Some(Slot::Id(id)),
]
}
#[test]
fn a_postgres_page_over_an_array_stored_collection_is_served() {
let terms = ascending();
assert_eq!(terms[0].subject(), TermSubject::Array);
assert_eq!(
<sqlx::Postgres as OrderCapability>::COLLECTION_BOUNDARY,
CollectionBoundary::Bindable
);
assert_eq!(
partition::<sqlx::Postgres>(&terms).paging::<sqlx::Postgres>(),
Ok(&terms[..])
);
}
#[test]
fn the_expansion_binds_the_whole_list_once_per_arm() {
assert_eq!(
rendered(&ascending(), boundary(&["hdr", "sdr"], 7), Walk::Forward),
(
"(\"tags\" > $1 OR (\"tags\" = $2 AND (\"id\" > $3)))".to_owned(),
3
)
);
assert_eq!(
rendered(&descending(), boundary(&["hdr", "sdr"], 7), Walk::Forward),
(
"(\"tags\" < $1 OR (\"tags\" = $2 AND (\"id\" < $3)))".to_owned(),
3
)
);
assert_eq!(
rendered(
&ascending(),
boundary(&["a", "b", "c", "d", "e", "f"], 7),
Walk::Forward
),
(
"(\"tags\" > $1 OR (\"tags\" = $2 AND (\"id\" > $3)))".to_owned(),
3
)
);
}
#[test]
fn the_backward_walk_inverts_the_collection_arm_too() {
assert_eq!(
rendered(&ascending(), boundary(&["hdr"], 7), Walk::Backward).0,
"(\"tags\" < $1 OR (\"tags\" = $2 AND (\"id\" < $3)))"
);
assert_eq!(
rendered(&descending(), boundary(&["hdr"], 7), Walk::Backward).0,
"(\"tags\" > $1 OR (\"tags\" = $2 AND (\"id\" > $3)))"
);
}
#[test]
fn the_empty_list_is_a_present_boundary() {
assert_eq!(
rendered(&ascending(), boundary(&[], 7), Walk::Forward),
(
"(\"tags\" > $1 OR (\"tags\" = $2 AND (\"id\" > $3)))".to_owned(),
3
)
);
}
#[test]
fn the_boundary_list_survives_the_opaque_string() {
let terms = ascending();
let values = boundary(&["hdr", "", "sdr"], 7);
let cursor = Cursor::at(&terms, values.clone());
let decoded = Cursor::<Slot>::decode(&cursor.encode()).expect("this crate wrote it");
assert_eq!(decoded, cursor);
assert_eq!(decoded.resume(&terms), Ok(&values[..]));
let empty = Cursor::at(&terms, boundary(&[], 1));
assert_eq!(
Cursor::<Slot>::decode(&empty.encode()).expect("this crate wrote it"),
empty
);
}
#[test]
fn a_cursor_from_another_order_is_still_refused() {
let terms = ascending();
let other = [OrderTerm::new(
ID,
FieldName::new("id"),
OrderDirection::Asc,
)];
let order = SqlOrder::<sqlx::Postgres>::new(&terms).expect("a renderable order");
let cursor = Cursor::at(&other, [Some(Slot::Id(7))]);
assert!(matches!(
SqlKeyset::resume(order, &cursor, Walk::Forward),
Err(CursorError::Order(_))
));
}
}
mod spanning {
use super::{ID, ROW, rendered_with};
use crate::{
At, ComplexComparison, Cursor, CursorValue, FieldName, OrderDirection, OrderTerm, TermName,
Walk,
comparison::sql::{SqlConjunction, SqlKeyset, SqlOrder},
};
const AT: &TermName = TermName::new("at");
fn instant() -> [OrderTerm; 2] {
[
OrderTerm::spanning(
AT,
FieldName::new("at"),
<crate::Timestamp as crate::ColumnKind>::SEGMENTS,
<crate::Timestamp as crate::ColumnKind>::ORDER,
OrderDirection::Asc,
),
OrderTerm::new(ID, FieldName::new("id"), OrderDirection::Asc),
]
}
fn at() -> crate::Timestamp {
"2026-08-09T21:14:03.123456789Z"
.parse()
.expect("the fixture parses")
}
#[derive(Debug, Clone, PartialEq)]
enum Slot {
At(crate::Timestamp),
Id(i64),
}
impl CursorValue for Slot {
fn write_cursor(&self, out: &mut Vec<u8>) {
match self {
Self::At(value) => {
out.push(0);
value.write_cursor(out);
}
Self::Id(value) => {
out.push(1);
value.write_cursor(out);
}
}
}
fn read_cursor(bytes: &[u8]) -> Option<Self> {
let (tag, rest) = bytes.split_first()?;
match *tag {
0 => CursorValue::read_cursor(rest).map(Self::At),
1 => CursorValue::read_cursor(rest).map(Self::Id),
_ => None,
}
}
}
impl crate::Carrier<sqlx::Sqlite> for Slot {
fn push_bind(&self, qb: &mut sqlx::QueryBuilder<sqlx::Sqlite>) {
match self {
Self::At(value) => crate::Carrier::push_bind(value, qb),
Self::Id(value) => crate::Carrier::push_bind(value, qb),
}
}
}
fn rendered(values: &[Option<Slot>], walk: Walk) -> (String, usize) {
use sqlx::Execute;
let terms = instant();
let order = SqlOrder::<sqlx::Sqlite>::new(&terms).expect("a renderable order");
let cursor = Cursor::at(&terms, values.to_vec());
let keyset = SqlKeyset::resume(order, &cursor, walk).expect("this cursor is this order's");
let mut qb = sqlx::QueryBuilder::<sqlx::Sqlite>::default();
{
let accumulator = SqlConjunction::with_lead(&mut qb, "");
keyset
.apply(At::new(&ROW), accumulator)
.expect("a constructed keyset cannot refuse");
}
let mut built = qb.build();
let binds = match built.take_arguments() {
Ok(Some(args)) => sqlx::Arguments::len(&args),
Ok(None) | Err(_) => 0,
};
(built.sql().as_str().to_owned(), binds)
}
#[test]
fn an_instant_level_is_a_row_value_at_both_of_its_occurrences() {
assert_eq!(
rendered(&[Some(Slot::At(at())), Some(Slot::Id(7))], Walk::Forward),
(
"((\"at_secs\", \"at_nanos\") > (?, ?) OR ((\"at_secs\", \"at_nanos\") = (?, ?) AND \
(\"id\" > ?)))"
.to_owned(),
5
)
);
}
#[test]
fn a_backward_walk_inverts_the_pairs_comparator() {
assert_eq!(
rendered(&[Some(Slot::At(at())), Some(Slot::Id(7))], Walk::Backward).0,
"((\"at_secs\", \"at_nanos\") < (?, ?) OR ((\"at_secs\", \"at_nanos\") = (?, ?) AND \
(\"id\" < ?)))"
);
}
#[test]
fn a_null_at_a_composite_level_tests_the_leaves() {
let terms = [
OrderTerm::spanning_nullable(
AT,
FieldName::new("at"),
<crate::Timestamp as crate::ColumnKind>::SEGMENTS,
<crate::Timestamp as crate::ColumnKind>::ORDER,
OrderDirection::Asc,
),
OrderTerm::new(ID, FieldName::new("id"), OrderDirection::Asc),
];
let order = SqlOrder::<sqlx::Sqlite>::new(&terms).expect("a renderable order");
let cursor = Cursor::at(&terms, vec![None, Some(Slot::Id(7))]);
let keyset = SqlKeyset::resume(order, &cursor, Walk::Forward).expect("this order's cursor");
let mut qb = sqlx::QueryBuilder::<sqlx::Sqlite>::default();
{
let accumulator = SqlConjunction::with_lead(&mut qb, "");
keyset
.apply(At::new(&ROW), accumulator)
.expect("a constructed keyset cannot refuse");
}
assert_eq!(
qb.into_string(),
"((\"at_secs\" IS NOT NULL AND \"at_nanos\" IS NOT NULL) OR \
((\"at_secs\" IS NULL AND \"at_nanos\" IS NULL) AND (\"id\" > ?)))"
);
}
#[test]
fn a_scalar_level_is_unchanged() {
assert_eq!(
rendered_with(
&[OrderTerm::new(
ID,
FieldName::new("id"),
OrderDirection::Asc
)],
&[Some(7i64)],
Walk::Forward,
"",
),
"(\"id\" > ?)"
);
}
}
mod derived_leaf {
use super::{ID, rendered_with};
use crate::{
ColumnName, ColumnShape, FieldName, OrderDirection, OrderTerm, TermName, Walk,
comparison::sql::SqlOrder,
};
const AT: &TermName = TermName::new("at");
const SEGMENTS: &[ColumnShape] = &[
ColumnShape::Plain(ColumnName::new("pts")),
ColumnShape::Composite {
field: Some(ColumnName::new("timebase")),
segments: &[
ColumnShape::Plain(ColumnName::new("num")),
ColumnShape::Plain(ColumnName::new("den")),
],
},
ColumnShape::Nullable(ColumnName::new("nanos")),
];
fn terms() -> [OrderTerm; 2] {
[
OrderTerm::spanning_nullable(AT, FieldName::new("at"), SEGMENTS, &[], OrderDirection::Asc),
OrderTerm::new(ID, FieldName::new("id"), OrderDirection::Asc),
]
}
#[test]
fn the_term_counts_its_columns_and_its_value_columns_apart() {
let [at, id] = terms();
assert_eq!(at.width(), 4, "pts, num, den, nanos");
assert_eq!(
at.value_width(),
3,
"and the derived position is not one of them"
);
assert_eq!(id.width(), 1, "a scalar term's one column");
assert_eq!(id.value_width(), 1, "is also its value");
}
#[test]
fn a_null_test_over_a_derived_composite_skips_the_derived_leaf() {
let rendered = rendered_with(&terms(), &[None, Some(7i64)], Walk::Forward, "");
assert_eq!(
rendered,
"((\"at_pts\" IS NOT NULL AND \"at_timebase_num\" IS NOT NULL AND \"at_timebase_den\" IS NOT \
NULL) OR ((\"at_pts\" IS NULL AND \"at_timebase_num\" IS NULL AND \"at_timebase_den\" IS \
NULL) AND (\"id\" > ?)))"
);
assert!(
!rendered.contains("at_nanos"),
"the derived column is absent from a presence question by name, which is the claim the \
column list above could satisfy by accident"
);
}
#[test]
fn a_comparison_over_a_derived_composite_names_every_column() {
let terms = terms();
let _ = SqlOrder::<sqlx::Sqlite>::new(&terms).expect("a renderable order");
let rendered = rendered_with(&terms, &[Some(1i64), Some(7i64)], Walk::Forward, "");
assert!(
rendered.contains("(\"at_pts\", \"at_timebase_num\", \"at_timebase_den\", \"at_nanos\") > ("),
"the arm compares what the ORDER BY sorted by: {rendered}"
);
}
}