1#![forbid(unsafe_code)]
2mod 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#[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#[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#[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#[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#[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#[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#[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}