@cratis/chronicle 6.10.0 → 6.12.0

package/readModels/ReadModels.spec.ts

@@ -50,7 +50,7 @@ describe('ReadModels', () => {
         class MissingModel { id = ''; }
         fromEvent(SomeEvent)(MissingModel);
 
-        it('should retain the legacy prototype-only instance for getInstanceById', async () => {
+        it('should retain a prototype-only instance for getInstanceById when the document is empty', async () => {
             const { readModels, release } = createReadModels(MissingModel);
             const instance = await readModels.getInstanceById(MissingModel, 'missing');
             expect(instance).toBeInstanceOf(MissingModel);
@@ -66,13 +66,21 @@ describe('ReadModels', () => {
             expect(release).not.toHaveBeenCalled();
         });
 
-        it('should return null when the kernel responds with literal JSON null', async () => {
+        it('should return null from findInstanceById when the kernel responds with JSON null', async () => {
             const { readModels, getInstanceByKey, release } = createReadModels(MissingModel);
             getInstanceByKey.mockResolvedValue({ ReadModel: 'null' });
             const instance = await readModels.findInstanceById(MissingModel, 'missing');
             expect(instance).toBeNull();
             expect(release).not.toHaveBeenCalled();
         });
+
+        it('should retain the constructed default instance from getInstanceById for JSON null', async () => {
+            const { readModels, getInstanceByKey } = createReadModels(MissingModel);
+            getInstanceByKey.mockResolvedValue({ ReadModel: 'null' });
+            const instance = await readModels.getInstanceById(MissingModel, 'missing');
+            expect(instance).toBeInstanceOf(MissingModel);
+            expect(instance.id).toBe('');
+        });
     });
 
     describe('when a read model instance exists for a key', () => {
@@ -86,9 +94,9 @@ describe('ReadModels', () => {
             const instance = await readModels.findInstanceById(ExistingModel, 'found');
             expect(instance).toBeInstanceOf(ExistingModel);
             expect(instance?.id).toBe('found');
-            const legacyInstance = await readModels.getInstanceById(ExistingModel, 'found');
-            expect(legacyInstance).toBeInstanceOf(ExistingModel);
-            expect(legacyInstance.id).toBe('found');
+            const canonicalInstance = await readModels.getInstanceById(ExistingModel, 'found');
+            expect(canonicalInstance).toBeInstanceOf(ExistingModel);
+            expect(canonicalInstance.id).toBe('found');
         });
     });
 

package/readModels/ReadModels.ts

@@ -9,9 +9,8 @@ import {
     ReadModelObserverType as ContractReadModelObserverType
 } from '@cratis/chronicle.contracts';
 import type { Constructor } from '@cratis/fundamentals';
-import { Guid, JsonSerializer } from '@cratis/fundamentals';
+import { JsonSerializer } from '@cratis/fundamentals';
 import { IClientArtifactsProvider } from '../artifacts/index.js';
-import { toContractsGuid } from '../connection/Guid.js';
 import { ChronicleConnection } from '../connection/index.js';
 import { ensureQuerySuccess } from '../connection/callResults.js';
 import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
@@ -23,6 +22,7 @@ import { getReducerMetadata } from '../reducers/reducer.js';
 import { JsonSchemaGenerator } from '../schemas/index.js';
 import { WellKnownSinks } from '../sinks/index.js';
 import { getReadModelMetadata, getReadModelId } from './readModel.js';
+import { buildReadModelDefinition } from './buildReadModelDefinition.js';
 import { assertUniqueReadModelIds } from './assertUniqueReadModelIds.js';
 import { rootReadModelTypes } from './rootReadModelTypes.js';
 import type { IMaterializedReadModels } from './IMaterializedReadModels.js';
@@ -78,10 +78,7 @@ export class ReadModels implements IReadModels {
         });
     }
 
-    /**
-     * @inheritdoc
-     * @deprecated Use {@link findInstanceById} to distinguish an absent instance from a stored one.
-     */
+    /** @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({
@@ -344,26 +341,16 @@ export class ReadModels implements IReadModels {
 
 
     private toDefinition(readModel: ResolvedReadModel) {
-        return {
-            Type: {
-                Identifier: readModel.identifier,
-                Generation: 1
-            },
-            ContainerName: readModel.identifier,
-            DisplayName: readModel.identifier,
-            Sink: {
-                ConfigurationId: toContractsGuid(Guid.empty),
-                // Passive read models never write to a materialized sink, so they register with the
-                // None sink and the kernel resolves them via immediate projection instead of an empty sink.
-                TypeId: readModel.isActive ? this._defaultSinkTypeId : WellKnownSinks.None
-            },
-            Schema: readModel.schema,
-            Indexes: [],
-            ObserverType: readModel.observerType,
-            ObserverIdentifier: readModel.observerIdentifier,
-            Owner: 1,
-            Source: 1
-        };
+        return buildReadModelDefinition({
+            identifier: readModel.identifier,
+            type: readModel.type,
+            schema: readModel.schema,
+            // Passive read models never write to a materialized sink, so they register with the
+            // None sink and the kernel resolves them via immediate projection instead of an empty sink.
+            sinkTypeId: readModel.isActive ? this._defaultSinkTypeId : WellKnownSinks.None,
+            observerType: readModel.observerType,
+            observerIdentifier: readModel.observerIdentifier
+        });
     }
 
     private getReadModelSchema(readModelType: Constructor, identifier: string): string {

package/readModels/buildReadModelDefinition.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReadModelObserverType } from '@cratis/chronicle.contracts';
+import { Guid } from '@cratis/fundamentals';
+import { toContractsGuid } from '../connection/Guid.js';
+import { getIndexesForType } from './indexDecorator.js';
+
+interface ReadModelDefinitionOptions {
+    identifier: string;
+    schema: string;
+    type?: Function;
+    sinkTypeId: string;
+    observerType: ReadModelObserverType;
+    observerIdentifier: string;
+}
+
+/** Builds the registration payload shared by projections, reducers, and direct read-model registration. */
+export function buildReadModelDefinition(options: ReadModelDefinitionOptions) {
+    return {
+        Type: {
+            Identifier: options.identifier,
+            Generation: 1
+        },
+        ContainerName: options.identifier,
+        DisplayName: options.identifier,
+        Sink: {
+            ConfigurationId: toContractsGuid(Guid.empty),
+            TypeId: options.sinkTypeId
+        },
+        Schema: options.schema,
+        Indexes: options.type ? getIndexesForType(options.type) : [],
+        ObserverType: options.observerType,
+        ObserverIdentifier: options.observerIdentifier,
+        Owner: 1,
+        Source: 1
+    };
+}

package/readModels/index.ts

@@ -2,6 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 export { ReadModelId } from './ReadModelId.js';
+export { index } from './indexDecorator.js';
 export type { IReadModels } from './IReadModels.js';
 export type { IMaterializedReadModels } from './IMaterializedReadModels.js';
 export { ReadModels } from './ReadModels.js';

package/readModels/indexDecorator.legacy.spec.ts

@@ -0,0 +1,83 @@
+// 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 type { ChronicleConnection } from '../connection/ChronicleConnection.js';
+import type { IClientArtifactsProvider } from '../artifacts/IClientArtifactsProvider.js';
+import { projection } from '../projections/declarative/projection.js';
+import { reducer } from '../reducers/reducer.js';
+import { ReadModels } from './ReadModels.js';
+import { index } from './indexDecorator.js';
+
+class Address {
+    @field(String) @index() zipCode!: string;
+}
+
+class Line {
+    @field(String) @index() productId!: string;
+    @field(Number) quantity!: number;
+}
+
+class Order {
+    @field(String) id!: string;
+    @field(String) @index() customerId!: string;
+    @field(String) @index() number!: string;
+    @field(Number) total!: number;
+    @field(Address) address!: Address;
+    @field(Array, { genericArguments: [Line] }) lines!: Line[];
+}
+
+class ReducedOrder {
+    @field(String) @index() number!: string;
+}
+
+@projection('indexed-orders', Order)
+class OrderProjection {
+    define(): void {}
+}
+
+@reducer('reduced-orders', undefined, ReducedOrder)
+class OrderReducer {}
+
+const artifacts = {
+    eventTypes: [], readModels: [], reactors: [], reducers: [OrderReducer], seeders: [],
+    constraints: [], projections: [OrderProjection], webhooks: [], eventTypeMigrations: [], globalForHandlers: []
+} as IClientArtifactsProvider;
+
+describe('read-model index registration with legacy decorators', () => {
+    it('sends the .NET-equivalent property paths for projections and reducers', async () => {
+        const registerMany = vi.fn().mockResolvedValue({});
+        const connection = { readModels: { registerMany } } as unknown as ChronicleConnection;
+        const readModels = new ReadModels('test', 'Default', connection, artifacts, 'sink');
+        await readModels.register();
+
+        expect(registerMany).toHaveBeenCalledWith(expect.objectContaining({
+            ReadModels: [
+                expect.objectContaining({
+                    ObserverIdentifier: 'indexed-orders',
+                    Indexes: [
+                        { PropertyPath: 'customerId' },
+                        { PropertyPath: 'number' },
+                        { PropertyPath: 'address.zipCode' },
+                        { PropertyPath: 'lines.productId' }
+                    ]
+                }),
+                expect.objectContaining({
+                    ObserverIdentifier: 'reduced-orders',
+                    Indexes: [{ PropertyPath: 'number' }]
+                })
+            ]
+        }));
+    });
+
+    it('sends the same indexes when registering a single model', async () => {
+        const registerMany = vi.fn().mockResolvedValue({});
+        const connection = { readModels: { registerMany } } as unknown as ChronicleConnection;
+        await new ReadModels('test', 'Default', connection, artifacts, 'sink').register(Order);
+        expect(registerMany.mock.calls[0][0].ReadModels[0].Indexes).toEqual([
+            { PropertyPath: 'customerId' }, { PropertyPath: 'number' },
+            { PropertyPath: 'address.zipCode' }, { PropertyPath: 'lines.productId' }
+        ]);
+    });
+});

package/readModels/indexDecorator.ts

@@ -0,0 +1,62 @@
+// 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 { conceptAsTypeKey, type Constructor, Fields, typeKeyOf } from '@cratis/fundamentals';
+import type { IndexDefinition } from '@cratis/chronicle.contracts';
+import { getChildrenFromMetadata } from '../projections/modelBound/childrenFrom.js';
+import { TypeIntrospector } from '../types/TypeIntrospector.js';
+import { ChroniclePropertyDecorator, decorateProperty, hasPropertyMetadata } from '../types/propertyDecoratorMetadata.js';
+
+const INDEX_METADATA_KEY = 'chronicle:readModel:index';
+
+/**
+ * Marks a read-model property for a single ascending, non-unique index.
+ * Indexed fields on nested objects or typed collections use dotted property paths.
+ * @returns A property decorator.
+ */
+export function index(): ChroniclePropertyDecorator {
+    return decorateProperty((target: object, propertyKey: string | symbol) => {
+        const name = propertyKey.toString();
+        TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, name);
+        Reflect.defineMetadata(INDEX_METADATA_KEY, true, target, name);
+    });
+}
+
+/**
+ * Collects the indexed paths of a read model, including nested objects and typed collections.
+ * @param type - The read-model type to inspect.
+ * @returns Index definitions with property paths for the read model.
+ */
+export function getIndexesForType(type: Function): IndexDefinition[] {
+    const indexes: IndexDefinition[] = [];
+    // Match .NET: a nested type shared by multiple properties is visited only on its first path.
+    const visited = new Set<Function>();
+
+    function collect(current: Function, prefix: string): void {
+        if (visited.has(current)) return;
+        visited.add(current);
+
+        const fields = Fields.getFieldsForType(current as Constructor);
+        for (const [name, memberType] of TypeIntrospector.getMembers(current)) {
+            const path = prefix ? `${prefix}.${name}` : name;
+            if (hasPropertyMetadata(INDEX_METADATA_KEY, current.prototype, name)) {
+                indexes.push({ PropertyPath: path });
+            }
+
+            const nestedType = memberType === Array
+                ? getChildrenFromMetadata(current.prototype, name).find(entry => entry.childType)?.childType
+                    ?? fields.find(field => field.name === name)?.genericArguments?.[0]
+                : memberType;
+            const isComplex = nestedType && nestedType !== String && nestedType !== Number && nestedType !== Boolean &&
+                nestedType !== Date && nestedType !== Array && nestedType !== Object;
+            if (isComplex && typeKeyOf(nestedType as Constructor) !== conceptAsTypeKey &&
+                typeKeyOf(nestedType as Constructor) !== 'Guid') {
+                collect(nestedType, path);
+            }
+        }
+    }
+
+    collect(type, '');
+    return indexes;
+}

package/readModels/indexRegistration.spec.ts

@@ -0,0 +1,99 @@
+// 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 { field } from '@cratis/fundamentals';
+import { describe, expect, it, vi } from 'vitest';
+import type { IClientArtifactsProvider } from '../artifacts/index.js';
+import type { ChronicleConnection } from '../connection/index.js';
+import { ConnectionLifecycle } from '../connection/ConnectionLifecycle.js';
+import { eventType } from '../events/eventTypeDecorator.js';
+import { Projections } from '../projections/Projections.js';
+import { projection } from '../projections/declarative/projection.js';
+import { fromEvent } from '../projections/modelBound/fromEvent.js';
+import { entersOn } from '../projections/modelBound/entersOn.js';
+import { variantOf } from '../projections/modelBound/variantOf.js';
+import { reducer } from '../reducers/reducer.js';
+import { Reducers } from '../reducers/Reducers.js';
+import { index } from './indexDecorator.js';
+
+class IndexedEvent {}
+eventType('indexed-event')(IndexedEvent);
+
+class DeclarativeModel {
+    @field(String) @index() reference!: string;
+}
+@projection('indexed-declarative', DeclarativeModel)
+class DeclarativeProjection {
+    define(): void {}
+}
+
+@fromEvent(IndexedEvent)
+class ModelBoundModel {
+    @field(String) @index() reference!: string;
+}
+
+class VariantIdentity {}
+@variantOf(VariantIdentity, 'id')
+@entersOn(IndexedEvent)
+@fromEvent(IndexedEvent)
+class IndexedVariant {
+    @field(String) id!: string;
+    @field(String) @index() reference!: string;
+}
+
+class ReducedModel {
+    @field(String) @index() reference!: string;
+}
+@reducer('indexed-reducer', undefined, ReducedModel)
+class IndexedReducer {}
+
+function artifacts(readModels: IClientArtifactsProvider['readModels'] = [], projections: IClientArtifactsProvider['projections'] = [], reducers: IClientArtifactsProvider['reducers'] = []): IClientArtifactsProvider {
+    return {
+        eventTypes: [], readModels, projections, reducers, reactors: [], seeders: [], constraints: [],
+        webhooks: [], eventTypeMigrations: [], globalForHandlers: []
+    };
+}
+
+function connection() {
+    const registerMany = vi.fn().mockResolvedValue({});
+    const value = {
+        readModels: { registerMany },
+        projections: { register: vi.fn().mockResolvedValue({}) },
+        reducers: { observe: vi.fn().mockImplementation(async function* () {}) }
+    } as unknown as ChronicleConnection;
+    return { value, registerMany };
+}
+
+function indexesFor(registerMany: ReturnType<typeof vi.fn>, identifier: string) {
+    const definitions = registerMany.mock.calls[0][0].ReadModels as Array<{ Type: { Identifier: string }; Indexes: unknown[] }>;
+    return definitions.find(definition => definition.Type.Identifier === identifier)?.Indexes;
+}
+
+describe('when registering indexed read models through the startup paths', () => {
+    it('should send indexes for a declarative projection', async () => {
+        const { value, registerMany } = connection();
+        await new Projections('store', 'Default', value, artifacts([], [DeclarativeProjection]), 'sink').register();
+        expect(indexesFor(registerMany, 'DeclarativeModel')).toEqual([{ PropertyPath: 'reference' }]);
+    });
+
+    it('should send indexes for a model-bound projection', async () => {
+        const { value, registerMany } = connection();
+        await new Projections('store', 'Default', value, artifacts([ModelBoundModel]), 'sink').register();
+        expect(indexesFor(registerMany, 'ModelBoundModel')).toEqual([{ PropertyPath: 'reference' }]);
+    });
+
+    it('should send indexes for a model-bound variant', async () => {
+        const { value, registerMany } = connection();
+        await new Projections('store', 'Default', value, artifacts([IndexedVariant]), 'sink').register();
+        expect(indexesFor(registerMany, 'IndexedVariant')).toEqual([{ PropertyPath: 'reference' }]);
+    });
+
+    it('should send indexes for a reducer read model', async () => {
+        const { value, registerMany } = connection();
+        const reducers = new Reducers(artifacts([], [], [IndexedReducer]), value, 'store', 'Default', new ConnectionLifecycle(), 'sink');
+        await reducers.register();
+        reducers.dispose();
+        expect(indexesFor(registerMany, 'ReducedModel')).toEqual([{ PropertyPath: 'reference' }]);
+    });
+});

package/readModels/standardFallbacks.standard.spec.ts

@@ -2,6 +2,8 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { field } from '@cratis/fundamentals';
+import { fromEvent } from '../projections/modelBound/fromEvent.js';
+import { index } from './indexDecorator.js';
 import { describe, expect, it, vi } from 'vitest';
 import { IClientArtifactsProvider } from '../artifacts/IClientArtifactsProvider.js';
 import { ChronicleConnection } from '../connection/ChronicleConnection.js';
@@ -16,12 +18,41 @@ class UndecoratedModel {
 @reducer('undecorated-model', undefined, UndecoratedModel)
 class ModelReducer {}
 
+class IndexedEvent { value = ''; }
+
+class IndexedLine {
+    @field(String) @index() productId!: string;
+    @field(Number) quantity!: number;
+}
+
+@fromEvent(IndexedEvent)
+class IndexedOrder {
+    @field(String) id!: string;
+    @field(String) @index() customerId!: string;
+    @field(Array, { genericArguments: [IndexedLine] }) lines!: IndexedLine[];
+}
+
 const artifacts = {
     eventTypes: [], readModels: [], reactors: [], reducers: [ModelReducer], seeders: [],
     constraints: [], projections: [], webhooks: [], eventTypeMigrations: [], globalForHandlers: []
 } as IClientArtifactsProvider;
 
 describe('inferred read models with standard decorators', () => {
+    it('registers model-bound indexes on fields and typed collection elements as .NET property paths', async () => {
+        const registerMany = vi.fn().mockResolvedValue({});
+        const connection = { readModels: { registerMany } } as unknown as ChronicleConnection;
+        const provider = { ...artifacts, readModels: [IndexedOrder] };
+        await new ReadModels('test', 'Default', connection, provider, 'sink').register(IndexedOrder);
+        expect(registerMany).toHaveBeenCalledWith(expect.objectContaining({
+            ReadModels: [expect.objectContaining({
+                Indexes: [
+                    { PropertyPath: 'customerId' },
+                    { PropertyPath: 'lines.productId' }
+                ]
+            })]
+        }));
+    });
+
     it('rejects an untyped array before registering a reducer read model', async () => {
         const registerMany = vi.fn();
         const connection = { readModels: { registerMany } } as unknown as ChronicleConnection;

package/reducers/Reducers.ts

@@ -3,11 +3,10 @@
 
 import 'reflect-metadata';
 import { diag } from '@opentelemetry/api';
-import { Constructor, Guid } from '@cratis/fundamentals';
+import { Constructor } from '@cratis/fundamentals';
 import { ObservationState, ReadModelObserverType, ReducerMessage } from '@cratis/chronicle.contracts';
 import { IClientArtifactsProvider } from '../artifacts/index.js';
 import { ChronicleConnection } from '../connection/index.js';
-import { toContractsGuid } from '../connection/Guid.js';
 import { ConnectionLifecycle } from '../connection/ConnectionLifecycle.js';
 import { getEventTypeMetadata } from '../events/eventTypeDecorator.js';
 import { toClientEventContext } from '../events/toClientEventContext.js';
@@ -19,6 +18,7 @@ import { IReducers } from './IReducers.js';
 import { getReducerMetadata } from './reducer.js';
 import { getReadModelMetadata } from '../readModels/index.js';
 import { getReadModelId } from '../readModels/readModel.js';
+import { buildReadModelDefinition } from '../readModels/buildReadModelDefinition.js';
 import { assertUniqueReadModelIds } from '../readModels/assertUniqueReadModelIds.js';
 import { JsonSchemaGenerator } from '../schemas/index.js';
 
@@ -181,24 +181,14 @@ export class Reducers implements IReducers {
 
         const readModels = Array.from(this._reducers.entries()).map(([id, reducerType]) => {
             const readModelName = this.getReducerReadModelIdentifier(reducerType);
-            return {
-                Type: {
-                    Identifier: readModelName,
-                    Generation: 1
-                },
-                ContainerName: readModelName,
-                DisplayName: readModelName,
-                Sink: {
-                    ConfigurationId: toContractsGuid(Guid.empty),
-                    TypeId: this._defaultSinkTypeId
-                },
-                Schema: this.getReducerSchema(reducerType, readModelName),
-                Indexes: [],
-                ObserverType: ReadModelObserverType.Reducer,
-                ObserverIdentifier: id,
-                Owner: 1,
-                Source: 1
-            };
+            return buildReadModelDefinition({
+                identifier: readModelName,
+                type: getReducerMetadata(reducerType)?.readModel,
+                schema: this.getReducerSchema(reducerType, readModelName),
+                sinkTypeId: this._defaultSinkTypeId,
+                observerType: ReadModelObserverType.Reducer,
+                observerIdentifier: id
+            });
         });
 
         const identifiers = new Set<string>();