@cratis/chronicle 3.1.1 → 4.0.0

package/readModels/ReadModelSubjectResolver.ts

@@ -0,0 +1,44 @@
+// 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 { getSubjectPropertyName } from '../compliance/subject';
+
+/**
+ * Resolves the compliance subject - the natural person a read model's Personal Identifiable
+ * Information (PII) belongs to - from a read model instance.
+ */
+export class ReadModelSubjectResolver {
+    /**
+     * Attempts to derive the compliance subject from a read model instance.
+     *
+     * Resolution order:
+     * 1. The property decorated with `@subject()` on {@link readModelType}, when it has a value.
+     * 2. The `id` property, by convention - kept so read models that predate `@subject()`
+     *    continue to resolve exactly as before.
+     * @param readModelType - The read model type to resolve subject metadata for.
+     * @param instance - The read model instance to inspect, or undefined/null for a read model
+     * that does not exist.
+     * @returns The resolved subject, or undefined when neither source yields a value.
+     */
+    static resolveFrom<TReadModel>(readModelType: Constructor<TReadModel>, instance: TReadModel): string | undefined {
+        if (instance === undefined || instance === null) {
+            return undefined;
+        }
+
+        const anyInstance = instance as Record<string, unknown>;
+        const subjectProperty = getSubjectPropertyName(readModelType);
+        const explicitSubject = subjectProperty ? ReadModelSubjectResolver.toSubject(anyInstance[subjectProperty]) : undefined;
+
+        return explicitSubject ?? ReadModelSubjectResolver.toSubject(anyInstance.id);
+    }
+
+    private static toSubject(value: unknown): string | undefined {
+        if (value === undefined || value === null) {
+            return undefined;
+        }
+
+        const stringValue = String(value);
+        return stringValue.length > 0 ? stringValue : undefined;
+    }
+}

package/readModels/ReadModels.spec.ts

@@ -0,0 +1,118 @@
+// 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 { Constructor } from '@cratis/fundamentals';
+import { describe, expect, it, vi } from 'vitest';
+import type { IClientArtifactsProvider } from '../artifacts';
+import type { ChronicleConnection } from '../connection';
+import { subject } from '../compliance/subject';
+import { fromEvent } from '../projections/modelBound/fromEvent';
+import { readModel } from './readModel';
+import { ReadModels } from './ReadModels';
+
+// Decorators are applied as plain function calls (rather than `@decorator` syntax) so these
+// fixtures don't depend on the test runner's decorator-syntax support.
+
+class SomeEvent {
+    value = '';
+}
+
+function createReadModels(readModelType: Constructor, releaseResponse: Record<string, unknown> = { HasError: false, Payload: '{}' }) {
+    const release = vi.fn().mockResolvedValue(releaseResponse);
+    const connection = {
+        compliance: { release }
+    } as unknown as ChronicleConnection;
+
+    const clientArtifacts = {
+        eventTypes: [],
+        readModels: [readModelType],
+        reactors: [],
+        reducers: [],
+        seeders: [],
+        constraints: [],
+        projections: [],
+        webhooks: [],
+        eventTypeMigrations: []
+    } as IClientArtifactsProvider;
+
+    const readModels = new ReadModels('test-store', 'test-namespace', connection, clientArtifacts, 'default-sink');
+    return { readModels, release };
+}
+
+describe('ReadModels', () => {
+    describe('when releasing a read model with a property decorated with @subject()', () => {
+        class Employee {
+            id = '';
+            personId = '';
+        }
+        subject()(Employee.prototype, 'personId');
+        fromEvent(SomeEvent)(Employee);
+        readModel('EmployeeWithSubject')(Employee);
+
+        it('should release using the decorated property as the subject', async () => {
+            const { readModels, release } = createReadModels(Employee);
+            const instance = new Employee();
+            instance.id = 'employee-1';
+            instance.personId = 'person-42';
+
+            await readModels.release(Employee, instance);
+
+            expect(release).toHaveBeenCalledWith(expect.objectContaining({ Subject: 'person-42' }));
+        });
+    });
+
+    describe('when releasing a read model without @subject() but with an id property', () => {
+        class Customer {
+            id = '';
+        }
+        fromEvent(SomeEvent)(Customer);
+        readModel('CustomerWithIdOnly')(Customer);
+
+        it('should fall back to the id property as the subject, unchanged from today', async () => {
+            const { readModels, release } = createReadModels(Customer);
+            const instance = new Customer();
+            instance.id = 'customer-7';
+
+            await readModels.release(Customer, instance);
+
+            expect(release).toHaveBeenCalledWith(expect.objectContaining({ Subject: 'customer-7' }));
+        });
+    });
+
+    describe('when releasing a read model with neither @subject() nor an id property', () => {
+        class Anonymous {
+            name = '';
+        }
+        fromEvent(SomeEvent)(Anonymous);
+        readModel('AnonymousReadModel')(Anonymous);
+
+        it('should throw, same as today', async () => {
+            const { readModels } = createReadModels(Anonymous);
+            const instance = new Anonymous();
+
+            await expect(readModels.release(Anonymous, instance)).rejects.toThrow(/subject/);
+        });
+    });
+
+    describe('when releasing many read model instances', () => {
+        class Customer {
+            id = '';
+        }
+        fromEvent(SomeEvent)(Customer);
+        readModel('CustomerForReleaseMany')(Customer);
+
+        it('should release each instance using its own resolved subject', async () => {
+            const { readModels, release } = createReadModels(Customer);
+            const first = new Customer();
+            first.id = 'customer-1';
+            const second = new Customer();
+            second.id = 'customer-2';
+
+            await readModels.releaseMany(Customer, [first, second]);
+
+            expect(release).toHaveBeenCalledWith(expect.objectContaining({ Subject: 'customer-1' }));
+            expect(release).toHaveBeenCalledWith(expect.objectContaining({ Subject: 'customer-2' }));
+        });
+    });
+});

package/readModels/ReadModels.ts

@@ -23,6 +23,7 @@ import { WellKnownSinks } from '../sinks';
 import { getReadModelMetadata } from './readModel';
 import type { IMaterializedReadModels } from './IMaterializedReadModels';
 import { MaterializedReadModels } from './MaterializedReadModels';
+import { ReadModelSubjectResolver } from './ReadModelSubjectResolver';
 import type { IReadModels } from './IReadModels';
 import type { ReadModelChangeset } from './ReadModelChangeset';
 import type { ReadModelSnapshot } from './ReadModelSnapshot';
@@ -173,7 +174,7 @@ export class ReadModels implements IReadModels {
         const readModel = this.resolveReadModel(readModelType);
         const schema = this.getReadModelSchema(readModelType, readModel.identifier);
         const payload = JsonSerializer.serialize(instance);
-        const subject = this.extractSubject(instance);
+        const subject = this.extractSubject(readModelType, instance);
 
         const response = await this._connection.compliance.release({
             EventStore: this._eventStore,
@@ -345,12 +346,11 @@ export class ReadModels implements IReadModels {
         }
     }
 
-    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);
+    private extractSubject<TReadModel>(readModelType: Constructor<TReadModel>, instance: TReadModel): string {
+        const subject = ReadModelSubjectResolver.resolveFrom(readModelType, instance);
+        if (subject !== undefined) {
+            return subject;
         }
-        throw new Error('Read model instance must have an "id" property to serve as the subject for PII release');
+        throw new Error('Read model instance must have a property decorated with @subject() or an "id" property to serve as the subject for PII release');
     }
 }

package/readModels/index.ts

@@ -6,6 +6,7 @@ export type { IReadModels } from './IReadModels';
 export type { IMaterializedReadModels } from './IMaterializedReadModels';
 export { ReadModels } from './ReadModels';
 export { MaterializedReadModels } from './MaterializedReadModels';
+export { ReadModelSubjectResolver } from './ReadModelSubjectResolver';
 export type { ReadModelChangeset } from './ReadModelChangeset';
 export type { ReadModelSnapshot } from './ReadModelSnapshot';
 export { readModel, getReadModelMetadata, isReadModel } from './readModel';

package/reducers/Reducers.spec.ts

@@ -6,11 +6,48 @@ import type { Constructor } from '@cratis/fundamentals';
 import type { IClientArtifactsProvider } from '../artifacts';
 import type { ChronicleConnection } from '../connection';
 import { ConnectionLifecycle } from '../connection/ConnectionLifecycle';
+import { eventType, getEventTypeFor } from '../events/eventTypeDecorator';
+import type { EventContext } from '../events/EventContext';
+import { filterEventsByTag } from '../events/filterEventsByTagDecorator';
+import { tag } from '../events/tagDecorator';
 import { reducer } from './reducer';
 import { Reducers } from './Reducers';
 
 const flush = () => new Promise(resolve => setTimeout(resolve, 0));
 
+class ReducersSomeEventHappened {
+    constructor(readonly value: string = '') {}
+}
+eventType('d2b2b2b2-2222-4a3c-9d3f-6f2f4a3c9d3f')(ReducersSomeEventHappened);
+
+class SomeTaggedReducerState {
+    count = 0;
+}
+
+class SomeTaggedReducer {
+    reducersSomeEventHappened(): SomeTaggedReducerState {
+        return { count: 1 };
+    }
+}
+reducer('some-tagged-reducer', undefined, SomeTaggedReducerState)(SomeTaggedReducer);
+tag('Analytics', 'Reporting')(SomeTaggedReducer);
+filterEventsByTag('vip')(SomeTaggedReducer);
+filterEventsByTag('priority')(SomeTaggedReducer);
+
+const receivedContexts: EventContext[] = [];
+
+class CapturingReducerState {
+    count = 0;
+}
+
+class CapturingReducer {
+    reducersSomeEventHappened(_event: ReducersSomeEventHappened, current: CapturingReducerState | undefined, context: EventContext): CapturingReducerState {
+        receivedContexts.push(context);
+        return { count: (current?.count ?? 0) + 1 };
+    }
+}
+reducer('capturing-reducer', undefined, CapturingReducerState)(CapturingReducer);
+
 /**
  * A minimal client artifacts provider exposing only the reducer types under test —
  * Reducers.ts only reads .reducers and .eventTypes off this during discovery.
@@ -84,4 +121,47 @@ describe('Reducers', () => {
             expect(message.Content.Value0.Reducer.IsActive).toBe(false);
         });
     });
+
+    describe('when registering a reducer that is tagged and filters by tag', () => {
+        type TaggedRegistration = {
+            Content: { Value0: { Reducer: { Tags: string[]; Filters: { FilterTags: string[] } } } };
+        };
+
+        const register = async () => {
+            const { connection, registrationMessages } = createConnection();
+            const reducers = new Reducers(createArtifacts([SomeTaggedReducer]), connection, 'my-event-store', 'my-namespace', new ConnectionLifecycle(), 'default-sink');
+
+            await reducers.register();
+            await flush();
+
+            return (registrationMessages[0] as TaggedRegistration).Content.Value0.Reducer;
+        };
+
+        it('should carry the tags the reducer is labeled with', async () => {
+            expect((await register()).Tags).toEqual(['Analytics', 'Reporting']);
+        });
+
+        it('should carry every tag it filters events by', async () => {
+            expect((await register()).Filters.FilterTags).toEqual(['vip', 'priority']);
+        });
+    });
+
+    describe('when registering a reducer that is neither tagged nor filtered', () => {
+        class SomeUntaggedReducer {}
+        reducer('some-untagged-reducer')(SomeUntaggedReducer);
+
+        it('should send empty tag lists rather than omitting them', async () => {
+            const { connection, registrationMessages } = createConnection();
+            const reducers = new Reducers(createArtifacts([SomeUntaggedReducer]), connection, 'my-event-store', 'my-namespace', new ConnectionLifecycle(), 'default-sink');
+
+            await reducers.register();
+            await flush();
+
+            const message = registrationMessages[0] as {
+                Content: { Value0: { Reducer: { Tags: string[]; Filters: { FilterTags: string[] } } } };
+            };
+            expect(message.Content.Value0.Reducer.Tags).toEqual([]);
+            expect(message.Content.Value0.Reducer.Filters.FilterTags).toEqual([]);
+        });
+    });
 });

package/reducers/Reducers.ts

@@ -10,6 +10,12 @@ import { ChronicleConnection } from '../connection';
 import { toContractsGuid } from '../connection/Guid';
 import { ConnectionLifecycle } from '../connection/ConnectionLifecycle';
 import { getEventTypeMetadata } from '../events/eventTypeDecorator';
+import { EventContext } from '../events/EventContext';
+import { EventTypeId } from '../events/EventTypeId';
+import { EventTypeGeneration } from '../events/EventTypeGeneration';
+import { Tag } from '../events/Tag';
+import { getTagsFor } from '../events/tagDecorator';
+import { getFilterTagsFor } from '../events/filterEventsByTagDecorator';
 import { EventSequenceId } from '../eventSequences/EventSequenceId';
 import { notifyReplayLifecycle } from '../observation/notifyReplayLifecycle';
 import { IReducers } from './IReducers';
@@ -310,9 +316,9 @@ export class Reducers implements IReducers {
                         })),
                         ReadModel: readModelName,
                         IsActive: isActive,
-                        Tags: [],
+                        Tags: getTagsFor(reducerType).map(t => t.value),
                         Filters: {
-                            FilterTags: [],
+                            FilterTags: getFilterTagsFor(reducerType).map(t => t.value),
                             EventSourceType: '',
                             EventStreamType: 'All'
                         }
@@ -369,6 +375,19 @@ export class Reducers implements IReducers {
                         }
 
                         const content = JSON.parse(event.Content) as Record<string, unknown>;
+                        const context: EventContext = {
+                            sequenceNumber: event.Context!.SequenceNumber,
+                            eventSourceId: event.Context!.EventSourceId,
+                            eventType: {
+                                id: new EventTypeId(event.Context!.EventType!.Id),
+                                generation: new EventTypeGeneration(event.Context!.EventType!.Generation),
+                                tombstone: event.Context!.EventType!.Tombstone
+                            },
+                            occurred: new Date(event.Context!.Occurred?.Value ?? ''),
+                            correlationId: event.Context?.CorrelationId ? `${event.Context.CorrelationId.lo}-${event.Context.CorrelationId.hi}` : '',
+                            causation: [],
+                            tags: (event.Context!.Tags ?? []).map(value => new Tag(value))
+                        };
 
                         this._logger.info('Invoking reducer handler', {
                             reducerId: id,
@@ -378,7 +397,7 @@ export class Reducers implements IReducers {
                             hasState: currentState !== undefined
                         });
 
-                        currentState = await reducerInstance[entry.methodName](content, currentState);
+                        currentState = await reducerInstance[entry.methodName](content, currentState, context);
                         lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
                     } catch (err) {
                         this._logger.error('Error handling event in reducer', { reducerId: id, error: String(err) });

package/schemas/JsonSchema.ts

@@ -1,6 +1,21 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+/**
+ * Represents a single compliance classification recorded on a schema node.
+ */
+export interface ComplianceSchemaMetadata {
+    /**
+     * The type of compliance metadata (e.g. 'PII').
+     */
+    metadataType: string;
+
+    /**
+     * Any additional details - can be empty.
+     */
+    details: string;
+}
+
 /**
  * Represents a JSON Schema object.
  */
@@ -15,4 +30,5 @@ export type JsonSchema = {
     items?: JsonSchema;
     additionalProperties?: boolean | JsonSchema;
     enum?: Array<string | number | boolean | null>;
+    compliance?: ComplianceSchemaMetadata[];
 };

package/schemas/JsonSchemaGenerator.spec.ts

@@ -0,0 +1,195 @@
+// 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 { ConceptAs, field } from '@cratis/fundamentals';
+import { describe, expect, it } from 'vitest';
+import { pii } from '../compliance/pii';
+import { eventType, getEventTypeJsonSchemaFor } from '../events/eventTypeDecorator';
+import { getReadModelMetadata, readModel } from '../readModels/readModel';
+import { JsonSchema } from './JsonSchema';
+
+// Decorators are applied as plain function calls (rather than `@decorator` syntax) so these
+// fixtures don't depend on the test runner's decorator-syntax support - they exercise exactly
+// the same decorator functions and metadata storage that `@decorator` syntax would invoke.
+//
+// Order matters here in a way it would not for a real `@decorator` stack: class decorators
+// apply bottom-to-top, so `pii()` must run - and therefore be called - before `readModel()`/
+// `eventType()` so the compliance metadata already exists when the schema is generated.
+
+function schemaFor(target: Function): JsonSchema {
+    return getReadModelMetadata(target)!.schema;
+}
+
+describe('JsonSchemaGenerator', () => {
+    describe('when a class is marked @pii() at the class level', () => {
+        class PersonProfile {
+            name = '';
+            email = '';
+        }
+        pii()(PersonProfile);
+        readModel()(PersonProfile);
+
+        const schema = schemaFor(PersonProfile);
+
+        it('should mark every one of its own properties as PII', () => {
+            expect(schema.properties!.name.compliance).toEqual([{ metadataType: 'PII', details: '' }]);
+            expect(schema.properties!.email.compliance).toEqual([{ metadataType: 'PII', details: '' }]);
+        });
+    });
+
+    describe('when only a single property is marked @pii()', () => {
+        class Contact {
+            name = '';
+            ssn = '';
+        }
+        pii('Social security number')(Contact.prototype, 'ssn');
+        readModel()(Contact);
+
+        const schema = schemaFor(Contact);
+
+        it('should mark the decorated property as PII', () => {
+            expect(schema.properties!.ssn.compliance).toEqual([{ metadataType: 'PII', details: 'Social security number' }]);
+        });
+
+        it('should leave the other property without compliance metadata', () => {
+            expect(schema.properties!.name.compliance).toBeUndefined();
+        });
+    });
+
+    describe('when a property is typed as a ConceptAs<T> marked @pii()', () => {
+        class EmailAddress extends ConceptAs<string> {
+            constructor(value: string) {
+                super(value);
+            }
+        }
+        pii('Email address')(EmailAddress);
+
+        describe('on a read model', () => {
+            class Customer {
+                email: EmailAddress = new EmailAddress('');
+            }
+            readModel()(Customer);
+
+            const schema = schemaFor(Customer);
+
+            it('should mark the concept-typed property as PII', () => {
+                expect(schema.properties!.email.compliance).toEqual([{ metadataType: 'PII', details: 'Email address' }]);
+            });
+
+            it('should describe the concept as its underlying primitive type', () => {
+                expect(schema.properties!.email.type).toBe('string');
+            });
+        });
+
+        describe('on an event', () => {
+            class CustomerRegistered {
+                email: EmailAddress = new EmailAddress('');
+            }
+            eventType()(CustomerRegistered);
+
+            const schema = getEventTypeJsonSchemaFor(CustomerRegistered);
+
+            it('should mark the concept-typed property as PII', () => {
+                expect(schema.properties!.email.compliance).toEqual([{ metadataType: 'PII', details: 'Email address' }]);
+            });
+        });
+    });
+
+    describe('when a property-level @pii() combines with a class-level @pii()', () => {
+        class Employee {
+            name = '';
+            email = '';
+        }
+        pii()(Employee.prototype, 'name');
+        pii('Every field on this record is personal')(Employee);
+        readModel()(Employee);
+
+        const schema = schemaFor(Employee);
+
+        it('should not duplicate the compliance entry on the property carrying both markers', () => {
+            expect(schema.properties!.name.compliance).toHaveLength(1);
+        });
+
+        it('should keep the property-level details when both sources apply', () => {
+            expect(schema.properties!.name.compliance).toEqual([{ metadataType: 'PII', details: '' }]);
+        });
+
+        it('should still mark the property that only carries the class-level marker', () => {
+            expect(schema.properties!.email.compliance).toEqual([{ metadataType: 'PII', details: 'Every field on this record is personal' }]);
+        });
+    });
+
+    describe('when a property typed as a nested composite value object is marked @pii()', () => {
+        class ContactDetails {
+            phone = '';
+            fax = '';
+        }
+        class Vendor {
+            contact: ContactDetails = new ContactDetails();
+        }
+        pii('Vendor contact information')(Vendor.prototype, 'contact');
+        readModel()(Vendor);
+
+        const schema = schemaFor(Vendor);
+
+        it('should push the compliance metadata down onto every leaf property', () => {
+            expect(schema.properties!.contact.properties!.phone.compliance).toEqual([{ metadataType: 'PII', details: 'Vendor contact information' }]);
+            expect(schema.properties!.contact.properties!.fax.compliance).toEqual([{ metadataType: 'PII', details: 'Vendor contact information' }]);
+        });
+
+        it('should not leave compliance metadata on the container node itself', () => {
+            expect(schema.properties!.contact.compliance).toBeUndefined();
+        });
+    });
+
+    describe('when an array element is a ConceptAs<T> marked @pii()', () => {
+        class RequirementCode extends ConceptAs<string> {
+            constructor(value: string) {
+                super(value);
+            }
+        }
+        pii('Sensitive requirement code')(RequirementCode);
+
+        class Contract {
+            codes: RequirementCode[] = [];
+        }
+        field(Array, { enumerable: true, genericArguments: [RequirementCode] })(Contract.prototype, 'codes');
+        readModel()(Contract);
+
+        const schema = schemaFor(Contract);
+
+        it('should describe the property as an array', () => {
+            expect(schema.properties!.codes.type).toBe('array');
+        });
+
+        it('should carry the element concept compliance metadata onto the item schema', () => {
+            expect(schema.properties!.codes.items!.compliance).toEqual([{ metadataType: 'PII', details: 'Sensitive requirement code' }]);
+        });
+
+        it('should describe the item as the concept underlying primitive type', () => {
+            expect(schema.properties!.codes.items!.type).toBe('string');
+        });
+
+        it('should not leave coarse compliance metadata on the array container itself', () => {
+            expect(schema.properties!.codes.compliance).toBeUndefined();
+        });
+    });
+
+    describe('when an array element is not a ConceptAs<T>', () => {
+        class PlainItem {
+            value = '';
+        }
+        class Basket {
+            items: PlainItem[] = [];
+        }
+        field(Array, { enumerable: true, genericArguments: [PlainItem] })(Basket.prototype, 'items');
+        readModel()(Basket);
+
+        const schema = schemaFor(Basket);
+
+        it('should fall back to an opaque object item schema', () => {
+            expect(schema.properties!.items.items).toEqual({ type: 'object' });
+        });
+    });
+});