sqlxo_traits/

core.rs

use smallvec::SmallVec;
use sqlx::{
	postgres::PgRow,
	prelude::Type,
	Postgres,
};

pub trait QueryModel =
	Send + Clone + Unpin + for<'r> sqlx::FromRow<'r, sqlx::postgres::PgRow>;

pub trait FilterQuery = Filterable + Clone;

pub trait QuerySort = Sortable + Clone;

pub trait Filterable {
	type Entity: QueryModel;

	fn write<W: SqlWrite>(&self, w: &mut W);
}

pub trait SqlWrite {
	fn push(&mut self, s: &str);

	fn bind<T>(&mut self, value: T)
	where
		T: sqlx::Encode<'static, Postgres> + Send + 'static,
		T: Type<Postgres>;
}

pub trait QueryContext: Send + Sync + 'static {
	const TABLE: &'static str;

	type Model: QueryModel
		+ Send
		+ Sync
		+ JoinNavigationModel
		+ WebJoinGraph
		+ PrimaryKey;
	type Query: FilterQuery + Send + Sync;
	type Sort: QuerySort + Send + Sync;
	type Join: SqlJoin + Send + Sync;
}

pub trait Sortable {
	type Entity: QueryModel;

	fn sort_clause(&self) -> String;
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum JoinKind {
	Left,
	Inner,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RelationFetchMode {
	Eager,
	Lazy,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct JoinThroughDescriptor {
	pub table:         &'static str,
	pub alias_segment: &'static str,
	pub left_field:    &'static str,
	pub right_field:   &'static str,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct JoinDescriptor {
	pub left_table:    &'static str,
	pub left_field:    &'static str,
	pub right_table:   &'static str,
	pub right_field:   &'static str,
	pub alias_segment: &'static str,
	pub identifier:    &'static str,
	pub through:       Option<JoinThroughDescriptor>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct JoinSegment {
	pub descriptor: JoinDescriptor,
	pub kind:       JoinKind,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct JoinPath {
	segments: Vec<JoinSegment>,
	start:    usize,
}

impl JoinPath {
	pub fn from_join<J: SqlJoin>(join: J, kind: JoinKind) -> Self {
		Self::new(join.descriptor(), kind)
	}

	pub fn new(descriptor: JoinDescriptor, kind: JoinKind) -> Self {
		Self {
			segments: vec![JoinSegment { descriptor, kind }],
			start:    0,
		}
	}

	pub fn then<J: SqlJoin>(mut self, join: J, kind: JoinKind) -> Self {
		let descriptor = join.descriptor();

		if let Some(prev) = self.segments.last() {
			assert_eq!(
				prev.descriptor.right_table, descriptor.left_table,
				"Invalid join path: expected next hop to start at `{}` but \
				 found `{}`",
				prev.descriptor.right_table, descriptor.left_table,
			);
		}

		self.segments.push(JoinSegment { descriptor, kind });
		self
	}

	pub fn segments(&self) -> &[JoinSegment] {
		&self.segments[self.start..]
	}

	pub fn len(&self) -> usize {
		self.segments().len()
	}

	pub fn append(&mut self, tail: &JoinPath) {
		if tail.is_empty() {
			return;
		}

		let Some(last) = self.segments().last() else {
			return;
		};
		let Some(first) = tail.segments().first() else {
			return;
		};

		assert_eq!(
			last.descriptor.right_table, first.descriptor.left_table,
			"Invalid join append: left table `{}` does not match `{}`",
			last.descriptor.right_table, first.descriptor.left_table,
		);

		self.segments.extend_from_slice(tail.segments());
	}

	pub fn strip_prefix(&self, len: usize) -> Option<Self> {
		let new_start = self.start + len;
		if new_start > self.segments.len() {
			return None;
		}

		Some(Self {
			segments: self.segments.clone(),
			start:    new_start,
		})
	}

	pub fn tail(&self) -> Option<Self> {
		if self.segments.len() - self.start <= 1 {
			None
		} else {
			Some(Self {
				segments: self.segments.clone(),
				start:    self.start + 1,
			})
		}
	}

	pub fn is_empty(&self) -> bool {
		self.len() == 0
	}

	pub fn first_table(&self) -> Option<&'static str> {
		self.segments().first().map(|seg| seg.descriptor.left_table)
	}

	pub fn alias(&self) -> String {
		self.alias_prefix(self.len())
	}

	pub fn alias_prefix(&self, len: usize) -> String {
		assert!(len <= self.len());
		let mut alias = String::new();
		let end = self.start + len;
		for segment in &self.segments[..end] {
			alias.push_str(segment.descriptor.alias_segment);
		}
		alias
	}
}

pub trait SqlJoin {
	fn descriptor(&self) -> JoinDescriptor;
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AliasedColumn {
	pub table_alias: String,
	pub column:      &'static str,
	pub alias:       String,
}

impl AliasedColumn {
	pub fn new(
		table_alias: impl Into<String>,
		column: &'static str,
		alias: impl Into<String>,
	) -> Self {
		Self {
			table_alias: table_alias.into(),
			column,
			alias: alias.into(),
		}
	}
}

#[derive(PartialEq, Default, Eq)]
pub enum Relation<T> {
	#[default]
	NotLoaded,
	Missing,
	Loaded(T),
}

impl<T: Clone> Clone for Relation<T> {
	fn clone(&self) -> Self {
		match self {
			Self::NotLoaded => Self::NotLoaded,
			Self::Missing => Self::Missing,
			Self::Loaded(v) => Self::Loaded(v.clone()),
		}
	}
}

impl<T: std::fmt::Debug> std::fmt::Debug for Relation<T> {
	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
		match self {
			Self::NotLoaded => f.write_str("Relation::NotLoaded"),
			Self::Missing => f.write_str("Relation::Missing"),
			Self::Loaded(v) => {
				f.debug_tuple("Relation::Loaded").field(v).finish()
			}
		}
	}
}

impl<T> Relation<T> {
	pub fn is_loaded(&self) -> bool {
		!self.is_not_loaded()
	}

	pub fn is_not_loaded(&self) -> bool {
		matches!(self, Self::NotLoaded)
	}

	pub fn is_missing(&self) -> bool {
		matches!(self, Self::Missing)
	}

	pub fn is_present(&self) -> bool {
		matches!(self, Self::Loaded(_))
	}

	pub fn is_some(&self) -> bool {
		self.is_present()
	}

	pub fn is_none(&self) -> bool {
		!self.is_some()
	}

	pub fn as_ref(&self) -> Relation<&T> {
		match self {
			Self::NotLoaded => Relation::NotLoaded,
			Self::Missing => Relation::Missing,
			Self::Loaded(value) => Relation::Loaded(value),
		}
	}

	pub fn as_mut(&mut self) -> Relation<&mut T> {
		match self {
			Self::NotLoaded => Relation::NotLoaded,
			Self::Missing => Relation::Missing,
			Self::Loaded(value) => Relation::Loaded(value),
		}
	}

	pub fn as_option(&self) -> Option<&T> {
		match self {
			Self::Loaded(value) => Some(value),
			Self::NotLoaded | Self::Missing => None,
		}
	}

	pub fn as_option_mut(&mut self) -> Option<&mut T> {
		match self {
			Self::Loaded(value) => Some(value),
			Self::NotLoaded | Self::Missing => None,
		}
	}

	pub fn into_option(self) -> Option<T> {
		match self {
			Self::Loaded(value) => Some(value),
			Self::NotLoaded | Self::Missing => None,
		}
	}

	pub fn map<U, F>(self, f: F) -> Relation<U>
	where
		F: FnOnce(T) -> U,
	{
		match self {
			Self::Loaded(value) => Relation::Loaded(f(value)),
			Self::NotLoaded => Relation::NotLoaded,
			Self::Missing => Relation::Missing,
		}
	}

	pub fn map_or<U, F>(self, default: U, f: F) -> U
	where
		F: FnOnce(T) -> U,
	{
		match self {
			Self::Loaded(value) => f(value),
			Self::NotLoaded | Self::Missing => default,
		}
	}

	pub fn map_or_else<U, D, F>(self, default: D, f: F) -> U
	where
		D: FnOnce() -> U,
		F: FnOnce(T) -> U,
	{
		match self {
			Self::Loaded(value) => f(value),
			Self::NotLoaded | Self::Missing => default(),
		}
	}

	pub fn ok_or<E>(self, err: E) -> Result<T, E> {
		match self {
			Self::Loaded(value) => Ok(value),
			Self::NotLoaded | Self::Missing => Err(err),
		}
	}

	pub fn ok_or_else<E, F>(self, err: F) -> Result<T, E>
	where
		F: FnOnce() -> E,
	{
		match self {
			Self::Loaded(value) => Ok(value),
			Self::NotLoaded | Self::Missing => Err(err()),
		}
	}

	pub fn unwrap(self) -> T {
		match self {
			Self::Loaded(value) => value,
			Self::NotLoaded => {
				panic!("called `Relation::unwrap()` on a `NotLoaded` relation")
			}
			Self::Missing => {
				panic!("called `Relation::unwrap()` on a `Missing` relation")
			}
		}
	}

	pub fn expect(self, msg: &str) -> T {
		match self {
			Self::Loaded(value) => value,
			Self::NotLoaded | Self::Missing => panic!("{msg}"),
		}
	}

	pub fn unwrap_or(self, default: T) -> T {
		match self {
			Self::Loaded(value) => value,
			Self::NotLoaded | Self::Missing => default,
		}
	}

	pub fn unwrap_or_else<F>(self, f: F) -> T
	where
		F: FnOnce() -> T,
	{
		match self {
			Self::Loaded(value) => value,
			Self::NotLoaded | Self::Missing => f(),
		}
	}

	pub fn unwrap_or_default(self) -> T
	where
		T: Default,
	{
		self.unwrap_or_else(T::default)
	}
}

pub type JoinValue<T> = Relation<T>;

pub fn merge_join_collections<T>(
	target: &mut Relation<Vec<T>>,
	incoming: Relation<Vec<T>>,
) where
	T: JoinIdentifiable,
{
	match target {
		Relation::NotLoaded => {
			*target = incoming;
		}
		Relation::Missing => {
			if let Relation::Loaded(values) = incoming {
				*target = Relation::Loaded(values);
			}
		}
		Relation::Loaded(existing) => {
			if let Relation::Loaded(mut values) = incoming {
				let mut keys: Vec<T::Key> =
					existing.iter().map(|item| item.join_key()).collect();
				for value in values.drain(..) {
					let key = value.join_key();
					if keys.iter().all(|existing_key| existing_key != &key) {
						keys.push(key);
						existing.push(value);
					}
				}
			}
		}
	}
}

pub trait JoinLoadable: Sized {
	fn project_join_columns(
		alias: &str,
		out: &mut SmallVec<[AliasedColumn; 4]>,
	);

	fn hydrate_from_join(
		row: &PgRow,
		alias: &str,
	) -> Result<Option<Self>, sqlx::Error>;
}

pub trait JoinIdentifiable {
	type Key: PartialEq;

	fn join_key(&self) -> Self::Key;
}

pub trait JoinNavigationModel {
	fn collect_join_columns(
		joins: Option<&[JoinPath]>,
		base_alias: &str,
	) -> SmallVec<[AliasedColumn; 4]>;

	fn hydrate_navigations(
		&mut self,
		joins: Option<&[JoinPath]>,
		row: &PgRow,
		base_alias: &str,
	) -> Result<(), sqlx::Error>;

	fn has_collection_joins(_joins: Option<&[JoinPath]>) -> bool {
		false
	}

	fn merge_collection_rows(
		rows: Vec<Self>,
		_joins: Option<&[JoinPath]>,
	) -> Vec<Self>
	where
		Self: Sized,
	{
		rows
	}

	fn relation_fetch_mode(_identifier: &str) -> Option<RelationFetchMode> {
		None
	}

	fn collect_default_join_paths(
		_include_lazy: bool,
		_visiting_tables: &mut Vec<&'static str>,
	) -> SmallVec<[JoinPath; 4]> {
		SmallVec::new()
	}

	fn default_join_paths(include_lazy: bool) -> SmallVec<[JoinPath; 4]>
	where
		Self: Sized,
	{
		let mut visiting_tables = Vec::new();
		Self::collect_default_join_paths(include_lazy, &mut visiting_tables)
	}
}

pub trait WebJoinGraph {
	fn resolve_join_path(segments: &[&str], kind: JoinKind)
		-> Option<JoinPath>;
}

pub trait PrimaryKey {
	const PRIMARY_KEY: &'static [&'static str];
}

pub trait Model {}

pub trait Deletable {
	const IS_SOFT_DELETE: bool;
	const DELETE_MARKER_FIELD: Option<&'static str>;
}

pub trait GetDeleteMarker {
	fn delete_marker_field() -> Option<&'static str>;
}

impl<T> GetDeleteMarker for T {
	default fn delete_marker_field() -> Option<&'static str> {
		None
	}
}

impl<T: Deletable> GetDeleteMarker for T {
	fn delete_marker_field() -> Option<&'static str> {
		T::DELETE_MARKER_FIELD
	}
}

pub trait Updatable {
	type UpdateModel: UpdateModel<Entity = Self>;
	const UPDATE_MARKER_FIELD: Option<&'static str>;
}

pub trait UpdateModel: Clone + Send + Sync {
	type Entity: QueryModel;

	fn apply_updates(
		&self,
		qb: &mut sqlx::QueryBuilder<'static, sqlx::Postgres>,
		has_previous: bool,
	) -> Vec<&'static str>;

	fn append_relation_ctes(
		&self,
		_qb: &mut sqlx::QueryBuilder<'static, sqlx::Postgres>,
		_affected_alias: &str,
	) {
	}

	fn append_relation_dependency_columns(
		&self,
		_qb: &mut sqlx::QueryBuilder<'static, sqlx::Postgres>,
	) {
	}

	fn apply_relation_payload(&self, _entity: &mut Self::Entity) {}
}

pub trait Creatable {
	type CreateModel: CreateModel<Entity = Self>;
	const INSERT_MARKER_FIELD: Option<&'static str>;
}

pub trait CreateModel: Clone + Send + Sync {
	type Entity: QueryModel;

	fn apply_inserts(
		&self,
		qb: &mut sqlx::QueryBuilder<'static, sqlx::Postgres>,
		insert_marker_field: Option<&'static str>,
	);

	fn append_relation_ctes(
		&self,
		_qb: &mut sqlx::QueryBuilder<'static, sqlx::Postgres>,
		_affected_alias: &str,
	) {
	}

	fn append_relation_dependency_columns(
		&self,
		_qb: &mut sqlx::QueryBuilder<'static, sqlx::Postgres>,
	) {
	}

	fn apply_relation_payload(&self, _entity: &mut Self::Entity) {}
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum SearchWeight {
	#[default]
	A,
	B,
	C,
	D,
}

impl SearchWeight {
	pub fn to_char(self) -> char {
		match self {
			Self::A => 'A',
			Self::B => 'B',
			Self::C => 'C',
			Self::D => 'D',
		}
	}

	pub fn sql_literal(self) -> &'static str {
		match self {
			Self::A => "'A'",
			Self::B => "'B'",
			Self::C => "'C'",
			Self::D => "'D'",
		}
	}
}

pub trait FullTextSearchConfig {
	fn include_rank(&self) -> bool;

	fn fuzzy_threshold(&self) -> Option<f64> {
		None
	}

	fn fuzzy_tokens(&self) -> Option<&[String]> {
		None
	}

	fn min_term_match_ratio(&self) -> f64 {
		0.5
	}
}

pub trait FullTextSearchConfigBuilder: FullTextSearchConfig {
	fn new_with_query(query: String) -> Self;
	fn apply_language(self, language: Option<String>) -> Self;
	fn apply_rank(self, include_rank: Option<bool>) -> Self;

	fn apply_fuzzy(self, _enable_fuzzy: Option<bool>) -> Self
	where
		Self: Sized,
	{
		self
	}

	fn apply_fuzzy_threshold(self, _threshold: Option<f64>) -> Self
	where
		Self: Sized,
	{
		self
	}
}

pub trait FullTextSearchJoinConfig {
	type Join;

	fn with_join(self, join: Self::Join) -> Self;
}

pub trait FullTextSearchable: Sized {
	type FullTextSearchField: Copy + Eq;
	type FullTextSearchConfig: FullTextSearchConfig + Send + Sync;
	type FullTextSearchJoin: Copy + Eq;

	fn write_tsvector<W>(
		w: &mut W,
		base_alias: &str,
		joins: Option<&[JoinPath]>,
		config: &Self::FullTextSearchConfig,
	) where
		W: SqlWrite;

	fn write_tsquery<W>(w: &mut W, config: &Self::FullTextSearchConfig)
	where
		W: SqlWrite;

	fn write_rank<W>(
		w: &mut W,
		base_alias: &str,
		joins: Option<&[JoinPath]>,
		config: &Self::FullTextSearchConfig,
	) where
		W: SqlWrite;

	fn write_fuzzy<W>(
		w: &mut W,
		base_alias: &str,
		joins: Option<&[JoinPath]>,
		config: &Self::FullTextSearchConfig,
	) where
		W: SqlWrite,
	{
		let _ = (base_alias, joins, config);
		w.push("FALSE");
	}

	fn write_search_document<W>(
		w: &mut W,
		base_alias: &str,
		joins: Option<&[JoinPath]>,
		config: &Self::FullTextSearchConfig,
	) where
		W: SqlWrite,
	{
		let _ = (base_alias, joins, config);
		w.push("''");
	}

	fn write_search_predicate<W>(
		w: &mut W,
		base_alias: &str,
		joins: Option<&[JoinPath]>,
		config: &Self::FullTextSearchConfig,
	) where
		W: SqlWrite,
	{
		w.push("(");
		w.push("(");
		Self::write_tsvector(w, base_alias, joins, config);
		w.push(") @@ (");
		Self::write_tsquery(w, config);
		w.push(")");
		if config.fuzzy_threshold().is_some() &&
			config
				.fuzzy_tokens()
				.map(|tokens| !tokens.is_empty())
				.unwrap_or(false)
		{
			w.push(" OR ");
			Self::write_fuzzy(w, base_alias, joins, config);
		}
		w.push(")");
	}

	fn write_search_score<W>(
		w: &mut W,
		base_alias: &str,
		joins: Option<&[JoinPath]>,
		config: &Self::FullTextSearchConfig,
	) where
		W: SqlWrite,
	{
		Self::write_rank(w, base_alias, joins, config);
	}

	fn resolve_search_join_path(
		_segments: &[&str],
	) -> Option<Self::FullTextSearchJoin> {
		None
	}
}

#[cfg(test)]
mod tests {
	use super::Relation;

	#[test]
	fn relation_state_helpers_work() {
		let not_loaded = Relation::<i32>::NotLoaded;
		let missing = Relation::<i32>::Missing;
		let loaded = Relation::Loaded(42);

		assert!(not_loaded.is_not_loaded());
		assert!(not_loaded.is_none());
		assert!(!not_loaded.is_loaded());
		assert!(!not_loaded.is_some());
		assert!(!not_loaded.is_missing());
		assert!(!not_loaded.is_present());

		assert!(missing.is_loaded());
		assert!(missing.is_missing());
		assert!(missing.is_none());
		assert!(!missing.is_some());
		assert!(!missing.is_not_loaded());

		assert!(loaded.is_loaded());
		assert!(loaded.is_present());
		assert!(loaded.is_some());
		assert!(!loaded.is_none());
		assert!(!loaded.is_missing());
	}

	#[test]
	fn relation_option_like_helpers_work() {
		assert_eq!(Relation::Loaded(7).unwrap_or(1), 7);
		assert_eq!(Relation::<i32>::NotLoaded.unwrap_or(1), 1);
		assert_eq!(Relation::<i32>::Missing.unwrap_or(1), 1);

		assert_eq!(Relation::Loaded(7).map(|v| v * 2), Relation::Loaded(14));
		assert_eq!(
			Relation::<i32>::NotLoaded.map(|v| v * 2),
			Relation::NotLoaded
		);

		assert_eq!(Relation::Loaded(7).map_or(3, |v| v * 2), 14);
		assert_eq!(Relation::<i32>::Missing.map_or(3, |v| v * 2), 3);
		assert_eq!(Relation::Loaded(7).ok_or("missing relation"), Ok(7));
		assert_eq!(
			Relation::<i32>::NotLoaded.ok_or("missing relation"),
			Err("missing relation")
		);
	}
}