@cratis/chronicle 3.0.0 → 3.1.1

package/projections/declarative/CompositeKeyBuilder.spec.ts

@@ -0,0 +1,117 @@
+// 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 OrderLineAdded {
+    orderId!: string;
+    lineNumber!: number;
+    quantity!: number;
+}
+eventType()(OrderLineAdded);
+
+class OrderLineJoined {
+    orderId!: string;
+    lineNumber!: number;
+    description!: string;
+}
+eventType()(OrderLineJoined);
+
+class CompositeKey {
+    orderId!: string;
+    lineNumber!: number;
+}
+
+class OrderLine {
+    id!: string;
+    quantity!: number;
+    description!: string;
+}
+
+interface FromRecord {
+    Key: { Id: string };
+    Value: { Key: string };
+}
+
+interface JoinRecord {
+    Key: { Id: string };
+    Value: { Key: string };
+}
+
+interface JoinRecordWithParentKey {
+    Key: { Id: string };
+    Value: { Key: string; ParentKey?: string };
+}
+
+describe('CompositeKeyBuilder', () => {
+    describe('when using a composite key on a from builder', () => {
+        it('should produce a $composite expression', () => {
+            const builder = new ProjectionBuilderFor<OrderLine>();
+            builder.from(OrderLineAdded, from => from.usingCompositeKey<CompositeKey>(key => key
+                .set(target => target.orderId, event => event.orderId)
+                .set(target => target.lineNumber, event => event.lineNumber)));
+
+            const definition = builder.build('orderLine', 'OrderLine') as unknown as { From: FromRecord[] };
+            const entry = definition.From.find(candidate => candidate.Key.Id === 'OrderLineAdded')!;
+
+            expect(entry.Value.Key).toBe('$composite(orderId=orderId,lineNumber=lineNumber)');
+        });
+    });
+
+    describe('when using a parent composite key on a from builder', () => {
+        it('should produce a $composite expression for the parent key', () => {
+            const builder = new ProjectionBuilderFor<OrderLine>();
+            builder.from(OrderLineAdded, from => from.usingParentCompositeKey<CompositeKey>(key => key
+                .set(target => target.orderId, event => event.orderId)
+                .set(target => target.lineNumber, event => event.lineNumber)));
+
+            const definition = builder.build('orderLine', 'OrderLine') as unknown as { From: Array<{ Key: { Id: string }; Value: { ParentKey: string } }> };
+            const entry = definition.From.find(candidate => candidate.Key.Id === 'OrderLineAdded')!;
+
+            expect(entry.Value.ParentKey).toBe('$composite(orderId=orderId,lineNumber=lineNumber)');
+        });
+    });
+
+    describe('when using a composite key on a join builder', () => {
+        it('should produce a $composite expression', () => {
+            const builder = new ProjectionBuilderFor<OrderLine>();
+            builder.join(OrderLineJoined, join => join
+                .on(model => model.id)
+                .usingCompositeKey<CompositeKey>(key => key
+                    .set(target => target.orderId, event => event.orderId)
+                    .set(target => target.lineNumber, event => event.lineNumber)));
+
+            const definition = builder.build('orderLine', 'OrderLine') as unknown as { Join: JoinRecord[] };
+            const entry = definition.Join.find(candidate => candidate.Key.Id === 'OrderLineJoined')!;
+
+            expect(entry.Value.Key).toBe('$composite(orderId=orderId,lineNumber=lineNumber)');
+        });
+    });
+
+    describe('when using parent-key methods on a join builder', () => {
+        it('should accept the calls without throwing, matching the C# client having no wire effect for Join', () => {
+            const builder = new ProjectionBuilderFor<OrderLine>();
+
+            expect(() => builder.join(OrderLineJoined, join => join
+                .on(model => model.id)
+                .usingParentKey(event => event.orderId)
+                .usingParentKeyFromContext('someContextProperty')
+                .usingParentCompositeKey<CompositeKey>(key => key.set(target => target.orderId, event => event.orderId))
+                .usingConstantParentKey('constant')
+            )).not.toThrow();
+
+            const definition = builder.build('orderLine', 'OrderLine') as unknown as { Join: JoinRecordWithParentKey[] };
+            const entry = definition.Join.find(candidate => candidate.Key.Id === 'OrderLineJoined')!;
+
+            // JoinDefinition has no ParentKey slot on the wire, so none of the calls above
+            // should have produced a ParentKey property.
+            expect(entry.Value.ParentKey).toBeUndefined();
+        });
+    });
+});

package/projections/declarative/CompositeKeyBuilder.ts

@@ -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.
+
+import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
+import { ICompositeKeyBuilder } from './ICompositeKeyBuilder';
+
+/**
+ * Concrete implementation of {@link ICompositeKeyBuilder} that builds a `$composite(...)` key
+ * expression from multiple event properties mapped onto named parts of a key type.
+ * @template TKeyType - The composite key type.
+ * @template TEvent - The event type.
+ */
+export class CompositeKeyBuilder<TKeyType, TEvent> implements ICompositeKeyBuilder<TKeyType, TEvent> {
+    private readonly _parts: Array<{ property: string; expression: string }> = [];
+
+    /** @inheritdoc */
+    set(
+        targetPropertyAccessor: PropertyAccessor<TKeyType>,
+        sourcePropertyAccessor: PropertyAccessor<TEvent>
+    ): ICompositeKeyBuilder<TKeyType, TEvent> {
+        const targetHandler = new PropertyPathResolverProxyHandler();
+        const targetProxy = new Proxy({}, targetHandler);
+        targetPropertyAccessor(targetProxy as TKeyType);
+
+        const sourceHandler = new PropertyPathResolverProxyHandler();
+        const sourceProxy = new Proxy({}, sourceHandler);
+        sourcePropertyAccessor(sourceProxy as TEvent);
+
+        this._parts.push({ property: targetHandler.property, expression: sourceHandler.property });
+        return this;
+    }
+
+    /** @inheritdoc */
+    build(): string {
+        const parts = this._parts.map(part => `${part.property}=${part.expression}`).join(',');
+        return `$composite(${parts})`;
+    }
+}

package/projections/declarative/FromBuilder.ts

@@ -2,6 +2,9 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
+import { AddBuilder } from './AddBuilder';
+import { AddChildBuilder, ChildAdditionEntry } from './AddChildBuilder';
+import { CompositeKeyBuilder } from './CompositeKeyBuilder';
 import { IAddBuilder } from './IAddBuilder';
 import { IAddChildBuilder } from './IAddChildBuilder';
 import { ICompositeKeyBuilder } from './ICompositeKeyBuilder';
@@ -9,6 +12,7 @@ import { IFromBuilder } from './IFromBuilder';
 import { ISetBuilder } from './ISetBuilder';
 import { ISubtractBuilder } from './ISubtractBuilder';
 import { SetBuilder } from './SetBuilder';
+import { SubtractBuilder } from './SubtractBuilder';
 
 /**
  * Accumulated property mapping for a from clause.
@@ -17,6 +21,7 @@ export interface FromEntry {
     properties: Record<string, string>;
     key: string;
     parentKey: string;
+    children: ChildAdditionEntry[];
 }
 
 /**
@@ -28,7 +33,8 @@ export class FromBuilder<TReadModel, TEvent> implements IFromBuilder<TReadModel,
     readonly entry: FromEntry = {
         properties: {},
         key: '$eventSourceId',
-        parentKey: ''
+        parentKey: '',
+        children: []
     };
 
     /** @inheritdoc */
@@ -75,13 +81,19 @@ export class FromBuilder<TReadModel, TEvent> implements IFromBuilder<TReadModel,
     }
 
     /** @inheritdoc */
-    usingCompositeKey<TKeyType>(_builderCallback: (builder: ICompositeKeyBuilder<TKeyType, TEvent>) => void): this {
-        throw new Error('usingCompositeKey is not implemented yet.');
+    usingCompositeKey<TKeyType>(builderCallback: (builder: ICompositeKeyBuilder<TKeyType, TEvent>) => void): this {
+        const compositeKeyBuilder = new CompositeKeyBuilder<TKeyType, TEvent>();
+        builderCallback(compositeKeyBuilder);
+        this.entry.key = compositeKeyBuilder.build();
+        return this;
     }
 
     /** @inheritdoc */
-    usingParentCompositeKey<TKeyType>(_builderCallback: (builder: ICompositeKeyBuilder<TKeyType, TEvent>) => void): this {
-        throw new Error('usingParentCompositeKey is not implemented yet.');
+    usingParentCompositeKey<TKeyType>(builderCallback: (builder: ICompositeKeyBuilder<TKeyType, TEvent>) => void): this {
+        const compositeKeyBuilder = new CompositeKeyBuilder<TKeyType, TEvent>();
+        builderCallback(compositeKeyBuilder);
+        this.entry.parentKey = compositeKeyBuilder.build();
+        return this;
     }
 
     /** @inheritdoc */
@@ -115,30 +127,63 @@ export class FromBuilder<TReadModel, TEvent> implements IFromBuilder<TReadModel,
     }
 
     /** @inheritdoc */
-    add(_readModelPropertyAccessor: PropertyAccessor<TReadModel>): IAddBuilder<TEvent, this> {
-        throw new Error('add is not implemented yet.');
+    add(readModelPropertyAccessor: PropertyAccessor<TReadModel>): IAddBuilder<TEvent, this> {
+        const handler = new PropertyPathResolverProxyHandler();
+        const proxy = new Proxy({}, handler);
+        readModelPropertyAccessor(proxy as TReadModel);
+        return new AddBuilder<TEvent, this>(
+            handler.property,
+            (property, expression) => { this.entry.properties[property] = expression; },
+            this
+        );
     }
 
     /** @inheritdoc */
-    subtract(_readModelPropertyAccessor: PropertyAccessor<TReadModel>): ISubtractBuilder<TEvent, this> {
-        throw new Error('subtract is not implemented yet.');
+    subtract(readModelPropertyAccessor: PropertyAccessor<TReadModel>): ISubtractBuilder<TEvent, this> {
+        const handler = new PropertyPathResolverProxyHandler();
+        const proxy = new Proxy({}, handler);
+        readModelPropertyAccessor(proxy as TReadModel);
+        return new SubtractBuilder<TEvent, this>(
+            handler.property,
+            (property, expression) => { this.entry.properties[property] = expression; },
+            this
+        );
     }
 
     /** @inheritdoc */
-    count(_readModelPropertyAccessor: PropertyAccessor<TReadModel>): this {
-        throw new Error('count is not implemented yet.');
+    count(readModelPropertyAccessor: PropertyAccessor<TReadModel>): this {
+        const handler = new PropertyPathResolverProxyHandler();
+        const proxy = new Proxy({}, handler);
+        readModelPropertyAccessor(proxy as TReadModel);
+        this.entry.properties[handler.property] = '$count';
+        return this;
     }
 
     /** @inheritdoc */
     addChild<TChildModel>(
-        _targetPropertyAccessor: PropertyAccessor<TReadModel>,
-        _eventPropertyAccessorOrBuilderCallback: PropertyAccessor<TEvent> | ((builder: IAddChildBuilder<TChildModel, TEvent>) => void)
+        targetPropertyAccessor: PropertyAccessor<TReadModel>,
+        eventPropertyAccessorOrBuilderCallback: PropertyAccessor<TEvent> | ((builder: IAddChildBuilder<TChildModel, TEvent>) => void)
     ): this {
-        throw new Error('addChild is not implemented yet.');
+        const targetHandler = new PropertyPathResolverProxyHandler();
+        const targetProxy = new Proxy({}, targetHandler);
+        targetPropertyAccessor(targetProxy as TReadModel);
+
+        const probe = new AddChildBuilder<TChildModel, TEvent>();
+        const probeProxy = new Proxy({}, probe);
+        (eventPropertyAccessorOrBuilderCallback as (value: unknown) => void)(probeProxy);
+
+        this.entry.children.push(probe.usedAsBuilder
+            ? { targetProperty: targetHandler.property, identifiedBy: probe.identifiedByProperty, usingKey: probe.usingKeyProperty }
+            : { targetProperty: targetHandler.property, fromEventProperty: probe.capturedEventProperty });
+        return this;
     }
 
     /** @inheritdoc */
     setThisValue(): ISetBuilder<TEvent, this> {
-        throw new Error('setThisValue is not implemented yet.');
+        return new SetBuilder<TEvent, this>(
+            '$this',
+            (rp, expr) => { this.entry.properties[rp] = expr; },
+            this
+        );
     }
 }

package/projections/declarative/ICompositeKeyBuilder.ts

@@ -19,4 +19,10 @@ export interface ICompositeKeyBuilder<TKeyType, TEvent> {
         targetPropertyAccessor: PropertyAccessor<TKeyType>,
         sourcePropertyAccessor: PropertyAccessor<TEvent>
     ): ICompositeKeyBuilder<TKeyType, TEvent>;
+
+    /**
+     * Builds the composite key expression from the configured parts.
+     * @returns The `$composite(...)` property expression.
+     */
+    build(): string;
 }

package/projections/declarative/JoinBuilder.ts

@@ -2,6 +2,9 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
+import { AddBuilder } from './AddBuilder';
+import { AddChildBuilder, ChildAdditionEntry } from './AddChildBuilder';
+import { CompositeKeyBuilder } from './CompositeKeyBuilder';
 import { IAddBuilder } from './IAddBuilder';
 import { IAddChildBuilder } from './IAddChildBuilder';
 import { ICompositeKeyBuilder } from './ICompositeKeyBuilder';
@@ -9,6 +12,7 @@ import { IJoinBuilder } from './IJoinBuilder';
 import { ISetBuilder } from './ISetBuilder';
 import { ISubtractBuilder } from './ISubtractBuilder';
 import { SetBuilder } from './SetBuilder';
+import { SubtractBuilder } from './SubtractBuilder';
 
 /**
  * Accumulated property mapping for a join clause.
@@ -17,6 +21,7 @@ export interface JoinEntry {
     on: string;
     properties: Record<string, string>;
     key: string;
+    children: ChildAdditionEntry[];
 }
 
 /**
@@ -28,7 +33,8 @@ export class JoinBuilder<TReadModel, TEvent> implements IJoinBuilder<TReadModel,
     readonly entry: JoinEntry = {
         on: '',
         properties: {},
-        key: '$eventSourceId'
+        key: '$eventSourceId',
+        children: []
     };
 
     /** @inheritdoc */
@@ -71,22 +77,31 @@ export class JoinBuilder<TReadModel, TEvent> implements IJoinBuilder<TReadModel,
 
     /** @inheritdoc */
     usingParentKey(_keyAccessor: PropertyAccessor<TEvent>): this {
-        throw new Error('usingParentKey is not supported for join mappings.');
+        // A join's wire definition (JoinDefinition) has no ParentKey slot - the C# client
+        // accepts this call too (it is inherited from the shared key-builder base) but its
+        // JoinBuilder.Build() only ever reads On/Properties/Key, so the value is silently
+        // unused there as well. Matching that: accept the call, but it has no effect.
+        return this;
     }
 
     /** @inheritdoc */
     usingParentKeyFromContext(_contextPropertyName: string): this {
-        throw new Error('usingParentKeyFromContext is not supported for join mappings.');
+        // See usingParentKey - accepted for interface parity with From, no wire effect for Join.
+        return this;
     }
 
     /** @inheritdoc */
-    usingCompositeKey<TKeyType>(_builderCallback: (builder: ICompositeKeyBuilder<TKeyType, TEvent>) => void): this {
-        throw new Error('usingCompositeKey is not implemented yet.');
+    usingCompositeKey<TKeyType>(builderCallback: (builder: ICompositeKeyBuilder<TKeyType, TEvent>) => void): this {
+        const compositeKeyBuilder = new CompositeKeyBuilder<TKeyType, TEvent>();
+        builderCallback(compositeKeyBuilder);
+        this.entry.key = compositeKeyBuilder.build();
+        return this;
     }
 
     /** @inheritdoc */
     usingParentCompositeKey<TKeyType>(_builderCallback: (builder: ICompositeKeyBuilder<TKeyType, TEvent>) => void): this {
-        throw new Error('usingParentCompositeKey is not supported for join mappings.');
+        // See usingParentKey - accepted for interface parity with From, no wire effect for Join.
+        return this;
     }
 
     /** @inheritdoc */
@@ -97,7 +112,8 @@ export class JoinBuilder<TReadModel, TEvent> implements IJoinBuilder<TReadModel,
 
     /** @inheritdoc */
     usingConstantParentKey(_value: string): this {
-        throw new Error('usingConstantParentKey is not supported for join mappings.');
+        // See usingParentKey - accepted for interface parity with From, no wire effect for Join.
+        return this;
     }
 
     /** @inheritdoc */
@@ -119,30 +135,63 @@ export class JoinBuilder<TReadModel, TEvent> implements IJoinBuilder<TReadModel,
     }
 
     /** @inheritdoc */
-    add(_readModelPropertyAccessor: PropertyAccessor<TReadModel>): IAddBuilder<TEvent, this> {
-        throw new Error('add is not implemented yet.');
+    add(readModelPropertyAccessor: PropertyAccessor<TReadModel>): IAddBuilder<TEvent, this> {
+        const handler = new PropertyPathResolverProxyHandler();
+        const proxy = new Proxy({}, handler);
+        readModelPropertyAccessor(proxy as TReadModel);
+        return new AddBuilder<TEvent, this>(
+            handler.property,
+            (property, expression) => { this.entry.properties[property] = expression; },
+            this
+        );
     }
 
     /** @inheritdoc */
-    subtract(_readModelPropertyAccessor: PropertyAccessor<TReadModel>): ISubtractBuilder<TEvent, this> {
-        throw new Error('subtract is not implemented yet.');
+    subtract(readModelPropertyAccessor: PropertyAccessor<TReadModel>): ISubtractBuilder<TEvent, this> {
+        const handler = new PropertyPathResolverProxyHandler();
+        const proxy = new Proxy({}, handler);
+        readModelPropertyAccessor(proxy as TReadModel);
+        return new SubtractBuilder<TEvent, this>(
+            handler.property,
+            (property, expression) => { this.entry.properties[property] = expression; },
+            this
+        );
     }
 
     /** @inheritdoc */
-    count(_readModelPropertyAccessor: PropertyAccessor<TReadModel>): this {
-        throw new Error('count is not implemented yet.');
+    count(readModelPropertyAccessor: PropertyAccessor<TReadModel>): this {
+        const handler = new PropertyPathResolverProxyHandler();
+        const proxy = new Proxy({}, handler);
+        readModelPropertyAccessor(proxy as TReadModel);
+        this.entry.properties[handler.property] = '$count';
+        return this;
     }
 
     /** @inheritdoc */
     addChild<TChildModel>(
-        _targetPropertyAccessor: PropertyAccessor<TReadModel>,
-        _eventPropertyAccessorOrBuilderCallback: PropertyAccessor<TEvent> | ((builder: IAddChildBuilder<TChildModel, TEvent>) => void)
+        targetPropertyAccessor: PropertyAccessor<TReadModel>,
+        eventPropertyAccessorOrBuilderCallback: PropertyAccessor<TEvent> | ((builder: IAddChildBuilder<TChildModel, TEvent>) => void)
     ): this {
-        throw new Error('addChild is not implemented yet.');
+        const targetHandler = new PropertyPathResolverProxyHandler();
+        const targetProxy = new Proxy({}, targetHandler);
+        targetPropertyAccessor(targetProxy as TReadModel);
+
+        const probe = new AddChildBuilder<TChildModel, TEvent>();
+        const probeProxy = new Proxy({}, probe);
+        (eventPropertyAccessorOrBuilderCallback as (value: unknown) => void)(probeProxy);
+
+        this.entry.children.push(probe.usedAsBuilder
+            ? { targetProperty: targetHandler.property, identifiedBy: probe.identifiedByProperty, usingKey: probe.usingKeyProperty }
+            : { targetProperty: targetHandler.property, fromEventProperty: probe.capturedEventProperty });
+        return this;
     }
 
     /** @inheritdoc */
     setThisValue(): ISetBuilder<TEvent, this> {
-        throw new Error('setThisValue is not implemented yet.');
+        return new SetBuilder<TEvent, this>(
+            '$this',
+            (rp, expr) => { this.entry.properties[rp] = expr; },
+            this
+        );
     }
 }

package/projections/declarative/NestedBuilder.ts

@@ -0,0 +1,76 @@
+// 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 { ChildrenBuilder } from './ChildrenBuilder';
+
+/**
+ * Concrete implementation of {@link INestedBuilder}, building the `ChildrenDefinition` for a
+ * nested single-object sub-projection reached through `.nested()`.
+ * @template TParentReadModel - The parent read model type.
+ * @template TNestedReadModel - The nested object read model type.
+ */
+export class NestedBuilder<TParentReadModel, TNestedReadModel>
+    extends ProjectionBuilderCore<TNestedReadModel, INestedBuilder<TParentReadModel, TNestedReadModel>>
+    implements INestedBuilder<TParentReadModel, TNestedReadModel> {
+    /** @inheritdoc */
+    clearWith(eventType: Function): INestedBuilder<TParentReadModel, TNestedReadModel> {
+        const contractType = this.toContractEventType(eventType);
+        this._removedWith.push({
+            Key: contractType,
+            Value: { Key: '$eventSourceId', ParentKey: '' }
+        });
+        return this;
+    }
+
+    /** @inheritdoc */
+    children<TChildModel>(
+        targetPropertyAccessor: PropertyAccessor<TNestedReadModel>,
+        builderCallback: (builder: IChildrenBuilder<TNestedReadModel, TChildModel>) => void
+    ): INestedBuilder<TParentReadModel, TNestedReadModel> {
+        const handler = new PropertyPathResolverProxyHandler();
+        const proxy = new Proxy({}, handler);
+        targetPropertyAccessor(proxy as TNestedReadModel);
+
+        const builder = new ChildrenBuilder<TNestedReadModel, TChildModel>();
+        builderCallback(builder);
+        this._children[handler.property] = builder.buildDefinition();
+        return this;
+    }
+
+    /** @inheritdoc */
+    nested<TGrandNestedModel>(
+        targetPropertyAccessor: PropertyAccessor<TNestedReadModel>,
+        builderCallback: (builder: INestedBuilder<TNestedReadModel, TGrandNestedModel>) => void
+    ): INestedBuilder<TParentReadModel, TNestedReadModel> {
+        const handler = new PropertyPathResolverProxyHandler();
+        const proxy = new Proxy({}, handler);
+        targetPropertyAccessor(proxy as TNestedReadModel);
+
+        const builder = new NestedBuilder<TNestedReadModel, TGrandNestedModel>();
+        builderCallback(builder);
+        this._nested[handler.property] = builder.buildDefinition();
+        return this;
+    }
+
+    /**
+     * Builds the {@link ChildrenDefinitionLike} representing this nested object.
+     * @returns The accumulated nested definition.
+     */
+    buildDefinition(): ChildrenDefinitionLike {
+        return {
+            IdentifiedBy: '',
+            From: this._from,
+            Join: this._join,
+            Children: this._children,
+            All: this._all,
+            RemovedWith: this._removedWith,
+            RemovedWithJoin: this._removedWithJoin,
+            AutoMap: this._autoMap,
+            Nested: this._nested
+        };
+    }
+}