@cratis/chronicle 6.29.0 → 6.31.0

package/testing/projections/ProjectionReadModelProcessor.ts

@@ -6,6 +6,7 @@ import type { Constructor } from '@cratis/fundamentals';
 import type { CompiledProjectionDefinitions } from '../../projections/CompiledProjectionDefinitions.js';
 import { eventContractPath } from '../../projections/eventContractPath.js';
 import type { FromRecord, RemovedWithRecord } from '../../projections/declarative/ProjectionBuilderCore.js';
+import type { ChildrenDefinitionLike } from '../../projections/modelBound/childrenAndNestedBuilder.js';
 import { deserializeReadModel } from '../../readModels/deserializeReadModel.js';
 import type { JsonSchema } from '../../schemas/JsonSchema.js';
 import type { IReadModelProcessor } from '../IReadModelProcessor.js';
@@ -16,12 +17,21 @@ import { ProjectionExpressionEvaluator } from './ProjectionExpressionEvaluator.j
 import { ProjectionValueConverter } from './ProjectionValueConverter.js';
 import { UnsupportedProjectionOperation } from './UnsupportedProjectionOperation.js';
 
+interface ChildBinding {
+    readonly property: string;
+    readonly identifiedBy: string;
+    readonly key: string;
+    readonly from: FromRecord | undefined;
+    readonly items: JsonSchema;
+}
+
 /** In-process interpreter of the validated, registered projection contract subset. */
 export class ProjectionReadModelProcessor<TReadModel extends object> implements IReadModelProcessor<TReadModel> {
     private readonly _schema: JsonSchema;
     private readonly _initial: Record<string, unknown>;
     private readonly _from: ReadonlyMap<string, FromRecord>;
     private readonly _removed: ReadonlySet<string>;
+    private readonly _children: ReadonlyMap<string, ChildBinding>;
     private readonly _eventSchemas: ReadonlyMap<string, JsonSchema>;
     private readonly _bindings: ReadonlyMap<string, { generation: number; path: string; declaration: string }>;
     private _engineState: Record<string, Record<string, unknown>> = {};
@@ -32,15 +42,29 @@ export class ProjectionReadModelProcessor<TReadModel extends object> implements
         const registration = compiled.readModels.find(entry => entry.Type.Identifier === _definition.ReadModel)!;
         this._schema = JSON.parse(registration.Schema) as JsonSchema;
         this._initial = JSON.parse(_definition.InitialModelState || '{}') as Record<string, unknown>;
-        const wire = _definition as unknown as { From: FromRecord[]; RemovedWith: RemovedWithRecord[] };
+        const wire = _definition as unknown as { From: FromRecord[]; RemovedWith: RemovedWithRecord[]; Children?: Record<string, ChildrenDefinitionLike> };
         this._from = new Map((wire.From ?? []).map(entry => [entry.Key.Id, entry]));
         this._removed = new Set((wire.RemovedWith ?? []).map(entry => entry.Key.Id));
-        this._bindings = new Map([...(wire.From ?? []), ...(wire.RemovedWith ?? [])].map(entry => {
+        const declarationFor = (path: string) => compiled.provenance.get(_definition)?.find(provenance => provenance.contractPath === path)?.declaration;
+        const bindings = [...(wire.From ?? []), ...(wire.RemovedWith ?? [])].map(entry => {
             const section = (wire.From ?? []).includes(entry as FromRecord) ? 'From' : 'RemovedWith';
             const path = eventContractPath(section, entry.Key);
-            const declaration = compiled.provenance.get(_definition)?.find(provenance => provenance.contractPath === path)?.declaration ?? 'contract';
-            return [entry.Key.Id, { generation: entry.Key.Generation, path, declaration }];
-        }));
+            return [entry.Key.Id, { generation: entry.Key.Generation, path, declaration: declarationFor(path) ?? 'contract' }] as const;
+        });
+        const children = new Map<string, ChildBinding>();
+        for (const [property, child] of Object.entries(wire.Children ?? {})) {
+            const items = this._schema.properties![property].items!;
+            for (const entry of [...child.From, ...child.RemovedWith]) {
+                const from = child.From.includes(entry as FromRecord) ? entry as FromRecord : undefined;
+                const path = `Children.${property}.${eventContractPath(from ? 'From' : 'RemovedWith', entry.Key)}`;
+                children.set(entry.Key.Id, { property, identifiedBy: child.IdentifiedBy, key: entry.Value.Key, from, items });
+                if (!bindings.some(([id]) => id === entry.Key.Id)) {
+                    bindings.push([entry.Key.Id, { generation: entry.Key.Generation, path, declaration: declarationFor(`Children.${property}`) ?? 'contract' }]);
+                }
+            }
+        }
+        this._children = children;
+        this._bindings = new Map(bindings);
         this._eventSchemas = new Map([...(compiled.eventSchemas.get(_definition) ?? new Map()).values()]
             .map(entry => [entry.eventType.Id, entry.schema]));
     }
@@ -57,41 +81,36 @@ export class ProjectionReadModelProcessor<TReadModel extends object> implements
             const typeId = event.context.eventType.id.value;
             const from = this._from.get(typeId);
             const removed = this._removed.has(typeId);
-            if (!from && !removed) continue;
+            const child = this._children.get(typeId);
+            if (!from && !removed && !child) continue;
             const binding = this._bindings.get(typeId)!;
             if (event.context.eventType.generation.value !== binding.generation) {
                 throw new UnsupportedProjectionOperation(String(this._definition.ReadModel), binding.path, binding.declaration,
                     `seeded event generation ${event.context.eventType.generation.value} differs from subscribed generation ${binding.generation}; multi-generation history requires a kernel-backed test`);
             }
-            // A root removal has the final say when an event is registered for both operations.
             const key = this.keyFor(event.sourceId);
             if (removed) {
                 delete engine[key];
                 states.set(event.sourceId, { instance: null, deleted: true });
                 continue;
             }
-            if (!from) continue;
-            const state = engine[key] ?? this.initialState(key, event);
-            const properties = { ...from.Value.Properties };
-            const schema = this._eventSchemas.get(typeId);
-            const content = ProjectionValueConverter.eventContent(event.content, schema!);
-            if (this._definition.AutoMap !== AutoMap.Disabled && schema) {
-                const explicit = new Set(Object.keys(properties).map(name => name.toLowerCase()));
-                const excluded = new Set((this._definition.NoAutoMapProperties ?? []).map(name => name.toLowerCase()));
-                for (const source of Object.keys(schema.properties ?? {})) {
-                    const destination = Object.keys(this._schema.properties ?? {}).find(name => name.toLowerCase() === source.toLowerCase());
-                    if (destination && !explicit.has(destination.toLowerCase()) && !excluded.has(destination.toLowerCase())) {
-                        properties[destination] = source;
-                        explicit.add(destination.toLowerCase());
-                    }
-                }
+            const schema = this._eventSchemas.get(typeId)!;
+            const content = ProjectionValueConverter.eventContent(event.content, schema);
+            let state = engine[key];
+            if (!state) {
+                // SetInitialState: an event only a child subscribes to creates an uninitialized parent.
+                state = from ? this.initialState(key, event) : this.identityState(key, event, false);
+            } else if (state.__initialized === false) {
+                for (const [name, value] of Object.entries(this.initialValues())) if (!(name in state)) state[name] = value;
+                state.__initialized = true;
             }
-            for (const [destination, expression] of Object.entries(properties)) {
-                const target = this._schema.properties![destination];
-                const value = ProjectionExpressionEvaluator.value(expression, content, event.context, target);
-                // The kernel compares old and new null values; null on an absent member is no change.
-                if (value !== null || state[destination] !== undefined) state[destination] = value;
+            if (from) {
+                const explicit = { ...from.Value.Properties };
+                const excluded = (this._definition.NoAutoMapProperties ?? []);
+                const properties = this._definition.AutoMap !== AutoMap.Disabled ? this.withAutoMap(explicit, schema, this._schema, excluded) : explicit;
+                this.apply(properties, content, event, this._schema, state);
             }
+            if (child) this.applyChild(child, content, event, schema, state, binding);
             // InMemorySink.ApplyChanges always restores lowercase id after applying mappings.
             state.id = ProjectionValueConverter.convert(key, this._schema.properties!.id);
             engine[key] = state;
@@ -112,22 +131,72 @@ export class ProjectionReadModelProcessor<TReadModel extends object> implements
         return canonical;
     }
 
-    private initialState(key: string, event: ScenarioEvent): Record<string, unknown> {
+    private applyChild(child: ChildBinding, content: unknown, event: ScenarioEvent, eventSchema: JsonSchema, state: Record<string, unknown>,
+        binding: { path: string; declaration: string }): void {
+        const identity = ProjectionExpressionEvaluator.pathValue(content, child.key);
+        if (typeof identity !== 'string') {
+            throw new UnsupportedProjectionOperation(String(this._definition.ReadModel), binding.path, binding.declaration,
+                `child key '${child.key}' has no string value in the seeded event; missing child keys require a kernel-backed test`);
+        }
+        const collection = (state[child.property] ??= []) as Record<string, unknown>[];
+        const index = collection.findIndex(item => item[child.identifiedBy] === identity);
+        if (!child.from) {
+            if (index >= 0) collection.splice(index, 1);
+            return;
+        }
+        const item = index >= 0 ? collection[index] : { [child.identifiedBy]: identity };
+        if (index < 0) collection.push(item);
+        // Validation admits only the identifier mapping explicitly; other fields come from same-name AutoMap.
+        // Kernel AutoMap is schema-driven: an untyped child item schema maps nothing (children-untyped-items).
+        const properties = child.items.properties ? this.withAutoMap({}, eventSchema, child.items, [child.identifiedBy]) : {};
+        this.apply(properties, content, event, child.items, item);
+    }
+
+    private withAutoMap(explicit: Record<string, string>, eventSchema: JsonSchema, target: JsonSchema, exclusions: readonly string[]): Record<string, string> {
+        const properties = { ...explicit };
+        const mapped = new Set(Object.keys(properties).map(name => name.toLowerCase()));
+        const excluded = new Set(exclusions.map(name => name.toLowerCase()));
+        for (const source of Object.keys(eventSchema.properties ?? {})) {
+            const destination = Object.keys(target.properties ?? {}).find(name => name.toLowerCase() === source.toLowerCase());
+            if (destination && !mapped.has(destination.toLowerCase()) && !excluded.has(destination.toLowerCase())) {
+                properties[destination] = source;
+                mapped.add(destination.toLowerCase());
+            }
+        }
+        return properties;
+    }
+
+    private apply(properties: Record<string, string>, content: unknown, event: ScenarioEvent, target: JsonSchema, state: Record<string, unknown>): void {
+        for (const [destination, expression] of Object.entries(properties)) {
+            const value = ProjectionExpressionEvaluator.value(expression, content, event.context, target.properties![destination]);
+            // The kernel compares old and new null values; null on an absent member is no change.
+            if (value !== null || state[destination] !== undefined) state[destination] = value;
+        }
+    }
+
+    private initialValues(): Record<string, unknown> {
         const initial: Record<string, unknown> = Object.create(null);
         if (Object.keys(this._initial).length) {
-            Object.assign(initial, ProjectionValueConverter.convert(structuredClone(this._initial), this._schema, false, false));
+            return Object.assign(initial, ProjectionValueConverter.convert(structuredClone(this._initial), this._schema, false, false));
         }
-        if (!Object.keys(this._initial).length) {
-            for (const [name, property] of Object.entries(this._schema.properties ?? {})) {
-                if (property.type === 'array') initial[name] = [];
-            }
+        for (const [name, property] of Object.entries(this._schema.properties ?? {})) {
+            if (property.type === 'array') initial[name] = [];
         }
-        initial.id = ProjectionValueConverter.convert(key, this._schema.properties!.id);
-        initial.__subject = event.context.subject ?? event.sourceId;
-        initial.__initialized = true;
         return initial;
     }
 
+    private initialState(key: string, event: ScenarioEvent): Record<string, unknown> {
+        return Object.assign(this.initialValues(), this.identityState(key, event, true));
+    }
+
+    private identityState(key: string, event: ScenarioEvent, initialized: boolean): Record<string, unknown> {
+        const state: Record<string, unknown> = Object.create(null);
+        state.id = ProjectionValueConverter.convert(key, this._schema.properties!.id);
+        state.__subject = event.context.subject ?? event.sourceId;
+        state.__initialized = initialized;
+        return state;
+    }
+
     private normalize(state: Record<string, unknown>): Record<string, unknown> {
         const result: Record<string, unknown> = Object.create(null);
         for (const [name, schema] of Object.entries(this._schema.properties ?? {})) {

package/testing/projections/for_ProjectionCapabilities/when_rejecting_unsupported_children_operations.spec.ts

@@ -0,0 +1,73 @@
+// 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 { AutoMap } from '@cratis/chronicle.contracts';
+import { field } from '@cratis/fundamentals';
+import { chai, describe, it } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import type { ChildrenDefinitionLike } from '../../../projections/modelBound/childrenAndNestedBuilder.js';
+import { childrenFrom } from '../../../projections/modelBound/childrenFrom.js';
+import { ProjectionCapabilities } from '../ProjectionCapabilities.js';
+import { UnsupportedProjectionOperation } from '../UnsupportedProjectionOperation.js';
+import { Changed } from './given/Changed.js';
+import { compileDeclarative, compileModelBound } from './given/compile.js';
+
+chai.should();
+
+class ChildAdded { itemId!: string; name!: string; }
+field(String)(ChildAdded.prototype, 'itemId');
+field(String)(ChildAdded.prototype, 'name');
+eventType('capability-child-added')(ChildAdded);
+
+type Wire = { Children: Record<string, ChildrenDefinitionLike>; RemovedWith: unknown[] };
+
+function compileChildren() {
+    const result = compileDeclarative(builder => {
+        builder.from(Changed).children<{ lineId: string }>(model => model.labels as never, child => child
+            .identifiedBy(line => line.lineId)
+            .from(ChildAdded, from => from.usingKey(event => event.itemId)));
+    }, [ChildAdded]);
+    const wire = result.definition as unknown as Wire;
+    return { ...result, wire, child: wire.Children.labels };
+}
+
+describe('when rejecting unsupported children operations before any event is seeded', () => {
+    it('should accept the fixture-backed keyed children shape', () => {
+        const { compiled, definition } = compileChildren();
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+    });
+
+    const cases: Array<{ name: string; change: (child: ChildrenDefinitionLike, wire: Wire) => void; path: string; reason: string }> = [
+        { name: 'a join inside children', change: child => { child.Join = [{}]; }, path: 'Children.labels.Join', reason: 'joins require a kernel-backed test' },
+        { name: 'nested children collections', change: child => { child.Children = { inner: child }; }, path: 'Children.labels.Children', reason: 'nested children collections' },
+        { name: 'nested projections inside children', change: child => { child.Nested = { inner: child }; }, path: 'Children.labels.Nested', reason: 'nested projections inside children' },
+        { name: 'removedWithJoin inside children', change: child => { child.RemovedWithJoin = [child.RemovedWithJoin[0] ?? { Key: child.From[0].Key, Value: { Key: '' } }]; }, path: 'Children.labels.RemovedWithJoin', reason: 'removedWithJoin inside children' },
+        { name: 'value children from an event property', change: child => { (child as unknown as Record<string, unknown>).FromEventProperty = { PropertyExpression: 'name' }; }, path: 'Children.labels.FromEventProperty', reason: 'value children from an event property' },
+        { name: 'disabled child AutoMap', change: child => { child.AutoMap = AutoMap.Disabled; }, path: 'Children.labels.AutoMap', reason: 'AutoMap disabled' },
+        { name: 'a child without an identifying property', change: child => { child.IdentifiedBy = '*NotSet*'; }, path: 'Children.labels.IdentifiedBy', reason: 'without a direct identifying property' },
+        { name: 'an event-source-id child key', change: child => { child.From[0].Value.Key = '$eventSourceId'; }, path: 'Children.labels.From[capability-child-added:1].Key', reason: 'only a child key read from a string event property' },
+        { name: 'an event-property parent key', change: child => { child.From[0].Value.ParentKey = 'itemId'; }, path: 'Children.labels.From[capability-child-added:1].ParentKey', reason: 'parent keys other than the event source id' },
+        { name: 'an explicit mapping into a child', change: child => { child.From[0].Value.Properties = { name: 'name' }; }, path: 'Children.labels.From[capability-child-added:1].Properties.name', reason: 'explicit child property mappings' },
+        { name: 'a renamed child mapping', change: child => { child.From[0].Value.Properties = { title: 'name' }; }, path: 'Children.labels.From[capability-child-added:1].Properties.title', reason: 'only same-name AutoMap into typed children' },
+        { name: 'a child mapping from the event context', change: child => { child.From[0].Value.Properties = { name: '$eventContext(occurred)' }; }, path: 'Children.labels.From[capability-child-added:1].Properties.name', reason: 'explicit child property mappings' },
+        { name: 'children combined with initial model state', change: (_child, wire) => { (wire as unknown as Record<string, unknown>).InitialModelState = '{"name":"initial"}'; }, path: 'InitialModelState', reason: 'children with initial model state' },
+        { name: 'a child identifier mapped from another value', change: child => { child.From[0].Value.Properties = { lineId: 'name' }; }, path: 'Children.labels.From[capability-child-added:1].Properties.lineId', reason: 'mapping the child identifier from anything but the child key' },
+        { name: 'a child event that also removes the parent', change: (child, wire) => { wire.RemovedWith = [{ Key: child.From[0].Key, Value: { Key: '$eventSourceId', ParentKey: '' } }]; }, path: 'Children.labels.From[capability-child-added:1]', reason: 'both removes and changes' },
+        { name: 'one event that both adds and removes a child', change: child => { child.RemovedWith = [{ Key: child.From[0].Key, Value: { Key: 'itemId', ParentKey: '' } }]; }, path: 'Children.labels.RemovedWith[capability-child-added:1]', reason: 'more than one children operation' }
+    ];
+    for (const testCase of cases) {
+        it(`should reject ${testCase.name} with its contract path and reason`, () => {
+            const { compiled, definition, wire, child } = compileChildren();
+            testCase.change(child, wire);
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                .with.property('message').that.includes(testCase.path).and.includes(testCase.reason);
+        });
+    }
+
+    it('should reject a children collection that does not target an array of objects', () => {
+        const { compiled, definition } = compileModelBound(model => childrenFrom(ChildAdded, { key: 'itemId' })(model.prototype, 'name'), [ChildAdded]);
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('Children.name (@childrenFrom)').and.includes('must target an array of objects');
+    });
+});

package/testing/projections/for_ProjectionCapabilities/when_rejecting_unsupported_operations.spec.ts

@@ -6,7 +6,6 @@ import { field } from '@cratis/fundamentals';
 import { chai, describe, it } from 'vitest';
 import { eventType } from '../../../events/eventTypeDecorator.js';
 import type { IProjectionBuilderFor } from '../../../projections/declarative/IProjectionBuilderFor.js';
-import { childrenFrom } from '../../../projections/modelBound/childrenFrom.js';
 import { entersOn } from '../../../projections/modelBound/entersOn.js';
 import { eventSequence } from '../../../projections/modelBound/eventSequence.js';
 import { fromEvent } from '../../../projections/modelBound/fromEvent.js';
@@ -30,7 +29,6 @@ chai.should();
 
 describe('when rejecting unsupported operations before any event is seeded', () => {
     const modelBound = [
-        { name: 'children', configure: (model: Function) => childrenFrom(Removed)(model.prototype, 'name'), path: 'Children.name (@childrenFrom)', reason: 'children projections' },
         { name: 'nested', configure: (model: Function) => nested(model.prototype, 'name'), path: 'Nested.name (@nested)', reason: 'nested projections' },
         { name: 'join', configure: (model: Function) => join(Removed, 'name')(model.prototype, 'name'), path: 'Join[capability-removed:1] (@join)', reason: 'joins' },
         { name: 'removedWithJoin', configure: (model: Function) => removedWithJoin(Removed)(model), path: 'RemovedWithJoin[capability-removed:1] (@removedWithJoin)', reason: 'removedWithJoin' },
@@ -77,7 +75,6 @@ describe('when rejecting unsupported operations before any event is seeded', ()
         { name: 'composite key', define: builder => { builder.from(Changed, from => from.usingCompositeKey<{ name: string }>(key => key.set(target => target.name, event => event.name))); }, path: 'From[capability-changed:1].Key (.from().usingCompositeKey)' },
         { name: 'parent key', define: builder => { builder.from(Changed, from => from.usingParentKey(event => event.name)); }, path: 'From[capability-changed:1].ParentKey (.from().usingParentKey)' },
         { name: 'join', define: builder => { builder.from(Changed).join(Removed, join => join.on(model => model.id)); }, path: 'Join[capability-removed:1] (.join)' },
-        { name: 'children', define: builder => { builder.from(Changed).children(model => model.labels, child => child.from(Removed)); }, path: 'Children.labels (.children)' },
         { name: 'nested', define: builder => { builder.from(Changed).nested(model => model.details, child => child.clearWith(Removed)); }, path: 'Nested.details (.nested)' },
         { name: 'removedWithJoin', define: builder => { builder.from(Changed).removedWithJoin(Removed); }, path: 'RemovedWithJoin[capability-removed:1] (.removedWithJoin)' },
         { name: 'removal key', define: builder => { builder.from(Removed).removedWith(Changed, removal => removal.usingKey(event => event.name)); }, path: 'RemovedWith[capability-changed:1].Key (.removedWith)' },

package/vitest.config.ts

@@ -23,7 +23,8 @@ export default defineConfig({
     }],
     test: {
         include: ['**/*.spec.ts', '**/*.spec.js'],
-        exclude: ['node_modules', 'dist'],
+        // Kernel-backed specifications run through vitest.integration.config.ts.
+        exclude: ['node_modules', 'dist', '**/*.integration.spec.ts'],
         environment: 'node'
     }
 });

package/vitest.integration.config.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { defineConfig } from 'vitest/config';
+import baseConfig from './vitest.config.js';
+
+// Kernel-backed specifications. They need a running Chronicle kernel and are skipped unless
+// CHRONICLE_INTEGRATION_CONNECTION_STRING points at one, for example
+// chronicle://chronicle-dev-client:chronicle-dev-secret@localhost:35000
+export default defineConfig({
+    ...baseConfig,
+    test: {
+        include: ['**/*.integration.spec.ts'],
+        exclude: ['node_modules', 'dist'],
+        environment: 'node',
+        testTimeout: 60_000,
+        hookTimeout: 60_000
+    }
+});