ZeroAlloc.ValueObjects 1.4.0

ZeroAlloc.ValueObjects

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

ZeroAlloc.ValueObjects matches record and record struct performance exactly. The only allocating variant is CSharpFunctionalExtensions.ValueObject.

Full methodology and more scenarios: 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