@cratis/chronicle 6.39.0 → 6.41.0

package/testing/for_EventScenario/when_using_routed_builders/with_routing_options.spec.ts

@@ -0,0 +1,116 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it, vi } from 'vitest';
+import type { AppendOptions } from '../../../eventSequences/AppendOptions.js';
+import { Claim, createEvents, rejection, route, routing } from '../given/routed_scenario.fixture.js';
+
+chai.should();
+describe('when seeding with routed builders', () => {
+    it('should record each setup route through single append without action results', async () => {
+        const scenario = createEvents();
+        await scenario.given.forEventSource('A', route).events(new Claim('Alpha'), new Claim('Beta'));
+        scenario.appendedEvents.map(event => routing(event.context)).should.deep.equal([route, route]);
+        scenario.results.should.have.lengthOf(0);
+        (await scenario.append('B', new Claim('Alpha'), route)).isSuccess.should.be.true;
+        (await scenario.append('B', new Claim('Beta'), route)).isSuccess.should.be.false;
+    });
+
+    it('should roll back routed setup and preserve claims in other scopes', async () => {
+        const scenario = createEvents();
+        await scenario.given.forEventSource('A', route).events(new Claim('Taken'));
+        await scenario.given.forEventSource('A').events(new Claim('DefaultKey'));
+        const before = scenario.appendedEvents;
+        await scenario.given.forEventSource('B', route).events(new Claim('Temporary'), new Claim('Taken')).then(
+            () => { throw new Error('Expected failed setup'); }, error => (error as Error).message.should.include('EventScenario given setup failed'));
+        scenario.appendedEvents.should.deep.equal(before);
+        scenario.results.should.have.lengthOf(0);
+        (await scenario.when.forEventSource('C', route).event(new Claim('Temporary'))).sequenceNumber.value.should.equal(2n);
+        (await scenario.when.forEventSource('D').event(new Claim('DefaultKey'))).isSuccess.should.be.false;
+    });
+});
+
+describe('when acting with routed builders', () => {
+    it('should preserve append metadata identically to direct atomic batches', async () => {
+        vi.useFakeTimers({ toFake: ['Date'] });
+        vi.setSystemTime(new Date('2026-01-02T03:04:05.000Z'));
+        try {
+            const scenario = createEvents();
+            const direct = createEvents();
+            const subject = 'CustomerSubject';
+            const correlationId = '11111111-2222-3333-4444-555555555555';
+            const occurred = new Date('2025-12-01T12:34:56.000Z');
+            const tags = ['Priority', 'Routed'];
+            await scenario.when.forEventSource('A', { ...route, subject, correlationId, occurred, tags }).events(new Claim('Alpha'), new Claim('Beta'));
+            await direct.appendMany('A', [new Claim('Alpha'), new Claim('Beta')], { ...route, subject, correlationId, occurred, tags });
+            scenario.appendedEvents.map(event => event.context).should.deep.equal(direct.appendedEvents.map(event => event.context));
+        } finally { vi.useRealTimers(); }
+    });
+
+    it('should use the route for single actions and atomic batches', async () => {
+        const scenario = createEvents();
+        (await scenario.when.forEventSource('A', route).event(new Claim('Alpha'))).isSuccess.should.be.true;
+        const results = await scenario.when.forEventSource('B', { ...route, streamId: 'East' }).events(new Claim('Alpha'), new Claim('Beta'));
+        results.every(result => result.isSuccess).should.be.true;
+        scenario.appendedEvents.map(event => routing(event.context)).should.deep.equal([route,
+            { ...route, streamId: 'East' }, { ...route, streamId: 'East' }]);
+        scenario.results.should.have.lengthOf(3);
+    });
+
+    it('should honor every scoped dimension and reject only the matching route', async () => {
+        const scenario = createEvents();
+        await scenario.given.forEventSource('A', route).events(new Claim('Taken'));
+        for (const dimension of ['sourceType', 'streamType', 'streamId'] as const) {
+            (await scenario.when.forEventSource(`B-${dimension}`, { ...route, [dimension]: 'Other' }).event(new Claim('Taken'))).isSuccess.should.be.true;
+        }
+        const before = scenario.appendedEvents;
+        const results = await scenario.when.forEventSource('C', route).events(new Claim('Temporary'), new Claim('Taken'));
+        results.every(result => !result.isSuccess).should.be.true;
+        scenario.appendedEvents.should.deep.equal(before);
+        (await scenario.when.forEventSource('D', route).event(new Claim('Temporary'))).sequenceNumber.value.should.equal(4n);
+    });
+
+    it('should retain omitted routing and resolve empty strings to exact defaults', async () => {
+        const scenario = createEvents();
+        await scenario.given.forEventSource('A').events(new Claim('Given'));
+        await scenario.given.forEventSource('B', { sourceType: '', streamType: '', streamId: '' }).events(new Claim('Empty'));
+        await scenario.when.forEventSource('C').event(new Claim('Single'));
+        await scenario.when.forEventSource('D', {}).events(new Claim('Batch'));
+        scenario.appendedEvents.map(event => routing(event.context)).should.deep.equal(Array(4).fill({ sourceType: 'Default', streamType: 'All', streamId: 'Default' }));
+        (await scenario.when.forEventSource('E', { streamId: '' }).event(new Claim('Given'))).isSuccess.should.be.false;
+    });
+});
+
+describe('when routed builders receive unsupported options', () => {
+    it('should reject identically to their append path without changing history, results or notifications', async () => {
+        const scenario = createEvents();
+        await scenario.given.forEventSource('A', route).events(new Claim('Taken'));
+        const before = scenario.appendedEvents;
+        const notifications = scenario.eventLog.appendOperations[Symbol.asyncIterator]();
+        const pending = notifications.next();
+        try {
+            const invalid: unknown[] = [null, [], { concurrencyScopes: {} }, { arbitrary: true }];
+            for (const dimension of ['sourceType', 'streamType', 'streamId'] as const) {
+                for (const value of [' ', 'a|b', 'é', '*', 'a:b', 'a\u0000b', 1, null]) invalid.push({ [dimension]: value });
+            }
+            for (const value of invalid) {
+                const options = value as AppendOptions;
+                const single = await rejection(() => scenario.append('B', new Claim('Other'), options));
+                (await rejection(() => scenario.given.forEventSource('B', options).events(new Claim('Other')))).message.should.equal(single.message);
+                (await rejection(() => scenario.when.forEventSource('B', options).event(new Claim('Other')))).message.should.equal(single.message);
+                const batch = await rejection(() => scenario.appendMany('B', [new Claim('Other')], options));
+                (await rejection(() => scenario.when.forEventSource('B', options).events(new Claim('Other')))).message.should.equal(batch.message);
+            }
+            const metadata = { tags: [] };
+            const single = await rejection(() => scenario.append('B', new Claim('Other'), metadata));
+            (await rejection(() => scenario.given.forEventSource('B', metadata).events(new Claim('Other')))).message.should.equal(single.message);
+            (await rejection(() => scenario.when.forEventSource('B', metadata).event(new Claim('Other')))).message.should.equal(single.message);
+            scenario.appendedEvents.should.deep.equal(before);
+            scenario.results.should.have.lengthOf(0);
+            (await scenario.eventLog.getNextSequenceNumber()).value.should.equal(1n);
+            const rejected = await scenario.when.forEventSource('B', route).event(new Claim('Taken'));
+            rejected.isSuccess.should.be.false;
+            (await pending).value![0].result.should.equal(rejected);
+        } finally { await notifications.return?.(); }
+    });
+});

package/testing/for_ReactorScenario/when_using_routed_builders/with_routing_options.spec.ts

@@ -0,0 +1,88 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it } from 'vitest';
+import type { AppendOptions } from '../../../eventSequences/AppendOptions.js';
+import { Claim, Effect, createEvents, createReactor, rejection, route, routing } from '../../for_EventScenario/given/routed_scenario.fixture.js';
+
+chai.should();
+describe('when delivering routed setup and action events', () => {
+    it('should preserve append metadata in handled and triggering contexts', async () => {
+        const scenario = createReactor();
+        const subject = 'CustomerSubject';
+        const correlationId = '11111111-2222-3333-4444-555555555555';
+        const occurred = new Date('2025-12-01T12:34:56.000Z');
+        const tags = ['Priority', 'Routed'];
+        await scenario.when.forEventSource('A', { ...route, subject, correlationId, occurred, tags }).events(new Claim('Alpha'), new Claim('Beta'));
+        const contexts = [...scenario.results.flatMap(result => result.handled), ...scenario.sideEffects.map(effect => effect.triggeringContext)];
+        contexts.map(context => ({ subject: context.subject, correlationId: context.correlationId, occurred: context.occurred,
+            tags: context.tags.map(tag => tag.value) })).should.deep.equal(Array(4).fill({ subject, correlationId, occurred, tags }));
+    });
+
+    it('should expose the recorded route in handled and triggering contexts', async () => {
+        const scenario = createReactor();
+        await scenario.given.forEventSource('A', route).events(new Claim('Given'));
+        await scenario.when.forEventSource('B', { ...route, streamId: 'East' }).events(new Claim('First'), new Claim('Second'));
+        const expected = [route, { ...route, streamId: 'East' }, { ...route, streamId: 'East' }];
+        scenario.appendedEvents.map(event => routing(event.context)).should.deep.equal(expected);
+        scenario.results.flatMap(result => result.handled.map(routing)).should.deep.equal(expected);
+        scenario.sideEffects.map(effect => routing(effect.triggeringContext)).should.deep.equal(expected);
+        scenario.sideEffects.map(effect => effect.triggeringContext).should.deep.equal(scenario.appendedEvents.map(event => event.context));
+        scenario.sideEffects.map(effect => effect.target.eventStreamId).should.deep.equal(['West', 'East', 'East']);
+        scenario.produced.map(effect => (effect as Effect).key).should.deep.equal([
+            'Given:Customer/Orders/West', 'First:Customer/Orders/East', 'Second:Customer/Orders/East']);
+    });
+
+    it('should enforce scoped constraints before delivering any rejected action batch', async () => {
+        const scenario = createReactor();
+        await scenario.given.forEventSource('A', route).events(new Claim('Taken'));
+        await scenario.when.forEventSource('B', { ...route, streamId: 'East' }).events(new Claim('Taken'));
+        const before = scenario.appendedEvents;
+        await scenario.when.forEventSource('C', route).events(new Claim('Temporary'), new Claim('Taken')).then(
+            () => { throw new Error('Expected constraint rejection'); }, error => (error as Error).message.should.include('ReactorScenario action append failed'));
+        scenario.appendedEvents.should.deep.equal(before);
+        scenario.produced.should.have.lengthOf(2);
+        scenario.results.should.have.lengthOf(2);
+        await scenario.when.forEventSource('D', route).events(new Claim('Temporary'));
+        scenario.appendedEvents[2].context.sequenceNumber.should.equal(2n);
+    });
+
+    it('should roll back rejected routed setup before recording effects or delivery outcomes', async () => {
+        const scenario = createReactor();
+        await scenario.given.forEventSource('A', route).events(new Claim('Taken'));
+        await scenario.given.forEventSource('B', route).events(new Claim('Temporary'), new Claim('Taken')).then(
+            () => { throw new Error('Expected failed setup'); }, error => (error as Error).message.should.include('EventScenario given setup failed'));
+        scenario.appendedEvents.should.have.lengthOf(1);
+        scenario.produced.should.have.lengthOf(1);
+        scenario.results.should.have.lengthOf(1);
+        await scenario.when.forEventSource('C', route).events(new Claim('Temporary'));
+        scenario.appendedEvents[1].context.sequenceNumber.should.equal(1n);
+    });
+
+    it('should keep default routing for omitted and empty route options', async () => {
+        const scenario = createReactor();
+        await scenario.given.forEventSource('A').events(new Claim('Given'));
+        await scenario.when.forEventSource('B', { sourceType: '', streamType: '', streamId: '' }).events(new Claim('Action'));
+        scenario.results.flatMap(result => result.handled.map(routing)).should.deep.equal(Array(2).fill({ sourceType: 'Default', streamType: 'All', streamId: 'Default' }));
+    });
+});
+
+describe('when reactor builders receive unsupported routing', () => {
+    it('should reject through append validation without delivering or poisoning the next action', async () => {
+        const scenario = createReactor();
+        const direct = createEvents();
+        for (const value of [null, [], { sourceType: 1 }, { streamType: 'a|b' }, { streamId: ' ' }, { arbitrary: true }]) {
+            const options = value as AppendOptions;
+            const single = await rejection(() => direct.append('A', new Claim('Other'), options));
+            (await rejection(() => scenario.given.forEventSource('A', options).events(new Claim('Other')))).message.should.equal(single.message);
+            const batch = await rejection(() => direct.appendMany('A', [new Claim('Other')], options));
+            (await rejection(() => scenario.when.forEventSource('A', options).events(new Claim('Other')))).message.should.equal(batch.message);
+        }
+        scenario.appendedEvents.should.have.lengthOf(0);
+        scenario.results.should.have.lengthOf(0);
+        scenario.sideEffects.should.have.lengthOf(0);
+        await scenario.when.forEventSource('A', route).events(new Claim('Accepted'));
+        scenario.appendedEvents[0].context.sequenceNumber.should.equal(0n);
+        scenario.results[0].completed.should.be.true;
+    });
+});

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

@@ -0,0 +1,42 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it } from 'vitest';
+import type { AppendOptions } from '../../../eventSequences/AppendOptions.js';
+import { reducer } from '../../../reducers/reducer.js';
+import { ReadModelScenario, UnsupportedProjectionOperation } from '../../index.js';
+import { Claim, createEvents, rejection, route } 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('BuilderRouteCounter', undefined, Count)(Counter);
+const create = () => new ReadModelScenario(Count, { eventTypes: [Claim], reducers: [Counter], projections: [] });
+
+describe('when read-model setup receives route options', () => {
+    it('should preserve default setup with omitted, explicit or empty defaults', async () => {
+        const scenario = create();
+        scenario.given.forEventSource('A').events(new Claim('First'));
+        scenario.given.forEventSource('A', { sourceType: '', streamType: '', streamId: '' }).events(new Claim('Second'));
+        scenario.given.forEventSource('A', { sourceType: 'Default', streamType: 'All', streamId: 'Default' }).events(new Claim('Third'));
+        (await scenario.instance)!.claimed.should.equal(3);
+    });
+
+    it('should reuse single-append rejection messages without collecting unsupported input', async () => {
+        const scenario = create();
+        const events = createEvents();
+        for (const value of [{ sourceType: ' ' }, { streamType: null }, { streamId: 1 }, { tags: [] }, { arbitrary: true }, null, []]) {
+            const options = value as AppendOptions;
+            const error = await rejection(() => events.append('A', new Claim('Other'), options));
+            (await rejection(() => scenario.given.forEventSource('A', options).events(new Claim('Other')))).message.should.equal(error.message);
+        }
+        ((await scenario.instance) === null).should.be.true;
+    });
+
+    it('should retain the unproven routed read-model boundary instead of simulating projection routing', async () => {
+        const scenario = create();
+        (() => scenario.given.forEventSource('A', route).events(new Claim('Other'))).should.throw(UnsupportedProjectionOperation, 'routed events');
+        scenario.given.forEventSource('A').events(new Claim('Accepted'));
+        (await scenario.instance)!.claimed.should.equal(1);
+    });
+});

package/testing/singleAppendRoute.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 type { AppendOptions } from '../eventSequences/AppendOptions.js';
+import { UnsupportedEventSequenceOperation } from './UnsupportedEventSequenceOperation.js';
+
+/** 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)
+): { sourceType: string; streamType: string; streamId: string } {
+    if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) {
+        throw unsupported('append.options', artifact, 'Append options must be an object.');
+    }
+    if (options && (Reflect.ownKeys(options).some(key => !['sourceType', 'streamType', 'streamId'].includes(String(key))) ||
+        options.correlationId !== undefined || options.subject !== undefined || options.occurred !== undefined ||
+        options.eventSourceId !== undefined || options.concurrencyScope !== undefined || options.tags !== undefined ||
+        options.concurrencyScopes !== undefined)) {
+        throw unsupported('append.options', artifact, 'Only sourceType, streamType and streamId routing options are fixture-backed for single append.');
+    }
+    const route = { sourceType: options?.sourceType, streamType: options?.streamType, streamId: options?.streamId };
+    for (const [name, value] of Object.entries(route)) {
+        if (value !== undefined && (typeof value !== 'string' || !/^[A-Za-z0-9_-]*$/.test(value))) {
+            throw unsupported(`append.${name}`, String(value), 'Only simple routing identifiers or empty defaults are fixture-backed.');
+        }
+    }
+    // ts-proto omits empty strings; the append pipeline resolves omissions to these exact values.
+    return { sourceType: route.sourceType || 'Default', streamType: route.streamType || 'All', streamId: route.streamId || 'Default' };
+}