@cratis/chronicle 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "0.2.0",
+    "version": "0.2.1",
     "description": "TypeScript idiomatic client for Cratis Chronicle",
     "author": "Cratis",
     "license": "MIT",
@@ -36,6 +36,16 @@
             "import": "./dist/eventSequences/index.js",
             "default": "./dist/eventSequences/index.js"
         },
+        "./eventStoreSubscriptions": {
+            "types": "./dist/eventStoreSubscriptions/index.d.ts",
+            "import": "./dist/eventStoreSubscriptions/index.js",
+            "default": "./dist/eventStoreSubscriptions/index.js"
+        },
+        "./compliance": {
+            "types": "./dist/compliance/index.d.ts",
+            "import": "./dist/compliance/index.js",
+            "default": "./dist/compliance/index.js"
+        },
         "./reactors": {
             "types": "./dist/reactors/index.d.ts",
             "import": "./dist/reactors/index.js",
@@ -124,16 +134,16 @@
     },
     "dependencies": {
         "@bufbuild/protobuf": "^2.12.0",
-        "@cratis/chronicle.contracts": "^15.31.2",
-        "@cratis/fundamentals": "^7.9.0",
-        "@grpc/grpc-js": "^1.14.0",
+        "@cratis/chronicle.contracts": "15.33.3",
+        "@cratis/fundamentals": "7.14.0",
+        "@grpc/grpc-js": "^1.14.4",
         "@opentelemetry/api": "^1.9.1",
-        "nice-grpc": "^2.1.12",
-        "nice-grpc-common": "^2.0.2",
+        "nice-grpc": "^2.1.16",
+        "nice-grpc-common": "^2.0.3",
         "reflect-metadata": "^0.2.2"
     },
     "devDependencies": {
-        "@types/node": "^25.6.1",
+        "@types/node": "^25.9.1",
         "typescript": "^6.0.3"
     }
 }

package/reactors/Reactors.ts

@@ -250,7 +250,7 @@ export class Reactors implements IReactors {
                         this._logger.info('Invoking reactor handler', {
                             reactorId: id,
                             method: entry.methodName,
-                            sequenceNumber: event.Context!.SequenceNumber,
+                            sequenceNumber: event.Context!.SequenceNumber.toString(),
                             eventTypeId
                         });
 

package/readModels/IMaterializedReadModels.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Constructor } from '@cratis/fundamentals';
+
+/**
+ * Defines a system for working with materialized read model instances stored in the sink.
+ */
+export interface IMaterializedReadModels {
+    /**
+     * Gets paginated instances of a read model from the sink.
+     * @param readModelType - The read model type to retrieve.
+     * @param skip - Number of instances to skip. Defaults to zero.
+     * @param take - Number of instances to retrieve. Defaults to 50.
+     * @returns Collection of read model instances.
+     */
+    getInstances<TReadModel>(readModelType: Constructor<TReadModel>, skip?: number, take?: number): Promise<TReadModel[]>;
+
+    /**
+     * Observes changes for a paginated window of read model instances from the sink.
+     * @param readModelType - The read model type to observe.
+     * @param skip - Number of instances to skip. Defaults to zero.
+     * @param take - Number of instances to observe. Defaults to 50.
+     * @returns An async iterable of read model instance collections.
+     */
+    observeInstances<TReadModel>(readModelType: Constructor<TReadModel>, skip?: number, take?: number): AsyncIterable<TReadModel[]>;
+}

package/readModels/IReadModels.ts

@@ -0,0 +1,87 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Constructor } from '@cratis/fundamentals';
+import type { IMaterializedReadModels } from './IMaterializedReadModels';
+import type { ReadModelChangeset } from './ReadModelChangeset';
+import type { ReadModelSnapshot } from './ReadModelSnapshot';
+
+/**
+ * Defines a system that works with read models in the event store.
+ */
+export interface IReadModels {
+    /**
+     * Gets the {@link IMaterializedReadModels} for working with materialized read model instances from the sink.
+     */
+    readonly materialized: IMaterializedReadModels;
+
+    /**
+     * Registers all discovered read models.
+     * @returns A promise that resolves when registration completes.
+     */
+    register(): Promise<void>;
+
+    /**
+     * Registers a specific read model type.
+     * @param readModelType - The read model type to register.
+     * @returns A promise that resolves when registration completes.
+     */
+    register<TReadModel>(readModelType: Constructor<TReadModel>): Promise<void>;
+
+    /**
+     * Gets a read model instance by key.
+     * @param readModelType - The read model type to retrieve.
+     * @param key - The read model key.
+     * @param sessionId - Optional session identifier.
+     * @returns The read model instance.
+     */
+    getInstanceById<TReadModel>(readModelType: Constructor<TReadModel>, key: string, sessionId?: string): Promise<TReadModel>;
+
+    /**
+     * Gets all instances of a read model.
+     * @param readModelType - The read model type to retrieve.
+     * @param eventCount - Optional maximum number of events to process.
+     * @returns The read model instances.
+     */
+    getInstances<TReadModel>(readModelType: Constructor<TReadModel>, eventCount?: bigint): Promise<TReadModel[]>;
+
+    /**
+     * Gets snapshots for a read model instance by key.
+     * @param readModelType - The read model type to retrieve snapshots for.
+     * @param key - The read model key.
+     * @returns The read model snapshots.
+     */
+    getSnapshotsById<TReadModel>(readModelType: Constructor<TReadModel>, key: string): Promise<ReadModelSnapshot<TReadModel>[]>;
+
+    /**
+     * Watches changes for a specific read model type.
+     * @param readModelType - The read model type to observe.
+     * @returns An async iterable of read model changes.
+     */
+    watch<TReadModel>(readModelType: Constructor<TReadModel>): AsyncIterable<ReadModelChangeset<TReadModel>>;
+
+    /**
+     * Dehydrates a read model session.
+     * @param sessionId - The session identifier to dehydrate.
+     * @param readModelType - The read model type.
+     * @param key - The read model key.
+     * @returns A promise that resolves when dehydration completes.
+     */
+    dehydrateSession<TReadModel>(sessionId: string, readModelType: Constructor<TReadModel>, key: string): Promise<void>;
+
+    /**
+     * Releases (decrypts) PII properties in a read model instance.
+     * @param readModelType - The read model type.
+     * @param instance - The read model instance with encrypted PII.
+     * @returns The read model instance with decrypted PII values.
+     */
+    release<TReadModel>(readModelType: Constructor<TReadModel>, instance: TReadModel): Promise<TReadModel>;
+
+    /**
+     * Releases (decrypts) PII properties in multiple read model instances.
+     * @param readModelType - The read model type.
+     * @param instances - The read model instances with encrypted PII.
+     * @returns The read model instances with decrypted PII values.
+     */
+    releaseMany<TReadModel>(readModelType: Constructor<TReadModel>, instances: TReadModel[]): Promise<TReadModel[]>;
+}

package/readModels/MaterializedReadModels.ts

@@ -0,0 +1,151 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Constructor } from '@cratis/fundamentals';
+import { JsonSerializer } from '@cratis/fundamentals';
+import { ChronicleConnection } from '../connection';
+import { JsonSchemaGenerator } from '../schemas';
+import { getReadModelMetadata } from './readModel';
+import type { IMaterializedReadModels } from './IMaterializedReadModels';
+
+const defaultTake = 50;
+
+/**
+ * Implements {@link IMaterializedReadModels} by working with the Chronicle materialized read model gRPC service.
+ */
+export class MaterializedReadModels implements IMaterializedReadModels {
+    constructor(
+        private readonly _eventStore: string,
+        private readonly _namespace: string,
+        private readonly _connection: ChronicleConnection
+    ) {}
+
+    /** @inheritdoc */
+    async getInstances<TReadModel>(readModelType: Constructor<TReadModel>, skip: number = 0, take: number = defaultTake): Promise<TReadModel[]> {
+        const readModelIdentifier = this.resolveIdentifier(readModelType);
+        const { page, pageSize, skipWithinPage } = this.toPageParams(skip, take);
+
+        const response = await this._connection.materializedReadModels.getInstances({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            ReadModel: readModelIdentifier,
+            Page: page,
+            PageSize: pageSize
+        });
+
+        let instances = response.Instances.map(json => this.deserialize(readModelType, json));
+
+        if (skipWithinPage > 0) {
+            instances = instances.slice(skipWithinPage);
+        }
+
+        return this.releaseInstances(readModelType, instances);
+    }
+
+    /** @inheritdoc */
+    async *observeInstances<TReadModel>(readModelType: Constructor<TReadModel>, skip: number = 0, take: number = defaultTake): AsyncIterable<TReadModel[]> {
+        const readModelIdentifier = this.resolveIdentifier(readModelType);
+        const { page, pageSize, skipWithinPage } = this.toPageParams(skip, take);
+
+        for await (const response of this._connection.materializedReadModels.observeInstances({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            ReadModel: readModelIdentifier,
+            Page: page,
+            PageSize: pageSize
+        })) {
+            let instances = response.Instances.map(json => this.deserialize(readModelType, json));
+
+            if (skipWithinPage > 0) {
+                instances = instances.slice(skipWithinPage);
+            }
+
+            yield await this.releaseInstances(readModelType, instances);
+        }
+    }
+
+    private resolveIdentifier<TReadModel>(readModelType: Constructor<TReadModel>): string {
+        const metadata = getReadModelMetadata(readModelType);
+        return metadata?.id.value ?? readModelType.name;
+    }
+
+    private toPageParams(skip: number, take: number): { page: number; pageSize: number; skipWithinPage: number } {
+        if (take <= 0) {
+            return { page: 0, pageSize: Number.MAX_SAFE_INTEGER, skipWithinPage: 0 };
+        }
+
+        const page = skip > 0 ? Math.floor(skip / take) : 0;
+        const skipWithinPage = skip % take;
+
+        return { page, pageSize: take, skipWithinPage };
+    }
+
+    private deserialize<TReadModel>(readModelType: Constructor<TReadModel>, json: string): TReadModel {
+        if (!json) {
+            return Object.create(readModelType.prototype) as TReadModel;
+        }
+        return JsonSerializer.deserialize(readModelType as Constructor<object>, json) as TReadModel;
+    }
+
+    private async releaseInstances<TReadModel>(readModelType: Constructor<TReadModel>, instances: TReadModel[]): Promise<TReadModel[]> {
+        const schema = this.getSchema(readModelType);
+        if (!this.schemaHasComplianceMetadata(schema)) {
+            return instances;
+        }
+
+        return Promise.all(instances.map(instance => this.releaseInstance(readModelType, instance, schema)));
+    }
+
+    private async releaseInstance<TReadModel>(readModelType: Constructor<TReadModel>, instance: TReadModel, schema: string): Promise<TReadModel> {
+        const subject = this.extractSubject(instance);
+        if (!subject) {
+            return instance;
+        }
+
+        const payload = JsonSerializer.serialize(instance);
+        const response = await this._connection.compliance.release({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            Subject: subject,
+            Schema: schema,
+            Payload: payload
+        });
+
+        if (response.HasError) {
+            return instance;
+        }
+
+        return this.deserialize(readModelType, response.Payload);
+    }
+
+    private getSchema<TReadModel>(readModelType: Constructor<TReadModel>): string {
+        const metadata = getReadModelMetadata(readModelType);
+        if (metadata) {
+            return JSON.stringify(metadata.schema);
+        }
+        return JSON.stringify(JsonSchemaGenerator.generate(readModelType) ?? JsonSchemaGenerator.createEmptySchema(readModelType.name));
+    }
+
+    private schemaHasComplianceMetadata(schema: string): boolean {
+        try {
+            const parsed = JSON.parse(schema) as Record<string, unknown>;
+            const properties = parsed.properties as Record<string, Record<string, unknown>> | undefined;
+            if (!properties) {
+                return false;
+            }
+            return Object.values(properties).some(
+                property => Array.isArray(property.compliance) && (property.compliance as unknown[]).length > 0
+            );
+        } catch {
+            return false;
+        }
+    }
+
+    private extractSubject<TReadModel>(instance: TReadModel): string | undefined {
+        const anyInstance = instance as Record<string, unknown>;
+        if (anyInstance.id !== undefined && anyInstance.id !== null) {
+            return String(anyInstance.id);
+        }
+        return undefined;
+    }
+}

package/readModels/ReadModelChangeset.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 a change observed for a read model.
+ */
+export interface ReadModelChangeset<TReadModel> {
+    /** The namespace the change belongs to. */
+    readonly namespace: string;
+
+    /** The read model key. */
+    readonly key: string;
+
+    /** The current read model state. */
+    readonly readModel: TReadModel;
+
+    /** Whether the read model was removed. */
+    readonly removed: boolean;
+}

package/readModels/ReadModelSnapshot.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { AppendedEvent, Guid as ContractsGuid } from '@cratis/chronicle.contracts';
+
+/**
+ * Represents a read model snapshot together with the events that produced it.
+ */
+export interface ReadModelSnapshot<TReadModel> {
+    /** The read model state at the snapshot. */
+    readonly readModel: TReadModel;
+
+    /** The events that were applied to reach the snapshot. */
+    readonly events: AppendedEvent[];
+
+    /** When the snapshot occurred. */
+    readonly occurred: Date | undefined;
+
+    /** The correlation identifier for the snapshot, when available. */
+    readonly correlationId: ContractsGuid | undefined;
+}