@evolu/common 7.4.1 → 8.0.0-next.1

package/dist/src/WebSocket.js

@@ -1,131 +1,292 @@
-import { err, ok } from "./Result.js";
-import { retry } from "./Task.js";
-import { maxPositiveInt } from "./Type.js";
 /**
- * Create a new {@link WebSocket}.
- *
- * The default behavior is that WebSocket tries to reconnect repeatedly in case
- * the application is offline, because online events (both web and native) are
- * not reliable. Once it connects and the connection is closed, it tries to
- * reconnect again. Retrying the connection can be controlled using the
- * retryOptions retryable predicate.
- *
- * ### How Binary Messages Work in WebSockets
- *
- * The Server Chooses the Message Type:
- *
- * - Text (0x1) → Sent as UTF-8 encoded text (always received as a string in the
- *   browser).
- * - Binary (0x2) → Sent as raw binary data (received as a Blob or ArrayBuffer,
- *   depending on binaryType).
+ * WebSocket with auto-reconnect.
  *
- * The Client's binaryType Controls How Binary Data is Processed:
- *
- * - If the server sends a text frame (0x1), the browser always delivers
- *   event.data as a string, regardless of binaryType.
- * - If the server sends a binary frame (0x2), the browser delivers event.data as:
- *
- *   - A Blob (default: "blob")
- *   - An ArrayBuffer ("arraybuffer")
- *
- * ### Example
- *
- * TODO:
+ * @module
  */
-export const createWebSocket = (url, { protocols, binaryType, onOpen, onClose, onMessage, onError, retryOptions, WebSocketConstructor = globalThis.WebSocket, } = {}) => {
-    let isDisposed = false;
-    const reconnectController = new AbortController();
-    const defaultRetryOptions = {
-        retries: maxPositiveInt, // Practically infinite retries
-    };
-    let socket = null;
-    const disposeSocket = () => {
-        if (!socket)
-            return;
-        // Remove all listeners before closing
-        socket.onopen = null;
-        socket.onclose = null;
-        socket.onmessage = null;
-        socket.onerror = null;
-        if (socket.readyState !== socket.CLOSING &&
-            socket.readyState !== socket.CLOSED) {
-            socket.close();
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
         }
-        socket = null;
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
     };
-    // To prevent a memory leak from pending connection promise.
-    let disposePromise = null;
-    /**
-     * This promise represents continuous connection which:
-     *
-     * - Is rejected when a connection cannot be established.
-     * - Is rejected when a connection is closed.
-     * - Is resolved when WebSocket is disposed().
-     */
-    void retry({
-        ...defaultRetryOptions,
-        ...retryOptions,
-    }, () => new Promise((resolve) => {
-        disposePromise = () => {
-            resolve(ok());
-        };
-        if (isDisposed)
-            disposePromise();
-        disposeSocket();
-        socket = new WebSocketConstructor(url, protocols);
-        if (binaryType)
-            socket.binaryType = binaryType;
-        let isOpen = false;
-        socket.onopen = () => {
-            isOpen = true;
-            onOpen?.();
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { assert } from "./Assert.js";
+import { lazyTrue } from "./Function.js";
+import { err, ok } from "./Result.js";
+import { exponential, jitter, maxDelay } from "./Schedule.js";
+import { callback, retry } from "./Task.js";
+import { ArrayBuffer, String, Uint8Array } from "./Type.js";
+/** Create a new {@link WebSocket}. */
+export const createWebSocket = (url, { protocols, binaryType, onOpen, onClose, shouldRetryOnClose = lazyTrue, onMessage, onError, schedule = jitter(1)(maxDelay("30s")(exponential("100ms"))), WebSocketConstructor = globalThis.WebSocket, } = {}) => async (run) => {
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
+        const stack = __addDisposableResource(env_1, new AsyncDisposableStack(), true);
+        let socket = null;
+        const closeSocket = () => {
+            if (!socket)
+                return;
+            socket.onopen = null;
+            socket.onclose = null;
+            socket.onmessage = null;
+            socket.onerror = null;
+            if (socket.readyState !== socket.CLOSING &&
+                socket.readyState !== socket.CLOSED) {
+                socket.close();
+            }
+            socket = null;
         };
-        socket.onerror = (event) => {
-            const error = isOpen
-                ? { type: "WebSocketConnectionError", event }
-                : { type: "WebSocketConnectError", event };
-            onError?.(error);
-            // Trigger reconnect only on WebSocketConnectError.
-            if (error.type === "WebSocketConnectError") {
-                resolve(err(error));
+        /**
+         * A task that connects and stays connected until the connection closes or
+         * errors. Returns error to trigger retry.
+         */
+        const connect = callback(({ err, ok }) => {
+            closeSocket();
+            socket = new WebSocketConstructor(url, String.is(protocols) ? protocols : protocols && [...protocols]);
+            if (binaryType)
+                socket.binaryType = binaryType;
+            let isOpen = false;
+            socket.onopen = () => {
+                isOpen = true;
+                onOpen?.();
+            };
+            socket.onclose = (event) => {
+                onClose?.(event);
+                if (shouldRetryOnClose(event)) {
+                    err({ type: "WebSocketConnectionCloseError", event });
+                }
+                else {
+                    ok();
+                }
+            };
+            socket.onmessage = (event) => {
+                onMessage?.(event.data);
+            };
+            socket.onerror = (event) => {
+                const error = isOpen
+                    ? { type: "WebSocketConnectionError", event }
+                    : { type: "WebSocketConnectError", event };
+                onError?.(error);
+                if (error.type === "WebSocketConnectError")
+                    err(error);
+            };
+            return closeSocket;
+        });
+        const retryFiber = stack.use(run.daemon(retry(connect, schedule)));
+        // Report RetryError (schedule exhausted) via onError callback
+        void retryFiber.then((result) => {
+            if (!result.ok && result.error.type === "RetryError") {
+                onError?.(result.error);
             }
+        });
+        const moved = stack.move();
+        return ok({
+            send: (data) => {
+                // https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send
+                if (!socket || socket.readyState === socket.CONNECTING) {
+                    return err({ type: "WebSocketSendError" });
+                }
+                socket.send(ensureSendableData(data));
+                return ok();
+            },
+            getReadyState: () => {
+                if (moved.disposed)
+                    return "closed";
+                return socket ? nativeToStringState[socket.readyState] : "connecting";
+            },
+            isOpen: () => !moved.disposed && socket?.readyState === globalThis.WebSocket.OPEN,
+            [Symbol.asyncDispose]: () => moved.disposeAsync(),
+        });
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        const result_1 = __disposeResources(env_1);
+        if (result_1)
+            await result_1;
+    }
+};
+/** Clones SharedArrayBuffer-backed Uint8Array values before WebSocket.send. */
+const ensureSendableData = (data) => {
+    if (!Uint8Array.is(data))
+        return data;
+    return ArrayBuffer.is(data.buffer)
+        ? data
+        : new globalThis.Uint8Array(data);
+};
+const nativeToStringState = {
+    [globalThis.WebSocket.CONNECTING]: "connecting",
+    [globalThis.WebSocket.OPEN]: "open",
+    [globalThis.WebSocket.CLOSING]: "closing",
+    [globalThis.WebSocket.CLOSED]: "closed",
+};
+/** Creates {@link TestCreateWebSocket}. */
+export const testCreateWebSocket = (options = {}) => {
+    const createdUrls = [];
+    const sentMessages = [];
+    const stateByUrl = new Map();
+    const getState = (url) => {
+        const state = stateByUrl.get(url);
+        assert(state, `Test WebSocket for ${url} does not exist.`);
+        return state;
+    };
+    const createWebSocket = (url, socketOptions) => () => {
+        if (options.throwOnCreate) {
+            throw new Error("testCreateWebSocket is configured to throw on create");
+        }
+        createdUrls.push(url);
+        stateByUrl.set(url, {
+            options: socketOptions,
+            isOpen: options.isOpen ?? true,
+            isDisposed: false,
+        });
+        return ok({
+            send: (data) => {
+                const state = getState(url);
+                if (state.isDisposed || !state.isOpen) {
+                    return err({ type: "WebSocketSendError" });
+                }
+                sentMessages.push({
+                    url,
+                    data: ensureSendableData(data),
+                });
+                return ok();
+            },
+            getReadyState: () => {
+                const state = getState(url);
+                if (state.isDisposed)
+                    return "closed";
+                return state.isOpen ? "open" : "closed";
+            },
+            isOpen: () => {
+                const state = getState(url);
+                return !state.isDisposed && state.isOpen;
+            },
+            [Symbol.asyncDispose]: () => {
+                const state = getState(url);
+                state.isDisposed = true;
+                state.isOpen = false;
+                return Promise.resolve();
+            },
+        });
+    };
+    return Object.assign(createWebSocket, {
+        createdUrls,
+        sentMessages,
+        message: (url, data) => {
+            getState(url).options?.onMessage?.(data);
+        },
+        open: (url) => {
+            const state = getState(url);
+            state.isOpen = true;
+            state.options?.onOpen?.();
+        },
+    });
+};
+/** Opens a native {@link WebSocket} and returns {@link TestSetupWebSocket}. */
+export const testSetupWebSocket = async (url) => {
+    const socket = new globalThis.WebSocket(url);
+    socket.binaryType = "arraybuffer";
+    await new Promise((resolve, reject) => {
+        const onOpen = () => {
+            cleanup();
+            resolve();
         };
-        socket.onclose = (event) => {
-            onClose?.(event);
-            resolve(err({ type: "WebSocketConnectionCloseError", event }));
+        const onError = () => {
+            cleanup();
+            socket.close();
+            reject(new Error("WebSocket connection failed"));
         };
-        socket.onmessage = (event) => {
-            onMessage?.(event.data);
+        const cleanup = () => {
+            socket.removeEventListener("open", onOpen);
+            socket.removeEventListener("error", onError);
         };
-    }))(reconnectController).then((result) => {
-        if (result.ok || result.error.type === "AbortError")
-            return;
-        onError?.(result.error);
+        socket.addEventListener("open", onOpen, { once: true });
+        socket.addEventListener("error", onError, { once: true });
     });
     return {
+        socket,
         send: (data) => {
-            // https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send
-            if (!socket || socket.readyState === socket.CONNECTING) {
-                return err({ type: "WebSocketSendError" });
-            }
-            socket.send(data);
-            return ok();
+            socket.send(ensureSendableData(data));
         },
-        getReadyState: () => socket ? nativeToStringState[socket.readyState] : "connecting",
-        isOpen: () => (socket ? socket.readyState === socket.OPEN : false),
-        [Symbol.dispose]() {
-            if (isDisposed)
+        waitForMessage: () => new Promise((resolve, reject) => {
+            if (socket.readyState === globalThis.WebSocket.CLOSED) {
+                reject(new Error("WebSocket closed before message"));
                 return;
-            isDisposed = true;
-            reconnectController.abort();
-            disposeSocket();
-            disposePromise?.();
+            }
+            const onMessage = (event) => {
+                cleanup();
+                if (typeof event.data === "string") {
+                    resolve(event.data);
+                    return;
+                }
+                resolve(new globalThis.Uint8Array(event.data));
+            };
+            const onClose = () => {
+                cleanup();
+                reject(new Error("WebSocket closed before message"));
+            };
+            const cleanup = () => {
+                socket.removeEventListener("message", onMessage);
+                socket.removeEventListener("close", onClose);
+            };
+            socket.addEventListener("message", onMessage, { once: true });
+            socket.addEventListener("close", onClose, { once: true });
+        }),
+        [Symbol.asyncDispose]: async () => {
+            if (socket.readyState === globalThis.WebSocket.CLOSED)
+                return;
+            const closed = new Promise((resolve) => {
+                socket.addEventListener("close", () => resolve(), { once: true });
+            });
+            socket.close();
+            await closed;
         },
     };
 };
-const nativeToStringState = {
-    [WebSocket.CONNECTING]: "connecting",
-    [WebSocket.OPEN]: "open",
-    [WebSocket.CLOSING]: "closing",
-    [WebSocket.CLOSED]: "closed",
-};