@cratis/chronicle 0.0.1 → 0.2.0

package/EventStore.ts

@@ -5,26 +5,34 @@ import { diag } from '@opentelemetry/api';
 import { SpanStatusCode } from '@opentelemetry/api';
 import { ChronicleConnection } from './connection';
 import { ConnectionLifecycle } from './connection/ConnectionLifecycle';
-import { EventLog } from './EventSequences/EventLog';
-import { EventSequence } from './EventSequences/EventSequence';
-import { EventSequenceId } from './EventSequences/EventSequenceId';
-import { IEventLog } from './EventSequences/IEventLog';
-import { IEventSequence } from './EventSequences/IEventSequence';
+import { EventLog } from './eventSequences/EventLog';
+import { EventSequence } from './eventSequences/EventSequence';
+import { EventSequenceId } from './eventSequences/EventSequenceId';
+import { IEventLog } from './eventSequences/IEventLog';
+import { IEventSequence } from './eventSequences/IEventSequence';
 import { EventStoreName } from './EventStoreName';
 import { EventStoreNamespaceName } from './EventStoreNamespaceName';
 import { IEventStore } from './IEventStore';
-import { EventTypes } from './Events/EventTypes';
-import { IEventTypes } from './Events/IEventTypes';
-import { Constraints } from './Events/Constraints/Constraints';
-import { IConstraints } from './Events/Constraints/IConstraints';
-import { Projections } from './Projections/Projections';
-import { IProjections } from './Projections/IProjections';
-import { Reactors } from './Reactors/Reactors';
-import { IReactors } from './Reactors/IReactors';
-import { Reducers } from './Reducers/Reducers';
-import { IReducers } from './Reducers/IReducers';
+import { EventTypes } from './events/EventTypes';
+import { IEventTypes } from './events/IEventTypes';
+import { Constraints } from './events/constraints/Constraints';
+import { IConstraints } from './events/constraints/IConstraints';
+import { Projections } from './projections/Projections';
+import { IProjections } from './projections/IProjections';
+import { Reactors } from './reactors/Reactors';
+import { IReactors } from './reactors/IReactors';
+import { Reducers } from './reducers/Reducers';
+import { IReducers } from './reducers/IReducers';
+import { EventSeeding } from './seeding/EventSeeding';
+import { IEventSeeding } from './seeding/IEventSeeding';
 import { ChronicleTracer } from './Tracing';
 import { DefaultClientArtifactsProvider } from './artifacts/DefaultClientArtifactsProvider';
+import { IUnitOfWorkManager } from './transactions/IUnitOfWorkManager';
+import { UnitOfWorkManager } from './transactions/UnitOfWorkManager';
+import { IJobs } from './jobs/IJobs';
+import { Jobs } from './jobs/Jobs';
+import { IWebhooks } from './webhooks/IWebhooks';
+import { Webhooks } from './webhooks/Webhooks';
 
 /**
  * Implements {@link IEventStore} by communicating with the Chronicle Kernel
@@ -41,6 +49,10 @@ export class EventStore implements IEventStore {
     readonly projections: IProjections;
     readonly reactors: IReactors;
     readonly reducers: IReducers;
+    readonly unitOfWorkManager: IUnitOfWorkManager;
+    readonly jobs: IJobs;
+    readonly webhooks: IWebhooks;
+    readonly seeding: IEventSeeding;
 
     private readonly _sequences: Map<string, IEventSequence> = new Map();
 
@@ -50,7 +62,9 @@ export class EventStore implements IEventStore {
         private readonly _connection: ChronicleConnection,
         lifecycle: ConnectionLifecycle
     ) {
-        this.eventLog = new EventLog(name.value, namespace.value, _connection);
+        this.unitOfWorkManager = new UnitOfWorkManager(this);
+
+        this.eventLog = new EventLog(name.value, namespace.value, _connection, this.unitOfWorkManager);
         this._sequences.set(EventSequenceId.eventLog.value, this.eventLog);
 
         const artifacts = DefaultClientArtifactsProvider.default;
@@ -59,6 +73,9 @@ export class EventStore implements IEventStore {
         this.projections = new Projections(name.value, _connection, artifacts);
         this.reactors = new Reactors(artifacts, _connection, name.value, namespace.value, lifecycle);
         this.reducers = new Reducers(artifacts, _connection, name.value, namespace.value, lifecycle);
+        this.jobs = new Jobs(name.value, namespace.value, _connection);
+        this.webhooks = new Webhooks(name.value, _connection, this.eventTypes, artifacts);
+        this.seeding = new EventSeeding(name.value, _connection, artifacts);
     }
 
     /**
@@ -77,7 +94,9 @@ export class EventStore implements IEventStore {
             this.constraints.discover(),
             this.projections.discover(),
             this.reactors.discover(),
-            this.reducers.discover()
+            this.reducers.discover(),
+            this.webhooks.discover(),
+            this.seeding.discover()
         ]);
 
         this._logger.debug('Registering discovered artifacts', {
@@ -90,9 +109,12 @@ export class EventStore implements IEventStore {
             this.constraints.register(),
             this.projections.register(),
             this.reactors.register(),
-            this.reducers.register()
+            this.reducers.register(),
+            this.webhooks.registerDiscovered()
         ]);
 
+        await this.seeding.register();
+
         this._logger.info('Artifact registration completed', {
             eventStore: this.name.value,
             namespace: this.namespace.value
@@ -106,7 +128,7 @@ export class EventStore implements IEventStore {
             return existing;
         }
 
-        const sequence = new EventSequence(id, this.name.value, this.namespace.value, this._connection);
+        const sequence = new EventSequence(id, this.name.value, this.namespace.value, this._connection, this.unitOfWorkManager);
         this._sequences.set(id.value, sequence);
         return sequence;
     }

package/IEventStore.ts

@@ -1,16 +1,20 @@
 // 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 { 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';
+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';
+import { IUnitOfWorkManager } from './transactions/IUnitOfWorkManager';
+import { IJobs } from './jobs/IJobs';
+import { IWebhooks } from './webhooks/IWebhooks';
+import { IEventSeeding } from './seeding/IEventSeeding';
 
 /**
  * Defines the API surface for an event store.
@@ -41,6 +45,18 @@ export interface IEventStore {
     /** The reducers manager for this event store. */
     readonly reducers: IReducers;
 
+    /** The unit of work manager for transaction-scoped appends. */
+    readonly unitOfWorkManager: IUnitOfWorkManager;
+
+    /** The jobs manager for this event store. */
+    readonly jobs: IJobs;
+
+    /** The webhooks manager for this event store. */
+    readonly webhooks: IWebhooks;
+
+    /** The event seeding manager for this event store. */
+    readonly seeding: IEventSeeding;
+
     /**
      * Gets an event sequence by its identifier.
      * @param id - The identifier of the event sequence to retrieve.

package/README.md

@@ -6,7 +6,7 @@ A TypeScript-idiomatic client for [Cratis Chronicle](https://github.com/Cratis/C
 
 `@cratis/chronicle` provides a clean, type-safe TypeScript API for interacting with the Chronicle Kernel. It builds on top of [`@cratis/chronicle.contracts`](https://www.npmjs.com/package/@cratis/chronicle.contracts) (the gRPC contracts package) and exposes idiomatic TypeScript constructs including:
 
-- **Decorators** — `@eventType`, `@readModel`, `@reactor`, `@reducer`, `@constraint`, `@projection`, `@modelBoundProjection`
+- **Decorators** — `@eventType`, `@eventTypeMigration`, `@readModel`, `@reactor`, `@reducer`, `@constraint`, `@projection`, and model-bound decorators such as `@fromEvent`
 - **Value objects** — `EventSequenceNumber`, `EventTypeId`, `EventStoreName`, etc.
 - **Fluent client** — `ChronicleClient` → `EventStore` → `EventLog` → `append()`
 

package/artifacts/DefaultClientArtifactsProvider.ts

@@ -39,6 +39,11 @@ export class DefaultClientArtifactsProvider implements IClientArtifactsProvider
         return this.discoverer.getTypesByDecoratorType(DecoratorType.Reducer);
     }
 
+    /** @inheritdoc */
+    get seeders(): Constructor[] {
+        return this.discoverer.getTypesByDecoratorType(DecoratorType.Seeder);
+    }
+
     /** @inheritdoc */
     get constraints(): Constructor[] {
         return this.discoverer.getTypesByDecoratorType(DecoratorType.Constraint);
@@ -50,7 +55,11 @@ export class DefaultClientArtifactsProvider implements IClientArtifactsProvider
     }
 
     /** @inheritdoc */
-    get modelBoundProjections(): Constructor[] {
-        return this.discoverer.getTypesByDecoratorType(DecoratorType.ModelBoundProjection);
+    get webhooks(): Constructor[] {
+        return this.discoverer.getTypesByDecoratorType(DecoratorType.Webhook);
+    }
+
+    get eventTypeMigrations(): Constructor[] {
+        return this.discoverer.getTypesByDecoratorType(DecoratorType.EventTypeMigration);
     }
 }

package/artifacts/IClientArtifactsProvider.ts

@@ -19,12 +19,18 @@ export interface IClientArtifactsProvider {
     /** Gets discovered reducer constructors. */
     readonly reducers: Constructor[];
 
+    /** Gets discovered seeder constructors. */
+    readonly seeders: Constructor[];
+
     /** Gets discovered constraint constructors. */
     readonly constraints: Constructor[];
 
     /** Gets discovered declarative projection constructors. */
     readonly projections: Constructor[];
 
-    /** Gets discovered model-bound projection constructors. */
-    readonly modelBoundProjections: Constructor[];
+    /** Gets discovered webhook constructors. */
+    readonly webhooks: Constructor[];
+
+    /** Gets discovered event type migration constructors. */
+    readonly eventTypeMigrations: Constructor[];
 }

package/auditing/Causation.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CausationType } from './CausationType';
+
+/**
+ * Represents a causation instance.
+ */
+export class Causation {
+    /**
+     * Creates an unknown causation instance.
+     * @returns A new {@link Causation} with the current time, type set to {@link CausationType.unknown}, and empty properties.
+     */
+    static unknown(): Causation {
+        return new Causation(new Date(), CausationType.unknown, {});
+    }
+
+    /**
+     * Initializes a new instance of the {@link Causation} class.
+     * @param occurred - When it occurred.
+     * @param type - Type of causation.
+     * @param properties - Any properties associated with the causation.
+     */
+    constructor(
+        readonly occurred: Date,
+        readonly type: CausationType,
+        readonly properties: Readonly<Record<string, string>>
+    ) {}
+}

package/auditing/CausationManager.ts

@@ -0,0 +1,51 @@
+// 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 { Causation } from './Causation';
+import { CausationType } from './CausationType';
+import { ICausationManager } from './ICausationManager';
+
+/**
+ * Implements {@link ICausationManager} using {@link AsyncLocalStorage} to scope the causation chain to the active async call context.
+ */
+export class CausationManager implements ICausationManager {
+    private readonly _storage = new AsyncLocalStorage<Causation[]>();
+    private _root: Causation = new Causation(new Date(), CausationType.root, {});
+
+    /** @inheritdoc */
+    get root(): Causation {
+        return this._root;
+    }
+
+    /** @inheritdoc */
+    getCurrentChain(): ReadonlyArray<Causation> {
+        const chain = this._getOrInitChain();
+        return chain;
+    }
+
+    /** @inheritdoc */
+    add(type: CausationType, properties: Record<string, string>): void {
+        const chain = this._getOrInitChain();
+        chain.push(new Causation(new Date(), type, properties));
+    }
+
+    /**
+     * Defines the root causation for the current process.
+     * @param properties - Properties associated with the root causation.
+     */
+    defineRoot(properties: Record<string, string>): void {
+        this._root = new Causation(new Date(), CausationType.root, properties);
+    }
+
+    private _getOrInitChain(): Causation[] {
+        let chain = this._storage.getStore();
+        if (chain === undefined) {
+            chain = [this._root];
+            this._storage.enterWith(chain);
+        } else if (chain.length === 0) {
+            chain.push(this._root);
+        }
+        return chain;
+    }
+}

package/auditing/CausationType.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents a type of causation.
+ */
+export class CausationType {
+    /**
+     * Represents the root causation type.
+     */
+    static readonly root = new CausationType('Root');
+
+    /**
+     * Represents the unknown causation type.
+     */
+    static readonly unknown = new CausationType('Unknown');
+
+    /**
+     * Represents the causation type for a single event append via the TypeScript client.
+     */
+    static readonly appendEvent = new CausationType('TypeScriptClient.Append');
+
+    /**
+     * Represents the causation type for a batch event append via the TypeScript client.
+     */
+    static readonly appendManyEvents = new CausationType('TypeScriptClient.AppendMany');
+
+    /**
+     * Initializes a new instance of the {@link CausationType} class.
+     * @param name - The name of the causation type.
+     */
+    constructor(readonly name: string) {}
+
+    /** @inheritdoc */
+    toString(): string {
+        return this.name;
+    }
+}

package/auditing/ICausationManager.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Causation } from './Causation';
+import { CausationType } from './CausationType';
+
+/**
+ * Defines a system that manages causation for the active call context.
+ */
+export interface ICausationManager {
+    /**
+     * Gets the root causation.
+     */
+    readonly root: Causation;
+
+    /**
+     * Gets the full causation chain for the current call context.
+     * The chain always starts with {@link root} if no other causation has been added.
+     * @returns An array of {@link Causation} representing the current chain.
+     */
+    getCurrentChain(): ReadonlyArray<Causation>;
+
+    /**
+     * Adds a causation entry to the current chain.
+     * @param type - The type of causation to add.
+     * @param properties - Properties associated with the causation.
+     */
+    add(type: CausationType, properties: Record<string, string>): void;
+}

package/auditing/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 { Causation } from './Causation';
+export { CausationType } from './CausationType';
+export type { ICausationManager } from './ICausationManager';
+export { CausationManager } from './CausationManager';
+
+import { CausationManager } from './CausationManager';
+
+/**
+ * The default singleton {@link CausationManager} for the process.
+ * Use this to manage the causation chain for the current async call context.
+ */
+export const causationManager = new CausationManager();