actor-ts 0.9.0

package/dist/testkit/ParallelMultiNodeSpec.js

@@ -0,0 +1,310 @@
+import { NodeAddress } from '../cluster/NodeAddress.js';
+import { LogLevel } from '../Logger.js';
+import { getWorkerBackend } from '../runtime/worker/index.js';
+import { MultiNodeBroker } from './internal/MultiNodeBroker.js';
+let nextPortBase = 30_500; // disjoint from MultiNodeSpec's 30_000
+export class ParallelMultiNodeSpec {
+    settings;
+    nodes = new Map();
+    broker = new MultiNodeBroker();
+    started = false;
+    nextReqId = 1;
+    /** Pending RPC promises keyed by reqId. */
+    pending = new Map();
+    constructor(settings) {
+        if (settings.roles.length === 0) {
+            throw new Error('ParallelMultiNodeSpec: at least one role is required');
+        }
+        if (new Set(settings.roles).size !== settings.roles.length) {
+            throw new Error('ParallelMultiNodeSpec: roles must be unique');
+        }
+        this.settings = {
+            roles: settings.roles,
+            seedRoles: settings.seedRoles ?? [settings.roles[0]],
+            gossipIntervalMs: settings.gossipIntervalMs ?? 100,
+            awaitTimeoutMs: settings.awaitTimeoutMs ?? 15_000,
+            logLevel: settings.logLevel ?? LogLevel.Off,
+            addresses: settings.addresses,
+            failureDetector: settings.failureDetector,
+            scenarioModule: settings.scenarioModule,
+            scenarioInitDataFor: settings.scenarioInitDataFor,
+            bootstrapModule: settings.bootstrapModule,
+        };
+    }
+    /* ---------------------------- lifecycle --------------------------- */
+    async start() {
+        if (this.started)
+            throw new Error('ParallelMultiNodeSpec: already started');
+        this.started = true;
+        const portBase = nextPortBase;
+        nextPortBase += this.settings.roles.length + 1;
+        const addressByRole = new Map();
+        this.settings.roles.forEach((role, idx) => {
+            const explicit = this.settings.addresses?.[role];
+            const host = explicit?.host ?? '127.0.0.1';
+            const port = explicit?.port ?? (portBase + idx);
+            addressByRole.set(role, new NodeAddress(role, host, port));
+        });
+        const seeds = this.settings.seedRoles
+            .map((r) => addressByRole.get(r).toString());
+        const orderedRoles = [
+            ...this.settings.seedRoles,
+            ...this.settings.roles.filter((r) => !this.settings.seedRoles.includes(r)),
+        ];
+        for (const role of orderedRoles) {
+            const address = addressByRole.get(role);
+            const handle = await this.spawnRole(role, address, seeds);
+            this.nodes.set(role, handle);
+        }
+    }
+    async stop() {
+        const errs = [];
+        for (const node of this.nodes.values()) {
+            if (node.removed)
+                continue;
+            try {
+                node.worker?.terminate();
+            }
+            catch (e) {
+                errs.push(e);
+            }
+        }
+        this.broker.close();
+        this.nodes.clear();
+        this.started = false;
+        // Reject any in-flight RPCs.
+        for (const p of this.pending.values()) {
+            clearTimeout(p.timer);
+            p.reject(new Error('ParallelMultiNodeSpec: stopped'));
+        }
+        this.pending.clear();
+        if (errs.length > 0) {
+            // eslint-disable-next-line no-console
+            console.warn(`ParallelMultiNodeSpec.stop ran into ${errs.length} error(s):`, errs.map((e) => e.message));
+        }
+    }
+    async crash(role) {
+        const node = this.requireNode(role);
+        if (node.removed)
+            return;
+        node.removed = true;
+        if (node.worker) {
+            try {
+                await node.worker.terminate();
+            }
+            catch { /* ignore */ }
+        }
+        if (node.port)
+            this.broker.unregister(node.address);
+        node.worker = null;
+        node.port = null;
+    }
+    async leave(role) {
+        const node = this.requireNode(role);
+        if (node.removed)
+            return;
+        node.removed = true;
+        try {
+            await this.controlRpc(node, { kind: 'mns-test.leave' });
+        }
+        catch { /* ignore — graceful leave is best-effort */ }
+        // After cluster.leave returns, the worker has closed its
+        // transport; we still have to terminate the worker process.
+        if (node.worker) {
+            try {
+                node.worker.terminate();
+            }
+            catch { /* ignore */ }
+        }
+        if (node.port)
+            this.broker.unregister(node.address);
+        node.worker = null;
+        node.port = null;
+    }
+    partition(roleA, roleB) {
+        this.broker.partition(this.requireNode(roleA).address, this.requireNode(roleB).address);
+    }
+    heal(roleA, roleB) {
+        this.broker.heal(this.requireNode(roleA).address, this.requireNode(roleB).address);
+    }
+    /* ---------------------------- accessors --------------------------- */
+    addressFor(role) { return this.requireNode(role).address; }
+    allRoles() { return Array.from(this.nodes.keys()); }
+    /** Async snapshot of the worker's view of cluster members. */
+    async getMembers(role) {
+        const node = this.requireNode(role);
+        const resp = await this.controlRpc(node, { kind: 'mns-test.query-members' });
+        return resp.members;
+    }
+    async getLeader(role) {
+        const node = this.requireNode(role);
+        const resp = await this.controlRpc(node, { kind: 'mns-test.query-leader' });
+        return resp.leader;
+    }
+    /** Invoke a scenario-defined command on the worker. */
+    async runIn(role, command, args = undefined) {
+        const node = this.requireNode(role);
+        const resp = await this.controlRpc(node, {
+            kind: 'mns-test.run-command', command, args,
+        });
+        if (resp.error)
+            throw new Error(`runIn(${role}, ${command}): ${resp.error}`);
+        return resp.result;
+    }
+    /* ---------------------------- await helpers --------------------------- */
+    async awaitMembers(role, expectedCount, timeoutMs = this.settings.awaitTimeoutMs) {
+        await this.awaitCondition(async () => {
+            const members = await this.getMembers(role);
+            return members.filter((m) => m.status === 'up').length === expectedCount;
+        }, `awaitMembers(${role}, expected=${expectedCount})`, timeoutMs);
+    }
+    async awaitMemberStatus(role, targetRole, status, timeoutMs = this.settings.awaitTimeoutMs) {
+        const targetAddr = this.requireNode(targetRole).address.toString();
+        await this.awaitCondition(async () => {
+            const members = await this.getMembers(role);
+            return members.find((m) => m.address === targetAddr)?.status === status;
+        }, `awaitMemberStatus(${role}, ${targetRole} → ${status})`, timeoutMs);
+    }
+    async awaitLeader(role, expectedLeaderRole, timeoutMs = this.settings.awaitTimeoutMs) {
+        const expectedAddr = expectedLeaderRole
+            ? this.requireNode(expectedLeaderRole).address.toString()
+            : null;
+        await this.awaitCondition(async () => (await this.getLeader(role)) === expectedAddr, `awaitLeader(${role}, expected=${expectedLeaderRole ?? 'null'})`, timeoutMs);
+    }
+    /* ----------------------------- internals ---------------------------- */
+    requireNode(role) {
+        const node = this.nodes.get(role);
+        if (!node)
+            throw new Error(`ParallelMultiNodeSpec: unknown role '${role}'`);
+        return node;
+    }
+    async awaitCondition(cond, description, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            try {
+                if (await cond())
+                    return;
+            }
+            catch { /* retry */ }
+            await new Promise((r) => setTimeout(r, 50));
+        }
+        throw new Error(`ParallelMultiNodeSpec: timeout after ${timeoutMs} ms — ${description}`);
+    }
+    /**
+     * Spawn one worker, do the WorkerNode handshake, register the
+     * worker-side port with the broker, and wire up the control
+     * channel so RPC responses flow back to `this.pending`.
+     */
+    async spawnRole(role, address, seeds) {
+        const backend = await getWorkerBackend();
+        const bootstrap = this.settings.bootstrapModule
+            ?? new URL('./internal/parallel-multi-node-bootstrap.js', import.meta.url);
+        const worker = backend.spawn(bootstrap, { name: `parallel-mns-${role}` });
+        const initData = {
+            role,
+            seeds,
+            failureDetector: this.settings.failureDetector,
+            gossipIntervalMs: this.settings.gossipIntervalMs,
+            logLevel: this.settings.logLevel,
+            scenarioModule: this.settings.scenarioModule?.toString(),
+            scenarioInitData: this.settings.scenarioInitDataFor?.(role),
+        };
+        const init = {
+            kind: 'worker-init',
+            self: address.toJSON(),
+            systemName: role,
+            data: initData,
+        };
+        // Hello/init/ready handshake — exactly mirrors WorkerCluster.
+        await this.handshake(worker, init, address);
+        // Wire the broker port — same shape as WorkerCluster.brokerFacade.
+        const port = this.brokerFacade(worker);
+        this.broker.register(address, port);
+        // Listen for control-channel responses on the worker's main
+        // postMessage stream.  Cluster transport frames are tagged
+        // `actor-ts.transport`; control frames are `mns-test.*`.
+        worker.addEventListener('message', (e) => {
+            const data = (e.data ?? undefined);
+            if (!data?.kind || !data.kind.startsWith('mns-test.'))
+                return;
+            const reqId = data.reqId;
+            const pending = reqId !== undefined ? this.pending.get(reqId) : undefined;
+            if (!pending)
+                return;
+            this.pending.delete(reqId);
+            clearTimeout(pending.timer);
+            pending.resolve(data);
+        });
+        return { role, address, worker, port, removed: false };
+    }
+    brokerFacade(worker) {
+        let handler = null;
+        worker.addEventListener('message', (e) => {
+            const msg = (e.data ?? undefined);
+            if (msg && msg.kind === 'worker-transport' && handler) {
+                handler({ data: msg.envelope });
+            }
+        });
+        return {
+            postMessage(v) {
+                const envelope = v;
+                const msg = { kind: 'worker-transport', envelope };
+                worker.postMessage(msg);
+            },
+            get onmessage() { return handler; },
+            set onmessage(h) { handler = h; },
+            close() { handler = null; },
+        };
+    }
+    handshake(worker, init, addr) {
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                worker.removeEventListener('message', onMessage);
+                reject(new Error(`Worker ${addr} did not become ready within 10s`));
+            }, 10_000);
+            const onMessage = (e) => {
+                const msg = (e.data ?? undefined);
+                if (!msg)
+                    return;
+                if (msg.kind === 'worker-hello') {
+                    const hello = msg;
+                    void hello;
+                    worker.postMessage(init);
+                }
+                else if (msg.kind === 'worker-ready') {
+                    const ready = msg;
+                    void ready;
+                    clearTimeout(timeout);
+                    worker.removeEventListener('message', onMessage);
+                    resolve();
+                }
+            };
+            worker.addEventListener('message', onMessage);
+        });
+    }
+    /**
+     * Send a control request to a worker and await its response.
+     * Times out after 5s — RPC failures usually indicate the worker
+     * is wedged; fast timeouts surface the issue rather than hanging
+     * the test forever.
+     */
+    controlRpc(node, request) {
+        if (!node.worker) {
+            return Promise.reject(new Error(`controlRpc: role '${node.role}' has been crashed/left`));
+        }
+        const reqId = this.nextReqId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(reqId);
+                reject(new Error(`controlRpc(${request.kind}): timed out after 5s`));
+            }, 5_000);
+            this.pending.set(reqId, {
+                resolve: (v) => resolve(v),
+                reject,
+                timer,
+            });
+            node.worker.postMessage({ ...request, reqId });
+        });
+    }
+}
+//# sourceMappingURL=ParallelMultiNodeSpec.js.map

package/dist/testkit/ParallelMultiNodeSpec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParallelMultiNodeSpec.js","sourceRoot":"","sources":["../../src/testkit/ParallelMultiNodeSpec.ts"],"names":[],"mappings":"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"}

package/dist/testkit/TestKit.d.ts

@@ -0,0 +1,40 @@
+import { ActorSystem, type ActorSystemSettings } from '../ActorSystem.js';
+import { ManualScheduler } from './ManualScheduler.js';
+import { TestProbe, type TestProbeOptions } from './TestProbe.js';
+export interface TestKitOptions extends ActorSystemSettings {
+    /** When true, install a NoopLogger if the caller didn't provide one. */
+    readonly quiet?: boolean;
+}
+/**
+ * Convenience fassade to create an ActorSystem pre-wired for deterministic
+ * testing: NoopLogger by default and a TestProbe factory handy.
+ *
+ * Typical usage:
+ *
+ *   const tk = TestKit.create('my-spec');
+ *   const probe = tk.createTestProbe();
+ *   const ref = tk.system.spawn(Props.create(() => new Worker(probe)), 'worker');
+ *   ref.tell('go');
+ *   await probe.expectMsg('done');
+ *   await tk.shutdown();
+ */
+export declare class TestKit {
+    readonly system: ActorSystem;
+    private constructor();
+    static create(name?: string, options?: TestKitOptions): TestKit;
+    /** Create a TestProbe scoped to this kit's system. */
+    createTestProbe(opts?: TestProbeOptions): TestProbe;
+    /** Run `fn` with a soft deadline; throws if it takes longer than `durationMs`. */
+    within<T>(durationMs: number, fn: () => Promise<T>): Promise<T>;
+    /** Tear the system down at the end of a test. */
+    shutdown(): Promise<void>;
+    /**
+     * Build a TestKit that uses a `ManualScheduler` so that timers fire
+     * deterministically via `scheduler.advance(ms)`.
+     */
+    static withManualScheduler(name?: string, options?: Omit<TestKitOptions, 'scheduler'>): {
+        kit: TestKit;
+        scheduler: ManualScheduler;
+    };
+}
+//# sourceMappingURL=TestKit.d.ts.map

package/dist/testkit/TestKit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestKit.d.ts","sourceRoot":"","sources":["../../src/testkit/TestKit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE1E,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElE,MAAM,WAAW,cAAe,SAAQ,mBAAmB;IACzD,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,OAAO;IAClB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B,OAAO;IAIP,MAAM,CAAC,MAAM,CAAC,IAAI,GAAE,MAAmB,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO;IAU/E,sDAAsD;IACtD,eAAe,CAAC,IAAI,GAAE,gBAAqB,GAAG,SAAS;IAIvD,kFAAkF;IAC5E,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAUrE,iDAAiD;IAC3C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B;;;OAGG;IACH,MAAM,CAAC,mBAAmB,CACxB,IAAI,GAAE,MAA0B,EAChC,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,WAAW,CAAM,GAC9C;QAAE,GAAG,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,eAAe,CAAA;KAAE;CAKhD"}

package/dist/testkit/TestKit.js

@@ -0,0 +1,60 @@
+import { ActorSystem } from '../ActorSystem.js';
+import { LogLevel, NoopLogger } from '../Logger.js';
+import { ManualScheduler } from './ManualScheduler.js';
+import { TestProbe } from './TestProbe.js';
+/**
+ * Convenience fassade to create an ActorSystem pre-wired for deterministic
+ * testing: NoopLogger by default and a TestProbe factory handy.
+ *
+ * Typical usage:
+ *
+ *   const tk = TestKit.create('my-spec');
+ *   const probe = tk.createTestProbe();
+ *   const ref = tk.system.spawn(Props.create(() => new Worker(probe)), 'worker');
+ *   ref.tell('go');
+ *   await probe.expectMsg('done');
+ *   await tk.shutdown();
+ */
+export class TestKit {
+    system;
+    constructor(system) {
+        this.system = system;
+    }
+    static create(name = 'test-kit', options = {}) {
+        const quiet = options.quiet ?? true;
+        const system = ActorSystem.create(name, {
+            ...options,
+            logger: options.logger ?? (quiet ? new NoopLogger() : undefined),
+            logLevel: options.logLevel ?? (quiet ? LogLevel.Off : undefined),
+        });
+        return new TestKit(system);
+    }
+    /** Create a TestProbe scoped to this kit's system. */
+    createTestProbe(opts = {}) {
+        return new TestProbe(this.system, opts);
+    }
+    /** Run `fn` with a soft deadline; throws if it takes longer than `durationMs`. */
+    async within(durationMs, fn) {
+        const started = Date.now();
+        const value = await fn();
+        const elapsed = Date.now() - started;
+        if (elapsed > durationMs) {
+            throw new Error(`within(${durationMs}ms) exceeded — actual ${elapsed}ms`);
+        }
+        return value;
+    }
+    /** Tear the system down at the end of a test. */
+    async shutdown() {
+        await this.system.terminate();
+    }
+    /**
+     * Build a TestKit that uses a `ManualScheduler` so that timers fire
+     * deterministically via `scheduler.advance(ms)`.
+     */
+    static withManualScheduler(name = 'test-kit-manual', options = {}) {
+        const scheduler = new ManualScheduler();
+        const kit = TestKit.create(name, { ...options, scheduler });
+        return { kit, scheduler };
+    }
+}
+//# sourceMappingURL=TestKit.js.map

package/dist/testkit/TestKit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestKit.js","sourceRoot":"","sources":["../../src/testkit/TestKit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAA4B,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAyB,MAAM,gBAAgB,CAAC;AAOlE;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,OAAO;IACT,MAAM,CAAc;IAE7B,YAAoB,MAAmB;QACrC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,MAAM,CAAC,MAAM,CAAC,OAAe,UAAU,EAAE,UAA0B,EAAE;QACnE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC;QACpC,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,IAAI,EAAE;YACtC,GAAG,OAAO;YACV,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;YAChE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;SACjE,CAAC,CAAC;QACH,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IAED,sDAAsD;IACtD,eAAe,CAAC,OAAyB,EAAE;QACzC,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC1C,CAAC;IAED,kFAAkF;IAClF,KAAK,CAAC,MAAM,CAAI,UAAkB,EAAE,EAAoB;QACtD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,MAAM,EAAE,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC;QACrC,IAAI,OAAO,GAAG,UAAU,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,UAAU,UAAU,yBAAyB,OAAO,IAAI,CAAC,CAAC;QAC5E,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,iDAAiD;IACjD,KAAK,CAAC,QAAQ;QACZ,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;IAChC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,mBAAmB,CACxB,OAAe,iBAAiB,EAChC,UAA6C,EAAE;QAE/C,MAAM,SAAS,GAAG,IAAI,eAAe,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;QAC5D,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;IAC5B,CAAC;CACF"}

package/dist/testkit/TestProbe.d.ts

@@ -0,0 +1,56 @@
+import { ActorPath } from '../ActorPath.js';
+import { ActorRef } from '../ActorRef.js';
+import type { ActorSystem } from '../ActorSystem.js';
+export interface TestProbeOptions {
+    /** Default timeout used when a caller doesn't specify one. */
+    readonly defaultTimeoutMs?: number;
+    /** Visible name of the probe (default: auto-generated). */
+    readonly name?: string;
+}
+interface Pending {
+    readonly message: unknown;
+    readonly sender: ActorRef | null;
+}
+/**
+ * A lightweight ActorRef that captures every `tell` for inspection by tests.
+ * Unlike an ordinary actor it is synchronous and not driven by the dispatcher —
+ * messages sit in an internal queue until a test asserts on them.
+ */
+export declare class TestProbe extends ActorRef<unknown> {
+    private readonly system;
+    readonly path: ActorPath;
+    private readonly queue;
+    /** Parked resolvers when a caller is waiting for the next message. */
+    private readonly waiters;
+    private readonly defaultTimeoutMs;
+    private _lastSender;
+    constructor(system: ActorSystem, opts?: TestProbeOptions);
+    tell(message: unknown, sender?: ActorRef | null): void;
+    /** Number of messages currently buffered. */
+    get messageCount(): number;
+    /** True when there is at least one buffered message waiting to be consumed. */
+    hasMessage(): boolean;
+    /** The sender of the LAST message consumed via expect* / receive*. */
+    get sender(): ActorRef | null;
+    /** Convenience: reply to the last sender (throws if there is none). */
+    reply(message: unknown): void;
+    /** Clear all buffered messages — handy between test phases. */
+    clearInbox(): void;
+    /** Wait for the next message and return it.  Throws on timeout. */
+    receiveOne(timeoutMs?: number): Promise<unknown>;
+    /** Receive the next `n` messages. */
+    receiveN(n: number, timeoutMs?: number): Promise<unknown[]>;
+    /** Assert the next message deep-equals `expected`. */
+    expectMsg<T>(expected: T, timeoutMs?: number): Promise<T>;
+    /** Assert the next message is an instance of `Class`. */
+    expectMsgType<T>(Class: new (...args: any[]) => T, timeoutMs?: number): Promise<T>;
+    /** Assert NO message arrives within the timeout. */
+    expectNoMessage(timeoutMs?: number): Promise<void>;
+    /** Receive messages until `pred` returns true.  Other messages are discarded. */
+    fishForMessage<T>(pred: (m: unknown) => boolean, timeoutMs?: number): Promise<T>;
+    private _next;
+    /** @internal — used by TestKit for diagnostics. */
+    _snapshot(): ReadonlyArray<Pending>;
+}
+export {};
+//# sourceMappingURL=TestProbe.d.ts.map

package/dist/testkit/TestProbe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestProbe.d.ts","sourceRoot":"","sources":["../../src/testkit/TestProbe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,OAAO;IACf,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAAC;CAClC;AAID;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,QAAQ,CAAC,OAAO,CAAC;IAclC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAbnC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAEzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAIhB;IAER,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,WAAW,CAAyB;gBAEf,MAAM,EAAE,WAAW,EAAE,IAAI,GAAE,gBAAqB;IAO7E,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,GAAE,QAAQ,GAAG,IAAW,GAAG,IAAI;IAY5D,6CAA6C;IAC7C,IAAI,YAAY,IAAI,MAAM,CAA8B;IAExD,+EAA+E;IAC/E,UAAU,IAAI,OAAO;IAErB,sEAAsE;IACtE,IAAI,MAAM,IAAI,QAAQ,GAAG,IAAI,CAA6B;IAE1D,uEAAuE;IACvE,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAK7B,+DAA+D;IAC/D,UAAU,IAAI,IAAI;IAIlB,mEAAmE;IAC7D,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAItD,qCAAqC;IAC/B,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAMjE,sDAAsD;IAChD,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAQ/D,yDAAyD;IACnD,aAAa,CAAC,CAAC,EACnB,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAChC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC;IAQb,oDAAoD;IAC9C,eAAe,CAAC,SAAS,GAAE,MAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B7D,iFAAiF;IAC3E,cAAc,CAAC,CAAC,EACpB,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,EAC7B,SAAS,GAAE,MAA8B,GACxC,OAAO,CAAC,CAAC,CAAC;IAWb,OAAO,CAAC,KAAK;IA0Bb,mDAAmD;IACnD,SAAS,IAAI,aAAa,CAAC,OAAO,CAAC;CACpC"}