@cratis/chronicle 6.9.1 → 6.11.0

package/projections/modelBound/childrenFrom.ts

@@ -3,12 +3,15 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the childrenFrom property decorator. */
 export interface ChildrenFromMetadata {
     /** The event constructor that adds children to the collection. */
     readonly eventType: Function;
+    /** Optional child type for TypeScript runtimes without emitted generic metadata. */
+    readonly childType?: Function;
     /** The event property name used as the key for children. Defaults to the event source identifier. */
     readonly key?: string;
     /** The child model property name used to uniquely identify instances in the collection. */
@@ -22,22 +25,25 @@ const METADATA_KEY = 'chronicle:projection:childrenFrom';
 /**
  * Property decorator that configures a children collection sub-projection from an event type.
  * @param eventType - The event constructor.
- * @param key - Optional event property name to use as the key for children.
+ * @param key - Optional event property name to use as the key for children, or the child constructor.
  * @param identifiedBy - Optional child model property name used to identify instances.
  * @param parentKey - Optional event property name used as the parent key.
  * @returns A property decorator.
  */
 export function childrenFrom(
     eventType: Function,
-    key?: string,
+    key?: string | Function,
     identifiedBy?: string,
     parentKey?: string
 ): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         const propKey = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, propKey);
         const existing: ChildrenFromMetadata[] = Reflect.getMetadata(METADATA_KEY, target, propKey) ?? [];
-        const metadata: ChildrenFromMetadata = { eventType, key, identifiedBy, parentKey };
+        const metadata: ChildrenFromMetadata = {
+            eventType, key: typeof key === 'string' ? key : undefined,
+            childType: typeof key === 'function' ? key : undefined, identifiedBy, parentKey
+        };
         Reflect.defineMetadata(METADATA_KEY, [...existing, metadata], target, propKey);
     });
 }

package/projections/modelBound/clearWith.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChronicleClassOrPropertyDecorator, decorateClassOrProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundClassOrProperty } from '../../types/modelBoundProperty.js';
+import { ChronicleClassOrPropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the clearWith class or property decorator. */
 export interface ClearWithMetadata {
@@ -22,7 +23,7 @@ const PROPERTY_METADATA_KEY = 'chronicle:projection:clearWith:property';
  * @returns A class and property decorator.
  */
 export function clearWith(eventType: Function): ChronicleClassOrPropertyDecorator {
-    return decorateClassOrProperty((target: object, propertyKey?: string | symbol) => {
+    return decorateModelBoundClassOrProperty((target: object, propertyKey?: string | symbol) => {
         if (propertyKey !== undefined) {
             const key = propertyKey.toString();
             TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);

package/projections/modelBound/count.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the count property decorator. */
 export interface CountMetadata {
@@ -22,7 +23,7 @@ const METADATA_KEY = 'chronicle:projection:count';
  * @returns A property decorator.
  */
 export function count(eventType: Function, constantKey?: string): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: CountMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];

package/projections/modelBound/decorators.standard.spec.ts

@@ -20,6 +20,12 @@ import { getSetFromMetadata, setFrom } from './setFrom.js';
 import { getSetValueMetadata, setValue } from './setValue.js';
 import { getSubtractFromMetadata, subtractFrom } from './subtractFrom.js';
 import { getTrackedJsonSchemaProperties, jsonSchemaProperty } from '../../schemas/jsonSchemaProperty.js';
+import { DecoratorType } from '../../types/DecoratorType.js';
+import { TypeDiscoverer } from '../../types/TypeDiscoverer.js';
+import { DefaultClientArtifactsProvider } from '../../artifacts/DefaultClientArtifactsProvider.js';
+import { ReadModels } from '../../readModels/ReadModels.js';
+import type { ChronicleConnection } from '../../connection/ChronicleConnection.js';
+import { vi } from 'vitest';
 
 class Changed {}
 
@@ -45,7 +51,46 @@ class Mappings {
     @jsonSchemaProperty() tracked!: string;
 }
 
+class StandardMappedOnly {
+    @setFrom(Changed) value = '';
+}
+
+class UnconstructedMappedOnly {
+    @setFrom(Changed) value = '';
+}
+
 describe('standard model-bound decorators', () => {
+    it('collects a standard-mapped class for lazy root discovery when constructed without file discovery', () => {
+        new StandardMappedOnly();
+        new StandardMappedOnly();
+        expect(TypeDiscoverer.default.getTypeByDecoratorTypeAndName(DecoratorType.ReadModel, 'StandardMappedOnly'))
+            .toBeUndefined();
+        expect(DefaultClientArtifactsProvider.default.readModels.filter(type => type === StandardMappedOnly)).toHaveLength(1);
+    });
+
+    it('registers the declaring class once even when subclasses and many instances are constructed', () => {
+        class Base {
+            @setFrom(Changed) value = '';
+        }
+        class Derived extends Base {}
+        const track = vi.spyOn(TypeDiscoverer.default, 'trackModelBoundProperty');
+        try {
+            for (let index = 0; index < 50; index++) new Base();
+            new Derived();
+            expect(track.mock.calls.filter(([type]) => type === Base)).toHaveLength(1);
+            expect(track.mock.calls.some(([type]) => type === Derived)).toBe(false);
+        } finally {
+            track.mockRestore();
+        }
+    });
+
+    it('should explain that an unconstructed property-only model was never registered', async () => {
+        const getInstanceByKey = vi.fn().mockResolvedValue({ ReadModel: '{"value":"stored"}' });
+        const connection = { readModels: { getInstanceByKey } } as unknown as ChronicleConnection;
+        const readModels = new ReadModels('store', 'Default', connection, DefaultClientArtifactsProvider.default, 'sink');
+        await expect(readModels.findInstanceById(UnconstructedMappedOnly, 'id')).rejects.toThrow(/add a class-level @fromEvent/);
+        expect(getInstanceByKey).not.toHaveBeenCalled();
+    });
     it('stores class and property annotations without constructing an instance', () => {
         const target = Mappings.prototype;
         expect(isNoAutoMap(Mappings)).toBe(true);

package/projections/modelBound/decrement.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the decrement property decorator. */
 export interface DecrementMetadata {
@@ -22,7 +23,7 @@ const METADATA_KEY = 'chronicle:projection:decrement';
  * @returns A property decorator.
  */
 export function decrement(eventType: Function, constantKey?: string): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: DecrementMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];

package/projections/modelBound/fromAll.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the fromAll property decorator. */
 export interface FromAllMetadata {
@@ -25,7 +26,7 @@ const METADATA_KEY = 'chronicle:projection:fromAll';
  * @returns A property decorator.
  */
 export function fromAll(property?: string, contextProperty?: string): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, propertyKey.toString());
         const metadata: FromAllMetadata = { property, contextProperty };
         Reflect.defineMetadata(METADATA_KEY, metadata, target, propertyKey.toString());

package/projections/modelBound/fromEvery.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the fromEvery property decorator. */
 export interface FromEveryMetadata {
@@ -22,7 +23,7 @@ const METADATA_KEY = 'chronicle:projection:fromEvery';
  * @returns A property decorator.
  */
 export function fromEvery(property?: string, contextProperty?: string): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, propertyKey.toString());
         const metadata: FromEveryMetadata = { property, contextProperty };
         Reflect.defineMetadata(METADATA_KEY, metadata, target, propertyKey.toString());

package/projections/modelBound/increment.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the increment property decorator. */
 export interface IncrementMetadata {
@@ -22,7 +23,7 @@ const METADATA_KEY = 'chronicle:projection:increment';
  * @returns A property decorator.
  */
 export function increment(eventType: Function, constantKey?: string): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: IncrementMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];

package/projections/modelBound/join.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the join property decorator. */
 export interface JoinMetadata {
@@ -25,7 +26,7 @@ const METADATA_KEY = 'chronicle:projection:join';
  * @returns A property decorator.
  */
 export function join(eventType: Function, on?: string, eventPropertyName?: string): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: JoinMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];

package/projections/modelBound/nested.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { decorateProperty, hasPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { hasPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
 
 const METADATA_KEY = 'chronicle:projection:nested';
 
@@ -13,7 +14,7 @@ const METADATA_KEY = 'chronicle:projection:nested';
  * @param target - The class prototype.
  * @param propertyKey - The property name.
  */
-const decorateNested = decorateProperty((target: object, propertyKey: string | symbol): void => {
+const decorateNested = decorateModelBoundProperty((target: object, propertyKey: string | symbol): void => {
     const key = propertyKey.toString();
     TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
     Reflect.defineMetadata(METADATA_KEY, true, target, key);

package/projections/modelBound/noAutoMap.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { decorateClassOrProperty, hasPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { hasPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundClassOrProperty } from '../../types/modelBoundProperty.js';
 
 const CLASS_METADATA_KEY = 'chronicle:projection:noAutoMap:class';
 const PROPERTY_METADATA_KEY = 'chronicle:projection:noAutoMap:property';
@@ -18,7 +19,7 @@ const PROPERTY_METADATA_KEY = 'chronicle:projection:noAutoMap:property';
  * @param target - The class constructor, or the class prototype when used on a property.
  * @param propertyKey - The property name, when used as a property decorator.
  */
-const decorateNoAutoMap = decorateClassOrProperty((target: object, propertyKey?: string | symbol): void => {
+const decorateNoAutoMap = decorateModelBoundClassOrProperty((target: object, propertyKey?: string | symbol): void => {
     if (propertyKey !== undefined) {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);

package/projections/modelBound/removedWith.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChronicleClassOrPropertyDecorator, decorateClassOrProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundClassOrProperty } from '../../types/modelBoundProperty.js';
+import { ChronicleClassOrPropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the removedWith class or property decorator. */
 export interface RemovedWithMetadata {
@@ -28,7 +29,7 @@ const PROPERTY_METADATA_KEY = 'chronicle:projection:removedWith:property';
  * @returns A class and property decorator.
  */
 export function removedWith(eventType: Function, key?: string, parentKey?: string): ChronicleClassOrPropertyDecorator {
-    return decorateClassOrProperty((target: object, propertyKey?: string | symbol) => {
+    return decorateModelBoundClassOrProperty((target: object, propertyKey?: string | symbol) => {
         if (propertyKey !== undefined) {
             const propKey = propertyKey.toString();
             TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, propKey);

package/projections/modelBound/removedWithJoin.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChronicleClassOrPropertyDecorator, decorateClassOrProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundClassOrProperty } from '../../types/modelBoundProperty.js';
+import { ChronicleClassOrPropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the removedWithJoin class or property decorator. */
 export interface RemovedWithJoinMetadata {
@@ -23,7 +24,7 @@ const PROPERTY_METADATA_KEY = 'chronicle:projection:removedWithJoin:property';
  * @returns A class and property decorator.
  */
 export function removedWithJoin(eventType: Function, key?: string): ChronicleClassOrPropertyDecorator {
-    return decorateClassOrProperty((target: object, propertyKey?: string | symbol) => {
+    return decorateModelBoundClassOrProperty((target: object, propertyKey?: string | symbol) => {
         if (propertyKey !== undefined) {
             const propKey = propertyKey.toString();
             TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, propKey);

package/projections/modelBound/setFrom.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the setFrom property decorator. */
 export interface SetFromMetadata {
@@ -22,7 +23,7 @@ const METADATA_KEY = 'chronicle:projection:setFrom';
  * @returns A property decorator.
  */
 export function setFrom(eventType: Function, eventPropertyName?: string): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: SetFromMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];

package/projections/modelBound/setFromContext.ts

@@ -5,7 +5,8 @@ import 'reflect-metadata';
 import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
 import type { EventContext } from '../../events/index.js';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the setFromContext property decorator. */
 export interface SetFromContextMetadata {
@@ -29,7 +30,7 @@ export function setFromContext(
     eventType: Function,
     contextPropertyOrAccessor?: string | PropertyAccessor<EventContext>
 ): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: SetFromContextMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];

package/projections/modelBound/setValue.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the setValue property decorator. */
 export interface SetValueMetadata {
@@ -22,7 +23,7 @@ const METADATA_KEY = 'chronicle:projection:setValue';
  * @returns A property decorator.
  */
 export function setValue(eventType: Function, value: unknown): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: SetValueMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];

package/projections/modelBound/subtractFrom.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the subtractFrom property decorator. */
 export interface SubtractFromMetadata {
@@ -22,7 +23,7 @@ const METADATA_KEY = 'chronicle:projection:subtractFrom';
  * @returns A property decorator.
  */
 export function subtractFrom(eventType: Function, eventPropertyName?: string): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: SubtractFromMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];

package/projections/notSetPropertyPath.ts

@@ -0,0 +1,5 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The wire representation of PropertyPath.NotSet, used for nested projections. */
+export const notSetPropertyPath = '*NotSet*';

package/reactors/Reactors.ts

@@ -105,7 +105,9 @@ export class Reactors implements IReactors {
     private readonly _lifecycle: ConnectionLifecycle;
     private readonly _reactors = new Map<string, Constructor>();
     private readonly _queues = new Map<string, AsyncQueue<ReactorMessage>>();
+    private readonly _observations = new Map<string, AbortController>();
     private _registered = false;
+    private _disposed = false;
 
     /**
      * Creates a new {@link Reactors} instance.
@@ -133,6 +135,13 @@ export class Reactors implements IReactors {
         });
     }
 
+    /** Stops observations permanently when the owning client is disposed. */
+    dispose(): void {
+        this._disposed = true;
+        this._registered = false;
+        this.disconnectAll();
+    }
+
     /** @inheritdoc */
     async discover(): Promise<void> {
         this._reactors.clear();
@@ -147,7 +156,7 @@ export class Reactors implements IReactors {
 
     /** @inheritdoc */
     async register(): Promise<void> {
-        if (this._registered) {
+        if (this._registered || this._disposed) {
             return;
         }
 
@@ -155,6 +164,7 @@ export class Reactors implements IReactors {
             await this.discover();
         }
 
+        if (this._disposed) return;
         this._logger.info('Registering reactors', { count: this._reactors.size });
         for (const [id, reactorType] of this._reactors) {
             this.startObservation(id, reactorType);
@@ -164,6 +174,7 @@ export class Reactors implements IReactors {
     }
 
     private startObservation(id: string, reactorType: Constructor): void {
+        if (this._disposed) return;
         const metadata = getReactorMetadata(reactorType)!;
         const eventSequenceId = metadata.eventSequenceId ?? EventSequenceId.eventLog.value;
         const eventTypes = this.getEventTypesFor(reactorType);
@@ -205,12 +216,12 @@ export class Reactors implements IReactors {
     private scheduleReobserve(id: string, reactorType: Constructor): void {
         // A disconnect clears the registration; the reconnect re-registers every
         // reactor from scratch, so retrying here as well would double up.
-        if (!this._registered) {
+        if (!this._registered || this._disposed) {
             return;
         }
 
         const handle = setTimeout(() => {
-            if (!this._registered) {
+            if (!this._registered || this._disposed) {
                 return;
             }
 
@@ -228,7 +239,9 @@ export class Reactors implements IReactors {
         eventTypes: EventTypeEntry[]
     ): Promise<void> {
         const queue = new AsyncQueue<ReactorMessage>();
+        const controller = new AbortController();
         this._queues.set(id, queue);
+        this._observations.set(id, controller);
 
         queue.send({
             Content: {
@@ -259,7 +272,7 @@ export class Reactors implements IReactors {
         try {
             const reactorInstance = new (reactorType as new () => Record<string, Function>)();
 
-            for await (const eventsToObserve of this._connection.reactors.observe(queue)) {
+            for await (const eventsToObserve of this._connection.reactors.observe(queue, { signal: controller.signal })) {
                 let lastSuccessfullyObservedEvent = SEQUENCE_NUMBER_UNAVAILABLE;
                 let state = ObservationState.Success;
                 const exceptionMessages: string[] = [];
@@ -358,7 +371,9 @@ export class Reactors implements IReactors {
             // leak a duplicate stream on every reconnect.
             if (this._queues.get(id) === queue) {
                 this._queues.delete(id);
+                this._observations.delete(id);
             }
+            queue.complete();
         }
     }
 
@@ -422,9 +437,9 @@ export class Reactors implements IReactors {
     }
 
     private disconnectAll(): void {
-        for (const queue of this._queues.values()) {
-            queue.complete();
-        }
+        for (const controller of this._observations.values()) controller.abort();
+        for (const queue of this._queues.values()) queue.complete();
+        this._observations.clear();
         this._queues.clear();
     }
 }

package/reactors/reactor.ts

@@ -25,8 +25,8 @@ export interface ReactorMetadata {
  * identifier. This is the TypeScript equivalent of the C# `[Reactor]` attribute.
  *
  * Reactors observe events from an event sequence and produce side effects.
- * Method dispatch is by convention: the type of the first parameter of each public method
- * determines which events it handles.
+ * Method dispatch is by convention: a handler's name is the event class name with
+ * its first letter lowercased (for example, `projectRegistered` handles `ProjectRegistered`).
  *
  * @param id - The unique identifier for the reactor. Defaults to the class name if omitted.
  * @param eventSequenceId - Optional explicit event sequence identifier.

package/readModels/IReadModels.ts

@@ -33,8 +33,9 @@ export interface IReadModels {
      * @param readModelType - The read model type to retrieve.
      * @param key - The read model key.
      * @param sessionId - Optional session identifier.
-     * @returns The read model instance. When no instance exists, returns a prototype-only instance.
-     * @deprecated Use {@link findInstanceById} to distinguish an absent instance from a stored one.
+     * @returns The read model instance. When the kernel returns an empty document for a missing key,
+     * returns a prototype-only instance; a JSON `null` document may construct a model with default fields.
+     * Use {@link findInstanceById} when absence must be distinguished from stored data.
      */
     getInstanceById<TReadModel>(readModelType: Constructor<TReadModel>, key: string, sessionId?: string): Promise<TReadModel>;
 

package/readModels/MaterializedReadModels.spec.ts

@@ -25,6 +25,28 @@ function createMaterializedReadModels(instancesJson: string[], releaseResponse:
 }
 
 describe('MaterializedReadModels', () => {
+    describe('when materialized models have undecorated members', () => {
+        class Model { name = ''; count = 0; occurred = new Date(0); }
+        const json = JSON.stringify({ name: 'stored', count: 3, occurred: '2024-02-01T00:00:00.000Z' });
+
+        it('should restore members in paged reads', async () => {
+            const { readModels } = createMaterializedReadModels([json]);
+            const [instance] = await readModels.getInstances(Model);
+            expect(instance).toMatchObject({ name: 'stored', count: 3 });
+            expect(instance.occurred).toEqual(new Date('2024-02-01T00:00:00.000Z'));
+        });
+
+        it('should restore members in observed pages', async () => {
+            const connection = { materializedReadModels: { observeInstances: async function* () {
+                yield { Instances: [json] };
+            } } } as unknown as ChronicleConnection;
+            const readModels = new MaterializedReadModels('store', 'tenant', connection);
+            const response = await readModels.observeInstances(Model)[Symbol.asyncIterator]().next();
+            expect(response.value?.[0].name).toBe('stored');
+            expect(response.value?.[0].occurred).toBeInstanceOf(Date);
+        });
+    });
+
     describe('when a read model has a property decorated with @subject()', () => {
         class Employee {
             id = '';

package/readModels/MaterializedReadModels.ts

@@ -7,6 +7,7 @@ import { ChronicleConnection } from '../connection/index.js';
 import { JsonSchemaGenerator } from '../schemas/index.js';
 import { getReadModelMetadata } from './readModel.js';
 import { ReadModelSubjectResolver } from './ReadModelSubjectResolver.js';
+import { deserializeReadModel } from './deserializeReadModel.js';
 import type { IMaterializedReadModels } from './IMaterializedReadModels.js';
 
 const defaultTake = 50;
@@ -82,10 +83,7 @@ export class MaterializedReadModels implements IMaterializedReadModels {
     }
 
     private deserialize<TReadModel>(readModelType: Constructor<TReadModel>, json: string): TReadModel {
-        if (!json) {
-            return Object.create(readModelType.prototype) as TReadModel;
-        }
-        return JsonSerializer.deserialize(readModelType as Constructor<object>, json) as TReadModel;
+        return deserializeReadModel(readModelType, json);
     }
 
     private async releaseInstances<TReadModel>(readModelType: Constructor<TReadModel>, instances: TReadModel[]): Promise<TReadModel[]> {