@adobe/data-sync 0.9.90

package/dist/sync.test.js

@@ -0,0 +1,233 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+//
+// Soundness tests for the @adobe/data-sync protocol.
+//
+// Each test wires up a SyncServer + one or more SyncServices over loopback
+// transports and verifies convergence / correctness properties. Application
+// code only ever calls `db.transactions.X(args)` — the sync service forwards
+// envelopes transparently.
+import { describe, it, expect } from "vitest";
+import { Database, createRebaseReplayConcurrency } from "@adobe/data/ecs";
+import { createLoopbackTransport } from "./loopback-transport.js";
+import { createSyncServer } from "./create-sync-server.js";
+import { createSyncService } from "./create-sync-service.js";
+// ---------------------------------------------------------------------------
+// Shared test fixture
+// ---------------------------------------------------------------------------
+const plugin = Database.Plugin.create({
+    components: {
+        x: { type: "number", default: 0 },
+        y: { type: "number", default: 0 },
+        label: { type: "string" },
+    },
+    resources: {
+        // Synced resource — replicates to peers.
+        score: { default: 0 },
+        // Local-only resource — never replicates because of `nonPersistent: true`.
+        // (Verified by the "nonPersistent resource never replicates" test below.)
+        bannerText: { default: "", nonPersistent: true },
+        // Local + durable resource — persisted locally, but never replicated to
+        // peers because of `nonShared: true`. (Verified by the nonShared test.)
+        localPref: { default: "", nonShared: true },
+    },
+    archetypes: {
+        Point: ["x", "y", "label"],
+    },
+    transactions: {
+        createPoint(s, args) {
+            return s.archetypes.Point.insert(args);
+        },
+        movePoint(s, args) {
+            s.update(args.entity, { x: args.x, y: args.y });
+        },
+        bumpScore(s, args) {
+            s.resources.score = s.resources.score + args.delta;
+        },
+        setBanner(s, args) {
+            s.resources.bannerText = args.text;
+        },
+        setLocalPref(s, args) {
+            s.resources.localPref = args.text;
+        },
+    },
+});
+const makeDb = (userId) => Database.create(plugin, { concurrency: createRebaseReplayConcurrency(userId) });
+const snap = (db) => db.select(["x", "y", "label"])
+    .map(e => ({ entity: e, ...db.read(e) }))
+    .sort((a, b) => (a.label ?? "") < (b.label ?? "") ? -1 : 1);
+// ---------------------------------------------------------------------------
+describe("sync soundness", () => {
+    // -----------------------------------------------------------------------
+    // 1. Determinism: two clients receiving the same committed sequence converge
+    // -----------------------------------------------------------------------
+    it("two peers converge after one peer's transactions are forwarded via loopback", () => {
+        const server = createSyncServer();
+        const { client: c1t, server: s1t } = createLoopbackTransport();
+        const { client: c2t, server: s2t } = createLoopbackTransport();
+        const db1 = makeDb("peer1");
+        const db2 = makeDb("peer2");
+        server.connect(s1t);
+        server.connect(s2t);
+        const sync1 = createSyncService({ database: db1, transport: c1t });
+        // peer 2 is a passive observer — sync service alone, no transactions
+        createSyncService({ database: db2, transport: c2t });
+        db1.transactions.createPoint({ x: 1, y: 2, label: "A" });
+        db1.transactions.createPoint({ x: 3, y: 4, label: "B" });
+        // Both DBs should have the same two points with the same entity ids.
+        const snap1 = snap(db1);
+        const snap2 = snap(db2);
+        expect(snap1.length).toBe(2);
+        expect(snap2.length).toBe(2);
+        expect(snap1[0].entity).toBe(snap2[0].entity);
+        expect(snap1[1].entity).toBe(snap2[1].entity);
+        expect(snap1[0].label).toBe("A");
+        expect(snap2[0].label).toBe("A");
+        sync1.dispose();
+        server.dispose();
+    });
+    // -----------------------------------------------------------------------
+    // 2. Round-trip rebase: a local transaction is promoted from transient
+    //    to committed and the database converges.
+    // -----------------------------------------------------------------------
+    it("a local transaction is promoted to committed and the database converges", () => {
+        const server = createSyncServer();
+        const { client: ct, server: st } = createLoopbackTransport();
+        const db = makeDb("peer");
+        server.connect(st);
+        const sync = createSyncService({ database: db, transport: ct });
+        db.transactions.createPoint({ x: 10, y: 20, label: "X" });
+        const points = db.select(["label"]);
+        expect(points.length).toBe(1);
+        expect(db.read(points[0])?.label).toBe("X");
+        sync.dispose();
+        server.dispose();
+    });
+    // -----------------------------------------------------------------------
+    // 3. Concurrent inserts from two clients converge to identical entity ids.
+    // -----------------------------------------------------------------------
+    it("concurrent inserts from two peers converge to identical entity ids", () => {
+        const server = createSyncServer();
+        const { client: c1t, server: s1t } = createLoopbackTransport();
+        const { client: c2t, server: s2t } = createLoopbackTransport();
+        const db1 = makeDb("peer1");
+        const db2 = makeDb("peer2");
+        server.connect(s1t);
+        server.connect(s2t);
+        const sync1 = createSyncService({ database: db1, transport: c1t });
+        const sync2 = createSyncService({ database: db2, transport: c2t });
+        db1.transactions.createPoint({ x: 1, y: 0, label: "Alpha" });
+        db2.transactions.createPoint({ x: 2, y: 0, label: "Beta" });
+        const entityByLabel = (db, lbl) => db.select(["label"]).find(e => db.read(e)?.label === lbl);
+        expect(entityByLabel(db1, "Alpha")).toBe(entityByLabel(db2, "Alpha"));
+        expect(entityByLabel(db1, "Beta")).toBe(entityByLabel(db2, "Beta"));
+        sync1.dispose();
+        sync2.dispose();
+        server.dispose();
+    });
+    // -----------------------------------------------------------------------
+    // 4. Late-join: a peer that connects after commits have already been
+    //    made receives the full history and ends up in identical state.
+    // -----------------------------------------------------------------------
+    it("a late-joining peer receives full history and converges with existing peers", () => {
+        const server = createSyncServer();
+        const { client: c1t, server: s1t } = createLoopbackTransport();
+        const db1 = makeDb("peer1");
+        server.connect(s1t);
+        const sync1 = createSyncService({ database: db1, transport: c1t });
+        db1.transactions.createPoint({ x: 1, y: 2, label: "First" });
+        db1.transactions.createPoint({ x: 3, y: 4, label: "Second" });
+        // late peer joins AFTER both commits are already in the server log
+        const { client: c2t, server: s2t } = createLoopbackTransport();
+        const db2 = makeDb("peer2");
+        server.connect(s2t);
+        createSyncService({ database: db2, transport: c2t });
+        const snap1 = snap(db1);
+        const snap2 = snap(db2);
+        expect(snap2.length).toBe(2);
+        expect(snap2[0].entity).toBe(snap1[0].entity);
+        expect(snap2[1].entity).toBe(snap1[1].entity);
+        expect(snap2[0].label).toBe("First");
+        expect(snap2[1].label).toBe("Second");
+        sync1.dispose();
+        server.dispose();
+    });
+    // -----------------------------------------------------------------------
+    // 5. NonPersistent resource never replicates.
+    //    Red-green: this is the semantic guarantee that nonPersistent: true
+    //    resources stay local. Sync service skips envelopes whose
+    //    TransactionResult.nonPersistent === true.
+    // -----------------------------------------------------------------------
+    it("nonPersistent resource mutations are never replicated to peers", () => {
+        const server = createSyncServer();
+        const { client: c1t, server: s1t } = createLoopbackTransport();
+        const { client: c2t, server: s2t } = createLoopbackTransport();
+        const db1 = makeDb("peer1");
+        const db2 = makeDb("peer2");
+        server.connect(s1t);
+        server.connect(s2t);
+        const sync1 = createSyncService({ database: db1, transport: c1t });
+        createSyncService({ database: db2, transport: c2t });
+        db1.transactions.setBanner({ text: "private to peer1" });
+        // Local DB sees the local change.
+        expect(db1.resources.bannerText).toBe("private to peer1");
+        // Peer 2 must NOT see it.
+        expect(db2.resources.bannerText).toBe("");
+        // Sanity check: a non-nonPersistent mutation in the same session DOES replicate.
+        db1.transactions.bumpScore({ delta: 5 });
+        expect(db1.resources.score).toBe(5);
+        expect(db2.resources.score).toBe(5);
+        sync1.dispose();
+        server.dispose();
+    });
+    // -----------------------------------------------------------------------
+    // 5b. NonShared resource never replicates (but is still local + durable).
+    //     The sync service skips envelopes with no shared effect.
+    // -----------------------------------------------------------------------
+    it("nonShared resource mutations are never replicated to peers", () => {
+        const server = createSyncServer();
+        const { client: c1t, server: s1t } = createLoopbackTransport();
+        const { client: c2t, server: s2t } = createLoopbackTransport();
+        const db1 = makeDb("peer1");
+        const db2 = makeDb("peer2");
+        server.connect(s1t);
+        server.connect(s2t);
+        const sync1 = createSyncService({ database: db1, transport: c1t });
+        createSyncService({ database: db2, transport: c2t });
+        db1.transactions.setLocalPref({ text: "local to peer1" });
+        // Local DB sees the change; peer 2 must NOT.
+        expect(db1.resources.localPref).toBe("local to peer1");
+        expect(db2.resources.localPref).toBe("");
+        // Sanity: a shared mutation in the same session DOES replicate.
+        db1.transactions.bumpScore({ delta: 3 });
+        expect(db2.resources.score).toBe(3);
+        sync1.dispose();
+        server.dispose();
+    });
+    // -----------------------------------------------------------------------
+    // 6. (userId, id) compound key keeps two peers' independent local
+    //    counters from colliding on the wire.
+    // -----------------------------------------------------------------------
+    it("two peers' identical local id counters do not collide via (userId, id) compound key", () => {
+        const server = createSyncServer();
+        const { client: c1t, server: s1t } = createLoopbackTransport();
+        const { client: c2t, server: s2t } = createLoopbackTransport();
+        const db1 = makeDb("peerA");
+        const db2 = makeDb("peerB");
+        server.connect(s1t);
+        server.connect(s2t);
+        const sync1 = createSyncService({ database: db1, transport: c1t });
+        const sync2 = createSyncService({ database: db2, transport: c2t });
+        // Both peers' local id counters start at 1; if compound keying were
+        // broken these envelopes would overwrite each other in the
+        // reconciler queue and one of the entities would be lost.
+        db1.transactions.createPoint({ x: 0, y: 0, label: "FromA" });
+        db2.transactions.createPoint({ x: 0, y: 0, label: "FromB" });
+        const labels = (db) => db.select(["label"]).map(e => db.read(e)?.label).sort();
+        expect(labels(db1)).toEqual(["FromA", "FromB"]);
+        expect(labels(db2)).toEqual(["FromA", "FromB"]);
+        sync1.dispose();
+        sync2.dispose();
+        server.dispose();
+    });
+});
+//# sourceMappingURL=sync.test.js.map

package/dist/sync.test.js.map

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

package/dist/transport-onclose.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/transport-onclose.test.js

@@ -0,0 +1,74 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+//
+// Tests for SyncTransport.onClose across the loopback transport.
+// (WebRTC and WebSocket adapters are tested via their integration paths.)
+import { describe, it, expect, vi } from "vitest";
+import { createLoopbackTransport } from "./loopback-transport.js";
+describe("SyncTransport.onClose — loopback", () => {
+    it("fires listener when close() is called on client side", () => {
+        const { client } = createLoopbackTransport();
+        const fn = vi.fn();
+        client.onClose(fn);
+        expect(fn).not.toHaveBeenCalled();
+        client.close();
+        expect(fn).toHaveBeenCalledTimes(1);
+    });
+    it("fires listener when close() is called on server side", () => {
+        const { client, server } = createLoopbackTransport();
+        const fn = vi.fn();
+        client.onClose(fn);
+        server.close();
+        expect(fn).toHaveBeenCalledTimes(1);
+    });
+    it("server onClose also fires when channel closes", () => {
+        const { client, server } = createLoopbackTransport();
+        const fn = vi.fn();
+        server.onClose(fn);
+        client.close();
+        expect(fn).toHaveBeenCalledTimes(1);
+    });
+    it("fires at most once even if close() is called multiple times", () => {
+        const { client } = createLoopbackTransport();
+        const fn = vi.fn();
+        client.onClose(fn);
+        client.close();
+        client.close();
+        expect(fn).toHaveBeenCalledTimes(1);
+    });
+    it("calls listener immediately if already closed at registration time", () => {
+        const { client } = createLoopbackTransport();
+        client.close();
+        const fn = vi.fn();
+        client.onClose(fn);
+        expect(fn).toHaveBeenCalledTimes(1);
+    });
+    it("unsubscribe prevents the listener from firing", () => {
+        const { client } = createLoopbackTransport();
+        const fn = vi.fn();
+        const unsub = client.onClose(fn);
+        unsub();
+        client.close();
+        expect(fn).not.toHaveBeenCalled();
+    });
+    it("multiple listeners all fire", () => {
+        const { client } = createLoopbackTransport();
+        const fn1 = vi.fn();
+        const fn2 = vi.fn();
+        client.onClose(fn1);
+        client.onClose(fn2);
+        client.close();
+        expect(fn1).toHaveBeenCalledTimes(1);
+        expect(fn2).toHaveBeenCalledTimes(1);
+    });
+    it("messages can be exchanged before close fires", () => {
+        const { client, server } = createLoopbackTransport();
+        const received = [];
+        server.onMessage((msg) => received.push(msg));
+        client.send({ kind: "cancel", id: 1 });
+        expect(received).toHaveLength(1);
+        client.close();
+        // No more messages after close
+        expect(received).toHaveLength(1);
+    });
+});
+//# sourceMappingURL=transport-onclose.test.js.map

package/dist/transport-onclose.test.js.map

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

package/dist/transport.d.ts

@@ -0,0 +1,94 @@
+import type { TransactionEnvelope } from "@adobe/data/ecs";
+/**
+ * Messages flowing from server → client (broadcasts).
+ *
+ * - `committed`  — an envelope has been accepted by the server and assigned a
+ *   canonical wall-clock `time`. Every client must apply this in the order it
+ *   is received; the `time` values are monotonically increasing per session.
+ * - `cancelled`  — an envelope the server received was rejected (e.g. auth
+ *   failure, validation error). Clients that hold a matching transient should
+ *   roll it back.
+ * - `welcome`    — response to `hello`. Sent before any replay. When
+ *   `resetRequired` is true the client must wipe its database before applying
+ *   the full replay that follows; when false the server will replay only the
+ *   tail since `lastAppliedTime`.
+ * - `pong`       — keep-alive reply to a client `ping`. Carries no payload;
+ *   its only purpose is to refresh the client's liveness deadline and keep
+ *   intermediate NAT mappings warm.
+ */
+export type ServerMessage = {
+    readonly kind: "committed";
+    readonly envelope: TransactionEnvelope;
+} | {
+    readonly kind: "cancelled";
+    readonly id: number;
+    readonly reason?: string;
+} | {
+    readonly kind: "welcome";
+    readonly sessionId: string;
+    readonly resetRequired: boolean;
+} | {
+    readonly kind: "pong";
+};
+/**
+ * Messages flowing from client → server (proposals).
+ *
+ * - `propose`    — client wants to commit an operation. The envelope's `time`
+ *   must be negative (transient) when sent; the server assigns the final time.
+ * - `intermediate` — speculative state the client wants other clients to see
+ *   (e.g. cursor position, dragging). Servers may broadcast these as-is or
+ *   drop/throttle them; they are never persisted.
+ * - `cancel`     — client withdraws a previously proposed envelope.
+ * - `hello`      — sent exactly once per connection, immediately after wiring.
+ *   Carries the client's prior `sessionId` (omit for a fresh client) and the
+ *   highest committed `time` already applied locally. The server responds with
+ *   `welcome` and replays only what the client is missing.
+ * - `ping`       — keep-alive probe. The server replies with `pong` and uses
+ *   the receipt to refresh its per-client liveness deadline. Pings carry no
+ *   payload and are independent of the hello/welcome handshake.
+ */
+export type ClientMessage = {
+    readonly kind: "propose";
+    readonly envelope: TransactionEnvelope;
+} | {
+    readonly kind: "intermediate";
+    readonly envelope: TransactionEnvelope;
+} | {
+    readonly kind: "cancel";
+    readonly id: number;
+} | {
+    readonly kind: "hello";
+    readonly sessionId?: string;
+    readonly lastAppliedTime: number;
+} | {
+    readonly kind: "ping";
+};
+/**
+ * Runtime-agnostic, bidirectional message channel.
+ *
+ * Implementations are provided for:
+ *   - in-process loopback (testing / single-tab)
+ *   - WebSocket (browser ↔ Node.js)
+ *
+ * The transport does not own serialization — callers pass structured objects.
+ * Ordering of `send` calls is preserved; delivery is assumed reliable (use a
+ * reliable transport like WebSocket, not UDP, for the committed stream).
+ */
+export interface SyncTransport<Send, Receive> {
+    /** Send a message to the remote end. */
+    readonly send: (msg: Send) => void;
+    /** Register a listener that will receive messages from the remote end. */
+    readonly onMessage: (listener: (msg: Receive) => void) => () => void;
+    /**
+     * Register a listener that fires once when the channel closes — whether
+     * due to a remote close, network drop, or a local `close()` call.
+     * Returns an unsubscribe function. Firing is idempotent (at most once).
+     */
+    readonly onClose: (listener: () => void) => () => void;
+    /** Tear down the channel. */
+    readonly close: () => void;
+}
+/** Transport from the client's perspective. */
+export type ClientTransport = SyncTransport<ClientMessage, ServerMessage>;
+/** Transport from the server's perspective (per connected client). */
+export type ServerTransport = SyncTransport<ServerMessage, ClientMessage>;

package/dist/transport.js

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export {};
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,uDAAuD"}

package/dist/websocket-transport.d.ts

@@ -0,0 +1,71 @@
+import type { ClientTransport, ServerTransport } from "./transport.js";
+/**
+ * Options for {@link createWebSocketClientTransport}.
+ */
+export interface WebSocketClientTransportOptions {
+    /**
+     * WebSocket URL to connect to (e.g. `"ws://localhost:4000/sync"`).
+     */
+    readonly url: string;
+    /**
+     * Optional WebSocket constructor override for environments that do not have
+     * a global `WebSocket` (Node.js < 22). Pass `require("ws")` or a polyfill.
+     */
+    readonly WebSocket?: typeof globalThis.WebSocket;
+    /**
+     * Called when the connection opens. Use to send an initial handshake if
+     * needed (e.g. authentication token).
+     */
+    readonly onOpen?: (ws: globalThis.WebSocket) => void;
+    /** Called when the connection closes (clean or error). */
+    readonly onClose?: (event: CloseEvent) => void;
+}
+/**
+ * Creates a {@link ClientTransport} backed by a WebSocket connection.
+ *
+ * The connection is established immediately. Messages sent before the socket
+ * is open are buffered and flushed on connect. Closing the transport closes
+ * the socket with code 1000 (normal closure).
+ *
+ * Works in browsers (native `WebSocket`) and in Node.js 22+ (global
+ * `WebSocket`). For earlier Node.js, pass `options.WebSocket = require("ws")`.
+ *
+ * @example
+ * ```ts
+ * const transport = createWebSocketClientTransport({ url: "ws://localhost:4000/sync" });
+ * const sync = createSyncService({ database: myDb, transport });
+ * ```
+ */
+export declare const createWebSocketClientTransport: (options: WebSocketClientTransportOptions) => ClientTransport;
+/**
+ * Minimal interface for an already-open WebSocket connection on the server
+ * side. Compatible with the browser `WebSocket` API and the `ws` npm package.
+ */
+export interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string): void;
+    addEventListener(event: "message", handler: (event: {
+        data: string;
+    }) => void): void;
+    addEventListener(event: "close", handler: () => void): void;
+    removeEventListener(event: string, handler: (...args: any[]) => void): void;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Wraps an already-accepted `WebSocket` connection into a {@link ServerTransport}.
+ *
+ * Call this inside your WebSocket server's "connection" handler:
+ *
+ * ```ts
+ * const server = createSyncServer();
+ *
+ * // With the `ws` package:
+ * const wss = new WebSocketServer({ port: 4000 });
+ * wss.on("connection", (ws) => {
+ *   const transport = createWebSocketServerTransport(ws);
+ *   const disconnect = server.connect(transport);
+ *   ws.on("close", disconnect);
+ * });
+ * ```
+ */
+export declare const createWebSocketServerTransport: (ws: WebSocketLike) => ServerTransport;

package/dist/websocket-transport.js

@@ -0,0 +1,148 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// ---------------------------------------------------------------------------
+// Serialization helpers
+// ---------------------------------------------------------------------------
+const encode = (msg) => JSON.stringify(msg);
+const decode = (raw) => JSON.parse(raw);
+/**
+ * Creates a {@link ClientTransport} backed by a WebSocket connection.
+ *
+ * The connection is established immediately. Messages sent before the socket
+ * is open are buffered and flushed on connect. Closing the transport closes
+ * the socket with code 1000 (normal closure).
+ *
+ * Works in browsers (native `WebSocket`) and in Node.js 22+ (global
+ * `WebSocket`). For earlier Node.js, pass `options.WebSocket = require("ws")`.
+ *
+ * @example
+ * ```ts
+ * const transport = createWebSocketClientTransport({ url: "ws://localhost:4000/sync" });
+ * const sync = createSyncService({ database: myDb, transport });
+ * ```
+ */
+export const createWebSocketClientTransport = (options) => {
+    const WS = options.WebSocket ?? globalThis.WebSocket;
+    const ws = new WS(options.url);
+    const listeners = new Set();
+    const closeListeners = new Set();
+    const pendingOutbound = [];
+    let closed = false;
+    const fireClose = () => {
+        if (closed)
+            return;
+        closed = true;
+        for (const l of closeListeners)
+            l();
+        closeListeners.clear();
+    };
+    ws.addEventListener("open", () => {
+        options.onOpen?.(ws);
+        for (const msg of pendingOutbound)
+            ws.send(msg);
+        pendingOutbound.length = 0;
+    });
+    ws.addEventListener("message", (event) => {
+        const msg = decode(event.data);
+        for (const l of listeners)
+            l(msg);
+    });
+    ws.addEventListener("close", (event) => {
+        options.onClose?.(event);
+        fireClose();
+    });
+    return {
+        send(msg) {
+            const encoded = encode(msg);
+            if (ws.readyState === ws.OPEN) {
+                ws.send(encoded);
+            }
+            else {
+                pendingOutbound.push(encoded);
+            }
+        },
+        onMessage(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        onClose(listener) {
+            if (closed) {
+                listener();
+                return () => undefined;
+            }
+            closeListeners.add(listener);
+            return () => closeListeners.delete(listener);
+        },
+        close() {
+            fireClose();
+            listeners.clear();
+            if (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING) {
+                ws.close(1000, "client disposed");
+            }
+        },
+    };
+};
+/**
+ * Wraps an already-accepted `WebSocket` connection into a {@link ServerTransport}.
+ *
+ * Call this inside your WebSocket server's "connection" handler:
+ *
+ * ```ts
+ * const server = createSyncServer();
+ *
+ * // With the `ws` package:
+ * const wss = new WebSocketServer({ port: 4000 });
+ * wss.on("connection", (ws) => {
+ *   const transport = createWebSocketServerTransport(ws);
+ *   const disconnect = server.connect(transport);
+ *   ws.on("close", disconnect);
+ * });
+ * ```
+ */
+export const createWebSocketServerTransport = (ws) => {
+    const listeners = new Set();
+    const closeListeners = new Set();
+    let closed = false;
+    const fireClose = () => {
+        if (closed)
+            return;
+        closed = true;
+        for (const l of closeListeners)
+            l();
+        closeListeners.clear();
+    };
+    const messageHandler = (event) => {
+        const msg = decode(event.data);
+        for (const l of listeners)
+            l(msg);
+    };
+    ws.addEventListener("message", messageHandler);
+    ws.addEventListener("close", fireClose);
+    return {
+        send(msg) {
+            if (ws.readyState === 1 /* OPEN */) {
+                ws.send(encode(msg));
+            }
+        },
+        onMessage(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        onClose(listener) {
+            if (closed) {
+                listener();
+                return () => undefined;
+            }
+            closeListeners.add(listener);
+            return () => closeListeners.delete(listener);
+        },
+        close() {
+            fireClose();
+            ws.removeEventListener("message", messageHandler);
+            listeners.clear();
+            if (ws.readyState === 1) {
+                ws.close(1000, "server transport disposed");
+            }
+        },
+    };
+};
+//# sourceMappingURL=websocket-transport.js.map