Merge pull request #2338 from Cratis:fix/projections-fixing

Fix/projections-fixing

Author: einari

Documentation/projections/declarative/auto-map.md

@@ -168,11 +168,12 @@ public void Define(IProjectionBuilderFor<Company> builder) => builder
         // AutoMap inherited from parent
         .From<DepartmentCreated>(_ => _
             .UsingKey(e => e.DepartmentId))
+        // No parent key specified - uses EventSourceId (CompanyId) by default
         .Children(dm => dm.Employees, employees => employees
             .IdentifiedBy(e => e.EmployeeId)
             // AutoMap still applies at this nested level
             .From<EmployeeAssignedToDepartment>(_ => _
-                .UsingParentKey(e => e.DepartmentId)
+                .UsingParentKey(e => e.DepartmentId)  // Extracts from event content
                 .UsingKey(e => e.EmployeeId))));
 ```
 

Documentation/projections/declarative/children.md

@@ -66,6 +66,71 @@ public record UserRemovedFromGroup(string UserId);
 4. `UsingKey()` tells the projection which property contains the child identifier
 5. Child items are created, updated, or remain unchanged based on the events
 
+## Parent key resolution
+
+By default, when a child event is processed, the framework uses the **EventSourceId** to identify the parent. This works well when the event is appended with the parent's identifier as the EventSourceId.
+
+### Default behavior (EventSourceId as parent key)
+
+In most scenarios, you don't need to specify the parent key explicitly:
+
+```csharp
+.Children(m => m.Members, children => children
+    .IdentifiedBy(e => e.UserId)
+    .AutoMap()
+    .From<UserAddedToGroup>(b => b
+        .UsingKey(e => e.UserId)))
+    // No UsingParentKey needed - uses EventSourceId by default
+```
+
+When you append the event:
+```csharp
+await EventStore.EventLog.Append(groupId, new UserAddedToGroup(userId, role));
+```
+
+The `groupId` (EventSourceId) is automatically used to find the parent `Group`.
+
+### Extracting parent key from event content
+
+If your event contains the parent key as a property (instead of using EventSourceId), use `UsingParentKey()`:
+
+```csharp
+.Children(m => m.Members, children => children
+    .IdentifiedBy(e => e.UserId)
+    .AutoMap()
+    .From<UserAddedToGroup>(b => b
+        .UsingParentKey(e => e.GroupId)  // Extract from event content
+        .UsingKey(e => e.UserId)))
+```
+
+When you append the event:
+```csharp
+await EventStore.EventLog.Append(userId, new UserAddedToGroup(userId, groupId, role));
+```
+
+The `groupId` property from the event content is used to find the parent `Group`.
+
+### Using EventSourceId explicitly with UsingParentKeyFromContext
+
+In some advanced scenarios, you might want to explicitly indicate that the EventSourceId should be used as the parent key (e.g., for documentation clarity):
+
+```csharp
+.Children(m => m.Members, children => children
+    .IdentifiedBy(e => e.UserId)
+    .AutoMap()
+    .From<UserAddedToGroup>(b => b
+        .UsingParentKeyFromContext(ctx => ctx.EventSourceId)  // Explicit
+        .UsingKey(e => e.UserId)))
+```
+
+This is functionally equivalent to not specifying the parent key at all, but can make the intent clearer in complex projections.
+
+### When to use each approach
+
+- **No parent key specified** (default): Use when EventSourceId represents the parent identifier
+- **`UsingParentKey(e => e.Property)`**: Use when parent identifier is in the event content
+- **`UsingParentKeyFromContext(ctx => ctx.EventSourceId)`**: Use for explicit documentation of default behavior
+
 ## Child lifecycle
 
 - **Adding children**: When a new event arrives with a previously unseen key, a new child is created

Documentation/projections/declarative/index.md

@@ -40,9 +40,14 @@ Declarative Projections in Cratis allow you to create read models from events st
 
 ### Keys and identification
 
-- Event source ID is used as the default key for read models
-- Child collections use custom identifiers for individual items
-- Joins use keys to link data from different streams
+- **EventSourceId** is used as the default key for both read models and parent identification in child collections
+- **Child identifiers**: Use `.IdentifiedBy()` to specify how child items are uniquely identified within collections
+- **Parent key resolution**:
+  - By default, the EventSourceId is used to identify the parent when adding children
+  - Use `.UsingParentKey(e => e.Property)` when the parent identifier is in the event content
+  - Use `.UsingParentKeyFromContext(ctx => ctx.EventSourceId)` to explicitly document default behavior
+- **Child key specification**: Use `.UsingKey(e => e.Property)` to extract the child identifier from event content
+- **Joins**: Use keys to link data from different event streams using `.On(m => m.Property)`
 
 ### Performance
 

Documentation/projections/declarative/remove-with-join.md

@@ -32,9 +32,12 @@ public class UserProjection : IProjectionFor<User>
 In this example:
 
 - When a `UserAddedToGroup` event occurs, a group is added to the user's collection
+- `UsingParentKey(e => e.UserId)` extracts the parent (user) identifier from the event content
 - When a `GroupDeleted` event occurs anywhere in the system, that group is removed from all users
 - The removal is based on the group ID that was used to join the data
 
+> **Note**: If you don't specify `UsingParentKey()`, the framework uses the EventSourceId as the parent identifier by default. Use `UsingParentKey()` when the parent identifier is a property in the event content rather than the EventSourceId.
+
 ## How RemoveWithJoin works
 
 When using `RemovedWithJoin<>()`:

Documentation/projections/model-bound/children.md

@@ -34,6 +34,8 @@ In this example, the `[Key]` attribute on the `LineItem.Id` property is automati
   2. Look for a property named `Id` (case-insensitive)
   3. Fall back to `EventSourceId` if neither is found
 - **parentKey** (optional): Property that identifies the parent. Defaults to `EventSourceId`
+  - Use this when the parent identifier is a property in the event content rather than the EventSourceId
+  - Example: `parentKey: nameof(LineItemAdded.OrderId)` when OrderId is in the event
 - **autoMap** (optional): Whether to automatically map matching properties from the event to the child model. Defaults to `true`
 
 > **Note**: With automatic key discovery, you typically don't need to specify `identifiedBy` explicitly. Just mark your child model's key property with `[Key]` attribute, or name it `Id`, and Chronicle will automatically discover it.

Integration/DotNET.InProcess/Projections/Scenarios/when_projecting_with_children_within_children_using_parent_key_from_context/Events/HubAddedToSimulationConfiguration.cs

@@ -7,4 +7,4 @@
 namespace Cratis.Chronicle.InProcess.Integration.Projections.Scenarios.when_projecting_with_children_within_children_using_parent_key_from_context.Events;
 
 [EventType]
-public record HubAddedToSimulationConfiguration(ConfigurationId ConfigurationId, HubId HubId, string Name);
+public record HubAddedToSimulationConfiguration(HubId HubId, string Name);

Integration/DotNET.InProcess/Projections/Scenarios/when_projecting_with_children_within_children_using_parent_key_from_context/Events/WeightsSetForSimulationConfiguration.cs

@@ -0,0 +1,13 @@
+// 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.Projections.Scenarios.when_projecting_with_children_within_children_using_parent_key_from_context.Events;
+
+[EventType]
+public record WeightsSetForSimulationConfiguration(
+    double Distance,
+    double Time,
+    double Cost,
+    double Waste);

Integration/DotNET.InProcess/Projections/Scenarios/when_projecting_with_children_within_children_using_parent_key_from_context/ReadModels/SimulationConfiguration.cs

@@ -12,5 +12,11 @@ public class SimulationConfiguration
     public ConfigurationId ConfigurationId { get; set; } = ConfigurationId.NotSet;
 
     public string Name { get; set; } = string.Empty;
+
+    public double Distance { get; set; }
+    public double Time { get; set; }
+    public double Cost { get; set; }
+    public double Waste { get; set; }
+
     public IList<Hub> Hubs { get; set; } = [];
 }

Integration/DotNET.InProcess/Projections/Scenarios/when_projecting_with_children_within_children_using_parent_key_from_context/SimulationDashboardProjection.cs

@@ -18,12 +18,9 @@ public void Define(IProjectionBuilderFor<SimulationDashboard> builder) => builde
         .From<SimulationAdded>()
         .Children(m => m.Configurations, m => m
             .IdentifiedBy(r => r.ConfigurationId)
-            .From<SimulationConfigurationAdded>(b => b
-                .UsingParentKeyFromContext(ctx => ctx.EventSourceId)
-                .UsingKey(e => e.ConfigurationId))
+            .From<SimulationConfigurationAdded>(b => b.UsingKey(e => e.ConfigurationId))
+            .From<WeightsSetForSimulationConfiguration>()
             .Children(m => m.Hubs, m => m
                 .IdentifiedBy(r => r.HubId)
-                .From<HubAddedToSimulationConfiguration>(e => e
-                    .UsingParentKey(e => e.ConfigurationId)
-                    .UsingKey(e => e.HubId))));
+                .From<HubAddedToSimulationConfiguration>(e => e.UsingKey(e => e.HubId))));
 }

Integration/DotNET.InProcess/Projections/Scenarios/when_projecting_with_children_within_children_using_parent_key_from_context/and_all_events_are_appended_in_one_transaction.cs

@@ -0,0 +1,105 @@
+// 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.Auditing;
+using Cratis.Chronicle.Events;
+using Cratis.Chronicle.EventSequences;
+using Cratis.Chronicle.InProcess.Integration.Projections.Scenarios.when_projecting_with_children_within_children_using_parent_key_from_context.Concepts;
+using Cratis.Chronicle.InProcess.Integration.Projections.Scenarios.when_projecting_with_children_within_children_using_parent_key_from_context.Events;
+using Cratis.Chronicle.InProcess.Integration.Projections.Scenarios.when_projecting_with_children_within_children_using_parent_key_from_context.ReadModels;
+using Cratis.Chronicle.Observation;
+using MongoDB.Driver;
+using context = Cratis.Chronicle.InProcess.Integration.Projections.Scenarios.when_projecting_with_children_within_children_using_parent_key_from_context.and_all_events_are_appended_in_one_transaction.context;
+
+namespace Cratis.Chronicle.InProcess.Integration.Projections.Scenarios.when_projecting_with_children_within_children_using_parent_key_from_context;
+
+[Collection(ChronicleCollection.Name)]
+public class and_all_events_are_appended_in_one_transaction(context context) : Given<context>(context)
+{
+    const string SimulationName = "Test Simulation";
+    const string ConfigurationName = "Test Configuration";
+    const string HubName = "Test Hub";
+
+    const double Distance = 100.0;
+    const double Time = 2.5;
+    const double Cost = 50.0;
+    const double Waste = 10.0;
+
+    public class context(ChronicleInProcessFixture fixture) : Specification(fixture)
+    {
+        public SimulationId SimulationId;
+        public ConfigurationId ConfigurationId;
+        public HubId HubId;
+        public IEnumerable<FailedPartition> FailedPartitions = [];
+        public SimulationDashboard Result;
+        public EventSequenceNumber LastEventSequenceNumber = EventSequenceNumber.First;
+
+        public override IEnumerable<Type> EventTypes => [typeof(SimulationAdded), typeof(SimulationConfigurationAdded), typeof(HubAddedToSimulationConfiguration), typeof(WeightsSetForSimulationConfiguration)];
+        public override IEnumerable<Type> Projections => [typeof(SimulationDashboardProjection)];
+
+        protected override void ConfigureServices(IServiceCollection services)
+        {
+            services.AddSingleton(new SimulationDashboardProjection());
+        }
+
+        void Establish()
+        {
+            SimulationId = Guid.Parse("0089d57f-9095-4b56-b948-ab170de8e0ee");
+            ConfigurationId = Guid.Parse("754fd741-adae-4fbd-8c47-2d622cc0b274");
+            HubId = Guid.Parse("eff2cf7a-4121-438b-94fd-139775a09f57");
+        }
+
+        async Task Because()
+        {
+            var projection = EventStore.Projections.GetHandlerFor<SimulationDashboardProjection>();
+            await projection.WaitTillActive();
+
+            var events = new EventForEventSourceId[]
+            {
+                new(ConfigurationId, new WeightsSetForSimulationConfiguration(Distance, Time, Cost, Waste), Causation.Unknown()),
+                new(ConfigurationId, new HubAddedToSimulationConfiguration(HubId, HubName), Causation.Unknown()),
+                new(SimulationId, new SimulationAdded(SimulationName), Causation.Unknown()),
+                new(SimulationId, new SimulationConfigurationAdded(ConfigurationId, ConfigurationName), Causation.Unknown())
+            };
+
+            var appendResult = await EventStore.EventLog.AppendMany(events);
+            LastEventSequenceNumber = appendResult.SequenceNumbers.Last();
+
+            await projection.WaitTillReachesEventSequenceNumber(LastEventSequenceNumber);
+
+            FailedPartitions = await projection.GetFailedPartitions();
+
+            var collection = ChronicleFixture.ReadModels.Database.GetCollection<SimulationDashboard>();
+            var queryResult = await collection.FindAsync(_ => true);
+            var allResults = await queryResult.ToListAsync();
+            Result = allResults.FirstOrDefault();
+        }
+    }
+
+    [Fact]
+    void should_have_no_failed_partitions()
+    {
+        if (Context.FailedPartitions.Any())
+        {
+            var failures = Context.FailedPartitions.ToList();
+            var messages = failures.SelectMany(f => f.Attempts.Select(a => a.Messages)).SelectMany(m => m).ToList();
+            var stackTraces = failures.SelectMany(f => f.Attempts.Select(a => a.StackTrace)).ToList();
+            var combined = string.Join("\n\n", messages.Zip(stackTraces, (msg, stack) => $"Message: {msg}\nStack: {stack}"));
+            throw new Xunit.Sdk.XunitException($"Failed partitions:\n{combined}");
+        }
+    }
+
+    [Fact] void should_return_model() => Context.Result.ShouldNotBeNull();
+    [Fact] void should_have_simulation_name() => Context.Result.Name.ShouldEqual(SimulationName);
+    [Fact] void should_have_one_configuration() => Context.Result.Configurations.Count.ShouldEqual(1);
+    [Fact] void should_have_configuration_id_on_child() => Context.Result.Configurations[0].ConfigurationId.ShouldEqual(Context.ConfigurationId);
+    [Fact] void should_have_configuration_name_on_child() => Context.Result.Configurations[0].Name.ShouldEqual(ConfigurationName);
+    [Fact] void should_have_one_hub_on_configuration() => Context.Result.Configurations[0].Hubs.Count.ShouldEqual(1);
+    [Fact] void should_have_hub_id_on_nested_child() => Context.Result.Configurations[0].Hubs[0].HubId.ShouldEqual(Context.HubId);
+    [Fact] void should_have_hub_name_on_nested_child() => Context.Result.Configurations[0].Hubs[0].Name.ShouldEqual(HubName);
+    [Fact] void should_set_the_event_sequence_number_to_last_event() => Context.Result.__lastHandledEventSequenceNumber.ShouldEqual(Context.LastEventSequenceNumber);
+    [Fact] void should_set_distance_on_configuration() => Context.Result.Configurations[0].Distance.ShouldEqual(Distance);
+    [Fact] void should_set_time_on_configuration() => Context.Result.Configurations[0].Time.ShouldEqual(Time);
+    [Fact] void should_set_cost_on_configuration() => Context.Result.Configurations[0].Cost.ShouldEqual(Cost);
+    [Fact] void should_set_waste_on_configuration() => Context.Result.Configurations[0].Waste.ShouldEqual(Waste);
+}