@cratis/chronicle 0.0.1

package/Events/EventTypes.ts

@@ -0,0 +1,95 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Constructor } from '@cratis/fundamentals';
+import { IClientArtifactsProvider } from '../artifacts';
+import { ChronicleConnection } from '../connection';
+import { EventTypeId } from './EventTypeId';
+import { IEventTypes } from './IEventTypes';
+import { getEventTypeMetadata, getEventTypeJsonSchemaFor } from './eventTypeDecorator';
+
+/**
+ * Implements {@link IEventTypes}, managing discovery and registration of event types
+ * with the Chronicle Kernel.
+ */
+export class EventTypes implements IEventTypes {
+    private readonly _types = new Map<string, Constructor>();
+
+    /**
+     * Creates a new {@link EventTypes} instance.
+     * @param _eventStore - The name of the event store these types belong to.
+     * @param _connection - The connection used to communicate with the Kernel.
+     * @param _clientArtifacts - Provider for discovered client artifact types.
+     */
+    constructor(
+        private readonly _eventStore: string,
+        private readonly _connection: ChronicleConnection,
+        private readonly _clientArtifacts: IClientArtifactsProvider
+    ) {}
+
+    /** @inheritdoc */
+    get all(): Constructor[] {
+        return [...this._types.values()];
+    }
+
+    /** @inheritdoc */
+    async discover(): Promise<void> {
+        this._types.clear();
+        for (const type of this._clientArtifacts.eventTypes) {
+            const metadata = getEventTypeMetadata(type);
+            if (metadata) {
+                this._types.set(metadata.eventType.id.value, type);
+            }
+        }
+    }
+
+    /** @inheritdoc */
+    async register(): Promise<void> {
+        if (this._types.size === 0) {
+            await this.discover();
+        }
+
+        const registrations = [...this._types.entries()].map(([, type]) => {
+            const metadata = getEventTypeMetadata(type)!;
+            const schema = getEventTypeJsonSchemaFor(type);
+            return {
+                Type: {
+                    Id: metadata.eventType.id.value,
+                    Generation: metadata.eventType.generation.value,
+                    Tombstone: false
+                },
+                Schema: JSON.stringify(schema),
+                Generations: [{
+                    Generation: metadata.eventType.generation.value,
+                    Schema: JSON.stringify(schema)
+                }],
+                Migrations: [],
+                EventStore: this._eventStore
+            };
+        });
+
+        if (registrations.length === 0) {
+            return;
+        }
+
+        await this._connection.eventTypes.register({
+            EventStore: this._eventStore,
+            Types: registrations,
+            DisableValidation: false
+        });
+    }
+
+    /** @inheritdoc */
+    hasFor(id: EventTypeId): boolean {
+        return this._types.has(id.value);
+    }
+
+    /** @inheritdoc */
+    getTypeFor(id: EventTypeId): Constructor {
+        const type = this._types.get(id.value);
+        if (!type) {
+            throw new Error(`No event type registered for id '${id.value}'.`);
+        }
+        return type;
+    }
+}

package/Events/IEventTypes.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Constructor } from '@cratis/fundamentals';
+import { EventTypeId } from './EventTypeId';
+
+/**
+ * Defines a system to work with event types, including discovery and registration with the Kernel.
+ */
+export interface IEventTypes {
+    /** Gets all registered event type constructors. */
+    readonly all: Constructor[];
+
+    /**
+     * Discovers all event types from the registered client artifacts.
+     * @returns A promise that resolves when discovery is complete.
+     */
+    discover(): Promise<void>;
+
+    /**
+     * Registers all discovered event types with the Chronicle Kernel.
+     * @returns A promise that resolves when registration is complete.
+     */
+    register(): Promise<void>;
+
+    /**
+     * Checks whether an event type constructor exists for the given identifier.
+     * @param id - The event type identifier to look up.
+     * @returns True if a matching type exists; otherwise false.
+     */
+    hasFor(id: EventTypeId): boolean;
+
+    /**
+     * Gets the event type constructor for the given identifier.
+     * @param id - The event type identifier to look up.
+     * @returns The constructor for the event type.
+     */
+    getTypeFor(id: EventTypeId): Constructor;
+}

package/Events/eventTypeDecorator.ts

@@ -0,0 +1,147 @@
+// 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 { EventType } from './EventType';
+import { EventTypeId } from './EventTypeId';
+import { EventTypeGeneration } from './EventTypeGeneration';
+import { DecoratorType, TypeDiscoverer, TypeIntrospector } from '../types';
+import { JsonSchema, JsonSchemaGenerator } from '../Schemas';
+
+/** Metadata key used to store event type information on a class. */
+const EVENT_TYPE_METADATA_KEY = 'chronicle:eventType';
+
+/**
+ * Metadata stored for an event type class.
+ */
+export interface EventTypeMetadata {
+    /** The event type descriptor for the event class. */
+    readonly eventType: EventType;
+
+    /** The reflected members and their runtime types. */
+    readonly members: ReadonlyMap<string, Function | undefined>;
+
+    /** The generated schema for the event class. */
+    readonly schema: JsonSchema;
+}
+
+/**
+ * TypeScript decorator that marks a class as an event type and associates it with a specific
+ * {@link EventType} identifier and generation. This is the TypeScript equivalent of the
+ * C# `[EventType]` attribute.
+ *
+ * Overloads:
+ * - `@eventType()` -> uses class name as id, generation 1, tombstone false.
+ * - `@eventType(generation)` -> uses class name as id and provided generation.
+ * - `@eventType(tombstone)` -> uses class name as id/generation and provided tombstone.
+ * - `@eventType(generation, tombstone)` -> uses class name as id.
+ * - `@eventType(id, generation, tombstone)` -> full explicit form.
+ *
+ * @param idOrGenerationOrTombstone - Optional id, generation, or tombstone based on overload.
+ * @param generationOrTombstone - Optional generation or tombstone based on overload.
+ * @param tombstone - Optional explicit tombstone for the explicit id overload.
+ * @returns A class decorator.
+ *
+ * @example
+ * ```typescript
+ * @eventType()
+ * class EmployeeHired {
+ *     constructor(readonly firstName: string, readonly lastName: string) {}
+ * }
+ * ```
+ */
+export function eventType(): ClassDecorator;
+export function eventType(id: string): ClassDecorator;
+export function eventType(id: string, generation: number): ClassDecorator;
+export function eventType(id: string, generation: number, tombstone: boolean): ClassDecorator;
+export function eventType(generation: number): ClassDecorator;
+export function eventType(generation: number, tombstone: boolean): ClassDecorator;
+export function eventType(tombstone: boolean): ClassDecorator;
+export function eventType(
+    idOrGenerationOrTombstone?: string | number | boolean,
+    generationOrTombstone?: number | boolean,
+    tombstone: boolean = false
+): ClassDecorator {
+    let id = '';
+    let generation = EventTypeGeneration.firstValue;
+    let isTombstone = false;
+
+    if (typeof idOrGenerationOrTombstone === 'string') {
+        id = idOrGenerationOrTombstone;
+        if (typeof generationOrTombstone === 'number') {
+            generation = generationOrTombstone;
+        }
+        if (typeof generationOrTombstone === 'boolean') {
+            isTombstone = generationOrTombstone;
+        } else {
+            isTombstone = tombstone;
+        }
+    } else if (typeof idOrGenerationOrTombstone === 'number') {
+        generation = idOrGenerationOrTombstone;
+        if (typeof generationOrTombstone === 'boolean') {
+            isTombstone = generationOrTombstone;
+        }
+    } else if (typeof idOrGenerationOrTombstone === 'boolean') {
+        isTombstone = idOrGenerationOrTombstone;
+    }
+
+    return (target: object) => {
+        const constructor = target as Function;
+        const eventTypeId = new EventTypeId(id || constructor.name);
+        const eventTypeInstance = new EventType(eventTypeId, new EventTypeGeneration(generation), isTombstone);
+        const members = TypeIntrospector.getMembers(constructor);
+        const metadata: EventTypeMetadata = {
+            eventType: eventTypeInstance,
+            members,
+            schema: JsonSchemaGenerator.generate(constructor, members)
+        };
+        Reflect.defineMetadata(EVENT_TYPE_METADATA_KEY, metadata, target);
+        TypeDiscoverer.default.register(
+            DecoratorType.EventType,
+            constructor as Constructor,
+            eventTypeId.value
+        );
+    };
+}
+
+/**
+ * Gets the {@link EventType} associated with a class decorated with {@link eventType}.
+ * @param target - The class constructor to retrieve the event type for.
+ * @returns The associated EventType, or EventType.unknown if not decorated.
+ */
+export function getEventTypeFor(target: Function): EventType {
+    return getEventTypeMetadata(target)?.eventType ?? EventType.unknown;
+}
+
+/**
+ * Checks whether a class has been decorated with {@link eventType}.
+ * @param target - The class constructor to check.
+ * @returns True if the class has an event type decorator; false otherwise.
+ */
+export function hasEventType(target: Function): boolean {
+    return getEventTypeMetadata(target) !== undefined;
+}
+
+/**
+ * Gets the metadata associated with a class decorated with {@link eventType}.
+ * @param target - The class constructor to retrieve metadata for.
+ * @returns The associated metadata, or undefined if not decorated.
+ */
+export function getEventTypeMetadata(target: Function): EventTypeMetadata | undefined {
+    return Reflect.getMetadata(EVENT_TYPE_METADATA_KEY, target);
+}
+
+/**
+ * Generates a JSON schema for the provided event type class.
+ * @param target - The event class constructor to generate schema for.
+ * @returns The generated JSON schema.
+ */
+export function getEventTypeJsonSchemaFor(target: Function): JsonSchema {
+    const metadata = getEventTypeMetadata(target);
+    if (metadata) {
+        return metadata.schema;
+    }
+
+    return JsonSchemaGenerator.createEmptySchema(target.name);
+}

package/Events/index.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.
+
+export { EventType } from './EventType';
+export { EventTypeId } from './EventTypeId';
+export { EventTypeGeneration } from './EventTypeGeneration';
+export { eventType, getEventTypeFor, hasEventType, getEventTypeMetadata, getEventTypeJsonSchemaFor } from './eventTypeDecorator';
+export type { EventTypeMetadata } from './eventTypeDecorator';
+export type { EventContext } from './EventContext';
+export type { CausationEntry } from './CausationEntry';
+export type { AppendedEvent } from './AppendedEvent';
+export type { IEventTypes } from './IEventTypes';
+export { EventTypes } from './EventTypes';
+export * from './Constraints';

package/IChronicleClient.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ChronicleOptions } from './ChronicleOptions';
+import { EventStoreName } from './EventStoreName';
+import { EventStoreNamespaceName } from './EventStoreNamespaceName';
+import { IEventStore } from './IEventStore';
+
+/**
+ * Defines the Cratis Chronicle client API surface.
+ *
+ * The Chronicle client is the primary entry point for interacting with the
+ * Chronicle Kernel. Use it to obtain event stores, which in turn provide access
+ * to event sequences for appending and observing events.
+ */
+export interface IChronicleClient {
+    /** The options used to configure the client. */
+    readonly options: ChronicleOptions;
+
+    /**
+     * Gets or creates an event store by name and optional namespace.
+     * If no namespace is provided, the default namespace is used.
+     * @param name - The name of the event store.
+     * @param namespace - Optional namespace name within the event store.
+     * @returns The event store.
+     */
+    getEventStore(name: string | EventStoreName, namespace?: string | EventStoreNamespaceName): Promise<IEventStore>;
+
+    /**
+     * Lists all event stores registered with the Chronicle Kernel.
+     * @returns An array of event store names.
+     */
+    getEventStores(): Promise<EventStoreName[]>;
+
+    /**
+     * Disposes of the client and releases all underlying resources.
+     */
+    dispose(): void;
+}

package/IEventStore.ts

@@ -0,0 +1,56 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IEventLog } from './EventSequences/IEventLog';
+import { IEventSequence } from './EventSequences/IEventSequence';
+import { EventSequenceId } from './EventSequences/EventSequenceId';
+import { EventStoreName } from './EventStoreName';
+import { EventStoreNamespaceName } from './EventStoreNamespaceName';
+import { IEventTypes } from './Events/IEventTypes';
+import { IConstraints } from './Events/Constraints/IConstraints';
+import { IProjections } from './Projections/IProjections';
+import { IReactors } from './Reactors/IReactors';
+import { IReducers } from './Reducers/IReducers';
+
+/**
+ * Defines the API surface for an event store.
+ * An event store is a logical grouping of event sequences within a namespace.
+ */
+export interface IEventStore {
+    /** The name of the event store. */
+    readonly name: EventStoreName;
+
+    /** The namespace of the event store. */
+    readonly namespace: EventStoreNamespaceName;
+
+    /** The primary event log sequence for this event store. */
+    readonly eventLog: IEventLog;
+
+    /** The event types manager for this event store. */
+    readonly eventTypes: IEventTypes;
+
+    /** The constraints manager for this event store. */
+    readonly constraints: IConstraints;
+
+    /** The projections manager for this event store. */
+    readonly projections: IProjections;
+
+    /** The reactors manager for this event store. */
+    readonly reactors: IReactors;
+
+    /** The reducers manager for this event store. */
+    readonly reducers: IReducers;
+
+    /**
+     * Gets an event sequence by its identifier.
+     * @param id - The identifier of the event sequence to retrieve.
+     * @returns The event sequence with the given identifier.
+     */
+    getEventSequence(id: EventSequenceId): IEventSequence;
+
+    /**
+     * Lists the namespaces available in this event store.
+     * @returns An array of namespace names.
+     */
+    getNamespaces(): Promise<EventStoreNamespaceName[]>;
+}

package/Metrics.ts

@@ -0,0 +1,109 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { metrics } from '@opentelemetry/api';
+
+/**
+ * The name of the Chronicle metrics instrumentation library.
+ * This matches {@link ChronicleInstrumentationName} from Tracing so that all Chronicle
+ * telemetry is grouped under a single instrumentation scope in your observability backend.
+ */
+export const ChronicleMeterName = '@cratis/chronicle';
+
+/**
+ * The OpenTelemetry meter used by the Chronicle client for all metric instrumentation.
+ *
+ * If your application has configured an OpenTelemetry SDK (e.g. via {@link https://www.npmjs.com/package/@opentelemetry/sdk-node}),
+ * Chronicle metrics will automatically flow through it.
+ * If no SDK is configured, the no-op meter is used and no overhead is incurred.
+ */
+export const ChronicleMeter = metrics.getMeter(ChronicleMeterName);
+
+/**
+ * Pre-built metric instruments for all Chronicle client operations.
+ * These are created once and shared across all invocations.
+ */
+export const ChronicleMetrics = {
+    /**
+     * Counts the number of individual events appended to an event sequence.
+     *
+     * Attributes: `chronicle.event_store`, `chronicle.namespace`,
+     * `chronicle.event_sequence_id`, `chronicle.event_type_id`
+     */
+    eventsAppended: ChronicleMeter.createCounter('chronicle.events.appended', {
+        description: 'Number of individual events appended to an event sequence.',
+        unit: '{event}'
+    }),
+
+    /**
+     * Counts the number of batch-append operations performed on an event sequence.
+     * Each call to appendMany counts as one batch regardless of how many events it contains.
+     *
+     * Attributes: `chronicle.event_store`, `chronicle.namespace`,
+     * `chronicle.event_sequence_id`, `chronicle.events_count`
+     */
+    batchAppendsPerformed: ChronicleMeter.createCounter('chronicle.events.batch_appends', {
+        description: 'Number of batch-append operations performed on an event sequence.',
+        unit: '{operation}'
+    }),
+
+    /**
+     * Counts the number of event store retrieval operations.
+     *
+     * Attributes: `chronicle.event_store`, `chronicle.namespace`
+     */
+    eventStoreRetrievals: ChronicleMeter.createCounter('chronicle.client.event_store_retrievals', {
+        description: 'Number of event store retrieval operations.',
+        unit: '{operation}'
+    }),
+
+    /**
+     * Measures the duration of append operations in milliseconds.
+     *
+     * Attributes: `chronicle.event_store`, `chronicle.namespace`,
+     * `chronicle.event_sequence_id`, `chronicle.event_type_id`
+     */
+    appendDuration: ChronicleMeter.createHistogram('chronicle.events.append_duration', {
+        description: 'Duration of individual event append operations.',
+        unit: 'ms',
+        advice: {
+            explicitBucketBoundaries: [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000]
+        }
+    }),
+
+    /**
+     * Measures the duration of batch-append operations in milliseconds.
+     *
+     * Attributes: `chronicle.event_store`, `chronicle.namespace`,
+     * `chronicle.event_sequence_id`, `chronicle.events_count`
+     */
+    appendManyDuration: ChronicleMeter.createHistogram('chronicle.events.append_many_duration', {
+        description: 'Duration of batch event append operations.',
+        unit: 'ms',
+        advice: {
+            explicitBucketBoundaries: [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000]
+        }
+    }),
+
+    /**
+     * Counts the number of append constraint violations encountered.
+     *
+     * Attributes: `chronicle.event_store`, `chronicle.namespace`,
+     * `chronicle.event_sequence_id`
+     */
+    constraintViolations: ChronicleMeter.createCounter('chronicle.events.constraint_violations', {
+        description: 'Number of constraint violations encountered during event appends.',
+        unit: '{violation}'
+    }),
+
+    /**
+     * Counts the number of append errors encountered.
+     *
+     * Attributes: `chronicle.event_store`, `chronicle.namespace`,
+     * `chronicle.event_sequence_id`
+     */
+    appendErrors: ChronicleMeter.createCounter('chronicle.events.append_errors', {
+        description: 'Number of errors encountered during event appends.',
+        unit: '{error}'
+    })
+};

package/Observation/ObserverId.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.
+
+/**
+ * Represents the unique identifier of an observer.
+ */
+export class ObserverId {
+    constructor(readonly value: string) {}
+
+    /** @inheritdoc */
+    toString(): string {
+        return this.value;
+    }
+}

package/Observation/ObserverRunningState.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents the running state of an observer.
+ */
+export enum ObserverRunningState {
+    /** The observer is in an unknown state. */
+    Unknown = 'Unknown',
+
+    /** The observer is subscribing to the event sequence. */
+    Subscribing = 'Subscribing',
+
+    /** The observer is replaying events from the beginning. */
+    Replaying = 'Replaying',
+
+    /** The observer is resuming after a pause. */
+    Resuming = 'Resuming',
+
+    /** The observer is actively processing events. */
+    Active = 'Active',
+
+    /** The observer is paused and not processing events. */
+    Paused = 'Paused',
+
+    /** The observer has stopped processing events. */
+    Stopped = 'Stopped',
+
+    /** The observer is in a failed state. */
+    Failed = 'Failed',
+
+    /** The observer has been disconnected. */
+    Disconnected = 'Disconnected'
+}

package/Observation/index.ts

@@ -0,0 +1,5 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export { ObserverId } from './ObserverId';
+export { ObserverRunningState } from './ObserverRunningState';

package/Projections/IProjections.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 projections, including discovery and registration with the Kernel.
+ */
+export interface IProjections {
+    /**
+     * Discovers all projections from the registered client artifacts.
+     * @returns A promise that resolves when discovery is complete.
+     */
+    discover(): Promise<void>;
+
+    /**
+     * Registers all discovered projections with the Chronicle Kernel.
+     * @returns A promise that resolves when registration is complete.
+     */
+    register(): Promise<void>;
+}

package/Projections/ProjectionId.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 projection.
+ */
+export class ProjectionId {
+    constructor(readonly value: string) {}
+
+    /** @inheritdoc */
+    toString(): string {
+        return this.value;
+    }
+}