sui-graphql-rust-sdk: add chain info methods with alias support [8/n]

Author: tpham-mysten

crates/sui-graphql-macros/src/lib.rs

@@ -158,29 +158,57 @@ fn derive_query_response_impl(input: DeriveInput) -> Result<TokenStream2, syn::E
 
 /// A segment in a field path.
 ///
-/// Paths like `"data.nodes[].name"` are parsed into segments:
-/// - `PathSegment { field: "data", is_array: false }`
-/// - `PathSegment { field: "nodes", is_array: true }`
-/// - `PathSegment { field: "name", is_array: false }`
+/// Segments can include an alias using `@` syntax for GraphQL aliases:
+/// - The field name (before `@`) is used for schema validation
+/// - The alias (after `@`) is used for JSON extraction
+///
+/// Examples:
+/// - `"data.nodes[].name"` parses to:
+///   - `{ field: "data", alias: None, is_array: false }`
+///   - `{ field: "nodes", alias: None, is_array: true }`
+///   - `{ field: "name", alias: None, is_array: false }`
+///
+/// - `"[email protected][].sequenceNumber"` parses to:
+///   - `{ field: "epoch", alias: None, is_array: false }`
+///   - `{ field: "checkpoints", alias: Some("firstCheckpoints"), is_array: false }`
+///   - `{ field: "nodes", alias: None, is_array: true }`
+///   - `{ field: "sequenceNumber", alias: None, is_array: false }`
 struct PathSegment<'a> {
-    /// The field name to access
+    /// The field name (used for schema validation)
     field: &'a str,
+    /// Optional alias (used for JSON extraction instead of field name)
+    alias: Option<&'a str>,
     /// Whether this is an array field (ends with `[]`)
     is_array: bool,
 }
 
 /// Parse a path string into segments.
 ///
-/// Each dot-separated part becomes a `PathSegment`. If it ends with `[]`, it's an array field.
+/// Each dot-separated part is parsed for:
+/// - Array suffix `[]` (e.g., `nodes[]`)
+/// - Alias syntax `@` (e.g., `checkpoints@firstCheckpoints`)
 fn parse_path(path: &str) -> Vec<PathSegment<'_>> {
     path.split('.')
         .map(|segment| {
-            let (field, is_array) = if let Some(stripped) = segment.strip_suffix("[]") {
+            // Check for array suffix first
+            let (segment, is_array) = if let Some(stripped) = segment.strip_suffix("[]") {
                 (stripped, true)
             } else {
                 (segment, false)
             };
-            PathSegment { field, is_array }
+
+            // Check for alias syntax: field@alias
+            let (field, alias) = if let Some(at_pos) = segment.find('@') {
+                (&segment[..at_pos], Some(&segment[at_pos + 1..]))
+            } else {
+                (segment, None)
+            };
+
+            PathSegment {
+                field,
+                alias,
+                is_array,
+            }
         })
         .collect()
 }
@@ -205,6 +233,7 @@ fn generate_field_extraction(path: &str, field_ident: &syn::Ident) -> TokenStrea
 
 /// Recursively generate extraction code by traversing path segments.
 ///
+/// For JSON extraction, uses the alias if present, otherwise uses the field name.
 /// Returns code that evaluates to `Result<T, String>` (caller adds `?` to unwrap).
 ///
 /// ## Example: Simple path `"object.address"`
@@ -242,20 +271,23 @@ fn generate_from_segments(full_path: &str, segments: &[PathSegment<'_>]) -> Toke
         };
     }
 
-    let segment = &segments[0];
-    let name = segment.field;
     let rest = generate_from_segments(full_path, &segments[1..]);
+    let segment = &segments[0];
+
+    // Use alias for JSON extraction if present, otherwise use field name
+    let json_key = segment.alias.unwrap_or(segment.field);
 
     if segment.is_array {
+        // Array field: check for null, then iterate and collect into Option<Vec>
         quote! {
             {
-                let field_value = current.get(#name)
-                    .ok_or_else(|| format!("missing field '{}' in path '{}'", #name, #full_path))?;
+                let field_value = current.get(#json_key)
+                    .ok_or_else(|| format!("missing field '{}' in path '{}'", #json_key, #full_path))?;
                 if field_value.is_null() {
                     Ok(None)
                 } else {
                     let array = field_value.as_array()
-                        .ok_or_else(|| format!("expected array at '{}' in path '{}'", #name, #full_path))?;
+                        .ok_or_else(|| format!("expected array at '{}' in path '{}'", #json_key, #full_path))?;
                     array.iter()
                         .map(|current| { #rest })
                         .collect::<Result<Vec<_>, String>>()
@@ -265,17 +297,15 @@ fn generate_from_segments(full_path: &str, segments: &[PathSegment<'_>]) -> Toke
         }
     } else {
         quote! {
-            {
-                let current = current.get(#name)
-                    .ok_or_else(|| format!("missing field '{}' in path '{}'", #name, #full_path))?;
-                // If null, skip remaining navigation and let serde handle it
-                // (returns Ok(None) for Option<T>, error for non-Option)
-                if current.is_null() {
-                    serde_json::from_value(current.clone())
-                        .map_err(|e| format!("failed to deserialize '{}': {}", #full_path, e))
-                } else {
-                    #rest
-                }
+            let current = current.get(#json_key)
+                .ok_or_else(|| format!("missing field '{}' in path '{}'", #json_key, #full_path))?;
+            // If null, skip remaining navigation and let serde handle it
+            // (returns Ok(None) for Option<T>, error for non-Option)
+            if current.is_null() {
+                serde_json::from_value(current.clone())
+                    .map_err(|e| format!("failed to deserialize '{}': {}", #full_path, e))
+            } else {
+                #rest
             }
         }
     }

crates/sui-graphql-macros/src/validation.rs

@@ -12,6 +12,10 @@ use crate::schema::Schema;
 /// - Validates that `objects` is a list type
 /// - Validates fields after `[]` against the list element type
 ///
+/// For aliased paths like `"[email protected][]"`:
+/// - Strips the alias (after `@`) and validates using the real field name
+/// - The alias is only used for JSON extraction, not schema validation
+///
 /// Returns the GraphQL type name of the final field.
 pub fn validate_path(schema: &Schema, path: &str, span: &syn::Ident) -> Result<String, syn::Error> {
     if path.is_empty() {
@@ -23,13 +27,26 @@ pub fn validate_path(schema: &Schema, path: &str, span: &syn::Ident) -> Result<S
     let mut current_type = "Query".to_string();
 
     for (i, segment) in segments.iter().enumerate() {
-        // Handle array iteration: "field[]"
-        if let Some(field_name) = segment.strip_suffix("[]") {
-            // Look up the field
-            let field = schema.get_field(&current_type, field_name).ok_or_else(|| {
-                field_not_found_error(schema, &current_type, field_name, path, span)
-            })?;
+        // Handle array iteration: "field[]" or "field@alias[]"
+        let (segment, is_array) = if let Some(stripped) = segment.strip_suffix("[]") {
+            (stripped, true)
+        } else {
+            (*segment, false)
+        };
+
+        // Strip alias if present: "field@alias" -> "field"
+        let field_name = if let Some(at_pos) = segment.find('@') {
+            &segment[..at_pos]
+        } else {
+            segment
+        };
+
+        // Look up the field
+        let field = schema
+            .get_field(&current_type, field_name)
+            .ok_or_else(|| field_not_found_error(schema, &current_type, field_name, path, span))?;
 
+        if is_array {
             // Verify it's a list type
             if !field.is_list {
                 return Err(syn::Error::new_spanned(
@@ -40,22 +57,14 @@ pub fn validate_path(schema: &Schema, path: &str, span: &syn::Ident) -> Result<S
                     ),
                 ));
             }
+        }
 
-            // Continue with the element type
-            current_type = field.type_name.clone();
-        } else {
-            // Regular field access
-            let field = schema
-                .get_field(&current_type, segment)
-                .ok_or_else(|| field_not_found_error(schema, &current_type, segment, path, span))?;
-
-            // If this is the last segment, return the type
-            if i == segments.len() - 1 {
-                return Ok(field.type_name.clone());
-            }
-
-            current_type = field.type_name.clone();
+        // If this is the last segment, return the type
+        if i == segments.len() - 1 {
+            return Ok(field.type_name.clone());
         }
+
+        current_type = field.type_name.clone();
     }
 
     // Should not reach here since we return in the loop for the last segment

crates/sui-graphql-macros/tests/compile/schema_validation_alias_invalid_field.rs

@@ -0,0 +1,11 @@
+use sui_graphql_macros::Response;
+
+/// Test that alias syntax validates the real field name (before @) against the schema.
+/// "nonExistentField" doesn't exist on Epoch type, so this should fail.
+#[derive(Response)]
+struct InvalidAlias {
+    #[field(path = "[email protected][].sequenceNumber")]
+    data: Option<Vec<u64>>,
+}
+
+fn main() {}

crates/sui-graphql-macros/tests/compile/schema_validation_alias_invalid_field.stderr

@@ -0,0 +1,5 @@
+error: Field 'nonExistentField' not found on type 'Epoch' in path '[email protected][].sequenceNumber'. Available fields: checkpoints, coinDenyList, endTimestamp, epochId, fundInflow, fundOutflow, fundSize, liveObjectSetDigest, netInflow, protocolConfigs, referenceGasPrice, safeMode, startTimestamp, storageFund, systemPackages, systemParameters, systemStakeSubsidy, systemStateVersion, totalCheckpoints, totalGasFees, totalStakeRewards, totalStakeSubsidies, totalTransactions, transactions, validatorSet
+ --> tests/compile/schema_validation_alias_invalid_field.rs:8:5
+  |
+8 |     data: Option<Vec<u64>>,
+  |     ^^^^

crates/sui-graphql-macros/tests/compile/schema_validation_with_alias.rs

@@ -0,0 +1,28 @@
+use sui_graphql_macros::Response;
+
+/// Test that alias syntax `field@alias` works correctly.
+/// The field name (before @) is validated against the schema,
+/// while the alias (after @) is used for JSON extraction.
+#[derive(Response)]
+struct EpochCheckpoints {
+    // "checkpoints" is the real field name validated against schema
+    // "firstCheckpoint" is the alias used for JSON extraction
+    #[field(path = "[email protected][].sequenceNumber")]
+    first_checkpoint_seq: Option<Vec<u64>>,
+}
+
+fn main() {
+    let json = serde_json::json!({
+        "epoch": {
+            "firstCheckpoint": {
+                "nodes": [
+                    { "sequenceNumber": 1000 },
+                    { "sequenceNumber": 1001 }
+                ]
+            }
+        }
+    });
+
+    let data = EpochCheckpoints::from_value(json).unwrap();
+    assert_eq!(data.first_checkpoint_seq, Some(vec![1000, 1001]));
+}

crates/sui-graphql-macros/tests/compile_tests.rs

@@ -5,6 +5,7 @@ fn compile_tests() {
     // Tests that should pass
     t.pass("tests/compile/basic_extraction.rs");
     t.pass("tests/compile/skip_validation.rs");
+    t.pass("tests/compile/schema_validation_with_alias.rs");
 
     // Tests that should fail with expected errors
     t.compile_fail("tests/compile/missing_field_path_attr.rs");
@@ -20,4 +21,5 @@ fn compile_tests() {
     t.compile_fail("tests/compile/schema_validation_field_after_list_suggestion.rs");
     t.compile_fail("tests/compile/schema_validation_array_on_non_list.rs");
     t.compile_fail("tests/compile/schema_validation_field_after_list_not_found.rs");
+    t.compile_fail("tests/compile/schema_validation_alias_invalid_field.rs");
 }