@cratis/chronicle 3.0.0 → 3.1.1

package/projections/Projections.ts

@@ -12,21 +12,25 @@ import { ChronicleConnection } from '../connection';
 import { toContractsGuid } from '../connection/Guid';
 import { WellKnownSinks } from '../sinks';
 import { EventSequenceId } from '../eventSequences/EventSequenceId';
-import { getEventTypeFor } from '../events/eventTypeDecorator';
 import { getReadModelMetadata } from '../readModels';
 import { TypeIntrospector } from '../types';
 import { IProjections } from './IProjections';
 import { getProjectionMetadata } from './declarative/projection';
 import { ProjectionBuilderFor } from './declarative/ProjectionBuilderFor';
 import type { IProjectionFor } from './declarative/IProjectionFor';
-import { getAddFromMetadata } from './modelBound/addFrom';
+import {
+    applyPropertyMappings,
+    buildChildrenEntry,
+    buildNestedEntry,
+    ChildrenDefinitionLike,
+    ContractEventType,
+    FromRecord,
+    getEventTypeMapKey,
+    toContractEventType
+} from './modelBound/childrenAndNestedBuilder';
 import { getChildrenFromMetadata } from './modelBound/childrenFrom';
-import { getClearWithClassMetadata, getClearWithPropertyMetadata } from './modelBound/clearWith';
-import { getCountMetadata } from './modelBound/count';
-import { getDecrementMetadata } from './modelBound/decrement';
 import { getFromEveryMetadata } from './modelBound/fromEvery';
 import { getFromEventMetadata, hasFromEventMetadata } from './modelBound/fromEvent';
-import { getIncrementMetadata } from './modelBound/increment';
 import { getJoinMetadata } from './modelBound/join';
 import { ProjectionId } from './ProjectionId';
 import { isNested } from './modelBound/nested';
@@ -34,12 +38,6 @@ import { isNotRewindable } from './modelBound/notRewindable';
 import { isPassive } from './modelBound/passive';
 import { getRemovedWithClassMetadata, getRemovedWithPropertyMetadata } from './modelBound/removedWith';
 import { getRemovedWithJoinClassMetadata, getRemovedWithJoinPropertyMetadata } from './modelBound/removedWithJoin';
-import { getSetFromMetadata } from './modelBound/setFrom';
-import { getSetFromContextMetadata } from './modelBound/setFromContext';
-import { getSetValueMetadata } from './modelBound/setValue';
-import { getSubtractFromMetadata } from './modelBound/subtractFrom';
-
-type ContractEventType = { Id: string; Generation: number; Tombstone: boolean };
 
 interface ResolvedModelBoundMetadata {
     id: ProjectionId;
@@ -277,15 +275,17 @@ export class Projections implements IProjections {
         const properties = TypeIntrospector.getTrackedProperties(type);
         const prototype = type.prototype;
 
-        const fromByEventType = new Map<string, { Key: ContractEventType; Value: { Properties: Record<string, string>; Key: string; ParentKey: string } }>();
+        const fromByEventType = new Map<string, FromRecord>();
         const joinByEventType = new Map<string, { Key: ContractEventType; Value: { On: string; Properties: Record<string, string>; Key: string } }>();
         const removedWithByEventType = new Map<string, { Key: ContractEventType; Value: { Key: string; ParentKey: string } }>();
         const removedWithJoinByEventType = new Map<string, { Key: ContractEventType; Value: { Key: string } }>();
+        const childrenByProperty: Record<string, ChildrenDefinitionLike> = {};
+        const nestedByProperty: Record<string, ChildrenDefinitionLike> = {};
 
         const fromEvents = getFromEventMetadata(type);
         for (const fromEvent of fromEvents) {
-            const eventType = this.toContractEventType(fromEvent.eventType);
-            const eventKey = this.getEventTypeMapKey(eventType);
+            const eventType = toContractEventType(fromEvent.eventType);
+            const eventKey = getEventTypeMapKey(eventType);
             fromByEventType.set(eventKey, {
                 Key: eventType,
                 Value: {
@@ -296,15 +296,10 @@ export class Projections implements IProjections {
             });
         }
 
-        const clearWithClass = getClearWithClassMetadata(type);
-        if (clearWithClass.length > 0) {
-            throw new Error(`Model-bound projection '${type.name}' uses @clearWith on class level, which is not implemented yet.`);
-        }
-
         const removedWithClass = getRemovedWithClassMetadata(type);
         for (const removed of removedWithClass) {
-            const eventType = this.toContractEventType(removed.eventType);
-            removedWithByEventType.set(this.getEventTypeMapKey(eventType), {
+            const eventType = toContractEventType(removed.eventType);
+            removedWithByEventType.set(getEventTypeMapKey(eventType), {
                 Key: eventType,
                 Value: { Key: removed.key ?? '$eventSourceId', ParentKey: removed.parentKey ?? '' }
             });
@@ -312,30 +307,15 @@ export class Projections implements IProjections {
 
         const removedWithJoinClass = getRemovedWithJoinClassMetadata(type);
         for (const removed of removedWithJoinClass) {
-            const eventType = this.toContractEventType(removed.eventType);
-            removedWithJoinByEventType.set(this.getEventTypeMapKey(eventType), {
+            const eventType = toContractEventType(removed.eventType);
+            removedWithJoinByEventType.set(getEventTypeMapKey(eventType), {
                 Key: eventType,
                 Value: { Key: removed.key ?? '$eventSourceId' }
             });
         }
 
         for (const property of properties) {
-            this.throwIfUnsupportedModelBoundDecorators(type.name, prototype, property);
-
-            for (const mapping of getSetFromMetadata(prototype, property)) {
-                const entry = this.ensureFromEntry(fromByEventType, mapping.eventType);
-                entry.Value.Properties[property] = mapping.eventPropertyName ?? property;
-            }
-
-            for (const mapping of getSetFromContextMetadata(prototype, property)) {
-                const entry = this.ensureFromEntry(fromByEventType, mapping.eventType);
-                entry.Value.Properties[property] = mapping.contextPropertyName ?? property;
-            }
-
-            for (const mapping of getSetValueMetadata(prototype, property)) {
-                const entry = this.ensureFromEntry(fromByEventType, mapping.eventType);
-                entry.Value.Properties[property] = JSON.stringify(mapping.value);
-            }
+            applyPropertyMappings(prototype, property, fromByEventType);
 
             for (const mapping of getJoinMetadata(prototype, property)) {
                 const entry = this.ensureJoinEntry(joinByEventType, mapping.eventType);
@@ -343,26 +323,30 @@ export class Projections implements IProjections {
                 entry.Value.Properties[property] = mapping.eventPropertyName ?? property;
             }
 
-            const fromEvery = getFromEveryMetadata(prototype, property);
-            if (fromEvery) {
-                // Applied later to projection.All
-            }
-
             for (const removed of getRemovedWithPropertyMetadata(prototype, property)) {
-                const eventType = this.toContractEventType(removed.eventType);
-                removedWithByEventType.set(this.getEventTypeMapKey(eventType), {
+                const eventType = toContractEventType(removed.eventType);
+                removedWithByEventType.set(getEventTypeMapKey(eventType), {
                     Key: eventType,
                     Value: { Key: removed.key ?? '$eventSourceId', ParentKey: removed.parentKey ?? '' }
                 });
             }
 
             for (const removed of getRemovedWithJoinPropertyMetadata(prototype, property)) {
-                const eventType = this.toContractEventType(removed.eventType);
-                removedWithJoinByEventType.set(this.getEventTypeMapKey(eventType), {
+                const eventType = toContractEventType(removed.eventType);
+                removedWithJoinByEventType.set(getEventTypeMapKey(eventType), {
                     Key: eventType,
                     Value: { Key: removed.key ?? '$eventSourceId' }
                 });
             }
+
+            const childrenFromList = getChildrenFromMetadata(prototype, property);
+            if (childrenFromList.length > 0) {
+                childrenByProperty[property] = buildChildrenEntry(type, property, childrenFromList);
+            }
+
+            if (isNested(prototype, property)) {
+                nestedByProperty[property] = buildNestedEntry(type, property);
+            }
         }
 
         const allProperties: Record<string, string> = {};
@@ -384,7 +368,7 @@ export class Projections implements IProjections {
             InitialModelState: '{}',
             From: Array.from(fromByEventType.values()),
             Join: Array.from(joinByEventType.values()),
-            Children: {},
+            Children: childrenByProperty,
             FromEvery: [],
             All: {
                 Properties: allProperties,
@@ -396,7 +380,7 @@ export class Projections implements IProjections {
             LastUpdated: { Value: '' },
             Tags: [],
             AutoMap: AutoMap.Enabled,
-            Nested: {}
+            Nested: nestedByProperty
         };
         definition.LastUpdated = { Value: this.computeStableLastUpdated(definition) };
         return definition;
@@ -416,62 +400,12 @@ export class Projections implements IProjections {
         return undefined;
     }
 
-    private throwIfUnsupportedModelBoundDecorators(typeName: string, prototype: object, property: string): void {
-        if (getAddFromMetadata(prototype, property).length > 0) {
-            throw new Error(`Model-bound projection '${typeName}' uses @addFrom on '${property}', which is not implemented yet.`);
-        }
-        if (getSubtractFromMetadata(prototype, property).length > 0) {
-            throw new Error(`Model-bound projection '${typeName}' uses @subtractFrom on '${property}', which is not implemented yet.`);
-        }
-        if (getIncrementMetadata(prototype, property).length > 0) {
-            throw new Error(`Model-bound projection '${typeName}' uses @increment on '${property}', which is not implemented yet.`);
-        }
-        if (getDecrementMetadata(prototype, property).length > 0) {
-            throw new Error(`Model-bound projection '${typeName}' uses @decrement on '${property}', which is not implemented yet.`);
-        }
-        if (getCountMetadata(prototype, property).length > 0) {
-            throw new Error(`Model-bound projection '${typeName}' uses @count on '${property}', which is not implemented yet.`);
-        }
-        if (getChildrenFromMetadata(prototype, property).length > 0) {
-            throw new Error(`Model-bound projection '${typeName}' uses @childrenFrom on '${property}', which is not implemented yet.`);
-        }
-        if (isNested(prototype, property)) {
-            throw new Error(`Model-bound projection '${typeName}' uses @nested on '${property}', which is not implemented yet.`);
-        }
-        if (getClearWithPropertyMetadata(prototype, property).length > 0) {
-            throw new Error(`Model-bound projection '${typeName}' uses @clearWith on '${property}', which is not implemented yet.`);
-        }
-    }
-
-    private ensureFromEntry(
-        fromByEventType: Map<string, { Key: ContractEventType; Value: { Properties: Record<string, string>; Key: string; ParentKey: string } }>,
-        eventTypeConstructor: Function
-    ): { Key: ContractEventType; Value: { Properties: Record<string, string>; Key: string; ParentKey: string } } {
-        const eventType = this.toContractEventType(eventTypeConstructor);
-        const key = this.getEventTypeMapKey(eventType);
-        const existing = fromByEventType.get(key);
-        if (existing) {
-            return existing;
-        }
-
-        const created = {
-            Key: eventType,
-            Value: {
-                Properties: {},
-                Key: '$eventSourceId',
-                ParentKey: ''
-            }
-        };
-        fromByEventType.set(key, created);
-        return created;
-    }
-
     private ensureJoinEntry(
         joinByEventType: Map<string, { Key: ContractEventType; Value: { On: string; Properties: Record<string, string>; Key: string } }>,
         eventTypeConstructor: Function
     ): { Key: ContractEventType; Value: { On: string; Properties: Record<string, string>; Key: string } } {
-        const eventType = this.toContractEventType(eventTypeConstructor);
-        const key = this.getEventTypeMapKey(eventType);
+        const eventType = toContractEventType(eventTypeConstructor);
+        const key = getEventTypeMapKey(eventType);
         const existing = joinByEventType.get(key);
         if (existing) {
             return existing;
@@ -489,22 +423,6 @@ export class Projections implements IProjections {
         return created;
     }
 
-    private toContractEventType(eventTypeConstructor: Function): ContractEventType {
-        const eventType = getEventTypeFor(eventTypeConstructor);
-        if (eventType.id.value === '') {
-            throw new Error(`Event type '${eventTypeConstructor.name}' is not decorated with @eventType().`);
-        }
-        return {
-            Id: eventType.id.value,
-            Generation: eventType.generation.value,
-            Tombstone: false
-        };
-    }
-
-    private getEventTypeMapKey(eventType: ContractEventType): string {
-        return `${eventType.Id}:${eventType.Generation}:${eventType.Tombstone ? '1' : '0'}`;
-    }
-
     /**
      * Computes a stable, deterministic ISO timestamp from the projection definition content,
      * excluding the LastUpdated field itself. This ensures the server does not interpret

package/projections/declarative/AddBuilder.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
+import { IAddBuilder } from './IAddBuilder';
+
+/**
+ * Concrete implementation of {@link IAddBuilder} that records an add expression
+ * into the owning from/join builder.
+ * @template TEvent - The event type.
+ * @template TParentBuilder - The parent builder type.
+ */
+export class AddBuilder<TEvent, TParentBuilder> implements IAddBuilder<TEvent, TParentBuilder> {
+    constructor(
+        private readonly _readModelProperty: string,
+        private readonly _setProperty: (readModelProp: string, expression: string) => void,
+        private readonly _parent: TParentBuilder
+    ) {}
+
+    /** @inheritdoc */
+    with(eventPropertyAccessor: PropertyAccessor<TEvent>): TParentBuilder {
+        const handler = new PropertyPathResolverProxyHandler();
+        const proxy = new Proxy({}, handler);
+        eventPropertyAccessor(proxy as TEvent);
+        this._setProperty(this._readModelProperty, `$add(${handler.property})`);
+        return this._parent;
+    }
+}

package/projections/declarative/AddChildBuilder.ts

@@ -0,0 +1,97 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
+import { IAddChildBuilder } from './IAddChildBuilder';
+
+/**
+ * A single `.addChild()` accumulation captured on a from/join builder, later merged into the
+ * owning projection builder's `Children` definitions once the enclosing `.from()`/`.join()`
+ * call resolves the event type it belongs to.
+ */
+export interface ChildAdditionEntry {
+    /** The read model property the child is added to. */
+    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. */
+    usingKey?: string;
+    /** The event property whose value becomes the child directly, when set via the plain accessor overload. */
+    fromEventProperty?: string;
+}
+
+/**
+ * Implements {@link IAddChildBuilder} and doubles as a {@link ProxyHandler} so a single probe
+ * object can resolve `.addChild()`'s two call shapes at runtime: a plain event-property
+ * accessor (`e => e.someProperty`), or a builder callback (`b => b.usingKey(...)`). Known
+ * builder members are dispatched to the real implementation below; any other property access
+ * (the plain-accessor shape) falls through to the same path-capturing proxy used everywhere
+ * else in this file for `PropertyAccessor<T>` resolution.
+ * @template TChildModel - The child model type.
+ * @template TEvent - The event type.
+ */
+export class AddChildBuilder<TChildModel, TEvent> implements IAddChildBuilder<TChildModel, TEvent>, ProxyHandler<object> {
+    private readonly _pathHandler = new PropertyPathResolverProxyHandler();
+    private readonly _pathProxy = new Proxy({}, this._pathHandler);
+    private _usedAsBuilder = false;
+    private _identifiedByProperty: string | undefined;
+    private _usingKeyProperty: string | undefined;
+
+    /** Whether any builder member (`identifiedBy`/`usingKey`) was invoked on the probe. */
+    get usedAsBuilder(): boolean {
+        return this._usedAsBuilder;
+    }
+
+    /** The child model property captured via `identifiedBy()`, if any. */
+    get identifiedByProperty(): string | undefined {
+        return this._identifiedByProperty;
+    }
+
+    /** The event property captured via `usingKey()`, if any. */
+    get usingKeyProperty(): string | undefined {
+        return this._usingKeyProperty;
+    }
+
+    /** The event property path captured when the probe was used as a plain accessor. */
+    get capturedEventProperty(): string {
+        return this._pathHandler.property;
+    }
+
+    /** @inheritdoc */
+    identifiedBy(childPropertyAccessor: PropertyAccessor<TChildModel>): IAddChildBuilder<TChildModel, TEvent> {
+        this._usedAsBuilder = true;
+        const handler = new PropertyPathResolverProxyHandler();
+        const proxy = new Proxy({}, handler);
+        childPropertyAccessor(proxy as TChildModel);
+        this._identifiedByProperty = handler.property;
+        return this;
+    }
+
+    /** @inheritdoc */
+    usingKey(eventPropertyAccessor: PropertyAccessor<TEvent>): IAddChildBuilder<TChildModel, TEvent> {
+        this._usedAsBuilder = true;
+        const handler = new PropertyPathResolverProxyHandler();
+        const proxy = new Proxy({}, handler);
+        eventPropertyAccessor(proxy as TEvent);
+        this._usingKeyProperty = handler.property;
+        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.
+     * @param _target - The proxy's (unused) empty target object.
+     * @param prop - The accessed property name.
+     * @returns The resolved member.
+     */
+    get(_target: object, prop: string | symbol): unknown {
+        if (prop === 'identifiedBy') {
+            return this.identifiedBy.bind(this);
+        }
+        if (prop === 'usingKey') {
+            return this.usingKey.bind(this);
+        }
+        return Reflect.get(this._pathProxy as object, prop);
+    }
+}

package/projections/declarative/ChildrenBuilder.spec.ts

@@ -0,0 +1,157 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { describe, expect, it } from 'vitest';
+import { eventType } from '../../events/eventTypeDecorator';
+import { ProjectionBuilderFor } from './ProjectionBuilderFor';
+
+// Decorators are applied as plain function calls (rather than `@decorator` syntax) so these
+// fixtures don't depend on the test runner's decorator-syntax support.
+
+class LineAdded {
+    productId!: string;
+    quantity!: number;
+}
+eventType()(LineAdded);
+
+class TagAdded {
+    name!: string;
+}
+eventType()(TagAdded);
+
+class SummaryUpdated {
+    total!: number;
+}
+eventType()(SummaryUpdated);
+
+class SummaryCleared {}
+eventType()(SummaryCleared);
+
+class WholeLineReceived {
+    productId!: string;
+}
+eventType()(WholeLineReceived);
+
+class OrderLine {
+    productId!: string;
+    quantity!: number;
+}
+
+class OrderSummary {
+    total!: number;
+}
+
+class Order {
+    id!: string;
+    lines!: OrderLine[];
+    tags!: string[];
+    summary!: OrderSummary | undefined;
+}
+
+interface FromRecord {
+    Key: { Id: string };
+    Value: { Properties: Record<string, string>; Key: string; ParentKey: string };
+}
+
+interface ChildrenDefinition {
+    IdentifiedBy: string;
+    From: FromRecord[];
+    RemovedWith: Array<{ Key: { Id: string } }>;
+    FromEventProperty?: { Event: { Id: string } | undefined; PropertyExpression: string };
+}
+
+interface BuiltDefinition {
+    From: FromRecord[];
+    Children: Record<string, ChildrenDefinition>;
+    Nested: Record<string, ChildrenDefinition>;
+}
+
+describe('ChildrenBuilder and NestedBuilder', () => {
+    describe('when using children on the top-level builder', () => {
+        it('should produce a children definition keyed by the target property', () => {
+            const builder = new ProjectionBuilderFor<Order>();
+            builder.children<OrderLine>(order => order.lines, children => children
+                .identifiedBy(line => line.productId)
+                .from(LineAdded, from => from.set(line => line.quantity).to(event => event.quantity)));
+
+            const definition = builder.build('order', 'Order') as unknown as BuiltDefinition;
+            const linesDefinition = definition.Children.lines;
+
+            expect(linesDefinition.IdentifiedBy).toBe('productId');
+            const fromEntry = linesDefinition.From.find(candidate => candidate.Key.Id === 'LineAdded')!;
+            expect(fromEntry.Value.Properties.quantity).toBe('quantity');
+        });
+    });
+
+    describe('when using nested with clearWith on the top-level builder', () => {
+        it('should produce a nested definition with a RemovedWith entry', () => {
+            const builder = new ProjectionBuilderFor<Order>();
+            builder.nested<OrderSummary>(order => order.summary, nested => nested
+                .from(SummaryUpdated, from => from.set(summary => summary.total).to(event => event.total))
+                .clearWith(SummaryCleared));
+
+            const definition = builder.build('order', 'Order') as unknown as BuiltDefinition;
+            const summaryDefinition = definition.Nested.summary;
+
+            const fromEntry = summaryDefinition.From.find(candidate => candidate.Key.Id === 'SummaryUpdated')!;
+            expect(fromEntry.Value.Properties.total).toBe('total');
+            expect(summaryDefinition.RemovedWith[0].Key.Id).toBe('SummaryCleared');
+        });
+    });
+
+    describe('when using addChild with a builder callback', () => {
+        it('should produce a children definition keyed by identifiedBy and usingKey', () => {
+            const builder = new ProjectionBuilderFor<Order>();
+            builder.from(LineAdded, from => from.addChild<OrderLine>(order => order.lines, child => child
+                .identifiedBy(line => line.productId)
+                .usingKey(event => event.productId)));
+
+            const definition = builder.build('order', 'Order') as unknown as BuiltDefinition;
+            const linesDefinition = definition.Children.lines;
+
+            expect(linesDefinition.IdentifiedBy).toBe('productId');
+            const fromEntry = linesDefinition.From.find(candidate => candidate.Key.Id === 'LineAdded')!;
+            expect(fromEntry.Value.Key).toBe('productId');
+        });
+    });
+
+    describe('when using addChild with a plain event property accessor', () => {
+        it('should produce a children definition with a FromEventProperty expression', () => {
+            const builder = new ProjectionBuilderFor<Order>();
+            builder.from(TagAdded, from => from.addChild<string>(order => order.tags, event => event.name));
+
+            const definition = builder.build('order', 'Order') as unknown as BuiltDefinition;
+            const tagsDefinition = definition.Children.tags;
+
+            expect(tagsDefinition.FromEventProperty?.PropertyExpression).toBe('name');
+            expect(tagsDefinition.FromEventProperty?.Event?.Id).toBe('TagAdded');
+        });
+    });
+
+    describe('when using addChild on a join builder', () => {
+        it('should produce a children definition from the join clause', () => {
+            const builder = new ProjectionBuilderFor<Order>();
+            builder.join(WholeLineReceived, join => join.addChild<OrderLine>(order => order.lines, child => child
+                .identifiedBy(line => line.productId)));
+
+            const definition = builder.build('order', 'Order') as unknown as BuiltDefinition;
+            const linesDefinition = definition.Children.lines;
+
+            expect(linesDefinition.IdentifiedBy).toBe('productId');
+            expect(linesDefinition.From.some(candidate => candidate.Key.Id === 'WholeLineReceived')).toBe(true);
+        });
+    });
+
+    describe('when using setThisValue on a from builder', () => {
+        it('should map the whole event property onto the $this well-known expression', () => {
+            const builder = new ProjectionBuilderFor<Order>();
+            builder.from(TagAdded, from => from.setThisValue().to(event => event.name));
+
+            const definition = builder.build('order', 'Order') as unknown as BuiltDefinition;
+            const fromEntry = definition.From.find(candidate => candidate.Key.Id === 'TagAdded')!;
+
+            expect(fromEntry.Value.Properties.$this).toBe('name');
+        });
+    });
+});

package/projections/declarative/ChildrenBuilder.ts

@@ -0,0 +1,90 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
+import { ChildrenDefinitionLike, ProjectionBuilderCore } from './ProjectionBuilderCore';
+import { IChildrenBuilder } from './IChildrenBuilder';
+import { INestedBuilder } from './INestedBuilder';
+import { NestedBuilder } from './NestedBuilder';
+
+/**
+ * Concrete implementation of {@link IChildrenBuilder}, building the `ChildrenDefinition` for a
+ * children collection sub-projection reached through `.children()`.
+ * @template TParentReadModel - The parent read model type.
+ * @template TChildReadModel - The child read model type.
+ */
+export class ChildrenBuilder<TParentReadModel, TChildReadModel>
+    extends ProjectionBuilderCore<TChildReadModel, IChildrenBuilder<TParentReadModel, TChildReadModel>>
+    implements IChildrenBuilder<TParentReadModel, TChildReadModel> {
+    private _identifiedBy: string | undefined;
+    private _fromEventPropertyPath: string | undefined;
+
+    /** @inheritdoc */
+    identifiedBy(propertyAccessor: PropertyAccessor<TChildReadModel>): IChildrenBuilder<TParentReadModel, TChildReadModel> {
+        const handler = new PropertyPathResolverProxyHandler();
+        const proxy = new Proxy({}, handler);
+        propertyAccessor(proxy as TChildReadModel);
+        this._identifiedBy = handler.property;
+        return this;
+    }
+
+    /** @inheritdoc */
+    fromEventProperty<TEvent>(propertyAccessor: PropertyAccessor<TEvent>): IChildrenBuilder<TParentReadModel, TChildReadModel> {
+        const handler = new PropertyPathResolverProxyHandler();
+        const proxy = new Proxy({}, handler);
+        propertyAccessor(proxy as TEvent);
+        this._fromEventPropertyPath = handler.property;
+        return this;
+    }
+
+    /** @inheritdoc */
+    children<TGrandchildModel>(
+        targetPropertyAccessor: PropertyAccessor<TChildReadModel>,
+        builderCallback: (builder: IChildrenBuilder<TChildReadModel, TGrandchildModel>) => void
+    ): IChildrenBuilder<TParentReadModel, TChildReadModel> {
+        const handler = new PropertyPathResolverProxyHandler();
+        const proxy = new Proxy({}, handler);
+        targetPropertyAccessor(proxy as TChildReadModel);
+
+        const builder = new ChildrenBuilder<TChildReadModel, TGrandchildModel>();
+        builderCallback(builder);
+        this._children[handler.property] = builder.buildDefinition();
+        return this;
+    }
+
+    /** @inheritdoc */
+    nested<TNestedModel>(
+        targetPropertyAccessor: PropertyAccessor<TChildReadModel>,
+        builderCallback: (builder: INestedBuilder<TChildReadModel, TNestedModel>) => void
+    ): IChildrenBuilder<TParentReadModel, TChildReadModel> {
+        const handler = new PropertyPathResolverProxyHandler();
+        const proxy = new Proxy({}, handler);
+        targetPropertyAccessor(proxy as TChildReadModel);
+
+        const builder = new NestedBuilder<TChildReadModel, TNestedModel>();
+        builderCallback(builder);
+        this._nested[handler.property] = builder.buildDefinition();
+        return this;
+    }
+
+    /**
+     * Builds the {@link ChildrenDefinitionLike} representing this children collection.
+     * @returns The accumulated children definition.
+     */
+    buildDefinition(): ChildrenDefinitionLike {
+        return {
+            IdentifiedBy: this._identifiedBy ?? '$eventSourceId',
+            From: this._from,
+            Join: this._join,
+            Children: this._children,
+            All: this._all,
+            FromEventProperty: this._fromEventPropertyPath === undefined
+                ? undefined
+                : { Event: undefined, PropertyExpression: this._fromEventPropertyPath },
+            RemovedWith: this._removedWith,
+            RemovedWithJoin: this._removedWithJoin,
+            AutoMap: this._autoMap,
+            Nested: this._nested
+        };
+    }
+}