@syncular/testkit 0.0.2-135 → 0.0.2-137

package/dist/sync-http.js

@@ -1,3 +1,4 @@
+import { parseSyncCombinedResponse, parseSyncPullResponse, parseSyncPushResponse, } from './sync-parse.js';
 export function createJsonActorHeaders(options) {
     return {
         'content-type': 'application/json',
@@ -19,12 +20,24 @@ export async function postJsonWithActor(options) {
     return { response, json };
 }
 export async function postSyncCombinedRequest(options) {
-    return postJsonWithActor(options);
+    const result = await postJsonWithActor(options);
+    return {
+        response: result.response,
+        json: parseSyncCombinedResponse(result.json),
+    };
 }
 export async function postSyncPushRequest(options) {
-    return postJsonWithActor(options);
+    const result = await postJsonWithActor(options);
+    return {
+        response: result.response,
+        json: parseSyncPushResponse(result.json),
+    };
 }
 export async function postSyncPullRequest(options) {
-    return postJsonWithActor(options);
+    const result = await postJsonWithActor(options);
+    return {
+        response: result.response,
+        json: parseSyncPullResponse(result.json),
+    };
 }
 //# sourceMappingURL=sync-http.js.map

package/dist/sync-http.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync-http.js","sourceRoot":"","sources":["../src/sync-http.ts"],"names":[],"mappings":"AAeA,MAAM,UAAU,sBAAsB,CACpC,OAAgC,EACR;IACxB,OAAO;QACL,cAAc,EAAE,kBAAkB;QAClC,CAAC,OAAO,CAAC,WAAW,IAAI,YAAY,CAAC,EAAE,OAAO,CAAC,OAAO;QACtD,GAAG,OAAO,CAAC,YAAY;KACxB,CAAC;AAAA,CACH;AAgBD,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAwC,EACK;IAC7C,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE;QAChD,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,sBAAsB,CAAC;YAC9B,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,YAAY,EAAE,OAAO,CAAC,YAAY;SACnC,CAAC;QACF,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC;KACnC,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAc,CAAC;IAClD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAAA,CAC3B;AAWD,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAAuC,EACiB;IACxD,OAAO,iBAAiB,CAA4C,OAAO,CAAC,CAAC;AAAA,CAC9E;AAWD,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAmC,EACiB;IACpD,OAAO,iBAAiB,CAAoC,OAAO,CAAC,CAAC;AAAA,CACtE;AAWD,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAmC,EACiB;IACpD,OAAO,iBAAiB,CAAoC,OAAO,CAAC,CAAC;AAAA,CACtE"}
+{"version":3,"file":"sync-http.js","sourceRoot":"","sources":["../src/sync-http.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAQtB,MAAM,UAAU,sBAAsB,CACpC,OAAgC,EACR;IACxB,OAAO;QACL,cAAc,EAAE,kBAAkB;QAClC,CAAC,OAAO,CAAC,WAAW,IAAI,YAAY,CAAC,EAAE,OAAO,CAAC,OAAO;QACtD,GAAG,OAAO,CAAC,YAAY;KACxB,CAAC;AAAA,CACH;AAgBD,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAwC,EACK;IAC7C,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE;QAChD,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,sBAAsB,CAAC;YAC9B,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,YAAY,EAAE,OAAO,CAAC,YAAY;SACnC,CAAC;QACF,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC;KACnC,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAc,CAAC;IAClD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAAA,CAC3B;AAWD,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAAuC,EACiB;IACxD,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAA+B,OAAO,CAAC,CAAC;IAC9E,OAAO;QACL,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,IAAI,EAAE,yBAAyB,CAAC,MAAM,CAAC,IAAI,CAAC;KAC7C,CAAC;AAAA,CACH;AAWD,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAmC,EACiB;IACpD,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAA2B,OAAO,CAAC,CAAC;IAC1E,OAAO;QACL,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,IAAI,CAAC;KACzC,CAAC;AAAA,CACH;AAWD,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAmC,EACiB;IACpD,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAA2B,OAAO,CAAC,CAAC;IAC1E,OAAO;QACL,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,IAAI,CAAC;KACzC,CAAC;AAAA,CACH"}

package/dist/sync-parse.d.ts

@@ -0,0 +1,8 @@
+import { type SyncCombinedResponse, type SyncPullResponse, type SyncPushResponse } from '@syncular/core';
+export declare function parseSyncCombinedResponse(value: unknown): SyncCombinedResponse;
+export declare function parseSyncPushResponse(value: unknown): SyncPushResponse;
+export declare function parseSyncPullResponse(value: unknown): SyncPullResponse;
+export declare function readSyncCombinedResponse(response: Response): Promise<SyncCombinedResponse>;
+export declare function readSyncPushResponse(response: Response): Promise<SyncPushResponse>;
+export declare function readSyncPullResponse(response: Response): Promise<SyncPullResponse>;
+//# sourceMappingURL=sync-parse.d.ts.map

package/dist/sync-parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-parse.d.ts","sourceRoot":"","sources":["../src/sync-parse.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,oBAAoB,EAEzB,KAAK,gBAAgB,EAErB,KAAK,gBAAgB,EAEtB,MAAM,gBAAgB,CAAC;AA0CxB,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,GACb,oBAAoB,CAItB;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAItE;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAItE;AAED,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,oBAAoB,CAAC,CAE/B;AAED,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,gBAAgB,CAAC,CAE3B;AAED,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,gBAAgB,CAAC,CAE3B"}

package/dist/sync-parse.js

@@ -0,0 +1,38 @@
+import { SyncCombinedResponseSchema, SyncPullResponseSchema, SyncPushResponseSchema, } from '@syncular/core';
+function formatIssue(issue) {
+    const path = issue.path.length > 0
+        ? issue.path
+            .map((segment) => typeof segment === 'symbol' ? segment.toString() : String(segment))
+            .join('.')
+        : 'root';
+    return `${path}: ${issue.message}`;
+}
+function formatIssues(issues) {
+    return issues.map((issue) => formatIssue(issue)).join('; ');
+}
+function parseOrThrow(label, value, parse) {
+    const parsed = parse(value);
+    if (parsed.success) {
+        return parsed.data;
+    }
+    throw new Error(`${label} validation failed: ${formatIssues(parsed.error.issues)}`);
+}
+export function parseSyncCombinedResponse(value) {
+    return parseOrThrow('SyncCombinedResponse', value, (input) => SyncCombinedResponseSchema.safeParse(input));
+}
+export function parseSyncPushResponse(value) {
+    return parseOrThrow('SyncPushResponse', value, (input) => SyncPushResponseSchema.safeParse(input));
+}
+export function parseSyncPullResponse(value) {
+    return parseOrThrow('SyncPullResponse', value, (input) => SyncPullResponseSchema.safeParse(input));
+}
+export async function readSyncCombinedResponse(response) {
+    return parseSyncCombinedResponse(await response.json());
+}
+export async function readSyncPushResponse(response) {
+    return parseSyncPushResponse(await response.json());
+}
+export async function readSyncPullResponse(response) {
+    return parseSyncPullResponse(await response.json());
+}
+//# sourceMappingURL=sync-parse.js.map

package/dist/sync-parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-parse.js","sourceRoot":"","sources":["../src/sync-parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,0BAA0B,EAE1B,sBAAsB,EAEtB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAWxB,SAAS,WAAW,CAAC,KAAiB,EAAU;IAC9C,MAAM,IAAI,GACR,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;QACnB,CAAC,CAAC,KAAK,CAAC,IAAI;aACP,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACf,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CACnE;aACA,IAAI,CAAC,GAAG,CAAC;QACd,CAAC,CAAC,MAAM,CAAC;IACb,OAAO,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;AAAA,CACpC;AAED,SAAS,YAAY,CAAC,MAAiC,EAAU;IAC/D,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAAA,CAC7D;AAED,SAAS,YAAY,CACnB,KAAa,EACb,KAAc,EACd,KAAyC,EACtC;IACH,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IAC5B,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IAED,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,uBAAuB,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CACnE,CAAC;AAAA,CACH;AAED,MAAM,UAAU,yBAAyB,CACvC,KAAc,EACQ;IACtB,OAAO,YAAY,CAAC,sBAAsB,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAC3D,0BAA0B,CAAC,SAAS,CAAC,KAAK,CAAC,CAC5C,CAAC;AAAA,CACH;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAc,EAAoB;IACtE,OAAO,YAAY,CAAC,kBAAkB,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CACvD,sBAAsB,CAAC,SAAS,CAAC,KAAK,CAAC,CACxC,CAAC;AAAA,CACH;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAc,EAAoB;IACtE,OAAO,YAAY,CAAC,kBAAkB,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CACvD,sBAAsB,CAAC,SAAS,CAAC,KAAK,CAAC,CACxC,CAAC;AAAA,CACH;AAED,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,QAAkB,EACa;IAC/B,OAAO,yBAAyB,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;AAAA,CACzD;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,QAAkB,EACS;IAC3B,OAAO,qBAAqB,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;AAAA,CACrD;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,QAAkB,EACS;IAC3B,OAAO,qBAAqB,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;AAAA,CACrD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/testkit",
-  "version": "0.0.2-135",
+  "version": "0.0.2-137",
   "description": "Testing fixtures and utilities for Syncular",
   "license": "MIT",
   "author": "Benjamin Kniffler",
@@ -41,17 +41,17 @@
     "release": "bunx syncular-publish"
   },
   "dependencies": {
-    "@syncular/client": "0.0.2-135",
-    "@syncular/core": "0.0.2-135",
-    "@syncular/dialect-bun-sqlite": "0.0.2-135",
-    "@syncular/dialect-libsql": "0.0.2-135",
-    "@syncular/dialect-pglite": "0.0.2-135",
-    "@syncular/dialect-sqlite3": "0.0.2-135",
-    "@syncular/server": "0.0.2-135",
-    "@syncular/server-dialect-postgres": "0.0.2-135",
-    "@syncular/server-dialect-sqlite": "0.0.2-135",
-    "@syncular/server-hono": "0.0.2-135",
-    "@syncular/transport-http": "0.0.2-135",
+    "@syncular/client": "0.0.2-137",
+    "@syncular/core": "0.0.2-137",
+    "@syncular/dialect-bun-sqlite": "0.0.2-137",
+    "@syncular/dialect-libsql": "0.0.2-137",
+    "@syncular/dialect-pglite": "0.0.2-137",
+    "@syncular/dialect-sqlite3": "0.0.2-137",
+    "@syncular/server": "0.0.2-137",
+    "@syncular/server-dialect-postgres": "0.0.2-137",
+    "@syncular/server-dialect-sqlite": "0.0.2-137",
+    "@syncular/server-hono": "0.0.2-137",
+    "@syncular/transport-http": "0.0.2-137",
     "hono": "^4.11.9"
   },
   "devDependencies": {

package/src/deterministic.ts

@@ -0,0 +1,121 @@
+export interface CreateIdFactoryOptions {
+  prefix?: string;
+  separator?: string;
+  startAt?: number;
+  step?: number;
+  padLength?: number;
+}
+
+export interface IdFactory {
+  next: () => string;
+  peek: () => string;
+  current: () => number;
+  reset: (startAt?: number) => void;
+}
+
+function normalizeCounter(value: number, label: string): number {
+  if (!Number.isFinite(value)) {
+    throw new Error(`${label} must be a finite number`);
+  }
+
+  return Math.trunc(value);
+}
+
+function formatCounter(value: number, padLength: number): string {
+  const text = String(value);
+  return padLength > text.length ? text.padStart(padLength, '0') : text;
+}
+
+export function createIdFactory(
+  options: CreateIdFactoryOptions = {}
+): IdFactory {
+  const prefix = options.prefix ?? '';
+  const separator = options.separator ?? '-';
+  const step = normalizeCounter(options.step ?? 1, 'step');
+  const padLength = Math.max(
+    0,
+    normalizeCounter(options.padLength ?? 0, 'padLength')
+  );
+
+  if (step === 0) {
+    throw new Error('step must not be 0');
+  }
+
+  let counter = normalizeCounter(options.startAt ?? 1, 'startAt');
+
+  const format = (value: number): string => {
+    const token = formatCounter(value, padLength);
+    if (prefix.length === 0) {
+      return token;
+    }
+
+    return `${prefix}${separator}${token}`;
+  };
+
+  return {
+    next: () => {
+      const value = format(counter);
+      counter += step;
+      return value;
+    },
+    peek: () => format(counter),
+    current: () => counter,
+    reset: (nextStartAt = options.startAt ?? 1) => {
+      counter = normalizeCounter(nextStartAt, 'startAt');
+    },
+  };
+}
+
+export interface CreateCommitIdFactoryOptions
+  extends Omit<CreateIdFactoryOptions, 'prefix'> {
+  prefix?: string;
+}
+
+export function createCommitIdFactory(
+  options: CreateCommitIdFactoryOptions = {}
+): IdFactory {
+  return createIdFactory({
+    prefix: options.prefix ?? 'commit',
+    separator: options.separator,
+    startAt: options.startAt,
+    step: options.step,
+    padLength: options.padLength,
+  });
+}
+
+export interface CreateFakeClockOptions {
+  startMs?: number;
+  tickMs?: number;
+}
+
+export interface FakeClock {
+  now: () => number;
+  iso: () => string;
+  set: (nextMs: number) => number;
+  advance: (deltaMs: number) => number;
+  tick: (stepMs?: number) => number;
+}
+
+export function createFakeClock(
+  options: CreateFakeClockOptions = {}
+): FakeClock {
+  const defaultTickMs = normalizeCounter(options.tickMs ?? 1, 'tickMs');
+  let nowMs = normalizeCounter(options.startMs ?? Date.now(), 'startMs');
+
+  return {
+    now: () => nowMs,
+    iso: () => new Date(nowMs).toISOString(),
+    set: (nextMs: number) => {
+      nowMs = normalizeCounter(nextMs, 'nextMs');
+      return nowMs;
+    },
+    advance: (deltaMs: number) => {
+      nowMs += normalizeCounter(deltaMs, 'deltaMs');
+      return nowMs;
+    },
+    tick: (stepMs = defaultTickMs) => {
+      nowMs += normalizeCounter(stepMs, 'stepMs');
+      return nowMs;
+    },
+  };
+}

package/src/index.ts

@@ -1,9 +1,14 @@
 export * from './assertions';
+export * from './deterministic';
 export * from './faults';
 export * from './fixtures';
 export * from './hono-node-server';
 export * from './http-fixtures';
 export * from './project-scoped-tasks';
+export * from './realtime-ws';
 export * from './runtime-process';
+export * from './scenario-flow';
+export * from './sync-builders';
 export * from './sync-http';
+export * from './sync-parse';
 export * from './sync-response';

package/src/realtime-ws.ts

@@ -0,0 +1,321 @@
+import { isRecord } from '@syncular/core';
+
+export type RealtimeWsQueryValue = string | number | boolean | null | undefined;
+
+export interface CreateRealtimeWsUrlOptions {
+  baseUrl: string;
+  clientId: string;
+  actorId: string;
+  actorQueryParam?: string;
+  path?: string;
+  query?: Record<string, RealtimeWsQueryValue>;
+}
+
+export interface WebSocketConstructor {
+  new (url: string, protocols?: string | string[]): WebSocket;
+}
+
+export interface OpenRealtimeWsOptions extends CreateRealtimeWsUrlOptions {
+  WebSocketCtor?: WebSocketConstructor;
+  protocols?: string | string[];
+}
+
+function appendQueryParam(
+  url: URL,
+  key: string,
+  value: RealtimeWsQueryValue
+): void {
+  if (value === null || value === undefined) {
+    return;
+  }
+
+  url.searchParams.set(key, String(value));
+}
+
+function toWsProtocol(protocol: string): string {
+  if (protocol === 'http:') {
+    return 'ws:';
+  }
+
+  if (protocol === 'https:') {
+    return 'wss:';
+  }
+
+  return protocol;
+}
+
+export function createRealtimeWsUrl(
+  options: CreateRealtimeWsUrlOptions
+): string {
+  const url = new URL(options.baseUrl);
+  url.protocol = toWsProtocol(url.protocol);
+
+  const path = options.path ?? '/sync/realtime';
+  url.pathname = path.startsWith('/') ? path : `/${path}`;
+  url.search = '';
+
+  appendQueryParam(url, 'clientId', options.clientId);
+  appendQueryParam(url, options.actorQueryParam ?? 'userId', options.actorId);
+
+  for (const [key, value] of Object.entries(options.query ?? {})) {
+    appendQueryParam(url, key, value);
+  }
+
+  return url.toString();
+}
+
+export function openRealtimeWs(options: OpenRealtimeWsOptions): WebSocket {
+  const WebSocketCtor = options.WebSocketCtor ?? globalThis.WebSocket;
+  if (!WebSocketCtor) {
+    throw new Error('WebSocket constructor is unavailable in this runtime');
+  }
+
+  return new WebSocketCtor(createRealtimeWsUrl(options), options.protocols);
+}
+
+export interface WaitForWsOpenOptions {
+  timeoutMs?: number;
+}
+
+export function waitForWsOpen(
+  ws: WebSocket,
+  options: WaitForWsOpenOptions = {}
+): Promise<void> {
+  const timeoutMs = options.timeoutMs ?? 10_000;
+
+  return new Promise<void>((resolve, reject) => {
+    const cleanup = () => {
+      clearTimeout(timeout);
+      ws.removeEventListener('open', onOpen);
+      ws.removeEventListener('error', onError);
+      ws.removeEventListener('close', onClose);
+    };
+
+    const onOpen = () => {
+      cleanup();
+      resolve();
+    };
+
+    const onError = () => {
+      cleanup();
+      reject(new Error('WebSocket emitted an error before opening'));
+    };
+
+    const onClose = (event: CloseEvent) => {
+      cleanup();
+      reject(
+        new Error(
+          `WebSocket closed before opening (code=${event.code} reason=${event.reason || 'none'})`
+        )
+      );
+    };
+
+    const timeout = setTimeout(() => {
+      cleanup();
+      reject(
+        new Error(`Timed out waiting for WebSocket open (${timeoutMs}ms)`)
+      );
+    }, timeoutMs);
+
+    ws.addEventListener('open', onOpen);
+    ws.addEventListener('error', onError);
+    ws.addEventListener('close', onClose);
+  });
+}
+
+export interface WaitForWsMessageOptions {
+  timeoutMs?: number;
+  predicate?: (event: MessageEvent) => boolean;
+}
+
+export function waitForWsMessage(
+  ws: WebSocket,
+  options: WaitForWsMessageOptions = {}
+): Promise<MessageEvent> {
+  const timeoutMs = options.timeoutMs ?? 10_000;
+
+  return new Promise<MessageEvent>((resolve, reject) => {
+    const cleanup = () => {
+      clearTimeout(timeout);
+      ws.removeEventListener('message', onMessage);
+      ws.removeEventListener('error', onError);
+      ws.removeEventListener('close', onClose);
+    };
+
+    const onMessage = (event: MessageEvent) => {
+      if (options.predicate && !options.predicate(event)) {
+        return;
+      }
+
+      cleanup();
+      resolve(event);
+    };
+
+    const onError = () => {
+      cleanup();
+      reject(new Error('WebSocket emitted an error before a message arrived'));
+    };
+
+    const onClose = (event: CloseEvent) => {
+      cleanup();
+      reject(
+        new Error(
+          `WebSocket closed before receiving a matching message (code=${event.code} reason=${event.reason || 'none'})`
+        )
+      );
+    };
+
+    const timeout = setTimeout(() => {
+      cleanup();
+      reject(
+        new Error(`Timed out waiting for WebSocket message (${timeoutMs}ms)`)
+      );
+    }, timeoutMs);
+
+    ws.addEventListener('message', onMessage);
+    ws.addEventListener('error', onError);
+    ws.addEventListener('close', onClose);
+  });
+}
+
+function readTextPayload(data: MessageEvent['data']): string | null {
+  if (typeof data === 'string') {
+    return data;
+  }
+
+  if (data instanceof ArrayBuffer) {
+    return new TextDecoder().decode(new Uint8Array(data));
+  }
+
+  if (ArrayBuffer.isView(data)) {
+    return new TextDecoder().decode(
+      new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+    );
+  }
+
+  return null;
+}
+
+export function parseWsJsonMessage(
+  event: MessageEvent
+): Record<string, unknown> | null {
+  const payload = readTextPayload(event.data);
+  if (!payload) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(payload);
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface WaitForWsJsonMessageOptions {
+  timeoutMs?: number;
+  predicate?: (message: Record<string, unknown>) => boolean;
+}
+
+export function waitForWsJsonMessage(
+  ws: WebSocket,
+  options: WaitForWsJsonMessageOptions = {}
+): Promise<Record<string, unknown>> {
+  const timeoutMs = options.timeoutMs ?? 10_000;
+
+  return new Promise<Record<string, unknown>>((resolve, reject) => {
+    const cleanup = () => {
+      clearTimeout(timeout);
+      ws.removeEventListener('message', onMessage);
+      ws.removeEventListener('error', onError);
+      ws.removeEventListener('close', onClose);
+    };
+
+    const onMessage = (event: MessageEvent) => {
+      const parsed = parseWsJsonMessage(event);
+      if (!parsed) {
+        return;
+      }
+
+      if (options.predicate && !options.predicate(parsed)) {
+        return;
+      }
+
+      cleanup();
+      resolve(parsed);
+    };
+
+    const onError = () => {
+      cleanup();
+      reject(new Error('WebSocket emitted an error before JSON message'));
+    };
+
+    const onClose = (event: CloseEvent) => {
+      cleanup();
+      reject(
+        new Error(
+          `WebSocket closed before receiving JSON message (code=${event.code} reason=${event.reason || 'none'})`
+        )
+      );
+    };
+
+    const timeout = setTimeout(() => {
+      cleanup();
+      reject(
+        new Error(
+          `Timed out waiting for WebSocket JSON message (${timeoutMs}ms)`
+        )
+      );
+    }, timeoutMs);
+
+    ws.addEventListener('message', onMessage);
+    ws.addEventListener('error', onError);
+    ws.addEventListener('close', onClose);
+  });
+}
+
+export interface CloseWsSafeOptions {
+  code?: number;
+  reason?: string;
+  timeoutMs?: number;
+}
+
+const WS_CLOSING = 2;
+const WS_CLOSED = 3;
+
+export async function closeWsSafe(
+  ws: WebSocket,
+  options: CloseWsSafeOptions = {}
+): Promise<void> {
+  if (ws.readyState === WS_CLOSED) {
+    return;
+  }
+
+  const timeoutMs = options.timeoutMs ?? 2_000;
+
+  await new Promise<void>((resolve) => {
+    const cleanup = () => {
+      clearTimeout(timeout);
+      ws.removeEventListener('close', onClose);
+      resolve();
+    };
+
+    const onClose = () => {
+      cleanup();
+    };
+
+    const timeout = setTimeout(() => {
+      cleanup();
+    }, timeoutMs);
+
+    ws.addEventListener('close', onClose);
+
+    if (ws.readyState !== WS_CLOSING) {
+      try {
+        ws.close(options.code, options.reason);
+      } catch {
+        cleanup();
+      }
+    }
+  });
+}