@cratis/chronicle 0.1.0 → 0.2.1

package/EventStore.ts

@@ -5,26 +5,38 @@ 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 { IReadModels } from './readModels/IReadModels';
+import { ReadModels } from './readModels/ReadModels';
+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';
+import { EventStoreSubscriptions } from './eventStoreSubscriptions/EventStoreSubscriptions';
+import { IEventStoreSubscriptions } from './eventStoreSubscriptions/IEventStoreSubscriptions';
 
 /**
  * Implements {@link IEventStore} by communicating with the Chronicle Kernel
@@ -41,6 +53,12 @@ export class EventStore implements IEventStore {
     readonly projections: IProjections;
     readonly reactors: IReactors;
     readonly reducers: IReducers;
+    readonly readModels: IReadModels;
+    readonly unitOfWorkManager: IUnitOfWorkManager;
+    readonly jobs: IJobs;
+    readonly webhooks: IWebhooks;
+    readonly subscriptions: IEventStoreSubscriptions;
+    readonly seeding: IEventSeeding;
 
     private readonly _sequences: Map<string, IEventSequence> = new Map();
 
@@ -50,7 +68,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 +79,11 @@ 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.readModels = new ReadModels(name.value, namespace.value, _connection, artifacts);
+        this.jobs = new Jobs(name.value, namespace.value, _connection);
+        this.webhooks = new Webhooks(name.value, _connection, this.eventTypes, artifacts);
+        this.subscriptions = new EventStoreSubscriptions(this.eventTypes, name.value, _connection);
+        this.seeding = new EventSeeding(name.value, _connection, artifacts);
     }
 
     /**
@@ -77,7 +102,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 +117,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 +136,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,22 @@
 // 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';
+import { IEventStoreSubscriptions } from './eventStoreSubscriptions/IEventStoreSubscriptions';
+import { IReadModels } from './readModels/IReadModels';
 
 /**
  * Defines the API surface for an event store.
@@ -41,6 +47,24 @@ export interface IEventStore {
     /** The reducers manager for this event store. */
     readonly reducers: IReducers;
 
+    /** The read-models manager for this event store. */
+    readonly readModels: IReadModels;
+
+    /** 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 store subscriptions manager for this event store. */
+    readonly subscriptions: IEventStoreSubscriptions;
+
+    /** 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`, and model-bound decorators such as `@fromEvent`
+- **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);
@@ -48,4 +53,13 @@ export class DefaultClientArtifactsProvider implements IClientArtifactsProvider
     get projections(): Constructor[] {
         return this.discoverer.getTypesByDecoratorType(DecoratorType.Projection);
     }
+
+    /** @inheritdoc */
+    get webhooks(): Constructor[] {
+        return this.discoverer.getTypesByDecoratorType(DecoratorType.Webhook);
+    }
+
+    get eventTypeMigrations(): Constructor[] {
+        return this.discoverer.getTypesByDecoratorType(DecoratorType.EventTypeMigration);
+    }
 }

package/artifacts/IClientArtifactsProvider.ts

@@ -19,9 +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 webhook constructors. */
+    readonly webhooks: Constructor[];
+
+    /** Gets discovered event type migration constructors. */
+    readonly eventTypeMigrations: Constructor[];
 }

package/compliance/ComplianceContracts.ts

@@ -0,0 +1,63 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { CallOptions } from 'nice-grpc-common';
+
+/**
+ * Request to release (decrypt) PII properties in a read model.
+ * 
+ * Note: These types mirror the compliance contracts until they are exported
+ * from @cratis/chronicle.contracts package.
+ */
+export interface ReleaseRequest {
+    EventStore: string;
+    Namespace: string;
+    Subject: string;
+    Schema: string;
+    Payload: string;
+}
+
+/**
+ * Response from releasing PII properties.
+ */
+export interface ReleaseResponse {
+    Payload: string;
+    HasError: boolean;
+    Error: string;
+}
+
+type Builtin = Date | Function | Uint8Array | string | number | boolean | bigint | undefined;
+export type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : Partial<T>;
+
+/**
+ * Compliance service client interface.
+ */
+export interface ComplianceClient<CallOptionsExt = {}> {
+    release(request: DeepPartial<ReleaseRequest>, options?: CallOptions & CallOptionsExt): Promise<ReleaseResponse>;
+}
+
+/**
+ * Message functions placeholder - not needed for nice-grpc client creation
+ */
+export const ReleaseRequestFns = {} as any;
+export const ReleaseResponseFns = {} as any;
+
+/**
+ * Compliance service definition for nice-grpc.
+ */
+export const ComplianceDefinition = {
+    name: 'Compliance',
+    fullName: 'Cratis.Chronicle.Contracts.Compliance.Compliance',
+    methods: {
+        release: {
+            name: 'Release',
+            requestType: ReleaseRequestFns,
+            requestStream: false as const,
+            responseType: ReleaseResponseFns,
+            responseStream: false as const,
+            options: {}
+        }
+    }
+} as const;

package/compliance/ComplianceMetadata.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 type { ComplianceMetadataType } from './ComplianceMetadataType';
+
+/**
+ * Represents metadata related to compliance.
+ */
+export interface ComplianceMetadata {
+    /**
+     * The type of compliance metadata.
+     */
+    readonly metadataType: ComplianceMetadataType;
+
+    /**
+     * Any additional details - can be empty.
+     */
+    readonly details: string;
+}

package/compliance/ComplianceMetadataResolver.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 type { ComplianceMetadata } from './ComplianceMetadata';
+import { getPIIMetadata, getTypePIIMetadata } from './pii';
+
+/**
+ * Resolves compliance metadata for properties and types.
+ */
+export class ComplianceMetadataResolver {
+    /**
+     * Checks if a property has compliance metadata.
+     * @param target - The class prototype.
+     * @param propertyKey - The property name.
+     * @returns True if the property has compliance metadata; false otherwise.
+     */
+    static hasMetadataFor(target: object, propertyKey: string): boolean {
+        return getPIIMetadata(target, propertyKey) !== undefined;
+    }
+
+    /**
+     * Gets all compliance metadata for a property.
+     * @param target - The class prototype.
+     * @param propertyKey - The property name.
+     * @returns Array of compliance metadata.
+     */
+    static getMetadataFor(target: object, propertyKey: string): ComplianceMetadata[] {
+        const metadata: ComplianceMetadata[] = [];
+        
+        const piiMetadata = getPIIMetadata(target, propertyKey);
+        if (piiMetadata) {
+            metadata.push(piiMetadata);
+        }
+        
+        return metadata;
+    }
+
+    /**
+     * Gets compliance metadata for a type (e.g., ConceptAs types).
+     * @param type - The type constructor.
+     * @returns Array of compliance metadata.
+     */
+    static getMetadataForType(type: Function): ComplianceMetadata[] {
+        const metadata: ComplianceMetadata[] = [];
+        const piiMetadata = getTypePIIMetadata(type);
+        if (piiMetadata) {
+            metadata.push(piiMetadata);
+        }
+        return metadata;
+    }
+}

package/compliance/ComplianceMetadataType.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.
+
+/**
+ * Represents a type of compliance metadata.
+ */
+export class ComplianceMetadataType {
+    /**
+     * Personal Identifiable Information according to the definition in GDPR.
+     */
+    static readonly PII = new ComplianceMetadataType('PII');
+
+    private readonly _value: string;
+
+    /**
+     * Initializes a new instance of ComplianceMetadataType.
+     * @param value - The string value of the compliance metadata type.
+     */
+    constructor(value: string) {
+        this._value = value;
+    }
+
+    /**
+     * Gets the underlying string value.
+     */
+    get value(): string {
+        return this._value;
+    }
+
+    /**
+     * Returns the string representation of the compliance metadata type.
+     */
+    toString(): string {
+        return this._value;
+    }
+}

package/compliance/index.ts

@@ -0,0 +1,7 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export { ComplianceMetadataType } from './ComplianceMetadataType';
+export type { ComplianceMetadata } from './ComplianceMetadata';
+export { pii, getPIIMetadata, hasPIIMetadata, getTypePIIMetadata, isPII } from './pii';
+export { ComplianceMetadataResolver } from './ComplianceMetadataResolver';

package/compliance/pii.ts

@@ -0,0 +1,115 @@
+// 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 type { ComplianceMetadata } from './ComplianceMetadata';
+import { ComplianceMetadataType } from './ComplianceMetadataType';
+import { TypeIntrospector } from '../types';
+
+/** Metadata key for PII decorator on properties. */
+const PII_PROPERTY_METADATA_KEY = 'chronicle:compliance:pii:property';
+
+/** Metadata key for PII decorator on types. */
+const PII_TYPE_METADATA_KEY = 'chronicle:compliance:pii:type';
+
+/**
+ * Decorator that marks a property or type as containing Personal Identifiable Information (PII)
+ * according to the GDPR definition. When applied to read model properties or ConceptAs types,
+ * the Chronicle Kernel will encrypt the values using compliance-aware encryption.
+ *
+ * This decorator can be used in two ways:
+ * - As a property decorator: `@pii('details') propertyName: type`
+ * - As a class decorator: `@pii('details') class TypeName { }`
+ *
+ * @param details - Optional details explaining why or to what extent the property/type is classified as PII.
+ * @returns A decorator function that can be applied to either properties or classes (but not both on the same target).
+ *
+ * @example
+ * Property usage:
+ * ```typescript
+ * @readModel()
+ * class Employee {
+ *     @pii('Employee social security number')
+ *     ssn: string = '';
+ *
+ *     @pii('Personal email address')
+ *     email: string = '';
+ * }
+ * ```
+ *
+ * @example
+ * Type usage with ConceptAs:
+ * ```typescript
+ * @pii('Customer email address')
+ * class CustomerEmailConcept extends ConceptAs<string> {}
+ * export type CustomerEmail = CustomerEmailConcept | string;
+ * 
+ * @readModel()
+ * class Customer {
+ *     @field(CustomerEmailConcept)
+ *     email: CustomerEmail = '';
+ * }
+ * ```
+ */
+export function pii(details?: string): PropertyDecorator & ClassDecorator {
+    return (target: object | Function, propertyKey?: string | symbol) => {
+        // Class decorator usage (for types like ConceptAs)
+        if (typeof target === 'function' && propertyKey === undefined) {
+            const metadata: ComplianceMetadata = {
+                metadataType: ComplianceMetadataType.PII,
+                details: details ?? ''
+            };
+            Reflect.defineMetadata(PII_TYPE_METADATA_KEY, metadata, target);
+            return;
+        }
+
+        // Property decorator usage
+        if (propertyKey !== undefined) {
+            const key = propertyKey.toString();
+            TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
+            const metadata: ComplianceMetadata = {
+                metadataType: ComplianceMetadataType.PII,
+                details: details ?? ''
+            };
+            Reflect.defineMetadata(PII_PROPERTY_METADATA_KEY, metadata, target, key);
+        }
+    };
+}
+
+/**
+ * Gets the PII compliance metadata for a property.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ * @returns The compliance metadata, or undefined if not decorated with @pii.
+ */
+export function getPIIMetadata(target: object, propertyKey: string): ComplianceMetadata | undefined {
+    return Reflect.getMetadata(PII_PROPERTY_METADATA_KEY, target, propertyKey);
+}
+
+/**
+ * Checks whether a property has been decorated with @pii.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ * @returns True if the property has @pii decorator; false otherwise.
+ */
+export function hasPIIMetadata(target: object, propertyKey: string): boolean {
+    return Reflect.hasMetadata(PII_PROPERTY_METADATA_KEY, target, propertyKey);
+}
+
+/**
+ * Gets the PII compliance metadata for a type.
+ * @param type - The type constructor.
+ * @returns The compliance metadata, or undefined if not decorated with @pii.
+ */
+export function getTypePIIMetadata(type: Function): ComplianceMetadata | undefined {
+    return Reflect.getMetadata(PII_TYPE_METADATA_KEY, type);
+}
+
+/**
+ * Checks whether a type has been decorated with @pii.
+ * @param type - The type constructor.
+ * @returns True if the type has @pii decorator; false otherwise.
+ */
+export function isPII(type: Function): boolean {
+    return Reflect.hasMetadata(PII_TYPE_METADATA_KEY, type);
+}