@cratis/chronicle 6.48.0 → 6.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.48.0",
+    "version": "6.49.0",
     "description": "Event sourcing for TypeScript and Node.js — the idiomatic client for Cratis Chronicle, the open-source event-sourcing database",
     "author": "Cratis",
     "license": "MIT",
@@ -173,12 +173,12 @@
         "clean": "rm -rf dist",
         "test": "vitest run",
         "test:integration": "vitest run --config vitest.integration.config.ts",
-        "test:standard-types": "tsc --ignoreConfig --noEmit --target es2022 --module es2022 --moduleResolution bundler --lib es2022,esnext.decorators --types node --skipLibCheck --strict schemas/decorators.standard.spec.ts projections/declarative/addChildCompatibility.standard.spec.ts projections/declarative/for_CompositeKeyBuilder/when_typing_constant_parts.standard.spec.ts projections/modelBound/decorators.standard.spec.ts events/classDecorators.standard.spec.ts reactors/decorators.standard.spec.ts readModels/standardFallbacks.standard.spec.ts readModels/registration.standard.spec.ts for_ChronicleClient/when_registering_artifacts/with_standard_property_mappings.standard.spec.ts artifacts/validateArtifactSchemas.spec.ts testing/for_EventScenario/when_appending_concept_fields/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_scoped_constraints/with_standard_decorators.standard.spec.ts schemas/for_JsonSchemaGenerator/when_generating_children/with_standard_decorators.standard.spec.ts events/for_handles/when_decorating_a_method.standard.spec.ts testing/for_ReadModelScenario/when_evaluating_arithmetic/with_standard_decorators.standard.spec.ts testing/for_ReadModelScenario/when_evaluating_joins/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_field_types/with_standard_decorators.standard.spec.ts eventSequences/for_EventSequence/when_appending/with_subject_annotations.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_from_all.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_tags/with_standard_decorators.standard.spec.ts telemetry/for_ChronicleTelemetry/when_exposing_names/with_convention_names.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_from_all_events.standard.spec.ts events/for_observerFilters/when_registering/with_standard_decorators.standard.spec.ts reactors/for_Reactors/against_a_kernel/when_filtering_source_and_stream_types.integration.spec.ts testing/for_observerScenarios/when_selecting_filters/with_source_and_stream_types.spec.ts readModels/for_ReadModelWatcher/watchCompatibility.standard.spec.ts",
+        "test:standard-types": "tsc --ignoreConfig --noEmit --target es2022 --module es2022 --moduleResolution bundler --lib es2022,esnext.decorators --types node --skipLibCheck --strict schemas/decorators.standard.spec.ts projections/declarative/addChildCompatibility.standard.spec.ts projections/declarative/for_CompositeKeyBuilder/when_typing_constant_parts.standard.spec.ts projections/modelBound/decorators.standard.spec.ts events/classDecorators.standard.spec.ts reactors/decorators.standard.spec.ts readModels/standardFallbacks.standard.spec.ts readModels/registration.standard.spec.ts for_ChronicleClient/when_registering_artifacts/with_standard_property_mappings.standard.spec.ts artifacts/validateArtifactSchemas.spec.ts testing/for_EventScenario/when_appending_concept_fields/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_scoped_constraints/with_standard_decorators.standard.spec.ts schemas/for_JsonSchemaGenerator/when_generating_children/with_standard_decorators.standard.spec.ts events/for_handles/when_decorating_a_method.standard.spec.ts testing/for_ReadModelScenario/when_evaluating_arithmetic/with_standard_decorators.standard.spec.ts testing/for_ReadModelScenario/when_evaluating_joins/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_field_types/with_standard_decorators.standard.spec.ts eventSequences/for_EventSequence/when_appending/with_subject_annotations.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_from_all.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_tags/with_standard_decorators.standard.spec.ts telemetry/for_ChronicleTelemetry/when_exposing_names/with_convention_names.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_from_all_events.standard.spec.ts events/for_observerFilters/when_registering/with_standard_decorators.standard.spec.ts reactors/for_Reactors/against_a_kernel/when_filtering_source_and_stream_types.integration.spec.ts testing/for_observerScenarios/when_selecting_filters/with_source_and_stream_types.spec.ts readModels/for_ReadModelWatcher/watchCompatibility.standard.spec.ts for_EventStore/when_implementing_a_legacy_event_store.spec.ts",
         "test:native": "node ./scripts/check-native-esm.mjs"
     },
     "dependencies": {
         "@bufbuild/protobuf": "^2.16.0",
-        "@cratis/chronicle.contracts": "19.26.2",
+        "@cratis/chronicle.contracts": "19.30.0",
         "@grpc/grpc-js": "^1.14.5",
         "@opentelemetry/api": "^1.9.1",
         "glob": "^13.0.6",

package/projections/eventContextPropertyExpression.ts

@@ -23,7 +23,8 @@ const contextProperties = {
     correlationId: true,
     causation: true,
     tags: true
-} satisfies Record<keyof EventContext, true>;
+    // eventSource is deliberately not projectable: its kernel resolution is not part of the supported expression set.
+} satisfies Record<Exclude<keyof EventContext, 'eventSource'>, true>;
 
 // Mirror the kernel's DerivedPropertyFunctions registry: Week() applies to dates only.
 const derivedFunctions: Record<string, string> = { week: 'Week' };

package/testing/EventScenario.event-sources.spec.ts

@@ -0,0 +1,34 @@
+// 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 { chai, describe, it } from 'vitest';
+import { field } from '@cratis/fundamentals';
+import { eventType } from '../events/eventTypeDecorator.js';
+import { EventScenario, UnsupportedEventSequenceOperation } from './index.js';
+
+chai.should();
+class ScenarioSourceEvent { @field(String) name: string; constructor(name: string) { this.name = name; } }
+eventType('ScenarioSourceEvent')(ScenarioSourceEvent);
+
+const rejects = async (action: () => Promise<unknown>) => {
+    let caught: unknown;
+    try { await action(); } catch (error) { caught = error; }
+    (caught instanceof UnsupportedEventSequenceOperation).should.be.true;
+};
+const create = () => new EventScenario({ artifacts: { eventTypes: [ScenarioSourceEvent] } });
+
+describe('when appending with registered event sources in an in-process scenario', () => {
+    it('should reject the eventSource option on append instead of dropping it', async () => {
+        await rejects(() => create().append('A', new ScenarioSourceEvent('x'), { eventSource: 'Account' }));
+    });
+    it('should reject the eventSource option on appendMany instead of dropping it', async () => {
+        await rejects(() => create().appendMany([{ eventSourceId: 'A', event: new ScenarioSourceEvent('x') }], { eventSource: 'Account' }));
+    });
+    it('should reject a per-event eventSource on appendMany instead of dropping it', async () => {
+        await rejects(() => create().appendMany([{ eventSourceId: 'A', event: new ScenarioSourceEvent('x'), eventSource: 'Account' }]));
+    });
+    it('should reject a per-event eventStream on appendMany instead of dropping it', async () => {
+        await rejects(() => create().appendMany([{ eventSourceId: 'A', event: new ScenarioSourceEvent('x'), eventStream: 'Transactions' }]));
+    });
+});

package/testing/projections/ProjectionReadModelProcessor.ts

@@ -138,7 +138,8 @@ export class ProjectionReadModelProcessor<TReadModel extends object> implements
             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) {
+            } else if (state.__initialized === false && from) {
+                // Chronicle 19.30.0 no longer initializes a parent on events only a child subscribes to.
                 for (const [name, value] of Object.entries(this.initialValues())) if (!(name in state)) state[name] = value;
                 state.__initialized = true;
             }

package/transactions/IUnitOfWork.ts

@@ -6,6 +6,7 @@ import { AppendError } from '../eventSequences/AppendError.js';
 import { ConcurrencyViolation } from '../eventSequences/ConcurrencyViolation.js';
 import { ConstraintViolation } from '../eventSequences/ConstraintViolation.js';
 import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
+import { TransactionalEventRouting } from './TransactionalEventRouting.js';
 import { AppendResult } from '../eventSequences/AppendResult.js';
 
 /**
@@ -26,8 +27,9 @@ export interface IUnitOfWork {
      * @param eventSequenceId - The identifier of the event sequence to append to.
      * @param eventSourceId - The event source identifier.
      * @param event - The event payload.
+     * @param routing - Optional registered event source / stream routing for this event.
      */
-    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object): void;
+    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object, routing?: TransactionalEventRouting): void;
 
     /**
      * Gets all events currently buffered in this unit of work.

package/transactions/TransactionalEventRouting.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Constructor } from '@cratis/fundamentals';
+
+/**
+ * Optional registered event source routing for an event added to a unit of work.
+ * Carried through to the append on commit, where it is validated like any other append.
+ */
+export interface TransactionalEventRouting {
+    /** Registered event source definition (class decorated with `@eventSource`, or its name). */
+    readonly eventSource?: Constructor | string;
+
+    /** Stream name declared by {@link eventSource}. */
+    readonly eventStream?: string;
+}

package/transactions/UnitOfWork.ts

@@ -8,7 +8,9 @@ import { ConcurrencyViolation } from '../eventSequences/ConcurrencyViolation.js'
 import { ConstraintViolation } from '../eventSequences/ConstraintViolation.js';
 import { EventForEventSourceId } from '../eventSequences/EventForEventSourceId.js';
 import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
+import { planDerivedGuards, resolveBatchRouting } from '../eventSequences/resolveEventSourceRouting.js';
 import { IEventStore } from '../IEventStore.js';
+import { TransactionalEventRouting } from './TransactionalEventRouting.js';
 import { IUnitOfWork } from './IUnitOfWork.js';
 
 interface EventForEventSourceIdWithSequenceNumber {
@@ -46,14 +48,16 @@ export class UnitOfWork implements IUnitOfWork {
     }
 
     /** @inheritdoc */
-    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object): void {
+    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object, routing?: TransactionalEventRouting): void {
         this.throwIfCompleted();
         this._events.push({
             sequenceNumber: this._events.length,
             eventSequenceId,
             eventForEventSourceId: {
                 eventSourceId,
-                event
+                event,
+                ...(routing?.eventSource !== undefined ? { eventSource: routing.eventSource } : {}),
+                ...(routing?.eventStream !== undefined ? { eventStream: routing.eventStream } : {})
             }
         });
     }
@@ -100,6 +104,13 @@ export class UnitOfWork implements IUnitOfWork {
                 eventsByEventSequence.set(key, events);
             }
 
+            // Resolve routing and required guards for every group first: a rejection must not follow a written group.
+            const eventSources = this._eventStore.eventSources;
+            for (const eventsForSequence of eventSources ? eventsByEventSequence.values() : []) {
+                const events = eventsForSequence.map(_ => _.eventForEventSourceId);
+                planDerivedGuards(events.map(_ => resolveBatchRouting(eventSources, _)), events, undefined);
+            }
+
             for (const [eventSequenceId, eventsForSequence] of eventsByEventSequence) {
                 const sequence = this._eventStore.getEventSequence(new EventSequenceId(eventSequenceId));
                 const appendResults = await sequence.appendMany(

package/transactions/for_UnitOfWork/when_committing_events_with_event_source_routing.spec.ts

@@ -0,0 +1,41 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Guid } from '@cratis/fundamentals';
+import { beforeEach, chai, describe, it, vi } from 'vitest';
+import { EventSequenceId } from '../../eventSequences/index.js';
+import type { IEventStore } from '../../IEventStore.js';
+import { UnitOfWork } from '../UnitOfWork.js';
+
+const should = chai.should();
+
+describe('when committing events with event source routing in a unit of work', () => {
+    let batch: any[];
+    beforeEach(async () => {
+        const appendMany = vi.fn().mockResolvedValue([{ isSuccess: true, constraintViolations: [], errors: [] }, { isSuccess: true, constraintViolations: [], errors: [] }]);
+        const store = { getEventSequence: () => ({ appendMany }) } as unknown as IEventStore;
+        const unitOfWork = new UnitOfWork(Guid.create(), () => {}, store);
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { first: 1 }, { eventSource: 'Account', eventStream: 'Transactions' });
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'c-1', { second: 2 }, { eventSource: 'Customer' });
+        await unitOfWork.commit();
+        batch = appendMany.mock.calls[0][0];
+    });
+    it('should keep the source and stream of the first event', () => {
+        batch[0].eventSource.should.equal('Account');
+        batch[0].eventStream.should.equal('Transactions');
+    });
+    it('should keep a different source on the second event without a stream', () => {
+        batch[1].eventSource.should.equal('Customer');
+        should.not.exist(batch[1].eventStream);
+    });
+});
+
+describe('when adding an event to a unit of work without routing', () => {
+    it('should not add routing keys to the buffered event', async () => {
+        const appendMany = vi.fn().mockResolvedValue([{ isSuccess: true, constraintViolations: [], errors: [] }]);
+        const unitOfWork = new UnitOfWork(Guid.create(), () => {}, { getEventSequence: () => ({ appendMany }) } as unknown as IEventStore);
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', {});
+        await unitOfWork.commit();
+        Object.keys(appendMany.mock.calls[0][0][0]).sort().should.deep.equal(['event', 'eventSourceId']);
+    });
+});

package/transactions/index.ts

@@ -6,3 +6,4 @@ export type { IUnitOfWorkManager } from './IUnitOfWorkManager.js';
 export { NoUnitOfWorkHasBeenStarted } from './NoUnitOfWorkHasBeenStarted.js';
 export { UnitOfWork } from './UnitOfWork.js';
 export { UnitOfWorkManager } from './UnitOfWorkManager.js';
+export type { TransactionalEventRouting } from './TransactionalEventRouting.js';

package/types/DecoratorType.ts

@@ -33,5 +33,8 @@ export enum DecoratorType {
     EventTypeMigration = 'eventTypeMigration',
 
     /** Global read model variant handler artifacts discovered through the globalFor decorator. */
-    GlobalForHandler = 'globalForHandler'
+    GlobalForHandler = 'globalForHandler',
+
+    /** Event source definition artifacts discovered through the eventSource decorator. */
+    EventSource = 'eventSource'
 }