Skip to main content

rok_db_macros/
lib.rs

1//! Derive macros for [rok-db](https://docs.rs/rok-db). Use them through the
2//! `rok-db` crate rather than depending on this crate directly.
3
4use proc_macro::TokenStream;
5use proc_macro_crate::{FoundCrate, crate_name};
6use proc_macro2::{Span, TokenStream as TokenStream2};
7use quote::{format_ident, quote};
8use syn::{Data, DeriveInput, Fields, Ident, LitStr, Path, parse_macro_input, spanned::Spanned};
9
10/// Derive `rok_db::Model` (and `sqlx::FromRow`) for a struct with named fields.
11///
12/// # Container attributes
13///
14/// - `#[rok(table = "users")]` — table name, optionally schema-qualified.
15///   Defaults to the struct name in `snake_case`, pluralised
16///   (`User` → `users`, `BlogPost` → `blog_posts`, `Category` → `categories`).
17/// - `#[rok(timestamps)]` — the `created_at` and `updated_at` fields are
18///   managed automatically: both are set to `now()` on insert and
19///   `updated_at` on every update.
20/// - `#[rok(soft_delete)]` — the `deleted_at` field (an `Option` timestamp)
21///   marks deleted rows: `delete` sets it, queries skip such rows unless
22///   `with_trashed()`/`only_trashed()` is used, and `restore` clears it.
23/// - `#[rok(has_many(posts = Post::USER_ID))]` — a one-to-many relation:
24///   generates `User::POSTS` (a [`HasMany`]) and `user.posts()` (a query).
25/// - `#[rok(has_one(profile = Profile::USER_ID))]` — a one-to-one relation:
26///   generates `User::PROFILE` and `user.profile()`.
27/// - `#[rok(hooks)]` — you implement `rok_db::Hooks` yourself (otherwise a
28///   no-op implementation is generated).
29/// - `#[rok(validate_with = path::to::fn)]` — record-level validation,
30///   `fn(&Self) -> Result<(), ValidationErrors>`, run with the field rules.
31/// - `#[rok(default_scope = path::to::fn)]` — `fn() -> Expr<Self>` applied
32///   to every query; remove it with `.unscoped()`.
33/// - `#[rok(no_from_row)]` — don't generate `FromRow` (bring your own).
34/// - `#[rok(crate = "path::to::rok_db")]` — path of the `rok_db` crate when
35///   it is re-exported under another name.
36///
37/// # Field attributes
38///
39/// - `#[rok(primary_key)]` — the primary key. Defaults to the field named `id`.
40///   Mark several fields for a composite key (in field order); look records
41///   up with a tuple: `Membership::find(&db, (org_id, user_id))`.
42/// - `#[rok(generated)]` — filled in by the database (serial ids, defaults,
43///   triggers): read, but never written by `insert`/`save`.
44/// - `#[rok(column = "name")]` — column name, if it differs from the field.
45/// - `#[rok(skip)]` — not a column; initialised with `Default::default()`.
46/// - `#[rok(created_at)]` / `#[rok(updated_at)]` — managed timestamp column
47///   with a custom name (see `timestamps`).
48/// - `#[rok(deleted_at)]` — soft-delete column with a custom name.
49/// - `#[rok(tenant)]` — the tenant column for row-level multi-tenancy
50///   (see `rok_db::tenant`).
51/// - `#[rok(version)]` — optimistic-locking counter (an integer): every
52///   update increments it, and `save`/`delete` fail with a conflict error if
53///   it changed since the record was loaded.
54/// - `#[rok(validate(…))]` — validation rules checked before every insert
55///   and save: `length(min = 1, max = 50)`, `range(min = 0, max = 150)`,
56///   `email`, `non_empty`, `custom = path::to::fn` (`fn(&T) -> Result<(), String>`).
57///   Rules on `Option` fields apply only to `Some`.
58/// - `#[rok(belongs_to = User)]` on a foreign key field `user_id` — generates
59///   `Post::USER` (a [`BelongsTo`]) and `post.user()`. Use
60///   `#[rok(belongs_to(author = User))]` to pick the name.
61///
62/// [`HasMany`]: https://docs.rs/rok-db/latest/rok_db/struct.HasMany.html
63/// [`BelongsTo`]: https://docs.rs/rok-db/latest/rok_db/struct.BelongsTo.html
64///
65/// # Generated items
66///
67/// Besides the trait impls, one typed column constant is generated per
68/// column, named after the field in `SCREAMING_SNAKE_CASE`:
69///
70/// ```ignore
71/// #[derive(Model)]
72/// struct User { #[rok(primary_key, generated)] id: i64, email: String }
73///
74/// User::filter(User::EMAIL.eq("ann@example.com"))
75/// ```
76#[proc_macro_derive(Model, attributes(rok))]
77pub fn derive_model(input: TokenStream) -> TokenStream {
78    let input = parse_macro_input!(input as DeriveInput);
79    expand(input)
80        .unwrap_or_else(syn::Error::into_compile_error)
81        .into()
82}
83
84struct Field {
85    ident: Ident,
86    column: String,
87    primary_key: bool,
88    generated: bool,
89    skip: bool,
90    created_at: bool,
91    updated_at: bool,
92    deleted_at: bool,
93    version: bool,
94    tenant: bool,
95    belongs_to: Option<(Ident, Path)>,
96    rules: Vec<Rule>,
97}
98
99/// A `#[rok(validate(…))]` rule.
100enum Rule {
101    Length(Option<syn::Expr>, Option<syn::Expr>),
102    Range(Option<syn::Expr>, Option<syn::Expr>),
103    Email,
104    NonEmpty,
105    Custom(Path),
106}
107
108fn parse_bounds(
109    meta: &syn::meta::ParseNestedMeta<'_>,
110) -> syn::Result<(Option<syn::Expr>, Option<syn::Expr>)> {
111    let (mut min, mut max) = (None, None);
112    meta.parse_nested_meta(|b| {
113        if b.path.is_ident("min") {
114            min = Some(b.value()?.parse()?);
115        } else if b.path.is_ident("max") {
116            max = Some(b.value()?.parse()?);
117        } else {
118            return Err(b.error("expected `min` or `max`"));
119        }
120        Ok(())
121    })?;
122    if min.is_none() && max.is_none() {
123        return Err(meta.error("expected at least one of `min`, `max`"));
124    }
125    Ok((min, max))
126}
127
128fn parse_rules(meta: &syn::meta::ParseNestedMeta<'_>, rules: &mut Vec<Rule>) -> syn::Result<()> {
129    meta.parse_nested_meta(|r| {
130        if r.path.is_ident("length") {
131            let (min, max) = parse_bounds(&r)?;
132            rules.push(Rule::Length(min, max));
133        } else if r.path.is_ident("range") {
134            let (min, max) = parse_bounds(&r)?;
135            rules.push(Rule::Range(min, max));
136        } else if r.path.is_ident("email") {
137            rules.push(Rule::Email);
138        } else if r.path.is_ident("non_empty") {
139            rules.push(Rule::NonEmpty);
140        } else if r.path.is_ident("custom") {
141            rules.push(Rule::Custom(r.value()?.parse()?));
142        } else {
143            return Err(r.error(
144                "unknown rule; expected `length`, `range`, `email`, `non_empty` or `custom`",
145            ));
146        }
147        Ok(())
148    })
149}
150
151/// `has_many(name = Model::FK_COLUMN)` / `has_one(…)`.
152struct Relation {
153    kind: &'static str,
154    name: Ident,
155    model: Path,
156    foreign_key: Path,
157}
158
159fn parse_relations(
160    meta: &syn::meta::ParseNestedMeta<'_>,
161    kind: &'static str,
162    out: &mut Vec<Relation>,
163) -> syn::Result<()> {
164    meta.parse_nested_meta(|inner| {
165        let name = inner
166            .path
167            .get_ident()
168            .cloned()
169            .ok_or_else(|| inner.error("expected `name = Model::FOREIGN_KEY`"))?;
170        let foreign_key: Path = inner.value()?.parse()?;
171        let mut model = foreign_key.clone();
172        if model.segments.len() < 2 {
173            return Err(syn::Error::new(
174                foreign_key.span(),
175                "expected a column constant such as `Post::USER_ID`",
176            ));
177        }
178        model.segments.pop();
179        model.segments.pop_punct();
180        out.push(Relation {
181            kind,
182            name,
183            model,
184            foreign_key,
185        });
186        Ok(())
187    })
188}
189
190fn expand(input: DeriveInput) -> syn::Result<TokenStream2> {
191    let name = &input.ident;
192    if !input.generics.params.is_empty() {
193        return Err(syn::Error::new(
194            input.generics.span(),
195            "`#[derive(Model)]` does not support generic structs",
196        ));
197    }
198
199    let mut table = None;
200    let mut timestamps = false;
201    let mut soft_delete = false;
202    let mut hooks = false;
203    let mut validate_with: Option<Path> = None;
204    let mut default_scope: Option<Path> = None;
205    let mut relations = Vec::new();
206    let mut from_row = true;
207    let mut krate: Option<Path> = None;
208    for attr in input.attrs.iter().filter(|a| a.path().is_ident("rok")) {
209        attr.parse_nested_meta(|meta| {
210            if meta.path.is_ident("table") {
211                table = Some(meta.value()?.parse::<LitStr>()?.value());
212            } else if meta.path.is_ident("timestamps") {
213                timestamps = true;
214            } else if meta.path.is_ident("soft_delete") {
215                soft_delete = true;
216            } else if meta.path.is_ident("hooks") {
217                hooks = true;
218            } else if meta.path.is_ident("validate_with") {
219                validate_with = Some(meta.value()?.parse()?);
220            } else if meta.path.is_ident("default_scope") {
221                default_scope = Some(meta.value()?.parse()?);
222            } else if meta.path.is_ident("has_many") {
223                parse_relations(&meta, "HasMany", &mut relations)?;
224            } else if meta.path.is_ident("has_one") {
225                parse_relations(&meta, "HasOne", &mut relations)?;
226            } else if meta.path.is_ident("no_from_row") {
227                from_row = false;
228            } else if meta.path.is_ident("crate") {
229                krate = Some(meta.value()?.parse::<LitStr>()?.parse()?);
230            } else {
231                return Err(meta
232                    .error("unknown `rok` attribute; expected `table`, `no_from_row` or `crate`"));
233            }
234            Ok(())
235        })?;
236    }
237    let table = table.unwrap_or_else(|| pluralize(&snake_case(&name.to_string())));
238    let krate = match krate {
239        Some(path) => quote!(#path),
240        None => crate_path(),
241    };
242
243    let fields = parse_fields(&input, "Model")?;
244
245    let columns: Vec<&Field> = fields.iter().filter(|f| !f.skip).collect();
246    let mut pks: Vec<&Field> = columns.iter().filter(|f| f.primary_key).copied().collect();
247    if pks.is_empty() {
248        pks.push(*columns.iter().find(|f| f.ident == "id").ok_or_else(|| {
249            syn::Error::new(
250                name.span(),
251                "no primary key: add a field named `id` or mark one or more fields with `#[rok(primary_key)]`",
252            )
253        })?);
254    }
255    let pk = pks[0];
256    let pk_columns = pks.iter().map(|f| &f.column);
257
258    let find_ts = |flag: fn(&Field) -> bool,
259                   default: &str,
260                   implied: bool,
261                   container: &str|
262     -> syn::Result<Option<String>> {
263        let mut marked = columns.iter().filter(|f| flag(f));
264        match (marked.next(), marked.next()) {
265            (Some(_), Some(second)) => Err(syn::Error::new(
266                second.ident.span(),
267                format!("only one field can be `#[rok({default})]`"),
268            )),
269            (Some(f), None) => Ok(Some(f.column.clone())),
270            (None, _) if implied => columns
271                .iter()
272                .find(|f| f.ident == default)
273                .map(|f| Some(f.column.clone()))
274                .ok_or_else(|| {
275                    syn::Error::new(
276                        name.span(),
277                        format!("`#[rok({container})]` requires a `{default}` field (or mark one with `#[rok({default})]`)"),
278                    )
279                }),
280            (None, _) => Ok(None),
281        }
282    };
283    let created_at = find_ts(|f| f.created_at, "created_at", timestamps, "timestamps")?;
284    let updated_at = find_ts(|f| f.updated_at, "updated_at", timestamps, "timestamps")?;
285    let deleted_at = find_ts(|f| f.deleted_at, "deleted_at", soft_delete, "soft_delete")?;
286    let version = find_ts(|f| f.version, "version", false, "")?;
287    let tenant = find_ts(|f| f.tenant, "tenant", false, "")?;
288    let opt = |v: Option<String>| match v {
289        Some(c) => quote!(::core::option::Option::Some(#c)),
290        None => quote!(::core::option::Option::None),
291    };
292    let created_at = opt(created_at);
293    let updated_at = opt(updated_at);
294    let deleted_at = opt(deleted_at);
295    let version = opt(version);
296    let tenant = opt(tenant);
297
298    let value_arms = columns.iter().map(|f| {
299        let ident = &f.ident;
300        let column = &f.column;
301        quote!(#column => ::core::option::Option::Some(#krate::Value::from(&self.#ident)))
302    });
303
304    let mut relation_items = Vec::new();
305    for f in &columns {
306        if let Some((rel, model)) = &f.belongs_to {
307            let const_name = format_ident!("{}", unraw(rel).to_uppercase(), span = rel.span());
308            let fk_const =
309                format_ident!("{}", unraw(&f.ident).to_uppercase(), span = f.ident.span());
310            let doc = format!(
311                "`{name}` belongs to [`{}`] through `{}`.",
312                quote!(#model).to_string().replace(' ', ""),
313                f.column
314            );
315            relation_items.push(quote! {
316                #[doc = #doc]
317                #[allow(dead_code)]
318                pub const #const_name: #krate::BelongsTo<#name, #model> = #krate::BelongsTo::new(Self::#fk_const);
319
320                #[doc = #doc]
321                #[allow(dead_code)]
322                pub fn #rel(&self) -> #krate::Select<#model> {
323                    Self::#const_name.query(self)
324                }
325            });
326        }
327    }
328    for r in &relations {
329        let Relation {
330            kind,
331            name: rel,
332            model,
333            foreign_key,
334        } = r;
335        let kind = Ident::new(kind, Span::call_site());
336        let const_name = format_ident!("{}", unraw(rel).to_uppercase(), span = rel.span());
337        let doc = format!(
338            "`{name}` → [`{}`] through `{}`.",
339            quote!(#model).to_string().replace(' ', ""),
340            quote!(#foreign_key).to_string().replace(' ', "")
341        );
342        relation_items.push(quote! {
343            #[doc = #doc]
344            #[allow(dead_code)]
345            pub const #const_name: #krate::#kind<#name, #model> = #krate::#kind::new(#foreign_key);
346
347            #[doc = #doc]
348            #[allow(dead_code)]
349            pub fn #rel(&self) -> #krate::Select<#model> {
350                Self::#const_name.query(self)
351            }
352        });
353    }
354
355    let validations: Vec<TokenStream2> = columns
356        .iter()
357        .flat_map(|f| {
358            let ident = &f.ident;
359            let field = unraw(ident);
360            let v = quote!(#krate::validate);
361            f.rules.iter().map(move |rule| {
362                let opt = |e: &Option<syn::Expr>, cast: TokenStream2| match e {
363                    Some(e) => quote!(::core::option::Option::Some((#e) as #cast)),
364                    None => quote!(::core::option::Option::None),
365                };
366                let (code, check) = match rule {
367                    Rule::Length(min, max) => {
368                        let (min, max) = (opt(min, quote!(usize)), opt(max, quote!(usize)));
369                        ("length", quote!(#v::length(&self.#ident, #min, #max)))
370                    }
371                    Rule::Range(min, max) => {
372                        let (min, max) = (opt(min, quote!(f64)), opt(max, quote!(f64)));
373                        ("range", quote!(#v::range(&self.#ident, #min, #max)))
374                    }
375                    Rule::Email => ("email", quote!(#v::email(&self.#ident))),
376                    Rule::NonEmpty => ("non_empty", quote!(#v::non_empty(&self.#ident))),
377                    Rule::Custom(path) => ("custom", quote!(#path(&self.#ident))),
378                };
379                quote! {
380                    if let ::core::result::Result::Err(message) = #check {
381                        errors.add(#field, #code, message);
382                    }
383                }
384            })
385        })
386        .collect();
387    let validate_fn = (!validations.is_empty() || validate_with.is_some()).then(|| {
388        let record = validate_with.as_ref().map(|path| {
389            quote! {
390                if let ::core::result::Result::Err(more) = #path(self) {
391                    errors.merge(more);
392                }
393            }
394        });
395        quote! {
396            fn validate(&self) -> ::core::result::Result<(), #krate::ValidationErrors> {
397                let mut errors = #krate::ValidationErrors::new();
398                #(#validations)*
399                #record
400                errors.into_result()
401            }
402        }
403    });
404    let default_scope_fn = default_scope.map(|path| {
405        quote! {
406            fn default_scope() -> ::core::option::Option<#krate::Expr<Self>> {
407                ::core::option::Option::Some(#path())
408            }
409        }
410    });
411    let hooks_impl = (!hooks).then(|| quote!(impl #krate::Hooks for #name {}));
412
413    let pk_column = &pk.column;
414    let pk_ident = &pk.ident;
415    let column_names = columns.iter().map(|f| &f.column);
416    let generated = columns.iter().filter(|f| f.generated).map(|f| &f.column);
417    let values = columns.iter().map(|f| {
418        let ident = &f.ident;
419        let column = &f.column;
420        quote!((#column, #krate::Value::from(&self.#ident)))
421    });
422    let consts = columns.iter().map(|f| {
423        let const_name = format_ident!("{}", unraw(&f.ident).to_uppercase(), span = f.ident.span());
424        let column = &f.column;
425        let doc = format!("The `{column}` column.");
426        quote! {
427            #[doc = #doc]
428            #[allow(dead_code)]
429            pub const #const_name: #krate::Column<#name> = #krate::Column::new(#column);
430        }
431    });
432
433    let from_row_impl = from_row.then(|| from_row_tokens(name, &fields, &krate));
434    let from_row_at_fn = from_row.then(|| {
435        let mut index = 0usize;
436        let inits = fields.iter().map(|f| {
437            let ident = &f.ident;
438            if f.skip {
439                quote!(#ident: ::core::default::Default::default())
440            } else {
441                let i = index;
442                index += 1;
443                quote!(#ident: #krate::__private::Row::try_get(row, offset + #i)?)
444            }
445        });
446        let inits: Vec<_> = inits.collect();
447        quote! {
448            fn from_row_at(
449                row: &#krate::__private::PgRow,
450                offset: usize,
451            ) -> ::core::result::Result<Self, #krate::__private::SqlxError> {
452                ::core::result::Result::Ok(Self { #(#inits,)* })
453            }
454        }
455    });
456
457    Ok(quote! {
458        #from_row_impl
459        #hooks_impl
460
461        impl #name {
462            #(#consts)*
463            #(#relation_items)*
464        }
465
466        impl #krate::Model for #name {
467            const TABLE: &'static str = #table;
468            const PRIMARY_KEY: &'static str = #pk_column;
469            const PRIMARY_KEYS: &'static [&'static str] = &[#(#pk_columns),*];
470            const COLUMNS: &'static [&'static str] = &[#(#column_names),*];
471            const GENERATED: &'static [&'static str] = &[#(#generated),*];
472            const CREATED_AT_COLUMN: ::core::option::Option<&'static str> = #created_at;
473            const UPDATED_AT_COLUMN: ::core::option::Option<&'static str> = #updated_at;
474            const DELETED_AT_COLUMN: ::core::option::Option<&'static str> = #deleted_at;
475            const VERSION_COLUMN: ::core::option::Option<&'static str> = #version;
476            const TENANT_COLUMN: ::core::option::Option<&'static str> = #tenant;
477
478            fn primary_key(&self) -> #krate::Value {
479                #krate::Value::from(&self.#pk_ident)
480            }
481
482            fn values(&self) -> ::std::vec::Vec<(&'static str, #krate::Value)> {
483                ::std::vec![#(#values),*]
484            }
485
486            #validate_fn
487            #default_scope_fn
488            #from_row_at_fn
489
490            fn value_of(&self, column: &str) -> ::core::option::Option<#krate::Value> {
491                match column {
492                    #(#value_arms,)*
493                    _ => ::core::option::Option::None,
494                }
495            }
496        }
497    })
498}
499
500fn parse_fields(input: &DeriveInput, derive: &str) -> syn::Result<Vec<Field>> {
501    let named = match &input.data {
502        Data::Struct(data) => match &data.fields {
503            Fields::Named(fields) => &fields.named,
504            _ => {
505                return Err(syn::Error::new(
506                    input.ident.span(),
507                    format!("`#[derive({derive})]` requires a struct with named fields"),
508                ));
509            }
510        },
511        _ => {
512            return Err(syn::Error::new(
513                input.ident.span(),
514                format!("`#[derive({derive})]` can only be used on structs"),
515            ));
516        }
517    };
518
519    let mut fields = Vec::new();
520    for field in named {
521        let ident = field.ident.clone().expect("named field");
522        let mut f = Field {
523            column: unraw(&ident),
524            ident,
525            primary_key: false,
526            generated: false,
527            skip: false,
528            created_at: false,
529            updated_at: false,
530            deleted_at: false,
531            version: false,
532            tenant: false,
533            belongs_to: None,
534            rules: Vec::new(),
535        };
536        for attr in field.attrs.iter().filter(|a| a.path().is_ident("rok")) {
537            attr.parse_nested_meta(|meta| {
538                if meta.path.is_ident("primary_key") {
539                    f.primary_key = true;
540                } else if meta.path.is_ident("generated") || meta.path.is_ident("auto") {
541                    f.generated = true;
542                } else if meta.path.is_ident("skip") {
543                    f.skip = true;
544                } else if meta.path.is_ident("created_at") {
545                    f.created_at = true;
546                } else if meta.path.is_ident("updated_at") {
547                    f.updated_at = true;
548                } else if meta.path.is_ident("deleted_at") {
549                    f.deleted_at = true;
550                } else if meta.path.is_ident("version") {
551                    f.version = true;
552                } else if meta.path.is_ident("tenant") {
553                    f.tenant = true;
554                } else if meta.path.is_ident("validate") {
555                    parse_rules(&meta, &mut f.rules)?;
556                } else if meta.path.is_ident("belongs_to") {
557                    if meta.input.peek(syn::Token![=]) {
558                        let model: Path = meta.value()?.parse()?;
559                        let field = unraw(&f.ident);
560                        let name = field.strip_suffix("_id").ok_or_else(|| {
561                            meta.error(format!(
562                                "can't derive a relation name from `{field}`; use `belongs_to(name = Model)`"
563                            ))
564                        })?;
565                        f.belongs_to = Some((Ident::new(name, f.ident.span()), model));
566                    } else {
567                        meta.parse_nested_meta(|inner| {
568                            let name = inner.path.get_ident().cloned().ok_or_else(|| {
569                                inner.error("expected `belongs_to(name = Model)`")
570                            })?;
571                            let model: Path = inner.value()?.parse()?;
572                            f.belongs_to = Some((name, model));
573                            Ok(())
574                        })?;
575                    }
576                } else if meta.path.is_ident("column") || meta.path.is_ident("rename") {
577                    f.column = meta.value()?.parse::<LitStr>()?.value();
578                } else {
579                    return Err(meta.error(
580                        "unknown `rok` attribute; expected `primary_key`, `generated`, `column`, `skip`, `created_at`, `updated_at`, `deleted_at`, `version`, `tenant`, `validate` or `belongs_to`",
581                    ));
582                }
583                Ok(())
584            })?;
585        }
586        let managed = f.created_at || f.updated_at || f.deleted_at || f.version || f.tenant;
587        if f.skip
588            && (f.primary_key
589                || f.generated
590                || managed
591                || f.belongs_to.is_some()
592                || !f.rules.is_empty())
593        {
594            return Err(syn::Error::new(
595                f.ident.span(),
596                "`skip` fields are not columns and can't have other `rok` attributes",
597            ));
598        }
599        if managed && f.generated {
600            return Err(syn::Error::new(
601                f.ident.span(),
602                "managed columns (timestamps, `deleted_at`, `version`) are written by rok-db and can't be `generated`",
603            ));
604        }
605        fields.push(f);
606    }
607    Ok(fields)
608}
609
610fn from_row_tokens(name: &Ident, fields: &[Field], krate: &TokenStream2) -> TokenStream2 {
611    let inits = fields.iter().map(|f| {
612        let ident = &f.ident;
613        let column = &f.column;
614        if f.skip {
615            quote!(#ident: ::core::default::Default::default())
616        } else {
617            quote!(#ident: #krate::__private::Row::try_get(row, #column)?)
618        }
619    });
620    quote! {
621        impl<'r> #krate::__private::FromRow<'r, #krate::__private::PgRow> for #name {
622            fn from_row(
623                row: &'r #krate::__private::PgRow,
624            ) -> ::core::result::Result<Self, #krate::__private::SqlxError> {
625                ::core::result::Result::Ok(Self { #(#inits,)* })
626            }
627        }
628    }
629}
630
631/// Derive `sqlx::FromRow` for decoding query results into a plain struct,
632/// e.g. the output of [`Select::select`] with aliased projections — without
633/// depending on sqlx directly.
634///
635/// Fields are read by name; `#[rok(column = "name")]` and `#[rok(skip)]`
636/// work as on [`Model`](derive@Model), and `#[rok(crate = "…")]` sets the
637/// crate path.
638///
639/// ```ignore
640/// #[derive(rok_db::FromRow)]
641/// struct RoleStats { role: String, users: i64 }
642/// ```
643///
644/// [`Select::select`]: https://docs.rs/rok-db/latest/rok_db/struct.Select.html#method.select
645#[proc_macro_derive(FromRow, attributes(rok))]
646pub fn derive_from_row(input: TokenStream) -> TokenStream {
647    let input = parse_macro_input!(input as DeriveInput);
648    expand_from_row(input)
649        .unwrap_or_else(syn::Error::into_compile_error)
650        .into()
651}
652
653fn expand_from_row(input: DeriveInput) -> syn::Result<TokenStream2> {
654    if !input.generics.params.is_empty() {
655        return Err(syn::Error::new(
656            input.generics.span(),
657            "`#[derive(FromRow)]` does not support generic structs",
658        ));
659    }
660    let mut krate: Option<Path> = None;
661    for attr in input.attrs.iter().filter(|a| a.path().is_ident("rok")) {
662        attr.parse_nested_meta(|meta| {
663            if meta.path.is_ident("crate") {
664                krate = Some(meta.value()?.parse::<LitStr>()?.parse()?);
665                Ok(())
666            } else {
667                Err(meta.error("unknown `rok` attribute for `FromRow`; expected `crate`"))
668            }
669        })?;
670    }
671    let krate = match krate {
672        Some(path) => quote!(#path),
673        None => crate_path(),
674    };
675    let fields = parse_fields(&input, "FromRow")?;
676    if let Some(f) = fields.iter().find(|f| {
677        f.primary_key
678            || f.generated
679            || f.created_at
680            || f.updated_at
681            || f.deleted_at
682            || f.version
683            || f.tenant
684            || f.belongs_to.is_some()
685            || !f.rules.is_empty()
686    }) {
687        return Err(syn::Error::new(
688            f.ident.span(),
689            "only `column` and `skip` apply to `#[derive(FromRow)]`",
690        ));
691    }
692    Ok(from_row_tokens(&input.ident, &fields, &krate))
693}
694
695fn parse_crate_attr(
696    attrs: &[syn::Attribute],
697    allowed: &[&str],
698    mut other: impl FnMut(&syn::meta::ParseNestedMeta<'_>) -> syn::Result<bool>,
699) -> syn::Result<TokenStream2> {
700    let mut krate: Option<Path> = None;
701    for attr in attrs.iter().filter(|a| a.path().is_ident("rok")) {
702        attr.parse_nested_meta(|meta| {
703            if meta.path.is_ident("crate") {
704                krate = Some(meta.value()?.parse::<LitStr>()?.parse()?);
705                Ok(())
706            } else if other(&meta)? {
707                Ok(())
708            } else {
709                Err(meta.error(format!(
710                    "unknown `rok` attribute; expected one of: crate, {}",
711                    allowed.join(", ")
712                )))
713            }
714        })?;
715    }
716    Ok(match krate {
717        Some(path) => quote!(#path),
718        None => crate_path(),
719    })
720}
721
722fn rename(name: &str, rule: &str) -> syn::Result<String> {
723    let snake = snake_case(name);
724    Ok(match rule {
725        "snake_case" => snake,
726        "SCREAMING_SNAKE_CASE" => snake.to_uppercase(),
727        "kebab-case" => snake.replace('_', "-"),
728        "lowercase" => name.to_lowercase(),
729        "UPPERCASE" => name.to_uppercase(),
730        "PascalCase" => name.to_owned(),
731        _ => {
732            return Err(syn::Error::new(
733                Span::call_site(),
734                "`rename_all` must be one of snake_case, SCREAMING_SNAKE_CASE, kebab-case, lowercase, UPPERCASE, PascalCase",
735            ));
736        }
737    })
738}
739
740/// Derive a column type for a field-less enum, stored as `TEXT` (default)
741/// or as a native PostgreSQL enum.
742///
743/// - `#[rok(type_name = "mood")]` — use the PostgreSQL enum type `mood`
744///   (`CREATE TYPE mood AS ENUM (…)`) instead of `TEXT`.
745/// - `#[rok(rename_all = "snake_case")]` — how variant names are stored
746///   (default `snake_case`; also `SCREAMING_SNAKE_CASE`, `kebab-case`,
747///   `lowercase`, `UPPERCASE`, `PascalCase`).
748/// - `#[rok(rename = "…")]` on a variant — explicit stored name.
749///
750/// Also generates `as_str()`, `Display` and `FromStr`, and makes the enum
751/// usable in models, filters and `set` (it needs `Clone + Debug`).
752///
753/// ```ignore
754/// #[derive(Debug, Clone, Copy, PartialEq, DbEnum)]
755/// enum Role { Admin, Member, #[rok(rename = "ro")] ReadOnly }
756///
757/// User::filter(User::ROLE.eq(Role::Admin))
758/// ```
759#[proc_macro_derive(DbEnum, attributes(rok))]
760pub fn derive_db_enum(input: TokenStream) -> TokenStream {
761    let input = parse_macro_input!(input as DeriveInput);
762    expand_db_enum(input)
763        .unwrap_or_else(syn::Error::into_compile_error)
764        .into()
765}
766
767fn expand_db_enum(input: DeriveInput) -> syn::Result<TokenStream2> {
768    let name = &input.ident;
769    if !input.generics.params.is_empty() {
770        return Err(syn::Error::new(
771            input.generics.span(),
772            "`#[derive(DbEnum)]` does not support generics",
773        ));
774    }
775    let mut type_name: Option<String> = None;
776    let mut rule = "snake_case".to_owned();
777    let krate = parse_crate_attr(&input.attrs, &["type_name", "rename_all"], |meta| {
778        if meta.path.is_ident("type_name") {
779            type_name = Some(meta.value()?.parse::<LitStr>()?.value());
780            Ok(true)
781        } else if meta.path.is_ident("rename_all") {
782            rule = meta.value()?.parse::<LitStr>()?.value();
783            Ok(true)
784        } else {
785            Ok(false)
786        }
787    })?;
788    let Data::Enum(data) = &input.data else {
789        return Err(syn::Error::new(
790            name.span(),
791            "`#[derive(DbEnum)]` can only be used on enums",
792        ));
793    };
794    let mut variants = Vec::new();
795    for v in &data.variants {
796        if !matches!(v.fields, Fields::Unit) {
797            return Err(syn::Error::new(
798                v.ident.span(),
799                "`#[derive(DbEnum)]` variants can't have fields",
800            ));
801        }
802        let mut stored = rename(&v.ident.to_string(), &rule)?;
803        for attr in v.attrs.iter().filter(|a| a.path().is_ident("rok")) {
804            attr.parse_nested_meta(|meta| {
805                if meta.path.is_ident("rename") {
806                    stored = meta.value()?.parse::<LitStr>()?.value();
807                    Ok(())
808                } else {
809                    Err(meta.error("unknown `rok` attribute on a variant; expected `rename`"))
810                }
811            })?;
812        }
813        variants.push((v.ident.clone(), stored));
814    }
815    let p = quote!(#krate::__private);
816    let to_str = variants.iter().map(|(v, s)| quote!(#name::#v => #s));
817    let from_str = variants
818        .iter()
819        .map(|(v, s)| quote!(#s => ::core::result::Result::Ok(#name::#v)));
820    let expected = variants
821        .iter()
822        .map(|(_, s)| s.as_str())
823        .collect::<Vec<_>>()
824        .join(", ");
825    let err = format!("invalid `{name}` value {{:?}} (expected one of: {expected})");
826    let (type_info, compatible) = match &type_name {
827        Some(t) => (
828            quote!(#p::PgTypeInfo::with_name(#t)),
829            quote!(*ty == <Self as #p::Type<#p::Postgres>>::type_info() || <::std::string::String as #p::Type<#p::Postgres>>::compatible(ty)),
830        ),
831        None => (
832            quote!(<::std::string::String as #p::Type<#p::Postgres>>::type_info()),
833            quote!(<::std::string::String as #p::Type<#p::Postgres>>::compatible(ty)),
834        ),
835    };
836    Ok(quote! {
837        impl #name {
838            /// The value stored in the database.
839            pub const fn as_str(&self) -> &'static str {
840                match self { #(#to_str,)* }
841            }
842        }
843
844        impl ::core::fmt::Display for #name {
845            fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
846                f.write_str(self.as_str())
847            }
848        }
849
850        impl ::core::str::FromStr for #name {
851            type Err = ::std::string::String;
852            fn from_str(s: &str) -> ::core::result::Result<Self, Self::Err> {
853                match s {
854                    #(#from_str,)*
855                    other => ::core::result::Result::Err(::std::format!(#err, other)),
856                }
857            }
858        }
859
860        impl #p::Type<#p::Postgres> for #name {
861            fn type_info() -> #p::PgTypeInfo { #type_info }
862            fn compatible(ty: &#p::PgTypeInfo) -> bool { #compatible }
863        }
864
865        impl<'q> #p::Encode<'q, #p::Postgres> for #name {
866            fn encode_by_ref(
867                &self,
868                buf: &mut #p::PgArgumentBuffer,
869            ) -> ::core::result::Result<#p::IsNull, #p::BoxDynError> {
870                <&str as #p::Encode<'q, #p::Postgres>>::encode_by_ref(&self.as_str(), buf)
871            }
872        }
873
874        impl<'r> #p::Decode<'r, #p::Postgres> for #name {
875            fn decode(value: #p::PgValueRef<'r>) -> ::core::result::Result<Self, #p::BoxDynError> {
876                let s = <&str as #p::Decode<'r, #p::Postgres>>::decode(value)?;
877                <Self as ::core::str::FromStr>::from_str(s).map_err(::core::convert::Into::into)
878            }
879        }
880
881        #krate::impl_value!(#name);
882    })
883}
884
885/// Derive a column type for a single-field tuple struct (a "newtype"),
886/// stored exactly like its inner type:
887///
888/// ```ignore
889/// #[derive(Debug, Clone, PartialEq, DbNewtype)]
890/// struct Email(String);
891///
892/// #[derive(Model)]
893/// struct User { id: i64, email: Email }
894/// ```
895///
896/// The newtype must be `Clone + Debug`.
897#[proc_macro_derive(DbNewtype, attributes(rok))]
898pub fn derive_db_newtype(input: TokenStream) -> TokenStream {
899    let input = parse_macro_input!(input as DeriveInput);
900    expand_db_newtype(input)
901        .unwrap_or_else(syn::Error::into_compile_error)
902        .into()
903}
904
905fn expand_db_newtype(input: DeriveInput) -> syn::Result<TokenStream2> {
906    let name = &input.ident;
907    if !input.generics.params.is_empty() {
908        return Err(syn::Error::new(
909            input.generics.span(),
910            "`#[derive(DbNewtype)]` does not support generics",
911        ));
912    }
913    let krate = parse_crate_attr(&input.attrs, &[], |_| Ok(false))?;
914    let inner = match &input.data {
915        Data::Struct(s) => match &s.fields {
916            Fields::Unnamed(f) if f.unnamed.len() == 1 => f.unnamed[0].ty.clone(),
917            _ => None.ok_or_else(|| {
918                syn::Error::new(
919                    name.span(),
920                    "`#[derive(DbNewtype)]` requires a struct with exactly one unnamed field",
921                )
922            })?,
923        },
924        _ => {
925            return Err(syn::Error::new(
926                name.span(),
927                "`#[derive(DbNewtype)]` can only be used on structs",
928            ));
929        }
930    };
931    let p = quote!(#krate::__private);
932    Ok(quote! {
933        impl #p::Type<#p::Postgres> for #name {
934            fn type_info() -> #p::PgTypeInfo { <#inner as #p::Type<#p::Postgres>>::type_info() }
935            fn compatible(ty: &#p::PgTypeInfo) -> bool { <#inner as #p::Type<#p::Postgres>>::compatible(ty) }
936        }
937
938        impl<'q> #p::Encode<'q, #p::Postgres> for #name {
939            fn encode_by_ref(
940                &self,
941                buf: &mut #p::PgArgumentBuffer,
942            ) -> ::core::result::Result<#p::IsNull, #p::BoxDynError> {
943                <#inner as #p::Encode<'q, #p::Postgres>>::encode_by_ref(&self.0, buf)
944            }
945        }
946
947        impl<'r> #p::Decode<'r, #p::Postgres> for #name {
948            fn decode(value: #p::PgValueRef<'r>) -> ::core::result::Result<Self, #p::BoxDynError> {
949                <#inner as #p::Decode<'r, #p::Postgres>>::decode(value).map(#name)
950            }
951        }
952
953        #krate::impl_value!(#name);
954    })
955}
956
957/// Run an async test against a fresh, temporary database (feature
958/// `testing`). The database is created on the server named by
959/// `DATABASE_URL`, passed in as a [`Db`], and dropped afterwards — even if
960/// the test panics. Without `DATABASE_URL` the test is skipped.
961///
962/// ```ignore
963/// #[rok_db::test(migrations = "migrations", sql = "tests/fixtures/users.sql")]
964/// async fn finds_admins(db: Db) {
965///     assert_eq!(User::filter(User::ROLE.eq("admin")).count(&db).await.unwrap(), 1);
966/// }
967/// ```
968///
969/// - `migrations = "dir"` — run sqlx migrations from `dir` (needs the
970///   `migrate` feature); may be repeated.
971/// - `sql = "file.sql"` — execute an SQL file (schema or fixtures); may be
972///   repeated, runs after migrations in order.
973///
974/// Paths are relative to the crate's `Cargo.toml`. The test runs on
975/// `#[tokio::test]`, so `tokio` (with `macros` and `rt`) must be a
976/// dev-dependency. It may return `()` or a `Result<(), E>`.
977///
978/// [`Db`]: https://docs.rs/rok-db/latest/rok_db/struct.Db.html
979#[proc_macro_attribute]
980pub fn test(args: TokenStream, item: TokenStream) -> TokenStream {
981    let item = parse_macro_input!(item as syn::ItemFn);
982    expand_test(args.into(), item)
983        .unwrap_or_else(syn::Error::into_compile_error)
984        .into()
985}
986
987fn expand_test(args: TokenStream2, item: syn::ItemFn) -> syn::Result<TokenStream2> {
988    let mut migrations = Vec::new();
989    let mut sql_files = Vec::new();
990    let mut krate: Option<Path> = None;
991    let parser = syn::meta::parser(|meta| {
992        if meta.path.is_ident("migrations") {
993            migrations.push(meta.value()?.parse::<LitStr>()?);
994        } else if meta.path.is_ident("sql") {
995            sql_files.push(meta.value()?.parse::<LitStr>()?);
996        } else if meta.path.is_ident("crate") {
997            krate = Some(meta.value()?.parse::<LitStr>()?.parse()?);
998        } else {
999            return Err(meta.error("expected `migrations`, `sql` or `crate`"));
1000        }
1001        Ok(())
1002    });
1003    syn::parse::Parser::parse2(parser, args)?;
1004    let krate = match krate {
1005        Some(path) => quote!(#path),
1006        None => crate_path(),
1007    };
1008
1009    let syn::ItemFn {
1010        attrs,
1011        vis,
1012        sig,
1013        block,
1014        ..
1015    } = item;
1016    if sig.asyncness.is_none() {
1017        return Err(syn::Error::new(
1018            sig.fn_token.span(),
1019            "`#[rok_db::test]` functions must be `async`",
1020        ));
1021    }
1022    if sig.inputs.len() != 1 {
1023        return Err(syn::Error::new(
1024            sig.inputs.span(),
1025            "expected exactly one parameter, e.g. `db: Db`",
1026        ));
1027    }
1028    let syn::FnArg::Typed(param) = &sig.inputs[0] else {
1029        return Err(syn::Error::new(
1030            sig.inputs.span(),
1031            "expected a parameter like `db: Db`",
1032        ));
1033    };
1034    let (pat, ty) = (&param.pat, &param.ty);
1035    let name = &sig.ident;
1036    let output = &sig.output;
1037    let skip = match output {
1038        syn::ReturnType::Default => quote!(return),
1039        syn::ReturnType::Type(..) => quote!(return ::core::result::Result::Ok(())),
1040    };
1041    let migrate = migrations.iter().map(|dir| {
1042        quote! {
1043            __rok_test_db
1044                .migrate(::core::concat!(::core::env!("CARGO_MANIFEST_DIR"), "/", #dir))
1045                .await
1046                .expect(::core::concat!("failed to run migrations in ", #dir));
1047        }
1048    });
1049    let sql = sql_files.iter().map(|file| {
1050        quote! {
1051            __rok_test_db
1052                .db()
1053                .execute(::core::include_str!(::core::concat!(::core::env!("CARGO_MANIFEST_DIR"), "/", #file)))
1054                .await
1055                .expect(::core::concat!("failed to execute ", #file));
1056        }
1057    });
1058    Ok(quote! {
1059        #(#attrs)*
1060        #[::tokio::test]
1061        #vis async fn #name() #output {
1062            let __rok_test_db = match #krate::testing::TestDb::create().await {
1063                ::core::result::Result::Ok(::core::option::Option::Some(db)) => db,
1064                ::core::result::Result::Ok(::core::option::Option::None) => {
1065                    ::std::eprintln!("DATABASE_URL not set; skipping `{}`", ::core::stringify!(#name));
1066                    #skip;
1067                }
1068                ::core::result::Result::Err(e) => ::core::panic!("failed to create a test database: {e}"),
1069            };
1070            #(#migrate)*
1071            #(#sql)*
1072            let #pat: #ty = ::core::clone::Clone::clone(__rok_test_db.db());
1073            let __rok_result = async move #block.await;
1074            ::core::mem::drop(__rok_test_db);
1075            __rok_result
1076        }
1077    })
1078}
1079
1080/// Resolve the path to the `rok_db` crate from the caller's point of view.
1081fn crate_path() -> TokenStream2 {
1082    let found = crate_name("rok-db")
1083        .map(|c| (c, "rok_db"))
1084        .or_else(|_| crate_name("rok-db-core").map(|c| (c, "rok_db_core")));
1085    match found {
1086        // Inside rok-db's own tests/examples the crate is reachable by name.
1087        Ok((FoundCrate::Itself, default)) => {
1088            let ident = Ident::new(default, Span::call_site());
1089            quote!(::#ident)
1090        }
1091        Ok((FoundCrate::Name(name), _)) => {
1092            let ident = Ident::new(&name, Span::call_site());
1093            quote!(::#ident)
1094        }
1095        Err(_) => quote!(::rok_db),
1096    }
1097}
1098
1099fn unraw(ident: &Ident) -> String {
1100    let s = ident.to_string();
1101    s.strip_prefix("r#").map(str::to_owned).unwrap_or(s)
1102}
1103
1104fn snake_case(s: &str) -> String {
1105    let mut out = String::new();
1106    let chars: Vec<char> = s.chars().collect();
1107    for (i, &c) in chars.iter().enumerate() {
1108        if c.is_uppercase() {
1109            let prev_lower =
1110                i > 0 && (chars[i - 1].is_lowercase() || chars[i - 1].is_ascii_digit());
1111            let next_lower = chars.get(i + 1).is_some_and(|n| n.is_lowercase());
1112            let prev_upper = i > 0 && chars[i - 1].is_uppercase();
1113            if prev_lower || (prev_upper && next_lower) {
1114                out.push('_');
1115            }
1116            out.extend(c.to_lowercase());
1117        } else {
1118            out.push(c);
1119        }
1120    }
1121    out
1122}
1123
1124fn pluralize(s: &str) -> String {
1125    let ends_with_consonant_y =
1126        s.ends_with('y') && !s.chars().rev().nth(1).is_some_and(|c| "aeiou".contains(c));
1127    if ends_with_consonant_y {
1128        format!("{}ies", &s[..s.len() - 1])
1129    } else if ["s", "x", "z", "ch", "sh"].iter().any(|e| s.ends_with(e)) {
1130        format!("{s}es")
1131    } else {
1132        format!("{s}s")
1133    }
1134}
1135
1136#[cfg(test)]
1137mod tests {
1138    use super::{pluralize, snake_case};
1139
1140    #[test]
1141    fn table_names() {
1142        let t = |s: &str| pluralize(&snake_case(s));
1143        assert_eq!(t("User"), "users");
1144        assert_eq!(t("BlogPost"), "blog_posts");
1145        assert_eq!(t("Category"), "categories");
1146        assert_eq!(t("Day"), "days");
1147        assert_eq!(t("Address"), "addresses");
1148        assert_eq!(t("HTTPRequest"), "http_requests");
1149        assert_eq!(t("Box"), "boxes");
1150    }
1151}