@cratis/chronicle 0.0.1 → 0.2.0

package/events/migrations/eventTypeMigration.ts

@@ -0,0 +1,82 @@
+// 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 { getEventTypeFor } from '../eventTypeDecorator';
+import { EventType } from '../EventType';
+import { InvalidMigrationGenerationGap } from './InvalidMigrationGenerationGap';
+import { DecoratorType, TypeDiscoverer } from '../../types';
+
+const EVENT_TYPE_MIGRATION_METADATA_KEY = 'chronicle:eventTypeMigration';
+
+/**
+ * Metadata stored on an event type migration class.
+ */
+export interface EventTypeMigrationMetadata {
+    /** The upgraded (newer) event type represented by this migration. */
+    readonly eventType: EventType;
+
+    /** The previous (older) event type this migration migrates from. */
+    readonly previousEventType: EventType;
+}
+
+/**
+ * Decorator that marks a class as an event type migration between two generations
+ * of the same event type.
+ * @param upgradedType - The upgraded event type constructor.
+ * @param previousType - The previous event type constructor.
+ * @returns A class decorator.
+ */
+export function eventTypeMigration(upgradedType: Constructor, previousType: Constructor): ClassDecorator {
+    const upgradedEventType = getEventTypeFor(upgradedType);
+    const previousEventType = getEventTypeFor(previousType);
+
+    if (upgradedEventType.id.value === '') {
+        throw new Error(`Type '${upgradedType.name}' must be decorated with @eventType().`);
+    }
+    if (previousEventType.id.value === '') {
+        throw new Error(`Type '${previousType.name}' must be decorated with @eventType().`);
+    }
+
+    if (upgradedEventType.id.value !== previousEventType.id.value || upgradedEventType.generation.value !== previousEventType.generation.value + 1) {
+        throw new InvalidMigrationGenerationGap(
+            previousType.name,
+            upgradedType.name,
+            previousEventType.generation.value,
+            upgradedEventType.generation.value
+        );
+    }
+
+    return (target: object) => {
+        const metadata: EventTypeMigrationMetadata = {
+            eventType: upgradedEventType,
+            previousEventType
+        };
+
+        Reflect.defineMetadata(EVENT_TYPE_MIGRATION_METADATA_KEY, metadata, target);
+        TypeDiscoverer.default.register(
+            DecoratorType.EventTypeMigration,
+            target as Constructor,
+            `${upgradedEventType.id.value}+${upgradedEventType.generation.value}`
+        );
+    };
+}
+
+/**
+ * Gets the {@link EventTypeMigrationMetadata} associated with a class decorated with {@link eventTypeMigration}.
+ * @param target - The class constructor to retrieve the metadata for.
+ * @returns The associated metadata, or undefined if not decorated.
+ */
+export function getEventTypeMigrationMetadata(target: Function): EventTypeMigrationMetadata | undefined {
+    return Reflect.getMetadata(EVENT_TYPE_MIGRATION_METADATA_KEY, target);
+}
+
+/**
+ * Checks whether a class has been decorated with {@link eventTypeMigration}.
+ * @param target - The class constructor to check.
+ * @returns True if the class has migration metadata; false otherwise.
+ */
+export function isEventTypeMigration(target: Function): boolean {
+    return Reflect.hasMetadata(EVENT_TYPE_MIGRATION_METADATA_KEY, target);
+}

package/events/migrations/index.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.
+
+export type { IEventMigrationBuilder } from './IEventMigrationBuilder';
+export type { IEventMigrationPropertyBuilder } from './IEventMigrationPropertyBuilder';
+export { EventMigrationBuilder } from './EventMigrationBuilder';
+export { EventMigrationPropertyBuilder } from './EventMigrationPropertyBuilder';
+export type { IEventTypeMigration } from './IEventTypeMigration';
+export type { IEventTypeMigrators } from './IEventTypeMigrators';
+export { EventTypeMigrators } from './EventTypeMigrators';
+export { eventTypeMigration, getEventTypeMigrationMetadata, isEventTypeMigration } from './eventTypeMigration';
+export type { EventTypeMigrationMetadata } from './eventTypeMigration';
+export { InvalidMigrationGenerationGap } from './InvalidMigrationGenerationGap';

package/identity/IIdentityProvider.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Identity } from './Identity';
+
+/**
+ * Defines a system that can provide and manage the current {@link Identity} for the active call context.
+ */
+export interface IIdentityProvider {
+    /**
+     * Gets the current identity for the active call context.
+     * @returns The current {@link Identity}, or {@link Identity.system} if none has been set.
+     */
+    getCurrent(): Identity;
+
+    /**
+     * Sets the current identity for the active call context.
+     * @param identity - The {@link Identity} to set.
+     */
+    setCurrentIdentity(identity: Identity): void;
+
+    /**
+     * Clears the current identity for the active call context, resetting it to {@link Identity.system}.
+     */
+    clearCurrentIdentity(): void;
+}

package/identity/Identity.ts

@@ -0,0 +1,61 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents an identity of something that is responsible for causing a state change.
+ * An identity can be a user, a system, a service or anything else that can be identified.
+ */
+export class Identity {
+    /**
+     * The identity used when not set.
+     */
+    static readonly notSet = new Identity('1efc9b81-0612-4466-962c-86acc4e9a028', '[Not Set]', '[Not Set]');
+
+    /**
+     * The identity used when the identity is not known.
+     */
+    static readonly unknown = new Identity('3321cf62-db16-425e-8173-99fcfefe11dd', '[Unknown]', '[Unknown]');
+
+    /**
+     * The identity used when the system is the cause.
+     */
+    static readonly system = new Identity('5d032c92-9d5e-41eb-947a-ee5314ed0032', '[System]', '[System]');
+
+    /**
+     * Initializes a new instance of the {@link Identity} class.
+     * @param subject - The identifier of the identity, referred to as subject.
+     * @param name - Name of the identity.
+     * @param userName - Optional username, defaults to empty string.
+     * @param onBehalfOf - Optional behalf of {@link Identity}.
+     */
+    constructor(
+        readonly subject: string,
+        readonly name: string,
+        readonly userName: string = '',
+        readonly onBehalfOf?: Identity
+    ) {}
+
+    /**
+     * Returns a new {@link Identity} chain with duplicate subjects removed.
+     * The first occurrence of each subject is kept.
+     * @returns A new {@link Identity} with duplicates removed from the chain.
+     */
+    withoutDuplicates(): Identity {
+        const seen = new Set<string>();
+        const chain: Identity[] = [];
+        let current: Identity | undefined = this;
+        while (current !== undefined) {
+            if (!seen.has(current.subject)) {
+                seen.add(current.subject);
+                chain.push(current);
+            }
+            current = current.onBehalfOf;
+        }
+
+        let result: Identity | undefined;
+        for (let i = chain.length - 1; i >= 0; i--) {
+            result = new Identity(chain[i].subject, chain[i].name, chain[i].userName, result);
+        }
+        return result!;
+    }
+}

package/identity/IdentityProvider.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 { AsyncLocalStorage } from 'async_hooks';
+import { Identity } from './Identity';
+import { IIdentityProvider } from './IIdentityProvider';
+
+/**
+ * Implements {@link IIdentityProvider} using {@link AsyncLocalStorage} to scope the identity to the active async call context.
+ */
+export class IdentityProvider implements IIdentityProvider {
+    private readonly _storage = new AsyncLocalStorage<Identity>();
+
+    /** @inheritdoc */
+    getCurrent(): Identity {
+        return this._storage.getStore() ?? Identity.system;
+    }
+
+    /** @inheritdoc */
+    setCurrentIdentity(identity: Identity): void {
+        this._storage.enterWith(identity);
+    }
+
+    /** @inheritdoc */
+    clearCurrentIdentity(): void {
+        this._storage.enterWith(Identity.system);
+    }
+}

package/identity/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 { Identity } from './Identity';
+export type { IIdentityProvider } from './IIdentityProvider';
+export { IdentityProvider } from './IdentityProvider';
+
+import { IdentityProvider } from './IdentityProvider';
+
+/**
+ * The default singleton {@link IdentityProvider} for the process.
+ * Use this to get and set the identity for the current async call context.
+ */
+export const identityProvider = new IdentityProvider();

package/index.ts

@@ -1,6 +1,25 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import * as events from './events';
+import * as eventSequences from './eventSequences';
+import * as reactors from './reactors';
+import * as reducers from './reducers';
+import * as seeding from './seeding';
+import * as readModels from './readModels';
+import * as projections from './projections';
+import * as jobs from './jobs';
+import * as webhooks from './webhooks';
+import * as observation from './observation';
+import * as sinks from './sinks';
+import * as schemas from './schemas';
+import * as types from './types';
+import * as artifacts from './artifacts';
+import * as identity from './identity';
+import * as auditing from './auditing';
+import * as correlation from './correlation';
+import * as transactions from './transactions';
+
 export { ChronicleClient } from './ChronicleClient';
 export type { IChronicleClient } from './IChronicleClient';
 export { ChronicleOptions } from './ChronicleOptions';
@@ -12,13 +31,42 @@ export { Guid } from '@cratis/fundamentals';
 export { ChronicleInstrumentationName, ChronicleTracer } from './Tracing';
 export { ChronicleMeter, ChronicleMeterName, ChronicleMetrics } from './Metrics';
 
-export * from './Events';
-export * from './EventSequences';
-export * from './Reactors';
-export * from './Reducers';
-export * from './ReadModels';
-export * from './Projections';
-export * from './Observation';
-export * from './Schemas';
+export * from './events';
+export * from './eventSequences';
+export * from './reactors';
+export * from './reducers';
+export * from './seeding';
+export * from './readModels';
+export * from './projections';
+export * from './jobs';
+export * from './webhooks';
+export * from './observation';
+export * from './sinks';
+export * from './schemas';
 export * from './types';
 export * from './artifacts';
+export * from './identity';
+export * from './auditing';
+export * from './correlation';
+export * from './transactions';
+
+export {
+    events,
+    eventSequences,
+    reactors,
+    reducers,
+    seeding,
+    readModels,
+    projections,
+    jobs,
+    webhooks,
+    observation,
+    sinks,
+    schemas,
+    types,
+    artifacts,
+    identity,
+    auditing,
+    correlation,
+    transactions,
+};

package/jobs/IJobs.ts

@@ -0,0 +1,49 @@
+// 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 type { Job, JobStep } from '@cratis/chronicle.contracts';
+import { JobId } from './JobId';
+
+/**
+ * Defines the API for working with jobs in Chronicle.
+ */
+export interface IJobs {
+    /**
+     * Stops the job with the specified identifier.
+     * @param jobId - The job identifier.
+     */
+    stop(jobId: JobId | Guid | string): Promise<void>;
+
+    /**
+     * Resumes the job with the specified identifier.
+     * @param jobId - The job identifier.
+     */
+    resume(jobId: JobId | Guid | string): Promise<void>;
+
+    /**
+     * Deletes the job with the specified identifier.
+     * @param jobId - The job identifier.
+     */
+    delete(jobId: JobId | Guid | string): Promise<void>;
+
+    /**
+     * Gets a job by identifier.
+     * @param jobId - The job identifier.
+     * @returns The job, or undefined when not found.
+     */
+    getJob(jobId: JobId | Guid | string): Promise<Job | undefined>;
+
+    /**
+     * Gets all jobs for the event store namespace.
+     * @returns All jobs.
+     */
+    getJobs(): Promise<Job[]>;
+
+    /**
+     * Gets all steps for a specific job.
+     * @param jobId - The job identifier.
+     * @returns The job steps.
+     */
+    getJobSteps(jobId: JobId | Guid | string): Promise<JobStep[]>;
+}

package/jobs/JobId.ts

@@ -0,0 +1,25 @@
+// 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';
+
+/**
+ * Represents the unique identifier of a job.
+ */
+export class JobId {
+    constructor(readonly value: Guid) {}
+
+    /**
+     * Creates a {@link JobId} from a string or Guid.
+     * @param value - The value to create from.
+     * @returns A {@link JobId} instance.
+     */
+    static from(value: string | Guid): JobId {
+        return new JobId(typeof value === 'string' ? Guid.parse(value) : value);
+    }
+
+    /** @inheritdoc */
+    toString(): string {
+        return this.value.toString();
+    }
+}

package/jobs/Jobs.ts

@@ -0,0 +1,81 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Job, JobStep } from '@cratis/chronicle.contracts';
+import { Guid } from '@cratis/fundamentals';
+import { ChronicleConnection } from '../connection';
+import { toContractsGuid } from '../connection/Guid';
+import { IJobs } from './IJobs';
+import { JobId } from './JobId';
+
+/**
+ * Implements {@link IJobs}.
+ */
+export class Jobs implements IJobs {
+    /**
+     * Creates a new {@link Jobs} instance.
+     * @param _eventStore - The event store name.
+     * @param _namespace - The event store namespace.
+     * @param _connection - Chronicle connection.
+     */
+    constructor(
+        private readonly _eventStore: string,
+        private readonly _namespace: string,
+        private readonly _connection: ChronicleConnection
+    ) {}
+
+    /** @inheritdoc */
+    async stop(jobId: JobId | Guid | string): Promise<void> {
+        await this._connection.jobs.stop(this.createJobRequest(jobId));
+    }
+
+    /** @inheritdoc */
+    async resume(jobId: JobId | Guid | string): Promise<void> {
+        await this._connection.jobs.resume(this.createJobRequest(jobId));
+    }
+
+    /** @inheritdoc */
+    async delete(jobId: JobId | Guid | string): Promise<void> {
+        await this._connection.jobs.delete(this.createJobRequest(jobId));
+    }
+
+    /** @inheritdoc */
+    async getJob(jobId: JobId | Guid | string): Promise<Job | undefined> {
+        const result = await this._connection.jobs.getJob(this.createJobRequest(jobId));
+        return result.Value0;
+    }
+
+    /** @inheritdoc */
+    async getJobs(): Promise<Job[]> {
+        const response = await this._connection.jobs.getJobs({
+            EventStore: this._eventStore,
+            Namespace: this._namespace
+        });
+
+        return response.items ?? [];
+    }
+
+    /** @inheritdoc */
+    async getJobSteps(jobId: JobId | Guid | string): Promise<JobStep[]> {
+        const response = await this._connection.jobs.getJobSteps(this.createJobRequest(jobId));
+        return response.items ?? [];
+    }
+
+    private createJobRequest(jobId: JobId | Guid | string): { EventStore: string; Namespace: string; JobId: ReturnType<typeof toContractsGuid> } {
+        return {
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            JobId: toContractsGuid(this.normalizeJobId(jobId))
+        };
+    }
+
+    private normalizeJobId(jobId: JobId | Guid | string): Guid {
+        if (typeof jobId === 'string') {
+            return Guid.parse(jobId);
+        }
+        if (jobId instanceof JobId) {
+            return jobId.value;
+        }
+        return jobId;
+    }
+}

package/jobs/index.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "0.0.1",
+    "version": "0.2.0",
     "description": "TypeScript idiomatic client for Cratis Chronicle",
     "author": "Cratis",
     "license": "MIT",
@@ -14,11 +14,109 @@
     ],
     "publishConfig": {
         "access": "public",
-        "provenance": false
+        "provenance": true
     },
     "type": "module",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        },
+        "./events": {
+            "types": "./dist/events/index.d.ts",
+            "import": "./dist/events/index.js",
+            "default": "./dist/events/index.js"
+        },
+        "./eventSequences": {
+            "types": "./dist/eventSequences/index.d.ts",
+            "import": "./dist/eventSequences/index.js",
+            "default": "./dist/eventSequences/index.js"
+        },
+        "./reactors": {
+            "types": "./dist/reactors/index.d.ts",
+            "import": "./dist/reactors/index.js",
+            "default": "./dist/reactors/index.js"
+        },
+        "./reducers": {
+            "types": "./dist/reducers/index.d.ts",
+            "import": "./dist/reducers/index.js",
+            "default": "./dist/reducers/index.js"
+        },
+        "./seeding": {
+            "types": "./dist/seeding/index.d.ts",
+            "import": "./dist/seeding/index.js",
+            "default": "./dist/seeding/index.js"
+        },
+        "./readModels": {
+            "types": "./dist/readModels/index.d.ts",
+            "import": "./dist/readModels/index.js",
+            "default": "./dist/readModels/index.js"
+        },
+        "./projections": {
+            "types": "./dist/projections/index.d.ts",
+            "import": "./dist/projections/index.js",
+            "default": "./dist/projections/index.js"
+        },
+        "./jobs": {
+            "types": "./dist/jobs/index.d.ts",
+            "import": "./dist/jobs/index.js",
+            "default": "./dist/jobs/index.js"
+        },
+        "./webhooks": {
+            "types": "./dist/webhooks/index.d.ts",
+            "import": "./dist/webhooks/index.js",
+            "default": "./dist/webhooks/index.js"
+        },
+        "./observation": {
+            "types": "./dist/observation/index.d.ts",
+            "import": "./dist/observation/index.js",
+            "default": "./dist/observation/index.js"
+        },
+        "./sinks": {
+            "types": "./dist/sinks/index.d.ts",
+            "import": "./dist/sinks/index.js",
+            "default": "./dist/sinks/index.js"
+        },
+        "./schemas": {
+            "types": "./dist/schemas/index.d.ts",
+            "import": "./dist/schemas/index.js",
+            "default": "./dist/schemas/index.js"
+        },
+        "./types": {
+            "types": "./dist/types/index.d.ts",
+            "import": "./dist/types/index.js",
+            "default": "./dist/types/index.js"
+        },
+        "./artifacts": {
+            "types": "./dist/artifacts/index.d.ts",
+            "import": "./dist/artifacts/index.js",
+            "default": "./dist/artifacts/index.js"
+        },
+        "./identity": {
+            "types": "./dist/identity/index.d.ts",
+            "import": "./dist/identity/index.js",
+            "default": "./dist/identity/index.js"
+        },
+        "./auditing": {
+            "types": "./dist/auditing/index.d.ts",
+            "import": "./dist/auditing/index.js",
+            "default": "./dist/auditing/index.js"
+        },
+        "./correlation": {
+            "types": "./dist/correlation/index.d.ts",
+            "import": "./dist/correlation/index.js",
+            "default": "./dist/correlation/index.js"
+        },
+        "./transactions": {
+            "types": "./dist/transactions/index.d.ts",
+            "import": "./dist/transactions/index.js",
+            "default": "./dist/transactions/index.js"
+        }
+    },
     "scripts": {
         "compile": "tsc -b",
         "build": "tsc -b",
@@ -26,9 +124,12 @@
     },
     "dependencies": {
         "@bufbuild/protobuf": "^2.12.0",
-        "@cratis/chronicle.contracts": "^15.25.2",
+        "@cratis/chronicle.contracts": "^15.31.2",
         "@cratis/fundamentals": "^7.9.0",
+        "@grpc/grpc-js": "^1.14.0",
         "@opentelemetry/api": "^1.9.1",
+        "nice-grpc": "^2.1.12",
+        "nice-grpc-common": "^2.0.2",
         "reflect-metadata": "^0.2.2"
     },
     "devDependencies": {