@nanolink/mirrors 1.1.33 → 1.1.35

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,208 +1,269 @@
-# @nanolink/mirrors
-
-GraphQL subscription client + in‑memory mirror synchronization utilities. Optimized for incremental change streams that send START / UPDATED / DELETED / DONE / VERSION_ERROR frames.
-
-## Features
-* Lightweight `SubscriptionClient` around `graphql-ws` with explicit connect, controlled reconnect, and small event surface.
-* Dual version support in `MirrorSync` (`version` numeric + optional `opVersion` string) for hybrid sequence + causality ordering (either dimension can drive resync logic when present).
-* Stale delete & update guards: ignores events older in either version dimension to prevent resurrecting removed or outdated entities.
-* Efficient updates: UPDATED replaces item wholesale only when newer; no deep merge overhead.
-* Full sync cycle handling via START/DONE gates; `loaded` promise resolves after first DONE and re-arms on VERSION_ERROR.
-* Automatic resubscribe after reconnect using last known versions (no duplicate inserts).
-* Read‑only delegated map interface for consumers (prevents accidental mutation of internal state).
-* `Connection` helper manages multiple mirrors, re‑emitting namespaced events (`mirror:start`, `mirror:updated`, ...).
-* Proxy-aware WebSocket resolution: if proxy env vars are present (ALL_PROXY / HTTPS_PROXY / HTTP_PROXY / GLOBAL_AGENT_HTTP_PROXY) the client prefers the Node `ws` implementation; otherwise uses existing global WebSocket (browser / Node >=18) or falls back to `ws`.
-* Minimal dependencies; event system via `eventemitter3`.
-
-## Install
-```bash
-npm install @nanolink/mirrors
-```
-
-Optional (proxy via global-agent for generic HTTP(S) requests—WebSocket selection is still handled automatically as described):
-```js
-// enableProxy.js
-import 'global-agent/bootstrap';
-process.env.GLOBAL_AGENT_HTTP_PROXY = 'http://proxy:3128';
-```
-Run with:
-```bash
-node -r global-agent/bootstrap app.js
-```
-
-## Usage
-### Quick (multi‑mirror connection)
-```ts
-import { Connection } from '@nanolink/mirrors';
-
-const conn = new Connection('https://api.example.com', 'TOKEN');
-conn.connect();
-
-conn.on('connected', () => console.log('socket up'));
-conn.on('mirror:updated', e => console.log('updated', e.mirrorName, e.item.id));
-
-async function main() {
-  const users = await conn.getMirror('users', /* GraphQL subscription */ `
-    subscription Users($version: Long, $opVersion: String) {
-      users(version: $version, opVersion: $opVersion) {
-        type
-        total
-        deleteId
-        deleteVersion
-        deleteOpVersion
-        data { id version opVersion name }
-      }
-    }
-  `, {});
-
-  console.log('Initial size', users.size);
-  for (const user of users.values()) {
-    console.log(user);
-  }
-}
-main();
-```
-
-### Recommended: use `getPredefinedMirror()`
-```ts
-// preferred helper — uses predefined subscription templates from `src/definitions`
-const devices = await conn.getPredefinedMirror('trackers');
-await devices.loaded;
-console.log('Trackers count', devices.size);
-devices.on('updated', e => console.log('tracker updated', e.item.id));
-```
-
-### Direct low‑level client
-### Numeric‑only subscriptions (most common)
-Most Nanolink GraphQL subscription fields expose only a numeric `version` and omit `opVersion`. `MirrorSync` handles this seamlessly: pass just `$version` in the query and the server responses won’t include `opVersion` / `deleteOpVersion` fields.
-
-```ts
-// Numeric-only example
-const products = await conn.getMirror('products', `
-  subscription Products($version: Long) {
-    products(version: $version) {
-      type
-      total
-      deleteId
-      deleteVersion
-      data { id version title }
-    }
-  }
-`, {});
-
-await products.loaded; // after first DONE
-console.log('Products count', products.size);
-```
-
-When `opVersion` fields are absent they are simply ignored; ordering & stale protections rely on numeric `version` only.
-
-```ts
-import { SubscriptionClient } from '@nanolink/mirrors';
-
-const sc = new SubscriptionClient({ url: 'https://api.example.com', maxReconnectAttempts: 10 });
-sc.connect();
-sc.on('connected', () => {
-  const dispose = sc.subscribe({
-    query: 'subscription Ping { ping }'
-  }, {
-    next: (msg) => console.log(msg),
-    error: (e) => console.error('err', e),
-    complete: () => console.log('done')
-  });
-});
-```
-
-## Events
-`SubscriptionClient` emits:
-* connecting
-* connected (first successful connect)
-* reconnected (subsequent successful connect after a disconnect)
-* disconnected ({ code, reason, wasClean })
-* retry ({ attempt }) before a reconnect attempt delay
-* error (network/protocol)
-
-`Connection` re‑emits mirror events as `mirror:<event>` with payload `{ mirrorName, ... }`:
-* start
-* updated (only when a newer item actually replaced stored data)
-* deleted
-* done (end of full sync batch)
-* versionError (triggered resync)
-* resubscribe (automatic after reconnect)
-* error
-* removed (mirror explicitly removed)
-* cleared (mirror internal state cleared)
-
-## API Surface
-* `SubscriptionClient` – low level websocket subscription wrapper.
-* `MirrorSync` – single mirror controller (dual version tracking).
-* `Connection` – manages multiple mirrors + namespaced events.
-* `ReadonlyMapView` – immutable view returned by `getMirror()` / `MirrorSync.load()`.
-
-Note about mirror helpers
--------------------------
-`getMirror()` is available for custom ad-hoc mirrors but is seldom used in most integrations. The more commonly used helper is `getPredefinedMirror()` which returns mirrors for known server-side definitions (IDs and field payload shapes) and avoids having to supply the raw GraphQL subscription yourself. Check `src/definitions` for available predefined mirror names and subscription fragments.
-
-## Notes
-* Always call `connect()` explicitly; no implicit lazy connect.
-* VERSION_ERROR triggers automatic full resync (re-arms `loaded`).
-* First top-level field in GraphQL subscription payload is treated as the sync envelope.
-* Provide `webSocketImpl` manually if bundling for environments without a global WebSocket and you do NOT want `ws` as fallback.
-* When proxy env vars are set in Node, `SubscriptionClient` prefers `ws` (allowing external agent configuration); browsers ignore these env vars.
-
-## Build & Publish
-TypeScript sources compile to `dist/`.
-
-Scripts:
-```bash
-npm run build       # compile
-npm run publish:dry # preview publish contents
-npm run release     # build + publish (public)
-```
-
-Developer notes (recent refactor)
----------------------------------
-This repository recently split GraphQL subscription template literals into per-property modules to make maintenance easier:
-
-- Subscription templates: `src/definitions/subscriptions/*.ts` — one file per subscription property.
-- Shared fragments: `src/definitions/fragments.ts` — common fragment string constants used by the subscription files.
-- Compatibility surface: `src/definitions/mirrors.ts` now re-exports the assembled `Subscriptions`, `RequiredMirrors`, `TempSubscriptions`, and the fragment constants to preserve the original API.
-
-Packaging and what is published
---------------------------------
-- The npm package only ships the compiled build output. `package.json` lists `dist` and `dist-compat` in the `files` field, so the raw TypeScript source files under `src/` (including `src/definitions/subscriptions/*.ts`) are not included in the published package by default.
-- The TypeScript compiler emits JavaScript (to `dist`) and declaration files (`.d.ts`) when you run the build; those compiled artifacts are what go into the package.
-
-How to verify locally (PowerShell)
-----------------------------------
-1) Build the project:
-
-```powershell
-npm run build
-```
-
-2) Inspect the compiled `dist` tree to see the compiled outputs for the subscription modules:
-
-```powershell
-Get-ChildItem -Recurse .\dist | Select-Object FullName
-```
-
-3) See exactly what would be published (dry-run):
-
-```powershell
-npm pack --dry-run
-```
-
-If you want `.ts` sources included in the published package, add `src` to the `files` array in `package.json` or add a copy step that places sources in `dist`/`dist-compat` before publishing; then verify with `npm pack --dry-run`.
-
-## CI / GitHub Actions
-
-This repository includes a workflow that publishes the package to npm when changes are pushed to `main` and when a GitHub Release is published. The workflow expects a repository secret named `NPM_TOKEN` containing a valid npm automation token.
-
-To create and add the secret:
-1. Generate an npm token on https://www.npmjs.com/ under your account settings (Access Tokens -> Automation).
-2. In the GitHub repository, go to Settings → Secrets → Actions and add a new secret named `NPM_TOKEN` with the token value.
-
-The workflow builds both `dist` and `dist-compat` and then runs `npm publish --access public`. If you need to restrict publishing (for example, to skip on regular pushes), adjust the workflow triggers in `.github/workflows/publish.yml`.
-
-## License
-MIT
+# @nanolink/mirrors
+
+GraphQL subscription client + in‑memory mirror synchronization utilities. Optimized for incremental change streams that send START / UPDATED / DELETED / DONE / VERSION_ERROR frames.
+
+## Features
+* Lightweight `SubscriptionClient` around `graphql-ws` with explicit connect, controlled reconnect, and small event surface.
+* Dual version support in `MirrorSync` (`version` numeric + optional `opVersion` string) for hybrid sequence + causality ordering (either dimension can drive resync logic when present).
+* Stale delete & update guards: ignores events older in either version dimension to prevent resurrecting removed or outdated entities.
+* Efficient updates: UPDATED replaces item wholesale only when newer; no deep merge overhead.
+* Full sync cycle handling via START/DONE gates; `loaded` promise resolves after first DONE and re-arms on VERSION_ERROR.
+* Automatic resubscribe after reconnect using last known versions (no duplicate inserts).
+* Read‑only delegated map interface for consumers (prevents accidental mutation of internal state).
+* `Connection` helper manages multiple mirrors, re‑emitting namespaced events (`mirror:start`, `mirror:updated`, ...).
+* Proxy-aware WebSocket resolution: if proxy env vars are present (ALL_PROXY / HTTPS_PROXY / HTTP_PROXY / GLOBAL_AGENT_HTTP_PROXY) the client prefers the Node `ws` implementation; otherwise uses existing global WebSocket (browser / Node >=18) or falls back to `ws`.
+* Minimal dependencies; event system via `eventemitter3`.
+
+## Install
+```bash
+npm install @nanolink/mirrors
+```
+
+Optional (proxy via global-agent for generic HTTP(S) requests—WebSocket selection is still handled automatically as described):
+```js
+// enableProxy.js
+import 'global-agent/bootstrap';
+process.env.GLOBAL_AGENT_HTTP_PROXY = 'http://proxy:3128';
+```
+Run with:
+```bash
+node -r global-agent/bootstrap app.js
+```
+
+## Usage
+### What is a mirror?
+A mirror is an in-memory, read-only view of a server-side collection. The server sends GraphQL subscription frames with `START`, `UPDATED`, `DELETED`, `DONE`, and `VERSION_ERROR` messages; `MirrorSync` applies those messages to a local `Map` keyed by `id`.
+
+Each mirror tracks the latest cursor it has seen. Older subscriptions use numeric `version` / `deleteVersion`; newer subscriptions may use string `opVersion` / `deleteOpVersion`. `MirrorSync` supports both cursor styles and resubscribes from the latest known cursor after reconnect.
+
+`Connection` manages multiple named mirrors. It creates `MirrorSync` instances, stores them in `Connection.Mirrors`, and re-emits mirror events as `mirror:<event>` with the mirror name included.
+
+### Quick connection with a predefined mirror
+```ts
+import { Connection } from '@nanolink/mirrors';
+
+const conn = new Connection();
+
+conn.InitConnection('wss://api.example.com/ws', async () => ({
+  authToken: 'TOKEN',
+}));
+
+conn.on('connected', () => console.log('socket up'));
+conn.on('mirror:updated', e => console.log('updated', e.mirrorName, e.doc.id));
+
+conn.connect();
+
+async function main() {
+  const trackers = await conn.getPredefinedMirror('trackers');
+
+  console.log('Initial size', trackers.size);
+  for (const tracker of trackers.values()) {
+    console.log(tracker);
+  }
+}
+
+main();
+```
+
+### Custom mirror subscription
+```ts
+const users = await conn.getMirror('users', `
+    subscription Users($version: Long, $opVersion: String) {
+      users(version: $version, opVersion: $opVersion) {
+        type
+        total
+        deleteId
+        deleteVersion
+        deleteOpVersion
+        data { id version opVersion name }
+      }
+    }
+  `, {});
+
+console.log('Initial size', users.size);
+for (const user of users.values()) {
+  console.log(user);
+}
+```
+
+### Accessing the MirrorSync instance
+`getMirror()` and `getPredefinedMirror()` wait for the initial `DONE` frame and return a `ReadonlyMapView`. If you need mirror-specific events or stats, use `registerMirror()` directly.
+
+```ts
+const mirror = conn.registerMirror('users', usersSubscription, {});
+
+mirror.on('updated', e => console.log('user updated', e.doc.id));
+mirror.on('deleted', e => console.log('user deleted', e.orgDoc.id));
+
+const users = await mirror.load();
+console.log(mirror.stats(), users.size);
+```
+
+### Waiting for a specific mirror change
+Use `waitForUpdated()` or `waitForDeleted()` when a command or mutation must wait until the local mirror has observed the resulting server-side change. Create the wait promise before sending the command, then await it after the command completes.
+
+```ts
+const updated = mirror.waitForUpdated(referenceId);
+
+await saveReferenceMutation(referenceId);
+const { doc, orgDoc } = await updated;
+
+console.log('Mirror caught up', doc.id, orgDoc?.version, doc.version);
+```
+
+Both methods accept either an id or a predicate, and default to a 120 second timeout.
+
+```ts
+await mirror.waitForUpdated(
+  event => event.doc.externalIds?.some((id: any) => id.key === 'SAP_ID' && id.value === sapId),
+  { timeoutMs: 30_000 }
+);
+
+await mirror.waitForDeleted(referenceId);
+```
+
+### Numeric‑only subscriptions (most common)
+Most Nanolink GraphQL subscription fields expose only a numeric `version` and omit `opVersion`. `MirrorSync` handles this seamlessly: pass just `$version` in the query and the server responses won’t include `opVersion` / `deleteOpVersion` fields.
+
+```ts
+// Numeric-only example
+const products = await conn.getMirror('products', `
+  subscription Products($version: Long) {
+    products(version: $version) {
+      type
+      total
+      deleteId
+      deleteVersion
+      data { id version title }
+    }
+  }
+`, {});
+
+await products.loaded; // after first DONE
+console.log('Products count', products.size);
+```
+
+When `opVersion` fields are absent they are simply ignored; ordering & stale protections rely on numeric `version` only.
+
+### Direct low-level client
+```ts
+import { SubscriptionClient } from '@nanolink/mirrors';
+
+const sc = new SubscriptionClient();
+
+sc.InitClient({
+  url: 'wss://api.example.com/ws',
+  connectionParams: async () => ({ authToken: 'TOKEN' }),
+  maxReconnectAttempts: 10,
+});
+
+sc.connect();
+
+sc.on('connected', () => {
+  const dispose = sc.clientsubscribe({
+    query: 'subscription Ping { ping }'
+  }, {
+    next: (msg) => console.log(msg),
+    error: (e) => console.error('err', e),
+    complete: () => console.log('done')
+  });
+});
+```
+
+## Events
+`SubscriptionClient` emits:
+* connecting
+* connected (first successful connect)
+* reconnected (subsequent successful connect after a disconnect)
+* disconnected ({ code, reason, wasClean })
+* retry ({ attempt }) before a reconnect attempt delay
+* error (network/protocol)
+
+`Connection` re‑emits mirror events as `mirror:<event>` with payload `{ mirrorName, ... }`:
+* start
+* updated (only when a newer item actually replaced stored data)
+* deleted
+* done (end of full sync batch)
+* versionError (triggered resync)
+* resubscribe (automatic after reconnect)
+* error
+* removed (mirror explicitly removed)
+* cleared (mirror internal state cleared)
+
+## API Surface
+* `SubscriptionClient` – low level websocket subscription wrapper.
+* `MirrorSync` – single mirror controller (dual version tracking).
+* `Connection` – manages multiple named mirrors and re-emits namespaced mirror events.
+* `ReadonlyMapView` – read-only view returned by `getMirror()`, `getPredefinedMirror()`, and `MirrorSync.load()`.
+* `waitForUpdated()` / `waitForDeleted()` – wait until the mirror observes a specific future update or delete event.
+
+Note about mirror helpers
+-------------------------
+`getMirror()` is available for custom ad-hoc mirrors but is seldom used in most integrations. The more commonly used helper is `getPredefinedMirror()` which returns mirrors for known server-side definitions (IDs and field payload shapes) and avoids having to supply the raw GraphQL subscription yourself. Check `src/definitions` for available predefined mirror names and subscription fragments.
+
+## Notes
+* Always call `connect()` explicitly; no implicit lazy connect.
+* Call `InitConnection()` on `Connection`, or `InitClient()` on `SubscriptionClient`, before connecting.
+* VERSION_ERROR triggers automatic full resync (re-arms `loaded`).
+* First top-level field in GraphQL subscription payload is treated as the sync envelope.
+* Full sync updates are buffered until `DONE`, then swapped into the live mirror.
+* Provide `webSocketImpl` manually if bundling for environments without a global WebSocket and you do NOT want `ws` as fallback.
+* When proxy env vars are set in Node, `SubscriptionClient` prefers `ws` (allowing external agent configuration); browsers ignore these env vars.
+
+## Build & Publish
+TypeScript sources compile to `dist/`.
+
+Scripts:
+```bash
+npm run build       # compile
+npm run publish:dry # preview publish contents
+npm run release     # build + publish (public)
+```
+
+Developer notes (recent refactor)
+---------------------------------
+This repository recently split GraphQL subscription template literals into per-property modules to make maintenance easier:
+
+- Subscription templates: `src/definitions/subscriptions/*.ts` — one file per subscription property.
+- Shared fragments: `src/definitions/fragments.ts` — common fragment string constants used by the subscription files.
+- Compatibility surface: `src/definitions/mirrors.ts` now re-exports the assembled `Subscriptions`, `RequiredMirrors`, `TempSubscriptions`, and the fragment constants to preserve the original API.
+
+Packaging and what is published
+--------------------------------
+- The npm package only ships the compiled build output. `package.json` lists `dist` and `dist-compat` in the `files` field, so the raw TypeScript source files under `src/` (including `src/definitions/subscriptions/*.ts`) are not included in the published package by default.
+- The TypeScript compiler emits JavaScript (to `dist`) and declaration files (`.d.ts`) when you run the build; those compiled artifacts are what go into the package.
+
+How to verify locally (PowerShell)
+----------------------------------
+1) Build the project:
+
+```powershell
+npm run build
+```
+
+2) Inspect the compiled `dist` tree to see the compiled outputs for the subscription modules:
+
+```powershell
+Get-ChildItem -Recurse .\dist | Select-Object FullName
+```
+
+3) See exactly what would be published (dry-run):
+
+```powershell
+npm pack --dry-run
+```
+
+If you want `.ts` sources included in the published package, add `src` to the `files` array in `package.json` or add a copy step that places sources in `dist`/`dist-compat` before publishing; then verify with `npm pack --dry-run`.
+
+## CI / GitHub Actions
+
+This repository includes a workflow that publishes the package to npm when changes are pushed to `main` and when a GitHub Release is published. The workflow expects a repository secret named `NPM_TOKEN` containing a valid npm automation token.
+
+To create and add the secret:
+1. Generate an npm token on https://www.npmjs.com/ under your account settings (Access Tokens -> Automation).
+2. In the GitHub repository, go to Settings → Secrets → Actions and add a new secret named `NPM_TOKEN` with the token value.
+
+The workflow builds both `dist` and `dist-compat` and then runs `npm publish --access public`. If you need to restrict publishing (for example, to skip on regular pushes), adjust the workflow triggers in `.github/workflows/publish.yml`.
+
+## License
+MIT

package/dist/MirrorSync.d.ts

@@ -61,6 +61,19 @@ export interface MirrorItem {
     [k: string]: any;
     deleted?: boolean;
 }
+export interface MirrorUpdatedPayload {
+    doc: MirrorItem;
+    orgDoc: MirrorItem | undefined;
+    full: boolean;
+}
+export interface MirrorDeletedPayload {
+    orgDoc: MirrorItem;
+}
+export interface MirrorWaitOptions {
+    timeoutMs?: number;
+}
+export type MirrorUpdatedMatcher = string | ((payload: MirrorUpdatedPayload) => boolean);
+export type MirrorDeletedMatcher = string | ((payload: MirrorDeletedPayload) => boolean);
 /**
  * MirrorSync maintains an in-memory mirror of server state based on CacheSyncResult messages.
  * Generic TBase is the item shape (must include id & version).
@@ -98,6 +111,10 @@ export declare class MirrorSync extends EventEmitter {
     private resubscribe;
     private start;
     load(): Promise<ReadonlyMapView<string, any>>;
+    waitForUpdated(matcher: MirrorUpdatedMatcher, options?: MirrorWaitOptions): Promise<MirrorUpdatedPayload>;
+    waitForDeleted(matcher: MirrorDeletedMatcher, options?: MirrorWaitOptions): Promise<MirrorDeletedPayload>;
+    private waitForMirrorEvent;
+    private matchesMirrorEvent;
     private resetLoaded;
     private handlePayload;
     private handleVersionError;

package/dist/MirrorSync.js

@@ -123,6 +123,44 @@ class MirrorSync extends eventemitter3_1.default {
             this.start();
         return this.loaded;
     }
+    waitForUpdated(matcher, options) {
+        return this.waitForMirrorEvent('updated', matcher, options);
+    }
+    waitForDeleted(matcher, options) {
+        return this.waitForMirrorEvent('deleted', matcher, options);
+    }
+    waitForMirrorEvent(event, matcher, options) {
+        var _a;
+        const timeoutMs = (_a = options === null || options === void 0 ? void 0 : options.timeoutMs) !== null && _a !== void 0 ? _a : 120000;
+        return new Promise((resolve, reject) => {
+            let timeout;
+            const cleanup = () => {
+                this.off(event, handler);
+                if (timeout)
+                    clearTimeout(timeout);
+            };
+            const handler = (payload) => {
+                if (!this.matchesMirrorEvent(event, matcher, payload))
+                    return;
+                cleanup();
+                resolve(payload);
+            };
+            this.on(event, handler);
+            if (timeoutMs > 0) {
+                timeout = setTimeout(() => {
+                    cleanup();
+                    reject(new Error(`Timeout waiting for mirror ${event} event`));
+                }, timeoutMs);
+            }
+        });
+    }
+    matchesMirrorEvent(event, matcher, payload) {
+        if (typeof matcher === 'function')
+            return matcher(payload);
+        return event === 'updated'
+            ? payload.doc.id === matcher
+            : payload.orgDoc.id === matcher;
+    }
     resetLoaded() {
         this.loaded = new Promise(resolve => {
             this.resolveLoaded = resolve;