@cratis/chronicle 0.2.0 → 0.2.1

package/readModels/ReadModels.ts

@@ -0,0 +1,333 @@
+// 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,
+    ReadModelObserverType
+} from '@cratis/chronicle.contracts';
+import {
+    ReadModelObserverType as ContractReadModelObserverType
+} from '@cratis/chronicle.contracts';
+import type { Constructor } from '@cratis/fundamentals';
+import { JsonSerializer } from '@cratis/fundamentals';
+import { IClientArtifactsProvider } from '../artifacts';
+import { toContractsGuid } from '../connection/Guid';
+import { ChronicleConnection } from '../connection';
+import { EventSequenceId } from '../eventSequences/EventSequenceId';
+import { getProjectionMetadata } from '../projections/declarative/projection';
+import { hasFromEventMetadata } from '../projections/modelBound/fromEvent';
+import { getReducerMetadata } from '../reducers/reducer';
+import { JsonSchemaGenerator } from '../schemas';
+import { WellKnownSinks } from '../sinks';
+import { getReadModelMetadata } from './readModel';
+import type { IMaterializedReadModels } from './IMaterializedReadModels';
+import { MaterializedReadModels } from './MaterializedReadModels';
+import type { IReadModels } from './IReadModels';
+import type { ReadModelChangeset } from './ReadModelChangeset';
+import type { ReadModelSnapshot } from './ReadModelSnapshot';
+
+const unlimitedEventCount = BigInt('18446744073709551615');
+
+interface ResolvedReadModel {
+    readonly type: Constructor;
+    readonly identifier: string;
+    readonly eventSequenceId: string;
+    readonly observerType: ReadModelObserverType;
+    readonly observerIdentifier: string;
+    readonly schema: string;
+}
+
+/**
+ * Implements {@link IReadModels} by working with the Chronicle read-model gRPC service.
+ */
+export class ReadModels implements IReadModels {
+    readonly materialized: IMaterializedReadModels;
+
+    constructor(
+        private readonly _eventStore: string,
+        private readonly _namespace: string,
+        private readonly _connection: ChronicleConnection,
+        private readonly _clientArtifacts: IClientArtifactsProvider
+    ) {
+        this.materialized = new MaterializedReadModels(_eventStore, _namespace, _connection);
+    }
+
+    /** @inheritdoc */
+    async register<TReadModel>(readModelType?: Constructor<TReadModel>): Promise<void> {
+        const readModels = this.resolveReadModels(readModelType);
+        if (readModels.length === 0) {
+            return;
+        }
+
+        await this._connection.readModels.registerMany({
+            EventStore: this._eventStore,
+            Owner: 1,
+            Source: 1,
+            ReadModels: readModels.map(readModel => this.toDefinition(readModel))
+        });
+    }
+
+    /** @inheritdoc */
+    async getInstanceById<TReadModel>(readModelType: Constructor<TReadModel>, key: string, sessionId?: string): Promise<TReadModel> {
+        const readModel = this.resolveReadModel(readModelType);
+        const response = await this._connection.readModels.getInstanceByKey({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            ReadModelIdentifier: readModel.identifier,
+            EventSequenceId: readModel.eventSequenceId,
+            ReadModelKey: key,
+            SessionId: sessionId ?? ''
+        });
+
+        const instance = this.deserializeReadModel(readModelType, response.ReadModel);
+
+        if (readModel.observerType === ContractReadModelObserverType.Reducer && this.schemaHasComplianceMetadata(readModel.schema)) {
+            return this.release(readModelType, instance);
+        }
+
+        return instance;
+    }
+
+    /** @inheritdoc */
+    async getInstances<TReadModel>(readModelType: Constructor<TReadModel>, eventCount: bigint = unlimitedEventCount): Promise<TReadModel[]> {
+        const readModel = this.resolveReadModel(readModelType);
+        const response = await this._connection.readModels.getAllInstances({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            ReadModelIdentifier: readModel.identifier,
+            EventSequenceId: readModel.eventSequenceId,
+            EventCount: eventCount
+        });
+
+        const instances = response.Instances.map(instance => this.deserializeReadModel(readModelType, instance));
+
+        if (readModel.observerType === ContractReadModelObserverType.Reducer && this.schemaHasComplianceMetadata(readModel.schema)) {
+            return this.releaseMany(readModelType, instances);
+        }
+
+        return instances;
+    }
+
+    /** @inheritdoc */
+    async getSnapshotsById<TReadModel>(readModelType: Constructor<TReadModel>, key: string): Promise<ReadModelSnapshot<TReadModel>[]> {
+        const readModel = this.resolveReadModel(readModelType);
+        const response = await this._connection.readModels.getSnapshotsByKey({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            ReadModelIdentifier: readModel.identifier,
+            EventSequenceId: readModel.eventSequenceId,
+            ReadModelKey: key
+        });
+
+        return response.Snapshots.map(snapshot => ({
+            readModel: this.deserializeReadModel(readModelType, snapshot.ReadModel),
+            events: (snapshot.Events ?? []) as AppendedEvent[],
+            occurred: snapshot.Occurred?.Value ? new Date(snapshot.Occurred.Value) : undefined,
+            correlationId: snapshot.CorrelationId
+        }));
+    }
+
+    /** @inheritdoc */
+    async *watch<TReadModel>(readModelType: Constructor<TReadModel>): AsyncIterable<ReadModelChangeset<TReadModel>> {
+        const readModel = this.resolveReadModel(readModelType);
+
+        for await (const changeset of this._connection.readModels.watch({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            ReadModelIdentifier: readModel.identifier,
+            EventSequenceId: readModel.eventSequenceId
+        })) {
+            yield {
+                namespace: changeset.Namespace,
+                key: changeset.ModelKey,
+                readModel: this.deserializeReadModel(readModelType, changeset.ReadModel),
+                removed: changeset.Removed
+            };
+        }
+    }
+
+    /** @inheritdoc */
+    async dehydrateSession<TReadModel>(sessionId: string, readModelType: Constructor<TReadModel>, key: string): Promise<void> {
+        const readModel = this.resolveReadModel(readModelType);
+        await this._connection.readModels.dehydrateSession({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            ReadModelIdentifier: readModel.identifier,
+            EventSequenceId: readModel.eventSequenceId,
+            ReadModelKey: key,
+            SessionId: sessionId
+        });
+    }
+
+    /** @inheritdoc */
+    async release<TReadModel>(readModelType: Constructor<TReadModel>, instance: TReadModel): Promise<TReadModel> {
+        const readModel = this.resolveReadModel(readModelType);
+        const schema = this.getReadModelSchema(readModelType, readModel.identifier);
+        const payload = JsonSerializer.serialize(instance);
+        const subject = this.extractSubject(instance);
+
+        const response = await this._connection.compliance.release({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            Subject: subject,
+            Schema: schema,
+            Payload: payload
+        });
+
+        if (response.HasError) {
+            throw new Error(`Failed to release PII: ${response.Error}`);
+        }
+
+        return this.deserializeReadModel(readModelType, response.Payload);
+    }
+
+    /** @inheritdoc */
+    async releaseMany<TReadModel>(readModelType: Constructor<TReadModel>, instances: TReadModel[]): Promise<TReadModel[]> {
+        const releasePromises = instances.map(instance => this.release(readModelType, instance));
+        return Promise.all(releasePromises);
+    }
+
+    private resolveReadModels<TReadModel>(readModelType?: Constructor<TReadModel>): ResolvedReadModel[] {
+        const resolved = new Map<string, ResolvedReadModel>();
+
+        for (const projectionType of this._clientArtifacts.projections) {
+            const metadata = getProjectionMetadata(projectionType);
+            if (!metadata?.readModelType) {
+                continue;
+            }
+
+            if (readModelType && metadata.readModelType !== readModelType) {
+                continue;
+            }
+
+            const readModelMetadata = getReadModelMetadata(metadata.readModelType);
+            const identifier = readModelMetadata?.id.value ?? metadata.readModelType.name;
+            resolved.set(identifier, {
+                type: metadata.readModelType,
+                identifier,
+                eventSequenceId: metadata.eventSequenceId ?? EventSequenceId.eventLog.value,
+                observerType: ContractReadModelObserverType.Projection,
+                observerIdentifier: metadata.id.value,
+                schema: this.getReadModelSchema(metadata.readModelType, identifier)
+            });
+        }
+
+        for (const modelBoundType of this._clientArtifacts.readModels) {
+            if (!hasFromEventMetadata(modelBoundType)) {
+                continue;
+            }
+
+            if (readModelType && modelBoundType !== readModelType) {
+                continue;
+            }
+
+            const metadata = getReadModelMetadata(modelBoundType);
+            if (!metadata) {
+                continue;
+            }
+
+            resolved.set(metadata.id.value, {
+                type: modelBoundType,
+                identifier: metadata.id.value,
+                eventSequenceId: EventSequenceId.eventLog.value,
+                observerType: ContractReadModelObserverType.Projection,
+                observerIdentifier: metadata.id.value,
+                schema: JSON.stringify(metadata.schema)
+            });
+        }
+
+        for (const reducerType of this._clientArtifacts.reducers) {
+            const metadata = getReducerMetadata(reducerType);
+            if (!metadata?.readModel) {
+                continue;
+            }
+
+            if (readModelType && metadata.readModel !== readModelType) {
+                continue;
+            }
+
+            const readModelMetadata = getReadModelMetadata(metadata.readModel);
+            const identifier = readModelMetadata?.id.value ?? metadata.readModel.name;
+            resolved.set(identifier, {
+                type: metadata.readModel,
+                identifier,
+                eventSequenceId: metadata.eventSequenceId ?? EventSequenceId.eventLog.value,
+                observerType: ContractReadModelObserverType.Reducer,
+                observerIdentifier: metadata.id.value,
+                schema: this.getReadModelSchema(metadata.readModel, identifier)
+            });
+        }
+
+        return Array.from(resolved.values());
+    }
+
+    private resolveReadModel<TReadModel>(readModelType: Constructor<TReadModel>): ResolvedReadModel {
+        const [resolved] = this.resolveReadModels(readModelType);
+        if (!resolved) {
+            throw new Error(`Unknown read model '${readModelType.name}'. Make sure it is decorated and discoverable.`);
+        }
+
+        return resolved;
+    }
+
+    private toDefinition(readModel: ResolvedReadModel) {
+        return {
+            Type: {
+                Identifier: readModel.identifier,
+                Generation: 1
+            },
+            ContainerName: readModel.identifier,
+            DisplayName: readModel.identifier,
+            Sink: {
+                ConfigurationId: toContractsGuid(WellKnownSinks.Null),
+                TypeId: toContractsGuid(WellKnownSinks.MongoDB)
+            },
+            Schema: readModel.schema,
+            Indexes: [],
+            ObserverType: readModel.observerType,
+            ObserverIdentifier: readModel.observerIdentifier,
+            Owner: 1,
+            Source: 1
+        };
+    }
+
+    private getReadModelSchema(readModelType: Constructor, identifier: string): string {
+        const metadata = getReadModelMetadata(readModelType);
+        if (metadata) {
+            return JSON.stringify(metadata.schema);
+        }
+
+        return JSON.stringify(JsonSchemaGenerator.generate(readModelType) ?? JsonSchemaGenerator.createEmptySchema(identifier));
+    }
+
+    private deserializeReadModel<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 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 {
+        // By convention, use the 'id' property as the subject
+        const anyInstance = instance as any;
+        if (anyInstance.id !== undefined && anyInstance.id !== null) {
+            return String(anyInstance.id);
+        }
+        throw new Error('Read model instance must have an "id" property to serve as the subject for PII release');
+    }
+}

package/readModels/index.ts

@@ -2,5 +2,11 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 export { ReadModelId } from './ReadModelId';
+export type { IReadModels } from './IReadModels';
+export type { IMaterializedReadModels } from './IMaterializedReadModels';
+export { ReadModels } from './ReadModels';
+export { MaterializedReadModels } from './MaterializedReadModels';
+export type { ReadModelChangeset } from './ReadModelChangeset';
+export type { ReadModelSnapshot } from './ReadModelSnapshot';
 export { readModel, getReadModelMetadata, isReadModel } from './readModel';
 export type { ReadModelMetadata } from './readModel';

package/readModels/readModel.ts

@@ -33,7 +33,6 @@ export function readModel(id: string = ''): ClassDecorator {
     return (target: object) => {
         const constructor = target as Function;
         const readModelId = new ReadModelId(id || constructor.name);
-        trackInstanceProperties(constructor);
         const members = TypeIntrospector.getMembers(constructor);
         const metadata: ReadModelMetadata = {
             id: readModelId,
@@ -49,27 +48,6 @@ export function readModel(id: string = ''): ClassDecorator {
     };
 }
 
-function trackInstanceProperties(constructor: Function): void {
-    const instance = tryCreateInstance(constructor);
-    if (!instance || typeof instance !== 'object') {
-        return;
-    }
-
-    for (const propertyName of Object.keys(instance as Record<string, unknown>)) {
-        TypeIntrospector.trackProperty(constructor, propertyName);
-    }
-}
-
-function tryCreateInstance(constructor: Function): unknown {
-    try {
-        const parameterCount = constructor.length;
-        const parameters = Array.from({ length: parameterCount }, () => undefined);
-        return Reflect.construct(constructor as new (...args: unknown[]) => unknown, parameters);
-    } catch {
-        return undefined;
-    }
-}
-
 /**
  * Gets the {@link ReadModelMetadata} associated with a class decorated with {@link readModel}.
  * @param target - The class constructor to retrieve metadata for.

package/reducers/Reducers.ts

@@ -159,7 +159,7 @@ export class Reducers implements IReducers {
         }
 
         const readModels = Array.from(this._reducers.entries()).map(([id, reducerType]) => {
-            const readModelName = (reducerType as Function).name;
+            const readModelName = this.getReducerReadModelIdentifier(reducerType);
             return {
                 Type: {
                     Identifier: readModelName,
@@ -212,7 +212,7 @@ export class Reducers implements IReducers {
         const metadata = getReducerMetadata(reducerType)!;
         const eventSequenceId = metadata.eventSequenceId ?? EventSequenceId.eventLog.value;
         const eventTypes = this.getEventTypesFor(reducerType);
-        const readModelName = (reducerType as Function).name;
+        const readModelName = this.getReducerReadModelIdentifier(reducerType);
 
         this._logger.info('Starting reducer observation', {
             reducerId: id,
@@ -227,6 +227,15 @@ export class Reducers implements IReducers {
         });
     }
 
+    private getReducerReadModelIdentifier(reducerType: Constructor): string {
+        const metadata = getReducerMetadata(reducerType);
+        if (metadata?.readModel) {
+            return getReadModelMetadata(metadata.readModel)?.id.value ?? metadata.readModel.name;
+        }
+
+        return (reducerType as Function).name;
+    }
+
     private async observeReducer(
         id: string,
         reducerType: Constructor,
@@ -309,7 +318,7 @@ export class Reducers implements IReducers {
                         this._logger.info('Invoking reducer handler', {
                             reducerId: id,
                             method: entry.methodName,
-                            sequenceNumber: event.Context!.SequenceNumber,
+                            sequenceNumber: event.Context!.SequenceNumber.toString(),
                             eventTypeId,
                             hasState: currentState !== undefined
                         });

package/schemas/JsonSchemaGenerator.ts

@@ -2,9 +2,10 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import 'reflect-metadata';
-import { Guid } from '@cratis/fundamentals';
+import { ConceptAs, Guid } from '@cratis/fundamentals';
 import { JsonSchema } from './JsonSchema';
 import { TypeIntrospector } from '../types';
+import { ComplianceMetadataResolver } from '../compliance/ComplianceMetadataResolver';
 
 /**
  * Generates JSON schemas for class constructors using reflection metadata.
@@ -44,12 +45,15 @@ export class JsonSchemaGenerator {
     static generate(target: Function, members?: ReadonlyMap<string, Function | undefined>): JsonSchema {
         const membersToUse = members ?? TypeIntrospector.getMembers(target);
         const schemaProperties: Record<string, JsonSchema> = {};
+        const prototype = target.prototype;
 
         for (const [memberName, memberType] of membersToUse.entries()) {
             const propertySchema = this.mapRuntimeTypeToSchema(memberType);
             // Only include properties whose type was resolved. An empty schema ({}) means
             // the runtime type was unavailable (e.g. esbuild/tsx omits design:paramtypes).
             if (Object.keys(propertySchema).length > 0) {
+                // Add compliance metadata to property schema if present (both property and type-level)
+                this.addComplianceMetadata(propertySchema, prototype, memberName, memberType);
                 schemaProperties[memberName] = propertySchema;
             }
         }
@@ -94,6 +98,16 @@ export class JsonSchemaGenerator {
             return {};
         }
 
+        // A ConceptAs<T> serializes as its underlying primitive value, so the schema must
+        // describe that primitive rather than the wrapper object. The generic argument T is
+        // not available at runtime, so resolve it from the 'value' property's design:type
+        // when present (ts-node/webpack with emitDecoratorMetadata) and fall back to string
+        // when it is not (esbuild/tsx) — string-backed concepts are by far the common case.
+        if (this.isConceptAs(runtimeType)) {
+            const valueType = Reflect.getMetadata('design:type', runtimeType.prototype, 'value') as Function | undefined;
+            return this.mapRuntimeTypeToSchema(valueType ?? String);
+        }
+
         if (runtimeType !== Object) {
             return this.generate(runtimeType);
         }
@@ -101,6 +115,19 @@ export class JsonSchemaGenerator {
         return { type: 'object' };
     }
 
+    private static isConceptAs(runtimeType: Function): boolean {
+        let current: Function | null = runtimeType;
+        while (current && current !== Function.prototype) {
+            if (current === ConceptAs) {
+                return true;
+            }
+
+            current = Object.getPrototypeOf(current) as Function | null;
+        }
+
+        return false;
+    }
+
     private static getKnownTypeFormat(runtimeType: Function | undefined): JsonSchema | undefined {
         if (!runtimeType) {
             return undefined;
@@ -121,4 +148,37 @@ export class JsonSchemaGenerator {
         const normalized = format.toLowerCase();
         return this._formatAliases.get(normalized) ?? normalized;
     }
+
+    /**
+     * Adds compliance metadata to a property schema if the property has compliance decorators.
+     * Also checks if the property's type itself is marked as PII (e.g., ConceptAs types).
+     * @param schema - The property schema to add compliance metadata to.
+     * @param target - The class prototype.
+     * @param propertyKey - The property name.
+     */
+    private static addComplianceMetadata(schema: JsonSchema, target: object, propertyKey: string, propertyType?: Function): void {
+        const complianceArray: Array<{ metadataType: string; details: string }> = [];
+
+        // Check for property-level compliance decorators
+        if (ComplianceMetadataResolver.hasMetadataFor(target, propertyKey)) {
+            const propertyMetadata = ComplianceMetadataResolver.getMetadataFor(target, propertyKey);
+            complianceArray.push(...propertyMetadata.map(metadata => ({
+                metadataType: metadata.metadataType.value.toString(),
+                details: metadata.details
+            })));
+        }
+
+        // Check for type-level compliance decorators (e.g., @pii on ConceptAs)
+        if (propertyType) {
+            const typeMetadata = ComplianceMetadataResolver.getMetadataForType(propertyType);
+            complianceArray.push(...typeMetadata.map(metadata => ({
+                metadataType: metadata.metadataType.value.toString(),
+                details: metadata.details
+            })));
+        }
+
+        if (complianceArray.length > 0) {
+            (schema as Record<string, unknown>).compliance = complianceArray;
+        }
+    }
 }

package/types/TypeIntrospector.ts

@@ -2,6 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import 'reflect-metadata';
+import { Constructor, Fields } from '@cratis/fundamentals';
 
 /** Metadata key for tracked schema properties on a target type. */
 const TRACKED_PROPERTIES_METADATA_KEY = 'chronicle:typeIntrospection:properties';
@@ -35,16 +36,35 @@ export class TypeIntrospector {
 
     /**
      * Gets members and their runtime types for a class.
-     * Members are discovered from tracked properties and constructor parameters.
+     * Members are discovered from explicit `@field` decorators, tracked properties, the
+     * properties present on a default-constructed instance, and constructor parameters.
+     *
+     * `@field` declarations are the authoritative source: they carry the exact declared
+     * type (including `ConceptAs` types) regardless of whether the property has an
+     * initializer, so event types — whose properties are typically declared with definite
+     * assignment (`prop!: T`) and no default value — resolve their schema just like read
+     * models. Default-value and `design:type` resolution remain as fallbacks for plain
+     * classes that don't use `@field`, and keep working even under esbuild/tsx, which does
+     * not emit decorator metadata ('design:type'/'design:paramtypes').
      * @param target - The class constructor to inspect.
      * @returns A map of member name to runtime type.
      */
     static getMembers(target: Function): Map<string, Function | undefined> {
         const members = new Map<string, Function | undefined>();
         const defaultValues = this.tryGetDefaultPropertyValues(target);
+        const fieldTypes = this.getFieldTypes(target);
 
-        for (const property of this.getTrackedProperties(target)) {
-            let runtimeType = Reflect.getMetadata('design:type', target.prototype, property) as Function | undefined;
+        const propertyNames = new Set<string>([
+            ...this.getTrackedProperties(target),
+            ...fieldTypes.keys(),
+            ...Object.keys(defaultValues)
+        ]);
+
+        for (const property of propertyNames) {
+            let runtimeType = fieldTypes.get(property);
+            if (!runtimeType || runtimeType === Object) {
+                runtimeType = Reflect.getMetadata('design:type', target.prototype, property) as Function | undefined;
+            }
             if (!runtimeType || runtimeType === Object) {
                 runtimeType = this.getRuntimeTypeFromValue(defaultValues[property]);
             }
@@ -67,6 +87,15 @@ export class TypeIntrospector {
         return members;
     }
 
+    private static getFieldTypes(target: Function): Map<string, Function | undefined> {
+        const fieldTypes = new Map<string, Function | undefined>();
+        for (const field of Fields.getFieldsForType(target as Constructor)) {
+            fieldTypes.set(field.name, field.type);
+        }
+
+        return fieldTypes;
+    }
+
     private static tryGetDefaultPropertyValues(target: Function): Record<string, unknown> {
         try {
             const parameters = Array.from({ length: target.length }, () => undefined);