👁 Image
ZeroAlloc.ValueObjects 1.7.1

ZeroAlloc.ValueObjects

👁 NuGet
👁 Build
👁 AOT
👁 GitHub Sponsors

Zero-allocation source-generated ValueObject equality for your existing domain types.

Same performance as record — without forcing the record keyword on your domain model. Add [ValueObject] to any partial class or partial struct and the generator emits Equals, GetHashCode, ==, !=, and ToString with no heap allocations.

Install

dotnet add package ZeroAlloc.ValueObjects

Quick start

// Annotate any existing partial class — no keyword changes, no base class
[ValueObject]
public partial class Money
{
 public decimal Amount { get; }
 public string Currency { get; }
 public Money(decimal amount, string currency) => (Amount, Currency) = (amount, currency);
}

// Use standard equality — zero allocations
var a = new Money(10m, "USD");
var b = new Money(10m, "USD");

bool equal = a == b; // true
bool same = a.Equals(b); // true — IEquatable<Money> fast path
int hash = a.GetHashCode(); // same as b.GetHashCode() — safe as dict key
string s = a.ToString(); // "Money { Amount = 10, Currency = USD }"

Performance

Multi-field value objects (Money(decimal Amount, string Currency)): ZA matches record / record struct exactly. CFE allocates ~90 B per call.

Single-int wrapped IDs vs Vogen (the source-gen alternative):

ZA wins or ties every row, with 0 B allocated on all of them. The previous regressions on GetHashCode (~30× slower) and ToString (~72 B allocation) were closed in v1.7 by aligning the single-property emit to Value.ToString(InvariantCulture) / Value.GetHashCode() directly. ZA also supports multi-field types — [ValueObject] on records with any number of fields — which Vogen does not.

Full methodology and analysis: docs/performance.md

Features

• Zero allocations — no iterator state machine, no boxing
• Works on existing partial class and partial struct — no refactoring required
• Can inherit from non-record base classes
• Fine-grained member control with [EqualityMember] (opt-in) and [IgnoreEqualityMember] (opt-out)
• No extra generated members — no with, no Deconstruct, no EqualityContract
• Null-safe comparison for nullable reference type properties
• HashCode.Combine for ≤8 properties, incremental HashCode.Add for 9+

Why not just use record?

Typed identifiers

[TypedId] is the companion attribute for strongly-typed IDs — OrderId, UserId, MessageId. It solves the same problem as the ValueObject attribute, but tailored for single-value identifiers with built-in generation strategies.

Basic usage

using ZeroAlloc.ValueObjects;

[TypedId(Strategy = IdStrategy.Ulid)]
public readonly partial record struct OrderId;

// Usage
OrderId id = OrderId.New(); // monotonic ULID
string s = id.ToString(); // "01ARZ3NDEKTSV4RRFFQ69G5FAV" — 26-char base32
OrderId parsed = OrderId.Parse(s); // round-trip

Strategies

Assembly-level default

[assembly: TypedIdDefault(Strategy = IdStrategy.Ulid)]

[TypedId] // resolves to Ulid from the assembly default
public readonly partial record struct ProductId;

[TypedId(Strategy = IdStrategy.Snowflake)] // per-struct override
public readonly partial record struct MessageId;

Snowflake worker ID configuration

Snowflake IDs encode a 10-bit worker ID so multiple processes can mint IDs concurrently without collision. Configure at startup:

builder.Services.AddSnowflakeWorkerId(workerId: 5);
builder.Services.AddSnowflakeWorkerId(envVar: "POD_ORDINAL", fallback: 0);
builder.Services.AddSnowflakeWorkerId(sp => sp.GetRequiredService<IMachineIdProvider>().Id);

If no provider is registered, Snowflake.New() falls back to ZA_SNOWFLAKE_WORKER_ID env var, then throws TypedIdException.

EF Core

Install ZeroAlloc.ValueObjects.EfCore and register the convention:

protected override void ConfigureConventions(ModelConfigurationBuilder builder)
{
 builder.AddTypedIdConventions();
}

All [TypedId] structs in the DbContext's assembly are auto-mapped: Guid-backed → uniqueidentifier/uuid, long-backed → bigint. Per-property HasConversion still overrides.

Minimal API binding

No setup needed — the generator emits IParsable<T> + ISpanParsable<T>, so app.MapGet("/orders/{id}", (OrderId id) => …) just works.

JSON

Each TypedId carries [JsonConverter] pointing at a nested converter that reads/writes a string. Fully AOT-safe. No JsonSerializerContext wiring required for basic use; if you're source-generating JsonSerializerContext, include the TypedId types there too.

Compile-time diagnostics

Production checklist

• Sequential is not for production. The counter resets on process restart. Use it only in tests where deterministic IDs matter.
• Snowflake worker IDs must be unique across all producing processes. AddSnowflakeWorkerId cannot detect duplicates. Coordinate via orchestrator ordinals (Kubernetes pod index, Nomad alloc index) or a central registry. Duplicate worker IDs silently produce colliding IDs.
• Clock skew matters. Snowflake generation handles small rollbacks by pinning to the last observed millisecond, but severe skew (>5s) throws TypedIdException. Run NTP-synced or accept the brief unavailability.
• Process restart loses Sequential state but not Snowflake or ULID/UUID7 ordering. ULID/UUID7 are globally safe to restart; Snowflake is safe if worker ID is stable across restarts.

Documentation

License

MIT