@cratis/chronicle 3.0.0 → 3.1.0

package/reactors/ReactorSideEffects.spec.ts

@@ -0,0 +1,182 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it, vi } from 'vitest';
+import type { IEventLog } from '../eventSequences/IEventLog';
+import { EventSequenceNumber } from '../eventSequences/EventSequenceNumber';
+import { eventType } from '../events/eventTypeDecorator';
+import { appendReactorSideEffects } from './ReactorSideEffects';
+
+class SomethingHappened {
+    constructor(readonly value: string = '') {}
+}
+eventType('c3f6a2f0-6f2f-4a3c-9d3f-6f2f4a3c9d3h')(SomethingHappened);
+
+class SomethingElseHappened {
+    constructor(readonly value: string = '') {}
+}
+eventType('d3f6a2f0-6f2f-4a3c-9d3f-6f2f4a3c9d3i')(SomethingElseHappened);
+
+function createEventLog(appendManyResult?: unknown) {
+    const appendMany = vi.fn().mockResolvedValue(appendManyResult ?? [
+        { sequenceNumber: new EventSequenceNumber(1n), constraintViolations: [], errors: [], isSuccess: true }
+    ]);
+    const eventLog = { appendMany } as unknown as IEventLog;
+    return { eventLog, appendMany };
+}
+
+const successResultFor = (count: number) =>
+    Array.from({ length: count }, (_, index) => ({
+        sequenceNumber: new EventSequenceNumber(BigInt(index + 1)),
+        constraintViolations: [],
+        errors: [],
+        isSuccess: true
+    }));
+
+describe('appendReactorSideEffects', () => {
+    describe('when the handler returns undefined', () => {
+        const { eventLog, appendMany } = createEventLog();
+
+        it('should not append anything', async () => {
+            const result = await appendReactorSideEffects(eventLog, undefined, 'triggering-source', 'Default', 'triggering-source');
+
+            expect(appendMany).not.toHaveBeenCalled();
+            expect(result.isSuccess).toBe(true);
+            expect(result.errors).toEqual([]);
+        });
+    });
+
+    describe('when the handler returns a single bare event', () => {
+        const { eventLog, appendMany } = createEventLog(successResultFor(1));
+
+        it('should append it targeting the triggering event\'s event source, stream, and subject', async () => {
+            const result = await appendReactorSideEffects(
+                eventLog,
+                new SomethingHappened('a'),
+                'triggering-source',
+                'custom-stream-type',
+                'custom-stream-id');
+
+            expect(appendMany).toHaveBeenCalledTimes(1);
+            const [events] = appendMany.mock.calls[0];
+            expect(events).toEqual([{
+                eventSourceId: 'triggering-source',
+                event: expect.any(SomethingHappened),
+                eventStreamType: 'custom-stream-type',
+                eventStreamId: 'custom-stream-id',
+                subject: 'triggering-source'
+            }]);
+            expect(result.isSuccess).toBe(true);
+        });
+    });
+
+    describe('when the handler returns an array of bare events', () => {
+        const { eventLog, appendMany } = createEventLog(successResultFor(2));
+
+        it('should append all of them in a single atomic AppendMany call', async () => {
+            await appendReactorSideEffects(
+                eventLog,
+                [new SomethingHappened('a'), new SomethingElseHappened('b')],
+                'triggering-source',
+                'Default',
+                'triggering-source');
+
+            expect(appendMany).toHaveBeenCalledTimes(1);
+            const [events] = appendMany.mock.calls[0];
+            expect(events).toHaveLength(2);
+            expect(events[0].event).toBeInstanceOf(SomethingHappened);
+            expect(events[1].event).toBeInstanceOf(SomethingElseHappened);
+        });
+    });
+
+    describe('when the handler returns a single EventForEventSourceId', () => {
+        const { eventLog, appendMany } = createEventLog(successResultFor(1));
+
+        it('should append it using its own target rather than the triggering event\'s', async () => {
+            const wrapper = {
+                eventSourceId: 'other-source',
+                event: new SomethingHappened('a'),
+                eventStreamType: 'other-stream-type',
+                eventStreamId: 'other-stream-id',
+                subject: 'other-subject'
+            };
+
+            await appendReactorSideEffects(eventLog, wrapper, 'triggering-source', 'Default', 'triggering-source');
+
+            expect(appendMany).toHaveBeenCalledTimes(1);
+            const [events] = appendMany.mock.calls[0];
+            expect(events).toEqual([wrapper]);
+        });
+    });
+
+    describe('when the handler returns an array of EventForEventSourceId', () => {
+        const { eventLog, appendMany } = createEventLog(successResultFor(2));
+
+        it('should append all of them, each keeping its own target, in one atomic call', async () => {
+            const wrappers = [
+                { eventSourceId: 'source-1', event: new SomethingHappened('a') },
+                { eventSourceId: 'source-2', event: new SomethingElseHappened('b') }
+            ];
+
+            await appendReactorSideEffects(eventLog, wrappers, 'triggering-source', 'Default', 'triggering-source');
+
+            expect(appendMany).toHaveBeenCalledTimes(1);
+            const [events] = appendMany.mock.calls[0];
+            expect(events).toEqual(wrappers);
+        });
+    });
+
+    describe('when the handler returns a mix of bare events and EventForEventSourceId', () => {
+        const { eventLog, appendMany } = createEventLog(successResultFor(2));
+
+        it('should append the bare event using the triggering context and the wrapper using its own, in one atomic call', async () => {
+            const wrapper = { eventSourceId: 'other-source', event: new SomethingElseHappened('b') };
+            const bareEvent = new SomethingHappened('a');
+
+            await appendReactorSideEffects(eventLog, [bareEvent, wrapper], 'triggering-source', 'Default', 'triggering-source');
+
+            expect(appendMany).toHaveBeenCalledTimes(1);
+            const [events] = appendMany.mock.calls[0];
+            expect(events).toEqual([
+                {
+                    eventSourceId: 'triggering-source',
+                    event: bareEvent,
+                    eventStreamType: 'Default',
+                    eventStreamId: 'triggering-source',
+                    subject: 'triggering-source'
+                },
+                wrapper
+            ]);
+        });
+    });
+
+    describe('when a side-effect event fails to append', () => {
+        const { eventLog, appendMany } = createEventLog([
+            {
+                sequenceNumber: EventSequenceNumber.unset,
+                constraintViolations: [{ constraintId: 'unique', message: 'Value must be unique', details: {} }],
+                errors: [],
+                isSuccess: false
+            }
+        ]);
+
+        it('should report failure with the constraint violation message', async () => {
+            const result = await appendReactorSideEffects(eventLog, new SomethingHappened('a'), 'triggering-source', 'Default', 'triggering-source');
+
+            expect(appendMany).toHaveBeenCalledTimes(1);
+            expect(result.isSuccess).toBe(false);
+            expect(result.errors).toEqual(['Value must be unique']);
+        });
+    });
+
+    describe('when the handler returns a plain object that is not a known event type or EventForEventSourceId', () => {
+        const { eventLog, appendMany } = createEventLog();
+
+        it('should ignore it and not append anything', async () => {
+            const result = await appendReactorSideEffects(eventLog, { some: 'value' }, 'triggering-source', 'Default', 'triggering-source');
+
+            expect(appendMany).not.toHaveBeenCalled();
+            expect(result.isSuccess).toBe(true);
+        });
+    });
+});

package/reactors/ReactorSideEffects.ts

@@ -0,0 +1,97 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { hasEventType } from '../events/eventTypeDecorator';
+import type { EventForEventSourceId } from '../eventSequences/EventForEventSourceId';
+import type { IEventLog } from '../eventSequences/IEventLog';
+
+/**
+ * Represents the outcome of appending a reactor handler's returned side-effect events.
+ */
+export interface ReactorSideEffectResult {
+    /** Whether every side-effect event appended successfully. */
+    readonly isSuccess: boolean;
+
+    /** Constraint violation and error messages, populated when {@link isSuccess} is false. */
+    readonly errors: string[];
+}
+
+const noSideEffects: ReactorSideEffectResult = { isSuccess: true, errors: [] };
+
+/**
+ * Determines whether a value is shaped like an {@link EventForEventSourceId} — a plain object
+ * carrying its own `eventSourceId` and `event` — rather than an event object returned directly.
+ */
+function isEventForEventSourceId(value: unknown): value is EventForEventSourceId {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+
+    const candidate = value as Record<string, unknown>;
+    return typeof candidate.eventSourceId === 'string' &&
+        typeof candidate.event === 'object' && candidate.event !== null &&
+        hasEventType((candidate.event as object).constructor as Function);
+}
+
+/**
+ * Appends the events a `@reactor`-decorated class's handler method returned as side effects, in
+ * a single atomic `AppendMany` call — never one append per item, which would neither be atomic
+ * nor efficient.
+ * @param eventLog - The {@link IEventLog} to append the side effects to.
+ * @param handlerResult - Whatever the reactor handler method returned: `undefined`/`void`, a
+ * single event object, an array of events, a single {@link EventForEventSourceId}, an array of
+ * them, or a mix of bare events and {@link EventForEventSourceId} entries.
+ * @param triggeringEventSourceId - The event source id of the event that triggered the reactor,
+ * used as the target for bare event returns.
+ * @param triggeringEventStreamType - The event stream type of the triggering event, used for bare
+ * event returns.
+ * @param triggeringEventStreamId - The event stream identifier of the triggering event, used for
+ * bare event returns.
+ * @returns The outcome of the append. Each {@link EventForEventSourceId} entry keeps its own
+ * target (event source id, stream type/id, subject); bare events use the triggering event's.
+ */
+export async function appendReactorSideEffects(
+    eventLog: IEventLog,
+    handlerResult: unknown,
+    triggeringEventSourceId: string,
+    triggeringEventStreamType: string,
+    triggeringEventStreamId: string
+): Promise<ReactorSideEffectResult> {
+    if (handlerResult === undefined || handlerResult === null) {
+        return noSideEffects;
+    }
+
+    const items = Array.isArray(handlerResult) ? handlerResult : [handlerResult];
+    const events: EventForEventSourceId[] = [];
+
+    for (const item of items) {
+        if (isEventForEventSourceId(item)) {
+            events.push(item);
+        } else if (typeof item === 'object' && item !== null && hasEventType(item.constructor as Function)) {
+            events.push({
+                eventSourceId: triggeringEventSourceId,
+                event: item,
+                eventStreamType: triggeringEventStreamType,
+                eventStreamId: triggeringEventStreamId,
+                subject: triggeringEventSourceId
+            });
+        }
+        // Anything else — undefined array entries, plain objects that are neither a registered
+        // event type nor EventForEventSourceId-shaped — is not a recognized side-effect and is
+        // silently ignored, the same as a handler that returns Task/void.
+    }
+
+    if (events.length === 0) {
+        return noSideEffects;
+    }
+
+    const results = await eventLog.appendMany(events);
+    const errors = results
+        .filter(result => !result.isSuccess)
+        .flatMap(result => [
+            ...result.constraintViolations.map(violation => violation.message),
+            ...result.errors.map(error => error.message)
+        ]);
+
+    return { isSuccess: errors.length === 0, errors };
+}

package/reactors/Reactors.ts

@@ -13,7 +13,10 @@ import { EventContext } from '../events/EventContext';
 import { EventTypeId } from '../events/EventTypeId';
 import { EventTypeGeneration } from '../events/EventTypeGeneration';
 import { EventSequenceId } from '../eventSequences/EventSequenceId';
+import type { IEventLog } from '../eventSequences/IEventLog';
+import { notifyReplayLifecycle } from '../observation/notifyReplayLifecycle';
 import { IReactors } from './IReactors';
+import { appendReactorSideEffects } from './ReactorSideEffects';
 import { getReactorMetadata } from './reactor';
 
 /** Expression used to partition reactor observations by event source ID. */
@@ -107,13 +110,15 @@ export class Reactors implements IReactors {
      * @param _eventStoreName - The name of the event store.
      * @param _namespace - The namespace within the event store.
      * @param lifecycle - The connection lifecycle used to react to disconnect events.
+     * @param _eventLog - The event log used to append side-effect events a reactor handler returns.
      */
     constructor(
         private readonly _clientArtifacts: IClientArtifactsProvider,
         private readonly _connection: ChronicleConnection,
         private readonly _eventStoreName: string,
         private readonly _namespace: string,
-        lifecycle: ConnectionLifecycle
+        lifecycle: ConnectionLifecycle,
+        private readonly _eventLog: IEventLog
     ) {
         this._lifecycle = lifecycle;
         lifecycle.onDisconnected(async () => {
@@ -258,10 +263,20 @@ export class Reactors implements IReactors {
                 this._logger.debug('Received events to observe', {
                     reactorId: id,
                     partition: eventsToObserve.Partition,
-                    count: eventsToObserve.Events.length
+                    count: eventsToObserve.Events.length,
+                    replayState: eventsToObserve.ReplayState
                 });
 
-                for (const event of eventsToObserve.Events) {
+                try {
+                    await notifyReplayLifecycle(reactorInstance, eventsToObserve.ReplayState, eventsToObserve.Partition);
+                } catch (err) {
+                    this._logger.error('Error notifying reactor of replay lifecycle transition', { reactorId: id, error: String(err) });
+                    exceptionMessages.push(String(err));
+                    exceptionStackTrace = err instanceof Error ? (err.stack ?? '') : '';
+                    state = ObservationState.Failed;
+                }
+
+                for (const event of state === ObservationState.Failed ? [] : eventsToObserve.Events) {
                     try {
                         const eventTypeId = event.Context?.EventType?.Id;
                         if (!eventTypeId) {
@@ -298,7 +313,17 @@ export class Reactors implements IReactors {
                             eventTypeId
                         });
 
-                        await reactorInstance[entry.methodName](content, context);
+                        const handlerResult = await reactorInstance[entry.methodName](content, context);
+                        const sideEffectResult = await appendReactorSideEffects(
+                            this._eventLog,
+                            handlerResult,
+                            event.Context!.EventSourceId,
+                            event.Context!.EventStreamType,
+                            event.Context!.EventStreamId);
+                        if (!sideEffectResult.isSuccess) {
+                            throw new Error(`Reactor side effect failed to append: ${sideEffectResult.errors.join('; ')}`);
+                        }
+
                         lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
                     } catch (err) {
                         this._logger.error('Error handling event in reactor', { reactorId: id, error: String(err) });

package/reducers/Reducers.spec.ts

@@ -0,0 +1,87 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it, vi } from 'vitest';
+import type { Constructor } from '@cratis/fundamentals';
+import type { IClientArtifactsProvider } from '../artifacts';
+import type { ChronicleConnection } from '../connection';
+import { ConnectionLifecycle } from '../connection/ConnectionLifecycle';
+import { reducer } from './reducer';
+import { Reducers } from './Reducers';
+
+const flush = () => new Promise(resolve => setTimeout(resolve, 0));
+
+/**
+ * A minimal client artifacts provider exposing only the reducer types under test —
+ * Reducers.ts only reads .reducers and .eventTypes off this during discovery.
+ */
+function createArtifacts(reducers: Constructor[]): IClientArtifactsProvider {
+    return {
+        eventTypes: [],
+        readModels: [],
+        reactors: [],
+        reducers,
+        seeders: [],
+        constraints: [],
+        projections: [],
+        webhooks: [],
+        eventTypeMigrations: []
+    };
+}
+
+/**
+ * Captures the first message a reducer observation pushes onto its queue (the registration
+ * message), by having the mocked `observe` call itself consume the queue's async iterator.
+ */
+function createConnection() {
+    const registrationMessages: unknown[] = [];
+    const observe = vi.fn().mockImplementation(async function* (queue: AsyncIterable<unknown>) {
+        for await (const message of queue) {
+            registrationMessages.push(message);
+            break;
+        }
+    });
+    const registerMany = vi.fn().mockResolvedValue({});
+    const connection = {
+        reducers: { observe },
+        readModels: { registerMany }
+    } as unknown as ChronicleConnection;
+
+    return { connection, registrationMessages };
+}
+
+describe('Reducers', () => {
+    describe('when registering an active reducer (the default)', () => {
+        class SomeReducer {}
+        reducer('some-active-reducer')(SomeReducer);
+
+        it('should send a registration message with IsActive true', async () => {
+            const { connection, registrationMessages } = createConnection();
+            const reducers = new Reducers(createArtifacts([SomeReducer]), connection, 'my-event-store', 'my-namespace', new ConnectionLifecycle(), 'default-sink');
+
+            await reducers.register();
+            await flush();
+
+            expect(registrationMessages).toHaveLength(1);
+            const message = registrationMessages[0] as { Content: { Value0: { Reducer: { IsActive: boolean } } } };
+            expect(message.Content.Value0.Reducer.IsActive).toBe(true);
+        });
+    });
+
+    describe('when registering a passive (isActive: false) reducer', () => {
+        class SomePassiveReducer {}
+        reducer('some-passive-reducer', undefined, undefined, false)(SomePassiveReducer);
+
+        it('should send a registration message with IsActive false', async () => {
+            const { connection, registrationMessages } = createConnection();
+            const reducers = new Reducers(createArtifacts([SomePassiveReducer]), connection, 'my-event-store', 'my-namespace', new ConnectionLifecycle(), 'default-sink');
+
+            await reducers.register();
+            await flush();
+
+            expect(registrationMessages).toHaveLength(1);
+            const message = registrationMessages[0] as { Content: { Value0: { Reducer: { IsActive: boolean } } } };
+            expect(message.Content.Value0.Reducer.IsActive).toBe(false);
+        });
+    });
+});

package/reducers/Reducers.ts

@@ -11,6 +11,7 @@ import { toContractsGuid } from '../connection/Guid';
 import { ConnectionLifecycle } from '../connection/ConnectionLifecycle';
 import { getEventTypeMetadata } from '../events/eventTypeDecorator';
 import { EventSequenceId } from '../eventSequences/EventSequenceId';
+import { notifyReplayLifecycle } from '../observation/notifyReplayLifecycle';
 import { IReducers } from './IReducers';
 import { getReducerMetadata } from './reducer';
 import { getReadModelMetadata } from '../readModels';
@@ -292,6 +293,7 @@ export class Reducers implements IReducers {
     ): Promise<void> {
         const queue = new AsyncQueue<ReducerMessage>();
         this._queues.set(id, queue);
+        const isActive = getReducerMetadata(reducerType)?.isActive ?? true;
 
         queue.send({
             Content: {
@@ -307,7 +309,7 @@ export class Reducers implements IReducers {
                             Key: EVENT_SOURCE_ID_KEY
                         })),
                         ReadModel: readModelName,
-                        IsActive: true,
+                        IsActive: isActive,
                         Tags: [],
                         Filters: {
                             FilterTags: [],
@@ -334,14 +336,24 @@ export class Reducers implements IReducers {
                     reducerId: id,
                     partition: operation.Partition,
                     count: operation.Events.length,
-                    hasInitialState: operation.InitialState !== ''
+                    hasInitialState: operation.InitialState !== '',
+                    replayState: operation.ReplayState
                 });
 
+                try {
+                    await notifyReplayLifecycle(reducerInstance, operation.ReplayState, operation.Partition);
+                } catch (err) {
+                    this._logger.error('Error notifying reducer of replay lifecycle transition', { reducerId: id, error: String(err) });
+                    exceptionMessages.push(String(err));
+                    exceptionStackTrace = err instanceof Error ? (err.stack ?? '') : '';
+                    state = ObservationState.Failed;
+                }
+
                 let currentState: unknown = operation.InitialState
                     ? JSON.parse(operation.InitialState) as unknown
                     : undefined;
 
-                for (const event of operation.Events) {
+                for (const event of state === ObservationState.Failed ? [] : operation.Events) {
                     try {
                         const eventTypeId = event.Context?.EventType?.Id;
                         if (!eventTypeId) {

package/reducers/reducer.spec.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it } from 'vitest';
+import { getReducerMetadata, reducer } from './reducer';
+
+describe('reducer', () => {
+    describe('when decorating a class without specifying isActive', () => {
+        class SomeReducer {}
+        reducer('some-reducer')(SomeReducer);
+
+        it('should default isActive to true', () => {
+            const metadata = getReducerMetadata(SomeReducer);
+
+            expect(metadata?.isActive).toBe(true);
+        });
+    });
+
+    describe('when decorating a class with isActive explicitly true', () => {
+        class SomeActiveReducer {}
+        reducer('some-active-reducer', undefined, undefined, true)(SomeActiveReducer);
+
+        it('should set isActive to true', () => {
+            const metadata = getReducerMetadata(SomeActiveReducer);
+
+            expect(metadata?.isActive).toBe(true);
+        });
+    });
+
+    describe('when decorating a class with isActive false', () => {
+        class SomePassiveReducer {}
+        reducer('some-passive-reducer', undefined, undefined, false)(SomePassiveReducer);
+
+        it('should set isActive to false', () => {
+            const metadata = getReducerMetadata(SomePassiveReducer);
+
+            expect(metadata?.isActive).toBe(false);
+        });
+    });
+});

package/reducers/reducer.ts

@@ -21,6 +21,13 @@ export interface ReducerMetadata {
 
     /** The optional read model type produced by the reducer. */
     readonly readModel: Constructor | undefined;
+
+    /**
+     * Whether the reducer is active. An inactive (passive) reducer is registered with the
+     * Chronicle Kernel but does not automatically observe events — it can still be invoked
+     * on demand. Defaults to true.
+     */
+    readonly isActive: boolean;
 }
 
 /**
@@ -34,6 +41,8 @@ export interface ReducerMetadata {
  * @param id - The unique identifier for the reducer. Defaults to the class name if omitted.
  * @param eventSequenceId - Optional explicit event sequence identifier.
  * @param readModel - Optional read model type produced by the reducer.
+ * @param isActive - Whether the reducer is active (automatically observes events). Defaults to true.
+ * A passive reducer is registered but must be invoked on demand rather than observing automatically.
  * @returns A class decorator.
  *
  * @example
@@ -46,11 +55,11 @@ export interface ReducerMetadata {
  * }
  * ```
  */
-export function reducer(id: string = '', eventSequenceId?: string, readModel?: Constructor): ClassDecorator {
+export function reducer(id: string = '', eventSequenceId?: string, readModel?: Constructor, isActive: boolean = true): ClassDecorator {
     return (target: object) => {
         const constructor = target as Function;
         const reducerId = new ReducerId(id || constructor.name);
-        const metadata: ReducerMetadata = { id: reducerId, eventSequenceId, readModel };
+        const metadata: ReducerMetadata = { id: reducerId, eventSequenceId, readModel, isActive };
         Reflect.defineMetadata(REDUCER_METADATA_KEY, metadata, target);
         TypeDiscoverer.default.register(
             DecoratorType.Reducer,

package/transactions/IUnitOfWork.ts

@@ -2,6 +2,9 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { Guid } from '@cratis/fundamentals';
+import { AppendError } from '../eventSequences/AppendError';
+import { ConcurrencyViolation } from '../eventSequences/ConcurrencyViolation';
+import { ConstraintViolation } from '../eventSequences/ConstraintViolation';
 import { EventSequenceId } from '../eventSequences/EventSequenceId';
 import { AppendResult } from '../eventSequences/AppendResult';
 
@@ -38,6 +41,24 @@ export interface IUnitOfWork {
      */
     getAppendResults(): ReadonlyArray<AppendResult>;
 
+    /**
+     * Gets any constraint violations that occurred across the append results from the latest commit.
+     * @returns A thin filter over {@link getAppendResults}.
+     */
+    getConstraintViolations(): ReadonlyArray<ConstraintViolation>;
+
+    /**
+     * Gets any concurrency violations that occurred across the append results from the latest commit.
+     * @returns A thin filter over {@link getAppendResults}.
+     */
+    getConcurrencyViolations(): ReadonlyArray<ConcurrencyViolation>;
+
+    /**
+     * Gets any errors that occurred while attempting to commit.
+     * @returns A thin filter over {@link getAppendResults}.
+     */
+    getAppendErrors(): ReadonlyArray<AppendError>;
+
     /**
      * Commits all buffered events.
      */