feat: Implement collection count optimization for collection deserialization, including a new [GenJsonSkipCountOptimization] attribute and updated documentation.

Author: PereViader

README.md

@@ -289,6 +289,29 @@ public partial class Cat : Animal
 
 **Deserialization**: `Animal.FromJson(...)` will inspect the `$type` property and deserialize into the correct derived type (`Dog` or `Cat`). If the type is unknown or missing (for abstract bases), it returns `null`.
 
+### 11. Collection Count Optimization
+
+GenJson optimizes collection deserialization (Lists, Arrays, Dictionaries) by pre-allocating the collection with the exact size. This avoids resizing overhead during population.
+
+**How it works:**
+- **Serialization**: The generator automatically emits a hidden property named after the collection with a `$` prefix (e.g., `"$MyList": 5`) immediately before the collection property.
+- **Deserialization**: The parser reads this count property first and initializes the collection with the correct capacity (e.g., `new List<int>(5)`).
+
+> [!NOTE]
+> GenJson can still parse standard JSON without the count property. If the property is missing, it will automatically fall back to standard resizing behavior.
+
+**Disabling Optimization:**
+If you need strictly standard JSON or cannot support the extra property, you can disable this optimization using the `[GenJsonSkipCountOptimization]` attribute on your class or struct.
+
+```csharp
+[GenJson]
+[GenJsonSkipCountOptimization] // Disables usage of $MyList property
+public partial class MyClass
+{
+    public List<int> MyList { get; set; }
+}
+```
+
 ## How It Works
 
 GenJson analyzes your code during compilation and generates specialized serialization code.

src/GenJson.Generator/GenJsonSourceGenerator.cs

@@ -85,6 +85,7 @@ public record ClassData(
     bool HasGenJsonBase,
     bool IsNullableContext,
     string? PolymorphicDiscriminatorProp,
+    bool SkipCountOptimization,
     EquatableList<DerivedTypeData> DerivedTypes);
 
 public record DerivedTypeData(string TypeName, string DiscriminatorValue, bool IsIntDiscriminator);
@@ -312,7 +313,9 @@ private static bool IsSyntaxNodeValid(SyntaxNode node, CancellationToken ct)
             }
         }
 
-        return new ClassData(typeSymbol.Name, typeNameSpace, new EquatableList<PropertyData>(constructorArgs), new EquatableList<PropertyData>(initProperties), new EquatableList<PropertyData>(properties), keyword, typeSymbol.IsAbstract, hasGenJsonBase, isNullableContext, polymorphicDiscriminatorProp, new EquatableList<DerivedTypeData>(derivedTypes));
+        bool skipCountOptimization = typeSymbol.GetAttributes().Any(a => a.AttributeClass?.ToDisplayString() == "GenJson.GenJsonSkipCountOptimizationAttribute");
+
+        return new ClassData(typeSymbol.Name, typeNameSpace, new EquatableList<PropertyData>(constructorArgs), new EquatableList<PropertyData>(initProperties), new EquatableList<PropertyData>(properties), keyword, typeSymbol.IsAbstract, hasGenJsonBase, isNullableContext, polymorphicDiscriminatorProp, skipCountOptimization, new EquatableList<DerivedTypeData>(derivedTypes));
     }
 
     private static PropertyData? GetPropertyForParameter(
@@ -659,7 +662,7 @@ private void Generate(SourceProductionContext context, ClassData data)
 
             sb.Append(indent);
             sb.AppendLine("propertyCount++;");
-            if (prop.Type is GenJsonDataType.Enumerable en)
+            if (!data.SkipCountOptimization && prop.Type is GenJsonDataType.Enumerable en)
             {
                 if (en.IsArray)
                 {
@@ -704,7 +707,7 @@ private void Generate(SourceProductionContext context, ClassData data)
                     sb.AppendLine("}");
                 }
             }
-            else if (prop.Type is GenJsonDataType.Dictionary)
+            else if (!data.SkipCountOptimization && prop.Type is GenJsonDataType.Dictionary)
             {
                 sb.Append(indent);
                 sb.Append("size += ");
@@ -877,7 +880,7 @@ private void Generate(SourceProductionContext context, ClassData data)
                 else stateSpan = 1;
             }
 
-            if (prop.Type is GenJsonDataType.Enumerable en)
+            if (!data.SkipCountOptimization && prop.Type is GenJsonDataType.Enumerable en)
             {
                 if (en.IsArray)
                 {
@@ -938,7 +941,7 @@ private void Generate(SourceProductionContext context, ClassData data)
                     sb.AppendLine("}");
                 }
             }
-            else if (prop.Type is GenJsonDataType.Dictionary)
+            else if (!data.SkipCountOptimization && prop.Type is GenJsonDataType.Dictionary)
             {
                 sb.Append(indent);
                 sb.Append("global::GenJson.GenJsonWriter.WriteString(span, ref index, \"$");
@@ -1078,7 +1081,7 @@ private void Generate(SourceProductionContext context, ClassData data)
             sb.Append(prop.Name);
             sb.AppendLine(" = default;");
 
-            if (prop.Type is GenJsonDataType.Enumerable or GenJsonDataType.Dictionary)
+            if (!data.SkipCountOptimization && (prop.Type is GenJsonDataType.Enumerable or GenJsonDataType.Dictionary))
             {
                 sb.Append("            int _");
                 sb.Append(prop.Name);
@@ -1162,7 +1165,7 @@ private void Generate(SourceProductionContext context, ClassData data)
         sb.AppendLine("                bool matched = false;");
         foreach (var prop in allProperties)
         {
-            if (prop.Type is GenJsonDataType.Enumerable or GenJsonDataType.Dictionary)
+            if (!data.SkipCountOptimization && (prop.Type is GenJsonDataType.Enumerable or GenJsonDataType.Dictionary))
             {
                 sb.Append("                if (global::GenJson.GenJsonParser.MatchesKey(json, ref index, \"$");
                 sb.Append(prop.JsonName);
@@ -1182,7 +1185,7 @@ private void Generate(SourceProductionContext context, ClassData data)
             sb.AppendLine("\"))");
             sb.AppendLine("                {");
             sb.AppendLine("                    if (!global::GenJson.GenJsonParser.TryExpect(json, ref index, ':')) return null;");
-            GenerateParseValue(sb, prop.Type, "_" + prop.Name, "                    ", 0, (prop.Type is GenJsonDataType.Enumerable or GenJsonDataType.Dictionary) ? $"_{prop.Name}_count" : null);
+            GenerateParseValue(sb, prop.Type, "_" + prop.Name, "                    ", 0, (!data.SkipCountOptimization && (prop.Type is GenJsonDataType.Enumerable or GenJsonDataType.Dictionary)) ? $"_{prop.Name}_count" : null);
             if (data.IsNullableContext && prop.IsValueType && !prop.IsNullable)
             {
                 sb.Append("                    _");

src/GenJson.Tests/TestSkipOptimization.cs

@@ -0,0 +1,48 @@
+using System.Collections.Generic;
+using NUnit.Framework;
+
+namespace GenJson.Tests;
+
+[GenJson]
+[GenJsonSkipCountOptimization]
+public partial record SkipOptimizationClass(List<int> List, int[] Array, Dictionary<string, int> Dictionary);
+
+public class TestSkipOptimization
+{
+    [Test]
+    public void TestSerialization_SkipsCountProperty()
+    {
+        var obj = new SkipOptimizationClass([1, 2], [3, 4], new() { { "5", 6 } });
+        var json = obj.ToJson();
+
+        // Expect NO count properties
+        var expected = """{"List":[1,2],"Array":[3,4],"Dictionary":{"5":6}}""";
+        Assert.That(json, Is.EqualTo(expected));
+    }
+
+    [Test]
+    public void TestDeserialization_WorksWithoutCountProperty()
+    {
+        var json = """{"List":[1,2],"Array":[3,4],"Dictionary":{"5":6}}""";
+        var obj = SkipOptimizationClass.FromJson(json)!;
+
+        Assert.That(obj, Is.Not.Null);
+        Assert.That(obj.List, Is.EqualTo(new List<int> { 1, 2 }));
+        Assert.That(obj.Array, Is.EqualTo(new int[] { 3, 4 }));
+        Assert.That(obj.Dictionary, Is.EqualTo(new Dictionary<string, int> { { "5", 6 } }));
+    }
+
+    [Test]
+    public void TestDeserialization_IgnoresCountPropertyIfPresent()
+    {
+        // Even if count property is present in JSON (e.g. from older version or other system), 
+        // it should be treated as unknown property and ignored since we are skipping optimization.
+        var json = """{"$List":2,"List":[1,2],"$Array":2,"Array":[3,4],"$Dictionary":1,"Dictionary":{"5":6}}""";
+        var obj = SkipOptimizationClass.FromJson(json)!;
+
+        Assert.That(obj, Is.Not.Null);
+        Assert.That(obj.List, Is.EqualTo(new List<int> { 1, 2 }));
+        Assert.That(obj.Array, Is.EqualTo(new int[] { 3, 4 }));
+        Assert.That(obj.Dictionary, Is.EqualTo(new Dictionary<string, int> { { "5", 6 } }));
+    }
+}

src/GenJson/GenJsonAttribute.cs

@@ -115,4 +115,13 @@ public GenJsonDerivedTypeAttribute(Type type, object? typeDiscriminatorValue = n
         public Type Type { get; }
         public object? TypeDiscriminatorValue { get; }
     }
+    /// <summary>
+    /// This attribute can be used to skip the count optimization for collections.
+    /// When applied to a class or struct, the generator will not emit the $PropertyName count property
+    /// and will not look for it during deserialization.
+    /// </summary>
+    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct)]
+    public sealed class GenJsonSkipCountOptimizationAttribute : Attribute
+    {
+    }
 }