fraiseql_core/schema/compiled/
mutation.rs

1use indexmap::IndexMap;
2use serde::{Deserialize, Serialize};
3
4use super::argument::ArgumentDefinition;
5use crate::schema::{field_type::DeprecationInfo, security_config::InjectedParamSource};
6
7/// A mutation definition compiled from `@fraiseql.mutation`.
8///
9/// Mutations are declarative bindings to database functions.
10/// They describe *which function* to call, not arbitrary logic.
11///
12/// # Example
13///
14/// ```
15/// use fraiseql_core::schema::{MutationDefinition, MutationOperation};
16///
17/// let mutation = MutationDefinition::new("createUser", "User");
18/// ```
19#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
20pub struct MutationDefinition {
21    /// Mutation name (e.g., "createUser").
22    pub name: String,
23
24    /// Return type name.
25    pub return_type: String,
26
27    /// Input arguments.
28    #[serde(default)]
29    pub arguments: Vec<ArgumentDefinition>,
30
31    /// Description.
32    #[serde(default, skip_serializing_if = "Option::is_none")]
33    pub description: Option<String>,
34
35    /// SQL operation type.
36    #[serde(default)]
37    pub operation: MutationOperation,
38
39    /// Deprecation information (from @deprecated directive).
40    /// When set, this mutation is marked as deprecated in the schema.
41    #[serde(default, skip_serializing_if = "Option::is_none")]
42    pub deprecation: Option<DeprecationInfo>,
43
44    /// PostgreSQL function name to call for this mutation.
45    ///
46    /// When set, the runtime calls `SELECT * FROM {sql_source}($1, $2, ...)` with the
47    /// mutation arguments in `ArgumentDefinition` order, and parses the result as an
48    /// `app.mutation_response` composite row.
49    #[serde(default, skip_serializing_if = "Option::is_none")]
50    pub sql_source: Option<String>,
51
52    /// Server-side parameters injected from JWT claims at runtime.
53    ///
54    /// Keys are SQL parameter names. Values describe where to source the runtime value.
55    /// These params are NOT exposed as GraphQL arguments.
56    ///
57    /// For mutations: injected params are appended to the positional function call args
58    /// **after** client-provided arguments, in map insertion order. The SQL function
59    /// signature must declare the injected parameters last.
60    ///
61    /// Works on PostgreSQL, SQL Server, and MySQL. SQLite has no stored-routine mechanism
62    /// and will return an error if inject is configured on a mutation.
63    #[serde(default, skip_serializing_if = "IndexMap::is_empty")]
64    pub inject_params: IndexMap<String, InjectedParamSource>,
65
66    /// Fact tables whose version counter should be bumped after this mutation succeeds.
67    ///
68    /// When the mutation PostgreSQL function returns successfully, the runtime calls
69    /// `SELECT bump_tf_version($1)` for each listed table, incrementing the version used
70    /// in fact-table cache keys. This ensures that analytic/aggregate queries backed by
71    /// `FactTableVersionStrategy::VersionTable` are automatically invalidated.
72    ///
73    /// Each entry must be a valid SQL identifier validated at compile time.
74    ///
75    /// # Example
76    ///
77    /// ```python
78    /// @fraiseql.mutation(
79    ///     sql_source="fn_create_order",
80    ///     invalidates_fact_tables=["tf_sales", "tf_order_count"],
81    /// )
82    /// def create_order(amount: Decimal) -> Order: ...
83    /// ```
84    #[serde(default, skip_serializing_if = "Vec::is_empty")]
85    pub invalidates_fact_tables: Vec<String>,
86
87    /// View names whose cached query results should be invalidated after this
88    /// mutation succeeds.
89    ///
90    /// When the `CachedDatabaseAdapter` is active, the runtime calls
91    /// `invalidate_views()` with these names, clearing all cache entries that
92    /// read from the specified views.
93    ///
94    /// If empty and the mutation return type has a `sql_source`, the runtime
95    /// infers the primary view from the return type.
96    ///
97    /// Each entry must be a valid SQL identifier validated at compile time.
98    #[serde(default, skip_serializing_if = "Vec::is_empty")]
99    pub invalidates_views: Vec<String>,
100
101    /// Custom REST path override (e.g., `"/users/{id}"`).
102    #[serde(default, skip_serializing_if = "Option::is_none")]
103    pub rest_path: Option<String>,
104
105    /// REST HTTP method override (e.g., `"POST"`, `"PUT"`, `"PATCH"`).
106    #[serde(default, skip_serializing_if = "Option::is_none")]
107    pub rest_method: Option<String>,
108
109    /// PostgreSQL upsert function name for `PUT` semantics (insert-or-update).
110    #[serde(default, skip_serializing_if = "Option::is_none")]
111    pub upsert_function: Option<String>,
112}
113
114impl MutationDefinition {
115    /// Create a new mutation definition.
116    #[must_use]
117    pub fn new(name: impl Into<String>, return_type: impl Into<String>) -> Self {
118        Self {
119            name:                    name.into(),
120            return_type:             return_type.into(),
121            arguments:               Vec::new(),
122            description:             None,
123            operation:               MutationOperation::default(),
124            deprecation:             None,
125            sql_source:              None,
126            inject_params:           IndexMap::new(),
127            invalidates_fact_tables: Vec::new(),
128            invalidates_views:       Vec::new(),
129            rest_path:               None,
130            rest_method:             None,
131            upsert_function:         None,
132        }
133    }
134
135    /// Mark this mutation as deprecated.
136    ///
137    /// # Example
138    ///
139    /// ```
140    /// use fraiseql_core::schema::MutationDefinition;
141    ///
142    /// let mutation = MutationDefinition::new("oldCreateUser", "User")
143    ///     .deprecated(Some("Use 'createUser' instead".to_string()));
144    /// assert!(mutation.is_deprecated());
145    /// ```
146    #[must_use]
147    pub fn deprecated(mut self, reason: Option<String>) -> Self {
148        self.deprecation = Some(DeprecationInfo { reason });
149        self
150    }
151
152    /// Check if this mutation is deprecated.
153    #[must_use]
154    pub const fn is_deprecated(&self) -> bool {
155        self.deprecation.is_some()
156    }
157
158    /// Get the deprecation reason if deprecated.
159    #[must_use]
160    pub fn deprecation_reason(&self) -> Option<&str> {
161        self.deprecation.as_ref().and_then(|d| d.reason.as_deref())
162    }
163}
164
165/// Mutation operation types.
166///
167/// This enum describes what kind of database operation a mutation performs.
168#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
169#[serde(rename_all = "PascalCase")]
170#[non_exhaustive]
171pub enum MutationOperation {
172    /// INSERT into a table.
173    Insert {
174        /// Target table name.
175        table: String,
176    },
177
178    /// UPDATE a table.
179    Update {
180        /// Target table name.
181        table: String,
182    },
183
184    /// DELETE from a table.
185    Delete {
186        /// Target table name.
187        table: String,
188    },
189
190    /// Custom mutation (for complex operations).
191    #[default]
192    Custom,
193}
fraiseql_core/schema/compiled/mutation.rs

fraiseql_core/schema/compiled/
mutation.rs
