Merge pull request #167 from JasonXuDeveloper/claude/optimize-serializer-performance-011CUoq3vskRx4B6SWwa2wih

feat(generator): add NinoRefDeserializationAttribute for custom objec…

Author: JasonXuDeveloper

src/Nino.Core/NinoDeserializer.cs

@@ -21,6 +21,16 @@ public static void Deserialize<T>(ReadOnlySpan<byte> data, ref T value)
             DeserializeRef(ref value, ref reader);
         }
 
+        /// <summary>
+        /// Deserialize data into an existing object reference (convenience overload for ReadOnlySpan)
+        /// </summary>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static void DeserializeRef<T>(ref T value, ReadOnlySpan<byte> data)
+        {
+            var reader = new Reader(data);
+            DeserializeRef(ref value, ref reader);
+        }
+
         // ULTIMATE: Zero-overhead single entry point
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static void DeserializeRef<T>(ref T value, ref Reader reader)
@@ -106,6 +116,16 @@ public static object DeserializeBoxed(ref Reader reader, Type type = null)
             return typeDeserializer.outOverload(ref reader);
         }
 
+        /// <summary>
+        /// Deserialize data into an existing boxed object reference (convenience overload for ReadOnlySpan)
+        /// </summary>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static void DeserializeRefBoxed(ref object val, ReadOnlySpan<byte> data, Type type = null)
+        {
+            var reader = new Reader(data);
+            DeserializeRefBoxed(ref val, ref reader, type);
+        }
+
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static void DeserializeRefBoxed(ref object val, ref Reader reader, Type type = null)
         {

src/Nino.Core/NinoRefDeserializationAttribute.cs

@@ -0,0 +1,26 @@
+using System;
+
+namespace Nino.Core
+{
+    /// <summary>
+    /// Mark a public static parameterless method that returns an instance of the type.
+    /// This method will be called to instantiate objects during deserialization,
+    /// allowing custom object pooling or initialization logic.
+    /// <para>
+    /// The method must be:
+    /// - Public
+    /// - Static
+    /// - Parameterless
+    /// - Return the same type as the declaring class
+    /// </para>
+    /// <para>
+    /// When this attribute is present:
+    /// - In Deserialize: calls this method, then uses DeserializeRef to populate the instance
+    /// - In DeserializeRef: calls this method only if the ref parameter is null
+    /// </para>
+    /// </summary>
+    [AttributeUsage(AttributeTargets.Method)]
+    public class NinoRefDeserializationAttribute : Attribute
+    {
+    }
+}

src/Nino.Generator/Common/DeserializerGenerator.Trivial.cs

@@ -1039,8 +1039,20 @@ private void WriteMembersWithCustomConstructor(SourceProductionContext spc,
         string valName,
         string[] constructorMember,
         IMethodSymbol? constructor,
-        string indent = "")
+        string indent = "",
+        bool checkRefDeserializationNull = true)
     {
+        // RefDeserializationMethod: only check null when needed (ref path)
+        // Skip for non-ref path where instance is already created
+        if (checkRefDeserializationNull && !string.IsNullOrEmpty(nt.RefDeserializationMethod))
+        {
+            sb.AppendLine($"{indent}            if ({valName} == null)");
+            sb.AppendLine($"{indent}            {{");
+            sb.AppendLine($"{indent}                // use NinoRefDeserializationAttribute method: {nt.RefDeserializationMethod}");
+            sb.AppendLine($"{indent}                {valName} = {nt.TypeSymbol.GetDisplayString()}.{nt.RefDeserializationMethod}();");
+            sb.AppendLine($"{indent}            }}");
+        }
+
         var (vars, privateVars, args, tupleMap) =
             WriteMembers(valName, sb, nt, constructorMember, constructor == null, spc, indent);
 
@@ -1208,6 +1220,16 @@ private void CreateInstance(SourceProductionContext spc, StringBuilder sb,
             return;
         }
 
+        // Check for NinoRefDeserializationAttribute
+        if (!string.IsNullOrEmpty(nt.RefDeserializationMethod))
+        {
+            sb.AppendLine($"{indent}            // use NinoRefDeserializationAttribute method: {nt.RefDeserializationMethod}");
+            sb.AppendLine($"{indent}            {valName} = {nt.TypeSymbol.GetDisplayString()}.{nt.RefDeserializationMethod}();");
+            // Instance already created, skip null check
+            WriteMembersWithCustomConstructor(spc, sb, nt, valName, [], null, indent, checkRefDeserializationNull: false);
+            return;
+        }
+
         //if this subtype contains a custom constructor, use it
         //go through all constructors and find the one with the NinoConstructor attribute
         //get constructors of the symbol

src/Nino.Generator/Metadata/NinoType.cs

@@ -12,6 +12,7 @@ public class NinoType
     public ImmutableList<NinoType> Parents { get; set; }
     public string CustomSerializer { get; set; }
     public string CustomDeserializer { get; set; }
+    public string RefDeserializationMethod { get; set; }
 
     public NinoType(Compilation compilation, ITypeSymbol typeSymbol, ImmutableList<NinoMember>? members,
         ImmutableList<NinoType>? parents)
@@ -32,6 +33,7 @@ public NinoType(Compilation compilation, ITypeSymbol typeSymbol, ImmutableList<N
 
         CustomSerializer = "";
         CustomDeserializer = "";
+        RefDeserializationMethod = "";
 
         var declaredTypeAssembly = typeSymbol.ContainingAssembly;
         bool isSameAssembly = declaredTypeAssembly.Equals(compilation.Assembly,
@@ -140,6 +142,11 @@ public override string ToString()
             sb.AppendLine($"CustomDeserializer: {CustomDeserializer}");
         }
 
+        if (!string.IsNullOrEmpty(RefDeserializationMethod))
+        {
+            sb.AppendLine($"RefDeserializationMethod: {RefDeserializationMethod}");
+        }
+
         sb.AppendLine("Parents:");
         foreach (var parent in Parents)
         {

src/Nino.Generator/NinoAnalyzer.cs

@@ -222,6 +222,56 @@ public override void Initialize(AnalysisContext context)
             SyntaxKind.ClassDeclaration, SyntaxKind.StructDeclaration,
             SyntaxKind.InterfaceDeclaration, SyntaxKind.RecordDeclaration,
             SyntaxKind.RecordStructDeclaration);
+
+        // Validate NinoRefDeserializationAttribute usage - NINO012
+        context.RegisterSymbolAction(
+            symbolContext =>
+            {
+                var symbol = symbolContext.Symbol;
+                if (symbol is not IMethodSymbol methodSymbol) return;
+
+                var hasAttribute = methodSymbol.GetAttributesCache().Any(a =>
+                    a.AttributeClass != null &&
+                    a.AttributeClass.ToDisplayString().EndsWith("NinoRefDeserializationAttribute"));
+
+                if (!hasAttribute) return;
+
+                var errors = new List<string>();
+
+                // Check if method is public
+                if (methodSymbol.DeclaredAccessibility != Accessibility.Public)
+                {
+                    errors.Add("must be public");
+                }
+
+                // Check if method is static
+                if (!methodSymbol.IsStatic)
+                {
+                    errors.Add("must be static");
+                }
+
+                // Check if method is parameterless
+                if (methodSymbol.Parameters.Length > 0)
+                {
+                    errors.Add("must be parameterless");
+                }
+
+                // Check if method returns the containing type
+                if (!SymbolEqualityComparer.Default.Equals(methodSymbol.ReturnType, methodSymbol.ContainingType))
+                {
+                    errors.Add($"must return {methodSymbol.ContainingType.ToDisplayString()}");
+                }
+
+                if (errors.Count > 0)
+                {
+                    symbolContext.ReportDiagnostic(Diagnostic.Create(
+                        SupportedDiagnostics[11], // NINO012
+                        methodSymbol.Locations.First(),
+                        methodSymbol.Name,
+                        string.Join(", ", errors)));
+                }
+            },
+            SymbolKind.Method);
     }
 
     public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics =>
@@ -279,7 +329,12 @@ public override void Initialize(AnalysisContext context)
                 "Member type cannot be serialized",
                 "Member '{0}' of type '{1}' in NinoType '{2}' has an unrecognizable type and will be skipped during serialization/deserialization",
                 "Nino",
-                DiagnosticSeverity.Warning, true)
+                DiagnosticSeverity.Warning, true),
+            new DiagnosticDescriptor("NINO012",
+                "Invalid NinoRefDeserializationAttribute usage",
+                "Method '{0}' with [NinoRefDeserialization] {1}",
+                "Nino",
+                DiagnosticSeverity.Error, true)
         );
 
     private static bool IsValidNinoFormatter(INamedTypeSymbol formatterType, ITypeSymbol memberType)

src/Nino.Generator/Parser/CSharpParser.cs

@@ -354,6 +354,22 @@ void AddMembers(NinoType type)
                     }
                 }
 
+                //check for NinoRefDeserializationAttribute on public static parameterless methods
+                var refDeserMethod = typeSymbol.GetMembers().OfType<IMethodSymbol>()
+                    .FirstOrDefault(m =>
+                        m.DeclaredAccessibility == Accessibility.Public &&
+                        m.IsStatic &&
+                        m.Parameters.Length == 0 &&
+                        SymbolEqualityComparer.Default.Equals(m.ReturnType, typeSymbol) &&
+                        m.GetAttributesCache().Any(a =>
+                            a.AttributeClass != null &&
+                            a.AttributeClass.ToDisplayString().EndsWith("NinoRefDeserializationAttribute")));
+
+                if (refDeserMethod != null)
+                {
+                    ninoType.RefDeserializationMethod = refDeserMethod.Name;
+                }
+
                 //add to map
                 typeMap[typeSymbol] = ninoType;
 

src/Nino.UnitTests/AnalyzerTest.cs

@@ -438,4 +438,134 @@ await SetUpSourceGeneratorTest(code,
                 .WithArguments("UnsupportedTask", "System.Threading.Tasks.Task<int>", "TestClassWithTask")
         ).RunAsync();
     }
+
+    [TestMethod]
+    public async Task TestNino012_NotPublic()
+    {
+        var code = @"
+using Nino.Core;
+
+[NinoType]
+public class TestClass
+{
+    [NinoRefDeserialization]
+    private static TestClass GetInstance() => new TestClass();
+
+    public int Value;
+}
+";
+
+        await SetUpAnalyzerTest(code,
+            Verify.Diagnostic("NINO012")
+                .WithSpan(8, 30, 8, 41)
+                .WithArguments("GetInstance", "must be public")).RunAsync();
+    }
+
+    [TestMethod]
+    public async Task TestNino012_NotStatic()
+    {
+        var code = @"
+using Nino.Core;
+
+[NinoType]
+public class TestClass
+{
+    [NinoRefDeserialization]
+    public TestClass GetInstance() => new TestClass();
+
+    public int Value;
+}
+";
+
+        await SetUpAnalyzerTest(code,
+            Verify.Diagnostic("NINO012")
+                .WithSpan(8, 22, 8, 33)
+                .WithArguments("GetInstance", "must be static")).RunAsync();
+    }
+
+    [TestMethod]
+    public async Task TestNino012_HasParameters()
+    {
+        var code = @"
+using Nino.Core;
+
+[NinoType]
+public class TestClass
+{
+    [NinoRefDeserialization]
+    public static TestClass GetInstance(int value) => new TestClass();
+
+    public int Value;
+}
+";
+
+        await SetUpAnalyzerTest(code,
+            Verify.Diagnostic("NINO012")
+                .WithSpan(8, 29, 8, 40)
+                .WithArguments("GetInstance", "must be parameterless")).RunAsync();
+    }
+
+    [TestMethod]
+    public async Task TestNino012_WrongReturnType()
+    {
+        var code = @"
+using Nino.Core;
+
+[NinoType]
+public class TestClass
+{
+    [NinoRefDeserialization]
+    public static object GetInstance() => new TestClass();
+
+    public int Value;
+}
+";
+
+        await SetUpAnalyzerTest(code,
+            Verify.Diagnostic("NINO012")
+                .WithSpan(8, 26, 8, 37)
+                .WithArguments("GetInstance", "must return TestClass")).RunAsync();
+    }
+
+    [TestMethod]
+    public async Task TestNino012_MultipleErrors()
+    {
+        var code = @"
+using Nino.Core;
+
+[NinoType]
+public class TestClass
+{
+    [NinoRefDeserialization]
+    private object GetInstance(int value) => new TestClass();
+
+    public int Value;
+}
+";
+
+        await SetUpAnalyzerTest(code,
+            Verify.Diagnostic("NINO012")
+                .WithSpan(8, 20, 8, 31)
+                .WithArguments("GetInstance", "must be public, must be static, must be parameterless, must return TestClass")).RunAsync();
+    }
+
+    [TestMethod]
+    public async Task TestNino012_ValidUsage()
+    {
+        var code = @"
+using Nino.Core;
+
+[NinoType]
+public class TestClass
+{
+    [NinoRefDeserialization]
+    public static TestClass GetInstance() => new TestClass();
+
+    public int Value;
+}
+";
+
+        // No diagnostics expected for valid usage
+        await SetUpAnalyzerTest(code).RunAsync();
+    }
 }