use anyhow::{bail, Context, Result};
use heck::ToSnakeCase;
use std::collections::BTreeSet;
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum Kind {
String,
Text,
Boolean,
Integer,
Bigint,
Float,
Uuid,
Datetime,
Date,
Enum,
Decimal,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum DeleteBehavior {
Restrict,
Cascade,
SetNull,
}
impl DeleteBehavior {
pub fn sea_orm(self) -> &'static str {
match self {
Self::Restrict => "Restrict",
Self::Cascade => "Cascade",
Self::SetNull => "SetNull",
}
}
}
#[derive(Clone, Debug)]
pub(crate) struct Reference {
pub target: String,
pub on_delete: DeleteBehavior,
pub has_owner: bool,
}
#[derive(Clone, Debug)]
pub(crate) struct Field {
pub name: String,
pub kind: Kind,
pub nullable: bool,
pub unique: bool,
pub index: bool,
pub default: Option<String>,
pub reference: Option<Reference>,
pub enum_values: Option<Vec<String>>,
pub enum_resource: Option<String>,
pub decimal: Option<(u32, u32)>,
}
impl Field {
pub fn parse_all(definitions: &[String]) -> Result<Vec<Self>> {
if definitions.is_empty() || definitions.len() > 32 {
bail!(
"A resource needs 1..=32 fields, for example title:string published:boolean=false."
);
}
let mut names = BTreeSet::new();
definitions
.iter()
.map(|definition| {
let field = Self::parse(definition)
.with_context(|| format!("Invalid resource field `{definition}`"))?;
if !names.insert(field.name.clone()) {
bail!("Duplicate resource field `{}`.", field.name);
}
Ok(field)
})
.collect()
}
fn parse(definition: &str) -> Result<Self> {
let (shape, default) = definition
.split_once('=')
.map_or((definition, None), |(shape, value)| {
(shape, Some(value.to_owned()))
});
let mut parts = shape.split(':');
let name = parts.next().unwrap_or_default();
crate::names::validate_name(name, false)?;
if name != name.to_snake_case()
|| name.len() > 48
|| name.bytes().any(|c| c.is_ascii_uppercase())
|| name == "id"
|| name.starts_with('_')
{
bail!("Use a lowercase snake_case field name; `id` is generated automatically.");
}
let ty = parts
.next()
.context("Expected name:type, for example title:string")?;
let nullable = ty.ends_with('?');
if ty.trim_end_matches('?') == "references" {
if ty.matches('?').count() > 1 {
bail!("Use a single trailing ? for nullable references.");
}
let target = parts
.next()
.context("References require a target resource, such as post_id:references:Post")?;
let target_names = crate::names::GeneratedNames::new(target)?;
if name != format!("{}_id", target_names.module) {
bail!(
"Reference to {target} must use the field name {}_id.",
target_names.module
);
}
let on_delete = match parts.next() {
None | Some("on_delete_restrict") => DeleteBehavior::Restrict,
Some("on_delete_cascade") => DeleteBehavior::Cascade,
Some("on_delete_set_null") if nullable => DeleteBehavior::SetNull,
Some("on_delete_set_null") => bail!("on_delete_set_null requires a nullable reference (references?)."),
Some(flag) => bail!("Unknown reference modifier `{flag}`; use on_delete_restrict, on_delete_cascade or on_delete_set_null."),
};
if parts.next().is_some() || default.is_some() {
bail!("References accept one delete modifier and no default value.");
}
return Ok(Self {
name: name.into(),
kind: Kind::Integer,
nullable,
unique: false,
index: true,
default: None,
reference: Some(Reference {
target: target_names.module,
on_delete,
has_owner: false,
}),
enum_values: None,
enum_resource: None,
decimal: None,
});
}
let enum_values = if let Some(inner) = ty
.trim_end_matches('?')
.strip_prefix("enum[")
.and_then(|value| value.strip_suffix(']'))
{
let values = inner.split(',').map(str::to_owned).collect::<Vec<_>>();
if !(2..=32).contains(&values.len()) {
bail!("Enums require 2..=32 distinct values, for example enum[draft,published].");
}
let mut seen = BTreeSet::new();
for value in &values {
crate::names::validate_name(value, false)?;
if value != &value.to_snake_case()
|| value.len() > 32
|| !seen.insert(value.clone())
{
bail!("Enum values must be distinct lowercase snake_case names of at most 32 characters.");
}
}
Some(values)
} else {
None
};
let decimal = if let Some(inner) = ty
.trim_end_matches('?')
.strip_prefix("decimal(")
.and_then(|value| value.strip_suffix(')'))
{
let (precision, scale) = inner
.split_once(',')
.context("Decimal syntax is decimal(precision,scale), such as decimal(12,2)")?;
let precision = precision
.parse::<u32>()
.context("Decimal precision must be an integer")?;
let scale = scale
.parse::<u32>()
.context("Decimal scale must be an integer")?;
if !(1..=38).contains(&precision) || scale > precision {
bail!("Decimal precision must be 1..=38 and scale must be at most precision.");
}
Some((precision, scale))
} else {
None
};
let kind = match ty.trim_end_matches('?') {
"string" => Kind::String, "text" => Kind::Text, "boolean" => Kind::Boolean,
"integer" => Kind::Integer, "bigint" => Kind::Bigint, "float" => Kind::Float,
"uuid" => Kind::Uuid, "datetime" => Kind::Datetime, "date" => Kind::Date,
_ if enum_values.is_some() => Kind::Enum,
_ if decimal.is_some() => Kind::Decimal,
_ => bail!("Supported field types: string, text, boolean, integer, bigint, float, uuid, datetime, date, enum[values] and decimal(p,s); append ? for nullable."),
};
if ty.matches('?').count() > 1 {
bail!("Use a single trailing ? for nullable fields.");
}
let mut field = Self {
name: name.into(),
kind,
nullable,
unique: false,
index: false,
default,
reference: None,
enum_values,
enum_resource: None,
decimal,
};
for flag in parts {
match flag {
"unique" if !field.unique => field.unique = true,
"index" if !field.index => field.index = true,
_ => bail!("Unknown or repeated modifier `{flag}`; use :unique or :index."),
}
}
if field.unique && field.index {
bail!(":unique already creates an index; do not combine it with :index.");
}
if let Some(value) = &field.default {
field.validate_literal(value)?;
if !(field.nullable && value == "null") {
field.default = Some(match field.kind {
Kind::Integer | Kind::Bigint => value.parse::<i64>()?.to_string(),
Kind::Float => value.parse::<f64>()?.to_string(),
Kind::Uuid => uuid::Uuid::parse_str(value)?.to_string(),
Kind::Datetime => chrono::DateTime::parse_from_rfc3339(value)?
.with_timezone(&chrono::Utc)
.to_rfc3339(),
Kind::Date => chrono::NaiveDate::parse_from_str(value, "%Y-%m-%d")?.to_string(),
Kind::Enum => value.clone(),
Kind::Decimal => value.clone(),
_ => value.clone(),
});
}
}
Ok(field)
}
fn validate_literal(&self, value: &str) -> Result<()> {
if value == "null" && self.nullable {
return Ok(());
}
match self.kind {
Kind::String | Kind::Text => {
let max = if self.kind == Kind::String {
255
} else {
50_000
};
if value.is_empty() || value.chars().count() > max {
bail!("String defaults must contain 1..={max} characters.");
}
}
Kind::Boolean => {
value
.parse::<bool>()
.context("Boolean defaults must be true or false")?;
}
Kind::Integer => {
value
.parse::<i32>()
.context("Integer defaults must fit i32")?;
}
Kind::Bigint => {
value
.parse::<i64>()
.context("Bigint defaults must fit i64")?;
}
Kind::Float => {
if !value
.parse::<f64>()
.context("Float defaults must be numeric")?
.is_finite()
{
bail!("Float defaults must be finite JSON numbers.");
}
}
Kind::Uuid => {
uuid::Uuid::parse_str(value).context("UUID defaults must be valid UUIDs")?;
}
Kind::Datetime => {
let datetime = chrono::DateTime::parse_from_rfc3339(value)
.context("Datetime defaults must include an RFC3339 timezone")?;
let year = chrono::Datelike::year(&datetime.with_timezone(&chrono::Utc));
if !(1..=9999).contains(&year)
|| datetime.timestamp_subsec_nanos() >= 1_000_000_000
|| !datetime.timestamp_subsec_nanos().is_multiple_of(1000)
{
bail!("Portable datetime defaults require UTC years 0001..9999, no leap seconds and at most microsecond precision.");
}
}
Kind::Date => {
let date = chrono::NaiveDate::parse_from_str(value, "%Y-%m-%d")
.context("Date defaults must use YYYY-MM-DD")?;
if !(1..=9999).contains(&chrono::Datelike::year(&date)) {
bail!("Portable date defaults require years 0001..9999.");
}
}
Kind::Enum => {
if !self
.enum_values
.as_ref()
.is_some_and(|values| values.iter().any(|item| item == value))
{
bail!("Enum default must be one of its declared values.");
}
}
Kind::Decimal => {
let (precision, scale) = self.decimal.expect("parsed decimal");
if !valid_decimal(value, precision, scale) {
bail!("Decimal value must be an exact string with at most {} integer and {scale} fractional digits; exponents and leading plus signs are unsupported.", precision - scale);
}
}
}
Ok(())
}
pub fn entity_type(&self) -> String {
self.wrap(match self.kind {
Kind::String | Kind::Text | Kind::Decimal => "String",
Kind::Boolean => "bool",
Kind::Integer => "i32",
Kind::Bigint => "i64",
Kind::Float => "f64",
Kind::Uuid => "capy::uuid::Uuid",
Kind::Datetime => "capy::chrono::DateTime<capy::chrono::FixedOffset>",
Kind::Date => "capy::chrono::NaiveDate",
Kind::Enum => return self.wrap(&self.enum_type()),
})
}
pub fn wire_type(&self) -> String {
if self.kind == Kind::Bigint {
self.wrap("String")
} else {
self.entity_type()
}
}
fn wrap(&self, ty: &str) -> String {
if self.nullable {
format!("Option<{ty}>")
} else {
ty.into()
}
}
pub fn literal(&self, value: &str, wire: bool) -> String {
if value == "null" && self.nullable {
return "None".into();
}
let literal = match self.kind {
Kind::String | Kind::Text | Kind::Decimal => format!("{value:?}.to_owned()"),
Kind::Bigint if wire => format!("{value:?}.to_owned()"),
Kind::Boolean => value.to_owned(),
Kind::Integer | Kind::Bigint => {
value.parse::<i64>().expect("validated integer").to_string()
}
Kind::Float => format!("{:?}_f64", value.parse::<f64>().expect("validated float")),
Kind::Uuid | Kind::Datetime | Kind::Date => {
format!("{value:?}.parse().expect(\"validated generated default\")")
}
Kind::Enum => format!(
"{}::{}",
self.enum_type(),
heck::ToUpperCamelCase::to_upper_camel_case(value)
),
};
if self.nullable {
format!("Some({literal})")
} else {
literal
}
}
pub fn sample(&self) -> &str {
if self.kind == Kind::Enum {
return self
.default
.as_deref()
.unwrap_or_else(|| self.enum_values.as_ref().expect("parsed enum")[0].as_str());
}
if self.kind == Kind::Decimal {
let (precision, scale) = self.decimal.expect("parsed decimal");
return self.default.as_deref().unwrap_or(if scale == 0 {
"1"
} else if precision == scale {
"0.1"
} else if scale == 1 {
"1.2"
} else {
"1.25"
});
}
self.default.as_deref().unwrap_or(match self.kind {
Kind::String => "Example",
Kind::Text => "Example content",
Kind::Boolean => "false",
Kind::Integer | Kind::Bigint => "1",
Kind::Float => "1.5",
Kind::Uuid => "00000000-0000-4000-8000-000000000001",
Kind::Datetime => "2026-01-01T00:00:00+00:00",
Kind::Date => "2026-01-01",
Kind::Enum => unreachable!("handled above"),
Kind::Decimal => unreachable!("handled above"),
})
}
pub fn enum_type(&self) -> String {
use heck::ToUpperCamelCase;
let resource = self
.enum_resource
.as_deref()
.expect("enum belongs to a resource");
format!(
"crate::app::models::{resource}::{}{}",
resource.to_upper_camel_case(),
self.name.to_upper_camel_case()
)
}
pub fn decimal_pattern(&self) -> String {
let (precision, scale) = self.decimal.expect("parsed decimal");
let integer = precision - scale;
let whole = if integer == 0 {
"0".into()
} else if integer == 1 {
"(0|[1-9])".into()
} else {
format!("(0|[1-9][0-9]{{0,{}}})", integer - 1)
};
let fraction = if scale == 0 {
String::new()
} else {
format!(r"(\.[0-9]{{1,{scale}}})?")
};
format!("^-?{whole}{fraction}$")
}
}
pub(crate) fn valid_decimal(value: &str, precision: u32, scale: u32) -> bool {
let unsigned = value.strip_prefix('-').unwrap_or(value);
let (whole, fraction) = unsigned.split_once('.').unwrap_or((unsigned, ""));
let integer_digits = if whole == "0" { 0 } else { whole.len() };
!whole.is_empty()
&& whole.bytes().all(|digit| digit.is_ascii_digit())
&& (whole == "0" || !whole.starts_with('0'))
&& integer_digits <= (precision - scale) as usize
&& fraction.len() <= scale as usize
&& fraction.bytes().all(|digit| digit.is_ascii_digit())
&& (!unsigned.contains('.') || !fraction.is_empty())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn all_types_modifiers_and_literals_are_validated_before_generation() {
for definition in [
"title:string",
"body:text",
"active:boolean=false",
"count:integer=-42",
"amount:bigint=9223372036854775807",
"ratio:float=1.25",
"key:uuid=00000000-0000-4000-8000-000000000001",
"created_at:datetime=2026-01-01T00:00:00Z",
"created_at:datetime=2026-01-01T00:00:00.123456Z",
"birthday:date=2024-02-29",
"slug:string:unique",
"category:integer:index",
"published_at:datetime?",
"title:string?=null",
"caption:string?=Hello=world",
] {
let field = Field::parse_all(&[definition.into()])
.unwrap_or_else(|error| panic!("{definition}: {error:#}"));
if let Some(default) = &field[0].default {
syn::parse_str::<syn::Expr>(&field[0].literal(default, true)).unwrap();
}
}
assert_eq!(Field::parse("amount:bigint").unwrap().wire_type(), "String");
assert_eq!(
Field::parse("amount:bigint?").unwrap().entity_type(),
"Option<i64>"
);
assert_eq!(
Field::parse("amount:bigint=+001")
.unwrap()
.default
.as_deref(),
Some("1")
);
assert_eq!(
Field::parse("key:uuid=123E4567E89B12D3A456426614174000")
.unwrap()
.default
.as_deref(),
Some("123e4567-e89b-12d3-a456-426614174000")
);
assert_eq!(
Field::parse("occurred:datetime=2026-01-01T12:00:00+02:00")
.unwrap()
.default
.as_deref(),
Some("2026-01-01T10:00:00+00:00")
);
}
#[test]
fn invalid_or_ambiguous_definitions_are_rejected() {
for definition in [
"",
"title",
"title:unknown",
"title:string??",
"id:integer",
"Title:string",
"type:string",
"x:string:unique:index",
"x:string:index:index",
"x:boolean=1",
"x:integer=2147483648",
"x:bigint=9223372036854775808",
"x:float=NaN",
"x:float=inf",
"x:uuid=no",
"x:datetime=2026-01-01",
"x:datetime=2026-01-01T00:00:00.123456789Z",
"x:datetime=2016-12-31T23:59:60Z",
"x:datetime=0000-01-01T00:00:00Z",
"x:datetime=9999-12-31T23:59:59-01:00",
"x:date=2026-02-30",
"x:date=0000-01-01",
"x:date=+10000-01-01",
"x:string=",
"x:boolean=null",
"x:string:default",
"x:decimal",
"a/b:string",
"x:integer=1;panic!()",
] {
assert!(
Field::parse_all(&[definition.into()]).is_err(),
"{definition}"
);
}
assert!(Field::parse_all(&[]).is_err());
assert!(Field::parse_all(&["name:string".into(), "name:text".into()]).is_err());
}
#[test]
fn references_require_a_conventional_name_and_safe_delete_policy() {
let required = Field::parse("post_id:references:Post").unwrap();
assert!(required.index);
assert!(!required.nullable);
assert_eq!(
required.reference.unwrap().on_delete,
DeleteBehavior::Restrict
);
let nullable = Field::parse("post_id:references?:Post:on_delete_set_null").unwrap();
assert!(nullable.nullable);
assert_eq!(
nullable.reference.unwrap().on_delete,
DeleteBehavior::SetNull
);
for invalid in [
"post_id:references",
"author_id:references:Post",
"post_id:references:Post:on_delete_set_null",
"post_id:references:Post=1",
"post_id:references:Post:unknown",
"post_id:references:Post:on_delete_cascade:index",
] {
assert!(Field::parse(invalid).is_err(), "{invalid}");
}
}
#[test]
fn enums_reject_open_or_ambiguous_values() {
let mut field = Field::parse("status:enum[draft,published,archived]=draft").unwrap();
field.enum_resource = Some("post".into());
assert_eq!(
field.enum_values.as_ref().unwrap(),
&["draft", "published", "archived"]
);
assert_eq!(field.entity_type(), "crate::app::models::post::PostStatus");
assert_eq!(
field.literal("draft", true),
"crate::app::models::post::PostStatus::Draft"
);
for invalid in [
"status:enum[]",
"status:enum[draft]",
"status:enum[draft,draft]",
"status:enum[draft,Published]",
"status:enum[draft,published,]",
"status:enum[draft,published]=unknown",
"status:enum[draft,published",
] {
assert!(Field::parse(invalid).is_err(), "{invalid}");
}
}
#[test]
fn decimals_keep_exact_strings_and_validate_precision_and_scale() {
let field = Field::parse("price:decimal(12,2)=1234567890.12").unwrap();
assert_eq!(field.entity_type(), "String");
assert_eq!(field.wire_type(), "String");
assert_eq!(
field.literal("1234567890.12", true),
"\"1234567890.12\".to_owned()"
);
assert!(valid_decimal("-0.01", 12, 2));
assert!(!valid_decimal("12345678901.12", 12, 2));
assert!(!valid_decimal("1.234", 12, 2));
assert!(!valid_decimal("1e2", 12, 2));
assert!(!valid_decimal("1.2.3", 12, 2));
assert!(!valid_decimal("+1.20", 12, 2));
for invalid in [
"price:decimal",
"price:decimal(0,0)",
"price:decimal(39,2)",
"price:decimal(2,3)",
"price:decimal(12,)",
"price:decimal(12,2)=1.234",
"price:decimal(12,2)=1e2",
] {
assert!(Field::parse(invalid).is_err(), "{invalid}");
}
}
}