@cratis/chronicle 3.0.0 → 3.1.1

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.
      */

package/transactions/UnitOfWork.spec.ts

@@ -0,0 +1,82 @@
+// 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 { Guid } from '@cratis/fundamentals';
+import type { AppendResult } from '../eventSequences/AppendResult';
+import { EventSequenceId } from '../eventSequences/EventSequenceId';
+import { EventSequenceNumber } from '../eventSequences/EventSequenceNumber';
+import type { IEventSequence } from '../eventSequences/IEventSequence';
+import type { IEventStore } from '../IEventStore';
+import { UnitOfWork } from './UnitOfWork';
+
+function createAppendResult(overrides: Partial<AppendResult> = {}): AppendResult {
+    return {
+        sequenceNumber: EventSequenceNumber.first,
+        constraintViolations: [],
+        errors: [],
+        isSuccess: true,
+        waitForCompletion: vi.fn(),
+        ...overrides
+    };
+}
+
+function createUnitOfWork(appendManyResult: AppendResult[]) {
+    const appendMany = vi.fn().mockResolvedValue(appendManyResult);
+    const eventSequence = { appendMany } as unknown as IEventSequence;
+    const eventStore = { getEventSequence: vi.fn().mockReturnValue(eventSequence) } as unknown as IEventStore;
+    const unitOfWork = new UnitOfWork(Guid.create(), vi.fn(), eventStore);
+    return { unitOfWork, eventStore };
+}
+
+class SomethingHappened {
+    constructor(readonly value: string = '') {}
+}
+
+describe('UnitOfWork', () => {
+    describe('when filtering violations after a commit', () => {
+        const constraintViolation = { constraintId: 'unique', message: 'Value must be unique', details: {} };
+        const concurrencyViolation = {
+            eventSourceId: 'some-event-source',
+            expectedSequenceNumber: new EventSequenceNumber(1n),
+            actualSequenceNumber: new EventSequenceNumber(2n)
+        };
+        const appendError = { message: 'Something went wrong' };
+
+        const { unitOfWork } = createUnitOfWork([
+            createAppendResult({ constraintViolations: [constraintViolation], isSuccess: false }),
+            createAppendResult({ concurrencyViolation, isSuccess: false }),
+            createAppendResult({ errors: [appendError], isSuccess: false }),
+            createAppendResult()
+        ]);
+
+        it('should expose the constraint violations, concurrency violations, and errors as separate thin filters over getAppendResults', async () => {
+            unitOfWork.addEvent(EventSequenceId.eventLog, 'some-event-source', new SomethingHappened('a'));
+            unitOfWork.addEvent(EventSequenceId.eventLog, 'some-event-source', new SomethingHappened('b'));
+            unitOfWork.addEvent(EventSequenceId.eventLog, 'some-event-source', new SomethingHappened('c'));
+            unitOfWork.addEvent(EventSequenceId.eventLog, 'some-event-source', new SomethingHappened('d'));
+
+            await unitOfWork.commit();
+
+            expect(unitOfWork.getAppendResults()).toHaveLength(4);
+            expect(unitOfWork.getConstraintViolations()).toEqual([constraintViolation]);
+            expect(unitOfWork.getConcurrencyViolations()).toEqual([concurrencyViolation]);
+            expect(unitOfWork.getAppendErrors()).toEqual([appendError]);
+        });
+    });
+
+    describe('when nothing failed', () => {
+        const { unitOfWork } = createUnitOfWork([createAppendResult(), createAppendResult()]);
+
+        it('should return empty arrays for all three violation filters', async () => {
+            unitOfWork.addEvent(EventSequenceId.eventLog, 'some-event-source', new SomethingHappened('a'));
+            unitOfWork.addEvent(EventSequenceId.eventLog, 'some-event-source', new SomethingHappened('b'));
+
+            await unitOfWork.commit();
+
+            expect(unitOfWork.getConstraintViolations()).toEqual([]);
+            expect(unitOfWork.getConcurrencyViolations()).toEqual([]);
+            expect(unitOfWork.getAppendErrors()).toEqual([]);
+        });
+    });
+});

package/transactions/UnitOfWork.ts

@@ -2,7 +2,10 @@
 // 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 { AppendResult } from '../eventSequences/AppendResult';
+import { ConcurrencyViolation } from '../eventSequences/ConcurrencyViolation';
+import { ConstraintViolation } from '../eventSequences/ConstraintViolation';
 import { EventForEventSourceId } from '../eventSequences/EventForEventSourceId';
 import { EventSequenceId } from '../eventSequences/EventSequenceId';
 import { IEventStore } from '../IEventStore';
@@ -65,6 +68,23 @@ export class UnitOfWork implements IUnitOfWork {
         return this._appendResults;
     }
 
+    /** @inheritdoc */
+    getConstraintViolations(): ReadonlyArray<ConstraintViolation> {
+        return this._appendResults.flatMap(appendResult => appendResult.constraintViolations);
+    }
+
+    /** @inheritdoc */
+    getConcurrencyViolations(): ReadonlyArray<ConcurrencyViolation> {
+        return this._appendResults
+            .map(appendResult => appendResult.concurrencyViolation)
+            .filter((violation): violation is ConcurrencyViolation => violation !== undefined);
+    }
+
+    /** @inheritdoc */
+    getAppendErrors(): ReadonlyArray<AppendError> {
+        return this._appendResults.flatMap(appendResult => appendResult.errors);
+    }
+
     /** @inheritdoc */
     async commit(): Promise<void> {
         this.throwIfCompleted();