@cratis/chronicle 0.0.1

package/Reactors/reactor.ts

@@ -0,0 +1,75 @@
+// 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 { Constructor } from '@cratis/fundamentals';
+import { ReactorId } from './ReactorId';
+import { DecoratorType, TypeDiscoverer } from '../types';
+
+/** Metadata key used to store reactor information on a class. */
+const REACTOR_METADATA_KEY = 'chronicle:reactor';
+
+/**
+ * Metadata stored on a reactor class.
+ */
+export interface ReactorMetadata {
+    /** The unique identifier for the reactor. */
+    readonly id: ReactorId;
+
+    /** The optional explicit event sequence identifier. */
+    readonly eventSequenceId: string | undefined;
+}
+
+/**
+ * TypeScript decorator that marks a class as a reactor and associates it with a unique
+ * identifier. This is the TypeScript equivalent of the C# `[Reactor]` attribute.
+ *
+ * Reactors observe events from an event sequence and produce side effects.
+ * Method dispatch is by convention: the type of the first parameter of each public method
+ * determines which events it handles.
+ *
+ * @param id - The unique identifier for the reactor. Defaults to the class name if omitted.
+ * @param eventSequenceId - Optional explicit event sequence identifier.
+ * @returns A class decorator.
+ *
+ * @example
+ * ```typescript
+ * @reactor()
+ * class ProjectRegisteredNotifier {
+ *     async projectRegistered(event: ProjectRegistered, context: EventContext): Promise<void> {
+ *         console.log(`Project '${event.name}' was registered.`);
+ *     }
+ * }
+ * ```
+ */
+export function reactor(id: string = '', eventSequenceId?: string): ClassDecorator {
+    return (target: object) => {
+        const constructor = target as Function;
+        const reactorId = new ReactorId(id || constructor.name);
+        const metadata: ReactorMetadata = { id: reactorId, eventSequenceId };
+        Reflect.defineMetadata(REACTOR_METADATA_KEY, metadata, target);
+        TypeDiscoverer.default.register(
+            DecoratorType.Reactor,
+            constructor as Constructor,
+            reactorId.value
+        );
+    };
+}
+
+/**
+ * Gets the {@link ReactorMetadata} associated with a class decorated with {@link reactor}.
+ * @param target - The class constructor to retrieve the metadata for.
+ * @returns The associated ReactorMetadata, or undefined if not decorated.
+ */
+export function getReactorMetadata(target: Function): ReactorMetadata | undefined {
+    return Reflect.getMetadata(REACTOR_METADATA_KEY, target);
+}
+
+/**
+ * Checks whether a class has been decorated with {@link reactor}.
+ * @param target - The class constructor to check.
+ * @returns True if the class has a reactor decorator; false otherwise.
+ */
+export function isReactor(target: Function): boolean {
+    return Reflect.hasMetadata(REACTOR_METADATA_KEY, target);
+}

package/ReadModels/ReadModelId.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Unique identifier for a read model.
+ */
+export class ReadModelId {
+    constructor(readonly value: string) {}
+
+    /** @inheritdoc */
+    toString(): string {
+        return this.value;
+    }
+}

package/ReadModels/index.ts

@@ -0,0 +1,6 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export { ReadModelId } from './ReadModelId';
+export { readModel, getReadModelMetadata, isReadModel } from './readModel';
+export type { ReadModelMetadata } from './readModel';

package/ReadModels/readModel.ts

@@ -0,0 +1,89 @@
+// 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 { Constructor } from '@cratis/fundamentals';
+import { ReadModelId } from './ReadModelId';
+import { DecoratorType, TypeDiscoverer, TypeIntrospector } from '../types';
+import { JsonSchema, JsonSchemaGenerator } from '../Schemas';
+
+/** Metadata key used to store read model information on a class. */
+const READ_MODEL_METADATA_KEY = 'chronicle:readModel';
+
+/**
+ * Metadata stored on a read model class.
+ */
+export interface ReadModelMetadata {
+    /** The unique identifier for the read model. */
+    readonly id: ReadModelId;
+
+    /** The reflected members and their runtime types. */
+    readonly members: ReadonlyMap<string, Function | undefined>;
+
+    /** The generated JSON schema for the read model. */
+    readonly schema: JsonSchema;
+}
+
+/**
+ * TypeScript decorator that marks a class as a read model and captures reflection metadata.
+ * @param id - The unique identifier for the read model. Defaults to the class name if omitted.
+ * @returns A class decorator.
+ */
+export function readModel(id: string = ''): ClassDecorator {
+    return (target: object) => {
+        const constructor = target as Function;
+        const readModelId = new ReadModelId(id || constructor.name);
+        trackInstanceProperties(constructor);
+        const members = TypeIntrospector.getMembers(constructor);
+        const metadata: ReadModelMetadata = {
+            id: readModelId,
+            members,
+            schema: JsonSchemaGenerator.generate(constructor, members)
+        };
+        Reflect.defineMetadata(READ_MODEL_METADATA_KEY, metadata, target);
+        TypeDiscoverer.default.register(
+            DecoratorType.ReadModel,
+            constructor as Constructor,
+            readModelId.value
+        );
+    };
+}
+
+function trackInstanceProperties(constructor: Function): void {
+    const instance = tryCreateInstance(constructor);
+    if (!instance || typeof instance !== 'object') {
+        return;
+    }
+
+    for (const propertyName of Object.keys(instance as Record<string, unknown>)) {
+        TypeIntrospector.trackProperty(constructor, propertyName);
+    }
+}
+
+function tryCreateInstance(constructor: Function): unknown {
+    try {
+        const parameterCount = constructor.length;
+        const parameters = Array.from({ length: parameterCount }, () => undefined);
+        return Reflect.construct(constructor as new (...args: unknown[]) => unknown, parameters);
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * Gets the {@link ReadModelMetadata} associated with a class decorated with {@link readModel}.
+ * @param target - The class constructor to retrieve metadata for.
+ * @returns The associated metadata, or undefined if not decorated.
+ */
+export function getReadModelMetadata(target: Function): ReadModelMetadata | undefined {
+    return Reflect.getMetadata(READ_MODEL_METADATA_KEY, target);
+}
+
+/**
+ * Checks whether a class has been decorated with {@link readModel}.
+ * @param target - The class constructor to check.
+ * @returns True if the class has a read model decorator; false otherwise.
+ */
+export function isReadModel(target: Function): boolean {
+    return Reflect.hasMetadata(READ_MODEL_METADATA_KEY, target);
+}

package/Reducers/IReducers.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Defines a system to work with reducers, including discovery and registration with the Kernel.
+ */
+export interface IReducers {
+    /**
+     * Discovers all reducers from the registered client artifacts.
+     * @returns A promise that resolves when discovery is complete.
+     */
+    discover(): Promise<void>;
+
+    /**
+     * Registers all discovered reducers with the Chronicle Kernel and starts observation.
+     * @returns A promise that resolves when registration is complete.
+     */
+    register(): Promise<void>;
+}

package/Reducers/ReducerId.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Unique identifier for a reducer.
+ */
+export class ReducerId {
+    constructor(readonly value: string) {}
+
+    /** @inheritdoc */
+    toString(): string {
+        return this.value;
+    }
+}

package/Reducers/Reducers.ts

@@ -0,0 +1,322 @@
+// 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 { diag } from '@opentelemetry/api';
+import { Constructor } from '@cratis/fundamentals';
+import { ObservationState, ReducerMessage } from '@cratis/chronicle.contracts';
+import { IClientArtifactsProvider } from '../artifacts';
+import { ChronicleConnection } from '../connection';
+import { ConnectionLifecycle } from '../connection/ConnectionLifecycle';
+import { getEventTypeMetadata } from '../Events/eventTypeDecorator';
+import { EventSequenceId } from '../EventSequences/EventSequenceId';
+import { IReducers } from './IReducers';
+import { getReducerMetadata } from './reducer';
+
+/** Expression used to partition reducer observations by event source ID. */
+const EVENT_SOURCE_ID_KEY = '$eventSourceId';
+
+/** Sentinel sequence number sent back when no event was successfully processed. */
+const SEQUENCE_NUMBER_UNAVAILABLE = 4294967295;
+
+interface EventTypeEntry {
+    readonly id: string;
+    readonly generation: number;
+    readonly methodName: string;
+}
+
+/**
+ * A push-based async queue that implements {@link AsyncIterable} for use with nice-grpc
+ * bidirectional streaming. Values pushed via {@link send} are yielded in order to
+ * any consumer that iterates the queue.
+ */
+class AsyncQueue<T> {
+    private readonly _queue: T[] = [];
+    private _resolve: ((result: IteratorResult<T, undefined>) => void) | undefined = undefined;
+    private _done = false;
+
+    /** Pushes a value into the queue. No-op if the queue has been completed. */
+    send(value: T): void {
+        if (this._done) return;
+        if (this._resolve) {
+            const resolve = this._resolve;
+            this._resolve = undefined;
+            resolve({ value, done: false });
+        } else {
+            this._queue.push(value);
+        }
+    }
+
+    /** Signals that no more values will be pushed, causing consumers to finish iteration. */
+    complete(): void {
+        this._done = true;
+        if (this._resolve) {
+            this._resolve({ value: undefined, done: true });
+            this._resolve = undefined;
+        }
+    }
+
+    [Symbol.asyncIterator](): AsyncIterator<T, undefined> {
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const self = this;
+        return {
+            next(): Promise<IteratorResult<T, undefined>> {
+                if (self._queue.length > 0) {
+                    return Promise.resolve({ value: self._queue.shift()!, done: false });
+                }
+                if (self._done) {
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                return new Promise(resolve => {
+                    self._resolve = resolve as (result: IteratorResult<T, undefined>) => void;
+                });
+            },
+            return(): Promise<IteratorResult<T, undefined>> {
+                self._done = true;
+                if (self._resolve) {
+                    self._resolve({ value: undefined, done: true });
+                    self._resolve = undefined;
+                }
+                return Promise.resolve({ value: undefined, done: true });
+            }
+        };
+    }
+}
+
+/**
+ * Implements {@link IReducers}, managing discovery and registration of reducers
+ * with the Chronicle Kernel via bidirectional gRPC streaming.
+ */
+export class Reducers implements IReducers {
+    private readonly _logger = diag.createComponentLogger({ namespace: '@cratis/chronicle/Reducers' });
+    private readonly _lifecycle: ConnectionLifecycle;
+    private readonly _reducers = new Map<string, Constructor>();
+    private readonly _queues = new Map<string, AsyncQueue<ReducerMessage>>();
+    private _registered = false;
+
+    /**
+     * Creates a new {@link Reducers} instance.
+     * @param _clientArtifacts - Provider for discovered client artifact types.
+     * @param _connection - The Chronicle gRPC connection.
+     * @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.
+     */
+    constructor(
+        private readonly _clientArtifacts: IClientArtifactsProvider,
+        private readonly _connection: ChronicleConnection,
+        private readonly _eventStoreName: string,
+        private readonly _namespace: string,
+        lifecycle: ConnectionLifecycle
+    ) {
+        this._lifecycle = lifecycle;
+        lifecycle.onDisconnected(async () => {
+            this._logger.info('Disconnected — stopping all reducer observations');
+            this._registered = false;
+            this.disconnectAll();
+        });
+    }
+
+    /** @inheritdoc */
+    async discover(): Promise<void> {
+        this._reducers.clear();
+        for (const type of this._clientArtifacts.reducers) {
+            const metadata = getReducerMetadata(type);
+            if (metadata) {
+                this._reducers.set(metadata.id.value, type);
+                this._logger.debug('Discovered reducer', { reducerId: metadata.id.value, type: (type as Function).name });
+            }
+        }
+    }
+
+    /** @inheritdoc */
+    async register(): Promise<void> {
+        if (this._registered) {
+            return;
+        }
+
+        if (this._reducers.size === 0) {
+            await this.discover();
+        }
+
+        this._logger.info('Registering reducers', { count: this._reducers.size });
+        for (const [id, reducerType] of this._reducers) {
+            this.startObservation(id, reducerType);
+        }
+
+        this._registered = true;
+    }
+
+    private startObservation(id: string, reducerType: Constructor): void {
+        const metadata = getReducerMetadata(reducerType)!;
+        const eventSequenceId = metadata.eventSequenceId ?? EventSequenceId.eventLog.value;
+        const eventTypes = this.getEventTypesFor(reducerType);
+        const readModelName = (reducerType as Function).name;
+
+        this._logger.info('Starting reducer observation', {
+            reducerId: id,
+            eventSequenceId,
+            readModel: readModelName,
+            handlerCount: eventTypes.length,
+            handlers: eventTypes.map(e => e.methodName)
+        });
+
+        this.observeReducer(id, reducerType, eventSequenceId, eventTypes, readModelName).catch(err => {
+            this._logger.error('Reducer observation loop exited with error', { reducerId: id, error: String(err) });
+        });
+    }
+
+    private async observeReducer(
+        id: string,
+        reducerType: Constructor,
+        eventSequenceId: string,
+        eventTypes: EventTypeEntry[],
+        readModelName: string
+    ): Promise<void> {
+        const queue = new AsyncQueue<ReducerMessage>();
+        this._queues.set(id, queue);
+
+        queue.send({
+            Content: {
+                Value0: {
+                    ConnectionId: this._lifecycle.connectionId,
+                    EventStore: this._eventStoreName,
+                    Namespace: this._namespace,
+                    Reducer: {
+                        ReducerId: id,
+                        EventSequenceId: eventSequenceId,
+                        EventTypes: eventTypes.map(et => ({
+                            EventType: { Id: et.id, Generation: et.generation, Tombstone: false },
+                            Key: EVENT_SOURCE_ID_KEY
+                        })),
+                        ReadModel: readModelName,
+                        IsActive: true,
+                        Sink: { TypeId: { lo: 0, hi: 0 }, ConfigurationId: undefined },
+                        Tags: [],
+                        Filters: {
+                            FilterTags: [],
+                            EventSourceType: '',
+                            EventStreamType: 'All'
+                        }
+                    }
+                },
+                Value1: undefined
+            }
+        });
+
+        try {
+            const reducerInstance = new (reducerType as new () => Record<string, Function>)();
+
+            for await (const operation of this._connection.reducers.observe(queue)) {
+                let lastSuccessfullyObservedEvent = SEQUENCE_NUMBER_UNAVAILABLE;
+                let state = ObservationState.Success;
+                const exceptionMessages: string[] = [];
+                let exceptionStackTrace = '';
+                let readModelState: string | undefined;
+
+                this._logger.debug('Received reduce operation', {
+                    reducerId: id,
+                    partition: operation.Partition,
+                    count: operation.Events.length,
+                    hasInitialState: operation.InitialState !== ''
+                });
+
+                let currentState: unknown = operation.InitialState
+                    ? JSON.parse(operation.InitialState) as unknown
+                    : undefined;
+
+                for (const event of operation.Events) {
+                    try {
+                        const eventTypeId = event.Context?.EventType?.Id;
+                        if (!eventTypeId) {
+                            this._logger.warn('Event missing event type context', { reducerId: id });
+                            continue;
+                        }
+
+                        const entry = eventTypes.find(et => et.id === eventTypeId);
+                        if (!entry) {
+                            this._logger.debug('No handler registered for event type — skipping', { reducerId: id, eventTypeId });
+                            lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
+                            continue;
+                        }
+
+                        const content = JSON.parse(event.Content) as Record<string, unknown>;
+
+                        this._logger.info('Invoking reducer handler', {
+                            reducerId: id,
+                            method: entry.methodName,
+                            sequenceNumber: event.Context!.SequenceNumber,
+                            eventTypeId,
+                            hasState: currentState !== undefined
+                        });
+
+                        currentState = await reducerInstance[entry.methodName](content, currentState);
+                        lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
+                    } catch (err) {
+                        this._logger.error('Error handling event in reducer', { reducerId: id, error: String(err) });
+                        exceptionMessages.push(String(err));
+                        exceptionStackTrace = err instanceof Error ? (err.stack ?? '') : '';
+                        state = ObservationState.Failed;
+                        break;
+                    }
+                }
+
+                if (state === ObservationState.Success && currentState !== undefined) {
+                    readModelState = JSON.stringify(currentState);
+                }
+
+                queue.send({
+                    Content: {
+                        Value0: undefined,
+                        Value1: {
+                            Partition: operation.Partition,
+                            State: state,
+                            LastSuccessfulObservation: lastSuccessfullyObservedEvent,
+                            ExceptionMessages: exceptionMessages,
+                            ExceptionStackTrace: exceptionStackTrace,
+                            ReadModelState: readModelState ?? ''
+                        }
+                    }
+                });
+            }
+        } catch (err) {
+            if (!this._queues.has(id)) {
+                this._logger.debug('Reducer observation stream closed cleanly', { reducerId: id });
+            } else {
+                this._logger.error('Reducer observation stream ended unexpectedly', { reducerId: id, error: String(err) });
+            }
+        } finally {
+            this._queues.delete(id);
+        }
+    }
+
+    private getEventTypesFor(reducerType: Constructor): EventTypeEntry[] {
+        const proto = reducerType.prototype as Record<string, unknown>;
+        const entries: EventTypeEntry[] = [];
+
+        for (const eventTypeClass of this._clientArtifacts.eventTypes) {
+            const eventTypeMeta = getEventTypeMetadata(eventTypeClass);
+            if (!eventTypeMeta) continue;
+
+            const className = (eventTypeClass as Function).name;
+            const methodName = className.charAt(0).toLowerCase() + className.slice(1);
+
+            if (typeof proto[methodName] === 'function') {
+                entries.push({
+                    id: eventTypeMeta.eventType.id.value,
+                    generation: eventTypeMeta.eventType.generation.value,
+                    methodName
+                });
+            }
+        }
+
+        return entries;
+    }
+
+    private disconnectAll(): void {
+        for (const queue of this._queues.values()) {
+            queue.complete();
+        }
+        this._queues.clear();
+    }
+}

package/Reducers/index.ts

@@ -0,0 +1,8 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export { ReducerId } from './ReducerId';
+export { reducer, getReducerMetadata, isReducer } from './reducer';
+export type { ReducerMetadata } from './reducer';
+export type { IReducers } from './IReducers';
+export { Reducers } from './Reducers';

package/Reducers/reducer.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 'reflect-metadata';
+import { Constructor } from '@cratis/fundamentals';
+import { ReducerId } from './ReducerId';
+import { DecoratorType, TypeDiscoverer } from '../types';
+
+/** Metadata key used to store reducer information on a class. */
+const REDUCER_METADATA_KEY = 'chronicle:reducer';
+
+/**
+ * Metadata stored on a reducer class.
+ */
+export interface ReducerMetadata {
+    /** The unique identifier for the reducer. */
+    readonly id: ReducerId;
+
+    /** The optional explicit event sequence identifier. */
+    readonly eventSequenceId: string | undefined;
+
+    /** The optional read model type produced by the reducer. */
+    readonly readModel: Constructor | undefined;
+}
+
+/**
+ * TypeScript decorator that marks a class as a reducer and associates it with a unique
+ * identifier. This is the TypeScript equivalent of the C# `[Reducer]` attribute.
+ *
+ * Reducers observe events from an event sequence and fold them into a read model.
+ * Each handler method receives the event, the current state (or undefined), and an
+ * optional context, and returns the new state.
+ *
+ * @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.
+ * @returns A class decorator.
+ *
+ * @example
+ * ```typescript
+ * @reducer()
+ * class EmployeeReducer {
+ *     async employeeHired(event: EmployeeHired, state?: EmployeeState): Promise<EmployeeState> {
+ *         return { ...state, name: `${event.firstName} ${event.lastName}` };
+ *     }
+ * }
+ * ```
+ */
+export function reducer(id: string = '', eventSequenceId?: string, readModel?: Constructor): ClassDecorator {
+    return (target: object) => {
+        const constructor = target as Function;
+        const reducerId = new ReducerId(id || constructor.name);
+        const metadata: ReducerMetadata = { id: reducerId, eventSequenceId, readModel };
+        Reflect.defineMetadata(REDUCER_METADATA_KEY, metadata, target);
+        TypeDiscoverer.default.register(
+            DecoratorType.Reducer,
+            constructor as Constructor,
+            reducerId.value
+        );
+
+        if (readModel) {
+            TypeDiscoverer.default.register(
+                DecoratorType.ReadModel,
+                readModel,
+                readModel.name
+            );
+        }
+    };
+}
+
+/**
+ * Gets the {@link ReducerMetadata} associated with a class decorated with {@link reducer}.
+ * @param target - The class constructor to retrieve the metadata for.
+ * @returns The associated ReducerMetadata, or undefined if not decorated.
+ */
+export function getReducerMetadata(target: Function): ReducerMetadata | undefined {
+    return Reflect.getMetadata(REDUCER_METADATA_KEY, target);
+}
+
+/**
+ * Checks whether a class has been decorated with {@link reducer}.
+ * @param target - The class constructor to check.
+ * @returns True if the class has a reducer decorator; false otherwise.
+ */
+export function isReducer(target: Function): boolean {
+    return Reflect.hasMetadata(REDUCER_METADATA_KEY, target);
+}

package/Schemas/JsonSchema.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents a JSON Schema object.
+ */
+export type JsonSchema = {
+    $schema?: string;
+    title?: string;
+    description?: string;
+    type?: 'null' | 'boolean' | 'object' | 'array' | 'number' | 'string' | 'integer';
+    format?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    additionalProperties?: boolean | JsonSchema;
+    enum?: Array<string | number | boolean | null>;
+};