EricksonLopez.DomainPrimitives.AspNetCore.SourceGenerators 1.0.0

EricksonLopez.DomainPrimitives 🛡️

DomainPrimitives is a BCL-native, AOT-first domain primitive library for .NET 8+. It uses Roslyn Incremental Source Generators to produce strictly valid, immutable domain types with the deepest BCL interface coverage in the .NET ecosystem — including IUtf8SpanParsable<T>, ISpanFormattable, and IUtf8SpanFormattable.

Stop writing validation boilerplate. DomainPrimitives generates strongly-typed, BCL-native domain types from a single attribute — with built-in security gates, zero-alloc paths, and full Native AOT support out of the box.

🆚 Why DomainPrimitives?

Table notes: — means the library does not expose this capability as part of its generated surface (not tested, not documented, or explicitly out of scope for that library).
Not in DomainPrimitives yet: Discriminated Unions (Thinktecture only), Newtonsoft.Json converters (Vogen/StronglyTypedId), class-based primitives. See docs/feature-gaps.md for the full gap list.

📦 Supported Primitives

🎯 Semantic Shortcut Attributes

Instead of repeating validations, use built-in shortcut attributes that combine validation and normalization rules:

String shortcuts (15 types):

• Identity: [Email], [Username], [PasswordHash]
• Network: [Url], [IPAddress], [MacAddress]
• Commerce: [Phone], [CountryCode], [CurrencyCode], [LanguageCode], [IBAN]
• Content: [Slug], [HexColor], [ISBN], [VIN]

Numeric shortcuts (15 types): [Money], [Percentage], [Latitude], [Longitude], [Age], [Weight], [Height], [Distance], [Temperature], [Score], [Quantity], [Price], [TaxRate], [Discount], [Rating]

⚡ Quick Start

dotnet add package EricksonLopez.DomainPrimitives

using EricksonLopez.DomainPrimitives;

// 1. Define your primitive
[CountryCode] // Implies: [StringPrimitive], [Trim], [UpperCase], [Length(2, 2)]
public readonly partial record struct CountryIsoCode;

// 2. Create — throws DomainPrimitiveValidationException on invalid input
var code = CountryIsoCode.Create("  us  "); // Output: CountryIsoCode { Value = "US" } (trimmed + uppercased)

// 3. TryCreate — out-based, zero allocation on success
if (CountryIsoCode.TryCreate("us", out var validCode, out var error))
    Console.WriteLine($"Valid: {validCode}");  // Output: Valid: US
else
    Console.WriteLine($"Error [{error.Code}]: {error.Message}");

// 4. Parse from Span<char> — allocation-minimized path
if (CountryIsoCode.TryParse("us".AsSpan(), null, out var parsedCode))
    Console.WriteLine($"Parsed: {parsedCode}"); // Output: Parsed: US

// 5. Parse from UTF-8 bytes — native for HTTP/gRPC/Kafka scenarios (NET8+)
ReadOnlySpan<byte> utf8 = "us"u8;
if (CountryIsoCode.TryParse(utf8, null, out var utf8Code))
    Console.WriteLine($"UTF-8 parsed: {utf8Code}"); // Output: UTF-8 parsed: US

🔐 Security Gates

DomainPrimitives is the only domain primitive library with built-in security gates applied automatically to all string types:

⚡ Performance & Benchmarks

BenchmarkDotNet v0.15.8 · .NET 10.0.10 (10.0.1026.32716) · AMD Ryzen 7 9800X3D

DomainPrimitives is built with extreme performance and zero-allocation in mind. See the full benchmark methodology and results.

Hot Path Benchmarks

Note: JSON allocation is from the Utf8JsonReader/Utf8JsonWriter infrastructure, not from the domain primitive itself. The TryParse hot path (called internally during deserialization) is zero-allocation.

vs. Industry Competitors (StrongId<Guid>)

Results show DomainPrimitives maintains zero-allocation in hot paths and performs virtually identically to raw Guid and other struct-based generators, while avoiding the heap allocation overhead seen in class-based wrappers (e.g., ValueOf).

Allocation Model Audit

DomainPrimitives minimizes heap allocations in hot paths. Here is the honest per-path allocation audit:

Why 1 unavoidable allocation? Unicode NFC normalization (SEC-004) requires producing a System.String — normalization can change character count (combining characters → composed), so the result cannot be stored as a span. The stored domain value is always NFC-normalized, which is correct and prevents homoglyph attacks.

No Result<T> overhead. TryCreate(out result, out error) is zero-allocation on the success path because both result (a struct) and error (a struct) live on the caller's stack. Unlike Result<T> wrapper patterns, no heap object is created.

🧩 Ecosystem Integrations

DomainPrimitives provides seamless integration via dedicated packages. Converters are auto-discovered — no per-type attributes needed in your domain layer:

Known gap: Newtonsoft.Json converters are not yet supported. If your project uses Newtonsoft.Json, consider Vogen or StronglyTypedId for this scenario. Track progress in docs/feature-gaps.md.

Mapster note: For scalar primitives ([StringPrimitive], [StrongId], [NumericPrimitive<T>]), Mapster resolves the generated explicit operator automatically — no package needed. Add EricksonLopez.DomainPrimitives.Mapster only when mapping composite [ValueObject] types or when using Mapster in AOT source-generation mode. See ADR-017.

🏗️ Architecture

Target Framework Requirements

Minimum runtime: net8.0. IUtf8SpanParsable<T>, RegexOptions.NonBacktracking, System.Buffers.ArrayPool<T>, and MemoryExtensions.ToLowerInvariant all require .NET 8+. Use EricksonLopez.DomainPrimitives.Abstractions for shared contracts in netstandard2.0 projects.
Primary development target: net10.0 LTS. All benchmarks and new feature development target NET 10. See ADR-016 for the full rationale.

Native AOT

All generated code is AOT-compatible:

• Zero reflection in hot paths (Type.GetMethod(), Activator, Expression<> are never used)
• SmartEnum.GetAll() is a static readonly array — no runtime reflection
• IsAotCompatible=true in project metadata
• CI gate: dotnet publish with Native AOT verifies compatibility on every commit

Generated BCL Interfaces

For every domain primitive, the generator emits:

*IComparable<T> on ValueObject is intentionally not generated — composite types have no canonical ordering unless the domain explicitly defines one.

📚 Documentation

• 🛡️ Security Gates — SEC-001 through SEC-006 explained
• 🗺️ Feature Gaps — What's missing and what we explicitly reject
• 🍳 Cookbook — Common problems solved with DomainPrimitives
• 📖 API Reference — Interfaces, exceptions, and factory methods
• 📦 Packages — All 15 NuGet packages, TFM matrix, and dependency graph
• 🔄 Migration from Vogen — Step-by-step migration guide
• 🔄 Migration from StronglyTypedId — Step-by-step migration guide
• 📊 Benchmark Results — Performance data and allocation audit
• 📊 Benchmark Plan — 16 BenchmarkDotNet scenarios
• 🏗️ System Overview — Architecture and project dependency diagram
• ⚙️ CI/CD Pipelines — Build, test, quality gates, and supply chain security
• 🗺️ Roadmap — NOW / NEXT / LATER horizon planning
• 📝 Changelog — All notable changes per version

🚀 Sample Projects

The samples/OfficialSample/ folder contains step-by-step integration examples. Numbers are non-consecutive by design — they match the chapter index of the full documentation and leave room for future samples to be inserted without renumbering.

🤝 Contributing & Community

• Contributing Guide — Build, test, and PR process
• Code of Conduct — Contributor Covenant v2.1
• Security Policy — Vulnerability reporting and supply chain security
• Support — Getting help and support channels
• Governance — RFC process and design principles
• License — MIT