Skip to main content

ic_db_macros/
lib.rs

1#![forbid(unsafe_code)]
2//! Small attribute authoring boundary for the first persistent-record slice.
3//! Generates typed records/codecs and metadata, never endpoints or executors.
4//! All declarations use empty, nongeneric struct bodies without `where` clauses;
5//! unsupported Rust constraints are rejected rather than discarded during expansion.
6
7mod enumeration;
8mod field;
9mod insert;
10mod map;
11mod record;
12mod set;
13#[cfg(test)]
14mod tests;
15mod wrapped;
16
17use proc_macro::TokenStream;
18use proc_macro2::TokenStream as Tokens;
19use quote::quote;
20use std::collections::BTreeSet;
21use syn::{Expr, ItemStruct, Lit, Meta, Token, parse::Parser, punctuated::Punctuated};
22
23use field::Field;
24
25/// Author a typed record with named fields, a supplied scalar key and indexes.
26///
27/// Each field has an associated name constant, e.g. `User::NAME` for `name`.
28/// Field types follow the implemented `ic_db::FieldType` contract, with explicit
29/// bounds for variable-size values. Secondary indexes admit supported ordered
30/// scalar fields and unit enums, including optional forms. Optional unique indexes require
31/// `present_only`, omitting a row when any optional key component is absent. Unsupported shapes
32/// refuse explicitly; this is not a retirement of the broader planned type surface.
33/// Entity names default to the type name; `name = "StableName"` overrides it.
34/// Index names default to comma-separated ordered fields; `name` overrides them.
35/// Required or optional supported key fields may declare `references(entity = "path::Target")`;
36/// select the sole unfiltered index leading with this field, or use `index = "name"`.
37/// `None` has no target; every `Some(id)` requires that target in the final batch state.
38/// `entity = "path::Target"` lets Rust resolve an entity type (including imports
39/// and `Self`) to its logical identity. Numeric authoring IDs are unsupported.
40/// With the host-only `ic-db/build` feature, declarations also register their
41/// full Rust paths for second-stage schema assembly.
42/// Fields may declare `default = LITERAL` for integers, Bool, bounded Text and Blob.
43/// Blob defaults use Rust byte strings, e.g. `default = b"\x00\xff"`, never text/hex coercion.
44/// `Entity::insert()` builds typed omission-aware input for `Batch::insert_input`;
45/// explicit optional `None` is never replaced by a default. Primary-key and nested
46/// record defaults are not implemented. Defaults never run on decode/replacement.
47/// Required Timestamp fields and their scalar newtypes may declare `managed = "created_at"` or
48/// `managed = "updated_at"`, once per role. These fields have no insert setters;
49/// use `Batch::at(time)` to supply one operation time for the entire batch.
50#[proc_macro_attribute]
51pub fn entity(args: TokenStream, item: TokenStream) -> TokenStream {
52    expand(args.into(), item.into())
53        .unwrap_or_else(syn::Error::into_compile_error)
54        .into()
55}
56
57/// Declare a named enum using an empty struct and `variant(name = "...")` attributes.
58/// Supports 1–64 unit or typed payload variants. Canonical name order determines
59/// stored ordinals; source declaration order does not. Use item(indirect, is = "Self")
60/// for boxed recursion, with a finite base alternative.
61/// All-unit enums also convert by reference into `ic_db::IndexValue`, using the
62/// same canonical order. Any payload variant excludes the whole enum from indexes.
63#[proc_macro_attribute]
64pub fn enum_(args: TokenStream, item: TokenStream) -> TokenStream {
65    enumeration::expand(args.into(), item.into())
66        .unwrap_or_else(syn::Error::into_compile_error)
67        .into()
68}
69
70/// Declare a reusable ordered list with an item type and a shared maximum length.
71#[proc_macro_attribute]
72pub fn list(args: TokenStream, item: TokenStream) -> TokenStream {
73    wrapped::expand(args.into(), item.into(), true)
74        .unwrap_or_else(syn::Error::into_compile_error)
75        .into()
76}
77
78/// Declare a distinct Rust and schema type around one primitive, including its bounds.
79#[proc_macro_attribute]
80pub fn newtype(args: TokenStream, item: TokenStream) -> TokenStream {
81    wrapped::expand(args.into(), item.into(), false)
82        .unwrap_or_else(syn::Error::into_compile_error)
83        .into()
84}
85
86/// Declare a bounded ordered set with `item(...)` and `max_items = N` (0..256).
87/// Elements can be primitives, scalar newtypes or unit enums. The generated
88/// wrapper contains a `BTreeSet<T>`. Decoding requires strictly increasing keys.
89#[proc_macro_attribute]
90pub fn set(args: TokenStream, item: TokenStream) -> TokenStream {
91    set::expand(args.into(), item.into())
92        .unwrap_or_else(syn::Error::into_compile_error)
93        .into()
94}
95
96/// Declare a named `BTreeMap` wrapper using `key(...)`, `value(...)` and
97/// `max_items = N` (0..256). Keys are primitives, scalar newtypes or unit enums. Values use the
98/// ordinary optional/list/named field rules; stored duplicate keys refuse.
99#[proc_macro_attribute]
100pub fn map(args: TokenStream, item: TokenStream) -> TokenStream {
101    map::expand(args.into(), item.into())
102        .unwrap_or_else(syn::Error::into_compile_error)
103        .into()
104}
105
106/// Declare a named stored record using attribute-owned fields and an empty struct.
107#[proc_macro_attribute]
108pub fn record(args: TokenStream, item: TokenStream) -> TokenStream {
109    record::expand(args.into(), item.into())
110        .unwrap_or_else(syn::Error::into_compile_error)
111        .into()
112}
113
114struct Index {
115    name: String,
116    fields: Vec<String>,
117    unique: bool,
118    present_only: bool,
119}
120
121fn metas(tokens: Tokens) -> syn::Result<Vec<Meta>> {
122    Ok(Punctuated::<Meta, Token![,]>::parse_terminated
123        .parse2(tokens)?
124        .into_iter()
125        .collect())
126}
127
128fn meta_items(meta: &Meta) -> syn::Result<Vec<Meta>> {
129    match meta {
130        Meta::List(value) => metas(value.tokens.clone()),
131        _ => Err(syn::Error::new_spanned(meta, "expected attribute list")),
132    }
133}
134
135fn literal(meta: &Meta) -> syn::Result<&Lit> {
136    if let Meta::NameValue(value) = meta
137        && let Expr::Lit(value) = &value.value
138    {
139        return Ok(&value.lit);
140    }
141    Err(syn::Error::new_spanned(meta, "expected literal value"))
142}
143
144fn text(meta: &Meta) -> syn::Result<String> {
145    if let Lit::Str(value) = literal(meta)? {
146        return Ok(value.value());
147    }
148    Err(syn::Error::new_spanned(meta, "expected a string"))
149}
150
151fn once<T>(slot: &mut Option<T>, value: T, meta: &Meta) -> syn::Result<()> {
152    if slot.replace(value).is_some() {
153        return Err(syn::Error::new_spanned(meta, "duplicate attribute"));
154    }
155    Ok(())
156}
157
158fn fields(meta: &Meta) -> syn::Result<Vec<String>> {
159    if let Meta::NameValue(value) = meta
160        && let Expr::Array(values) = &value.value
161    {
162        return values
163            .elems
164            .iter()
165            .map(|value| {
166                if let Expr::Lit(value) = value
167                    && let Lit::Str(value) = &value.lit
168                {
169                    return Ok(value.value());
170                }
171                Err(syn::Error::new_spanned(value, "expected field name"))
172            })
173            .collect();
174    }
175    Err(syn::Error::new_spanned(
176        meta,
177        "expected an array of field names",
178    ))
179}
180
181fn declaration(item: Tokens, kind: &str) -> syn::Result<ItemStruct> {
182    let item: ItemStruct = syn::parse2(item)?;
183    if !matches!(&item.fields, syn::Fields::Named(fields) if fields.named.is_empty())
184        || !item.generics.params.is_empty()
185        || item.generics.where_clause.is_some()
186    {
187        return Err(syn::Error::new_spanned(
188            &item,
189            format!("{kind} requires an empty, nongeneric struct body without a where clause"),
190        ));
191    }
192    Ok(item)
193}
194
195fn expand(args: Tokens, item: Tokens) -> syn::Result<Tokens> {
196    let item = declaration(item, "entity")?;
197    let mut logical_name = None;
198    let mut primary = None;
199    let mut authored = None;
200    let mut indexes = Vec::new();
201    for meta in metas(args)? {
202        if meta.path().is_ident("name") {
203            once(&mut logical_name, text(&meta)?, &meta)?;
204        } else if meta.path().is_ident("pk") {
205            let mut key = None;
206            for part in meta_items(&meta)? {
207                if part.path().is_ident("field") {
208                    once(&mut key, text(&part)?, &part)?;
209                } else {
210                    return Err(syn::Error::new_spanned(
211                        part,
212                        "pk accepts only field = \"name\"",
213                    ));
214                }
215            }
216            let key = key.ok_or_else(|| syn::Error::new_spanned(&meta, "pk requires field"))?;
217            once(&mut primary, key, &meta)?;
218        } else if meta.path().is_ident("fields") {
219            let values = meta_items(&meta)?
220                .iter()
221                .map(Field::parse)
222                .collect::<syn::Result<Vec<_>>>()?;
223            once(&mut authored, values, &meta)?;
224        } else if meta.path().is_ident("index") {
225            let mut index_name = None;
226            let mut names = None;
227            let mut unique = false;
228            let mut present_only = false;
229            for part in meta_items(&meta)? {
230                if part.path().is_ident("name") {
231                    once(&mut index_name, text(&part)?, &part)?;
232                } else if part.path().is_ident("fields") {
233                    once(&mut names, fields(&part)?, &part)?;
234                } else if part.path().is_ident("field") {
235                    once(&mut names, vec![text(&part)?], &part)?;
236                } else if matches!(&part, Meta::Path(path) if path.is_ident("unique")) && !unique {
237                    unique = true;
238                } else if matches!(&part, Meta::Path(path) if path.is_ident("present_only"))
239                    && !present_only
240                {
241                    present_only = true;
242                } else {
243                    return Err(syn::Error::new_spanned(
244                        part,
245                        "unsupported or duplicate index option",
246                    ));
247                }
248            }
249            let fields =
250                names.ok_or_else(|| syn::Error::new_spanned(&meta, "index requires fields"))?;
251            indexes.push(Index {
252                name: index_name.unwrap_or_else(|| fields.join(",")),
253                fields,
254                unique,
255                present_only,
256            });
257        } else {
258            return Err(syn::Error::new_spanned(meta, "unsupported entity option"));
259        }
260    }
261    let fail = |message| syn::Error::new_spanned(&item.ident, message);
262    let logical_name = logical_name.unwrap_or_else(|| item.ident.to_string());
263    if logical_name.is_empty() || logical_name.len() > 64 {
264        return Err(fail("entity name requires 1..64 UTF-8 bytes"));
265    }
266    let primary = primary.ok_or_else(|| fail("entity requires pk"))?;
267    let mut authored = authored.ok_or_else(|| fail("entity requires fields"))?;
268    let names: BTreeSet<_> = authored.iter().map(|field| &field.name).collect();
269    if names.len() != authored.len()
270        || authored.is_empty()
271        || authored.len() > 16
272        || !names.contains(&primary)
273        || authored.iter().any(|field| field.name.len() > 64)
274    {
275        return Err(fail(
276            "invalid, duplicate or excessive fields/primary key (1..16 fields)",
277        ));
278    }
279    let field_ids: Vec<syn::Ident> = authored
280        .iter()
281        .map(|field| syn::parse_str(&field.name))
282        .collect::<syn::Result<_>>()?;
283    let mut constant_names = BTreeSet::new();
284    let mut field_constants = Vec::with_capacity(authored.len());
285    for field in &authored {
286        let source = &field.name;
287        let constant = source
288            .strip_prefix("r#")
289            .unwrap_or(source)
290            .to_ascii_uppercase();
291        if !constant_names.insert(constant.clone()) {
292            return Err(fail(&format!(
293                "fields generate the same associated constant `{constant}`"
294            )));
295        }
296        let ident = syn::parse_str::<syn::Ident>(&constant)?;
297        let doc = format!("Logical field name `{source}` for fluent queries.");
298        field_constants.push(quote! { #[doc = #doc] pub const #ident: &'static str = #source; });
299    }
300    let key_type = authored
301        .iter()
302        .find(|field| field.name == primary && field.required_key())
303        .ok_or_else(|| {
304            fail("primary key currently requires a non-optional integer, U256, Ulid, Principal, Account or Subaccount")
305        })?
306        .rust_type();
307    let key_id: syn::Ident = syn::parse_str(&primary)?;
308    indexes.sort_by(|left, right| left.name.cmp(&right.name));
309    if indexes.len() > 8
310        || indexes.windows(2).any(|pair| pair[0].name == pair[1].name)
311        || indexes
312            .iter()
313            .any(|index| index.name.is_empty() || index.name.len() > 64)
314    {
315        return Err(fail(
316            "indexes require distinct names of 1..64 bytes (maximum eight); use name to disambiguate",
317        ));
318    }
319    let mut descriptions = Vec::new();
320    let mut encoded_indexes = Vec::new();
321    for field in &mut authored {
322        if let Some((_, selected)) = &mut field.reference {
323            let mut candidates = indexes.iter().filter(|index| {
324                !index.present_only
325                    && index.fields.first() == Some(&field.name)
326                    && selected.as_ref().is_none_or(|name| *name == index.name)
327            });
328            let Some(index) = candidates.next() else {
329                return Err(fail(
330                    "reference requires an unfiltered declared index beginning with its field",
331                ));
332            };
333            if candidates.next().is_some() {
334                return Err(fail(
335                    "ambiguous reference access path; select an index by name",
336                ));
337            }
338            *selected = Some(index.name.clone());
339        }
340    }
341    for index in indexes {
342        let unique_fields: BTreeSet<_> = index.fields.iter().collect();
343        if index.fields.is_empty()
344            || index.fields.len() > 4
345            || unique_fields.len() != index.fields.len()
346            || index.fields.iter().any(|name| {
347                !authored
348                    .iter()
349                    .any(|field| &field.name == name && field.indexable())
350            })
351        {
352            return Err(fail(
353                "index requires 1..4 distinct supported scalar or unit-enum fields",
354            ));
355        }
356        let fields: Vec<syn::Ident> = index
357            .fields
358            .iter()
359            .map(|name| syn::parse_str(name))
360            .collect::<syn::Result<_>>()?;
361        let index_name = index.name;
362        let unique = index.unique;
363        let present_only = index.present_only;
364        let has_optional = index.fields.iter().any(|name| {
365            authored
366                .iter()
367                .any(|field| &field.name == name && field.optional)
368        });
369        if (unique && has_optional && !present_only) || (present_only && (!unique || !has_optional))
370        {
371            return Err(fail(
372                "optional unique indexes require present_only; present_only requires uniqueness and an optional component",
373            ));
374        }
375        let operands: Vec<_> = index
376            .fields
377            .iter()
378            .zip(&fields)
379            .map(|(name, ident)| {
380                let field = authored
381                    .iter()
382                    .find(|field| &field.name == name)
383                    .expect("admitted index field");
384                let value = field.index_value(ident);
385                let optional = field.optional;
386                quote!((#value, #optional))
387            })
388            .collect();
389        let names = index.fields;
390        descriptions.push(quote! { ::ic_db::IndexSchema { id: ::ic_db::__private::handle(#index_name), name: #index_name, fields: &[#(#names),*], unique: #unique, present_only: #present_only } });
391        encoded_indexes
392            .push(quote! { ::ic_db::__private::encode_index(&[#(#operands),*], #present_only) });
393    }
394    let name = &item.ident;
395    let attrs = &item.attrs;
396    let visibility = &item.vis;
397    let mut ordered: Vec<_> = authored.iter().collect();
398    ordered.sort_by_key(|field| &field.name);
399    let ordered_ids: Vec<syn::Ident> = ordered
400        .iter()
401        .map(|field| syn::parse_str(&field.name))
402        .collect::<syn::Result<_>>()?;
403    let nested_writes: Vec<_> = ordered
404        .iter()
405        .zip(&ordered_ids)
406        .filter(|(f, _)| f.many.is_some() || matches!(f.kind, field::Kind::Named(..)))
407        .map(|(f, id)| f.encode(id))
408        .collect();
409    let nested_validation = if nested_writes.is_empty() {
410        quote!()
411    } else {
412        quote! { let mut writer = ::ic_db::__private::Encoder::new(); #(#nested_writes)* }
413    };
414    let writes: Vec<_> = ordered
415        .iter()
416        .zip(&ordered_ids)
417        .map(|(field, id)| field.encode(id))
418        .collect();
419    let reads: Vec<_> = ordered
420        .iter()
421        .zip(&ordered_ids)
422        .map(|(field, id)| field.decode(id))
423        .collect();
424    let authored_types: Vec<_> = authored.iter().map(Field::rust_type).collect();
425    let descriptions_fields: Vec<_> = ordered.iter().map(|field| field.description()).collect();
426    let validations: Vec<_> = authored
427        .iter()
428        .zip(&field_ids)
429        .map(|(field, id)| field.validation(id))
430        .collect();
431    if authored
432        .iter()
433        .any(|field| field.name == primary && field.default.is_some())
434    {
435        return Err(syn::Error::new_spanned(
436            &item.ident,
437            "supplied primary keys cannot declare an insert default",
438        ));
439    }
440    let insert_input = insert::emit(&item, &authored)?;
441    let mut managed_fields = [None, None];
442    for (field, id) in authored.iter().zip(&field_ids) {
443        if let Some(policy) = field.managed {
444            let slot = usize::from(policy == field::Management::UpdatedAt);
445            let timestamp = if matches!(field.kind, field::Kind::Named(..)) {
446                quote!(#id.0)
447            } else {
448                quote!(#id)
449            };
450            if managed_fields[slot].replace(timestamp).is_some() {
451                return Err(syn::Error::new_spanned(
452                    id,
453                    "each managed timestamp role may appear once per entity",
454                ));
455            }
456        }
457    }
458    let managed_check = |owner: Tokens| {
459        if managed_fields.iter().all(Option::is_none) {
460            return quote!();
461        }
462        let values = managed_fields.iter().map(|field| {
463            field
464                .as_ref()
465                .map_or_else(|| quote!(None), |field| quote!(Some(#owner.#field)))
466        });
467        quote!(::ic_db::__private::validate_managed_order([#(#values),*])?;)
468    };
469    let validate_managed = managed_check(quote!(self));
470    let decode_managed = managed_check(quote!(row));
471    Ok(quote! {
472        #insert_input
473        #(#attrs)*
474        #[derive(Clone, Debug, PartialEq, Eq)]
475        #visibility struct #name { #(#[doc = "Authored stored field."] pub #field_ids: #authored_types,)* }
476        impl #name { #(#field_constants)* }
477        impl ::ic_db::__private::ReferenceTarget for #name {
478            const NAME: &'static str = #logical_name;
479        }
480        impl ::ic_db::Entity for #name {
481            type Key = #key_type;
482            fn declaration_path() -> &'static str { concat!(module_path!(), "::", stringify!(#name)) }
483            const SCHEMA: &'static ::ic_db::EntitySchema = &::ic_db::EntitySchema {
484                id: ::ic_db::__private::handle(#logical_name), name: #logical_name, fields: &[#(#descriptions_fields),*], primary_key: #primary,
485                indexes: &[#(#descriptions),*],
486            };
487            fn key(&self) -> Self::Key { self.#key_id }
488
489            fn __row_info(&self) -> ::ic_db::__private::RowInfo {
490                let row = self;
491                ::ic_db::__private::RowInfo {
492                    key: ::ic_db::PrimaryKey::into_row_key(<Self as ::ic_db::Entity>::key(row)),
493                    indexes: ::std::vec![#(#encoded_indexes),*]
494                }
495            }
496
497            fn validate(&self) -> Result<(), ::ic_db::Error> {
498                #validate_managed
499                #(#validations)*
500                #nested_validation
501                Ok(())
502            }
503
504            fn encode(&self) -> Result<::std::vec::Vec<u8>, ::ic_db::Error> {
505                #validate_managed
506                let mut writer = ::ic_db::__private::Encoder::new();
507                #(#writes)*
508                Ok(writer.finish())
509            }
510
511            fn decode(bytes: &[u8]) -> Result<Self, ::ic_db::Error> {
512                let mut reader = ::ic_db::__private::Decoder::new(bytes)?;
513                let row = Self { #(#reads)* };
514                reader.finish()?;
515                #decode_managed
516                Ok(row)
517            }
518        }
519        ::ic_db::__register_schema!(#name);
520    })
521}