Add support for zero-allocation deserialization with System.Text.Json

Author: PawelGerr

.claude/CLAUDE-ATTRIBUTES.md

@@ -102,6 +102,7 @@ SmartEnumAttribute()
 | `ConversionToKeyMemberType`   | `ConversionOperatorsGeneration` | `Implicit`                                      | Generate conversion operator from enum to key type                                   |
 | `ConversionFromKeyMemberType` | `ConversionOperatorsGeneration` | `Explicit`                                      | Generate conversion operator from key type to enum                                   |
 | `SerializationFrameworks`     | `SerializationFrameworks`       | `All`                                           | Which serialization frameworks to generate integration code for                      |
+| `DisableSpanBasedJsonConversion` | `bool`                       | `false`                                         | Disables ReadOnlySpan-based zero-allocation JSON conversion, falling back to string-based conversion (string keys only; NET9+) |
 | `SwitchMapStateParameterName` | `string?`                       | `"state"`                                       | Name of state parameter in Switch/Map methods                                        |
 
 **Note**: `ISpanParsable<T>` inherits from `IParsable<T>`, so setting `SkipISpanParsable = false` will automatically set `SkipIParsable = false` if needed.
@@ -278,7 +279,7 @@ public partial class ApiResponse
 
 ### ObjectFactoryAttribute&lt;T&gt;
 
-For types with custom factories for parsing/serialization.
+For types with custom factories for parsing/serialization. When `T` is `ReadOnlySpan<char>` and `UseForSerialization = SerializationFrameworks.SystemTextJson`, enables zero-allocation JSON deserialization on NET9+ by transcoding UTF-8 JSON bytes directly to `ReadOnlySpan<char>` instead of allocating a `string`.
 
 **Targets**: `class` or `struct`
 

.claude/CLAUDE-FEATURE-DEV.md

@@ -106,6 +106,8 @@ Separate code generator factories for each serialization framework:
 
 **Pattern**: Each factory checks if the corresponding serialization package is referenced, then generates appropriate converter/formatter registration code.
 
+- **`KeyedJsonCodeGenerator`**: Generates JSON converter attributes on the type. On NET9+, when `UseSpanBasedJsonConverter` is true, it emits `#if NET9_0_OR_GREATER` blocks that register `ThinktectureSpanParsableJsonConverterFactory<T, TValidationError>` for zero-allocation deserialization, with a fallback to the regular `ThinktectureJsonConverterFactory<T, TValidationError>` on older target frameworks.
+
 ## Type Information System
 
 Rich type metadata is captured and passed through the generation pipeline:
@@ -275,6 +277,103 @@ The generator creates:
 - Integration with serializers (JSON, MessagePack, etc.)
 - Model binding for ASP.NET Core
 
+### Zero-Allocation JSON via ObjectFactory (NET9+)
+
+When `[ObjectFactory<ReadOnlySpan<char>>]` is present with `UseForSerialization = SerializationFrameworks.SystemTextJson`, the source generator sets `UseSpanBasedJsonConverter = true` for the type. This causes the generated JSON converter attribute to use `ThinktectureSpanParsableJsonConverterFactory` on NET9+, enabling zero-allocation deserialization by transcoding UTF-8 JSON bytes directly to `ReadOnlySpan<char>` without allocating a `string`. This is the opt-in mechanism for Value Objects (unlike Smart Enums with string keys, where it is automatic).
+
+## Span-Based Zero-Allocation JSON Deserialization (NET9+)
+
+This feature enables zero-allocation JSON deserialization for string-keyed Smart Enums and Value Objects with `ReadOnlySpan<char>` object factories, by converting UTF-8 JSON bytes directly to `ReadOnlySpan<char>` instead of allocating an intermediate `string`.
+
+### Architecture
+
+The feature spans three layers:
+
+1. **`Utf8JsonReaderHelper`** (internal, `Thinktecture.Internal` namespace, NET9+ only): The low-level engine that converts UTF-8 JSON bytes to `ReadOnlySpan<char>` without string allocation.
+   - **Fast path**: When the JSON value is contiguous in the buffer and unescaped, it transcodes the raw UTF-8 bytes directly via `Encoding.UTF8.GetChars(ReadOnlySpan<byte>, Span<char>)`.
+   - **Slow path**: When the value is escaped or fragmented across buffer segments, it uses `Utf8JsonReader.CopyString(Span<byte>)` to get unescaped UTF-8 bytes, then transcodes.
+   - **Memory strategy**: Uses `stackalloc` for values up to 128 chars; rents from `ArrayPool<char>.Shared` for larger values and returns the buffer after use.
+
+2. **`ThinktectureSpanParsableJsonConverter<T, TValidationError>`** (NET9+ only): A `System.Text.Json` converter that uses `Utf8JsonReaderHelper` to obtain a `ReadOnlySpan<char>` from the JSON reader, then calls `IConvertible<ReadOnlySpan<char>>.ToValue()` on the target type to perform zero-allocation conversion.
+   - **Type constraints**: `T : IObjectFactory<T, ReadOnlySpan<char>, TValidationError>, IConvertible<ReadOnlySpan<char>>`
+   - Paired with `ThinktectureSpanParsableJsonConverterFactory<T, TValidationError>` for registration.
+
+3. **`ThinktectureJsonConverterFactory`** (runtime detection): Updated with a NET9+-only constructor accepting `Func<Type, bool>? skipSpanBasedDeserialization`. At runtime, it inspects metadata via its internal `CanUseSpanParsableConverter()` method to decide whether to return the span-based converter or the regular converter for a given type.
+
+### Runtime Converter Selection (`CanUseSpanParsableConverter`)
+
+The `ThinktectureJsonConverterFactory` checks two paths to determine if a type supports span-based deserialization:
+
+- **String-keyed Smart Enums**: Checks `Metadata.Keyed.SmartEnum.DisableSpanBasedJsonConversion`. If `false` (the default), the span-based converter is used.
+- **Other types (Value Objects, etc.)**: Checks the type's `ObjectFactories` metadata for an entry whose `ValueType` is `ReadOnlySpan<char>` and whose `SerializationFrameworks` includes `SystemTextJson`.
+
+The optional `skipSpanBasedDeserialization` delegate (passed via the constructor) provides an additional external override for consumers who need to disable span-based deserialization for specific types at the application level.
+
+### How It Works for Smart Enums
+
+**Automatic for string-keyed enums**: When a Smart Enum has a `string` key type, the source generator automatically enables span-based JSON deserialization (no user action needed).
+
+**Opt-out**: Set `DisableSpanBasedJsonConversion = true` on the `[SmartEnum<string>]` attribute:
+
+```csharp
+[SmartEnum<string>(DisableSpanBasedJsonConversion = true)]
+public partial class MyEnum
+{
+    public static readonly MyEnum Item1 = new("value1");
+}
+```
+
+**Non-string keys**: Not applicable. The feature is only effective for `string`-keyed Smart Enums because `IConvertible<ReadOnlySpan<char>>` maps naturally to string-based key lookup.
+
+### How It Works for Value Objects
+
+**Opt-in via ObjectFactory**: Value Objects must explicitly declare `[ObjectFactory<ReadOnlySpan<char>>]` with `UseForSerialization = SerializationFrameworks.SystemTextJson`:
+
+```csharp
+[ValueObject<string>]
+[ObjectFactory<ReadOnlySpan<char>>(UseForSerialization = SerializationFrameworks.SystemTextJson)]
+public partial class ProductName
+{
+    // The generated IObjectFactory<ProductName, ReadOnlySpan<char>, ValidationError>
+    // implementation enables zero-allocation JSON deserialization
+}
+```
+
+The `ObjectFactorySourceGenerator` detects the `ReadOnlySpan<char>` object factory and sets `UseSpanBasedJsonConverter = true` in the serializer generator state.
+
+### Source Generator Behavior
+
+**State tracking**: `KeyedSerializerGeneratorState` has a `UseSpanBasedJsonConverter` boolean property that is included in equality comparison and hash code computation (ensuring incremental generation correctness).
+
+**Per-generator logic for setting `UseSpanBasedJsonConverter`**:
+
+- **`SmartEnumSourceGenerator`**: Sets to `true` when `!state.Settings.DisableSpanBasedJsonConversion && state.KeyMember?.SpecialType == SpecialType.System_String`
+- **`ValueObjectSourceGenerator`**: Always passes `false` (Value Objects require an explicit `[ObjectFactory<ReadOnlySpan<char>>]`)
+- **`ObjectFactorySourceGenerator`**: Sets to `true` when `state.AttributeInfo.ObjectFactories.Any(f => f.IsReadOnlySpanOfChar)`
+
+**Generated code pattern** (`KeyedJsonCodeGenerator`):
+
+```csharp
+// When UseSpanBasedJsonConverter = true
+#if NET9_0_OR_GREATER
+[System.Text.Json.Serialization.JsonConverter(typeof(
+    global::Thinktecture.Text.Json.Serialization.ThinktectureSpanParsableJsonConverterFactory<MyType, ValidationError>))]
+#else
+[System.Text.Json.Serialization.JsonConverter(typeof(
+    global::Thinktecture.Text.Json.Serialization.ThinktectureJsonConverterFactory<MyType, string, ValidationError>))]
+#endif
+partial class MyType { }
+```
+
+**Settings and constants**:
+
+- `SmartEnumAttribute<TKey>.DisableSpanBasedJsonConversion`: New attribute property (default `false`)
+- `AllEnumSettings` and `SmartEnumSettings`: Track the `DisableSpanBasedJsonConversion` value
+- `Constants.DISABLE_SPAN_BASED_JSON_CONVERSION`: String constant for attribute property lookup
+- `AttributeDataExtensions.FindDisableSpanBasedJsonConversion()`: Extension method to extract the setting from attribute data
+
+**`IConvertible<T>` update**: On NET9+, the interface uses `allows ref struct` constraint to support `ReadOnlySpan<char>` as the type parameter.
+
 ## Runtime Metadata System
 
 The runtime metadata system provides the bridge between compile-time source generation and runtime framework integration. This system is critical for serialization, model binding, type conversion, and other runtime operations.
@@ -338,6 +437,7 @@ public partial class MyEnum
 
 **Concrete implementations**:
 - `SmartEnumMetadata`: For Smart Enums
+  - Includes `Metadata.Keyed.SmartEnum.DisableSpanBasedJsonConversion` (`bool`, `init`): When `true`, prevents the runtime `ThinktectureJsonConverterFactory` from selecting the span-based JSON converter for this Smart Enum. Default `false`. Only meaningful for string-keyed enums. Set via `SmartEnumAttribute<TKey>.DisableSpanBasedJsonConversion` and emitted by `SmartEnumCodeGenerator` in metadata initialization.
 - `KeyedValueObjectMetadata`: For simple Value Objects with single key
 - `ComplexValueObjectMetadata`: For complex Value Objects with multiple members
 

.claude/CLAUDE-REVIEW.md

@@ -123,6 +123,8 @@ static partial void ValidateFactoryArguments(ref string value, ref ValidationErr
 - [ ] Manual registration code correct if not using automatic integration
 - [ ] Serialization tested with roundtrip tests
 - [ ] Null handling correct for nullable types
+- [ ] Span-based JSON converter attribute generated correctly with `#if NET9_0_OR_GREATER` blocks (for string-keyed Smart Enums)
+- [ ] `DisableSpanBasedJsonConversion` setting respected when set to `true`
 
 ### Framework Integration
 
@@ -159,6 +161,7 @@ static partial void ValidateFactoryArguments(ref string value, ref ValidationErr
 - [ ] Generated code follows expected patterns
 - [ ] No duplicate members generated
 - [ ] Conditional compilation (`#if NET9_0_OR_GREATER`) used correctly
+- [ ] `#if NET9_0_OR_GREATER` blocks present for span-based JSON converter on string-keyed Smart Enums
 - [ ] Generated XML documentation present
 
 ### Test Coverage
@@ -175,6 +178,8 @@ static partial void ValidateFactoryArguments(ref string value, ref ValidationErr
 
 - [ ] No unnecessary allocations in hot paths
 - [ ] Span-based APIs used when available (NET9+)
+- [ ] Zero-allocation span-based JSON deserialization used for string-keyed Smart Enums (NET9+)
+- [ ] `[ObjectFactory<ReadOnlySpan<char>>]` with `UseForSerialization` used for value objects needing span-based JSON deserialization
 - [ ] StringBuilder used for string concatenation in loops
 - [ ] No LINQ in performance-critical code (if avoidable)
 

.claude/CLAUDE-TESTING.md

@@ -138,6 +138,10 @@ The test suite is organized into multiple projects, each with a specific purpose
 public partial struct IntBasedStructValueObject;
 ```
 
+**Notable test types for span-based JSON deserialization**:
+- `TestEnums/SmartEnum_StringBased_WithDisabledSpanBasedJsonConversion.cs`: Compilation test verifying that `DisableSpanBasedJsonConversion = true` on a string-based Smart Enum produces compilable generated code that falls back to string-based JSON deserialization
+- `TestValueObjects/ComplexValueObjectWithReadOnlySpanBasedObjectFactoryForJson.cs`: Compilation test verifying that a complex value object with `[ObjectFactory<ReadOnlySpan<char>>]` produces compilable generated code supporting span-based JSON deserialization
+
 **Best practices**:
 - Create separate types for each meaningful feature variation or configuration
 - Name types descriptively to indicate what feature/configuration they test
@@ -307,6 +311,20 @@ public void Should_serialize_and_deserialize_smart_enum()
 }
 ```
 
+#### Zero-Allocation Span-Based JSON Deserialization
+
+String-based Smart Enums and Value Objects support zero-allocation JSON deserialization via `ThinktectureSpanParsableJsonConverter`. This converter avoids allocating a `string` during deserialization by reading the UTF-8 JSON payload directly into a `ReadOnlySpan<char>` and calling `ISpanParsable<T>.Parse`.
+
+**Key test areas**:
+
+- **`ThinktectureSpanParsableJsonConverter` tests** (`SpanParsableJsonConverterTests.cs`): Verify that types implementing `ISpanParsable<T>` are deserialized through the span-based path. Test both `ThinktectureSpanParsableJsonConverterFactory` (standalone) and the integration through `ThinktectureJsonConverterFactory`.
+- **`Utf8JsonReaderHelper` tests** (`Utf8JsonReaderHelperTests.cs`): Verify correct UTF-8 byte to `ReadOnlySpan<char>` conversion, including multi-byte characters, empty strings, and edge cases. This helper is the core of the zero-allocation path.
+- **Opt-out via `DisableSpanBasedJsonConversion`**: Smart Enums can disable span-based JSON conversion by setting `DisableSpanBasedJsonConversion = true` on the `[SmartEnum<T>]` attribute. Test that the generated JSON converter falls back to string-based deserialization. The compilation test type `SmartEnum_StringBased_WithDisabledSpanBasedJsonConversion` verifies the generated code compiles correctly.
+- **Value objects with `[ObjectFactory<ReadOnlySpan<char>>]`**: Value objects that declare a `ReadOnlySpan<char>`-based object factory also get span-based JSON deserialization. The compilation test type `ComplexValueObjectWithReadOnlySpanBasedObjectFactoryForJson` verifies this path. Snapshot tests in `JsonObjectFactoryCodeGeneratorFactoryTests` verify the generated converter code.
+- **Source generator snapshot tests**: `Generate.Snapshot_StringKeyWithSpanJsonConverter.verified.txt` verifies the generated JSON converter includes the span-based deserialization code path.
+
+**Benchmarks**: `SmartEnumJsonDeserializationBenchmarks` and `ValueObjectJsonDeserializationBenchmarks` (in the `Benchmarking` sample project) measure the allocation reduction. These are not unit tests but are useful for validating performance characteristics.
+
 ### MessagePack Serialization
 
 ```csharp

.claude/CLAUDE.md

@@ -135,6 +135,7 @@ This is a .NET library providing **Smart Enums**, **Value Objects**, and **Discr
     - Can be generic types
     - Supports `IParsable<T>`, `ISpanParsable<T>` (NET9+, zero-allocation), `IComparable<T>`, `IFormattable`
     - Configurable operators, conversion, Switch/Map generation
+    - **Span-based JSON deserialization** (NET9+, string keys only): Zero-allocation JSON deserialization enabled by default; transcodes UTF-8 JSON bytes directly to `ReadOnlySpan<char>` instead of allocating a `string`. Opt out per enum via `DisableSpanBasedJsonConversion = true`
 
 #### Value Objects
 
@@ -196,7 +197,7 @@ The `MetadataLookup` class provides cached metadata discovery via reflection. Ob
 
 ### Framework Integration Quick Reference
 
-**Serialization**: System.Text.Json, MessagePack, Newtonsoft.Json, ProtoBuf - reference package for auto-generation or manually register converters
+**Serialization**: System.Text.Json, MessagePack, Newtonsoft.Json, ProtoBuf - reference package for auto-generation or manually register converters. On NET9+, string-based Smart Enums and types with `[ObjectFactory<ReadOnlySpan<char>>(UseForSerialization = SerializationFrameworks.SystemTextJson)]` automatically use zero-allocation span-based JSON deserialization (via `Utf8JsonReaderHelper` and `ThinktectureSpanParsableJsonConverter`)
 
 **Entity Framework Core**: Version-specific packages (8/9/10) - call `.UseThinktectureValueConverters()` on DbContextOptionsBuilder
 
@@ -214,6 +215,7 @@ The `MetadataLookup` class provides cached metadata discovery via reflection. Ob
 4. **Serialization not working**: Ensure integration package is referenced, or manually register converters/formatters
 5. **EF Core not converting**: Call `.UseThinktectureValueConverters()` on DbContextOptionsBuilder
 6. **ISpanParsable not available**: Requires NET9+; ensure project targets `net9.0` or later and key type implements `ISpanParsable<TKey>`
+7. **Span-based JSON deserialization causing issues**: Disable per Smart Enum with `[SmartEnum<string>(DisableSpanBasedJsonConversion = true)]`. For `ThinktectureJsonConverterFactory`, pass `skipSpanBasedDeserialization` callback to the constructor (NET9+ overload) to opt out at runtime
 
 ### Best Practices
 
@@ -225,6 +227,7 @@ The `MetadataLookup` class provides cached metadata discovery via reflection. Ob
 6. **Partial keyword**: Types must be marked `partial` for source generators to work
 7. **Culture-specific parsing**: Always pass appropriate `IFormatProvider` when parsing/formatting culture-sensitive types
 8. **Arithmetic operators**: Use unchecked arithmetic context - overflow/underflow wraps around
+9. **Span-based JSON for value objects**: To enable zero-allocation JSON deserialization for value objects on NET9+, add `[ObjectFactory<ReadOnlySpan<char>>(UseForSerialization = SerializationFrameworks.SystemTextJson)]` to the type. Without this attribute, value objects use regular key-based JSON conversion
 
 ## Project Structure
 

.gitignore

@@ -5,7 +5,6 @@
 **/packages/**
 **/test-results/**
 .local-memory/**
-.serena/cache/**
 
 *\.sln\.DotSettings\.user
 *\.csproj\.user
@@ -14,3 +13,6 @@
 # Verify
 test/**/*.received.*
 test/**/*.received/
+
+# Benchmarking
+**/BenchmarkDotNet.Artifacts/**

docs

@@ -0,0 +1,31 @@
+using System.Text.Json;
+using BenchmarkDotNet.Attributes;
+using Thinktecture.Database;
+
+namespace Thinktecture.Benchmarks;
+
+public class SmartEnumJsonDeserializationBenchmarks
+{
+   private readonly byte[] _stringBasedJson = "\"Value1\""u8.ToArray();
+   private readonly byte[] _intBasedJson = "1"u8.ToArray();
+
+   private readonly JsonSerializerOptions _options = new();
+
+   [Benchmark]
+   public TestSmartEnum_Class_StringBased? StringBased_with_ISpanParsable()
+   {
+      return JsonSerializer.Deserialize<TestSmartEnum_Class_StringBased>(_stringBasedJson, _options);
+   }
+
+   [Benchmark(Baseline = true)]
+   public TestSmartEnum_Class_StringBased_Without_SpanParsableConverter? StringBased_without_ISpanParsable()
+   {
+      return JsonSerializer.Deserialize<TestSmartEnum_Class_StringBased_Without_SpanParsableConverter>(_stringBasedJson, _options);
+   }
+
+   // [Benchmark]
+   // public TestSmartEnum_Class_IntBased? IntBased()
+   // {
+   //    return JsonSerializer.Deserialize<TestSmartEnum_Class_IntBased>(_intBasedJson, _options);
+   // }
+}