@cratis/chronicle 0.0.1 → 0.2.0

package/events/EventTypes.ts

@@ -0,0 +1,186 @@
+// 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';
+import { EventMigrationBuilder } from './migrations/EventMigrationBuilder';
+import { EventTypeMigrators } from './migrations/EventTypeMigrators';
+import { getEventTypeMigrationMetadata } from './migrations/eventTypeMigration';
+import { IEventTypeMigration } from './migrations/IEventTypeMigration';
+
+// Mirrors .NET client behavior for migration-only generations that do not have a local CLR/TS type.
+const UNKNOWN_GENERATION_SCHEMA = '{}';
+
+/**
+ * Implements {@link IEventTypes}, managing discovery and registration of event types
+ * with the Chronicle Kernel.
+ */
+export class EventTypes implements IEventTypes {
+    private readonly _typesByGeneration = new Map<string, Constructor>();
+    private readonly _latestTypes = new Map<string, Constructor>();
+    private readonly _eventTypeMigrators: EventTypeMigrators;
+
+    /**
+     * 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
+    ) {
+        this._eventTypeMigrators = new EventTypeMigrators(_clientArtifacts);
+    }
+
+    /** @inheritdoc */
+    get all(): Constructor[] {
+        return [...this._latestTypes.values()];
+    }
+
+    /** @inheritdoc */
+    async discover(): Promise<void> {
+        this._typesByGeneration.clear();
+        this._latestTypes.clear();
+        for (const type of this._clientArtifacts.eventTypes) {
+            const metadata = getEventTypeMetadata(type);
+            if (metadata) {
+                const key = metadata.eventType.toString();
+                this._typesByGeneration.set(key, type);
+                const existing = this._latestTypes.get(metadata.eventType.id.value);
+                if (!existing) {
+                    this._latestTypes.set(metadata.eventType.id.value, type);
+                    continue;
+                }
+
+                const existingMetadata = getEventTypeMetadata(existing);
+                if (!existingMetadata || existingMetadata.eventType.generation.value < metadata.eventType.generation.value) {
+                    this._latestTypes.set(metadata.eventType.id.value, type);
+                }
+            }
+        }
+    }
+
+    /** @inheritdoc */
+    async register(): Promise<void> {
+        if (this._typesByGeneration.size === 0) {
+            await this.discover();
+        }
+
+        const groupedById = new Map<string, Constructor[]>();
+        for (const type of this._typesByGeneration.values()) {
+            const metadata = getEventTypeMetadata(type);
+            if (!metadata) {
+                continue;
+            }
+
+            const existing = groupedById.get(metadata.eventType.id.value) ?? [];
+            existing.push(type);
+            groupedById.set(metadata.eventType.id.value, existing);
+        }
+
+        const registrations = Array.from(groupedById.values()).map(group => {
+            const sorted = group
+                .map(type => ({ type, metadata: getEventTypeMetadata(type)! }))
+                .sort((a, b) => {
+                    const left = a.metadata.eventType.generation.value;
+                    const right = b.metadata.eventType.generation.value;
+                    if (left < right) {
+                        return -1;
+                    }
+                    if (left > right) {
+                        return 1;
+                    }
+                    return 0;
+                });
+            const latest = sorted[sorted.length - 1];
+            const registration = {
+                Type: {
+                    Id: latest.metadata.eventType.id.value,
+                    Generation: latest.metadata.eventType.generation.value,
+                    Tombstone: latest.metadata.eventType.tombstone
+                },
+                Schema: JSON.stringify(getEventTypeJsonSchemaFor(latest.type)),
+                Generations: sorted.map(({ type, metadata }) => ({
+                    Generation: metadata.eventType.generation.value,
+                    Schema: JSON.stringify(getEventTypeJsonSchemaFor(type))
+                })),
+                Migrations: [] as {
+                    FromGeneration: number;
+                    ToGeneration: number;
+                    UpcastJmesPath: string;
+                    DowncastJmesPath: string;
+                }[],
+                EventStore: this._eventStore
+            };
+
+            for (const { type } of sorted) {
+                const migratorTypes = this._eventTypeMigrators.getMigratorsFor(type);
+                for (const migratorType of migratorTypes) {
+                    const metadata = getEventTypeMigrationMetadata(migratorType);
+                    if (!metadata) {
+                        continue;
+                    }
+
+                    const migrator = new (migratorType as Constructor<IEventTypeMigration>)();
+                    const upcastBuilder = new EventMigrationBuilder<unknown, unknown>();
+                    migrator.upcast(upcastBuilder);
+
+                    const downcastBuilder = new EventMigrationBuilder<unknown, unknown>();
+                    migrator.downcast(downcastBuilder);
+
+                    registration.Migrations.push({
+                        FromGeneration: metadata.previousEventType.generation.value,
+                        ToGeneration: metadata.eventType.generation.value,
+                        UpcastJmesPath: JSON.stringify(upcastBuilder.toObject()),
+                        DowncastJmesPath: JSON.stringify(downcastBuilder.toObject())
+                    });
+
+                    if (!registration.Generations.some(_ => _.Generation === metadata.previousEventType.generation.value)) {
+                        registration.Generations.push({
+                            Generation: metadata.previousEventType.generation.value,
+                            Schema: UNKNOWN_GENERATION_SCHEMA
+                        });
+                    }
+                    if (!registration.Generations.some(_ => _.Generation === metadata.eventType.generation.value)) {
+                        registration.Generations.push({
+                            Generation: metadata.eventType.generation.value,
+                            Schema: UNKNOWN_GENERATION_SCHEMA
+                        });
+                    }
+                }
+            }
+
+            return registration;
+        });
+
+        if (registrations.length === 0) {
+            return;
+        }
+
+        await this._connection.eventTypes.register({
+            EventStore: this._eventStore,
+            Types: registrations,
+            DisableValidation: false
+        });
+    }
+
+    /** @inheritdoc */
+    hasFor(id: EventTypeId): boolean {
+        return this._latestTypes.has(id.value);
+    }
+
+    /** @inheritdoc */
+    getTypeFor(id: EventTypeId): Constructor {
+        const type = this._latestTypes.get(id.value);
+        if (!type) {
+            throw new Error(`No event type registered for id '${id.value}'.`);
+        }
+        return type;
+    }
+}

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,15 @@
+// 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';
+export * from './migrations';

package/events/migrations/EventMigrationBuilder.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EventMigrationPropertyBuilder } from './EventMigrationPropertyBuilder';
+import { IEventMigrationBuilder } from './IEventMigrationBuilder';
+
+/**
+ * Represents an implementation of {@link IEventMigrationBuilder}.
+ */
+export class EventMigrationBuilder<TTarget, TSource> implements IEventMigrationBuilder<TTarget, TSource> {
+    private readonly _propertyBuilders: EventMigrationPropertyBuilder<TTarget, TSource>[] = [];
+
+    /** @inheritdoc */
+    properties(properties: (builder: EventMigrationPropertyBuilder<TTarget, TSource>) => void): void {
+        const builder = new EventMigrationPropertyBuilder<TTarget, TSource>();
+        properties(builder);
+        this._propertyBuilders.push(builder);
+    }
+
+    /**
+     * Convert the builder to an object representation.
+     * @returns The migration object representation.
+     */
+    toObject(): Record<string, unknown> {
+        const result: Record<string, unknown> = {};
+        for (const builder of this._propertyBuilders) {
+            Object.assign(result, builder.properties);
+        }
+        return result;
+    }
+}

package/events/migrations/EventMigrationPropertyBuilder.ts

@@ -0,0 +1,77 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IEventMigrationPropertyBuilder } from './IEventMigrationPropertyBuilder';
+
+const SPLIT_EXPRESSION = '$split';
+const COMBINE_EXPRESSION = '$combine';
+const RENAME_EXPRESSION = '$rename';
+const DEFAULT_VALUE_EXPRESSION = '$defaultValue';
+
+/**
+ * Represents an implementation of {@link IEventMigrationPropertyBuilder}.
+ */
+export class EventMigrationPropertyBuilder<TTarget, TSource> implements IEventMigrationPropertyBuilder<TTarget, TSource> {
+    private readonly _properties: Record<string, unknown> = {};
+
+    /**
+     * Gets the configured properties.
+     */
+    get properties(): Record<string, unknown> {
+        return this._properties;
+    }
+
+    /** @inheritdoc */
+    split(
+        targetProperty: keyof TTarget & string,
+        sourceProperty: keyof TSource & string,
+        separator: string,
+        part: number
+    ): IEventMigrationPropertyBuilder<TTarget, TSource> {
+        this._properties[targetProperty] = {
+            [SPLIT_EXPRESSION]: {
+                source: sourceProperty,
+                separator,
+                part
+            }
+        };
+        return this;
+    }
+
+    /** @inheritdoc */
+    combine(
+        targetProperty: keyof TTarget & string,
+        separator: string,
+        ...sourceProperties: (keyof TSource & string)[]
+    ): IEventMigrationPropertyBuilder<TTarget, TSource> {
+        this._properties[targetProperty] = {
+            [COMBINE_EXPRESSION]: {
+                sources: sourceProperties,
+                separator
+            }
+        };
+        return this;
+    }
+
+    /** @inheritdoc */
+    renamedFrom(
+        targetProperty: keyof TTarget & string,
+        sourceProperty: keyof TSource & string
+    ): IEventMigrationPropertyBuilder<TTarget, TSource> {
+        this._properties[targetProperty] = {
+            [RENAME_EXPRESSION]: sourceProperty
+        };
+        return this;
+    }
+
+    /** @inheritdoc */
+    defaultValue(
+        targetProperty: keyof TTarget & string,
+        value: unknown
+    ): IEventMigrationPropertyBuilder<TTarget, TSource> {
+        this._properties[targetProperty] = {
+            [DEFAULT_VALUE_EXPRESSION]: value
+        };
+        return this;
+    }
+}

package/events/migrations/EventTypeMigrators.ts

@@ -0,0 +1,48 @@
+// 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 { getEventTypeFor } from '../eventTypeDecorator';
+import { getEventTypeMigrationMetadata } from './eventTypeMigration';
+import { IEventTypeMigrators } from './IEventTypeMigrators';
+
+/**
+ * Represents an implementation of {@link IEventTypeMigrators}.
+ */
+export class EventTypeMigrators implements IEventTypeMigrators {
+    private readonly _migratorsByEventType = new Map<string, Constructor[]>();
+
+    /**
+     * Initializes a new instance of the {@link EventTypeMigrators} class.
+     * @param _clientArtifacts - The client artifact provider used to discover migrators.
+     */
+    constructor(private readonly _clientArtifacts: IClientArtifactsProvider) {}
+
+    /** @inheritdoc */
+    get allMigrators(): Constructor[] {
+        return this._clientArtifacts.eventTypeMigrations;
+    }
+
+    /** @inheritdoc */
+    getMigratorsFor(eventType: Constructor): Constructor[] {
+        const key = this.getEventTypeKey(eventType);
+        const cached = this._migratorsByEventType.get(key);
+        if (cached) {
+            return cached;
+        }
+
+        const migrators = this._clientArtifacts.eventTypeMigrations
+            .filter(migratorType => {
+                const metadata = getEventTypeMigrationMetadata(migratorType);
+                return metadata?.eventType.toString() === key;
+            });
+
+        this._migratorsByEventType.set(key, migrators);
+        return migrators;
+    }
+
+    private getEventTypeKey(eventType: Constructor): string {
+        return getEventTypeFor(eventType).toString();
+    }
+}

package/events/migrations/IEventMigrationBuilder.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IEventMigrationPropertyBuilder } from './IEventMigrationPropertyBuilder';
+
+/**
+ * Defines a builder for event migrations.
+ */
+export interface IEventMigrationBuilder<TTarget, TSource> {
+    /**
+     * Define property migrations.
+     * @param properties - Callback used to configure property migration operations.
+     */
+    properties(properties: (builder: IEventMigrationPropertyBuilder<TTarget, TSource>) => void): void;
+}

package/events/migrations/IEventMigrationPropertyBuilder.ts

@@ -0,0 +1,57 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Defines a builder for event migration property transformations.
+ */
+export interface IEventMigrationPropertyBuilder<TTarget, TSource> {
+    /**
+     * Split a source property value into a target property by extracting one part.
+     * @param targetProperty - The target property to write into.
+     * @param sourceProperty - The source property to split.
+     * @param separator - The separator to split by.
+     * @param part - The zero-based part index to extract.
+     * @returns The builder for continued configuration.
+     */
+    split(
+        targetProperty: keyof TTarget & string,
+        sourceProperty: keyof TSource & string,
+        separator: string,
+        part: number
+    ): IEventMigrationPropertyBuilder<TTarget, TSource>;
+
+    /**
+     * Combine multiple source properties into a single target property by concatenation.
+     * @param targetProperty - The target property to write into.
+     * @param separator - The separator inserted between source values.
+     * @param sourceProperties - Source properties to concatenate.
+     * @returns The builder for continued configuration.
+     */
+    combine(
+        targetProperty: keyof TTarget & string,
+        separator: string,
+        ...sourceProperties: (keyof TSource & string)[]
+    ): IEventMigrationPropertyBuilder<TTarget, TSource>;
+
+    /**
+     * Rename a source property to a target property.
+     * @param targetProperty - The new target property.
+     * @param sourceProperty - The existing source property.
+     * @returns The builder for continued configuration.
+     */
+    renamedFrom(
+        targetProperty: keyof TTarget & string,
+        sourceProperty: keyof TSource & string
+    ): IEventMigrationPropertyBuilder<TTarget, TSource>;
+
+    /**
+     * Provide a default value for a target property.
+     * @param targetProperty - The target property.
+     * @param value - The default value.
+     * @returns The builder for continued configuration.
+     */
+    defaultValue(
+        targetProperty: keyof TTarget & string,
+        value: unknown
+    ): IEventMigrationPropertyBuilder<TTarget, TSource>;
+}

package/events/migrations/IEventTypeMigration.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IEventMigrationBuilder } from './IEventMigrationBuilder';
+
+/**
+ * Defines an event type migration.
+ */
+export interface IEventTypeMigration<TTarget = unknown, TSource = unknown> {
+    /**
+     * Define the upcast migration.
+     * @param builder - The migration builder to use.
+     */
+    upcast(builder: IEventMigrationBuilder<TTarget, TSource>): void;
+
+    /**
+     * Define the downcast migration.
+     * @param builder - The migration builder to use.
+     */
+    downcast(builder: IEventMigrationBuilder<TSource, TTarget>): void;
+}

package/events/migrations/IEventTypeMigrators.ts

@@ -0,0 +1,21 @@
+// 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';
+
+/**
+ * Defines a system that discovers and provides event type migrators.
+ */
+export interface IEventTypeMigrators {
+    /**
+     * Gets all discovered migrator types.
+     */
+    readonly allMigrators: Constructor[];
+
+    /**
+     * Gets all migrator types for a specific event type.
+     * @param eventType - The event type constructor to get migrators for.
+     * @returns Collection of migrator constructors.
+     */
+    getMigratorsFor(eventType: Constructor): Constructor[];
+}

package/events/migrations/InvalidMigrationGenerationGap.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.
+
+/**
+ * Exception thrown when a migration does not connect adjacent generations.
+ */
+export class InvalidMigrationGenerationGap extends Error {
+    constructor(
+        previousTypeName: string,
+        upgradeTypeName: string,
+        previousGeneration: number,
+        upgradeGeneration: number
+    ) {
+        super(
+            `Migration from '${previousTypeName}' (generation ${previousGeneration}) to '${upgradeTypeName}' ` +
+            `(generation ${upgradeGeneration}) is invalid. The upgrade generation must be exactly one more than the previous generation.`
+        );
+    }
+}