ZeroAlloc.ORM 0.3.0

<h1 align="center">ZeroAlloc.ORM</h1>

<p align="center">Source-generator-based, NativeAOT-clean raw-SQL data access for .NET. Annotate <code>partial</code> methods with <code>[Query]</code> / <code>[Command]</code> / <code>[StoredProcedure]</code>; the generator emits typed parameter binding + materialization against <a href="https://github.com/MarcelRoozekrans/AdoNet.Async">AdoNet.Async</a>. Zero runtime reflection.</p>

Status: Pre-release. v0.3 shipped (multi-result tuples + IAsyncEnumerable streaming). Authoritative design lives at docs/design/2026-05-30-v1.0-design.md. Working backlog at docs/plans/za-orm-backlog.md.

What it is

A source-generator-driven data-access library that fills in the gap between two extremes adopters currently choose from:

• EF Core — full LINQ-to-SQL ORM, but its precompile-queries pipeline currently collides with co-resident source generators (e.g. ZA.Rest), blocking NativeAOT publish in template stacks like ZeroAlloc.Templates.
• Hand-written ADO.NET — works under AOT, but every repository becomes a hand-shaped tower of CreateCommand / CreateParameter / ReadAsync calls.

ZeroAlloc.ORM is the middle path: write the SQL string in an attribute, declare the partial method signature, let the source generator emit the ADO.NET pipeline. Zero runtime reflection, fully AOT-publishable, idiomatic with the rest of the ZeroAlloc ecosystem (consumes AdoNet.Async, dogfoods ZeroAlloc.ValueObjects, shares the convention catalog with ZeroAlloc.Mapping).

Packages

Quick Start

Scalar query

using System.Data.Async;
using System.Threading;
using System.Threading.Tasks;
using ZeroAlloc.ORM;

public sealed partial class Repo(IAsyncDbConnection connection)
{
    [Query("SELECT count(*) FROM Orders")]
    public partial Task<int> CountOrdersAsync(CancellationToken ct);
}

The source generator emits the open / execute / close pipeline against AdoNet.Async's IAsyncDbConnection. Zero runtime reflection; the emit composes through global::-qualified identifiers so it doesn't care about the consumer's using directives.

Row materialization (FlatRow)

public sealed record OrderRow(int Id, int CustomerId, decimal Total);

public sealed partial class OrderRepo(IAsyncDbConnection connection)
{
    [Query("SELECT Id, CustomerId, Total FROM Orders WHERE Id = @id")]
    public partial Task<OrderRow?> GetByIdAsync(int id, CancellationToken ct);
}

Positional record + matching SELECT column order = no mapping config. Nullable return = empty result set yields null.

Available in v0.1

• [Query] with scalar (Task<int>, Task<T?>) and FlatRow (Task<TRow?>) return shapes.
• 14 primitive types in parameter binding (int / long / short / byte / bool / decimal / double / float / string / Guid / DateTime / DateTimeOffset / TimeSpan / byte[]) + nullable variants.
• [Param(Name = "...")] SQL-side parameter name override.
• Compile-time diagnostics (ZAO001–ZAO009 + informational ZAO020–ZAO022) for signature contract violations.
• NativeAOT-clean publish (verified by aot-smoke CI gate).

Added in v0.2

• Value-object columns — types annotated with [ValueObject] from ZeroAlloc.ValueObjects (with a static From factory and a Value property) bind through their underlying primitive. Parameters unwrap to Value; reads wrap via T.From(primitive).

  [ValueObject]
  public readonly partial struct CustomerId
  {
      public int Value { get; }
      public CustomerId(int value) { Value = value; }
      public static CustomerId From(int value) => new(value);
  }
  
  public sealed record CustomerRow(CustomerId Id, string Name);
  
  public sealed partial class CustomerRepo(IAsyncDbConnection connection)
  {
      [Query("SELECT Id, Name FROM Customers WHERE Id = @id")]
      public partial Task<CustomerRow?> GetAsync(CustomerId id, CancellationToken ct);
  }
  

• Enums (default int round-trip) — any enum parameter or column binds as its underlying integer (reader.GetInt32 + cast on read; cast to underlying primitive on bind).

• Enums (string round-trip) — annotate the enum type with [StoreAsString] to round-trip as the member name (reader.GetString + Enum.Parse<T> on read; member-name bind).

• Domain-entity classes — plain class types with a single multi-arg public ctor materialize via column-name-keyed reads (__reader.GetOrdinal("ColumnName")). SELECT column order is irrelevant; each ctor parameter resolves to its matching column by name. Records keep the positional FlatRow path.

• Single-arg record discovery + static From factory discovery — wrappers without [ValueObject] still resolve when ConventionDiscovery can find an obvious construction strategy.

• New diagnostics ZAO040–ZAO044 — materialization-side failures (no construction strategy, conflicting strategies, unresolved ctor parameters, etc.) surface at build time with focused messages.

Added in v0.3

• Multi-result-set tuples (head + lines pattern) — tuple return types map each tuple element to one ;-separated SQL statement. Collapses the 1+N round-trip into a single command. Tuple element kinds: scalar (int, value-object, enum), row (record / single-ctor class), or list (List<T> / IReadOnlyList<T> / IEnumerable<T> / ...). See docs/cookbook/multi-result-set.md.

  public sealed record OrderRow(int Id, int CustomerId, decimal Total);
  public sealed record OrderLineRow(int Id, int OrderId, string Sku, int Qty);
  
  public sealed partial class OrderRepo(IAsyncDbConnection connection)
  {
      [Query("""
          SELECT Id, CustomerId, Total FROM Orders WHERE Id = @id;
          SELECT Id, OrderId, Sku, Qty FROM OrderLines WHERE OrderId = @id;
          """)]
      public partial Task<(OrderRow Head, IReadOnlyList<OrderLineRow> Lines)?> GetWithLinesAsync(
          int id, CancellationToken ct);
  }
  

• Batch dispatch (BatchMode.Auto / Always / Never) — [Query(Batch = ...)] picks how multi-statement SQL reaches the provider. Auto (default) branches at runtime on connection.CanCreateBatch: providers exposing IAsyncDbBatch get the pipelined path; everyone else falls back to a single command with ;-joined SQL and NextResultAsync. Both paths produce the same materialized tuple.

• IAsyncEnumerable<T> streaming — partial methods returning IAsyncEnumerable<T> with a [EnumeratorCancellation] CancellationToken parameter emit an async iterator that materializes rows lazily. Connection opens on first MoveNextAsync, closes deterministically on DisposeAsync (including early break exits). See docs/cookbook/streaming.md.

  public sealed partial class OrderRepo(IAsyncDbConnection connection)
  {
      [Query("SELECT Id, CustomerId, Total FROM Orders ORDER BY Id")]
      public partial IAsyncEnumerable<OrderRow> StreamAllAsync(
          [EnumeratorCancellation] CancellationToken ct);
  }
  

• New diagnostics ZAO032 / ZAO033 — arity mismatch between a tuple return and the number of ;-separated SQL statements. ZAO032 fires when the tuple has more elements than statements; ZAO033 fires when it has fewer. Both at build time, so the wrong shape never ships.

Deferred to later milestones: [Command] / [StoredProcedure] (v0.4), multi-column composite types (v0.5).

Design + roadmap

• Design: docs/design/2026-05-30-v1.0-design.md — 5-section v1.0 design covering architecture, generator surface, convention discovery, diagnostics, test strategy, milestones.
• Backlog: docs/plans/za-orm-backlog.md — priority-banded task list. New findings during implementation get appended.
• Ecosystem context: sits alongside ZeroAlloc.Mediator, ZeroAlloc.Mapping, ZeroAlloc.ValueObjects, ZeroAlloc.Validation. Substrate is AdoNet.Async (AOT-compatible since v1.x).

License

MIT