Up and running with the ability to get read model instances as collection and project multiple events not bound to an event source id

einari · einari · commit 80a30eb22631 · 2026-02-04T17:15:40.000+01:00
diff --git a/.github/workflows/dotnet-build.yml b/.github/workflows/dotnet-build.yml
@@ -116,6 +116,7 @@ jobs:
           - 'for_JobsManager'
           - 'for_Reactors'
           - 'for_Reducers'
+          - 'for_ReadModels'
           - 'for_Webhooks'
           - 'Jobs'
           - 'Projections'
diff --git a/Integration/DotNET.InProcess/for_ReadModels/AnotherEvent.cs b/Integration/DotNET.InProcess/for_ReadModels/AnotherEvent.cs
@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using Cratis.Chronicle.Events;
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels;
+
+[EventType("2d1f20ee-f0fd-5b82-cfa9-cf6eefb23c63")]
+public record AnotherEvent(string Value);
diff --git a/Integration/DotNET.InProcess/for_ReadModels/SomeEvent.cs b/Integration/DotNET.InProcess/for_ReadModels/SomeEvent.cs
@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using Cratis.Chronicle.Events;
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels;
+
+[EventType("1c0f19dd-e9fc-4a71-bfa8-bf5eefb12b52")]
+public record SomeEvent(int Number);
diff --git a/Integration/DotNET.InProcess/for_ReadModels/SomeProjection.cs b/Integration/DotNET.InProcess/for_ReadModels/SomeProjection.cs
@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels;
+
+public class SomeProjection : IProjectionFor<SomeReadModel>
+{
+    public ProjectionId Identifier => "some-projection";
+
+    public void Define(IProjectionBuilderFor<SomeReadModel> builder) => builder
+        .From<SomeEvent>(e => e
+            .Set(m => m.Number).To(e => e.Number))
+        .From<AnotherEvent>(e => e
+            .Set(m => m.Value).To(e => e.Value));
+}
diff --git a/Integration/DotNET.InProcess/for_ReadModels/SomeReadModel.cs b/Integration/DotNET.InProcess/for_ReadModels/SomeReadModel.cs
@@ -0,0 +1,6 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels;
+
+public record SomeReadModel(int Number, string Value);
diff --git a/Integration/DotNET.InProcess/for_ReadModels/given/a_projection_with_events.cs b/Integration/DotNET.InProcess/for_ReadModels/given/a_projection_with_events.cs
@@ -0,0 +1,29 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using Cratis.Chronicle.Events;
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels.given;
+
+public class a_projection_with_events(ChronicleInProcessFixture chronicleInProcessFixture) : Specification(chronicleInProcessFixture)
+{
+    public EventSourceId EventSourceId;
+    public SomeEvent FirstEvent;
+    public AnotherEvent SecondEvent;
+
+    public override IEnumerable<Type> EventTypes => [typeof(SomeEvent), typeof(AnotherEvent)];
+    public override IEnumerable<Type> Projections => [typeof(SomeProjection)];
+
+    protected void Establish()
+    {
+        EventSourceId = "some-source";
+        FirstEvent = new SomeEvent(42);
+        SecondEvent = new AnotherEvent("test-value");
+    }
+
+    protected async Task AppendEvents()
+    {
+        await EventStore.EventLog.Append(EventSourceId, FirstEvent);
+        await EventStore.EventLog.Append(EventSourceId, SecondEvent);
+    }
+}
diff --git a/Integration/DotNET.InProcess/for_ReadModels/when_getting_instance_with_unspecified_key/and_events_exist.cs b/Integration/DotNET.InProcess/for_ReadModels/when_getting_instance_with_unspecified_key/and_events_exist.cs
@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using Cratis.Chronicle.ReadModels;
+using context = Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instance_with_unspecified_key.and_events_exist.context;
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instance_with_unspecified_key;
+
+[Collection(ChronicleCollection.Name)]
+public class and_events_exist(context context) : Given<context>(context)
+{
+    public class context(ChronicleInProcessFixture chronicleInProcessFixture) : given.a_projection_with_events(chronicleInProcessFixture)
+    {
+        public SomeReadModel Result;
+
+        async Task Because()
+        {
+            await AppendEvents();
+            Result = await EventStore.ReadModels.GetInstanceById<SomeReadModel>(ReadModelKey.Unspecified);
+        }
+    }
+
+    [Fact] void should_have_number_from_first_event() => Context.Result.Number.ShouldEqual(Context.FirstEvent.Number);
+    [Fact] void should_have_value_from_second_event() => Context.Result.Value.ShouldEqual(Context.SecondEvent.Value);
+}
diff --git a/Integration/DotNET.InProcess/for_ReadModels/when_getting_instance_with_unspecified_key/and_multiple_event_sources_exist.cs b/Integration/DotNET.InProcess/for_ReadModels/when_getting_instance_with_unspecified_key/and_multiple_event_sources_exist.cs
@@ -0,0 +1,38 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using Cratis.Chronicle.Events;
+using Cratis.Chronicle.ReadModels;
+using context = Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instance_with_unspecified_key.and_multiple_event_sources_exist.context;
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instance_with_unspecified_key;
+
+[Collection(ChronicleCollection.Name)]
+public class and_multiple_event_sources_exist(context context) : Given<context>(context)
+{
+    public class context(ChronicleInProcessFixture chronicleInProcessFixture) : given.a_projection_with_events(chronicleInProcessFixture)
+    {
+        public EventSourceId SecondEventSourceId;
+        public SomeEvent ThirdEvent;
+        public AnotherEvent FourthEvent;
+        public SomeReadModel Result;
+
+        void Establish()
+        {
+            SecondEventSourceId = "another-source";
+            ThirdEvent = new SomeEvent(100);
+            FourthEvent = new AnotherEvent("another-value");
+        }
+
+        async Task Because()
+        {
+            await AppendEvents();
+            await EventStore.EventLog.Append(SecondEventSourceId, ThirdEvent);
+            await EventStore.EventLog.Append(SecondEventSourceId, FourthEvent);
+            Result = await EventStore.ReadModels.GetInstanceById<SomeReadModel>(ReadModelKey.Unspecified);
+        }
+    }
+
+    [Fact] void should_have_number_from_last_event() => Context.Result.Number.ShouldEqual(Context.ThirdEvent.Number);
+    [Fact] void should_have_value_from_last_event() => Context.Result.Value.ShouldEqual(Context.FourthEvent.Value);
+}
diff --git a/Integration/DotNET.InProcess/for_ReadModels/when_getting_instances/with_limited_event_count.cs b/Integration/DotNET.InProcess/for_ReadModels/when_getting_instances/with_limited_event_count.cs
@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using context = Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instances.with_limited_event_count.context;
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instances;
+
+[Collection(ChronicleCollection.Name)]
+public class with_limited_event_count(context context) : Given<context>(context)
+{
+    public class context(ChronicleInProcessFixture chronicleInProcessFixture) : given.a_projection_with_events(chronicleInProcessFixture)
+    {
+        public IEnumerable<SomeReadModel> Results;
+
+        async Task Because()
+        {
+            await AppendEvents();
+            Results = await EventStore.ReadModels.GetInstances<SomeReadModel>(1);
+        }
+    }
+
+    [Fact] void should_return_single_instance() => Context.Results.Count().ShouldEqual(1);
+    [Fact] void should_have_number_from_first_event() => Context.Results.First().Number.ShouldEqual(Context.FirstEvent.Number);
+    [Fact] void should_not_have_value_from_second_event() => Context.Results.First().Value.ShouldBeNull();
+}
diff --git a/Integration/DotNET.InProcess/for_ReadModels/when_getting_instances/with_multiple_event_sources.cs b/Integration/DotNET.InProcess/for_ReadModels/when_getting_instances/with_multiple_event_sources.cs
@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using Cratis.Chronicle.Events;
+using context = Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instances.with_multiple_event_sources.context;
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instances;
+
+[Collection(ChronicleCollection.Name)]
+public class with_multiple_event_sources(context context) : Given<context>(context)
+{
+    public class context(ChronicleInProcessFixture chronicleInProcessFixture) : given.a_projection_with_events(chronicleInProcessFixture)
+    {
+        public EventSourceId SecondEventSourceId;
+        public SomeEvent ThirdEvent;
+        public AnotherEvent FourthEvent;
+        public IEnumerable<SomeReadModel> Results;
+
+        void Establish()
+        {
+            SecondEventSourceId = "another-source";
+            ThirdEvent = new SomeEvent(100);
+            FourthEvent = new AnotherEvent("another-value");
+        }
+
+        async Task Because()
+        {
+            await AppendEvents();
+            await EventStore.EventLog.Append(SecondEventSourceId, ThirdEvent);
+            await EventStore.EventLog.Append(SecondEventSourceId, FourthEvent);
+            Results = await EventStore.ReadModels.GetInstances<SomeReadModel>();
+        }
+    }
+
+    [Fact] void should_return_two_instances() => Context.Results.Count().ShouldEqual(2);
+    [Fact] void should_have_first_instance_with_first_events() => Context.Results.First().Number.ShouldEqual(Context.FirstEvent.Number);
+    [Fact] void should_have_first_instance_value() => Context.Results.First().Value.ShouldEqual(Context.SecondEvent.Value);
+    [Fact] void should_have_second_instance_with_second_events() => Context.Results.Last().Number.ShouldEqual(Context.ThirdEvent.Number);
+    [Fact] void should_have_second_instance_value() => Context.Results.Last().Value.ShouldEqual(Context.FourthEvent.Value);
+}
diff --git a/Integration/DotNET.InProcess/for_ReadModels/when_getting_instances/without_event_count.cs b/Integration/DotNET.InProcess/for_ReadModels/when_getting_instances/without_event_count.cs
@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using context = Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instances.without_event_count.context;
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instances;
+
+[Collection(ChronicleCollection.Name)]
+public class without_event_count(context context) : Given<context>(context)
+{
+    public class context(ChronicleInProcessFixture chronicleInProcessFixture) : given.a_projection_with_events(chronicleInProcessFixture)
+    {
+        public IEnumerable<SomeReadModel> Results;
+
+        async Task Because()
+        {
+            await AppendEvents();
+            Results = await EventStore.ReadModels.GetInstances<SomeReadModel>();
+        }
+    }
+
+    [Fact] void should_return_single_instance() => Context.Results.Count().ShouldEqual(1);
+    [Fact] void should_have_number_from_first_event() => Context.Results.First().Number.ShouldEqual(Context.FirstEvent.Number);
+    [Fact] void should_have_value_from_second_event() => Context.Results.First().Value.ShouldEqual(Context.SecondEvent.Value);
+}
diff --git a/Source/Clients/DotNET/Events/EventCount.cs b/Source/Clients/DotNET/Events/EventCount.cs
@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Cratis.Chronicle.Events;
+
+/// <summary>
+/// Represents a count of events.
+/// </summary>
+/// <param name="Value">The actual count.</param>
+public record EventCount(ulong Value) : ConceptAs<ulong>(Value)
+{
+    /// <summary>
+    /// The value representing an unlimited count.
+    /// </summary>
+    public static readonly EventCount Unlimited = ulong.MaxValue;
+
+    /// <summary>
+    /// The value representing zero.
+    /// </summary>
+    public static readonly EventCount Zero = 0L;
+
+    /// <summary>
+    /// Implicitly convert from <see cref="ulong"/> to <see cref="EventCount"/>.
+    /// </summary>
+    /// <param name="value">Value to convert from.</param>
+    public static implicit operator EventCount(ulong value) => new(value);
+
+    /// <summary>
+    /// Implicitly convert from <see cref="long"/> to <see cref="EventCount"/>.
+    /// </summary>
+    /// <param name="value">Value to convert from.</param>
+    public static implicit operator EventCount(long value) => new((ulong)value);
+
+    /// <summary>
+    /// Implicitly convert from <see cref="int"/> to <see cref="EventCount"/>.
+    /// </summary>
+    /// <param name="value">Value to convert from.</param>
+    public static implicit operator EventCount(int value) => new((ulong)value);
+}
diff --git a/Source/Clients/DotNET/ReadModels/IReadModels.cs b/Source/Clients/DotNET/ReadModels/IReadModels.cs
@@ -1,6 +1,8 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+using Cratis.Chronicle.Events;
+
 namespace Cratis.Chronicle.ReadModels;
 
 /// <summary>
@@ -39,6 +41,14 @@ public interface IReadModels
     /// <returns>The read model instance.</returns>
     Task<object> GetInstanceById(Type readModelType, ReadModelKey key, ReadModelSessionId? sessionId = null);
 
+    /// <summary>
+    /// Get all instances of a read model by applying all events.
+    /// </summary>
+    /// <typeparam name="TReadModel">The read model type.</typeparam>
+    /// <param name="eventCount">Optional maximum number of events to process. Defaults to <see cref="EventCount.Unlimited"/>.</param>
+    /// <returns>Collection of read model instances.</returns>
+    Task<IEnumerable<TReadModel>> GetInstances<TReadModel>(EventCount? eventCount = null);
+
     /// <summary>
     /// Get snapshots of a read model grouped by CorrelationId by walking through events from the beginning.
     /// </summary>
diff --git a/Source/Clients/DotNET/ReadModels/ReadModels.cs b/Source/Clients/DotNET/ReadModels/ReadModels.cs
@@ -182,6 +182,34 @@ public async Task<object> GetInstanceById(Type readModelType, ReadModelKey key,
         return instance ?? throw new InvalidOperationException($"Read model returned null for type '{readModelType.Name}' with key '{key.Value}'");
     }
 
+    /// <inheritdoc/>
+    public async Task<IEnumerable<TReadModel>> GetInstances<TReadModel>(EventCount? eventCount = null)
+    {
+        var readModelType = typeof(TReadModel);
+
+        // Validate that the read model is known by projections (immediate projections only)
+        if (!projections.HasFor(readModelType))
+        {
+            throw new UnknownReadModel(readModelType);
+        }
+
+        var readModelIdentifier = readModelType.GetReadModelIdentifier();
+        var eventCountValue = eventCount ?? EventCount.Unlimited;
+
+        var request = new GetAllInstancesRequest
+        {
+            EventStore = eventStore.Name,
+            Namespace = eventStore.Namespace,
+            ReadModelIdentifier = readModelIdentifier,
+            EventSequenceId = EventSequenceId.Log,
+            EventCount = eventCountValue.Value
+        };
+
+        var response = await _chronicleServicesAccessor.Services.ReadModels.GetAllInstances(request);
+
+        return response.Instances.Select(json => JsonSerializer.Deserialize<TReadModel>(json, jsonSerializerOptions)!);
+    }
+
     /// <inheritdoc/>
     public async Task<IEnumerable<ReadModelSnapshot<TReadModel>>> GetSnapshotsById<TReadModel>(ReadModelKey readModelKey)
     {
diff --git a/Source/Kernel/Contracts/ReadModels/GetAllInstancesRequest.cs b/Source/Kernel/Contracts/ReadModels/GetAllInstancesRequest.cs
@@ -0,0 +1,41 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Cratis.Chronicle.Contracts.ReadModels;
+
+/// <summary>
+/// Represents the request for getting all instances of a read model by processing events.
+/// </summary>
+[ProtoContract]
+public class GetAllInstancesRequest
+{
+    /// <summary>
+    /// Gets or sets the name of the event store.
+    /// </summary>
+    [ProtoMember(1)]
+    public string EventStore { get; set; }
+
+    /// <summary>
+    /// Gets or sets the namespace of the read model.
+    /// </summary>
+    [ProtoMember(2)]
+    public string Namespace { get; set; }
+
+    /// <summary>
+    /// Gets or sets the identifier of the read model.
+    /// </summary>
+    [ProtoMember(3)]
+    public string ReadModelIdentifier { get; set; }
+
+    /// <summary>
+    /// Gets or sets the event sequence ID.
+    /// </summary>
+    [ProtoMember(4), DefaultValue("event-log")]
+    public string EventSequenceId { get; set; } = "event-log";
+
+    /// <summary>
+    /// Gets or sets the maximum number of events to process. If not set or set to ulong.MaxValue, all events will be processed.
+    /// </summary>
+    [ProtoMember(5), DefaultValue(ulong.MaxValue)]
+    public ulong EventCount { get; set; } = ulong.MaxValue;
+}
diff --git a/Source/Kernel/Contracts/ReadModels/GetAllInstancesResponse.cs b/Source/Kernel/Contracts/ReadModels/GetAllInstancesResponse.cs
diff --git a/Source/Kernel/Contracts/ReadModels/IReadModels.cs b/Source/Kernel/Contracts/ReadModels/IReadModels.cs
diff --git a/Source/Kernel/Services/ReadModels/ReadModels.cs b/Source/Kernel/Services/ReadModels/ReadModels.cs
