@cratis/chronicle 0.0.1

package/Events/AppendedEvent.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.
+
+import { EventContext } from './EventContext';
+import { EventType } from './EventType';
+
+/**
+ * Represents an event that has been appended to an event sequence.
+ */
+export interface AppendedEvent<TContent = Record<string, unknown>> {
+    /** The context of the event. */
+    readonly context: EventContext;
+
+    /** The type of the event. */
+    readonly eventType: EventType;
+
+    /** The deserialized content of the event. */
+    readonly content: TContent;
+}

package/Events/CausationEntry.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents a single entry in the causation chain of an event.
+ */
+export interface CausationEntry {
+    /** The type identifier of the causing operation. */
+    readonly type: string;
+
+    /** The properties associated with the causation entry. */
+    readonly properties: Readonly<Record<string, string>>;
+}

package/Events/Constraints/ConstraintBuilder.ts

@@ -0,0 +1,86 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { getEventTypeFor } from '../eventTypeDecorator';
+import { IConstraintBuilder } from './IConstraintBuilder';
+import { IUniqueConstraintBuilder } from './IUniqueConstraintBuilder';
+import { UniqueConstraintBuilder, UniqueConstraintCapture } from './UniqueConstraintBuilder';
+
+/** Represents the captured scope for a constraint. */
+export interface ConstraintScopeCapture {
+    perEventSourceType: boolean;
+    perEventStreamType: boolean;
+    perEventStreamId: boolean;
+}
+
+/** Represents the captured definition of a unique event type constraint. */
+export interface UniqueEventTypeCapture {
+    eventTypeId: string;
+    message?: string;
+    name?: string;
+}
+
+/** Represents the full captured definition of a constraint. */
+export interface ConstraintCapture {
+    name: string;
+    scope: ConstraintScopeCapture;
+    uniqueConstraint?: UniqueConstraintCapture;
+    uniqueEventType?: UniqueEventTypeCapture;
+}
+
+/**
+ * Implements {@link IConstraintBuilder}, capturing the constraint definition
+ * for later serialization and registration with the Kernel.
+ */
+export class ConstraintBuilder implements IConstraintBuilder {
+    readonly capture: ConstraintCapture;
+    private _uniqueBuilder?: UniqueConstraintBuilder;
+
+    constructor(name: string) {
+        this.capture = {
+            name,
+            scope: { perEventSourceType: false, perEventStreamType: false, perEventStreamId: false }
+        };
+    }
+
+    /** @inheritdoc */
+    perEventSourceType(): IConstraintBuilder {
+        this.capture.scope.perEventSourceType = true;
+        return this;
+    }
+
+    /** @inheritdoc */
+    perEventStreamType(): IConstraintBuilder {
+        this.capture.scope.perEventStreamType = true;
+        return this;
+    }
+
+    /** @inheritdoc */
+    perEventStreamId(): IConstraintBuilder {
+        this.capture.scope.perEventStreamId = true;
+        return this;
+    }
+
+    /** @inheritdoc */
+    unique(callback: (builder: IUniqueConstraintBuilder) => void): IConstraintBuilder {
+        const uniqueCapture: UniqueConstraintCapture = {
+            eventDefinitions: [],
+            ignoreCasing: false
+        };
+        this.capture.uniqueConstraint = uniqueCapture;
+        this._uniqueBuilder = new UniqueConstraintBuilder(uniqueCapture);
+        callback(this._uniqueBuilder);
+        return this;
+    }
+
+    /** @inheritdoc */
+    uniqueFor(eventType: Function, message?: string, name?: string): IConstraintBuilder {
+        const et = getEventTypeFor(eventType);
+        this.capture.uniqueEventType = {
+            eventTypeId: et.id.value,
+            message,
+            name
+        };
+        return this;
+    }
+}

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

package/Events/Constraints/Constraints.ts

@@ -0,0 +1,117 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ConstraintType } from '@cratis/chronicle.contracts';
+import { IClientArtifactsProvider } from '../../artifacts';
+import { ChronicleConnection } from '../../connection';
+import { ConstraintId } from './ConstraintId';
+import { IConstraint } from './IConstraint';
+import { IConstraints } from './IConstraints';
+import { ConstraintBuilder, ConstraintCapture } from './ConstraintBuilder';
+import { getConstraintMetadata } from './constraint';
+
+/**
+ * Manages discovery and registration of constraints with the Chronicle Kernel.
+ */
+export class Constraints implements IConstraints {
+    private readonly _captures = new Map<string, ConstraintCapture>();
+
+    /**
+     * Creates a new {@link Constraints} instance.
+     * @param _eventStore - The name of the event store these constraints 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 */
+    async discover(): Promise<void> {
+        this._captures.clear();
+        for (const type of this._clientArtifacts.constraints) {
+            const metadata = getConstraintMetadata(type);
+            if (!metadata) continue;
+
+            const builder = new ConstraintBuilder(metadata.id.value);
+            const instance = new (type as new () => IConstraint)();
+            instance.define(builder);
+            this._captures.set(metadata.id.value, builder.capture);
+        }
+    }
+
+    /** @inheritdoc */
+    async register(): Promise<void> {
+        if (this._captures.size === 0) {
+            await this.discover();
+        }
+
+        const constraints = [...this._captures.values()].map(capture => {
+            const scope = {
+                EventSourceType: capture.scope.perEventSourceType ? '*' : '',
+                EventStreamType: capture.scope.perEventStreamType ? '*' : '',
+                EventStreamId: capture.scope.perEventStreamId ? '*' : ''
+            };
+
+            if (capture.uniqueConstraint) {
+                const uc = capture.uniqueConstraint;
+                return {
+                    Name: capture.name,
+                    Type: ConstraintType.Unique,
+                    RemovedWith: uc.removedWithEventTypeId ?? '',
+                    Definition: {
+                        Value0: {
+                            EventDefinitions: uc.eventDefinitions.map(ed => ({
+                                EventTypeId: ed.eventTypeId,
+                                Properties: ed.properties
+                            })),
+                            IgnoreCasing: uc.ignoreCasing
+                        },
+                        Value1: undefined
+                    },
+                    Scope: scope
+                };
+            }
+
+            if (capture.uniqueEventType) {
+                const uet = capture.uniqueEventType;
+                return {
+                    Name: uet.name ?? capture.name,
+                    Type: ConstraintType.UniqueEventType,
+                    RemovedWith: '',
+                    Definition: {
+                        Value0: undefined,
+                        Value1: {
+                            EventTypeId: uet.eventTypeId
+                        }
+                    },
+                    Scope: scope
+                };
+            }
+
+            return {
+                Name: capture.name,
+                Type: ConstraintType.Unknown,
+                RemovedWith: '',
+                Definition: undefined,
+                Scope: scope
+            };
+        });
+
+        if (constraints.length === 0) {
+            return;
+        }
+
+        await this._connection.constraints.register({
+            EventStore: this._eventStore,
+            Constraints: constraints
+        });
+    }
+
+    /** @inheritdoc */
+    hasFor(id: ConstraintId): boolean {
+        return this._captures.has(id.value);
+    }
+}

package/Events/Constraints/IConstraint.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.
+
+import { IConstraintBuilder } from './IConstraintBuilder';
+
+/**
+ * Defines a constraint for events.
+ * Implement this interface on any class decorated with {@link constraint} to describe
+ * the constraint rules that the Chronicle server should enforce.
+ * Matches the C# IConstraint contract.
+ */
+export interface IConstraint {
+    /**
+     * Defines the constraint rules.
+     * @param builder - The {@link IConstraintBuilder} used to configure constraint rules.
+     */
+    define(builder: IConstraintBuilder): void;
+}

package/Events/Constraints/IConstraintBuilder.ts

@@ -0,0 +1,44 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IUniqueConstraintBuilder } from './IUniqueConstraintBuilder';
+
+/**
+ * Defines the builder for building constraints.
+ * Matches the C# IConstraintBuilder contract.
+ */
+export interface IConstraintBuilder {
+    /**
+     * Scopes the constraint per event source type.
+     * @returns This builder for fluent chaining.
+     */
+    perEventSourceType(): IConstraintBuilder;
+
+    /**
+     * Scopes the constraint per event stream type.
+     * @returns This builder for fluent chaining.
+     */
+    perEventStreamType(): IConstraintBuilder;
+
+    /**
+     * Scopes the constraint per event stream identifier.
+     * @returns This builder for fluent chaining.
+     */
+    perEventStreamId(): IConstraintBuilder;
+
+    /**
+     * Starts building a unique constraint using a fluent builder callback.
+     * @param callback - Callback that configures the unique constraint via {@link IUniqueConstraintBuilder}.
+     * @returns This builder for fluent chaining.
+     */
+    unique(callback: (builder: IUniqueConstraintBuilder) => void): IConstraintBuilder;
+
+    /**
+     * Adds a unique constraint for a specific event type.
+     * This means there can only be one instance of this event type per event source identifier.
+     * @param message - Optional violation message.
+     * @param name - Optional constraint name.
+     * @returns This builder for fluent chaining.
+     */
+    uniqueFor(eventType: Function, message?: string, name?: string): IConstraintBuilder;
+}

package/Events/Constraints/IConstraints.ts

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

package/Events/Constraints/IUniqueConstraintBuilder.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PropertyAccessor } from '@cratis/fundamentals';
+
+/**
+ * Defines the builder for building unique constraints.
+ * Matches the C# IUniqueConstraintBuilder contract.
+ */
+export interface IUniqueConstraintBuilder {
+    /**
+     * Defines the name of the unique constraint.
+     * The name is optional and if not provided, it will use the type name the constraint belongs to.
+     * @param name - Name to use.
+     * @returns This builder for fluent chaining.
+     */
+    withName(name: string): IUniqueConstraintBuilder;
+
+    /**
+     * Constrains on specific properties of an event type.
+     * @param properties - Property accessor expressions for specifying the properties on the event.
+     * @returns This builder for fluent chaining.
+     */
+    on<TEvent>(...properties: PropertyAccessor<TEvent>[]): IUniqueConstraintBuilder;
+
+    /**
+     * Ignores casing when comparing property values during constraint evaluation.
+     * @returns This builder for fluent chaining.
+     */
+    ignoreCasing(): IUniqueConstraintBuilder;
+
+    /**
+     * Specifies the event type that removes this unique constraint (e.g. a deletion event).
+     * @param eventType - The event constructor that removes the constraint.
+     * @returns This builder for fluent chaining.
+     */
+    removedWith(eventType: Function): IUniqueConstraintBuilder;
+
+    /**
+     * Specifies a static message to use when the unique constraint is violated.
+     * @param message - The violation message.
+     * @returns This builder for fluent chaining.
+     */
+    withMessage(message: string): IUniqueConstraintBuilder;
+
+    /**
+     * Specifies a provider function that produces the violation message dynamically.
+     * @param messageProvider - Callback that returns the violation message.
+     * @returns This builder for fluent chaining.
+     */
+    withMessageFrom(messageProvider: () => string): IUniqueConstraintBuilder;
+}

package/Events/Constraints/UniqueConstraintBuilder.ts

@@ -0,0 +1,97 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
+import { getEventTypeFor } from '../eventTypeDecorator';
+import { IUniqueConstraintBuilder } from './IUniqueConstraintBuilder';
+
+/** Resolves a property path string from a {@link PropertyAccessor}. */
+function resolvePropertyPath<T>(accessor: PropertyAccessor<T>): string {
+    const handler = new PropertyPathResolverProxyHandler();
+    const proxy = new Proxy({}, handler);
+    accessor(proxy as T);
+    return handler.path;
+}
+
+/** Captured definition of a unique constraint event entry. */
+export interface UniqueConstraintEventEntry {
+    eventTypeId: string;
+    properties: string[];
+}
+
+/** Captured definition of a unique constraint. */
+export interface UniqueConstraintCapture {
+    name?: string;
+    eventDefinitions: UniqueConstraintEventEntry[];
+    ignoreCasing: boolean;
+    removedWithEventTypeId?: string;
+    message?: string;
+}
+
+/**
+ * Implements {@link IUniqueConstraintBuilder}, capturing the unique constraint definition
+ * for later serialization and registration with the Kernel.
+ */
+export class UniqueConstraintBuilder implements IUniqueConstraintBuilder {
+    private readonly _capture: UniqueConstraintCapture;
+    private _currentEventTypeId?: string;
+
+    constructor(capture: UniqueConstraintCapture) {
+        this._capture = capture;
+    }
+
+    /** @inheritdoc */
+    withName(name: string): IUniqueConstraintBuilder {
+        this._capture.name = name;
+        return this;
+    }
+
+    /** @inheritdoc */
+    on<TEvent>(...properties: PropertyAccessor<TEvent>[]): IUniqueConstraintBuilder {
+        if (!this._currentEventTypeId) {
+            return this;
+        }
+        const paths = properties.map(p => resolvePropertyPath(p));
+        const existing = this._capture.eventDefinitions.find(d => d.eventTypeId === this._currentEventTypeId);
+        if (existing) {
+            existing.properties.push(...paths);
+        } else {
+            this._capture.eventDefinitions.push({ eventTypeId: this._currentEventTypeId, properties: paths });
+        }
+        return this;
+    }
+
+    /** @inheritdoc */
+    ignoreCasing(): IUniqueConstraintBuilder {
+        this._capture.ignoreCasing = true;
+        return this;
+    }
+
+    /** @inheritdoc */
+    removedWith(eventType: Function): IUniqueConstraintBuilder {
+        const et = getEventTypeFor(eventType);
+        this._capture.removedWithEventTypeId = et.id.value;
+        return this;
+    }
+
+    /** @inheritdoc */
+    withMessage(message: string): IUniqueConstraintBuilder {
+        this._capture.message = message;
+        return this;
+    }
+
+    /** @inheritdoc */
+    withMessageFrom(messageProvider: () => string): IUniqueConstraintBuilder {
+        this._capture.message = messageProvider();
+        return this;
+    }
+
+    /**
+     * Sets the current event type context for subsequent {@link on} calls.
+     * @param eventTypeId - The event type identifier string.
+     */
+    withEventType(eventTypeId: string): UniqueConstraintBuilder {
+        this._currentEventTypeId = eventTypeId;
+        return this;
+    }
+}

package/Events/Constraints/constraint.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 'reflect-metadata';
+import { Constructor } from '@cratis/fundamentals';
+import { ConstraintId } from './ConstraintId';
+import { DecoratorType, TypeDiscoverer } from '../../types';
+
+/** Metadata key used to store constraint information on a class. */
+const CONSTRAINT_METADATA_KEY = 'chronicle:constraint';
+
+/**
+ * Metadata stored on a constraint class.
+ */
+export interface ConstraintMetadata {
+    /** The unique identifier for the constraint. */
+    readonly id: ConstraintId;
+}
+
+/**
+ * TypeScript decorator that marks a class as an event constraint.
+ * The decorated class may implement {@link IConstraint} to define the constraint rules.
+ * @param id - The unique identifier for the constraint. Defaults to the class name if omitted.
+ * @returns A class decorator.
+ */
+export function constraint(id: string = ''): ClassDecorator {
+    return (target: object) => {
+        const constructor = target as Function;
+        const constraintId = new ConstraintId(id || constructor.name);
+        const metadata: ConstraintMetadata = { id: constraintId };
+        Reflect.defineMetadata(CONSTRAINT_METADATA_KEY, metadata, target);
+        TypeDiscoverer.default.register(
+            DecoratorType.Constraint,
+            constructor as Constructor,
+            constraintId.value
+        );
+    };
+}
+
+/**
+ * Gets the {@link ConstraintMetadata} associated with a class decorated with {@link constraint}.
+ * @param target - The class constructor to retrieve metadata for.
+ * @returns The associated metadata, or undefined if not decorated.
+ */
+export function getConstraintMetadata(target: Function): ConstraintMetadata | undefined {
+    return Reflect.getMetadata(CONSTRAINT_METADATA_KEY, target);
+}
+
+/**
+ * Checks whether a class has been decorated with {@link constraint}.
+ * @param target - The class constructor to check.
+ * @returns True if the class has a constraint decorator; false otherwise.
+ */
+export function isConstraint(target: Function): boolean {
+    return Reflect.hasMetadata(CONSTRAINT_METADATA_KEY, target);
+}

package/Events/Constraints/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 { ConstraintId } from './ConstraintId';
+export type { IConstraint } from './IConstraint';
+export type { IConstraintBuilder } from './IConstraintBuilder';
+export type { IUniqueConstraintBuilder } from './IUniqueConstraintBuilder';
+export { constraint, getConstraintMetadata, isConstraint } from './constraint';
+export type { ConstraintMetadata } from './constraint';
+export type { IConstraints } from './IConstraints';
+export { Constraints } from './Constraints';
+export { ConstraintBuilder } from './ConstraintBuilder';
+export type { ConstraintCapture, ConstraintScopeCapture, UniqueEventTypeCapture } from './ConstraintBuilder';
+export { UniqueConstraintBuilder } from './UniqueConstraintBuilder';
+export type { UniqueConstraintCapture, UniqueConstraintEventEntry } from './UniqueConstraintBuilder';

package/Events/EventContext.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EventType } from './EventType';
+import { CausationEntry } from './CausationEntry';
+
+/**
+ * Represents contextual information about an appended event.
+ */
+export interface EventContext {
+    /** The sequence number of the event in the event sequence. */
+    readonly sequenceNumber: number;
+
+    /** The unique identifier of the event source. */
+    readonly eventSourceId: string;
+
+    /** The type of the event. */
+    readonly eventType: EventType;
+
+    /** The timestamp when the event occurred. */
+    readonly occurred: Date;
+
+    /** The correlation identifier for the event. */
+    readonly correlationId: string;
+
+    /** The causation chain for the event. */
+    readonly causation: ReadonlyArray<CausationEntry>;
+}

package/Events/EventType.ts

@@ -0,0 +1,41 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EventTypeId } from './EventTypeId';
+import { EventTypeGeneration } from './EventTypeGeneration';
+
+/**
+ * Represents the type of an event.
+ */
+export class EventType {
+    /** Represents an unknown event type. */
+    static readonly unknown = new EventType(EventTypeId.unknown, EventTypeGeneration.first, false);
+
+    constructor(
+        readonly id: EventTypeId,
+        readonly generation: EventTypeGeneration,
+        readonly tombstone: boolean = false
+    ) {}
+
+    /** @inheritdoc */
+    toString(): string {
+        return `${this.id.value}+${this.generation.value}`;
+    }
+
+    /**
+     * Parse from a string representation of event type to actual type.
+     * The expected format is id+generation. Ex: EmployeeHired+1.
+     * @param input - The string representation to parse.
+     * @returns The parsed EventType.
+     */
+    static parse(input: string): EventType {
+        const segments = input.split('+');
+        if (segments.length === 1) {
+            return new EventType(new EventTypeId(segments[0]), EventTypeGeneration.first, false);
+        }
+        if (segments.length === 2) {
+            return new EventType(new EventTypeId(segments[0]), new EventTypeGeneration(parseInt(segments[1], 10)), false);
+        }
+        return new EventType(new EventTypeId(segments[0]), new EventTypeGeneration(parseInt(segments[1], 10)), segments[2] === 'true');
+    }
+}

package/Events/EventTypeGeneration.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents the generation of an event type.
+ */
+export class EventTypeGeneration {
+    /** The first generation value. */
+    static readonly firstValue = 1;
+
+    /** The first generation of any event type. */
+    static readonly first = new EventTypeGeneration(EventTypeGeneration.firstValue);
+
+    constructor(readonly value: number) {}
+
+    /** @inheritdoc */
+    toString(): string {
+        return this.value.toString();
+    }
+}

package/Events/EventTypeId.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.
+
+/**
+ * Represents the unique identifier for an event type.
+ */
+export class EventTypeId {
+    /**
+     * Represents an unknown event type identifier.
+     */
+    static readonly unknown = new EventTypeId('00000000-0000-0000-0000-000000000000');
+
+    constructor(readonly value: string) {}
+
+    /** @inheritdoc */
+    toString(): string {
+        return this.value;
+    }
+}