LayeredCraft.OptimizedEnums

LayeredCraft.OptimizedEnums is a modular C# .NET library providing high-performance, AOT-safe smart enum patterns using source generation. Inherit from a base class and the generator produces O(1) lookup tables, collection properties, and factory methods — all at compile time with zero reflection at runtime.

Key Features

• Zero reflection — all lookup tables are source-generated at compile time
• AOT / trimming friendly — compatible with NativeAOT, ReadyToRun, and Blazor WASM
• O(1) lookups — FromName, FromValue, ContainsName, ContainsValue
• Compile-time validation — errors for missing partial, duplicate values/names
• No allocations per call — all collections are statically cached
• Inheritance-based triggering — no attribute required, just inherit and go

📦 Packages

Package	NuGet	Downloads
LayeredCraft.OptimizedEnums
LayeredCraft.OptimizedEnums.SystemTextJson
LayeredCraft.OptimizedEnums.EFCore
LayeredCraft.OptimizedEnums.Dapper	coming soon
LayeredCraft.OptimizedEnums.AutoFixture	coming soon

Usage

publicsealedpartialclassOrderStatus:OptimizedEnum<OrderStatus,int>{publicstaticreadonlyOrderStatusPending=new(1,nameof(Pending));publicstaticreadonlyOrderStatusPaid=new(2,nameof(Paid));publicstaticreadonlyOrderStatusShipped=new(3,nameof(Shipped));privateOrderStatus(intvalue,stringname):base(value,name){}}

Or use the int-defaulting convenience base class:

publicsealedpartialclassPriority:OptimizedEnum<Priority>{publicstaticreadonlyPriorityLow=new(1,nameof(Low));publicstaticreadonlyPriorityMedium=new(2,nameof(Medium));publicstaticreadonlyPriorityHigh=new(3,nameof(High));privatePriority(intvalue,stringname):base(value,name){}}

The source generator produces:

// Lookupvarstatus=OrderStatus.FromName("Paid");// OrderStatus.Paidvarstatus=OrderStatus.FromValue(3);// OrderStatus.Shipped// Try-styleOrderStatus.TryFromName("Paid",outvarresult);OrderStatus.TryFromValue(3,outvarresult);// MembershipOrderStatus.ContainsName("Paid");// trueOrderStatus.ContainsValue(99);// false// EnumerationIReadOnlyList<OrderStatus>all=OrderStatus.All;IReadOnlyList<string>names=OrderStatus.Names;IReadOnlyList<int>values=OrderStatus.Values;intcount=OrderStatus.Count;// compile-time constant

Performance

Benchmarks run on Apple M3 Max, .NET 9.0.8, BenchmarkDotNet v0.14.0.

Method	Mean	Allocated
FromName	5.48 ns	0 B
TryFromName	4.53 ns	0 B
FromValue	2.18 ns	0 B
TryFromValue	1.21 ns	0 B
ContainsName	4.54 ns	0 B
ContainsValue	1.18 ns	0 B
GetAll	0.76 ns	0 B
GetCount	~0 ns	0 B

All lookups are O(1) via statically-cached dictionaries. Count is a compile-time constant.

JSON Serialization

Add LayeredCraft.OptimizedEnums.SystemTextJson for source-generated, zero-reflection JsonConverter support. One package is all you need — it pulls in the core package automatically:

dotnet add package LayeredCraft.OptimizedEnums.SystemTextJson

Decorate your class with [OptimizedEnumJsonConverter] and the generator emits a concrete, AOT-safe converter and wires it up via [JsonConverter]:

usingLayeredCraft.OptimizedEnums;usingLayeredCraft.OptimizedEnums.SystemTextJson;[OptimizedEnumJsonConverter(OptimizedEnumJsonConverterType.ByName)]publicsealedpartialclassOrderStatus:OptimizedEnum<OrderStatus,int>{publicstaticreadonlyOrderStatusPending=new(1,nameof(Pending));publicstaticreadonlyOrderStatusPaid=new(2,nameof(Paid));publicstaticreadonlyOrderStatusShipped=new(3,nameof(Shipped));privateOrderStatus(intvalue,stringname):base(value,name){}}

{ "status": "Pending" }

Two strategies are available: ByName (serializes as the member name string) and ByValue (serializes as the underlying value). See the JSON Serialization docs for full details.

Entity Framework Core

Add LayeredCraft.OptimizedEnums.EFCore for source-generated, zero-reflection EF Core value converter support. One package is all you need — it pulls in the core package automatically:

dotnet add package LayeredCraft.OptimizedEnums.EFCore

Decorate your class with [OptimizedEnumEfCore] and the generator emits concrete ValueConverter classes and registration helpers:

usingLayeredCraft.OptimizedEnums;usingLayeredCraft.OptimizedEnums.EFCore;[OptimizedEnumEfCore(OptimizedEnumEfCoreStorage.ByValue)]publicsealedpartialclassOrderStatus:OptimizedEnum<OrderStatus,int>{publicstaticreadonlyOrderStatusPending=new(1,nameof(Pending));publicstaticreadonlyOrderStatusPaid=new(2,nameof(Paid));publicstaticreadonlyOrderStatusShipped=new(3,nameof(Shipped));privateOrderStatus(intvalue,stringname):base(value,name){}}

Register conversions with the global convention hook in your DbContext:

protectedoverridevoidConfigureConventions(ModelConfigurationBuilderbuilder){builder.ConfigureOptimizedEnums();}

Two strategies are available: ByValue (stores the underlying value) and ByName (stores the member name string). See the Entity Framework Core docs for full details.

Installation

dotnet add package LayeredCraft.OptimizedEnums

Supports .NET 8.0, .NET 9.0, .NET 10.0.

Documentation

Full documentation is available at the LayeredCraft.OptimizedEnums docs site.

License

MIT