@cratis/chronicle 6.6.0 → 6.7.0

package/projections/Projections.ts

@@ -18,7 +18,11 @@ import { FailedPartition } from '../observation/FailedPartition.js';
 import { FailedPartitions } from '../observation/FailedPartitions.js';
 import { toObserverRunningState } from '../observation/toObserverRunningState.js';
 import { getReadModelMetadata } from '../readModels/index.js';
+import { getReadModelId } from '../readModels/readModel.js';
+import { assertUniqueReadModelIds } from '../readModels/assertUniqueReadModelIds.js';
+import { JsonSchemaGenerator } from '../schemas/index.js';
 import { TypeIntrospector } from '../types/index.js';
+import { hasModelBoundProperties } from '../types/TypeDiscoverer.js';
 import { IProjections } from './IProjections.js';
 import { getProjectionMetadata } from './declarative/projection.js';
 import { ProjectionBuilderFor } from './declarative/ProjectionBuilderFor.js';
@@ -109,7 +113,7 @@ export class Projections implements IProjections {
         }
 
         for (const type of readModelTypes) {
-            if (!hasFromEventMetadata(type)) {
+            if (!hasFromEventMetadata(type) && !hasModelBoundProperties(type)) {
                 continue;
             }
 
@@ -136,6 +140,10 @@ export class Projections implements IProjections {
 
         this._logger.info('Registering projections', { declarativeCount: this._declarative.size, modelBoundCount: this._modelBound.size });
 
+        const inferred = this._clientArtifacts.projections
+            .map(type => getProjectionMetadata(type)?.readModelType)
+            .filter((type): type is Constructor => type !== undefined);
+        assertUniqueReadModelIds([...this._clientArtifacts.readModels, ...inferred]);
         const builtProjections: BuiltProjection[] = [
             ...Array.from(this._declarative.values()).map(type => this.buildDeclarativeDefinition(type)),
             ...Array.from(this._modelBound.values()).map(type => this.buildModelBoundDefinition(type))
@@ -349,7 +357,14 @@ export class Projections implements IProjections {
 
         for (const projection of projections) {
             const readModelIdentifier = projection.ReadModel;
-            if (!readModelIdentifier || byReadModel.has(readModelIdentifier)) {
+            if (!readModelIdentifier) {
+                continue;
+            }
+            const existing = byReadModel.get(readModelIdentifier);
+            if (existing) {
+                if (existing.ObserverIdentifier !== projection.Identifier) {
+                    throw new Error(`Read model id '${readModelIdentifier}' has multiple projections.`);
+                }
                 continue;
             }
 
@@ -380,14 +395,16 @@ export class Projections implements IProjections {
     }
 
     private getReadModelSchema(readModelIdentifier: string): string {
-        for (const type of this._clientArtifacts.readModels) {
+        const types = [
+            ...this._clientArtifacts.readModels,
+            ...this._clientArtifacts.projections
+                .map(projectionType => getProjectionMetadata(projectionType)?.readModelType)
+                .filter((type): type is Constructor => type !== undefined)
+        ];
+        for (const type of types) {
             const metadata = getReadModelMetadata(type);
-            if (!metadata) {
-                continue;
-            }
-
-            if (metadata.id.value === readModelIdentifier || type.name === readModelIdentifier) {
-                return JSON.stringify(metadata.schema);
+            if (getReadModelId(type) === readModelIdentifier) {
+                return JSON.stringify(metadata?.schema ?? JsonSchemaGenerator.generate(type));
             }
         }
 
@@ -409,8 +426,7 @@ export class Projections implements IProjections {
         if (explicitReadModelIdentifier === type.name) {
             // Use explicit readModelType from decorator if provided
             if (metadata.readModelType) {
-                const rm = getReadModelMetadata(metadata.readModelType);
-                definition.ReadModel = rm?.id.value ?? (metadata.readModelType as Function).name;
+                definition.ReadModel = getReadModelId(metadata.readModelType);
             } else {
                 const inferredReadModelIdentifier = this.inferReadModelIdentifier(builder.getMappedReadModelProperties());
                 if (inferredReadModelIdentifier) {
@@ -651,13 +667,12 @@ export class Projections implements IProjections {
     }
 
     private resolveModelBoundMetadata(type: Constructor): ResolvedModelBoundMetadata | undefined {
-        const readModelMetadata = getReadModelMetadata(type);
-
-        if (readModelMetadata && hasFromEventMetadata(type)) {
+        if (hasFromEventMetadata(type) || hasModelBoundProperties(type)) {
+            const identifier = getReadModelId(type);
             return {
-                id: new ProjectionId(readModelMetadata.id.value),
+                id: new ProjectionId(identifier),
                 eventSequenceId: getEventSequenceMetadata(type),
-                readModelIdentifier: readModelMetadata.id.value
+                readModelIdentifier: identifier
             };
         }
 

package/projections/modelBound/fromEvent.ts

@@ -4,6 +4,8 @@
 import 'reflect-metadata';
 import { FromEventMetadata } from './FromEventMetadata.js';
 import { FromEventOptions } from './FromEventOptions.js';
+import { DecoratorType, TypeDiscoverer } from '../../types/index.js';
+import type { Constructor } from '@cratis/fundamentals';
 
 const METADATA_KEY = 'chronicle:projection:fromEvent';
 
@@ -18,6 +20,7 @@ export function fromEvent(eventType: Function, options?: FromEventOptions): Clas
         const existing: FromEventMetadata[] = Reflect.getMetadata(METADATA_KEY, target) ?? [];
         const metadata: FromEventMetadata = { eventType, ...options };
         Reflect.defineMetadata(METADATA_KEY, [...existing, metadata], target);
+        TypeDiscoverer.default.register(DecoratorType.ReadModel, target as Constructor);
     };
 }
 

package/readModels/ReadModels.ts

@@ -17,11 +17,13 @@ import { ensureQuerySuccess } from '../connection/callResults.js';
 import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
 import { getProjectionMetadata } from '../projections/declarative/projection.js';
 import { hasFromEventMetadata } from '../projections/modelBound/fromEvent.js';
+import { hasModelBoundProperties } from '../types/TypeDiscoverer.js';
 import { isPassive } from '../projections/modelBound/passive.js';
 import { getReducerMetadata } from '../reducers/reducer.js';
 import { JsonSchemaGenerator } from '../schemas/index.js';
 import { WellKnownSinks } from '../sinks/index.js';
-import { getReadModelMetadata } from './readModel.js';
+import { getReadModelMetadata, getReadModelId } from './readModel.js';
+import { assertUniqueReadModelIds } from './assertUniqueReadModelIds.js';
 import type { IMaterializedReadModels } from './IMaterializedReadModels.js';
 import { MaterializedReadModels } from './MaterializedReadModels.js';
 import { ReadModelSubjectResolver } from './ReadModelSubjectResolver.js';
@@ -239,6 +241,7 @@ export class ReadModels implements IReadModels {
     }
 
     private resolveReadModels<TReadModel>(readModelType?: Constructor<TReadModel>): ResolvedReadModel[] {
+        assertUniqueReadModelIds(this._clientArtifacts.readModels);
         const resolved = new Map<string, ResolvedReadModel>();
 
         for (const projectionType of this._clientArtifacts.projections) {
@@ -251,9 +254,8 @@ export class ReadModels implements IReadModels {
                 continue;
             }
 
-            const readModelMetadata = getReadModelMetadata(metadata.readModelType);
-            const identifier = readModelMetadata?.id.value ?? metadata.readModelType.name;
-            resolved.set(identifier, {
+            const identifier = getReadModelId(metadata.readModelType);
+            this.addResolved(resolved, {
                 type: metadata.readModelType,
                 identifier,
                 eventSequenceId: metadata.eventSequenceId ?? EventSequenceId.eventLog.value,
@@ -265,7 +267,7 @@ export class ReadModels implements IReadModels {
         }
 
         for (const modelBoundType of this._clientArtifacts.readModels) {
-            if (!hasFromEventMetadata(modelBoundType)) {
+            if (!hasFromEventMetadata(modelBoundType) && !hasModelBoundProperties(modelBoundType)) {
                 continue;
             }
 
@@ -273,18 +275,14 @@ export class ReadModels implements IReadModels {
                 continue;
             }
 
-            const metadata = getReadModelMetadata(modelBoundType);
-            if (!metadata) {
-                continue;
-            }
-
-            resolved.set(metadata.id.value, {
+            const identifier = getReadModelId(modelBoundType);
+            this.addResolved(resolved, {
                 type: modelBoundType,
-                identifier: metadata.id.value,
+                identifier,
                 eventSequenceId: EventSequenceId.eventLog.value,
                 observerType: ContractReadModelObserverType.Projection,
-                observerIdentifier: metadata.id.value,
-                schema: JSON.stringify(metadata.schema),
+                observerIdentifier: identifier,
+                schema: this.getReadModelSchema(modelBoundType, identifier),
                 isActive: !isPassive(modelBoundType)
             });
         }
@@ -299,9 +297,8 @@ export class ReadModels implements IReadModels {
                 continue;
             }
 
-            const readModelMetadata = getReadModelMetadata(metadata.readModel);
-            const identifier = readModelMetadata?.id.value ?? metadata.readModel.name;
-            resolved.set(identifier, {
+            const identifier = getReadModelId(metadata.readModel);
+            this.addResolved(resolved, {
                 type: metadata.readModel,
                 identifier,
                 eventSequenceId: metadata.eventSequenceId ?? EventSequenceId.eventLog.value,
@@ -315,6 +312,15 @@ export class ReadModels implements IReadModels {
         return Array.from(resolved.values());
     }
 
+    private addResolved(models: Map<string, ResolvedReadModel>, model: ResolvedReadModel): void {
+        const existing = models.get(model.identifier);
+        if (existing && (existing.type !== model.type || existing.observerType !== model.observerType ||
+            existing.observerIdentifier !== model.observerIdentifier)) {
+            throw new Error(`Read model id '${model.identifier}' has multiple observers or model types.`);
+        }
+        models.set(model.identifier, model);
+    }
+
     private resolveReadModel<TReadModel>(readModelType: Constructor<TReadModel>): ResolvedReadModel {
         const [resolved] = this.resolveReadModels(readModelType);
         if (!resolved) {

package/readModels/assertUniqueReadModelIds.ts

@@ -0,0 +1,18 @@
+// 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 { getReadModelId } from './readModel.js';
+
+/** Refuses to register two different model types under the same storage identity. */
+export function assertUniqueReadModelIds(types: Iterable<Constructor>): void {
+    const byId = new Map<string, Constructor>();
+    for (const type of types) {
+        const id = getReadModelId(type);
+        const previous = byId.get(id);
+        if (previous && previous !== type) {
+            throw new Error(`Read model id '${id}' is shared by '${previous.name}' and '${type.name}'.`);
+        }
+        byId.set(id, type);
+    }
+}

package/readModels/discovery.spec.ts

@@ -0,0 +1,94 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { field } from '@cratis/fundamentals';
+import { describe, expect, it, vi } from 'vitest';
+import { DefaultClientArtifactsProvider } from '../artifacts/DefaultClientArtifactsProvider.js';
+import type { ChronicleConnection } from '../connection/index.js';
+import { projection } from '../projections/declarative/projection.js';
+import { fromEvent } from '../projections/modelBound/fromEvent.js';
+import { setFrom } from '../projections/modelBound/setFrom.js';
+import { Projections } from '../projections/Projections.js';
+import { eventType } from '../events/eventTypeDecorator.js';
+import { TypeDiscoverer } from '../types/TypeDiscoverer.js';
+import { reducer } from '../reducers/reducer.js';
+import { ReadModels } from './ReadModels.js';
+import { readModel } from './readModel.js';
+
+@eventType('discovery-event')
+class Event { @field(String) value!: string; }
+@fromEvent(Event)
+class ModelBound {
+    @field(String) value!: string;
+}
+class Projected {
+    static readonly readModelId = 'projected-custom';
+    @field(String) value!: string;
+}
+@projection('projected-observer', Projected)
+class ProjectedObserver {
+    define() {}
+}
+class Reduced {
+    @field(Number) count!: number;
+}
+@reducer('reduced-observer', undefined, Reduced)
+class ReducedObserver {}
+@readModel('legacy-id')
+@fromEvent(Event)
+class Legacy {
+    @field(String) value!: string;
+}
+class MappedOnly {
+    @field(String)
+    @setFrom(Event)
+    value!: string;
+}
+
+function createConnection() {
+    const registerMany = vi.fn().mockResolvedValue({});
+    const register = vi.fn().mockResolvedValue({});
+    const connection = { readModels: { registerMany }, projections: { register } } as unknown as ChronicleConnection;
+    return { connection, registerMany, register };
+}
+
+describe('when discovering read models from observers', () => {
+    it('should discover and register an exported property-bound model without a class decorator', async () => {
+        const discoverer = new TypeDiscoverer(async () => ['virtual.ts'], async () => ({ MappedOnly }));
+        await discoverer.discover('virtual');
+        const provider = new DefaultClientArtifactsProvider(discoverer);
+        expect(provider.readModels).toContain(MappedOnly);
+        const { connection, registerMany, register } = createConnection();
+        const projections = new Projections('store', 'Default', connection, provider, 'sink');
+        await projections.register();
+        const definition = registerMany.mock.calls[0][0].ReadModels.find(
+            (model: { Type: { Identifier: string } }) => model.Type.Identifier === 'MappedOnly');
+        expect(definition).toBeDefined();
+        expect(JSON.parse(definition.Schema).properties.value.type).toBe('string');
+        expect(register.mock.calls.some(call => call[0].Projections[0].ReadModel === 'MappedOnly')).toBe(true);
+    });
+    it('should deduplicate inferred types and retain decorated and custom identifiers', async () => {
+        const provider = DefaultClientArtifactsProvider.default;
+        for (const type of [ModelBound, Projected, Reduced, Legacy]) {
+            expect(provider.readModels.filter(model => model === type)).toHaveLength(1);
+        }
+        const { connection, registerMany } = createConnection();
+        await new ReadModels('store', 'Default', connection, provider, 'sink').register();
+        const definitions = registerMany.mock.calls[0][0].ReadModels;
+        const byId = new Map(definitions.map((definition: { Type: { Identifier: string } }) => [definition.Type.Identifier, definition]));
+        for (const id of ['ModelBound', 'projected-custom', 'Reduced', 'legacy-id']) {
+            expect(byId.has(id)).toBe(true);
+        }
+        expect(JSON.parse(byId.get('projected-custom').Schema).properties.value.type).toBe('string');
+        expect(JSON.parse(byId.get('Reduced').Schema).properties.count.type).toBe('number');
+    });
+
+    it('should reject two distinct models with the same identifier before registration', async () => {
+        class First { static readonly readModelId = 'collision'; }
+        class Second { static readonly readModelId = 'collision'; }
+        const provider = { ...DefaultClientArtifactsProvider.default, readModels: [First, Second], projections: [], reducers: [] };
+        const { connection, registerMany } = createConnection();
+        await expect(new ReadModels('store', 'Default', connection, provider, 'sink').register()).rejects.toThrow(/collision/);
+        expect(registerMany).not.toHaveBeenCalled();
+    });
+});

package/readModels/readModel.ts

@@ -30,6 +30,9 @@ export interface ReadModelMetadata {
  * TypeScript decorator that marks a class as a read model and captures reflection metadata.
  * @param id - The unique identifier for the read model. Defaults to the class name if omitted.
  * @returns A class decorator.
+ * @deprecated Read models are discovered from @projection(..., ReadModelType),
+ * @reducer(..., ReadModelType), or @fromEvent on the model. For a custom identifier,
+ * declare `static readonly readModelId = 'custom-id'` on the model instead.
  */
 export function readModel(id: string = ''): ChronicleClassDecorator {
     return (target: object, context?: ClassDecoratorContext) => {
@@ -83,3 +86,14 @@ export function getReadModelMetadata(target: Function): ReadModelMetadata | unde
 export function isReadModel(target: Function): boolean {
     return Reflect.hasMetadata(READ_MODEL_METADATA_KEY, target);
 }
+
+/** Resolves the compatible identifier of a decorated or inferred read model. */
+export function getReadModelId(target: Function): string {
+    const decorated = getReadModelMetadata(target);
+    if (decorated) return decorated.id.value;
+    const explicit = (target as unknown as { readModelId?: unknown }).readModelId;
+    if (explicit !== undefined && (typeof explicit !== 'string' || !explicit.trim())) {
+        throw new TypeError(`Read model '${target.name}' must have a non-empty string readModelId.`);
+    }
+    return explicit as string | undefined ?? target.name;
+}

package/reducers/Reducers.spec.ts

@@ -89,6 +89,24 @@ function createConnection() {
 }
 
 describe('Reducers', () => {
+    describe('when a reducer produces a model without @readModel', () => {
+        class NamedState {
+            static readonly readModelId = 'existing-state-id';
+            count = 0;
+        }
+        class NamedReducer {}
+        reducer('named-reducer', undefined, NamedState)(NamedReducer);
+
+        it('should register the model under its explicit identifier with a schema from its type', async () => {
+            const { connection } = createConnection();
+            const registerMany = vi.spyOn(connection.readModels, 'registerMany');
+            const reducers = new Reducers(createArtifacts([NamedReducer]), connection, 'store', 'Default', new ConnectionLifecycle(), 'sink');
+            await reducers.register();
+            const definition = registerMany.mock.calls[0][0].ReadModels[0];
+            expect(definition.Type.Identifier).toBe('existing-state-id');
+            expect(JSON.parse(definition.Schema).properties.count.type).toBe('number');
+        });
+    });
     describe('when registering an active reducer (the default)', () => {
         class SomeReducer {}
         reducer('some-active-reducer')(SomeReducer);

package/reducers/Reducers.ts

@@ -18,6 +18,8 @@ import { notifyReplayLifecycle } from '../observation/notifyReplayLifecycle.js';
 import { IReducers } from './IReducers.js';
 import { getReducerMetadata } from './reducer.js';
 import { getReadModelMetadata } from '../readModels/index.js';
+import { getReadModelId } from '../readModels/readModel.js';
+import { assertUniqueReadModelIds } from '../readModels/assertUniqueReadModelIds.js';
 import { JsonSchemaGenerator } from '../schemas/index.js';
 
 /** Expression used to partition reducer observations by event source ID. */
@@ -151,6 +153,7 @@ export class Reducers implements IReducers {
             await this.discover();
         }
 
+        assertUniqueReadModelIds(this._clientArtifacts.readModels);
         await this.registerReadModels();
 
         this._logger.info('Registering reducers', { count: this._reducers.size });
@@ -188,6 +191,12 @@ export class Reducers implements IReducers {
             };
         });
 
+        const identifiers = new Set<string>();
+        for (const definition of readModels) {
+            const identifier = definition.Type.Identifier;
+            if (identifiers.has(identifier)) throw new Error(`Read model id '${identifier}' has multiple reducers.`);
+            identifiers.add(identifier);
+        }
         this._logger.info('Registering read models for reducers', { count: readModels.length });
         await this._connection.readModels.registerMany({
             EventStore: this._eventStoreName,
@@ -281,7 +290,7 @@ 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 getReadModelId(metadata.readModel);
         }
 
         return (reducerType as Function).name;

package/types/TypeDiscoverer.ts

@@ -4,10 +4,23 @@
 import path from 'path';
 import { DecoratorType } from './DecoratorType.js';
 import { Constructor } from '@cratis/fundamentals';
+import { TypeIntrospector } from './TypeIntrospector.js';
+import { hasPropertyMetadata } from './propertyDecoratorMetadata.js';
 
 type GlobFunction = (pattern: string | string[]) => Promise<string[]>;
 type FileImporter = (filePath: string) => Promise<unknown>;
 
+const modelBoundPropertyKeys = [
+    'setFrom', 'setFromContext', 'setValue', 'addFrom', 'subtractFrom',
+    'increment', 'decrement', 'count', 'childrenFrom', 'join', 'fromEvery', 'fromAll'
+].map(name => `chronicle:projection:${name}`);
+
+/** Identifies models whose event mappings live on their properties rather than on @fromEvent. */
+export function hasModelBoundProperties(type: Function): boolean {
+    return TypeIntrospector.getTrackedProperties(type).some(property =>
+        modelBoundPropertyKeys.some(key => hasPropertyMetadata(key, type.prototype, property)));
+}
+
 /**
  * Encapsulates discovery and registry operations for decorator-based artifacts.
  */
@@ -38,7 +51,15 @@ export class TypeDiscoverer {
         const patterns = Array.isArray(pattern) ? pattern : [pattern];
         const files = await this._glob(patterns);
         for (const file of files) {
-            await this._importFile(path.resolve(file));
+            const module = await this._importFile(path.resolve(file));
+            if (module && typeof module === 'object') {
+                for (const type of Object.values(module)) {
+                    if (typeof type !== 'function' || !type.prototype) continue;
+                    if (hasModelBoundProperties(type)) {
+                        this.register(DecoratorType.ReadModel, type as Constructor);
+                    }
+                }
+            }
         }
     }
 
@@ -51,7 +72,22 @@ export class TypeDiscoverer {
     register(decoratorType: DecoratorType, type: Constructor, name?: string): void {
         const discoveredName = name ?? type.name;
         const typesForDecorator = TypeDiscoverer._registeredTypes.get(decoratorType) ?? new Map<string, Constructor>();
-        typesForDecorator.set(discoveredName, type);
+        if (decoratorType === DecoratorType.ReadModel) {
+            const previous = Array.from(typesForDecorator).find(([, registered]) => registered === type);
+            if (previous && previous[0] !== discoveredName) {
+                // A named @readModel overrides the type-name alias registered by an observer.
+                if (previous[0] !== type.name) return;
+                typesForDecorator.delete(previous[0]);
+            }
+        }
+        let key = discoveredName;
+        if (decoratorType === DecoratorType.ReadModel && typesForDecorator.has(key) && typesForDecorator.get(key) !== type &&
+            !(type.prototype instanceof typesForDecorator.get(key)!)) {
+            let suffix = 2;
+            while (typesForDecorator.has(`${discoveredName}#${suffix}`)) suffix++;
+            key = `${discoveredName}#${suffix}`;
+        }
+        typesForDecorator.set(key, type);
         TypeDiscoverer._registeredTypes.set(decoratorType, typesForDecorator);
     }