use std::fmt::Write as _;
use crate::{
dialect::{PostgresDialect, SqlDialect},
types::{
DatabaseType,
sql_hints::{OrderByClause, OrderDirection, ScalarFieldType},
},
};
pub const SORT_KEYS_KEY: &str = "__fraiseql_sort_keys";
#[must_use]
pub fn with_sort_keys(document: &str, keys: &[KeysetKey]) -> String {
if keys.is_empty() {
return document.to_string();
}
let values: Vec<String> = keys.iter().map(|k| format!("({})::text", k.expr)).collect();
format!(
"({document} || jsonb_build_object('{SORT_KEYS_KEY}', jsonb_build_array({})))",
values.join(", ")
)
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct KeysetKey {
pub expr: String,
pub direction: OrderDirection,
cast: Cast,
seekable: bool,
}
#[derive(Debug, Clone, PartialEq, Eq)]
enum Cast {
Text,
Scalar(ScalarFieldType),
Native(String),
Float,
}
impl KeysetKey {
fn param(&self, placeholder: &str) -> String {
match self.value_type() {
Some(ty) => format!("({placeholder}::text)::{ty}"),
None => format!("{placeholder}::text"),
}
}
fn value_type(&self) -> Option<String> {
match &self.cast {
Cast::Text => None,
Cast::Scalar(ty) => PostgresDialect.cast_type_name(*ty).map(str::to_string),
Cast::Native(native) => match native.to_lowercase().as_str() {
"boolean" | "bool" => Some("boolean".to_string()),
"text" | "varchar" | "character varying" | "char" | "bpchar" | "name" => None,
_ => Some(native.clone()),
},
Cast::Float => Some("float8".to_string()),
}
}
}
#[must_use]
pub fn cursor_values_probe(
keys: &[KeysetKey],
values: &[Option<String>],
uuid_position: Option<&str>,
) -> Option<(String, Vec<String>)> {
let typed = keys
.iter()
.zip(values)
.filter_map(|(key, value)| Some((value.clone()?, key.value_type()?)))
.chain(uuid_position.map(|p| (p.to_string(), "uuid".to_string())));
let mut checks = Vec::new();
let mut params = Vec::new();
for (value, ty) in typed {
params.push(value);
params.push(ty);
checks.push(format!(
"pg_input_is_valid(${}::text, ${}::text)",
params.len() - 1,
params.len()
));
}
if checks.is_empty() {
return None;
}
Some((format!("SELECT ARRAY[{}] AS valid", checks.join(", ")), params))
}
pub fn keyset_keys(order_by: Option<&[OrderByClause]>) -> crate::Result<Vec<KeysetKey>> {
crate::order_by::refuse_relevance_under_cursor_pagination(order_by)?;
order_by
.unwrap_or_default()
.iter()
.map(|clause| {
let expr = crate::order_by::sort_expr(clause, DatabaseType::PostgreSQL)?;
let cast = if clause.vector.is_some() {
Cast::Float
} else if clause.localized.is_some() {
Cast::Text
} else if let (Some(_), Some(native)) = (&clause.native_column, &clause.native_type) {
Cast::Native(native.clone())
} else {
Cast::Scalar(clause.field_type)
};
let seekable = matches!(cast, Cast::Native(_)) && clause.native_not_null;
Ok(KeysetKey {
expr,
direction: clause.direction,
cast,
seekable,
})
})
.collect()
}
#[must_use]
pub fn keyset_signature(keys: &[KeysetKey]) -> String {
keys.iter()
.map(|key| {
let direction = match key.direction {
OrderDirection::Asc => "ASC",
OrderDirection::Desc => "DESC",
};
format!("{} {direction}", key.expr)
})
.collect::<Vec<_>>()
.join(", ")
}
pub fn keyset_predicate(
keys: &[KeysetKey],
values: &[Option<String>],
position: &str,
position_param: impl Fn(&str) -> String,
forward: bool,
first_param: usize,
) -> crate::Result<(String, Vec<String>, usize)> {
if keys.len() != values.len() {
return Err(fraiseql_error::FraiseQLError::validation(format!(
"the cursor carries {} sort key(s), and the ordering has {}",
values.len(),
keys.len()
)));
}
let dialect = PostgresDialect;
if let Some(seek) =
row_comparison(keys, values, position, &position_param, forward, first_param)
{
return Ok(seek);
}
let mut params = Vec::new();
let mut disjuncts = Vec::new();
let mut equal_so_far: Vec<String> = Vec::new();
for (key, value) in keys.iter().zip(values) {
let expr = &key.expr;
let bound = value.as_ref().map(|v| {
params.push(v.clone());
key.param(&dialect.placeholder(first_param + params.len() - 1))
});
let ascending_page = matches!(key.direction, OrderDirection::Asc) == forward;
let beyond = match (&bound, ascending_page) {
(Some(v), true) => Some(format!("({expr} > {v} OR {expr} IS NULL)")),
(Some(v), false) => Some(format!("{expr} < {v}")),
(None, true) => None,
(None, false) => Some(format!("{expr} IS NOT NULL")),
};
if let Some(beyond) = beyond {
disjuncts.push(conjunction(&equal_so_far, beyond));
}
equal_so_far.push(match &bound {
Some(v) => format!("{expr} = {v}"),
None => format!("{expr} IS NULL"),
});
}
let position_index = first_param + params.len();
let comparison = if forward { ">" } else { "<" };
let position_value = position_param(&dialect.placeholder(position_index));
disjuncts.push(conjunction(&equal_so_far, format!("{position} {comparison} {position_value}")));
Ok((format!("({})", disjuncts.join(" OR ")), params, position_index))
}
fn row_comparison(
keys: &[KeysetKey],
values: &[Option<String>],
position: &str,
position_param: &impl Fn(&str) -> String,
forward: bool,
first_param: usize,
) -> Option<(String, Vec<String>, usize)> {
let seekable = !keys.is_empty()
&& keys
.iter()
.all(|key| key.seekable && matches!(key.direction, OrderDirection::Asc));
if !seekable {
return None;
}
let values: Vec<&String> = values.iter().map(Option::as_ref).collect::<Option<_>>()?;
let dialect = PostgresDialect;
let mut left: Vec<&str> = keys.iter().map(|key| key.expr.as_str()).collect();
left.push(position);
let mut right: Vec<String> = keys
.iter()
.enumerate()
.map(|(i, key)| key.param(&dialect.placeholder(first_param + i)))
.collect();
let position_index = first_param + keys.len();
right.push(position_param(&dialect.placeholder(position_index)));
let comparison = if forward { ">" } else { "<" };
let params = values.into_iter().cloned().collect();
Some((
format!("(({}) {comparison} ({}))", left.join(", "), right.join(", ")),
params,
position_index,
))
}
fn conjunction(prefix: &[String], last: String) -> String {
if prefix.is_empty() {
return last;
}
let mut terms = prefix.to_vec();
terms.push(last);
format!("({})", terms.join(" AND "))
}
#[must_use]
pub fn keyset_order(keys: &[KeysetKey], position: &str, forward: bool) -> String {
let mut terms: Vec<String> = keys
.iter()
.map(|key| {
let direction = match (key.direction, forward) {
(OrderDirection::Asc, true) | (OrderDirection::Desc, false) => "ASC",
_ => "DESC",
};
format!("{} {direction}", key.expr)
})
.collect();
terms.push(format!("{position} {}", if forward { "ASC" } else { "DESC" }));
terms.join(", ")
}
#[must_use]
pub fn carried_keys(keys: &[KeysetKey], prefix: &str, subquery: &str) -> (String, Vec<KeysetKey>) {
let mut select = String::new();
let carried = keys
.iter()
.enumerate()
.map(|(i, key)| {
let _ = write!(select, ", {} AS {prefix}{i}", key.expr);
KeysetKey {
expr: format!("{subquery}.{prefix}{i}"),
..key.clone()
}
})
.collect();
(select, carried)
}
#[cfg(feature = "postgres")]
#[must_use]
pub fn position_param(
position: &crate::traits::CursorValue,
) -> (crate::types::QueryParam, fn(&str) -> String) {
use crate::{traits::CursorValue, types::QueryParam};
match position {
CursorValue::Int64(pk) => (QueryParam::BigInt(*pk), str::to_string),
CursorValue::Uuid(uuid) => (QueryParam::Text(uuid.clone()), |p| format!("{p}::text::uuid")),
}
}
#[cfg(test)]
mod tests;