@cratis/chronicle 6.17.0 → 6.18.0

package/projections/Projections.childrenAndNested.spec.ts

@@ -10,7 +10,10 @@ import { ChronicleConnection } from '../connection/index.js';
 import { eventType } from '../events/eventTypeDecorator.js';
 import { childrenFrom } from './modelBound/childrenFrom.js';
 import { clearWith } from './modelBound/clearWith.js';
+import { count } from './modelBound/count.js';
+import { decrement } from './modelBound/decrement.js';
 import { fromEvent } from './modelBound/fromEvent.js';
+import { increment } from './modelBound/increment.js';
 import { nested } from './modelBound/nested.js';
 import { noAutoMap } from './modelBound/noAutoMap.js';
 import { setFrom } from './modelBound/setFrom.js';
@@ -22,6 +25,7 @@ import { Projections } from './Projections.js';
 class LineAdded {
     productId!: string;
     quantity!: number;
+    label!: string;
 }
 eventType()(LineAdded);
 
@@ -30,6 +34,11 @@ class LineQuantityChanged {
 }
 eventType()(LineQuantityChanged);
 
+class AlternateLineAdded {
+    alternateId!: string;
+}
+eventType()(AlternateLineAdded);
+
 class LineQuantityCleared {}
 eventType()(LineQuantityCleared);
 
@@ -71,6 +80,117 @@ setFrom(LineQuantityChanged)(OrderLine.prototype, 'quantity');
 noAutoMap(OrderLine.prototype, 'quantity');
 clearWith(LineQuantityCleared)(OrderLine.prototype, 'quantity');
 
+class ChildWithId {
+    id = '';
+    label = '';
+}
+class ChildWithUppercaseId {
+    Id = '';
+}
+class ChildWithExplicitId {
+    employeeNumber = '';
+    label = '';
+}
+class ChildWithMatchingEventKey {
+    productId = '';
+}
+class ChildWithMappedId {
+    id = '';
+}
+setFrom(LineAdded, 'productId')(ChildWithMappedId.prototype, 'id');
+class ChildWithoutAutoMap {
+    id = '';
+}
+noAutoMap(ChildWithoutAutoMap);
+class ChildWithNoAutoMappedId {
+    id = '';
+}
+noAutoMap(ChildWithNoAutoMappedId.prototype, 'id');
+class ChildWithConstantCount {
+    id = '';
+    total = 0;
+    label = '';
+}
+count(LineAdded, 'all')(ChildWithConstantCount.prototype, 'total');
+class ChildWithConstantIncrement {
+    id = '';
+    total = 0;
+    label = '';
+}
+increment(LineAdded, 'all')(ChildWithConstantIncrement.prototype, 'total');
+class ChildWithConstantDecrement {
+    id = '';
+    total = 0;
+    label = '';
+}
+decrement(LineAdded, 'all')(ChildWithConstantDecrement.prototype, 'total');
+class ChildWithPlainCount {
+    id = '';
+    total = 0;
+    label = '';
+}
+count(LineAdded)(ChildWithPlainCount.prototype, 'total');
+class ChildWithMappedLabelAndCount {
+    id = '';
+    total = 0;
+    label = '';
+}
+count(LineAdded)(ChildWithMappedLabelAndCount.prototype, 'total');
+setFrom(LineAdded)(ChildWithMappedLabelAndCount.prototype, 'label');
+class ChildWithEmptyKey {
+    [''] = '';
+}
+class ChildWithoutMatchingEmptyKey {
+    label = '';
+}
+class IdentifiedChildren {
+    byConvention!: ChildWithId[];
+    byUppercaseId!: ChildWithUppercaseId[];
+    byExplicitId!: ChildWithExplicitId[];
+    byExplicitIdWithoutChildType!: ChildWithId[];
+    byInferredEventKey!: ChildWithMatchingEventKey[];
+    byEventKey!: ChildWithId[];
+    byMatchingKey!: ChildWithId[];
+    withExplicitMapping!: ChildWithMappedId[];
+    withoutAutoMap!: ChildWithoutAutoMap[];
+    withNoAutoMappedId!: ChildWithNoAutoMappedId[];
+    withDifferentEventKeys!: ChildWithId[];
+    withConstantCount!: ChildWithConstantCount[];
+    withConstantIncrement!: ChildWithConstantIncrement[];
+    withConstantDecrement!: ChildWithConstantDecrement[];
+    withPlainCount!: ChildWithPlainCount[];
+    withMappedLabelAndCount!: ChildWithMappedLabelAndCount[];
+    withEmptyEventKey!: ChildWithEmptyKey[];
+    withoutMatchingEmptyKey!: ChildWithoutMatchingEmptyKey[];
+}
+childrenFrom(LineAdded, ChildWithId)(IdentifiedChildren.prototype, 'byConvention');
+childrenFrom(LineAdded, ChildWithUppercaseId)(IdentifiedChildren.prototype, 'byUppercaseId');
+childrenFrom(LineAdded, ChildWithExplicitId, 'employeeNumber')(IdentifiedChildren.prototype, 'byExplicitId');
+childrenFrom(LineAdded, undefined, 'id')(IdentifiedChildren.prototype, 'byExplicitIdWithoutChildType');
+childrenFrom(LineAdded, 'productId')(IdentifiedChildren.prototype, 'byInferredEventKey');
+childrenFrom(LineAdded, 'productId', 'id')(IdentifiedChildren.prototype, 'byEventKey');
+childrenFrom(LineAdded, 'id', 'id')(IdentifiedChildren.prototype, 'byMatchingKey');
+childrenFrom(LineAdded, ChildWithMappedId)(IdentifiedChildren.prototype, 'withExplicitMapping');
+childrenFrom(LineAdded, ChildWithoutAutoMap)(IdentifiedChildren.prototype, 'withoutAutoMap');
+childrenFrom(LineAdded, ChildWithNoAutoMappedId)(IdentifiedChildren.prototype, 'withNoAutoMappedId');
+childrenFrom(LineAdded, 'productId')(IdentifiedChildren.prototype, 'withDifferentEventKeys');
+childrenFrom(AlternateLineAdded, 'alternateId')(IdentifiedChildren.prototype, 'withDifferentEventKeys');
+childrenFrom(LineAdded, ChildWithConstantCount)(IdentifiedChildren.prototype, 'withConstantCount');
+childrenFrom(LineAdded, 'productId')(IdentifiedChildren.prototype, 'withConstantIncrement');
+field(Array, { enumerable: true, genericArguments: [ChildWithConstantIncrement] })(IdentifiedChildren.prototype, 'withConstantIncrement');
+childrenFrom(LineAdded, ChildWithConstantDecrement)(IdentifiedChildren.prototype, 'withConstantDecrement');
+childrenFrom(LineAdded, ChildWithPlainCount)(IdentifiedChildren.prototype, 'withPlainCount');
+childrenFrom(LineAdded, ChildWithMappedLabelAndCount)(IdentifiedChildren.prototype, 'withMappedLabelAndCount');
+childrenFrom(LineAdded, '')(IdentifiedChildren.prototype, 'withEmptyEventKey');
+childrenFrom(LineAdded, '')(IdentifiedChildren.prototype, 'withoutMatchingEmptyKey');
+field(Array, { enumerable: true, genericArguments: [ChildWithMatchingEventKey] })(IdentifiedChildren.prototype, 'byInferredEventKey');
+field(Array, { enumerable: true, genericArguments: [ChildWithId] })(IdentifiedChildren.prototype, 'byEventKey');
+field(Array, { enumerable: true, genericArguments: [ChildWithId] })(IdentifiedChildren.prototype, 'byMatchingKey');
+field(Array, { enumerable: true, genericArguments: [ChildWithId] })(IdentifiedChildren.prototype, 'withDifferentEventKeys');
+field(Array, { enumerable: true, genericArguments: [ChildWithEmptyKey] })(IdentifiedChildren.prototype, 'withEmptyEventKey');
+field(Array, { enumerable: true, genericArguments: [ChildWithoutMatchingEmptyKey] })(IdentifiedChildren.prototype, 'withoutMatchingEmptyKey');
+fromEvent(OrderCreated)(IdentifiedChildren);
+
 class OrderSummary {
     total!: number;
 }
@@ -140,10 +260,11 @@ noAutoMap(OrderWithoutAutoMap);
 fromEvent(OrderCreated)(OrderWithoutAutoMap);
 
 class Grandchild {
-    id!: string;
+    id = '';
 }
 
 class ChildWithGrandchildren {
+    id = '';
     grandchildren!: Grandchild[];
     detail!: Grandchild | undefined;
 }
@@ -248,6 +369,130 @@ describe('Projections with childrenFrom, nested and clearWith', () => {
             expect(updateEntry.Value.Properties.quantity).toBe('quantity');
         });
 
+        it('should map a convention or explicit child identifier from the creating event source id', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const children = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children;
+            expect(children.byConvention.IdentifiedBy).toBe('id');
+            expect(children.byConvention.From[0].Value.Properties).toEqual({ id: '$eventContext(EventSourceId)' });
+            expect(children.byUppercaseId.IdentifiedBy).toBe('Id');
+            expect(children.byUppercaseId.From[0].Value.Properties).toEqual({ Id: '$eventContext(EventSourceId)' });
+            expect(children.byExplicitId.IdentifiedBy).toBe('employeeNumber');
+            expect(children.byExplicitId.From[0].Value.Properties).toEqual({ employeeNumber: '$eventContext(EventSourceId)' });
+        });
+
+        it('should map an explicit identifier without child-type metadata from the creating event source id', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const child = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children.byExplicitIdWithoutChildType;
+            expect(child.IdentifiedBy).toBe('id');
+            expect(child.From[0].Value.Properties).toEqual({ id: '$eventContext(EventSourceId)' });
+        });
+
+        it('should map the child identifier from an explicit event key when it differs from the property name', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const children = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children;
+            expect(children.byEventKey.From[0].Value.Properties.id).toBe('productId');
+            expect(children.byInferredEventKey.IdentifiedBy).toBe('productId');
+            expect(children.byInferredEventKey.From[0].Value.Properties).toEqual({});
+            expect(children.byMatchingKey.From[0].Value.Properties).toEqual({});
+        });
+
+        it('should leave explicitly mapped identifiers and class-level disabled auto-mapping unchanged', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const children = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children;
+            expect(children.withExplicitMapping.From[0].Value.Properties).toEqual({ id: 'productId' });
+            expect(children.withoutAutoMap.AutoMap).toBe(AutoMap.Disabled);
+            expect(children.withoutAutoMap.From[0].Value.Properties).toEqual({});
+        });
+
+        it('should map an identifier with property-level noAutoMap from the creating event source id', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const child = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children.withNoAutoMappedId;
+            expect(child.AutoMap).toBe(AutoMap.Enabled);
+            expect(child.NoAutoMapProperties).toContain('id');
+            expect(child.From[0].Value.Properties.id).toBe('$eventContext(EventSourceId)');
+        });
+
+        it('should map each creating event using its own key on a shared children collection', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const child = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children.withDifferentEventKeys;
+            expect(child.IdentifiedBy).toBe('id');
+            expect(child.From).toHaveLength(2);
+            expect(child.From.find(candidate => candidate.Key.Id === 'LineAdded')?.Value).toEqual({
+                Key: 'productId', ParentKey: '$eventSourceId', Properties: { id: 'productId' }
+            });
+            expect(child.From.find(candidate => candidate.Key.Id === 'AlternateLineAdded')?.Value).toEqual({
+                Key: 'alternateId', ParentKey: '$eventSourceId', Properties: { id: 'alternateId' }
+            });
+        });
+
+        it('should preserve aggregate-only child count, increment and decrement with constant keys', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const children = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children;
+            for (const [name, operation] of [
+                ['withConstantCount', '$count'],
+                ['withConstantIncrement', '$increment'],
+                ['withConstantDecrement', '$decrement']
+            ]) {
+                const child = children[name];
+                expect(child.IdentifiedBy).toBe('id');
+                expect(child.From[0].Value).toEqual({
+                    Key: '$value(all)', ParentKey: '$eventSourceId', Properties: { total: operation }
+                });
+            }
+        });
+
+        it('should preserve aggregate-only child count without a constant key', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const child = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children.withPlainCount;
+            expect(child.IdentifiedBy).toBe('id');
+            expect(child.From[0].Value).toEqual({
+                Key: '$eventSourceId', ParentKey: '$eventSourceId', Properties: { total: '$count' }
+            });
+        });
+
+        it('should still map the identifier when a child count also explicitly maps a label', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const child = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children.withMappedLabelAndCount;
+            expect(child.From[0].Value.Properties).toEqual({ total: '$count', label: 'label', id: '$eventContext(EventSourceId)' });
+        });
+
+        it('should discover a child property matching an explicitly empty event key', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const child = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children.withEmptyEventKey;
+            expect(child.IdentifiedBy).toBe('');
+            expect(child.From[0].Value.Key).toBe('');
+            expect(child.From[0].Value.Properties).toEqual({});
+        });
+
+        it('should not infer an identifier from an empty event key without a matching child property', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const child = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children.withoutMatchingEmptyKey;
+            expect(child.IdentifiedBy).toBe('$eventSourceId');
+            expect(child.From[0].Value.Key).toBe('');
+        });
+
         it('should clear only the child member through a From mapping', async () => {
             const { projections, registerMock } = createProjections([Order]);
             await projections.register();
@@ -324,6 +569,7 @@ describe('Projections with childrenFrom, nested and clearWith', () => {
             const child = definition.Children.children;
             expect(child.AutoMap).toBe(AutoMap.Disabled);
             expect(child.Children.grandchildren.AutoMap).toBe(AutoMap.Disabled);
+            expect(child.Children.grandchildren.From[0].Value.Properties).toEqual({});
             expect(child.Nested.detail.AutoMap).toBe(AutoMap.Disabled);
         });
 
@@ -334,7 +580,10 @@ describe('Projections with childrenFrom, nested and clearWith', () => {
             const definition = registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition;
             const child = definition.Children.children;
             expect(child.AutoMap).toBe(AutoMap.Disabled);
+            expect(child.From[0].Value.Properties).toEqual({});
             expect(child.Children.grandchildren.AutoMap).toBe(AutoMap.Enabled);
+            expect(child.Children.grandchildren.IdentifiedBy).toBe('id');
+            expect(child.Children.grandchildren.From[0].Value.Properties.id).toBe('$eventContext(EventSourceId)');
             expect(child.Nested.detail.AutoMap).toBe(AutoMap.Enabled);
         });
 

package/projections/declarative/AddChildBuilder.ts

@@ -2,6 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
+import { eventContextPropertyExpression } from '../eventContextPropertyExpression.js';
 import { IAddChildBuilder } from './IAddChildBuilder.js';
 
 /**
@@ -14,8 +15,10 @@ export interface ChildAdditionEntry {
     targetProperty: string;
     /** The child model property used to identify instances, when set via the builder callback overload. */
     identifiedBy?: string;
-    /** The event property used as the key, when set via the builder callback overload. */
+    /** The event property or context expression used as the key, when set via the builder callback overload. */
     usingKey?: string;
+    /** The event context expression used as the parent key, when set via the builder callback overload. */
+    usingParentKey?: string;
     /** The event property whose value becomes the child directly, when set via the plain accessor overload. */
     fromEventProperty?: string;
 }
@@ -36,8 +39,9 @@ export class AddChildBuilder<TChildModel, TEvent> implements IAddChildBuilder<TC
     private _usedAsBuilder = false;
     private _identifiedByProperty: string | undefined;
     private _usingKeyProperty: string | undefined;
+    private _usingParentKeyProperty: string | undefined;
 
-    /** Whether any builder member (`identifiedBy`/`usingKey`) was invoked on the probe. */
+    /** Whether any builder member (`identifiedBy`, `usingKey`, `usingKeyFromContext`, or `usingParentKeyFromContext`) was invoked on the probe. */
     get usedAsBuilder(): boolean {
         return this._usedAsBuilder;
     }
@@ -52,6 +56,11 @@ export class AddChildBuilder<TChildModel, TEvent> implements IAddChildBuilder<TC
         return this._usingKeyProperty;
     }
 
+    /** The parent key expression captured via `usingParentKeyFromContext()`, if any. */
+    get usingParentKeyProperty(): string | undefined {
+        return this._usingParentKeyProperty;
+    }
+
     /** The event property path captured when the probe was used as a plain accessor. */
     get capturedEventProperty(): string {
         return this._pathHandler.property;
@@ -77,10 +86,26 @@ export class AddChildBuilder<TChildModel, TEvent> implements IAddChildBuilder<TC
         return this;
     }
 
+    /** @inheritdoc */
+    usingKeyFromContext(contextPropertyName: string): IAddChildBuilder<TChildModel, TEvent> {
+        this._usingKeyProperty = eventContextPropertyExpression(contextPropertyName);
+        this._usedAsBuilder = true;
+        return this;
+    }
+
+    /** @inheritdoc */
+    usingParentKeyFromContext(contextPropertyName: string): IAddChildBuilder<TChildModel, TEvent> {
+        this._usingParentKeyProperty = eventContextPropertyExpression(contextPropertyName);
+        this._usedAsBuilder = true;
+        return this;
+    }
+
     /**
      * Proxy `get` trap: known builder members dispatch to the real implementation above;
      * anything else (a plain event property accessed by the accessor overload) falls through
      * to path-capturing so the accessor overload keeps working against the same probe.
+     * The builder member names are therefore reserved: an event property with one of these names
+     * cannot be selected through the accessor overload.
      * @param _target - The proxy's (unused) empty target object.
      * @param prop - The accessed property name.
      * @returns The resolved member.
@@ -92,6 +117,12 @@ export class AddChildBuilder<TChildModel, TEvent> implements IAddChildBuilder<TC
         if (prop === 'usingKey') {
             return this.usingKey.bind(this);
         }
+        if (prop === 'usingKeyFromContext') {
+            return this.usingKeyFromContext.bind(this);
+        }
+        if (prop === 'usingParentKeyFromContext') {
+            return this.usingParentKeyFromContext.bind(this);
+        }
         return Reflect.get(this._pathProxy as object, prop);
     }
 }

package/projections/declarative/FromBuilder.ts

@@ -171,6 +171,14 @@ export class FromBuilder<TReadModel, TEvent> implements IFromBuilder<TReadModel,
     }
 
     /** @inheritdoc */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, builderCallback: (builder: IAddChildBuilder<TChildModel, TEvent> & TEvent) => void): this;
+    /** @inheritdoc */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, eventPropertyAccessor: PropertyAccessor<TEvent>): this;
+    /** @inheritdoc */
+    addChild<TChildModel>(
+        targetPropertyAccessor: PropertyAccessor<TReadModel>,
+        eventPropertyAccessorOrBuilderCallback: PropertyAccessor<TEvent> | ((builder: IAddChildBuilder<TChildModel, TEvent>) => void)
+    ): this;
     addChild<TChildModel>(
         targetPropertyAccessor: PropertyAccessor<TReadModel>,
         eventPropertyAccessorOrBuilderCallback: PropertyAccessor<TEvent> | ((builder: IAddChildBuilder<TChildModel, TEvent>) => void)
@@ -184,7 +192,7 @@ export class FromBuilder<TReadModel, TEvent> implements IFromBuilder<TReadModel,
         (eventPropertyAccessorOrBuilderCallback as (value: unknown) => void)(probeProxy);
 
         this.entry.children.push(probe.usedAsBuilder
-            ? { targetProperty: targetHandler.property, identifiedBy: probe.identifiedByProperty, usingKey: probe.usingKeyProperty }
+            ? { targetProperty: targetHandler.property, identifiedBy: probe.identifiedByProperty, usingKey: probe.usingKeyProperty, usingParentKey: probe.usingParentKeyProperty }
             : { targetProperty: targetHandler.property, fromEventProperty: probe.capturedEventProperty });
         return this;
     }

package/projections/declarative/IAddChildBuilder.ts

@@ -22,4 +22,18 @@ export interface IAddChildBuilder<TChildModel, TEvent> {
      * @returns This builder for fluent chaining.
      */
     usingKey(eventPropertyAccessor: PropertyAccessor<TEvent>): IAddChildBuilder<TChildModel, TEvent>;
+
+    /**
+     * Specifies an event context property used as the key when adding a child.
+     * @param contextPropertyName - Property path on EventContext, using TypeScript casing.
+     * @returns This builder for fluent chaining.
+     */
+    usingKeyFromContext(contextPropertyName: string): IAddChildBuilder<TChildModel, TEvent>;
+
+    /**
+     * Specifies an event context property used as the parent key when adding a child.
+     * @param contextPropertyName - Property path on EventContext, using TypeScript casing.
+     * @returns This builder for fluent chaining.
+     */
+    usingParentKeyFromContext(contextPropertyName: string): IAddChildBuilder<TChildModel, TEvent>;
 }

package/projections/declarative/IReadModelPropertiesBuilder.ts

@@ -107,7 +107,24 @@ export interface IReadModelPropertiesBuilder<TReadModel, TEvent, TBuilder> {
     count(readModelPropertyAccessor: PropertyAccessor<TReadModel>): TBuilder;
 
     /**
-     * Adds a child model from the event to a collection property on the read model.
+     * Adds a child model configured through a child builder to a collection on the read model.
+     * Event members remain available while TypeScript resolves the two function-shaped overloads.
+     * @param targetPropertyAccessor - Accessor for the collection property on the read model.
+     * @param builderCallback - Callback configuring the child identifier and keys.
+     * @returns This builder for fluent chaining.
+     */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, builderCallback: (builder: IAddChildBuilder<TChildModel, TEvent> & TEvent) => void): TBuilder;
+
+    /**
+     * Adds a child model directly from an event property to a collection on the read model.
+     * @param targetPropertyAccessor - Accessor for the collection property on the read model.
+     * @param eventPropertyAccessor - Accessor for the event property holding the child value.
+     * @returns This builder for fluent chaining.
+     */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, eventPropertyAccessor: PropertyAccessor<TEvent>): TBuilder;
+
+    /**
+     * Retains support for arbitrary read model accessors and explicitly selected child types.
      * @param targetPropertyAccessor - Accessor for the collection property on the read model.
      * @param eventPropertyAccessorOrBuilderCallback - Either a direct event property accessor or a builder callback.
      * @returns This builder for fluent chaining.

package/projections/declarative/JoinBuilder.ts

@@ -170,6 +170,14 @@ export class JoinBuilder<TReadModel, TEvent> implements IJoinBuilder<TReadModel,
     }
 
     /** @inheritdoc */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, builderCallback: (builder: IAddChildBuilder<TChildModel, TEvent> & TEvent) => void): this;
+    /** @inheritdoc */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, eventPropertyAccessor: PropertyAccessor<TEvent>): this;
+    /** @inheritdoc */
+    addChild<TChildModel>(
+        targetPropertyAccessor: PropertyAccessor<TReadModel>,
+        eventPropertyAccessorOrBuilderCallback: PropertyAccessor<TEvent> | ((builder: IAddChildBuilder<TChildModel, TEvent>) => void)
+    ): this;
     addChild<TChildModel>(
         targetPropertyAccessor: PropertyAccessor<TReadModel>,
         eventPropertyAccessorOrBuilderCallback: PropertyAccessor<TEvent> | ((builder: IAddChildBuilder<TChildModel, TEvent>) => void)
@@ -183,7 +191,7 @@ export class JoinBuilder<TReadModel, TEvent> implements IJoinBuilder<TReadModel,
         (eventPropertyAccessorOrBuilderCallback as (value: unknown) => void)(probeProxy);
 
         this.entry.children.push(probe.usedAsBuilder
-            ? { targetProperty: targetHandler.property, identifiedBy: probe.identifiedByProperty, usingKey: probe.usingKeyProperty }
+            ? { targetProperty: targetHandler.property, identifiedBy: probe.identifiedByProperty, usingKey: probe.usingKeyProperty, usingParentKey: probe.usingParentKeyProperty }
             : { targetProperty: targetHandler.property, fromEventProperty: probe.capturedEventProperty });
         return this;
     }

package/projections/declarative/ProjectionBuilderCore.ts

@@ -256,7 +256,7 @@ export abstract class ProjectionBuilderCore<TReadModel, TBuilder> {
                 Key: eventType,
                 Value: {
                     Key: child.usingKey ?? '$eventSourceId',
-                    ParentKey: '$eventSourceId',
+                    ParentKey: child.usingParentKey ?? '$eventSourceId',
                     Properties: {}
                 }
             });

package/projections/declarative/addChildCompatibility.standard.spec.ts

@@ -0,0 +1,80 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it } from 'vitest';
+import { eventType } from '../../events/eventTypeDecorator.js';
+import { FromBuilder } from './FromBuilder.js';
+import { IAddChildBuilder } from './IAddChildBuilder.js';
+import { IReadModelPropertiesBuilder } from './IReadModelPropertiesBuilder.js';
+import { JoinBuilder } from './JoinBuilder.js';
+import { ProjectionBuilderFor } from './ProjectionBuilderFor.js';
+
+class Line {
+    id = '';
+}
+
+class Base {
+    id = '';
+}
+
+class Derived extends Base {
+    derivedId = '';
+}
+
+class LineAdded {
+    line = new Line();
+}
+eventType()(LineAdded);
+
+class Order {
+    id = '';
+    lines: Line[] = [];
+    nullableLines: Line[] | null = null;
+    bases: Base[] = [];
+}
+
+// This checks the shared public interface independently of either concrete builder.
+function acceptOriginalCallSites(builder: IReadModelPropertiesBuilder<Order, LineAdded, unknown>): void {
+    builder.addChild<Line>(model => model.nullableLines, event => event.line);
+    builder.addChild(model => model.nullableLines, child => child.identifiedBy(item => item.id));
+    builder.addChild<Derived>(model => model.bases, (event: LineAdded) => event.line);
+    builder.addChild<Derived>(model => model.bases, (child: IAddChildBuilder<Derived, LineAdded>) => child
+        .identifiedBy(item => item.derivedId)
+        .usingKeyFromContext('sequenceNumber'));
+    builder.addChild<Line>(model => model.lines, (event: LineAdded) => event.line);
+}
+
+describe('addChild source compatibility', () => {
+    it('should accept nullable targets and explicitly narrower child types on the shared interface', () => {
+        const builder: IReadModelPropertiesBuilder<Order, LineAdded, unknown> = new FromBuilder<Order, LineAdded>();
+        acceptOriginalCallSites(builder);
+    });
+
+    it('should accept the original call shapes on the concrete from builder', () => {
+        const builder = new FromBuilder<Order, LineAdded>();
+        builder.addChild<Line>(model => model.nullableLines, event => event.line);
+        builder.addChild<Derived>(model => model.bases, (child: IAddChildBuilder<Derived, LineAdded>) => child.identifiedBy(item => item.derivedId));
+        builder.addChild<Derived>(model => model.bases, (event: LineAdded) => event.line);
+        builder.addChild<Line>(model => model.lines, (event: LineAdded) => event.line);
+        expect(builder.entry.children).toHaveLength(4);
+    });
+
+    it('should accept the original call shapes on the concrete join builder', () => {
+        const builder = new JoinBuilder<Order, LineAdded>();
+        builder.addChild<Line>(model => model.nullableLines, event => event.line);
+        builder.addChild<Derived>(model => model.bases, (child: IAddChildBuilder<Derived, LineAdded>) => child.identifiedBy(item => item.derivedId));
+        builder.addChild<Derived>(model => model.bases, (event: LineAdded) => event.line);
+        builder.addChild<Line>(model => model.lines, (event: LineAdded) => event.line);
+        expect(builder.entry.children).toHaveLength(4);
+    });
+
+    it('should contextually type the unannotated builder callback in the documentation example', () => {
+        const projection = new ProjectionBuilderFor<Order>();
+        projection.from(LineAdded, from => from
+            .addChild(model => model.lines, child => child
+                .identifiedBy(item => item.id)
+                .usingKeyFromContext('sequenceNumber')
+                .usingParentKeyFromContext('eventSourceId')));
+        expect(projection.build('order', 'Order').Children).toHaveProperty('lines');
+    });
+});

package/projections/eventContextExpressions.spec.ts

@@ -182,6 +182,24 @@ describe('event context expressions', () => {
             .From[0].Value.Key.should.equal('$eventContext(EventSourceId)');
     });
 
+    it('should use context properties as addChild keys in a from clause', () => {
+        const child = declarative(builder => builder.from(Recorded, from => from.addChild<Child>(model => model.children, added => added
+            .identifiedBy(model => model.happened)
+            .usingKeyFromContext('sequenceNumber')
+            .usingParentKeyFromContext('eventSourceId'))));
+        child.Children.children.From[0].Value.Key.should.equal('$eventContext(SequenceNumber)');
+        child.Children.children.From[0].Value.ParentKey.should.equal('$eventContext(EventSourceId)');
+    });
+
+    it('should use context properties as addChild keys in a join clause', () => {
+        const child = declarative(builder => builder.join(Recorded, join => join.on(model => model.occurred)
+            .addChild<Child>(model => model.children, added => added
+                .usingKeyFromContext('eventSourceId')
+                .usingParentKeyFromContext('sequenceNumber'))));
+        child.Children.children.From[0].Value.Key.should.equal('$eventContext(EventSourceId)');
+        child.Children.children.From[0].Value.ParentKey.should.equal('$eventContext(SequenceNumber)');
+    });
+
     it('should use a context property as a from parent key', () => {
         declarative(builder => builder.from(Recorded, from => from.usingParentKeyFromContext('eventSourceId')))
             .From[0].Value.ParentKey.should.equal('$eventContext(EventSourceId)');
@@ -255,6 +273,8 @@ describe('event context expressions', () => {
         const mappings = [
             (builder: ProjectionBuilderFor<Model>) => builder.from(Recorded, from => from.usingKeyFromContext('missingKey')),
             (builder: ProjectionBuilderFor<Model>) => builder.from(Recorded, from => from.usingParentKeyFromContext('missingParent')),
+            (builder: ProjectionBuilderFor<Model>) => builder.from(Recorded, from => from.addChild<Child>(model => model.children, child => child.usingKeyFromContext('missingChildKey'))),
+            (builder: ProjectionBuilderFor<Model>) => builder.join(Recorded, join => join.on(model => model.occurred).addChild<Child>(model => model.children, child => child.usingParentKeyFromContext('missingChildParent'))),
             (builder: ProjectionBuilderFor<Model>) => builder.join(Recorded, join => join.on(model => model.occurred).usingKeyFromContext('missingJoinKey')),
             (builder: ProjectionBuilderFor<Model>) => builder.removedWith(Removed, removed => removed.usingKeyFromContext('missingRemovalKey'))
         ];