@cratis/chronicle 6.49.0 → 6.50.0

package/testing/for_ReactorScenario/when_recording_side_effects/with_named_tags.spec.ts

@@ -0,0 +1,119 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { field } from '@cratis/fundamentals';
+import { beforeEach, chai, describe, it } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { InvalidNamedTag } from '../../../events/InvalidNamedTag.js';
+import { NamedTag } from '../../../events/NamedTag.js';
+import { NamedTagsWithRegisteredEventSourceNotSupported } from '../../../eventSequences/index.js';
+import type { EventContext } from '../../../events/EventContext.js';
+import { reactor } from '../../../reactors/reactor.js';
+import { ReactorScenario } from '../../ReactorScenario.js';
+
+chai.should();
+@eventType('scenario-named-tag-input')
+class NamedTagInput { @field(String) name = 'input'; }
+@eventType('scenario-named-tag-output')
+class NamedTagOutput { @field(String) name = 'output'; }
+
+const contexts: EventContext[] = [];
+@reactor('scenario-named-tag-reactor')
+class NamedTagReactor {
+    namedTagInput(_: NamedTagInput, context: EventContext) {
+        contexts.push(context);
+        return { eventSourceId: 'other', event: new NamedTagOutput(), namedTags: [new NamedTag('origin', context.eventSourceId)] };
+    }
+}
+@reactor('scenario-invalid-named-tag-reactor')
+class InvalidNamedTagReactor {
+    namedTagInput() {
+        return { eventSourceId: 'other', event: new NamedTagOutput(), namedTags: [{ name: ' ', value: 'x' }] };
+    }
+}
+@reactor('scenario-named-tags-registered-source-same-entry')
+class NamedTagRegisteredSourceReactor {
+    namedTagInput() {
+        return { eventSourceId: 'other', event: new NamedTagOutput(), eventSource: 'Account', namedTags: [new NamedTag('origin', 'trigger')] };
+    }
+}
+@reactor('scenario-named-tags-registered-source-cross-entry')
+class NamedTagCrossEntryReactor {
+    namedTagInput() {
+        return [
+            { eventSourceId: 'tagged', event: new NamedTagOutput(), namedTags: [new NamedTag('origin', 'trigger')] },
+            { eventSourceId: 'registered', event: new NamedTagOutput(), eventSource: 'Account' }
+        ];
+    }
+}
+@reactor('scenario-named-tags-registered-source-cross-entry-reversed')
+class NamedTagCrossEntryReversedReactor {
+    namedTagInput() {
+        return [
+            { eventSourceId: 'registered', event: new NamedTagOutput(), eventSource: 'Account' },
+            { eventSourceId: 'tagged', event: new NamedTagOutput(), namedTags: [new NamedTag('origin', 'trigger')] }
+        ];
+    }
+}
+@reactor('scenario-empty-named-tags-registered-source')
+class EmptyNamedTagsRegisteredSourceReactor {
+    namedTagInput() {
+        return { eventSourceId: 'other', event: new NamedTagOutput(), eventSource: 'Account', namedTags: [] };
+    }
+}
+const artifacts = { eventTypes: [NamedTagInput, NamedTagOutput] };
+
+describe('when recording a side effect with named tags', () => {
+    let scenario: ReactorScenario;
+    beforeEach(async () => {
+        contexts.length = 0;
+        scenario = new ReactorScenario(NamedTagReactor, { artifacts, constraints: 'disabled' });
+        await scenario.when.forEventSource('trigger').events(new NamedTagInput());
+    });
+    it('should record the named tags on the side-effect target', () =>
+        scenario.sideEffects[0].target.namedTags!.map(tag => `${tag.name}=${tag.value}`).should.deep.equal(['origin=trigger']));
+    it('should deliver an empty named tag list like a kernel delivery of an untagged event', () =>
+        contexts[0].namedTags!.should.deep.equal([]));
+});
+
+describe('when recording a side effect with an invalid named tag', () => {
+    let error: unknown;
+    beforeEach(async () => {
+        const scenario = new ReactorScenario(InvalidNamedTagReactor, { artifacts, constraints: 'disabled' });
+        error = await scenario.when.forEventSource('trigger').events(new NamedTagInput()).catch(caught => caught);
+    });
+    it('should fail the delivery with an invalid named tag error, as production append does', () =>
+        (error as Error).should.be.instanceOf(InvalidNamedTag));
+});
+
+for (const [description, reactorType] of [
+    ['the same entry', NamedTagRegisteredSourceReactor],
+    ['a tagged entry before a registered entry', NamedTagCrossEntryReactor],
+    ['a registered entry before a tagged entry', NamedTagCrossEntryReversedReactor]
+] as const) {
+    describe(`when recording named tags and a registered source in ${description}`, () => {
+        let scenario: ReactorScenario;
+        let error: unknown;
+        beforeEach(async () => {
+            scenario = new ReactorScenario(reactorType, { artifacts, constraints: 'disabled' });
+            error = await scenario.when.forEventSource('trigger').events(new NamedTagInput()).catch(caught => caught);
+        });
+        it('should reject with the production unsupported combination error', () =>
+            (error as Error).should.be.instanceOf(NamedTagsWithRegisteredEventSourceNotSupported));
+        it('should record an unsuccessful delivery', () => scenario.results[0].completed.should.be.false);
+        it('should retain the rejection on the delivery result', () => scenario.results[0].error!.should.equal(error));
+        it('should not record any returned side effect', () => scenario.sideEffects.should.have.lengthOf(0));
+        it('should not report any produced event', () => scenario.produced.should.have.lengthOf(0));
+    });
+}
+
+describe('when recording a registered source with empty named tags', () => {
+    let scenario: ReactorScenario;
+    beforeEach(async () => {
+        scenario = new ReactorScenario(EmptyNamedTagsRegisteredSourceReactor, { artifacts, constraints: 'disabled' });
+        await scenario.when.forEventSource('trigger').events(new NamedTagInput());
+    });
+    it('should complete the delivery', () => scenario.results[0].completed.should.be.true);
+    it('should retain the registered source on the recorded effect', () => scenario.sideEffects[0].target.eventSource!.should.equal('Account'));
+    it('should retain the empty named tag array', () => scenario.sideEffects[0].target.namedTags!.should.deep.equal([]));
+});

package/testing/for_ReadModelScenario/when_seeding_with_options/with_named_tags.spec.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { NamedTag } from '../../../events/index.js';
+import { reducer } from '../../../reducers/reducer.js';
+import { ReadModelScenario, UnsupportedEventSequenceOperation } from '../../index.js';
+import { Claim, rejection } from '../../for_EventScenario/given/routed_scenario.fixture.js';
+
+chai.should();
+class Count { claimed = 0; }
+class Counter { claim(_event: Claim, current: Count | undefined): Count { return { claimed: (current?.claimed ?? 0) + 1 }; } }
+reducer('NamedTagSetupCounter', undefined, Count)(Counter);
+const create = () => new ReadModelScenario(Count, { eventTypes: [Claim], reducers: [Counter], projections: [] });
+
+describe('when read-model setup receives non-empty named tags', () => {
+    let scenario: ReadModelScenario<Count>;
+    let error: Error;
+    beforeEach(async () => {
+        scenario = create();
+        error = await rejection(() => scenario.given.forEventSource('A', { namedTags: [new NamedTag('batch', 'b-1')] }).events(new Claim('Rejected')));
+    });
+    it('should reject with the typed unsupported operation error', () => error.should.be.instanceOf(UnsupportedEventSequenceOperation));
+    it('should identify the append named tags operation', () => error.message.should.contain('UnsupportedEventSequenceOperation: append.namedTags (Claim)'));
+    it('should not collect the rejected event', async () => ((await scenario.instance) === null).should.be.true);
+});
+
+describe('when read-model setup receives an empty named tag array', () => {
+    let scenario: ReadModelScenario<Count>;
+    beforeEach(() => {
+        scenario = create();
+        scenario.given.forEventSource('A', { namedTags: [] }).events(new Claim('Accepted'));
+    });
+    it('should accept and fold the event', async () => (await scenario.instance)!.claimed.should.equal(1));
+});

package/testing/singleAppendRoute.ts

@@ -4,6 +4,14 @@
 import type { AppendOptions } from '../eventSequences/AppendOptions.js';
 import { UnsupportedEventSequenceOperation } from './UnsupportedEventSequenceOperation.js';
 
+/**
+ * Whether a named-tag option asks for anything. An explicitly empty array carries no tags, exactly like an
+ * omitted option; anything else is reported, including malformed values the production client would reject.
+ */
+export function hasNamedTags(namedTags: unknown): boolean {
+    return namedTags !== undefined && !(Array.isArray(namedTags) && namedTags.length === 0);
+}
+
 /** The fixture-proven single-append route boundary, shared with read-model setup. */
 export function singleAppendRoute(options: AppendOptions | undefined, artifact: string,
     unsupported = (operation: string, artifact: string, reason: string) => new UnsupportedEventSequenceOperation(operation, artifact, reason),
@@ -12,8 +20,12 @@ export function singleAppendRoute(options: AppendOptions | undefined, artifact:
     if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) {
         throw unsupported('append.options', artifact, 'Append options must be an object.');
     }
+    if (options && hasNamedTags(options.namedTags)) {
+        throw unsupported('append.namedTags', artifact, 'Named tags are not fixture-backed.');
+    }
     const allowed = ['sourceType', 'streamType', 'streamId', ...(allowSubject ? ['subject'] : [])];
-    if (options && (Reflect.ownKeys(options).some(key => !allowed.includes(String(key))) ||
+    // An explicitly empty namedTags array is accepted (checked above) but not advertised as a supported option.
+    if (options && (Reflect.ownKeys(options).some(key => key !== 'namedTags' && !allowed.includes(String(key))) ||
         options.correlationId !== undefined || (!allowSubject && options.subject !== undefined) || options.occurred !== undefined ||
         options.eventSourceId !== undefined || options.concurrencyScope !== undefined || options.tags !== undefined ||
         options.concurrencyScopes !== undefined)) {

package/transactions/IUnitOfWork.ts

@@ -6,7 +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 type { TransactionalAppendOptions } from './TransactionalAppendOptions.js';
 import { AppendResult } from '../eventSequences/AppendResult.js';
 
 /**
@@ -27,9 +27,10 @@ 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.
+     * @param options - Optional registered event source / stream routing and named tags for this event.
+     * @throws {@link InvalidNamedTag} when a named tag is invalid; the event is not added.
      */
-    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object, routing?: TransactionalEventRouting): void;
+    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object, options?: TransactionalAppendOptions): void;
 
     /**
      * Gets all events currently buffered in this unit of work.

package/transactions/TransactionalAppendOptions.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { NamedTag } from '../events/NamedTag.js';
+import type { TransactionalEventRouting } from './TransactionalEventRouting.js';
+
+/**
+ * Optional metadata for an event added to a unit of work: registered event source routing and
+ * structured named tags. Carried through to the append on commit.
+ */
+export interface TransactionalAppendOptions extends TransactionalEventRouting {
+    /**
+     * Structured named tags for the event. Validated when the event is added, so an invalid tag fails
+     * before anything is committed; the first occurrence of each exact name and value pair is kept.
+     */
+    readonly namedTags?: ReadonlyArray<NamedTag>;
+}

package/transactions/UnitOfWork.ts

@@ -9,8 +9,10 @@ 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 { ensureNamedTagBatchIsSupported } from '../eventSequences/ensureNamedTagBatchIsSupported.js';
 import { IEventStore } from '../IEventStore.js';
-import { TransactionalEventRouting } from './TransactionalEventRouting.js';
+import type { TransactionalAppendOptions } from './TransactionalAppendOptions.js';
+import { mergeNamedTags } from '../events/mergeNamedTags.js';
 import { IUnitOfWork } from './IUnitOfWork.js';
 
 interface EventForEventSourceIdWithSequenceNumber {
@@ -48,16 +50,18 @@ export class UnitOfWork implements IUnitOfWork {
     }
 
     /** @inheritdoc */
-    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object, routing?: TransactionalEventRouting): void {
+    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object, options?: TransactionalAppendOptions): void {
         this.throwIfCompleted();
+        const namedTags = mergeNamedTags(options?.namedTags);
         this._events.push({
             sequenceNumber: this._events.length,
             eventSequenceId,
             eventForEventSourceId: {
                 eventSourceId,
                 event,
-                ...(routing?.eventSource !== undefined ? { eventSource: routing.eventSource } : {}),
-                ...(routing?.eventStream !== undefined ? { eventStream: routing.eventStream } : {})
+                ...(options?.eventSource !== undefined ? { eventSource: options.eventSource } : {}),
+                ...(options?.eventStream !== undefined ? { eventStream: options.eventStream } : {}),
+                ...(namedTags.length > 0 ? { namedTags } : {})
             }
         });
     }
@@ -94,6 +98,11 @@ export class UnitOfWork implements IUnitOfWork {
         this.throwIfCompleted();
 
         if (this._events.length > 0) {
+            // Validate the entire commit before writing any sequence, including combinations in different groups.
+            ensureNamedTagBatchIsSupported(
+                this._events.some(entry => (entry.eventForEventSourceId.namedTags?.length ?? 0) > 0),
+                this._events.some(entry => entry.eventForEventSourceId.eventSource !== undefined)
+            );
             const resultsBySequenceNumber = new Map<number, AppendResult>();
             const eventsByEventSequence = new Map<string, EventForEventSourceIdWithSequenceNumber[]>();
 

package/transactions/for_UnitOfWork/when_committing_events_with_named_tags.spec.ts

@@ -0,0 +1,112 @@
+// 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 { InvalidNamedTag, NamedTag } from '../../events/index.js';
+import { EventSequenceId, NamedTagsWithRegisteredEventSourceNotSupported, type EventForEventSourceId } from '../../eventSequences/index.js';
+import { ConcurrencyDimensions, type IEventSources } from '../../eventSources/index.js';
+import type { IEventStore } from '../../IEventStore.js';
+import { UnitOfWork } from '../UnitOfWork.js';
+
+const should = chai.should();
+const success = { isSuccess: true, constraintViolations: [], errors: [] };
+
+class Account {}
+const eventSources = {
+    getFor: () => ({ type: Account, name: 'Account', description: '', concurrency: ConcurrencyDimensions.none, streams: [] })
+} as unknown as IEventSources;
+
+function a_unit_of_work() {
+    const appendMany = vi.fn().mockImplementation(async (events: EventForEventSourceId[]) => events.map(() => success));
+    const completed = vi.fn();
+    const unitOfWork = new UnitOfWork(Guid.create(), completed, { eventSources, getEventSequence: () => ({ appendMany }) } as unknown as IEventStore);
+    return { unitOfWork, appendMany, completed };
+}
+
+describe('when committing events with named tags in a unit of work', () => {
+    let batch: EventForEventSourceId[];
+    beforeEach(async () => {
+        const { unitOfWork, appendMany } = a_unit_of_work();
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { first: 1 },
+            { namedTags: [new NamedTag('batch', 'b-1'), new NamedTag('batch', 'b-1')] });
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-2', { second: 2 }, { namedTags: [] });
+        await unitOfWork.commit();
+        batch = appendMany.mock.calls[0][0];
+    });
+    it('should carry the distinct named tags on the event they were added with', () =>
+        batch[0].namedTags!.map(tag => `${tag.name}=${tag.value}`).should.deep.equal(['batch=b-1']));
+    it('should not add named tags to an event added with none', () => should.not.exist(batch[1].namedTags));
+});
+
+describe('when adding an event with an invalid named tag to a unit of work', () => {
+    let error: unknown;
+    let unitOfWork: UnitOfWork;
+    beforeEach(() => {
+        ({ unitOfWork } = a_unit_of_work());
+        try {
+            unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', {}, { namedTags: [{ name: ' ', value: 'x' } as NamedTag] });
+        } catch (caught) {
+            error = caught;
+        }
+    });
+    it('should fail with an invalid named tag error', () => (error as Error).should.be.instanceOf(InvalidNamedTag));
+    it('should not buffer the event', () => unitOfWork.getEvents().should.have.lengthOf(0));
+});
+
+for (const separateSequences of [false, true]) {
+    describe(`when committing named tags and a registered source in ${separateSequences ? 'different event sequences' : 'one batch'}`, () => {
+        let calls: ReturnType<typeof a_unit_of_work>;
+        let error: unknown;
+        beforeEach(async () => {
+            calls = a_unit_of_work();
+            // An otherwise valid group must not be written before a later unsupported combination is found.
+            calls.unitOfWork.addEvent(EventSequenceId.eventLog, 'plain', { first: 1 });
+            const sequenceId = separateSequences ? new EventSequenceId('other') : EventSequenceId.eventLog;
+            calls.unitOfWork.addEvent(sequenceId, 'tagged', { second: 2 }, { namedTags: [new NamedTag('batch', 'b-1')] });
+            calls.unitOfWork.addEvent(sequenceId, 'registered', { third: 3 }, { eventSource: Account });
+            error = await calls.unitOfWork.commit().catch(caught => caught);
+        });
+        it('should reject with the typed unsupported combination error', () =>
+            (error as Error).should.be.instanceOf(NamedTagsWithRegisteredEventSourceNotSupported));
+        it('should not write any group', () => calls.appendMany.mock.calls.should.have.lengthOf(0));
+        it('should leave the unit of work uncompleted', () => calls.unitOfWork.isCompleted.should.be.false);
+        it('should not invoke completion callbacks', () => calls.completed.mock.calls.should.have.lengthOf(0));
+        it('should retain the buffered events for rollback', () => calls.unitOfWork.getEvents().should.have.lengthOf(3));
+    });
+}
+
+describe('when committing tags and registered sources on different event sequences', () => {
+    let calls: ReturnType<typeof a_unit_of_work>;
+    let error: unknown;
+    beforeEach(async () => {
+        calls = a_unit_of_work();
+        calls.unitOfWork.addEvent(EventSequenceId.eventLog, 'tagged', {}, { namedTags: [new NamedTag('batch', 'b-1')] });
+        calls.unitOfWork.addEvent(new EventSequenceId('other'), 'registered', {}, { eventSource: 'Account' });
+        error = await calls.unitOfWork.commit().catch(caught => caught);
+    });
+    it('should reject the entire commit', () => (error as Error).should.be.instanceOf(NamedTagsWithRegisteredEventSourceNotSupported));
+    it('should not append the first event sequence', () => calls.appendMany.mock.calls.should.have.lengthOf(0));
+});
+
+describe('when committing a registered source and named tags on one event', () => {
+    let error: unknown;
+    beforeEach(async () => {
+        const { unitOfWork } = a_unit_of_work();
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'registered', {}, { eventSource: 'Account', namedTags: [new NamedTag('batch', 'b-1')] });
+        error = await unitOfWork.commit().catch(caught => caught);
+    });
+    it('should reject with the typed unsupported combination error', () =>
+        (error as Error).should.be.instanceOf(NamedTagsWithRegisteredEventSourceNotSupported));
+});
+
+describe('when committing a registered source with an empty named tag array', () => {
+    let calls: ReturnType<typeof a_unit_of_work>;
+    beforeEach(async () => {
+        calls = a_unit_of_work();
+        calls.unitOfWork.addEvent(EventSequenceId.eventLog, 'registered', {}, { eventSource: 'Account', namedTags: [] });
+        await calls.unitOfWork.commit();
+    });
+    it('should append the registered source', () => calls.appendMany.mock.calls[0][0][0].eventSource.should.equal('Account'));
+    it('should complete the unit of work', () => calls.unitOfWork.isCompleted.should.be.true);
+});

package/transactions/index.ts

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