Skip to main content

che_orm/
query.rs

1use std::collections::HashSet;
2use std::marker::PhantomData;
3
4use crate::{
5    ColumnRef, CompareOp, CreateTableQuery, DatabaseValue, Expr, ModelField, QueryValue, TableRef,
6    TableSchema,
7};
8
9#[derive(Debug, Clone, Copy)]
10pub enum OrderDirection {
11    Asc,
12    Desc,
13}
14
15#[derive(Debug, Clone, Copy)]
16pub struct OrderBy {
17    pub column: ColumnRef,
18    pub direction: OrderDirection,
19}
20
21#[derive(Debug, Clone, Copy)]
22pub struct JoinedField<T> {
23    column: ColumnRef,
24    _marker: PhantomData<T>,
25}
26
27impl<T> JoinedField<T> {
28    pub const fn new(column: ColumnRef) -> Self {
29        Self {
30            column,
31            _marker: PhantomData,
32        }
33    }
34
35    fn comparison<V>(self, op: CompareOp, value: V) -> Expr
36    where
37        V: QueryValue<T>,
38    {
39        Expr::Compare {
40            left: Box::new(Expr::Column(self.column)),
41            op,
42            right: Box::new(Expr::Value(value.into_query_value())),
43        }
44    }
45
46    pub fn eq<V>(self, value: V) -> Expr
47    where
48        V: QueryValue<T>,
49    {
50        self.comparison(CompareOp::Eq, value)
51    }
52
53    pub fn ne<V>(self, value: V) -> Expr
54    where
55        V: QueryValue<T>,
56    {
57        self.comparison(CompareOp::Ne, value)
58    }
59
60    pub fn gt<V>(self, value: V) -> Expr
61    where
62        V: QueryValue<T>,
63    {
64        self.comparison(CompareOp::Gt, value)
65    }
66
67    pub fn gte<V>(self, value: V) -> Expr
68    where
69        V: QueryValue<T>,
70    {
71        self.comparison(CompareOp::Gte, value)
72    }
73
74    pub fn lt<V>(self, value: V) -> Expr
75    where
76        V: QueryValue<T>,
77    {
78        self.comparison(CompareOp::Lt, value)
79    }
80
81    pub fn lte<V>(self, value: V) -> Expr
82    where
83        V: QueryValue<T>,
84    {
85        self.comparison(CompareOp::Lte, value)
86    }
87
88    pub fn is_null(self) -> Expr {
89        Expr::IsNull(Box::new(Expr::Column(self.column)))
90    }
91
92    pub fn is_not_null(self) -> Expr {
93        Expr::IsNotNull(Box::new(Expr::Column(self.column)))
94    }
95
96    pub const fn asc(self) -> OrderBy {
97        OrderBy {
98            column: self.column,
99            direction: OrderDirection::Asc,
100        }
101    }
102
103    pub const fn desc(self) -> OrderBy {
104        OrderBy {
105            column: self.column,
106            direction: OrderDirection::Desc,
107        }
108    }
109}
110
111#[derive(Debug, Clone)]
112pub struct SelectAst {
113    pub table: TableRef,
114    pub columns: Vec<ColumnRef>,
115    pub joins: Vec<JoinAst>,
116    pub filter: Option<Expr>,
117    pub order_by: Vec<OrderBy>,
118    pub limit: Option<u64>,
119    pub offset: Option<u64>,
120}
121
122#[derive(Debug, Clone)]
123pub struct JoinAst {
124    pub table: TableRef,
125    pub alias: &'static str,
126    pub kind: JoinType,
127    pub on: Expr,
128}
129
130#[derive(Debug, Clone, Copy)]
131pub enum JoinType {
132    Inner,
133    Left,
134}
135
136#[derive(Debug, Clone)]
137pub struct InsertValue {
138    pub column: ColumnRef,
139    pub value: DatabaseValue,
140}
141
142#[derive(Debug, Clone)]
143pub struct InsertAst {
144    pub table: TableRef,
145    pub values: Vec<InsertValue>,
146    pub returning: Vec<ColumnRef>,
147}
148
149#[derive(Debug, Clone)]
150pub struct Assignment {
151    pub column: ColumnRef,
152    pub value: DatabaseValue,
153}
154
155#[derive(Debug, Clone)]
156pub struct UpdateAst {
157    pub table: TableRef,
158    pub assignments: Vec<Assignment>,
159    pub filter: Option<Expr>,
160    pub returning: Vec<ColumnRef>,
161    pub allow_all: bool,
162}
163
164#[derive(Debug, Clone)]
165pub struct DeleteAst {
166    pub table: TableRef,
167    pub filter: Option<Expr>,
168    pub allow_all: bool,
169}
170
171#[derive(Debug, Clone)]
172pub enum QueryAst {
173    Select(SelectAst),
174    Insert(InsertAst),
175    Update(UpdateAst),
176    Delete(DeleteAst),
177    CreateTable(crate::CreateTableAst),
178}
179
180#[derive(Debug, Clone, PartialEq, Eq)]
181/// Errors detected while finalizing a query builder.
182pub enum QueryBuildError {
183    EmptyInsert,
184    EmptyUpdate,
185    PrimaryKeyUpdate,
186    MissingFilter,
187    DuplicateColumn(&'static str),
188    ForeignTableColumn {
189        column: &'static str,
190        table: &'static str,
191        expected_table: &'static str,
192    },
193    InvalidSchema(String),
194}
195
196impl QueryAst {
197    /// Validates a query before it is sent to a database.
198    pub fn validate(&self) -> Result<(), QueryBuildError> {
199        match self {
200            Self::Select(query) => {
201                validate_expr_table(query.filter.as_ref(), query.table.name)?;
202                validate_columns_table(
203                    query.table.name,
204                    query.order_by.iter().map(|order| &order.column),
205                )
206            }
207            Self::Insert(query) => {
208                validate_unique_columns(query.values.iter().map(|value| &value.column))?;
209                validate_columns_table(
210                    query.table.name,
211                    query.values.iter().map(|value| &value.column),
212                )
213            }
214            Self::Update(query) => {
215                if query.assignments.is_empty() {
216                    return Err(QueryBuildError::EmptyUpdate);
217                }
218                if query.filter.is_none() && !query.allow_all {
219                    return Err(QueryBuildError::MissingFilter);
220                }
221                validate_unique_columns(
222                    query
223                        .assignments
224                        .iter()
225                        .map(|assignment| &assignment.column),
226                )?;
227                validate_columns_table(
228                    query.table.name,
229                    query
230                        .assignments
231                        .iter()
232                        .map(|assignment| &assignment.column),
233                )?;
234                validate_expr_table(query.filter.as_ref(), query.table.name)
235            }
236            Self::Delete(query) => {
237                if query.filter.is_none() && !query.allow_all {
238                    return Err(QueryBuildError::MissingFilter);
239                }
240                validate_expr_table(query.filter.as_ref(), query.table.name)
241            }
242            Self::CreateTable(query) => query
243                .schema
244                .validate()
245                .map_err(|error| QueryBuildError::InvalidSchema(format!("{error:?}"))),
246        }
247    }
248}
249
250/// Trait implemented by `#[derive(Model)]` for ORM models.
251pub trait Model: Sized {
252    /// Stable Rust model name used by migration state. It is deliberately
253    /// independent from `table_name()` so table renames keep model identity.
254    fn model_name() -> &'static str {
255        std::any::type_name::<Self>()
256            .rsplit("::")
257            .next()
258            .unwrap_or("Model")
259    }
260    fn table_name() -> &'static str;
261    fn columns() -> &'static [&'static str];
262    /// Returns the model's generated integer primary-key field.
263    fn primary_key() -> ModelField<Self, i64>;
264    fn primary_key_value(&self) -> i64 {
265        panic!("Model::primary_key_value must be implemented for eager relations")
266    }
267    fn schema() -> TableSchema;
268    fn from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<Self>;
269    fn from_row_at(row: &rusqlite::Row<'_>, offset: usize) -> rusqlite::Result<Self> {
270        if offset == 0 {
271            Self::from_row(row)
272        } else {
273            Err(rusqlite::Error::InvalidColumnIndex(offset))
274        }
275    }
276    fn insert_values(&self) -> Vec<InsertValue>;
277    fn managed_update_values() -> Vec<Assignment> {
278        Vec::new()
279    }
280    fn query() -> SelectQuery<Self> {
281        SelectQuery::new()
282    }
283    fn insert() -> InsertQuery<Self> {
284        InsertQuery::new()
285    }
286    fn update() -> UpdateQuery<Self> {
287        UpdateQuery::new()
288    }
289    fn delete() -> DeleteQuery<Self> {
290        DeleteQuery::new()
291    }
292    fn create_table() -> CreateTableQuery<Self> {
293        CreateTableQuery::new(Self::schema())
294    }
295}
296
297/// Converts a materialized ORM model into an API representation.
298pub trait ModelSerializer: serde::Serialize + Sized {
299    type Model: Model;
300    type Input;
301
302    fn from_input(input: Self::Input) -> Self;
303
304    fn to_json(input: Self::Input) -> Result<serde_json::Value, serde_json::Error> {
305        serde_json::to_value(Self::from_input(input))
306    }
307
308    fn fields() -> &'static [SerializerField] {
309        &[]
310    }
311}
312
313/// Identifies the actual foreign-key column behind a serializer relation.
314pub trait RelationSource {
315    const SOURCE: &'static str;
316}
317
318#[derive(Debug, Clone, Copy, PartialEq, Eq)]
319pub struct SerializerField {
320    pub name: &'static str,
321    pub source: &'static str,
322    pub read_only: bool,
323    pub write_only: bool,
324    pub rust_type: &'static str,
325    pub related_model: Option<&'static str>,
326    pub many: bool,
327}
328
329/// A typed forward foreign-key relation from one model to another.
330#[derive(Debug, Clone, Copy)]
331pub struct BelongsTo<From, To, Relation = (), Key = i64> {
332    field: ColumnRef,
333    getter: fn(&From) -> Key,
334    alias: &'static str,
335    related_name: &'static str,
336    _marker: PhantomData<fn() -> (From, To, Relation, Key)>,
337}
338
339impl<From, To, Relation, Key> BelongsTo<From, To, Relation, Key> {
340    pub const fn new(
341        table: &'static str,
342        column: &'static str,
343        getter: fn(&From) -> Key,
344        alias: &'static str,
345        related_name: &'static str,
346    ) -> Self {
347        Self {
348            field: ColumnRef::new(table, column),
349            getter,
350            alias,
351            related_name,
352            _marker: PhantomData,
353        }
354    }
355
356    pub const fn field(&self) -> ColumnRef {
357        self.field
358    }
359
360    pub const fn alias(&self) -> &'static str {
361        self.alias
362    }
363
364    pub const fn related_field<T>(&self, field: ModelField<To, T>) -> JoinedField<T> {
365        JoinedField::new(ColumnRef::new(self.alias, field.column().name))
366    }
367
368    pub fn foreign_key(&self, model: &From) -> Key {
369        (self.getter)(model)
370    }
371
372    pub const fn reverse(&self) -> HasMany<To, From, Relation, Key> {
373        HasMany {
374            field: self.field,
375            getter: self.getter,
376            related_name: self.related_name,
377            _marker: PhantomData,
378        }
379    }
380}
381
382/// A typed reverse foreign-key relation from one model to many related models.
383#[derive(Debug, Clone, Copy)]
384pub struct HasMany<From, To, Relation = (), Key = i64> {
385    field: ColumnRef,
386    getter: fn(&To) -> Key,
387    related_name: &'static str,
388    _marker: PhantomData<fn() -> (From, To, Relation, Key)>,
389}
390
391impl<From, To, Relation, Key> HasMany<From, To, Relation, Key> {
392    pub const fn field(&self) -> ColumnRef {
393        self.field
394    }
395
396    pub fn foreign_key(&self, model: &To) -> Key {
397        (self.getter)(model)
398    }
399
400    pub const fn related_name(&self) -> &'static str {
401        self.related_name
402    }
403}
404
405pub struct SelectQuery<M> {
406    ast: SelectAst,
407    _model: PhantomData<M>,
408}
409
410impl<M: Model> SelectQuery<M> {
411    pub fn new() -> Self {
412        let table = M::table_name();
413        let columns = M::columns()
414            .iter()
415            .map(|column| ColumnRef::new(table, column))
416            .collect();
417        Self {
418            ast: SelectAst {
419                table: TableRef::new(table),
420                columns,
421                joins: Vec::new(),
422                filter: None,
423                order_by: Vec::new(),
424                limit: None,
425                offset: None,
426            },
427            _model: PhantomData,
428        }
429    }
430    pub fn filter(mut self, expr: Expr) -> Self {
431        self.ast.filter = Some(
432            self.ast
433                .filter
434                .map_or(expr.clone(), |previous| previous.and(expr)),
435        );
436        self
437    }
438    pub fn order_by(mut self, order: OrderBy) -> Self {
439        self.ast.order_by.push(order);
440        self
441    }
442    pub fn limit(mut self, limit: u64) -> Self {
443        self.ast.limit = Some(limit);
444        self
445    }
446    pub fn offset(mut self, offset: u64) -> Self {
447        self.ast.offset = Some(offset);
448        self
449    }
450    pub fn into_ast(self) -> Result<QueryAst, QueryBuildError> {
451        let mut tables = vec![self.ast.table.name];
452        for join in &self.ast.joins {
453            tables.push(join.table.name);
454            tables.push(join.alias);
455        }
456        validate_expr_tables(self.ast.filter.as_ref(), &tables)?;
457        for join in &self.ast.joins {
458            validate_expr_tables(Some(&join.on), &tables)?;
459        }
460        Ok(QueryAst::Select(self.ast))
461    }
462
463    #[cfg(feature = "sqlite")]
464    pub(crate) fn into_select_ast(self) -> Result<SelectAst, QueryBuildError> {
465        match self.into_ast()? {
466            QueryAst::Select(select) => Ok(select),
467            _ => unreachable!(),
468        }
469    }
470
471    pub fn into_joined_ast<R: Model, Relation>(
472        self,
473        relation: BelongsTo<M, R, Relation>,
474    ) -> Result<QueryAst, QueryBuildError> {
475        self.into_joined_ast_with_kind(relation, JoinType::Inner)
476    }
477
478    pub fn into_optional_joined_ast<R: Model, Relation>(
479        self,
480        relation: BelongsTo<M, R, Relation, Option<i64>>,
481    ) -> Result<QueryAst, QueryBuildError> {
482        self.into_joined_ast_with_kind(relation, JoinType::Left)
483    }
484
485    fn into_joined_ast_with_kind<R: Model, Relation, Key>(
486        mut self,
487        relation: BelongsTo<M, R, Relation, Key>,
488        kind: JoinType,
489    ) -> Result<QueryAst, QueryBuildError> {
490        self.ast.columns.extend(
491            R::columns()
492                .iter()
493                .map(|column| ColumnRef::new(relation.alias(), column)),
494        );
495        self.ast.joins.push(JoinAst {
496            table: TableRef::new(R::table_name()),
497            alias: relation.alias(),
498            kind,
499            on: Expr::Compare {
500                left: Box::new(Expr::Column(relation.field())),
501                op: CompareOp::Eq,
502                right: Box::new(Expr::Column(ColumnRef::new(
503                    relation.alias(),
504                    R::primary_key().column().name,
505                ))),
506            },
507        });
508        self.into_ast()
509    }
510}
511
512pub struct InsertQuery<M> {
513    ast: InsertAst,
514    _model: PhantomData<M>,
515}
516
517impl<M: Model> InsertQuery<M> {
518    pub fn new() -> Self {
519        Self {
520            ast: InsertAst {
521                table: TableRef::new(M::table_name()),
522                values: Vec::new(),
523                returning: Vec::new(),
524            },
525            _model: PhantomData,
526        }
527    }
528    pub fn set<T, V>(mut self, field: ModelField<M, T>, value: V) -> Self
529    where
530        V: QueryValue<T>,
531    {
532        self.ast.values.push(InsertValue {
533            column: field.column(),
534            value: value.into_query_value(),
535        });
536        self
537    }
538    pub fn returning_all(mut self) -> Self {
539        self.ast.returning = M::columns()
540            .iter()
541            .map(|column| ColumnRef::new(M::table_name(), column))
542            .collect();
543        self
544    }
545    pub fn into_ast(self) -> Result<QueryAst, QueryBuildError> {
546        validate_unique_columns(self.ast.values.iter().map(|value| &value.column))?;
547        Ok(QueryAst::Insert(self.ast))
548    }
549}
550
551pub struct UpdateQuery<M> {
552    ast: UpdateAst,
553    allow_all: bool,
554    _model: PhantomData<M>,
555}
556
557impl<M: Model> UpdateQuery<M> {
558    pub fn new() -> Self {
559        Self {
560            ast: UpdateAst {
561                table: TableRef::new(M::table_name()),
562                assignments: Vec::new(),
563                filter: None,
564                returning: Vec::new(),
565                allow_all: false,
566            },
567            allow_all: false,
568            _model: PhantomData,
569        }
570    }
571    pub fn set<T, V>(mut self, field: ModelField<M, T>, value: V) -> Self
572    where
573        V: QueryValue<T>,
574    {
575        self.ast.assignments.push(Assignment {
576            column: field.column(),
577            value: value.into_query_value(),
578        });
579        self
580    }
581    pub fn filter(mut self, expr: Expr) -> Self {
582        self.ast.filter = Some(
583            self.ast
584                .filter
585                .map_or(expr.clone(), |previous| previous.and(expr)),
586        );
587        self
588    }
589    pub fn returning_all(mut self) -> Self {
590        self.ast.returning = M::columns()
591            .iter()
592            .map(|column| ColumnRef::new(M::table_name(), column))
593            .collect();
594        self
595    }
596    pub fn allow_all(mut self) -> Self {
597        self.allow_all = true;
598        self
599    }
600    pub fn into_ast(mut self) -> Result<QueryAst, QueryBuildError> {
601        for managed in M::managed_update_values() {
602            self.ast
603                .assignments
604                .retain(|assignment| assignment.column.name != managed.column.name);
605            self.ast.assignments.push(managed);
606        }
607        if self.ast.assignments.is_empty() {
608            return Err(QueryBuildError::EmptyUpdate);
609        }
610        if self.ast.filter.is_none() && !self.allow_all {
611            return Err(QueryBuildError::MissingFilter);
612        }
613        let primary_key = M::primary_key().column();
614        if self
615            .ast
616            .assignments
617            .iter()
618            .any(|assignment| assignment.column == primary_key)
619        {
620            return Err(QueryBuildError::PrimaryKeyUpdate);
621        }
622        validate_unique_columns(
623            self.ast
624                .assignments
625                .iter()
626                .map(|assignment| &assignment.column),
627        )?;
628        validate_expr_table(self.ast.filter.as_ref(), self.ast.table.name)?;
629        self.ast.allow_all = self.allow_all;
630        Ok(QueryAst::Update(self.ast))
631    }
632}
633
634pub struct DeleteQuery<M> {
635    ast: DeleteAst,
636    allow_all: bool,
637    _model: PhantomData<M>,
638}
639
640impl<M: Model> DeleteQuery<M> {
641    pub fn new() -> Self {
642        Self {
643            ast: DeleteAst {
644                table: TableRef::new(M::table_name()),
645                filter: None,
646                allow_all: false,
647            },
648            allow_all: false,
649            _model: PhantomData,
650        }
651    }
652    pub fn filter(mut self, expr: Expr) -> Self {
653        self.ast.filter = Some(
654            self.ast
655                .filter
656                .map_or(expr.clone(), |previous| previous.and(expr)),
657        );
658        self
659    }
660    pub fn allow_all(mut self) -> Self {
661        self.allow_all = true;
662        self
663    }
664    pub fn into_ast(mut self) -> Result<QueryAst, QueryBuildError> {
665        if self.ast.filter.is_none() && !self.allow_all {
666            return Err(QueryBuildError::MissingFilter);
667        }
668        validate_expr_table(self.ast.filter.as_ref(), self.ast.table.name)?;
669        self.ast.allow_all = self.allow_all;
670        Ok(QueryAst::Delete(self.ast))
671    }
672}
673
674fn validate_unique_columns<'a>(
675    columns: impl Iterator<Item = &'a ColumnRef>,
676) -> Result<(), QueryBuildError> {
677    let mut names = HashSet::new();
678    for column in columns {
679        if !names.insert(column.name) {
680            return Err(QueryBuildError::DuplicateColumn(column.name));
681        }
682    }
683    Ok(())
684}
685
686fn validate_columns_table<'a>(
687    table: &'static str,
688    columns: impl Iterator<Item = &'a ColumnRef>,
689) -> Result<(), QueryBuildError> {
690    for column in columns {
691        validate_column_table(column, table)?;
692    }
693    Ok(())
694}
695
696fn validate_expr_table(expr: Option<&Expr>, table: &'static str) -> Result<(), QueryBuildError> {
697    let Some(expr) = expr else {
698        return Ok(());
699    };
700    match expr {
701        Expr::Column(column) => validate_column_table(column, table),
702        Expr::Value(_) => Ok(()),
703        Expr::Like { left, pattern } => {
704            validate_expr_table(Some(left), table)?;
705            validate_expr_table(Some(pattern), table)
706        }
707        Expr::Compare { left, right, .. }
708        | Expr::And { left, right }
709        | Expr::Or { left, right } => {
710            validate_expr_table(Some(left), table)?;
711            validate_expr_table(Some(right), table)
712        }
713        Expr::In { left, .. } => validate_expr_table(Some(left), table),
714        Expr::Not(expr) | Expr::IsNull(expr) | Expr::IsNotNull(expr) => {
715            validate_expr_table(Some(expr), table)
716        }
717    }
718}
719
720fn validate_column_table(column: &ColumnRef, table: &'static str) -> Result<(), QueryBuildError> {
721    if column.table == table {
722        Ok(())
723    } else {
724        Err(QueryBuildError::ForeignTableColumn {
725            column: column.name,
726            table: column.table,
727            expected_table: table,
728        })
729    }
730}
731
732fn validate_expr_tables(
733    expr: Option<&Expr>,
734    tables: &[&'static str],
735) -> Result<(), QueryBuildError> {
736    let Some(expr) = expr else {
737        return Ok(());
738    };
739    match expr {
740        Expr::Column(column) => {
741            if tables.contains(&column.table) {
742                Ok(())
743            } else {
744                Err(QueryBuildError::ForeignTableColumn {
745                    column: column.name,
746                    table: column.table,
747                    expected_table: tables[0],
748                })
749            }
750        }
751        Expr::Like { left, pattern } => {
752            validate_expr_tables(Some(left), tables)?;
753            validate_expr_tables(Some(pattern), tables)
754        }
755        Expr::Value(_) => Ok(()),
756        Expr::Compare { left, right, .. }
757        | Expr::And { left, right }
758        | Expr::Or { left, right } => {
759            validate_expr_tables(Some(left), tables)?;
760            validate_expr_tables(Some(right), tables)
761        }
762        Expr::In { left, .. } => validate_expr_tables(Some(left), tables),
763        Expr::Not(expr) | Expr::IsNull(expr) | Expr::IsNotNull(expr) => {
764            validate_expr_tables(Some(expr), tables)
765        }
766    }
767}