@cratis/chronicle 6.47.0 → 6.49.0

package/dist/readModels/ReadModelChangeContext.d.ts

@@ -0,0 +1,9 @@
+/** The triggering event metadata available on the kernel's read model change stream. */
+export interface ReadModelChangeContext {
+    readonly eventStore: string;
+    readonly namespace: string;
+    readonly sequenceNumber: bigint;
+    readonly correlationId?: string;
+    readonly occurred?: Date;
+}
+//# sourceMappingURL=ReadModelChangeContext.d.ts.map

package/dist/readModels/ReadModelChangeContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadModelChangeContext.d.ts","sourceRoot":"","sources":["../../readModels/ReadModelChangeContext.ts"],"names":[],"mappings":"AAGA,wFAAwF;AACxF,MAAM,WAAW,sBAAsB;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;CAC5B"}

package/dist/readModels/ReadModelChangeContext.js

@@ -0,0 +1,4 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+export {};
+//# sourceMappingURL=ReadModelChangeContext.js.map

package/dist/readModels/ReadModelChangeContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadModelChangeContext.js","sourceRoot":"","sources":["../../readModels/ReadModelChangeContext.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG"}

package/dist/readModels/ReadModelChangeType.d.ts

@@ -0,0 +1,7 @@
+/** The kind of change to a read model instance. */
+export declare enum ReadModelChangeType {
+    Added = 0,
+    Modified = 1,
+    Removed = 2
+}
+//# sourceMappingURL=ReadModelChangeType.d.ts.map

package/dist/readModels/ReadModelChangeType.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadModelChangeType.d.ts","sourceRoot":"","sources":["../../readModels/ReadModelChangeType.ts"],"names":[],"mappings":"AAGA,mDAAmD;AACnD,oBAAY,mBAAmB;IAC3B,KAAK,IAAI;IACT,QAAQ,IAAI;IACZ,OAAO,IAAI;CACd"}

package/dist/readModels/ReadModelChangeType.js

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/** The kind of change to a read model instance. */
+export var ReadModelChangeType;
+(function (ReadModelChangeType) {
+    ReadModelChangeType[ReadModelChangeType["Added"] = 0] = "Added";
+    ReadModelChangeType[ReadModelChangeType["Modified"] = 1] = "Modified";
+    ReadModelChangeType[ReadModelChangeType["Removed"] = 2] = "Removed";
+})(ReadModelChangeType || (ReadModelChangeType = {}));
+//# sourceMappingURL=ReadModelChangeType.js.map

package/dist/readModels/ReadModelChangeType.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadModelChangeType.js","sourceRoot":"","sources":["../../readModels/ReadModelChangeType.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAErG,mDAAmD;AACnD,MAAM,CAAN,IAAY,mBAIX;AAJD,WAAY,mBAAmB;IAC3B,+DAAS,CAAA;IACT,qEAAY,CAAA;IACZ,mEAAW,CAAA;AACf,CAAC,EAJW,mBAAmB,KAAnB,mBAAmB,QAI9B"}

package/dist/readModels/ReadModelChangeset.d.ts

@@ -1,3 +1,5 @@
+import type { ReadModelChangeType } from './ReadModelChangeType.js';
+import type { ReadModelChangeContext } from './ReadModelChangeContext.js';
 /**
  * Represents a change observed for a read model.
  */
@@ -10,5 +12,9 @@ export interface ReadModelChangeset<TReadModel> {
     readonly readModel: TReadModel;
     /** Whether the read model was removed. */
     readonly removed: boolean;
+    /** The kind of change. Optional for compatibility with user-created changesets. */
+    readonly changeType?: ReadModelChangeType;
+    /** Triggering event metadata supplied by the kernel, not a complete event context. */
+    readonly changeContext?: ReadModelChangeContext;
 }
 //# sourceMappingURL=ReadModelChangeset.d.ts.map

package/dist/readModels/ReadModelChangeset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReadModelChangeset.d.ts","sourceRoot":"","sources":["../../readModels/ReadModelChangeset.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,UAAU;IAC1C,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,oCAAoC;IACpC,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAE/B,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC7B"}
+{"version":3,"file":"ReadModelChangeset.d.ts","sourceRoot":"","sources":["../../readModels/ReadModelChangeset.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,UAAU;IAC1C,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,oCAAoC;IACpC,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAE/B,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B,mFAAmF;IACnF,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,CAAC;IAE1C,sFAAsF;IACtF,QAAQ,CAAC,aAAa,CAAC,EAAE,sBAAsB,CAAC;CACnD"}

package/dist/readModels/ReadModelWatchOptions.d.ts

@@ -0,0 +1,19 @@
+/** Options for creating a read model watcher. */
+export interface ReadModelWatchOptions {
+    /** Aborting completes iteration and rejects pending readiness. */
+    readonly signal?: AbortSignal;
+    /**
+     * Resume after transport failure or completion. Defaults to false; registering an
+     * onResubscribed callback also opts in while at least one callback is registered.
+     * Changes missed during an outage are not replayed; refresh your query after resubscription.
+     */
+    readonly resume?: boolean;
+    /**
+     * Opt into failing on overflow instead of applying backpressure. Must be a positive safe integer.
+     * By default, pause reads at 1,024 buffered changes after subscription acknowledgment.
+     * Before each acknowledgment, keep reading to reach the marker; exceeding 1,024 changes
+     * (or this explicit limit) fails iteration and pending readiness rather than dropping changes.
+     */
+    readonly maxBuffered?: number;
+}
+//# sourceMappingURL=ReadModelWatchOptions.d.ts.map

package/dist/readModels/ReadModelWatchOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadModelWatchOptions.d.ts","sourceRoot":"","sources":["../../readModels/ReadModelWatchOptions.ts"],"names":[],"mappings":"AAGA,iDAAiD;AACjD,MAAM,WAAW,qBAAqB;IAClC,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CACjC"}

package/dist/readModels/ReadModelWatchOptions.js

@@ -0,0 +1,4 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+export {};
+//# sourceMappingURL=ReadModelWatchOptions.js.map

package/dist/readModels/ReadModelWatchOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadModelWatchOptions.js","sourceRoot":"","sources":["../../readModels/ReadModelWatchOptions.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG"}

package/dist/readModels/ReadModelWatcher.d.ts

@@ -0,0 +1,52 @@
+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 declare class ReadModelWatcher<TReadModel> implements IReadModelWatcher<TReadModel>, AsyncIterableIterator<ReadModelChangeset<TReadModel>> {
+    private readonly _open;
+    private readonly _convert;
+    private readonly _lifecycle?;
+    private static readonly _restartDelayMs;
+    private readonly _bufferLimit;
+    private readonly _failOnOverflow;
+    private readonly _resume;
+    private _resumeReading?;
+    private _subscribed;
+    private _resolveSubscribed;
+    private _rejectSubscribed;
+    private _acknowledged;
+    private _hasSubscribed;
+    private _delivery;
+    private readonly _onResubscribed;
+    private _controller?;
+    private _stopped;
+    private _failed;
+    private _failure?;
+    private readonly _buffered;
+    private _restartTimer?;
+    private readonly _waiting;
+    private readonly _unsubscribe;
+    constructor(_open: (signal: AbortSignal) => AsyncIterable<ContractChangeset>, _convert: (change: ContractChangeset) => Promise<ReadModelChangeset<TReadModel>>, signal: AbortSignal, _lifecycle?: ConnectionLifecycle | undefined, options?: ReadModelWatchOptions);
+    get subscribed(): Promise<void>;
+    onResubscribed(callback: () => void | Promise<void>): () => void;
+    [Symbol.asyncIterator](): AsyncIterableIterator<ReadModelChangeset<TReadModel>>;
+    next(): Promise<IteratorResult<ReadModelChangeset<TReadModel>>>;
+    return(): Promise<IteratorResult<ReadModelChangeset<TReadModel>>>;
+    dispose(): void;
+    private resetReadiness;
+    private start;
+    private disconnect;
+    private shouldResume;
+    private restart;
+    private clearRestartTimer;
+    private cancelStream;
+    private resumeReading;
+    private waitForCapacity;
+    private read;
+    private deliver;
+    private notifyResubscribed;
+    private finish;
+}
+//# sourceMappingURL=ReadModelWatcher.d.ts.map

package/dist/readModels/ReadModelWatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadModelWatcher.d.ts","sourceRoot":"","sources":["../../readModels/ReadModelWatcher.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,IAAI,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAC3F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAChF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAExE,uEAAuE;AACvE,qBAAa,gBAAgB,CAAC,UAAU,CAAE,YAAW,iBAAiB,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC;IA2BjI,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAEzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IA7BhC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAQ;IAC/C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,cAAc,CAAC,CAAa;IAEpC,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,kBAAkB,CAAc;IACxC,OAAO,CAAC,iBAAiB,CAA4B;IACrD,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyC;IACzE,OAAO,CAAC,WAAW,CAAC,CAAkB;IACtC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,CAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE,OAAO,CAAC,aAAa,CAAC,CAAgC;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAGhB;IACT,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IAEnD,YACqB,KAAK,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,aAAa,CAAC,iBAAiB,CAAC,EAChE,QAAQ,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,OAAO,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC,EACjG,MAAM,EAAE,WAAW,EACF,UAAU,CAAC,EAAE,mBAAmB,YAAA,EACjD,OAAO,GAAE,qBAA0B,EA2BtC;IAED,IAAI,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAE9B;IAED,cAAc,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAI/D;IAED,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,qBAAqB,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC,CAE9E;IAED,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC,CAAC,CAS9D;IAEK,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC,CAAC,CAGtE;IAED,OAAO,IAAI,IAAI,CAGd;IAED,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,KAAK;IAQb,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,OAAO;IAYf,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,eAAe;YAST,IAAI;YAyCJ,OAAO;YA0BP,kBAAkB;IAYhC,OAAO,CAAC,MAAM;CAiBjB"}

package/dist/readModels/ReadModelWatcher.js

@@ -0,0 +1,276 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/** @internal Owns one cancellable stream per connection generation. */
+export class ReadModelWatcher {
+    _open;
+    _convert;
+    _lifecycle;
+    static _restartDelayMs = 1000;
+    _bufferLimit;
+    _failOnOverflow;
+    _resume;
+    _resumeReading;
+    _subscribed;
+    _resolveSubscribed;
+    _rejectSubscribed;
+    _acknowledged = false;
+    _hasSubscribed = false;
+    _delivery = Promise.resolve();
+    _onResubscribed = new Set();
+    _controller;
+    _stopped = false;
+    _failed = false;
+    _failure;
+    _buffered = [];
+    _restartTimer;
+    _waiting = [];
+    _unsubscribe = [];
+    constructor(_open, _convert, signal, _lifecycle, options = {}) {
+        this._open = _open;
+        this._convert = _convert;
+        this._lifecycle = _lifecycle;
+        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() {
+        return this._subscribed;
+    }
+    onResubscribed(callback) {
+        if (this._stopped)
+            return () => { };
+        this._onResubscribed.add(callback);
+        return () => { this._onResubscribed.delete(callback); };
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    next() {
+        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() {
+        this.dispose();
+        return { done: true, value: undefined };
+    }
+    dispose() {
+        this._buffered.length = 0;
+        this.finish(new DOMException('Read model watcher disposed.', 'AbortError'), false);
+    }
+    resetReadiness() {
+        this._acknowledged = false;
+        this._subscribed = new Promise((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(() => { });
+    }
+    start() {
+        if (this._stopped || this._controller)
+            return;
+        this.clearRestartTimer();
+        const controller = new AbortController();
+        this._controller = controller;
+        void this.read(controller);
+    }
+    disconnect() {
+        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();
+    }
+    shouldResume() {
+        return this._resume || this._onResubscribed.size > 0;
+    }
+    restart() {
+        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?.();
+    }
+    clearRestartTimer() {
+        clearTimeout(this._restartTimer);
+        this._restartTimer = undefined;
+    }
+    cancelStream() {
+        const controller = this._controller;
+        this._controller = undefined;
+        controller?.abort();
+        this.resumeReading();
+    }
+    resumeReading() {
+        this._resumeReading?.();
+        this._resumeReading = undefined;
+    }
+    waitForCapacity(controller) {
+        if (this._controller === controller && this._acknowledged && !this._failOnOverflow &&
+            this._buffered.length >= this._bufferLimit) {
+            return new Promise(resolve => { this._resumeReading = resolve; })
+                .then(() => this.waitForCapacity(controller));
+        }
+        return undefined;
+    }
+    async read(controller) {
+        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?.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);
+        }
+    }
+    async deliver(change) {
+        if (this._stopped)
+            return;
+        let converted;
+        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);
+        }
+    }
+    async notifyResubscribed(callbacks) {
+        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);
+        }
+    }
+    finish(reason, failed, preserveBuffered = false) {
+        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 });
+        }
+    }
+}
+//# sourceMappingURL=ReadModelWatcher.js.map

package/dist/readModels/ReadModelWatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadModelWatcher.js","sourceRoot":"","sources":["../../readModels/ReadModelWatcher.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAQrG,uEAAuE;AACvE,MAAM,OAAO,gBAAgB;IA2BJ,KAAK;IACL,QAAQ;IAER,UAAU;IA7BvB,MAAM,CAAU,eAAe,GAAG,IAAI,CAAC;IAC9B,YAAY,CAAS;IACrB,eAAe,CAAU;IACzB,OAAO,CAAU;IAC1B,cAAc,CAAc;IAE5B,WAAW,CAAiB;IAC5B,kBAAkB,CAAc;IAChC,iBAAiB,CAA4B;IAC7C,aAAa,GAAG,KAAK,CAAC;IACtB,cAAc,GAAG,KAAK,CAAC;IACvB,SAAS,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IACrB,eAAe,GAAG,IAAI,GAAG,EAA8B,CAAC;IACjE,WAAW,CAAmB;IAC9B,QAAQ,GAAG,KAAK,CAAC;IACjB,OAAO,GAAG,KAAK,CAAC;IAChB,QAAQ,CAAW;IACV,SAAS,GAAqC,EAAE,CAAC;IAC1D,aAAa,CAAiC;IACrC,QAAQ,GAGnB,EAAE,CAAC;IACQ,YAAY,GAAmB,EAAE,CAAC;IAEnD,YACqB,KAAgE,EAChE,QAAgF,EACjG,MAAmB,EACF,UAAgC,EACjD,OAAO,GAA0B,EAAE;qBAJlB,KAAK;wBACL,QAAQ;0BAER,UAAU;QAG3B,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,WAAW,GAAG,CAAC,CAAC,EAAE,CAAC;YAC/G,MAAM,IAAI,UAAU,CAAC,8CAA8C,CAAC,CAAC;QACzE,CAAC;QACD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC;QAChD,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC;QACzD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC;QACvC,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACtD,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;QACzE,IAAI,UAAU,EAAE,CAAC;YACb,+EAA+E;YAC/E,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,KAAK,IAAI,EAAE;gBACxD,IAAI,IAAI,CAAC,YAAY,EAAE;oBAAE,IAAI,CAAC,UAAU,EAAE,CAAC;YAC/C,CAAC,CAAC,CAAC,CAAC;YACJ,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACzE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,EAAC,KAAK,EAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;QAC/F,CAAC;QACD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACjB,KAAK,EAAE,CAAC;QACZ,CAAC;aAAM,IAAI,UAAU,EAAE,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QAChD,CAAC;aAAM,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,WAAW,EAAE,CAAC;YAC/C,IAAI,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;IACL,CAAC;IAED,IAAI,UAAU;QACV,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;IAED,cAAc,CAAC,QAAoC;QAC/C,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;QACnC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACnC,OAAO,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,CAAC,MAAM,CAAC,aAAa,CAAC;QAClB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,IAAI;QACA,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACrC,IAAI,KAAK,EAAE,CAAC;YACR,IAAI,CAAC,aAAa,EAAE,CAAC;YACrB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QACnD,CAAC;QACD,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvD,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QAC5E,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IACrF,CAAC;IAED,KAAK,CAAC,MAAM;QACR,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAC5C,CAAC;IAED,OAAO;QACH,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,8BAA8B,EAAE,YAAY,CAAC,EAAE,KAAK,CAAC,CAAC;IACvF,CAAC;IAEO,cAAc;QAClB,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;QAC3B,IAAI,CAAC,WAAW,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrD,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC;YAClC,IAAI,CAAC,iBAAiB,GAAG,MAAM,CAAC;QACpC,CAAC,CAAC,CAAC;QACH,iFAAiF;QACjF,sFAAsF;QACtF,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACrC,CAAC;IAEO,KAAK;QACT,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,WAAW;YAAE,OAAO;QAC9C,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC;QAC9B,KAAK,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC/B,CAAC;IAEO,UAAU;QACd,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,gFAAgF;QAChF,IAAI,IAAI,CAAC,aAAa;YAAE,IAAI,CAAC,cAAc,EAAE,CAAC;IAClD,CAAC;IAEO,YAAY;QAChB,OAAO,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,eAAe,CAAC,IAAI,GAAG,CAAC,CAAC;IACzD,CAAC;IAEO,OAAO;QACX,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;YAAE,OAAO;QAC/E,4EAA4E;QAC5E,6EAA6E;QAC7E,IAAI,CAAC,aAAa,GAAG,UAAU,CAAC,GAAG,EAAE;YACjC,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;YAC/B,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC,WAAW;gBAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QACtE,CAAC,EAAE,gBAAgB,CAAC,eAAe,CAAC,CAAC;QACrC,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,EAAE,CAAC;IACjC,CAAC;IAEO,iBAAiB;QACrB,YAAY,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QACjC,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;IACnC,CAAC;IAEO,YAAY;QAChB,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;QAC7B,UAAU,EAAE,KAAK,EAAE,CAAC;QACpB,IAAI,CAAC,aAAa,EAAE,CAAC;IACzB,CAAC;IAEO,aAAa;QACjB,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;QACxB,IAAI,CAAC,cAAc,GAAG,SAAS,CAAC;IACpC,CAAC;IAEO,eAAe,CAAC,UAA2B;QAC/C,IAAI,IAAI,CAAC,WAAW,KAAK,UAAU,IAAI,IAAI,CAAC,aAAa,IAAI,CAAC,IAAI,CAAC,eAAe;YAC9E,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC7C,OAAO,IAAI,OAAO,CAAO,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;iBAClE,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC;QACtD,CAAC;QACD,OAAO,SAAS,CAAC;IACrB,CAAC;IAEO,KAAK,CAAC,IAAI,CAAC,UAA2B;QAC1C,IAAI,CAAC;YACD,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBACvD,IAAI,IAAI,CAAC,WAAW,KAAK,UAAU;oBAAE,OAAO;gBAC5C,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;oBACpB,IAAI,IAAI,CAAC,aAAa;wBAAE,SAAS;oBACjC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;oBAC1B,IAAI,CAAC,kBAAkB,EAAE,CAAC;oBAC1B,MAAM,YAAY,GAAG,IAAI,CAAC,cAAc,CAAC;oBACzC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;oBAC3B,IAAI,YAAY,EAAE,CAAC;wBACf,MAAM,SAAS,GAAG,CAAC,GAAG,IAAI,CAAC,eAAe,CAAC,CAAC;wBAC5C,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC;wBAC/E,MAAM,IAAI,CAAC,SAAS,CAAC;oBACzB,CAAC;oBACD,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC;oBAClD,IAAI,QAAQ;wBAAE,MAAM,QAAQ,CAAC;oBAC7B,IAAI,IAAI,CAAC,WAAW,KAAK,UAAU;wBAAE,OAAO;oBAC5C,SAAS;gBACb,CAAC;gBACD,gFAAgF;gBAChF,yEAAyE;gBACzE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;gBACjE,MAAM,IAAI,CAAC,SAAS,CAAC;gBACrB,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC;gBAClD,IAAI,QAAQ;oBAAE,MAAM,QAAQ,CAAC;gBAC7B,IAAI,IAAI,CAAC,WAAW,KAAK,UAAU;oBAAE,OAAO;YAChD,CAAC;YACD,IAAI,IAAI,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;gBAClC,IAAI,IAAI,CAAC,YAAY,EAAE;oBAAE,IAAI,CAAC,OAAO,EAAE,CAAC;;oBACnC,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,4DAA4D,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;YAC3G,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,IAAI,IAAI,CAAC,WAAW,KAAK,UAAU;gBAAE,OAAO;YAC5C,MAAM,IAAI,GAAI,KAA2B,EAAE,IAAI,CAAC;YAChD,IAAI,IAAI,CAAC,YAAY,EAAE,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,IAAI,CAAC,OAAO,EAAE,CAAC;YAC/F,sFAAsF;;gBACjF,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACxC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,OAAO,CAAC,MAAyB;QAC3C,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,SAAyC,CAAC;QAC9C,IAAI,CAAC;YACD,SAAS,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC5C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,wEAAwE;YACxE,6DAA6D;YAC7D,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YACzB,OAAO;QACX,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtC,IAAI,OAAO,EAAE,CAAC;YACV,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QACvD,CAAC;aAAM,CAAC;YACJ,wEAAwE;YACxE,gFAAgF;YAChF,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;gBAC7C,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,sCAAsC,IAAI,CAAC,YAAY,sFAAsF,CAAC,EAAE,IAAI,CAAC,CAAC;gBAC5K,OAAO;YACX,CAAC;YACD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACnC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,kBAAkB,CAAC,SAAyC;QACtE,IAAI,CAAC;YACD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;gBAC/B,IAAI,IAAI,CAAC,QAAQ;oBAAE,OAAO;gBAC1B,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC;oBAAE,MAAM,QAAQ,EAAE,CAAC;YAC7D,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,8EAA8E;YAC9E,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC7B,CAAC;IACL,CAAC;IAEO,MAAM,CAAC,MAAe,EAAE,MAAe,EAAE,gBAAgB,GAAG,KAAK;QACrE,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC;QACvB,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,IAAI,CAAC,gBAAgB;YAAE,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;QACjD,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,YAAY;YAAE,WAAW,EAAE,CAAC;QAC3D,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAC7B,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5C,IAAI,MAAM;gBAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;;gBAC9B,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QAC3D,CAAC;IACL,CAAC;CACJ"}

package/dist/readModels/ReadModels.d.ts

@@ -1,10 +1,13 @@
 import type { Constructor } from '@cratis/fundamentals';
 import { IClientArtifactsProvider } from '../artifacts/index.js';
 import { ChronicleConnection } from '../connection/index.js';
+import type { ConnectionLifecycle } from '../connection/ConnectionLifecycle.js';
 import type { IMaterializedReadModels } from './IMaterializedReadModels.js';
 import type { ReadModelNamingPolicy } from './ReadModelNamingPolicy.js';
 import type { IReadModels } from './IReadModels.js';
+import type { IReadModelWatcher } from './IReadModelWatcher.js';
 import type { ReadModelChangeset } from './ReadModelChangeset.js';
+import type { ReadModelWatchOptions } from './ReadModelWatchOptions.js';
 import type { ReadModelSnapshot } from './ReadModelSnapshot.js';
 /**
  * Implements {@link IReadModels} by working with the Chronicle read-model gRPC service.
@@ -17,8 +20,10 @@ export declare class ReadModels implements IReadModels {
     private readonly _defaultSinkTypeId;
     private readonly _isModelBoundProjectionRegistered?;
     private readonly _readModelNamingPolicy?;
+    private readonly _lifecycle?;
     readonly materialized: IMaterializedReadModels;
-    constructor(_eventStore: string, _namespace: string, _connection: ChronicleConnection, _clientArtifacts: IClientArtifactsProvider, _defaultSinkTypeId: string, _isModelBoundProjectionRegistered?: ((readModelType: Constructor) => boolean) | undefined, _readModelNamingPolicy?: ReadModelNamingPolicy | undefined);
+    private readonly _watchCancellation;
+    constructor(_eventStore: string, _namespace: string, _connection: ChronicleConnection, _clientArtifacts: IClientArtifactsProvider, _defaultSinkTypeId: string, _isModelBoundProjectionRegistered?: ((readModelType: Constructor) => boolean) | undefined, _readModelNamingPolicy?: ReadModelNamingPolicy | undefined, _lifecycle?: ConnectionLifecycle | undefined);
     /** @inheritdoc */
     register<TReadModel>(readModelType?: Constructor<TReadModel>): Promise<void>;
     /** @inheritdoc */
@@ -32,6 +37,10 @@ export declare class ReadModels implements IReadModels {
     /** @inheritdoc */
     watch<TReadModel>(readModelType: Constructor<TReadModel>): AsyncIterable<ReadModelChangeset<TReadModel>>;
     /** @inheritdoc */
+    createWatcher<TReadModel>(readModelType: Constructor<TReadModel>, options?: ReadModelWatchOptions): IReadModelWatcher<TReadModel>;
+    /** Stops all watchers created through createWatcher for this event store. */
+    dispose(): void;
+    /** @inheritdoc */
     dehydrateSession<TReadModel>(sessionId: string, readModelType: Constructor<TReadModel>, key: string): Promise<void>;
     /** @inheritdoc */
     release<TReadModel>(readModelType: Constructor<TReadModel>, instance: TReadModel): Promise<TReadModel>;
@@ -43,6 +52,7 @@ export declare class ReadModels implements IReadModels {
     private copyStoredDocument;
     private isDocumentObject;
     private isDocumentSubject;
+    private toChangeset;
     private releaseSnapshotInstances;
     private resolveReadModels;
     private addResolved;

package/dist/readModels/ReadModels.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReadModels.d.ts","sourceRoot":"","sources":["../../readModels/ReadModels.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ReadModels.d.ts","sourceRoot":"","sources":["../../readModels/ReadModels.ts"],"names":[],"mappings":"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"}

package/dist/readModels/ReadModels.js

@@ -1,7 +1,8 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
-import { ReadModelObserverType as ContractReadModelObserverType } from '@cratis/chronicle.contracts';
+import { ReadModelObserverType as ContractReadModelObserverType, ReadModelChangeType as ContractReadModelChangeType } from '@cratis/chronicle.contracts';
 import { JsonSerializer } from '@cratis/fundamentals';
+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';
@@ -18,6 +19,8 @@ import { rootReadModelTypes } from './rootReadModelTypes.js';
 import { MaterializedReadModels } from './MaterializedReadModels.js';
 import { ReadModelSubjectResolver } from './ReadModelSubjectResolver.js';
 import { deserializeReadModel } from './deserializeReadModel.js';
+import { ReadModelWatcher } from './ReadModelWatcher.js';
+import { ReadModelChangeType } from './ReadModelChangeType.js';
 const unlimitedEventCount = BigInt('18446744073709551615');
 /**
  * Implements {@link IReadModels} by working with the Chronicle read-model gRPC service.
@@ -30,8 +33,10 @@ export class ReadModels {
     _defaultSinkTypeId;
     _isModelBoundProjectionRegistered;
     _readModelNamingPolicy;
+    _lifecycle;
     materialized;
-    constructor(_eventStore, _namespace, _connection, _clientArtifacts, _defaultSinkTypeId, _isModelBoundProjectionRegistered, _readModelNamingPolicy) {
+    _watchCancellation = new AbortController();
+    constructor(_eventStore, _namespace, _connection, _clientArtifacts, _defaultSinkTypeId, _isModelBoundProjectionRegistered, _readModelNamingPolicy, _lifecycle) {
         this._eventStore = _eventStore;
         this._namespace = _namespace;
         this._connection = _connection;
@@ -39,6 +44,7 @@ export class ReadModels {
         this._defaultSinkTypeId = _defaultSinkTypeId;
         this._isModelBoundProjectionRegistered = _isModelBoundProjectionRegistered;
         this._readModelNamingPolicy = _readModelNamingPolicy;
+        this._lifecycle = _lifecycle;
         this.materialized = new MaterializedReadModels(_eventStore, _namespace, _connection);
     }
     /** @inheritdoc */
@@ -141,18 +147,27 @@ export class ReadModels {
             if (changeset.Subscribed) {
                 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(readModelType, options) {
+        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() {
+        this._watchCancellation.abort();
+    }
+    /** @inheritdoc */
     async dehydrateSession(sessionId, readModelType, key) {
         const readModel = this.resolveReadModel(readModelType);
         await this._connection.readModels.dehydrateSession({
@@ -297,6 +312,27 @@ export class ReadModels {
     isDocumentSubject(value) {
         return typeof value === 'string' && value.length > 0;
     }
+    async toChangeset(readModelType, readModel, changeset) {
+        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
+            }
+        };
+    }
     async releaseSnapshotInstances(readModelType, snapshots) {
         return Promise.all(snapshots.map(async (snapshot) => ({
             ...snapshot,