@cratis/chronicle 0.1.0 → 0.2.0

package/seeding/IEventSeedingBuilder.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EventStoreNamespaceName } from '../EventStoreNamespaceName';
+import { IEventSeedingScopeBuilder } from './IEventSeedingScopeBuilder';
+
+/**
+ * Defines a builder for seeding events in the event store.
+ */
+export interface IEventSeedingBuilder {
+    /**
+     * Seeds events for a specific event source id.
+     * By default, seed data applies to all namespaces globally.
+     * @param eventSourceId - The event source id to seed for.
+     * @param events - The events to seed.
+     * @returns The builder for chaining.
+     */
+    for<TEvent extends object>(eventSourceId: string, events: Iterable<TEvent>): IEventSeedingBuilder;
+
+    /**
+     * Seeds events of multiple types for a specific event source id.
+     * By default, seed data applies to all namespaces globally.
+     * @param eventSourceId - The event source id to seed for.
+     * @param events - The events to seed.
+     * @returns The builder for chaining.
+     */
+    forEventSource(eventSourceId: string, events: Iterable<object>): IEventSeedingBuilder;
+
+    /**
+     * Configures seed data to be specific to a namespace.
+     * @param namespace - The namespace to seed for.
+     * @returns A scoped builder for namespace-specific seed data.
+     */
+    forNamespace(namespace: string | EventStoreNamespaceName): IEventSeedingScopeBuilder;
+}

package/seeding/IEventSeedingScopeBuilder.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Defines a scoped builder for namespace-specific event seeding.
+ */
+export interface IEventSeedingScopeBuilder {
+    /**
+     * Seeds events for a specific event source id.
+     * @param eventSourceId - The event source id to seed for.
+     * @param events - The events to seed.
+     * @returns The scoped builder for chaining.
+     */
+    for<TEvent extends object>(eventSourceId: string, events: Iterable<TEvent>): IEventSeedingScopeBuilder;
+
+    /**
+     * Seeds events of multiple types for a specific event source id.
+     * @param eventSourceId - The event source id to seed for.
+     * @param events - The events to seed.
+     * @returns The scoped builder for chaining.
+     */
+    forEventSource(eventSourceId: string, events: Iterable<object>): IEventSeedingScopeBuilder;
+}

package/seeding/index.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export type { ICanSeedEvents } from './ICanSeedEvents';
+export type { IEventSeedingScopeBuilder } from './IEventSeedingScopeBuilder';
+export type { IEventSeedingBuilder } from './IEventSeedingBuilder';
+export type { IEventSeeding } from './IEventSeeding';
+export { seeder, getSeederMetadata, isSeeder } from './seeder';
+export type { SeederMetadata } from './seeder';
+export { EventSeeding } from './EventSeeding';

package/seeding/seeder.ts

@@ -0,0 +1,54 @@
+// 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 { DecoratorType, TypeDiscoverer } from '../types';
+
+/** Metadata key used to store seeder information on a class. */
+const SEEDER_METADATA_KEY = 'chronicle:seeder';
+
+/**
+ * Metadata stored on a seeder class.
+ */
+export interface SeederMetadata {
+    /** Marker indicating this type is an event seeder. */
+    readonly isSeeder: true;
+}
+
+/**
+ * TypeScript decorator that marks a class as an event seeder.
+ * This is the TypeScript equivalent of a discoverable event seeder artifact.
+ *
+ * @returns A class decorator.
+ */
+export function seeder(): ClassDecorator {
+    return (target: object) => {
+        const constructor = target as Function;
+        const metadata: SeederMetadata = { isSeeder: true };
+        Reflect.defineMetadata(SEEDER_METADATA_KEY, metadata, target);
+        TypeDiscoverer.default.register(
+            DecoratorType.Seeder,
+            constructor as Constructor,
+            constructor.name
+        );
+    };
+}
+
+/**
+ * Gets the {@link SeederMetadata} associated with a class decorated with {@link seeder}.
+ * @param target - The class constructor to retrieve metadata for.
+ * @returns The associated metadata, or undefined if not decorated.
+ */
+export function getSeederMetadata(target: Function): SeederMetadata | undefined {
+    return Reflect.getMetadata(SEEDER_METADATA_KEY, target);
+}
+
+/**
+ * Checks whether a class has been decorated with {@link seeder}.
+ * @param target - The class constructor to check.
+ * @returns True if the class has a seeder decorator; otherwise false.
+ */
+export function isSeeder(target: Function): boolean {
+    return getSeederMetadata(target) !== undefined;
+}

package/transactions/IUnitOfWork.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 { Guid } from '@cratis/fundamentals';
+import { EventSequenceId } from '../eventSequences/EventSequenceId';
+import { AppendResult } from '../eventSequences/AppendResult';
+
+/**
+ * Represents a unit of work for buffering event appends and committing them as transactions.
+ */
+export interface IUnitOfWork {
+    /** The correlation identifier used for all appends within this unit of work. */
+    readonly correlationId: Guid;
+
+    /** Whether the unit of work has been completed (committed or rolled back). */
+    readonly isCompleted: boolean;
+
+    /** Whether all append operations in this unit of work succeeded. */
+    readonly isSuccess: boolean;
+
+    /**
+     * Adds an event to the unit of work.
+     * @param eventSequenceId - The identifier of the event sequence to append to.
+     * @param eventSourceId - The event source identifier.
+     * @param event - The event payload.
+     */
+    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object): void;
+
+    /**
+     * Gets all events currently buffered in this unit of work.
+     * @returns The buffered events in append order.
+     */
+    getEvents(): ReadonlyArray<object>;
+
+    /**
+     * Gets append results from the latest commit.
+     * @returns The append results in append order.
+     */
+    getAppendResults(): ReadonlyArray<AppendResult>;
+
+    /**
+     * Commits all buffered events.
+     */
+    commit(): Promise<void>;
+
+    /**
+     * Rolls back all buffered events.
+     */
+    rollback(): Promise<void>;
+
+    /**
+     * Sets a callback that runs when the unit of work completes.
+     * @param callback - Callback to invoke on completion.
+     */
+    onCompleted(callback: (unitOfWork: IUnitOfWork) => void): void;
+}

package/transactions/IUnitOfWorkManager.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Guid } from '@cratis/fundamentals';
+import { IUnitOfWork } from './IUnitOfWork';
+
+/**
+ * Defines an API for managing units of work in the active async context.
+ */
+export interface IUnitOfWorkManager {
+    /** The current unit of work for the active async context. */
+    readonly current: IUnitOfWork;
+
+    /** Whether there is a current unit of work for the active async context. */
+    readonly hasCurrent: boolean;
+
+    /**
+     * Tries to get a unit of work by correlation identifier.
+     * @param correlationId - Correlation identifier to look up.
+     * @returns The unit of work if found; otherwise undefined.
+     */
+    tryGetFor(correlationId: string | Guid): IUnitOfWork | undefined;
+
+    /**
+     * Begins a new unit of work in the active async context.
+     * @param correlationId - Optional correlation identifier. A new one is generated if omitted.
+     * @returns The created unit of work.
+     */
+    begin(correlationId?: string | Guid): IUnitOfWork;
+
+    /**
+     * Sets the current unit of work for the active async context.
+     * @param unitOfWork - The unit of work to set as current.
+     */
+    setCurrent(unitOfWork: IUnitOfWork): void;
+}

package/transactions/NoUnitOfWorkHasBeenStarted.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.
+
+/**
+ * Error thrown when there is no current unit of work for the active async context.
+ */
+export class NoUnitOfWorkHasBeenStarted extends Error {
+    /**
+     * Initializes a new instance of the {@link NoUnitOfWorkHasBeenStarted} class.
+     */
+    constructor() {
+        super('No unit of work has been started for the current async context.');
+    }
+}

package/transactions/UnitOfWork.ts

@@ -0,0 +1,132 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Guid } from '@cratis/fundamentals';
+import { AppendResult } from '../eventSequences/AppendResult';
+import { EventForEventSourceId } from '../eventSequences/EventForEventSourceId';
+import { EventSequenceId } from '../eventSequences/EventSequenceId';
+import { IEventStore } from '../IEventStore';
+import { IUnitOfWork } from './IUnitOfWork';
+
+interface EventForEventSourceIdWithSequenceNumber {
+    readonly sequenceNumber: number;
+    readonly eventSequenceId: EventSequenceId;
+    readonly eventForEventSourceId: EventForEventSourceId;
+}
+
+/**
+ * Represents a unit of work that buffers events and commits them as transaction-like append operations.
+ */
+export class UnitOfWork implements IUnitOfWork {
+    private _events: EventForEventSourceIdWithSequenceNumber[] = [];
+    private _appendResults: AppendResult[] = [];
+    private _isCommitted = false;
+    private _isRolledBack = false;
+    private _onCompleted: (unitOfWork: IUnitOfWork) => void;
+
+    constructor(
+        readonly correlationId: Guid,
+        onCompleted: (unitOfWork: IUnitOfWork) => void,
+        private readonly _eventStore: IEventStore
+    ) {
+        this._onCompleted = onCompleted;
+    }
+
+    /** @inheritdoc */
+    get isCompleted(): boolean {
+        return this._isCommitted || this._isRolledBack;
+    }
+
+    /** @inheritdoc */
+    get isSuccess(): boolean {
+        return this._appendResults.every(_ => _.isSuccess);
+    }
+
+    /** @inheritdoc */
+    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object): void {
+        this.throwIfCompleted();
+        this._events.push({
+            sequenceNumber: this._events.length,
+            eventSequenceId,
+            eventForEventSourceId: {
+                eventSourceId,
+                event
+            }
+        });
+    }
+
+    /** @inheritdoc */
+    getEvents(): ReadonlyArray<object> {
+        return this._events.map(_ => _.eventForEventSourceId.event);
+    }
+
+    /** @inheritdoc */
+    getAppendResults(): ReadonlyArray<AppendResult> {
+        return this._appendResults;
+    }
+
+    /** @inheritdoc */
+    async commit(): Promise<void> {
+        this.throwIfCompleted();
+
+        if (this._events.length > 0) {
+            const resultsBySequenceNumber = new Map<number, AppendResult>();
+            const eventsByEventSequence = new Map<string, EventForEventSourceIdWithSequenceNumber[]>();
+
+            for (const eventToAppend of this._events) {
+                const key = eventToAppend.eventSequenceId.value;
+                const events = eventsByEventSequence.get(key) ?? [];
+                events.push(eventToAppend);
+                eventsByEventSequence.set(key, events);
+            }
+
+            for (const [eventSequenceId, eventsForSequence] of eventsByEventSequence) {
+                const sequence = this._eventStore.getEventSequence(new EventSequenceId(eventSequenceId));
+                const appendResults = await sequence.appendMany(
+                    eventsForSequence.map(_ => _.eventForEventSourceId),
+                    { correlationId: this.correlationId }
+                );
+
+                appendResults.forEach((appendResult, index) => {
+                    resultsBySequenceNumber.set(eventsForSequence[index].sequenceNumber, appendResult);
+                });
+            }
+
+            this._appendResults = [...resultsBySequenceNumber.entries()]
+                .sort(([left], [right]) => left - right)
+                .map(([, appendResult]) => appendResult);
+        } else {
+            this._appendResults = [];
+        }
+
+        this._isCommitted = true;
+        this._onCompleted(this);
+    }
+
+    /** @inheritdoc */
+    async rollback(): Promise<void> {
+        this.throwIfCompleted();
+        this._isRolledBack = true;
+        this._events = [];
+        this._appendResults = [];
+        this._onCompleted(this);
+    }
+
+    /** @inheritdoc */
+    onCompleted(callback: (unitOfWork: IUnitOfWork) => void): void {
+        const previous = this._onCompleted;
+        this._onCompleted = unitOfWork => {
+            previous(unitOfWork);
+            callback(unitOfWork);
+        };
+    }
+
+    private throwIfCompleted(): void {
+        if (this._isCommitted) {
+            throw new Error(`Unit of work ${this.correlationId} is already committed.`);
+        }
+        if (this._isRolledBack) {
+            throw new Error(`Unit of work ${this.correlationId} is already rolled back.`);
+        }
+    }
+}

package/transactions/UnitOfWorkManager.ts

@@ -0,0 +1,70 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { AsyncLocalStorage } from 'async_hooks';
+import { Guid } from '@cratis/fundamentals';
+import { IEventStore } from '../IEventStore';
+import { IUnitOfWork } from './IUnitOfWork';
+import { IUnitOfWorkManager } from './IUnitOfWorkManager';
+import { NoUnitOfWorkHasBeenStarted } from './NoUnitOfWorkHasBeenStarted';
+import { UnitOfWork } from './UnitOfWork';
+
+/**
+ * Implements {@link IUnitOfWorkManager} using {@link AsyncLocalStorage} for async-context scoping.
+ */
+export class UnitOfWorkManager implements IUnitOfWorkManager {
+    private readonly _storage = new AsyncLocalStorage<IUnitOfWork | undefined>();
+    private readonly _unitsOfWork = new Map<string, IUnitOfWork>();
+
+    constructor(private readonly _eventStore: IEventStore) {}
+
+    /** @inheritdoc */
+    get current(): IUnitOfWork {
+        const current = this._storage.getStore();
+        if (current === undefined) {
+            throw new NoUnitOfWorkHasBeenStarted();
+        }
+        return current;
+    }
+
+    /** @inheritdoc */
+    get hasCurrent(): boolean {
+        return this._storage.getStore() !== undefined;
+    }
+
+    /** @inheritdoc */
+    tryGetFor(correlationId: string | Guid): IUnitOfWork | undefined {
+        const key = Guid.as(correlationId).toString();
+        return this._unitsOfWork.get(key);
+    }
+
+    /** @inheritdoc */
+    begin(correlationId?: string | Guid): IUnitOfWork {
+        const unitOfWork = new UnitOfWork(
+            correlationId === undefined ? Guid.create() : Guid.as(correlationId),
+            this.unitOfWorkCompleted.bind(this),
+            this._eventStore
+        );
+        this.setCurrent(unitOfWork);
+        return unitOfWork;
+    }
+
+    /** @inheritdoc */
+    setCurrent(unitOfWork: IUnitOfWork): void {
+        const key = unitOfWork.correlationId.toString();
+        const existing = this._unitsOfWork.get(key);
+        if (existing === unitOfWork) {
+            this._storage.enterWith(unitOfWork);
+            return;
+        }
+
+        this._storage.enterWith(unitOfWork);
+        this._unitsOfWork.set(key, unitOfWork);
+        unitOfWork.onCompleted(this.unitOfWorkCompleted.bind(this));
+    }
+
+    private unitOfWorkCompleted(unitOfWork: IUnitOfWork): void {
+        this._unitsOfWork.delete(unitOfWork.correlationId.toString());
+        this._storage.enterWith(undefined);
+    }
+}

package/transactions/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 type { IUnitOfWork } from './IUnitOfWork';
+export type { IUnitOfWorkManager } from './IUnitOfWorkManager';
+export { NoUnitOfWorkHasBeenStarted } from './NoUnitOfWorkHasBeenStarted';
+export { UnitOfWork } from './UnitOfWork';
+export { UnitOfWorkManager } from './UnitOfWorkManager';

package/types/DecoratorType.ts

@@ -17,9 +17,18 @@ export enum DecoratorType {
     /** Reducer artifacts discovered through the reducer decorator. */
     Reducer = 'reducer',
 
+    /** Seeder artifacts discovered through the seeder decorator. */
+    Seeder = 'seeder',
+
     /** Constraint artifacts discovered through the constraint decorator. */
     Constraint = 'constraint',
 
     /** Declarative projection artifacts discovered through the projection decorator. */
-    Projection = 'projection'
+    Projection = 'projection',
+
+    /** Webhook artifacts discovered through the webhook decorator. */
+    Webhook = 'webhook',
+
+    /** Event type migration artifacts discovered through the eventTypeMigration decorator. */
+    EventTypeMigration = 'eventTypeMigration'
 }

package/webhooks/IWebhook.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 { IWebhookDefinitionBuilder } from './IWebhookDefinitionBuilder';
+
+/**
+ * Defines a discoverable webhook.
+ */
+export interface IWebhook {
+    /**
+     * Defines the webhook using the provided builder.
+     * @param builder - The builder used for configuration.
+     */
+    define(builder: IWebhookDefinitionBuilder): void;
+}

package/webhooks/IWebhookDefinitionBuilder.ts

@@ -0,0 +1,68 @@
+// 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 { EventSequenceId } from '../eventSequences/EventSequenceId';
+
+/**
+ * Defines a builder for webhook definitions.
+ */
+export interface IWebhookDefinitionBuilder {
+    /**
+     * Sets the event sequence for the webhook.
+     * @param eventSequenceId - The event sequence identifier.
+     * @returns The builder for chaining.
+     */
+    onEventSequence(eventSequenceId: EventSequenceId): IWebhookDefinitionBuilder;
+
+    /**
+     * Uses basic authorization for the webhook target.
+     * @param username - Basic auth username.
+     * @param password - Basic auth password.
+     * @returns The builder for chaining.
+     */
+    withBasicAuth(username: string, password: string): IWebhookDefinitionBuilder;
+
+    /**
+     * Uses bearer token authorization for the webhook target.
+     * @param token - Bearer token.
+     * @returns The builder for chaining.
+     */
+    withBearerToken(token: string): IWebhookDefinitionBuilder;
+
+    /**
+     * Uses OAuth authorization for the webhook target.
+     * @param authority - OAuth authority.
+     * @param clientId - OAuth client id.
+     * @param clientSecret - OAuth client secret.
+     * @returns The builder for chaining.
+     */
+    withOAuth(authority: string, clientId: string, clientSecret: string): IWebhookDefinitionBuilder;
+
+    /**
+     * Adds a target header.
+     * @param key - Header key.
+     * @param value - Header value.
+     * @returns The builder for chaining.
+     */
+    withHeader(key: string, value: string): IWebhookDefinitionBuilder;
+
+    /**
+     * Adds an event type by constructor.
+     * @param eventType - Event type constructor.
+     * @returns The builder for chaining.
+     */
+    withEventType(eventType: Constructor): IWebhookDefinitionBuilder;
+
+    /**
+     * Marks the webhook as not replayable.
+     * @returns The builder for chaining.
+     */
+    notReplayable(): IWebhookDefinitionBuilder;
+
+    /**
+     * Marks the webhook as not active.
+     * @returns The builder for chaining.
+     */
+    notActive(): IWebhookDefinitionBuilder;
+}

package/webhooks/IWebhooks.ts

@@ -0,0 +1,45 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { WebhookDefinition } from '@cratis/chronicle.contracts';
+import { IWebhookDefinitionBuilder } from './IWebhookDefinitionBuilder';
+import { WebhookId } from './WebhookId';
+import { WebhookTargetUrl } from './WebhookTargetUrl';
+
+/**
+ * Defines the API for working with webhooks.
+ */
+export interface IWebhooks {
+    /**
+     * Discovers all webhooks from registered client artifacts.
+     */
+    discover(): Promise<void>;
+
+    /**
+     * Registers all discovered webhooks with the Chronicle Kernel.
+     */
+    registerDiscovered(): Promise<void>;
+
+    /**
+     * Registers a single webhook.
+     * @param webhookId - Webhook identifier.
+     * @param targetUrl - Webhook target URL.
+     * @param configure - Function to configure the webhook definition.
+     */
+    register(
+        webhookId: WebhookId | string,
+        targetUrl: WebhookTargetUrl | string,
+        configure: (builder: IWebhookDefinitionBuilder) => void
+    ): Promise<void>;
+
+    /**
+     * Gets all registered webhooks for the event store.
+     */
+    getWebhooks(): Promise<WebhookDefinition[]>;
+
+    /**
+     * Removes a webhook by identifier.
+     * @param webhookId - Webhook identifier.
+     */
+    remove(webhookId: WebhookId | string): Promise<void>;
+}