react-websocket 4.0.0 → 4.18.0

package/dist/replay.cjs

@@ -0,0 +1,324 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/replay.ts
+const CONNECTING = 0;
+const OPEN = 1;
+const CLOSING = 2;
+const CLOSED = 3;
+function closeEvent(code, reason, wasClean) {
+	const init = {
+		code,
+		reason,
+		wasClean
+	};
+	return typeof CloseEvent === "function" ? new CloseEvent("close", init) : Object.assign(new Event("close"), init);
+}
+function encode(bytes) {
+	const view = bytes instanceof ArrayBuffer ? new Uint8Array(bytes) : new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	let text = "";
+	for (const byte of view) text += String.fromCharCode(byte);
+	return { binary: btoa(text) };
+}
+function decode(data, binaryType) {
+	if (typeof data === "string") return data;
+	const buffer = Uint8Array.from(atob(data.binary), (char) => char.charCodeAt(0)).buffer;
+	return binaryType === "blob" ? new Blob([buffer]) : buffer;
+}
+/** Shared by both classes: the `WebSocket` surface over a state and some events. */
+var Base = class extends EventTarget {
+	static CONNECTING = CONNECTING;
+	static OPEN = OPEN;
+	static CLOSING = CLOSING;
+	static CLOSED = CLOSED;
+	CONNECTING = CONNECTING;
+	OPEN = OPEN;
+	CLOSING = CLOSING;
+	CLOSED = CLOSED;
+	url;
+	extensions = "";
+	onopen = null;
+	onmessage = null;
+	onerror = null;
+	onclose = null;
+	protocol = "";
+	state = CONNECTING;
+	constructor(url) {
+		super();
+		this.url = String(url);
+		for (const type of [
+			"open",
+			"message",
+			"error",
+			"close"
+		]) this.addEventListener(type, (event) => this[`on${type}`]?.call(this, event));
+	}
+	get readyState() {
+		return this.state;
+	}
+	opened(protocol) {
+		this.state = OPEN;
+		this.protocol = protocol;
+		this.dispatchEvent(new Event("open"));
+	}
+	received(data) {
+		if (this.state === OPEN) this.dispatchEvent(new MessageEvent("message", { data }));
+	}
+	ended(code, reason, wasClean) {
+		if (this.state === CLOSED) return;
+		this.state = CLOSED;
+		this.dispatchEvent(closeEvent(code, reason, wasClean));
+	}
+};
+/**
+* A `WebSocket` class that records what its connections do: when each one opened, every message
+* sent and received, errors and closes. Pass it as the `WebSocket` option, and get the session
+* back with `recording()`, or download it with `save()`, to attach to a bug report or replay
+* with {@link createReplayWebSocket}.
+*
+* Recordings hold every message, so they can hold tokens and personal data: record in
+* development, or ask before saving one from a user's session.
+*
+* @example
+* ```ts
+* import { createRecordingWebSocket } from 'react-websocket/replay';
+*
+* export const Recorder = createRecordingWebSocket();
+* export const live = createWebSocket(url, { WebSocket: Recorder });
+*
+* reportButton.onclick = () => Recorder.save('session.json');
+* ```
+*/
+function createRecordingWebSocket(options = {}) {
+	let connections = [];
+	class RecordingSocket extends Base {
+		#inner;
+		#binaryType = "blob";
+		static recording() {
+			return JSON.parse(JSON.stringify({
+				format: "react-websocket-recording",
+				version: 1,
+				connections
+			}));
+		}
+		static save(filename = "websocket-recording.json") {
+			const url = URL.createObjectURL(new Blob([JSON.stringify(RecordingSocket.recording(), null, 2)], { type: "application/json" }));
+			Object.assign(document.createElement("a"), {
+				href: url,
+				download: filename
+			}).click();
+			setTimeout(() => URL.revokeObjectURL(url), 0);
+		}
+		static clear() {
+			connections = [];
+		}
+		constructor(url, protocols) {
+			super(url);
+			const Impl = options.WebSocket ?? globalThis.WebSocket;
+			const inner = this.#inner = new Impl(url, protocols);
+			inner.binaryType = "arraybuffer";
+			const start = performance.now();
+			const events = [];
+			connections.push({
+				url: this.url,
+				at: Date.now(),
+				events
+			});
+			const record = (event) => events.push({
+				t: Math.round(performance.now() - start),
+				...event
+			});
+			this.#record = record;
+			inner.onopen = () => {
+				record({
+					type: "open",
+					protocol: inner.protocol ?? ""
+				});
+				this.opened(inner.protocol);
+			};
+			inner.onmessage = (event) => {
+				const data = event.data;
+				record({
+					type: "message",
+					data: typeof data === "string" ? data : encode(data)
+				});
+				this.received(typeof data === "string" || this.#binaryType !== "blob" ? data : new Blob([data]));
+			};
+			inner.onerror = () => {
+				record({ type: "error" });
+				this.dispatchEvent(new Event("error"));
+			};
+			inner.onclose = (event) => {
+				record({
+					type: "close",
+					code: event.code,
+					reason: event.reason,
+					wasClean: event.wasClean
+				});
+				this.ended(event.code, event.reason, event.wasClean);
+			};
+		}
+		#record;
+		get binaryType() {
+			return this.#binaryType;
+		}
+		set binaryType(value) {
+			this.#binaryType = value;
+		}
+		get bufferedAmount() {
+			return this.#inner.bufferedAmount;
+		}
+		send(data) {
+			this.#inner.send(data);
+			if (typeof data === "string") this.#record({
+				type: "send",
+				data
+			});
+			else if (data instanceof Blob) {
+				const event = {
+					type: "send",
+					data: { binary: "" }
+				};
+				this.#record(event);
+				data.arrayBuffer().then((buffer) => Object.assign(event.data, encode(buffer)));
+			} else this.#record({
+				type: "send",
+				data: encode(data)
+			});
+		}
+		close(code, reason) {
+			if (this.state >= CLOSING) return;
+			this.state = CLOSING;
+			this.#inner.close(code, reason);
+		}
+	}
+	return RecordingSocket;
+}
+/**
+* A `WebSocket` class that plays a recording back, without a server: each connection the client
+* opens replays the next recorded one, with its open, messages, errors and close, at the recorded
+* timing or faster. For reproducing a bug report, offline demos, and UI tests that don't call a
+* live backend, such as an AI model, on every run.
+*
+* By default, what came after a send in the recording waits until the app sends too, so the
+* replay follows the app. Wrap it with `createChaosWebSocket({ WebSocket: Replay })` to add
+* faults.
+*
+* @example
+* ```ts
+* import { createReplayWebSocket } from 'react-websocket/replay';
+* import recording from './fixtures/chat.json';
+*
+* const Replay = createReplayWebSocket(recording, { speed: Infinity });
+* render(<Chat client={createWebSocket(url, { WebSocket: Replay })} />);
+* await Replay.done;
+* ```
+*/
+function createReplayWebSocket(recording, options = {}) {
+	const speed = options.speed ?? 1;
+	const waitForSends = options.waitForSends ?? true;
+	let next = 0;
+	let sent = [];
+	let finish;
+	let done = new Promise((resolve) => finish = resolve);
+	const live = /* @__PURE__ */ new Set();
+	class ReplaySocket extends Base {
+		binaryType = "blob";
+		bufferedAmount = 0;
+		#events;
+		#index = 0;
+		#sent = [];
+		#recordedAt = 0;
+		#realAt = performance.now();
+		#timer;
+		#sends = 0;
+		#paused = false;
+		static get sent() {
+			return sent;
+		}
+		static get done() {
+			return done;
+		}
+		static reset() {
+			for (const socket of live) socket.#stop();
+			next = 0;
+			sent = [];
+			done = new Promise((resolve) => finish = resolve);
+		}
+		constructor(url, protocols) {
+			super(url);
+			const connection = recording.connections[next++];
+			sent.push(this.#sent);
+			this.#events = connection?.events ?? [{
+				t: 0,
+				type: "error"
+			}, {
+				t: 0,
+				type: "close",
+				code: 1006,
+				reason: "",
+				wasClean: false
+			}];
+			live.add(this);
+			this.#schedule();
+		}
+		send(data) {
+			if (this.state === CONNECTING) throw new DOMException("WebSocket is still in CONNECTING state", "InvalidStateError");
+			if (this.state !== OPEN) return;
+			this.#sent.push(typeof data === "string" ? data : data instanceof Blob ? { binary: "" } : encode(data));
+			if (this.#paused) {
+				this.#paused = false;
+				this.#schedule();
+			}
+		}
+		close(code = 1e3, reason = "") {
+			if (this.state >= CLOSING) return;
+			this.state = CLOSING;
+			this.#stop();
+			setTimeout(() => this.ended(code, reason, true), 0);
+		}
+		#schedule() {
+			clearTimeout(this.#timer);
+			const event = this.#events[this.#index];
+			if (!event || this.state === CLOSED) return this.#finished();
+			if (event.type === "send") {
+				if (waitForSends) {
+					if (this.#sent.length <= this.#sends) return void (this.#paused = true);
+					this.#recordedAt = event.t;
+					this.#realAt = performance.now();
+				}
+				this.#index++;
+				this.#sends++;
+				return this.#schedule();
+			}
+			const wait = (event.t - this.#recordedAt) / speed - (performance.now() - this.#realAt);
+			this.#timer = setTimeout(() => this.#play(event), Math.max(0, Number.isFinite(wait) ? wait : 0));
+		}
+		#play(event) {
+			this.#index++;
+			this.#recordedAt = event.t;
+			this.#realAt = performance.now();
+			if (event.type === "open") this.opened(event.protocol);
+			else if (event.type === "message") this.received(decode(event.data, this.binaryType));
+			else if (event.type === "error") this.dispatchEvent(new Event("error"));
+			else if (event.type === "close") {
+				this.#stop();
+				return this.ended(event.code, event.reason, event.wasClean);
+			}
+			this.#schedule();
+		}
+		#stop() {
+			clearTimeout(this.#timer);
+			this.#index = this.#events.length;
+			this.#finished();
+		}
+		#finished() {
+			live.delete(this);
+			if (next >= recording.connections.length && !live.size) finish();
+		}
+	}
+	return ReplaySocket;
+}
+//#endregion
+exports.createRecordingWebSocket = createRecordingWebSocket;
+exports.createReplayWebSocket = createReplayWebSocket;
+
+//# sourceMappingURL=replay.cjs.map

package/dist/replay.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.cjs","names":[],"sources":["../src/replay.ts"],"sourcesContent":["// An entry with no imports: it only implements the `WebSocket` interface.\n\n/** Data in a recording: text as it was, binary as base64. */\nexport type RecordedData = string | { readonly binary: string };\n\n/** One event of a recorded connection, `t` ms after it was created. */\nexport type RecordedEvent =\n  | { readonly t: number; readonly type: 'open'; readonly protocol: string }\n  | { readonly t: number; readonly type: 'send' | 'message'; readonly data: RecordedData }\n  | { readonly t: number; readonly type: 'error' }\n  | {\n      readonly t: number;\n      readonly type: 'close';\n      readonly code: number;\n      readonly reason: string;\n      readonly wasClean: boolean;\n    };\n\n/** A recorded event before its time is known. */\ntype Untimed = RecordedEvent extends infer E\n  ? E extends RecordedEvent\n    ? Omit<E, 't'>\n    : never\n  : never;\n\n/** A recorded session: every connection, in the order they were opened. Plain JSON. */\nexport interface WebSocketRecording {\n  readonly format: 'react-websocket-recording';\n  readonly version: 1;\n  readonly connections: readonly {\n    readonly url: string;\n    /** When it was created, from `Date.now()`. */\n    readonly at: number;\n    readonly events: readonly RecordedEvent[];\n  }[];\n}\n\n/** The class from {@link createRecordingWebSocket}: a `WebSocket` that records what it does. */\nexport interface RecordingWebSocket extends Statics {\n  new (url: string | URL, protocols?: string | string[]): WebSocket;\n  readonly prototype: WebSocket;\n  /** Everything recorded so far, as a new plain object. */\n  recording(): WebSocketRecording;\n  /** Download the recording as a JSON file, e.g. from a \"Report a problem\" button. */\n  save(filename?: string): void;\n  /** Forget everything recorded so far. */\n  clear(): void;\n}\n\n/** Options for {@link createReplayWebSocket}. */\nexport interface ReplayOptions {\n  /**\n   * How fast to replay: `1` is the recorded timing, `4` four times faster, `Infinity` as fast as\n   * possible, each event in a task of its own.\n   * @default 1\n   */\n  speed?: number;\n  /**\n   * Wait for the app to send before replaying what came after a send in the recording, so the\n   * replay follows the app instead of the clock: a server's answer comes after the question,\n   * however long the app takes to ask. `false` follows the recorded timing alone.\n   * @default true\n   */\n  waitForSends?: boolean;\n}\n\n/** The class from {@link createReplayWebSocket}: a `WebSocket` that plays a recording back. */\nexport interface ReplayWebSocket extends Statics {\n  new (url: string | URL, protocols?: string | string[]): WebSocket;\n  readonly prototype: WebSocket;\n  /** What the app sent during the replay, by connection, as recorded data. */\n  readonly sent: readonly RecordedData[][];\n  /** Resolves once every recorded connection has been played to its end. */\n  readonly done: Promise<void>;\n  /** Start again from the first recorded connection. */\n  reset(): void;\n}\n\ninterface Statics {\n  readonly CONNECTING: 0;\n  readonly OPEN: 1;\n  readonly CLOSING: 2;\n  readonly CLOSED: 3;\n}\n\nconst CONNECTING = 0;\nconst OPEN = 1;\nconst CLOSING = 2;\nconst CLOSED = 3;\n\nfunction closeEvent(code: number, reason: string, wasClean: boolean): Event {\n  const init = { code, reason, wasClean };\n  // Node 22 has no CloseEvent.\n  return typeof CloseEvent === 'function'\n    ? new CloseEvent('close', init)\n    : Object.assign(new Event('close'), init);\n}\n\nfunction encode(bytes: ArrayBuffer | ArrayBufferView): RecordedData {\n  const view =\n    bytes instanceof ArrayBuffer\n      ? new Uint8Array(bytes)\n      : new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);\n  let text = '';\n  for (const byte of view) text += String.fromCharCode(byte);\n  return { binary: btoa(text) };\n}\n\nfunction decode(data: RecordedData, binaryType: BinaryType): unknown {\n  if (typeof data === 'string') return data;\n  const buffer = Uint8Array.from(atob(data.binary), char => char.charCodeAt(0)).buffer;\n  return binaryType === 'blob' ? new Blob([buffer]) : buffer;\n}\n\n/** Shared by both classes: the `WebSocket` surface over a state and some events. */\nclass Base extends EventTarget {\n  static readonly CONNECTING = CONNECTING;\n  static readonly OPEN = OPEN;\n  static readonly CLOSING = CLOSING;\n  static readonly CLOSED = CLOSED;\n  readonly CONNECTING = CONNECTING;\n  readonly OPEN = OPEN;\n  readonly CLOSING = CLOSING;\n  readonly CLOSED = CLOSED;\n  readonly url: string;\n  readonly extensions = '';\n  onopen: WebSocket['onopen'] = null;\n  onmessage: WebSocket['onmessage'] = null;\n  onerror: WebSocket['onerror'] = null;\n  onclose: WebSocket['onclose'] = null;\n  protocol = '';\n  state: WebSocket['readyState'] = CONNECTING;\n\n  constructor(url: string | URL) {\n    super();\n    this.url = String(url);\n    for (const type of ['open', 'message', 'error', 'close'] as const) {\n      this.addEventListener(type, event =>\n        (this[`on${type}`] as ((event: Event) => void) | null)?.call(this, event)\n      );\n    }\n  }\n\n  get readyState() {\n    return this.state;\n  }\n\n  opened(protocol: string) {\n    this.state = OPEN;\n    this.protocol = protocol;\n    this.dispatchEvent(new Event('open'));\n  }\n\n  received(data: unknown) {\n    if (this.state === OPEN) this.dispatchEvent(new MessageEvent('message', { data }));\n  }\n\n  ended(code: number, reason: string, wasClean: boolean) {\n    if (this.state === CLOSED) return;\n    this.state = CLOSED;\n    this.dispatchEvent(closeEvent(code, reason, wasClean));\n  }\n}\n\n/**\n * A `WebSocket` class that records what its connections do: when each one opened, every message\n * sent and received, errors and closes. Pass it as the `WebSocket` option, and get the session\n * back with `recording()`, or download it with `save()`, to attach to a bug report or replay\n * with {@link createReplayWebSocket}.\n *\n * Recordings hold every message, so they can hold tokens and personal data: record in\n * development, or ask before saving one from a user's session.\n *\n * @example\n * ```ts\n * import { createRecordingWebSocket } from 'react-websocket/replay';\n *\n * export const Recorder = createRecordingWebSocket();\n * export const live = createWebSocket(url, { WebSocket: Recorder });\n *\n * reportButton.onclick = () => Recorder.save('session.json');\n * ```\n */\nexport function createRecordingWebSocket(\n  options: { WebSocket?: typeof WebSocket } = {}\n): RecordingWebSocket {\n  let connections: { url: string; at: number; events: RecordedEvent[] }[] = [];\n\n  class RecordingSocket extends Base implements WebSocket {\n    #inner: WebSocket;\n    #binaryType: BinaryType = 'blob';\n\n    static recording(): WebSocketRecording {\n      return JSON.parse(\n        JSON.stringify({ format: 'react-websocket-recording', version: 1, connections })\n      );\n    }\n\n    static save(filename = 'websocket-recording.json') {\n      const url = URL.createObjectURL(\n        new Blob([JSON.stringify(RecordingSocket.recording(), null, 2)], {\n          type: 'application/json'\n        })\n      );\n      const link = Object.assign(document.createElement('a'), { href: url, download: filename });\n      link.click();\n      setTimeout(() => URL.revokeObjectURL(url), 0);\n    }\n\n    static clear() {\n      connections = [];\n    }\n\n    constructor(url: string | URL, protocols?: string | string[]) {\n      super(url);\n      const Impl = options.WebSocket ?? globalThis.WebSocket;\n      const inner = (this.#inner = new Impl(url, protocols));\n      // Binary data arrives as an ArrayBuffer, to record it without waiting on a Blob.\n      inner.binaryType = 'arraybuffer';\n      const start = performance.now();\n      const events: RecordedEvent[] = [];\n      connections.push({ url: this.url, at: Date.now(), events });\n      const record = (event: Untimed) =>\n        events.push({ t: Math.round(performance.now() - start), ...event } as RecordedEvent);\n      this.#record = record;\n      inner.onopen = () => {\n        record({ type: 'open', protocol: inner.protocol ?? '' });\n        this.opened(inner.protocol);\n      };\n      inner.onmessage = event => {\n        const data = event.data as string | ArrayBuffer;\n        record({ type: 'message', data: typeof data === 'string' ? data : encode(data) });\n        this.received(\n          typeof data === 'string' || this.#binaryType !== 'blob' ? data : new Blob([data])\n        );\n      };\n      inner.onerror = () => {\n        record({ type: 'error' });\n        this.dispatchEvent(new Event('error'));\n      };\n      inner.onclose = event => {\n        record({ type: 'close', code: event.code, reason: event.reason, wasClean: event.wasClean });\n        this.ended(event.code, event.reason, event.wasClean);\n      };\n    }\n\n    #record: (event: Untimed) => void;\n\n    get binaryType() {\n      return this.#binaryType;\n    }\n\n    set binaryType(value) {\n      this.#binaryType = value;\n    }\n\n    get bufferedAmount() {\n      return this.#inner.bufferedAmount;\n    }\n\n    send(data: Parameters<WebSocket['send']>[0]) {\n      this.#inner.send(data);\n      if (typeof data === 'string') this.#record({ type: 'send', data });\n      else if (data instanceof Blob) {\n        // Recorded where it was sent; its bytes are filled in once read.\n        const event = { type: 'send', data: { binary: '' } } as const;\n        this.#record(event);\n        void data.arrayBuffer().then(buffer => Object.assign(event.data, encode(buffer)));\n      } else this.#record({ type: 'send', data: encode(data) });\n    }\n\n    close(code?: number, reason?: string) {\n      if (this.state >= CLOSING) return;\n      this.state = CLOSING;\n      this.#inner.close(code, reason);\n    }\n  }\n\n  return RecordingSocket as unknown as RecordingWebSocket;\n}\n\n/**\n * A `WebSocket` class that plays a recording back, without a server: each connection the client\n * opens replays the next recorded one, with its open, messages, errors and close, at the recorded\n * timing or faster. For reproducing a bug report, offline demos, and UI tests that don't call a\n * live backend, such as an AI model, on every run.\n *\n * By default, what came after a send in the recording waits until the app sends too, so the\n * replay follows the app. Wrap it with `createChaosWebSocket({ WebSocket: Replay })` to add\n * faults.\n *\n * @example\n * ```ts\n * import { createReplayWebSocket } from 'react-websocket/replay';\n * import recording from './fixtures/chat.json';\n *\n * const Replay = createReplayWebSocket(recording, { speed: Infinity });\n * render(<Chat client={createWebSocket(url, { WebSocket: Replay })} />);\n * await Replay.done;\n * ```\n */\nexport function createReplayWebSocket(\n  recording: WebSocketRecording,\n  options: ReplayOptions = {}\n): ReplayWebSocket {\n  const speed = options.speed ?? 1;\n  const waitForSends = options.waitForSends ?? true;\n  let next = 0;\n  let sent: RecordedData[][] = [];\n  let finish: () => void;\n  let done = new Promise<void>(resolve => (finish = resolve));\n  const live = new Set<ReplaySocket>();\n\n  class ReplaySocket extends Base implements WebSocket {\n    binaryType: BinaryType = 'blob';\n    readonly bufferedAmount = 0;\n    #events: readonly RecordedEvent[];\n    #index = 0;\n    #sent: RecordedData[] = [];\n    // The recorded time the timeline is at, and the real time it was there.\n    #recordedAt = 0;\n    #realAt = performance.now();\n    #timer: ReturnType<typeof setTimeout> | undefined;\n    // Recorded sends passed so far, and whether the timeline waits for the app to send.\n    #sends = 0;\n    #paused = false;\n\n    static get sent() {\n      return sent;\n    }\n\n    static get done() {\n      return done;\n    }\n\n    static reset() {\n      for (const socket of live) socket.#stop();\n      next = 0;\n      sent = [];\n      done = new Promise<void>(resolve => (finish = resolve));\n    }\n\n    constructor(url: string | URL, protocols?: string | string[]) {\n      super(url);\n      void protocols;\n      const connection = recording.connections[next++];\n      sent.push(this.#sent);\n      // More connections than were recorded: refused, like a server that's gone.\n      this.#events = connection?.events ?? [\n        { t: 0, type: 'error' },\n        { t: 0, type: 'close', code: 1006, reason: '', wasClean: false }\n      ];\n      live.add(this);\n      this.#schedule();\n    }\n\n    send(data: Parameters<WebSocket['send']>[0]) {\n      if (this.state === CONNECTING) {\n        throw new DOMException('WebSocket is still in CONNECTING state', 'InvalidStateError');\n      }\n      if (this.state !== OPEN) return;\n      this.#sent.push(\n        typeof data === 'string' ? data : data instanceof Blob ? { binary: '' } : encode(data)\n      );\n      if (this.#paused) {\n        this.#paused = false;\n        this.#schedule();\n      }\n    }\n\n    close(code = 1000, reason = '') {\n      if (this.state >= CLOSING) return;\n      this.state = CLOSING;\n      this.#stop();\n      setTimeout(() => this.ended(code, reason, true), 0);\n    }\n\n    #schedule(): void {\n      clearTimeout(this.#timer);\n      const event = this.#events[this.#index];\n      if (!event || this.state === CLOSED) return this.#finished();\n      if (event.type === 'send') {\n        if (waitForSends) {\n          // Wait until the app has sent as many messages, then go on from that moment.\n          if (this.#sent.length <= this.#sends) return void (this.#paused = true);\n          this.#recordedAt = event.t;\n          this.#realAt = performance.now();\n        }\n        this.#index++;\n        this.#sends++;\n        return this.#schedule();\n      }\n      const wait = (event.t - this.#recordedAt) / speed - (performance.now() - this.#realAt);\n      this.#timer = setTimeout(\n        () => this.#play(event),\n        Math.max(0, Number.isFinite(wait) ? wait : 0)\n      );\n    }\n\n    #play(event: RecordedEvent) {\n      this.#index++;\n      this.#recordedAt = event.t;\n      this.#realAt = performance.now();\n      if (event.type === 'open') this.opened(event.protocol);\n      else if (event.type === 'message') this.received(decode(event.data, this.binaryType));\n      else if (event.type === 'error') this.dispatchEvent(new Event('error'));\n      else if (event.type === 'close') {\n        this.#stop();\n        return this.ended(event.code, event.reason, event.wasClean);\n      }\n      this.#schedule();\n    }\n\n    #stop() {\n      clearTimeout(this.#timer);\n      this.#index = this.#events.length;\n      this.#finished();\n    }\n\n    #finished() {\n      live.delete(this);\n      if (next >= recording.connections.length && !live.size) finish();\n    }\n  }\n\n  return ReplaySocket as unknown as ReplayWebSocket;\n}\n"],"mappings":"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"}

package/dist/replay.d.cts

@@ -0,0 +1,124 @@
+//#region src/replay.d.ts
+/** Data in a recording: text as it was, binary as base64. */
+export type RecordedData = string | {
+  readonly binary: string;
+};
+/** One event of a recorded connection, `t` ms after it was created. */
+export type RecordedEvent = {
+  readonly t: number;
+  readonly type: 'open';
+  readonly protocol: string;
+} | {
+  readonly t: number;
+  readonly type: 'send' | 'message';
+  readonly data: RecordedData;
+} | {
+  readonly t: number;
+  readonly type: 'error';
+} | {
+  readonly t: number;
+  readonly type: 'close';
+  readonly code: number;
+  readonly reason: string;
+  readonly wasClean: boolean;
+};
+/** A recorded session: every connection, in the order they were opened. Plain JSON. */
+export interface WebSocketRecording {
+  readonly format: 'react-websocket-recording';
+  readonly version: 1;
+  readonly connections: readonly {
+    readonly url: string;
+    /** When it was created, from `Date.now()`. */
+    readonly at: number;
+    readonly events: readonly RecordedEvent[];
+  }[];
+}
+/** The class from {@link createRecordingWebSocket}: a `WebSocket` that records what it does. */
+export interface RecordingWebSocket extends Statics {
+  new (url: string | URL, protocols?: string | string[]): WebSocket;
+  readonly prototype: WebSocket;
+  /** Everything recorded so far, as a new plain object. */
+  recording(): WebSocketRecording;
+  /** Download the recording as a JSON file, e.g. from a "Report a problem" button. */
+  save(filename?: string): void;
+  /** Forget everything recorded so far. */
+  clear(): void;
+}
+/** Options for {@link createReplayWebSocket}. */
+export interface ReplayOptions {
+  /**
+   * How fast to replay: `1` is the recorded timing, `4` four times faster, `Infinity` as fast as
+   * possible, each event in a task of its own.
+   * @default 1
+   */
+  speed?: number;
+  /**
+   * Wait for the app to send before replaying what came after a send in the recording, so the
+   * replay follows the app instead of the clock: a server's answer comes after the question,
+   * however long the app takes to ask. `false` follows the recorded timing alone.
+   * @default true
+   */
+  waitForSends?: boolean;
+}
+/** The class from {@link createReplayWebSocket}: a `WebSocket` that plays a recording back. */
+export interface ReplayWebSocket extends Statics {
+  new (url: string | URL, protocols?: string | string[]): WebSocket;
+  readonly prototype: WebSocket;
+  /** What the app sent during the replay, by connection, as recorded data. */
+  readonly sent: readonly RecordedData[][];
+  /** Resolves once every recorded connection has been played to its end. */
+  readonly done: Promise<void>;
+  /** Start again from the first recorded connection. */
+  reset(): void;
+}
+interface Statics {
+  readonly CONNECTING: 0;
+  readonly OPEN: 1;
+  readonly CLOSING: 2;
+  readonly CLOSED: 3;
+}
+/**
+ * A `WebSocket` class that records what its connections do: when each one opened, every message
+ * sent and received, errors and closes. Pass it as the `WebSocket` option, and get the session
+ * back with `recording()`, or download it with `save()`, to attach to a bug report or replay
+ * with {@link createReplayWebSocket}.
+ *
+ * Recordings hold every message, so they can hold tokens and personal data: record in
+ * development, or ask before saving one from a user's session.
+ *
+ * @example
+ * ```ts
+ * import { createRecordingWebSocket } from 'react-websocket/replay';
+ *
+ * export const Recorder = createRecordingWebSocket();
+ * export const live = createWebSocket(url, { WebSocket: Recorder });
+ *
+ * reportButton.onclick = () => Recorder.save('session.json');
+ * ```
+ */
+export declare function createRecordingWebSocket(options?: {
+  WebSocket?: typeof WebSocket;
+}): RecordingWebSocket;
+/**
+ * A `WebSocket` class that plays a recording back, without a server: each connection the client
+ * opens replays the next recorded one, with its open, messages, errors and close, at the recorded
+ * timing or faster. For reproducing a bug report, offline demos, and UI tests that don't call a
+ * live backend, such as an AI model, on every run.
+ *
+ * By default, what came after a send in the recording waits until the app sends too, so the
+ * replay follows the app. Wrap it with `createChaosWebSocket({ WebSocket: Replay })` to add
+ * faults.
+ *
+ * @example
+ * ```ts
+ * import { createReplayWebSocket } from 'react-websocket/replay';
+ * import recording from './fixtures/chat.json';
+ *
+ * const Replay = createReplayWebSocket(recording, { speed: Infinity });
+ * render(<Chat client={createWebSocket(url, { WebSocket: Replay })} />);
+ * await Replay.done;
+ * ```
+ */
+export declare function createReplayWebSocket(recording: WebSocketRecording, options?: ReplayOptions): ReplayWebSocket;
+//#endregion
+//# sourceMappingURL=replay.d.cts.map

package/dist/replay.d.ts

@@ -0,0 +1,124 @@
+//#region src/replay.d.ts
+/** Data in a recording: text as it was, binary as base64. */
+export type RecordedData = string | {
+  readonly binary: string;
+};
+/** One event of a recorded connection, `t` ms after it was created. */
+export type RecordedEvent = {
+  readonly t: number;
+  readonly type: 'open';
+  readonly protocol: string;
+} | {
+  readonly t: number;
+  readonly type: 'send' | 'message';
+  readonly data: RecordedData;
+} | {
+  readonly t: number;
+  readonly type: 'error';
+} | {
+  readonly t: number;
+  readonly type: 'close';
+  readonly code: number;
+  readonly reason: string;
+  readonly wasClean: boolean;
+};
+/** A recorded session: every connection, in the order they were opened. Plain JSON. */
+export interface WebSocketRecording {
+  readonly format: 'react-websocket-recording';
+  readonly version: 1;
+  readonly connections: readonly {
+    readonly url: string;
+    /** When it was created, from `Date.now()`. */
+    readonly at: number;
+    readonly events: readonly RecordedEvent[];
+  }[];
+}
+/** The class from {@link createRecordingWebSocket}: a `WebSocket` that records what it does. */
+export interface RecordingWebSocket extends Statics {
+  new (url: string | URL, protocols?: string | string[]): WebSocket;
+  readonly prototype: WebSocket;
+  /** Everything recorded so far, as a new plain object. */
+  recording(): WebSocketRecording;
+  /** Download the recording as a JSON file, e.g. from a "Report a problem" button. */
+  save(filename?: string): void;
+  /** Forget everything recorded so far. */
+  clear(): void;
+}
+/** Options for {@link createReplayWebSocket}. */
+export interface ReplayOptions {
+  /**
+   * How fast to replay: `1` is the recorded timing, `4` four times faster, `Infinity` as fast as
+   * possible, each event in a task of its own.
+   * @default 1
+   */
+  speed?: number;
+  /**
+   * Wait for the app to send before replaying what came after a send in the recording, so the
+   * replay follows the app instead of the clock: a server's answer comes after the question,
+   * however long the app takes to ask. `false` follows the recorded timing alone.
+   * @default true
+   */
+  waitForSends?: boolean;
+}
+/** The class from {@link createReplayWebSocket}: a `WebSocket` that plays a recording back. */
+export interface ReplayWebSocket extends Statics {
+  new (url: string | URL, protocols?: string | string[]): WebSocket;
+  readonly prototype: WebSocket;
+  /** What the app sent during the replay, by connection, as recorded data. */
+  readonly sent: readonly RecordedData[][];
+  /** Resolves once every recorded connection has been played to its end. */
+  readonly done: Promise<void>;
+  /** Start again from the first recorded connection. */
+  reset(): void;
+}
+interface Statics {
+  readonly CONNECTING: 0;
+  readonly OPEN: 1;
+  readonly CLOSING: 2;
+  readonly CLOSED: 3;
+}
+/**
+ * A `WebSocket` class that records what its connections do: when each one opened, every message
+ * sent and received, errors and closes. Pass it as the `WebSocket` option, and get the session
+ * back with `recording()`, or download it with `save()`, to attach to a bug report or replay
+ * with {@link createReplayWebSocket}.
+ *
+ * Recordings hold every message, so they can hold tokens and personal data: record in
+ * development, or ask before saving one from a user's session.
+ *
+ * @example
+ * ```ts
+ * import { createRecordingWebSocket } from 'react-websocket/replay';
+ *
+ * export const Recorder = createRecordingWebSocket();
+ * export const live = createWebSocket(url, { WebSocket: Recorder });
+ *
+ * reportButton.onclick = () => Recorder.save('session.json');
+ * ```
+ */
+export declare function createRecordingWebSocket(options?: {
+  WebSocket?: typeof WebSocket;
+}): RecordingWebSocket;
+/**
+ * A `WebSocket` class that plays a recording back, without a server: each connection the client
+ * opens replays the next recorded one, with its open, messages, errors and close, at the recorded
+ * timing or faster. For reproducing a bug report, offline demos, and UI tests that don't call a
+ * live backend, such as an AI model, on every run.
+ *
+ * By default, what came after a send in the recording waits until the app sends too, so the
+ * replay follows the app. Wrap it with `createChaosWebSocket({ WebSocket: Replay })` to add
+ * faults.
+ *
+ * @example
+ * ```ts
+ * import { createReplayWebSocket } from 'react-websocket/replay';
+ * import recording from './fixtures/chat.json';
+ *
+ * const Replay = createReplayWebSocket(recording, { speed: Infinity });
+ * render(<Chat client={createWebSocket(url, { WebSocket: Replay })} />);
+ * await Replay.done;
+ * ```
+ */
+export declare function createReplayWebSocket(recording: WebSocketRecording, options?: ReplayOptions): ReplayWebSocket;
+//#endregion
+//# sourceMappingURL=replay.d.ts.map