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