StreamEventState + StreamEvents result types for Marten.AspNetCore

[jeremydmiller]

Builds on the FetchStreamStatePlan / FetchStreamPlan query plans from #5043 (@uniquelau), now merged. That PR was conflicting on docs/cSpell.json — #5049 had landed "jasperfx" in the same slot in the words array — so I pushed the resolution to its branch and merged it; this PR has been rebased and now carries only the ASP.NET Core work.

What this adds

The event-side siblings of StreamAggregate<T>, backed by those two plans. Both implement IResult and IEndpointMetadataProvider like the rest of the family:

app.MapGet("/orders/{id:guid}/state",  (Guid id, IQuerySession s) => new StreamEventState(s, id));
app.MapGet("/orders/{id:guid}/events", (Guid id, IQuerySession s) => new StreamEvents(s, id));

Both also accept a pre-built plan, so a handler can share one plan between a batched query and its HTTP result:

var plan = new FetchStreamPlan(orderId, version: 5);
var fetcher = batch.QueryByPlan(plan);   // batch it...
return new StreamEvents(session, plan);  // ...or return it

Why the wire types aren't Marten's own

Neither StreamState nor IEvent can be written to the response directly. StreamState.AggregateType and IEvent.EventType are System.Type, and System.Text.Json refuses to serialize those:

NotSupportedException: Serialization and deserialization of 'System.Type' instances
is not supported. Path: $.AggregateType.

I verified this against the actual store serializer before designing around it — both types throw, so a result that serialized them naively would fail at runtime for every STJ user. StreamStateResponse and EventResponse project them onto stable wire shapes: the aggregate type reduces to its simple name, and IEvent's assembly-qualified DotNetTypeName is deliberately left off the wire (EventTypeName, Marten's event type alias, is the discriminator clients should key on).

Empty streams

FetchStream yields an empty list both for a stream that does not exist and for a filter that excludes every event, and the two cannot be told apart. StreamEvents therefore exposes OnEmptyStatus, defaulting to 404 to match the other single-resource results — set it to 200 when running off the end is expected, as when paging forward with fromVersion.

Details

• Serialization buffers through an ArrayBufferWriter<byte> and ISerializer.WriteTo, so the JSON never round-trips through a .NET string; Content-Length is set on both.
• WriteStreamState / WriteEvents extension methods on IQuerySession carry the actual write, mirroring how StreamOne delegates to WriteSingle.
• string stream key overloads on both, and the version / timestamp / fromVersion filters on StreamEvents.

Tests and docs

12 new Alba tests against real Minimal API endpoints, covering both results, the plan constructor, the OnEmptyStatus opt-out, Content-Length, the serialized event body, and OpenAPI metadata. Full Marten.AspNetCore.Testing suite: 97 passed, re-run green after the rebase.

Docs: the result-type table in documents/aspnetcore.md grows to seven entries, with new sections for both types (including the JSON each writes and the empty-stream discussion), the "StreamOne vs StreamAggregate" section becomes a four-way "Choosing between the result types", and events/querying.md cross-links from the query plan section. markdownlint and cspell clean over all of docs/.

Polecat parity tracked at JasperFx/polecat#370.

🤖 Generated with Claude Code