@cratis/chronicle 6.47.0 → 6.49.0

package/readModels/ReadModelWatcher.ts

@@ -0,0 +1,271 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ReadModelChangeset as ContractChangeset } from '@cratis/chronicle.contracts';
+import type { ConnectionLifecycle } from '../connection/ConnectionLifecycle.js';
+import type { IReadModelWatcher } from './IReadModelWatcher.js';
+import type { ReadModelChangeset } from './ReadModelChangeset.js';
+import type { ReadModelWatchOptions } from './ReadModelWatchOptions.js';
+
+/** @internal Owns one cancellable stream per connection generation. */
+export class ReadModelWatcher<TReadModel> implements IReadModelWatcher<TReadModel>, AsyncIterableIterator<ReadModelChangeset<TReadModel>> {
+    private static readonly _restartDelayMs = 1000;
+    private readonly _bufferLimit: number;
+    private readonly _failOnOverflow: boolean;
+    private readonly _resume: boolean;
+    private _resumeReading?: () => void;
+
+    private _subscribed!: Promise<void>;
+    private _resolveSubscribed!: () => void;
+    private _rejectSubscribed!: (error: unknown) => void;
+    private _acknowledged = false;
+    private _hasSubscribed = false;
+    private _delivery = Promise.resolve();
+    private readonly _onResubscribed = new Set<() => void | Promise<void>>();
+    private _controller?: AbortController;
+    private _stopped = false;
+    private _failed = false;
+    private _failure?: unknown;
+    private readonly _buffered: ReadModelChangeset<TReadModel>[] = [];
+    private _restartTimer?: ReturnType<typeof setTimeout>;
+    private readonly _waiting: {
+        resolve: (result: IteratorResult<ReadModelChangeset<TReadModel>>) => void;
+        reject: (error: unknown) => void;
+    }[] = [];
+    private readonly _unsubscribe: (() => void)[] = [];
+
+    constructor(
+        private readonly _open: (signal: AbortSignal) => AsyncIterable<ContractChangeset>,
+        private readonly _convert: (change: ContractChangeset) => Promise<ReadModelChangeset<TReadModel>>,
+        signal: AbortSignal,
+        private readonly _lifecycle?: ConnectionLifecycle,
+        options: ReadModelWatchOptions = {}
+    ) {
+        if (options.maxBuffered !== undefined && (!Number.isSafeInteger(options.maxBuffered) || options.maxBuffered < 1)) {
+            throw new RangeError('maxBuffered must be a positive safe integer.');
+        }
+        this._bufferLimit = options.maxBuffered ?? 1024;
+        this._failOnOverflow = options.maxBuffered !== undefined;
+        this._resume = options.resume === true;
+        this.resetReadiness();
+        const abort = () => this.finish(signal.reason, false);
+        signal.addEventListener('abort', abort, { once: true });
+        this._unsubscribe.push(() => signal.removeEventListener('abort', abort));
+        if (_lifecycle) {
+            // Without opt-in, let the watch stream propagate its original transport error.
+            this._unsubscribe.push(_lifecycle.onDisconnected(async () => {
+                if (this.shouldResume()) this.disconnect();
+            }));
+            this._unsubscribe.push(_lifecycle.onConnected(async () => this.start()));
+            this._unsubscribe.push(_lifecycle.onFailed(async error => this.finish(error, true, true)));
+        }
+        if (signal.aborted) {
+            abort();
+        } else if (_lifecycle?.failure) {
+            this.finish(_lifecycle.failure, true, true);
+        } else if (!_lifecycle || _lifecycle.isConnected) {
+            this.start();
+        }
+    }
+
+    get subscribed(): Promise<void> {
+        return this._subscribed;
+    }
+
+    onResubscribed(callback: () => void | Promise<void>): () => void {
+        if (this._stopped) return () => {};
+        this._onResubscribed.add(callback);
+        return () => { this._onResubscribed.delete(callback); };
+    }
+
+    [Symbol.asyncIterator](): AsyncIterableIterator<ReadModelChangeset<TReadModel>> {
+        return this;
+    }
+
+    next(): Promise<IteratorResult<ReadModelChangeset<TReadModel>>> {
+        const value = this._buffered.shift();
+        if (value) {
+            this.resumeReading();
+            return Promise.resolve({ done: false, value });
+        }
+        if (this._failed) return Promise.reject(this._failure);
+        if (this._stopped) return Promise.resolve({ done: true, value: undefined });
+        return new Promise((resolve, reject) => this._waiting.push({ resolve, reject }));
+    }
+
+    async return(): Promise<IteratorResult<ReadModelChangeset<TReadModel>>> {
+        this.dispose();
+        return { done: true, value: undefined };
+    }
+
+    dispose(): void {
+        this._buffered.length = 0;
+        this.finish(new DOMException('Read model watcher disposed.', 'AbortError'), false);
+    }
+
+    private resetReadiness(): void {
+        this._acknowledged = false;
+        this._subscribed = new Promise<void>((resolve, reject) => {
+            this._resolveSubscribed = resolve;
+            this._rejectSubscribed = reject;
+        });
+        // Legacy consumers only iterate. They still receive stream failures from next();
+        // not observing the optional readiness promise must not cause an unhandled rejection.
+        this._subscribed.catch(() => {});
+    }
+
+    private start(): void {
+        if (this._stopped || this._controller) return;
+        this.clearRestartTimer();
+        const controller = new AbortController();
+        this._controller = controller;
+        void this.read(controller);
+    }
+
+    private disconnect(): void {
+        if (this._stopped) return;
+        this.clearRestartTimer();
+        this.cancelStream();
+        // Received changes are not replayed by the kernel. Keep them across reconnects.
+        if (this._acknowledged) this.resetReadiness();
+    }
+
+    private shouldResume(): boolean {
+        return this._resume || this._onResubscribed.size > 0;
+    }
+
+    private restart(): void {
+        this.disconnect();
+        if (this._stopped || (this._lifecycle && !this._lifecycle.isConnected)) return;
+        // The watch and keep-alive share a transport, but can fail in either order.
+        // Also recover a watch-only failure if no disconnected notification follows.
+        this._restartTimer = setTimeout(() => {
+            this._restartTimer = undefined;
+            if (!this._lifecycle || this._lifecycle.isConnected) this.start();
+        }, ReadModelWatcher._restartDelayMs);
+        this._restartTimer.unref?.();
+    }
+
+    private clearRestartTimer(): void {
+        clearTimeout(this._restartTimer);
+        this._restartTimer = undefined;
+    }
+
+    private cancelStream(): void {
+        const controller = this._controller;
+        this._controller = undefined;
+        controller?.abort();
+        this.resumeReading();
+    }
+
+    private resumeReading(): void {
+        this._resumeReading?.();
+        this._resumeReading = undefined;
+    }
+
+    private waitForCapacity(controller: AbortController): Promise<void> | undefined {
+        if (this._controller === controller && this._acknowledged && !this._failOnOverflow &&
+            this._buffered.length >= this._bufferLimit) {
+            return new Promise<void>(resolve => { this._resumeReading = resolve; })
+                .then(() => this.waitForCapacity(controller));
+        }
+        return undefined;
+    }
+
+    private async read(controller: AbortController): Promise<void> {
+        try {
+            for await (const change of this._open(controller.signal)) {
+                if (this._controller !== controller) return;
+                if (change.Subscribed) {
+                    if (this._acknowledged) continue;
+                    this._acknowledged = true;
+                    this._resolveSubscribed();
+                    const resubscribed = this._hasSubscribed;
+                    this._hasSubscribed = true;
+                    if (resubscribed) {
+                        const callbacks = [...this._onResubscribed];
+                        this._delivery = this._delivery.then(() => this.notifyResubscribed(callbacks));
+                        await this._delivery;
+                    }
+                    const capacity = this.waitForCapacity(controller);
+                    if (capacity) await capacity;
+                    if (this._controller !== controller) return;
+                    continue;
+                }
+                // Finish converting changes already received, even if their stream disconnects.
+                // A new stream queues behind them so conversion cannot reorder delivery.
+                this._delivery = this._delivery.then(() => this.deliver(change));
+                await this._delivery;
+                const capacity = this.waitForCapacity(controller);
+                if (capacity) await capacity;
+                if (this._controller !== controller) return;
+            }
+            if (this._controller === controller) {
+                if (this.shouldResume()) this.restart();
+                else this.finish(new Error('Read model watch ended before subscription acknowledgment.'), false, true);
+            }
+        } catch (error) {
+            if (this._controller !== controller) return;
+            const code = (error as { code?: number })?.code;
+            if (this.shouldResume() && code !== undefined && [1, 4, 13, 14].includes(code)) this.restart();
+            // Let the consumer drain received changes before observing the terminal stream error.
+            else this.finish(error, true, true);
+        }
+    }
+
+    private async deliver(change: ContractChangeset): Promise<void> {
+        if (this._stopped) return;
+        let converted: ReadModelChangeset<TReadModel>;
+        try {
+            converted = await this._convert(change);
+        } catch (error) {
+            // Conversion includes compliance RPCs: even transport-coded errors here
+            // are terminal, not permission to skip an unreleased change.
+            this.finish(error, true);
+            return;
+        }
+        if (this._stopped) return;
+        const waiting = this._waiting.shift();
+        if (waiting) {
+            waiting.resolve({ done: false, value: converted });
+        } else {
+            // Before Subscribed we must keep reading to reach the readiness marker.
+            // Afterward the default pauses reads; only an explicit limit opts into failure.
+            if (this._buffered.length >= this._bufferLimit) {
+                this.finish(new Error(`Read model watcher buffer exceeded ${this._bufferLimit} changes. Consume changes faster or refresh the read model and create a new watcher.`), true);
+                return;
+            }
+            this._buffered.push(converted);
+        }
+    }
+
+    private async notifyResubscribed(callbacks: (() => void | Promise<void>)[]): Promise<void> {
+        try {
+            for (const callback of callbacks) {
+                if (this._stopped) return;
+                if (this._onResubscribed.has(callback)) await callback();
+            }
+        } catch (error) {
+            // A failed refresh is not a recovered watch, even for transport-coded errors.
+            this.finish(error, true);
+        }
+    }
+
+    private finish(reason: unknown, failed: boolean, preserveBuffered = false): void {
+        if (this._stopped) return;
+        this._stopped = true;
+        this._failed = failed;
+        this._failure = reason;
+        this._rejectSubscribed(reason);
+        this.clearRestartTimer();
+        this.cancelStream();
+        if (!preserveBuffered) this._buffered.length = 0;
+        for (const unsubscribe of this._unsubscribe) unsubscribe();
+        this._unsubscribe.length = 0;
+        this._onResubscribed.clear();
+        for (const waiting of this._waiting.splice(0)) {
+            if (failed) waiting.reject(reason);
+            else waiting.resolve({ done: true, value: undefined });
+        }
+    }
+}

package/readModels/ReadModels.ts

@@ -3,15 +3,19 @@
 
 import type {
     AppendedEvent,
+    ReadModelChangeset as ContractReadModelChangeset,
     ReadModelObserverType
 } from '@cratis/chronicle.contracts';
 import {
-    ReadModelObserverType as ContractReadModelObserverType
+    ReadModelObserverType as ContractReadModelObserverType,
+    ReadModelChangeType as ContractReadModelChangeType
 } from '@cratis/chronicle.contracts';
 import type { Constructor } from '@cratis/fundamentals';
 import { JsonSerializer } from '@cratis/fundamentals';
 import { IClientArtifactsProvider } from '../artifacts/index.js';
 import { ChronicleConnection } from '../connection/index.js';
+import type { ConnectionLifecycle } from '../connection/ConnectionLifecycle.js';
+import { fromContractsGuid } from '../connection/Guid.js';
 import { ensureQuerySuccess } from '../connection/callResults.js';
 import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
 import { getProjectionMetadata } from '../projections/declarative/projection.js';
@@ -31,7 +35,11 @@ import { ReadModelSubjectResolver } from './ReadModelSubjectResolver.js';
 import { deserializeReadModel } from './deserializeReadModel.js';
 import type { ReadModelNamingPolicy } from './ReadModelNamingPolicy.js';
 import type { IReadModels } from './IReadModels.js';
+import type { IReadModelWatcher } from './IReadModelWatcher.js';
+import { ReadModelWatcher } from './ReadModelWatcher.js';
 import type { ReadModelChangeset } from './ReadModelChangeset.js';
+import type { ReadModelWatchOptions } from './ReadModelWatchOptions.js';
+import { ReadModelChangeType } from './ReadModelChangeType.js';
 import type { ReadModelSnapshot } from './ReadModelSnapshot.js';
 
 const unlimitedEventCount = BigInt('18446744073709551615');
@@ -52,6 +60,7 @@ interface ResolvedReadModel {
  */
 export class ReadModels implements IReadModels {
     readonly materialized: IMaterializedReadModels;
+    private readonly _watchCancellation = new AbortController();
 
     constructor(
         private readonly _eventStore: string,
@@ -60,7 +69,8 @@ export class ReadModels implements IReadModels {
         private readonly _clientArtifacts: IClientArtifactsProvider,
         private readonly _defaultSinkTypeId: string,
         private readonly _isModelBoundProjectionRegistered?: (readModelType: Constructor) => boolean,
-        private readonly _readModelNamingPolicy?: ReadModelNamingPolicy
+        private readonly _readModelNamingPolicy?: ReadModelNamingPolicy,
+        private readonly _lifecycle?: ConnectionLifecycle
     ) {
         this.materialized = new MaterializedReadModels(_eventStore, _namespace, _connection);
     }
@@ -185,18 +195,35 @@ export class ReadModels implements IReadModels {
                 continue;
             }
 
-            const instance = this.deserializeReadModel(readModelType, changeset.ReadModel);
-            const requiresRelease = !changeset.Removed && readModel.observerType === ContractReadModelObserverType.Reducer &&
-                this.schemaHasComplianceMetadata(readModel.schema);
-            yield {
-                namespace: changeset.Namespace,
-                key: changeset.ModelKey,
-                readModel: requiresRelease ? await this.release(readModelType, instance) : instance,
-                removed: changeset.Removed
-            };
+            yield await this.toChangeset(readModelType, readModel, changeset);
         }
     }
 
+    /** @inheritdoc */
+    createWatcher<TReadModel>(readModelType: Constructor<TReadModel>, options?: ReadModelWatchOptions): IReadModelWatcher<TReadModel> {
+        const readModel = this.resolveReadModel(readModelType);
+        const signal = AbortSignal.any(options?.signal
+            ? [options.signal, this._watchCancellation.signal]
+            : [this._watchCancellation.signal]);
+        return new ReadModelWatcher(
+            streamSignal => this._connection.readModels.watch({
+                EventStore: this._eventStore,
+                Namespace: this._namespace,
+                ReadModelIdentifier: readModel.identifier,
+                EventSequenceId: readModel.eventSequenceId
+            }, { signal: streamSignal }),
+            changeset => this.toChangeset(readModelType, readModel, changeset),
+            signal,
+            this._lifecycle,
+            options
+        );
+    }
+
+    /** Stops all watchers created through createWatcher for this event store. */
+    dispose(): void {
+        this._watchCancellation.abort();
+    }
+
     /** @inheritdoc */
     async dehydrateSession<TReadModel>(sessionId: string, readModelType: Constructor<TReadModel>, key: string): Promise<void> {
         const readModel = this.resolveReadModel(readModelType);
@@ -355,6 +382,28 @@ export class ReadModels implements IReadModels {
         return typeof value === 'string' && value.length > 0;
     }
 
+    private async toChangeset<TReadModel>(readModelType: Constructor<TReadModel>, readModel: ResolvedReadModel, changeset: ContractReadModelChangeset): Promise<ReadModelChangeset<TReadModel>> {
+        const instance = this.deserializeReadModel(readModelType, changeset.ReadModel);
+        const occurred = changeset.Occurred?.Value ? new Date(changeset.Occurred.Value) : undefined;
+        const requiresRelease = !changeset.Removed && readModel.observerType === ContractReadModelObserverType.Reducer &&
+            this.schemaHasComplianceMetadata(readModel.schema);
+        return {
+            namespace: changeset.Namespace,
+            key: changeset.ModelKey,
+            readModel: requiresRelease ? await this.release(readModelType, instance) : instance,
+            removed: changeset.Removed,
+            changeType: changeset.ChangeType === ContractReadModelChangeType.Added ? ReadModelChangeType.Added :
+                changeset.ChangeType === ContractReadModelChangeType.Removed ? ReadModelChangeType.Removed : ReadModelChangeType.Modified,
+            changeContext: {
+                eventStore: this._eventStore,
+                namespace: changeset.Namespace,
+                sequenceNumber: changeset.EventSequenceNumber,
+                correlationId: changeset.CorrelationId ? fromContractsGuid(changeset.CorrelationId).toString() : undefined,
+                occurred: occurred && !Number.isNaN(occurred.getTime()) ? occurred : undefined
+            }
+        };
+    }
+
     private async releaseSnapshotInstances<TReadModel>(readModelType: Constructor<TReadModel>, snapshots: ReadModelSnapshot<TReadModel>[]): Promise<ReadModelSnapshot<TReadModel>[]> {
         return Promise.all(
             snapshots.map(async snapshot => ({

package/readModels/for_ReadModelWatcher/against_a_kernel/when_watching_changes.integration.spec.ts

@@ -0,0 +1,104 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { randomUUID } from 'node:crypto';
+import { field } from '@cratis/fundamentals';
+import { afterAll, beforeAll, chai, describe, it } from 'vitest';
+import { ChronicleClient } from '../../../ChronicleClient.js';
+import { ChronicleOptions } from '../../../ChronicleOptions.js';
+import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import { eventType } from '../../../events/index.js';
+import { fromEvent, removedWith } from '../../../projections/index.js';
+import type { IReadModelWatcher } from '../../IReadModelWatcher.js';
+import type { ReadModelChangeset } from '../../ReadModelChangeset.js';
+import { ReadModelChangeType } from '../../ReadModelChangeType.js';
+
+chai.should();
+const connectionString = process.env.CHRONICLE_INTEGRATION_CONNECTION_STRING;
+
+@eventType()
+class NameChanged {
+    @field(String) name = '';
+}
+
+@eventType()
+class EntryRemoved {
+    @field(String) reason = 'removed';
+}
+
+@fromEvent(NameChanged)
+@removedWith(EntryRemoved)
+class WatchedEntry {
+    @field(String) name = '';
+}
+
+const artifacts: IClientArtifactsProvider = {
+    eventTypes: [NameChanged, EntryRemoved], readModels: [WatchedEntry],
+    projections: [], reactors: [], reducers: [], seeders: [], constraints: [], webhooks: [],
+    eventTypeMigrations: [], globalForHandlers: []
+};
+
+describe.skipIf(!connectionString && !process.env.CI)('when awaiting readiness before appending against a kernel', () => {
+    const storeName = `Watcher${randomUUID().replaceAll('-', '').slice(0, 12)}`;
+    const source = randomUUID();
+    const correlationIds = [randomUUID(), randomUUID(), randomUUID()];
+    const occurred = new Date('2026-01-02T03:04:05.123Z');
+    const changes: ReadModelChangeset<WatchedEntry>[] = [];
+    const sequenceNumbers: bigint[] = [];
+    let client: ChronicleClient;
+    let watcher: IReadModelWatcher<WatchedEntry>;
+
+    beforeAll(async () => {
+        client = new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, {
+            discoveryPatterns: [], clientArtifactsProvider: artifacts
+        }));
+        const store = await client.getEventStore(storeName);
+        watcher = store.readModels.createWatcher(WatchedEntry, { signal: AbortSignal.timeout(60_000) });
+        // No iteration, arbitrary sleep, or append before the server's readiness barrier.
+        await watcher.subscribed;
+        const iterator = watcher[Symbol.asyncIterator]();
+        const events = [Object.assign(new NameChanged(), { name: 'first' }),
+            Object.assign(new NameChanged(), { name: 'second' }), new EntryRemoved()];
+        for (const [index, event] of events.entries()) {
+            const result = await store.eventLog.append(source, event, { correlationId: correlationIds[index], occurred });
+            result.isSuccess.should.be.true;
+            sequenceNumbers.push(result.sequenceNumber.value);
+            const change = await iterator.next();
+            if (change.done) throw new Error('Watcher ended before the appended change arrived.');
+            changes.push(change.value);
+        }
+    });
+    afterAll(() => {
+        watcher?.dispose();
+        client?.dispose();
+    });
+
+    it('should observe creation, modification, and removal in order', () => {
+        changes.map(change => change.changeType).should.deep.equal([
+            ReadModelChangeType.Added, ReadModelChangeType.Modified, ReadModelChangeType.Removed
+        ]);
+    });
+    it('should preserve the existing model, key, namespace and removal fields', () => {
+        changes[0].readModel.should.be.instanceOf(WatchedEntry);
+        changes[0].readModel.name.should.equal('first');
+        changes[1].readModel.name.should.equal('second');
+        changes.map(change => change.key).should.deep.equal([source, source, source]);
+        changes.map(change => change.namespace).should.deep.equal(['Default', 'Default', 'Default']);
+        changes.map(change => change.removed).should.deep.equal([false, false, true]);
+    });
+    it('should preserve each triggering sequence number without numeric conversion', () => {
+        changes.map(change => change.changeContext!.sequenceNumber).should.deep.equal(sequenceNumbers);
+    });
+    it('should preserve each triggering correlation identifier', () => {
+        changes.map(change => change.changeContext!.correlationId).should.deep.equal(correlationIds);
+    });
+    it('should preserve each triggering timestamp', () => {
+        changes.map(change => change.changeContext!.occurred!.toISOString()).should.deep.equal([
+            occurred.toISOString(), occurred.toISOString(), occurred.toISOString()
+        ]);
+    });
+    it('should include the store and namespace in the triggering context', () => {
+        changes.every(change => change.changeContext!.eventStore === storeName &&
+            change.changeContext!.namespace === 'Default').should.be.true;
+    });
+});

package/readModels/for_ReadModelWatcher/given/a_kernel_stream.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReadModelChangeset } from '@cratis/chronicle.contracts';
+
+export class a_kernel_stream implements AsyncIterableIterator<ReadModelChangeset> {
+    private readonly _messages: IteratorResult<ReadModelChangeset>[] = [];
+    private _waiting?: {
+        resolve: (result: IteratorResult<ReadModelChangeset>) => void;
+        reject: (error: unknown) => void;
+    };
+    signal!: AbortSignal;
+    closed = false;
+    pulls = 0;
+
+    [Symbol.asyncIterator]() { return this; }
+
+    next(): Promise<IteratorResult<ReadModelChangeset>> {
+        this.pulls++;
+        const message = this._messages.shift();
+        if (message) return Promise.resolve(message);
+        if (this.closed) return Promise.resolve({ done: true, value: undefined });
+        return new Promise((resolve, reject) => { this._waiting = { resolve, reject }; });
+    }
+
+    async return(): Promise<IteratorResult<ReadModelChangeset>> {
+        this.end();
+        return { done: true, value: undefined };
+    }
+
+    send(change: Partial<ReadModelChangeset>): void {
+        const result = { done: false as const, value: ReadModelChangeset.fromPartial(change) };
+        if (this._waiting) {
+            this._waiting.resolve(result);
+            this._waiting = undefined;
+        } else this._messages.push(result);
+    }
+
+    end(): void {
+        this.closed = true;
+        this._waiting?.resolve({ done: true, value: undefined });
+        this._waiting = undefined;
+    }
+
+    fail(error: unknown): void {
+        if (!this._waiting) throw new Error('The stream must be reading before failing it.');
+        this._waiting.reject(error);
+        this._waiting = undefined;
+    }
+}

package/readModels/for_ReadModelWatcher/given/a_watched_read_model.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { vi } from 'vitest';
+import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import { ConnectionLifecycle } from '../../../connection/ConnectionLifecycle.js';
+import type { ChronicleConnection } from '../../../connection/index.js';
+import { fromEvent } from '../../../projections/index.js';
+import { ReadModels } from '../../ReadModels.js';
+import { a_kernel_stream } from './a_kernel_stream.js';
+
+export class a_watched_read_model {
+    readonly model = class Model { id = ''; };
+    readonly lifecycle = new ConnectionLifecycle();
+    readonly streams: a_kernel_stream[] = [];
+    readonly watch = vi.fn((_request: unknown, options?: { signal: AbortSignal }) => {
+        const stream = new a_kernel_stream();
+        if (options) {
+            stream.signal = options.signal;
+            options.signal.addEventListener('abort', () => stream.end(), { once: true });
+        }
+        this.streams.push(stream);
+        return stream;
+    });
+    readonly readModels: ReadModels;
+
+    constructor() {
+        fromEvent(class Changed {})(this.model);
+        const artifacts = { readModels: [this.model], projections: [], reducers: [] } as unknown as IClientArtifactsProvider;
+        const connection = { readModels: { watch: this.watch } } as unknown as ChronicleConnection;
+        this.readModels = new ReadModels('store', 'tenant', connection, artifacts, 'sink', undefined, undefined, this.lifecycle);
+    }
+
+    async connect() { await this.lifecycle.connected(error => { throw error; }); }
+    async disconnect() { await this.lifecycle.disconnected(error => { throw error; }); }
+    async flush() { await new Promise<void>(resolve => setImmediate(resolve)); }
+}

package/readModels/for_ReadModelWatcher/watchCompatibility.standard.spec.ts

@@ -0,0 +1,29 @@
+// 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 { chai, describe, expectTypeOf, it } from 'vitest';
+import type { IReadModels } from '../IReadModels.js';
+import type { ReadModels } from '../ReadModels.js';
+import type { ReadModelChangeset } from '../ReadModelChangeset.js';
+
+chai.should();
+
+describe('when implementing the original watch contract', () => {
+    it('should keep exactly the signature exported on main', () => {
+        expectTypeOf<IReadModels['watch']>().toEqualTypeOf<
+            <TReadModel>(readModelType: Constructor<TReadModel>) => AsyncIterable<ReadModelChangeset<TReadModel>>
+        >();
+        expectTypeOf<ReadModels['watch']>().toEqualTypeOf<IReadModels['watch']>();
+    });
+
+    it('should accept an existing async generator implementation without watcher members', async () => {
+        const mock: Pick<IReadModels, 'watch'> = {
+            async *watch<TReadModel>(readModelType: Constructor<TReadModel>) {
+                yield { namespace: 'tenant', key: 'one', readModel: new readModelType(), removed: false };
+            }
+        };
+        const iterator = mock.watch(class Model {})[Symbol.asyncIterator]();
+        (await iterator.next()).value.key.should.equal('one');
+    });
+});