@reatomized/convex 0.0.0-stage → 0.1.1

package/dist/browser/reatom/client.js

@@ -0,0 +1,1138 @@
+/**
+ * A Convex sync client whose state lives in Reatom atoms.
+ *
+ * The query set is the set of connected query atoms: reading a query's
+ * `result` in a subscribed graph subscribes it on the server, and losing the
+ * last reader unsubscribes it. Query set changes made in one microtask go out
+ * as one `ModifyQuerySet`. A server transition updates only the queries it
+ * names; optimistic updates are replayed only while some are pending.
+ *
+ * State is per Reatom context: call the client's methods inside a frame of
+ * the context that owns it.
+ */
+import { action, atom, computed, context, noop, peek, wrap, } from "@reatom/core";
+import { version } from "../../index.js";
+import { parseArgs, validateDeploymentUrl } from "../../common/index.js";
+import { getFunctionName, } from "convex/server";
+import { convexToJson, jsonToConvex } from "convex/values";
+import { jwtDecode } from "../../vendor/jwt-decode/index.js";
+import { Long } from "../../vendor/long.js";
+import { instantiateDefaultLogger, instantiateNoopLogger, logFatalError, logForFunction, } from "../logging.js";
+import { getMarksReport, mark as markPerformance, } from "../sync/metrics.js";
+import { newSessionId } from "../sync/session.js";
+import { canonicalizeUdfPath, serializePaginatedPathAndArgs, } from "../sync/udf_path_utils.js";
+import { reatomAuth } from "./auth.js";
+import { withConnectionHooks } from "./connection_hooks.js";
+import { functionError } from "./errors.js";
+import { OptimisticLocalStoreImpl, } from "./optimistic.js";
+import { reatomPaginatedQuery, } from "./paginated.js";
+import { reatomSocket } from "./socket.js";
+const functionName = (ref) => typeof ref === "string" ? ref : getFunctionName(ref);
+const INITIAL_VERSION = {
+    querySet: 0,
+    ts: Long.fromNumber(0),
+    identity: 0,
+};
+/** Entries by token, held weakly where the runtime allows it. */
+class WeakCache {
+    refs = new Map();
+    registry = typeof FinalizationRegistry === "undefined"
+        ? null
+        : new FinalizationRegistry((token) => {
+            if (!this.refs.get(token)?.deref())
+                this.refs.delete(token);
+        });
+    get(token) {
+        return this.refs.get(token)?.deref();
+    }
+    set(value) {
+        if (typeof WeakRef === "undefined") {
+            this.refs.set(value.token, { deref: () => value });
+            return;
+        }
+        this.refs.set(value.token, new WeakRef(value));
+        this.registry?.register(value, value.token);
+    }
+    /** Forgets an unused value where it can't be collected. */
+    release(value) {
+        if (typeof WeakRef === "undefined" && this.get(value.token) === value) {
+            this.refs.delete(value.token);
+        }
+    }
+}
+function webSocketUri(address) {
+    const i = address.search("://");
+    if (i === -1) {
+        throw new Error("Provided address was not an absolute URL.");
+    }
+    const origin = address.substring(i + 3);
+    const protocol = address.substring(0, i);
+    let wsProtocol;
+    if (protocol === "http") {
+        wsProtocol = "ws";
+    }
+    else if (protocol === "https") {
+        wsProtocol = "wss";
+    }
+    else {
+        throw new Error(`Unknown parent protocol ${protocol}`);
+    }
+    return `${wsProtocol}://${origin}/api/${version}/sync`;
+}
+/**
+ * Create a Convex client whose state lives in Reatom atoms.
+ *
+ * The client connects on first use in a context: a query read, a request,
+ * `setAuth` or a `connectionState` subscriber. Call its methods inside a
+ * Reatom frame; each context gets its own connection.
+ *
+ * ```ts
+ * const convex = reatomConvexClient(import.meta.env.VITE_CONVEX_URL);
+ * const notes = computed(() => convex.query(api.notes.list, {}).data());
+ * ```
+ *
+ * @param address - The url of your Convex deployment, e.g.
+ * `https://small-mouse-123.convex.cloud`.
+ * @param options - See {@link BaseConvexClientOptions}.
+ * @param name - A prefix for the client's atom names.
+ *
+ * @public
+ */
+export function reatomConvexClient(address, options = {}, name = "convex") {
+    if (typeof address === "object") {
+        throw new Error("Passing a ClientConfig object is no longer supported. Pass the URL of the Convex deployment as a string directly.");
+    }
+    if (options.skipConvexDeploymentUrlCheck !== true) {
+        validateDeploymentUrl(address);
+    }
+    if (!options.webSocketConstructor && typeof WebSocket === "undefined") {
+        throw new Error("No WebSocket global variable defined! To use Convex in an environment without WebSocket try the HTTP client: https://docs.convex.dev/api/classes/browser.ConvexHttpClient");
+    }
+    const webSocketConstructor = options.webSocketConstructor || WebSocket;
+    const debug = options.reportDebugInfoToConvex ?? false;
+    const logger = options.logger === false
+        ? instantiateNoopLogger({ verbose: options.verbose ?? false })
+        : options.logger !== true && options.logger
+            ? options.logger
+            : instantiateDefaultLogger({ verbose: options.verbose ?? false });
+    const wsUri = webSocketUri(address);
+    const hasWindow = typeof window !== "undefined" &&
+        typeof window.addEventListener !== "undefined";
+    if (!hasWindow && options.unsavedChangesWarning === true) {
+        throw new Error("unsavedChangesWarning requested, but window.addEventListener not found! Remove {unsavedChangesWarning: true} from Convex client options.");
+    }
+    const querySetVersion = atom(0, `${name}.querySetVersion`);
+    const identityVersion = atom(0, `${name}.identityVersion`);
+    /** The version of the query results received on the current connection. */
+    const remoteVersion = atom(INITIAL_VERSION, `${name}.remoteVersion`);
+    const maxObservedTimestamp = atom(undefined, `${name}.maxObservedTimestamp`);
+    /** The token the server is told about. */
+    const authToken = atom(undefined, `${name}.authToken`);
+    /**
+     * Server side of the two-phase auth: `null` while a token waits for the
+     * server, then whether it accepted it. `false` without auth.
+     */
+    const isAuthenticated = atom(false, `${name}.isAuthenticated`);
+    /** The server rejected a confirmed token and a replacement is being fetched. */
+    const isRefreshingAuth = atom(false, `${name}.isRefreshingAuth`);
+    /** Mutations and actions sent or waiting to be sent. */
+    const requests = atom(new Map(), `${name}.requests`);
+    /** Optimistic updates of mutations the client has not seen reflected yet. */
+    const optimisticUpdates = atom([], `${name}.optimisticUpdates`);
+    const runtime = atom(() => ({
+        root: context(),
+        started: false,
+        closed: false,
+        sessionId: newSessionId(),
+        entries: new WeakCache(),
+        paginated: new WeakCache(),
+        byId: new Map(),
+        nextQueryId: 0,
+        pending: new Map(),
+        flushScheduled: false,
+        flush: noop,
+        paused: false,
+        outstandingQueriesOlderThanRestart: new Set(),
+        outstandingAuthOlderThanRestart: false,
+        clearAuthOnResume: false,
+        requestsOlderThanRestart: new Set(),
+        overlay: new Map(),
+        nextRequestId: 0,
+        firstMessageReceived: false,
+        transitionHandlers: new Set(),
+        onBeforeUnload: null,
+    }), `${name}._runtime`);
+    const lookup = (token) => peek(runtime).entries.get(token);
+    /** Shows `raw` behind `entry.result`; returns whether it changed. */
+    const setVisible = (entry, raw) => {
+        if (entry.visible === raw)
+            return false;
+        entry.visible = raw;
+        entry.result.set(raw);
+        return true;
+    };
+    const emitTransition = (transition) => {
+        const handlers = peek(runtime).transitionHandlers;
+        if (handlers.size === 0)
+            return;
+        const value = transition();
+        for (const handler of handlers)
+            handler(value);
+    };
+    const mark = (markName) => {
+        if (debug)
+            markPerformance(markName, peek(runtime).sessionId);
+    };
+    // Optimistic updates
+    const serverResults = {
+        get(token) {
+            const entry = lookup(token);
+            return entry?.id === null ? undefined : entry?.server;
+        },
+        *all() {
+            for (const entry of peek(runtime).byId.values()) {
+                if (entry.server === undefined)
+                    continue;
+                yield {
+                    token: entry.token,
+                    udfPath: entry.udfPath,
+                    args: entry.args,
+                    result: entry.server,
+                };
+            }
+        },
+    };
+    /**
+     * Shows the server results of `changed` under the optimistic updates still
+     * pending, dropping those of `completed` requests.
+     */
+    const ingest = (changed, completed, 
+    // Queries the server removed: shown, but not reported, as in convex@1.48.0.
+    removed = new Set()) => {
+        const rt = peek(runtime);
+        let updates = optimisticUpdates();
+        if (completed.size > 0 && updates.length > 0) {
+            updates = optimisticUpdates.set(updates.filter(({ mutationId }) => !completed.has(mutationId)));
+        }
+        const queries = [];
+        const show = (entry, raw) => {
+            if (setVisible(entry, raw) && !removed.has(entry)) {
+                queries.push({
+                    token: entry.token,
+                    modification: { kind: "Updated", result: raw },
+                });
+            }
+        };
+        if (updates.length === 0 && rt.overlay.size === 0) {
+            for (const entry of changed)
+                show(entry, entry.server);
+        }
+        else {
+            const previous = rt.overlay;
+            const overlay = (rt.overlay = new Map());
+            const store = new OptimisticLocalStoreImpl(overlay, serverResults);
+            for (const { update } of updates)
+                update(store);
+            const tokens = new Set([...previous.keys(), ...overlay.keys()]);
+            for (const entry of changed)
+                tokens.add(entry.token);
+            for (const token of tokens) {
+                const entry = lookup(token);
+                const local = overlay.get(token);
+                if (entry) {
+                    show(entry, local ? local.result : entry.server);
+                }
+                else if (local && local.result !== previous.get(token)?.result) {
+                    queries.push({
+                        token,
+                        modification: { kind: "Updated", result: local.result },
+                    });
+                }
+            }
+        }
+        emitTransition(() => ({
+            queries,
+            reflectedMutations: Array.from(completed, ([requestId, result]) => ({
+                requestId,
+                result,
+            })),
+            timestamp: remoteVersion().ts,
+        }));
+    };
+    const applyOptimisticUpdate = (update, mutationId) => {
+        optimisticUpdates.set((list) => [...list, { update, mutationId }]);
+        const { overlay } = peek(runtime);
+        const store = new OptimisticLocalStoreImpl(overlay, serverResults);
+        update(store);
+        const queries = [];
+        for (const token of store.modifiedQueries) {
+            const local = overlay.get(token);
+            const entry = lookup(token);
+            if (entry)
+                setVisible(entry, local.result);
+            queries.push({
+                token,
+                modification: { kind: "Updated", result: local.result },
+            });
+        }
+        emitTransition(() => ({
+            queries,
+            reflectedMutations: [],
+            timestamp: remoteVersion().ts,
+        }));
+    };
+    // Query set
+    const addQuery = (entry) => ({
+        type: "Add",
+        queryId: entry.id,
+        udfPath: entry.udfPath,
+        args: [convexToJson(entry.args)],
+        journal: entry.journal,
+        componentPath: entry.componentPath,
+    });
+    /** The server no longer has `entry`, or never will. */
+    const forget = (entry) => {
+        const { rt } = entry;
+        rt.byId.delete(entry.id);
+        rt.outstandingQueriesOlderThanRestart.delete(entry.id);
+        entry.id = null;
+        entry.op = null;
+        entry.server = undefined;
+        entry.journal = undefined;
+        setVisible(entry, rt.overlay.get(entry.token)?.result);
+        rt.entries.release(entry);
+    };
+    const takePending = (rt) => {
+        const modifications = [];
+        for (const entry of rt.pending.values()) {
+            if (entry.op === "Add") {
+                modifications.push(addQuery(entry));
+                entry.op = null;
+            }
+            else {
+                modifications.push({ type: "Remove", queryId: entry.id });
+                forget(entry);
+            }
+        }
+        rt.pending.clear();
+        return modifications;
+    };
+    const flush = () => {
+        const rt = peek(runtime);
+        rt.flushScheduled = false;
+        if (rt.pending.size === 0 || rt.paused || rt.closed)
+            return;
+        const baseVersion = querySetVersion();
+        const modification = {
+            type: "ModifyQuerySet",
+            baseVersion,
+            newVersion: baseVersion + 1,
+            modifications: takePending(rt),
+        };
+        querySetVersion.set(baseVersion + 1);
+        socket.send(modification);
+    };
+    const scheduleFlush = (rt) => {
+        if (rt.flushScheduled)
+            return;
+        rt.flushScheduled = true;
+        if (rt.flush === noop)
+            rt.flush = wrap(flush, rt.root);
+        queueMicrotask(rt.flush);
+    };
+    const connectEntry = (entry) => {
+        const { rt } = entry;
+        if (!rt.started)
+            start();
+        if (rt.closed)
+            return;
+        // Resubscribed before its removal went out: the server still has it.
+        if (entry.op === "Remove") {
+            entry.op = null;
+            rt.pending.delete(entry.id);
+            return;
+        }
+        const queryId = rt.nextQueryId++;
+        entry.id = queryId;
+        entry.op = "Add";
+        rt.byId.set(queryId, entry);
+        rt.pending.set(queryId, entry);
+        scheduleFlush(rt);
+    };
+    const disconnectEntry = (entry) => {
+        const { rt } = entry;
+        if (entry.id === null)
+            return;
+        // Never sent: nothing to remove.
+        if (entry.op === "Add") {
+            rt.pending.delete(entry.id);
+            forget(entry);
+            return;
+        }
+        rt.outstandingQueriesOlderThanRestart.delete(entry.id);
+        entry.op = "Remove";
+        rt.pending.set(entry.id, entry);
+        scheduleFlush(rt);
+    };
+    const createEntry = (rt, token, udfPath, args, queryOptions) => {
+        const visible = rt.overlay.get(token)?.result;
+        const result = atom(visible, `${name}.query#${udfPath}`);
+        let data;
+        let error;
+        let status;
+        const entry = {
+            rt,
+            connected: false,
+            retained: 0,
+            token,
+            udfPath,
+            args,
+            result,
+            componentPath: queryOptions?.componentPath,
+            id: null,
+            op: null,
+            server: undefined,
+            visible,
+            journal: queryOptions?.journal,
+            get data() {
+                return (data ??= computed(() => {
+                    const current = result();
+                    return current?.success ? current.value : undefined;
+                }, `${result.name}.data`));
+            },
+            get error() {
+                return (error ??= computed(() => {
+                    const current = result();
+                    return current && !current.success
+                        ? functionError("query", udfPath, current)
+                        : undefined;
+                }, `${result.name}.error`));
+            },
+            get status() {
+                return (status ??= computed(() => {
+                    const current = result();
+                    return current === undefined
+                        ? "loading"
+                        : current.success
+                            ? "success"
+                            : "error";
+                }, `${result.name}.status`));
+            },
+        };
+        result.extend(withConnectionHooks(() => {
+            entry.connected = true;
+            if (entry.retained === 0)
+                connectEntry(entry);
+        }, () => {
+            entry.connected = false;
+            if (entry.retained === 0)
+                disconnectEntry(entry);
+        }));
+        rt.entries.set(entry);
+        return entry;
+    };
+    /** The entry for a query, created on first use. */
+    const queryEntry = (udfPath, args, queryOptions) => {
+        const rt = peek(runtime);
+        const canonical = canonicalizeUdfPath(udfPath);
+        // `serializePathAndArgs` without canonicalizing the path again.
+        const token = JSON.stringify({
+            udfPath: canonical,
+            args: convexToJson(args),
+        });
+        const existing = rt.entries.get(token);
+        if (existing === undefined) {
+            return createEntry(rt, token, canonical, args, queryOptions);
+        }
+        // A journal only applies to a new subscription.
+        if (existing.id === null && queryOptions?.journal !== undefined) {
+            existing.journal = queryOptions.journal;
+        }
+        return existing;
+    };
+    // Identity
+    const setAuthToken = (token) => {
+        authToken.set(token);
+        const baseVersion = identityVersion();
+        if (!peek(runtime).paused)
+            identityVersion.set(baseVersion + 1);
+        return { type: "Authenticate", baseVersion, ...token };
+    };
+    const clearAuthToken = () => {
+        const rt = peek(runtime);
+        authToken.set(undefined);
+        rt.outstandingAuthOlderThanRestart = false;
+        const baseVersion = identityVersion();
+        if (!rt.paused)
+            identityVersion.set(baseVersion + 1);
+        return { type: "Authenticate", tokenType: "None", baseVersion };
+    };
+    const authSync = {
+        isCurrentOrNewerAuthVersion: (version) => version >= identityVersion(),
+        markAuthCompletion: () => {
+            peek(runtime).outstandingAuthOlderThanRestart = false;
+        },
+        token: () => authToken()?.value,
+        hasAuth: () => authToken() !== undefined,
+        authenticate: (value) => {
+            socket.send(setAuthToken({ tokenType: "User", value }));
+        },
+        dropAuth: () => void clearAuthToken(),
+        clearAuth: () => {
+            // A paused socket drops the message.
+            if (peek(runtime).paused)
+                peek(runtime).clearAuthOnResume = true;
+            socket.send(clearAuthToken());
+        },
+        stopSocket: () => socket.stop(),
+        tryRestartSocket: () => socket.tryRestart(),
+        pauseSocket: () => {
+            socket.pause();
+            peek(runtime).paused = true;
+        },
+        resumeSocket: () => socket.resume(),
+    };
+    // Requests
+    const updateRequests = (update) => requests.set((current) => {
+        const next = new Map(current);
+        update(next);
+        return next;
+    });
+    const request = (message) => {
+        const sent = socket.send(message);
+        return new Promise((resolve) => {
+            updateRequests((all) => all.set(message.requestId, {
+                message,
+                status: sent ? "Requested" : "NotSent",
+                requestedAt: new Date(),
+                resolve,
+            }));
+        });
+    };
+    /** Returns the result when the request is done and its update can be dropped. */
+    const onResponse = (response) => {
+        const rt = peek(runtime);
+        const current = requests().get(response.requestId);
+        // A request no longer tracked, e.g. a mutation answered again after a
+        // reconnect, or one `restart` already re-sent and completed.
+        if (current === undefined || current.status === "Completed")
+            return null;
+        const udfType = current.message.type === "Mutation" ? "mutation" : "action";
+        const udfPath = current.message.udfPath;
+        for (const line of response.logLines) {
+            logForFunction(logger, "info", udfType, udfPath, line);
+        }
+        let result;
+        if (response.success) {
+            result = {
+                success: true,
+                logLines: response.logLines,
+                value: jsonToConvex(response.result),
+            };
+        }
+        else {
+            const errorMessage = response.result;
+            logForFunction(logger, "error", udfType, udfPath, errorMessage);
+            result = {
+                success: false,
+                errorMessage,
+                errorData: response.errorData !== undefined
+                    ? jsonToConvex(response.errorData)
+                    : undefined,
+                logLines: response.logLines,
+            };
+        }
+        // A failed mutation changed nothing, and actions are not ordered with
+        // queries, so both resolve now.
+        if (response.type === "ActionResponse" || !response.success) {
+            current.resolve(result);
+            updateRequests((all) => all.delete(response.requestId));
+            rt.requestsOlderThanRestart.delete(response.requestId);
+            return { requestId: response.requestId, result };
+        }
+        // A mutation resolves once a transition reaches its timestamp, so the
+        // caller reads its own write.
+        updateRequests((all) => all.set(response.requestId, {
+            ...current,
+            status: "Completed",
+            result,
+            ts: response.ts,
+        }));
+        return null;
+    };
+    const removeCompleted = (ts) => {
+        const rt = peek(runtime);
+        const completed = new Map();
+        for (const [requestId, current] of requests()) {
+            if (current.status !== "Completed" || !current.ts.lessThanOrEqual(ts)) {
+                continue;
+            }
+            current.resolve(current.result);
+            completed.set(requestId, current.result);
+            rt.requestsOlderThanRestart.delete(requestId);
+        }
+        if (completed.size > 0) {
+            updateRequests((all) => completed.forEach((_, id) => all.delete(id)));
+        }
+        return completed;
+    };
+    /**
+     * Requests to send on a new connection. Mutations are idempotent and go
+     * again, even completed ones, so the server transitions the client past
+     * them. In-flight actions might have run, so they fail.
+     */
+    const restartRequests = () => {
+        const rt = peek(runtime);
+        rt.requestsOlderThanRestart = new Set(requests().keys());
+        const messages = [];
+        const lost = [];
+        updateRequests((all) => {
+            for (const [requestId, current] of all) {
+                if (current.status === "NotSent") {
+                    all.set(requestId, { ...current, status: "Requested" });
+                    messages.push(current.message);
+                }
+                else if (current.message.type === "Mutation") {
+                    messages.push(current.message);
+                }
+                else {
+                    all.delete(requestId);
+                    rt.requestsOlderThanRestart.delete(requestId);
+                    lost.push(current);
+                }
+            }
+        });
+        for (const { resolve } of lost) {
+            resolve({
+                success: false,
+                errorMessage: "Connection lost while action was in flight",
+                logLines: [],
+            });
+        }
+        return messages;
+    };
+    const resumeRequests = () => {
+        const messages = [];
+        updateRequests((all) => {
+            for (const [requestId, current] of all) {
+                if (current.status !== "NotSent")
+                    continue;
+                all.set(requestId, { ...current, status: "Requested" });
+                messages.push(current.message);
+            }
+        });
+        return messages;
+    };
+    const hasIncompleteRequests = () => {
+        for (const current of requests().values()) {
+            if (current.status === "Requested")
+                return true;
+        }
+        return false;
+    };
+    const timeOfOldestInflightRequest = (pending) => {
+        if (pending.size === 0)
+            return null;
+        let oldest = Date.now();
+        for (const current of pending.values()) {
+            if (current.status !== "Completed") {
+                oldest = Math.min(oldest, current.requestedAt.getTime());
+            }
+        }
+        return new Date(oldest);
+    };
+    const tryReportLongDisconnect = () => {
+        if (!debug)
+            return;
+        const oldest = timeOfOldestInflightRequest(requests());
+        if (oldest === null || Date.now() - oldest.getTime() <= 60 * 1000)
+            return;
+        fetch(`${address}/api/debug_event`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Convex-Client": `npm-${version}`,
+            },
+            body: JSON.stringify({ event: "LongWebsocketDisconnect" }),
+        })
+            .then((response) => {
+            if (!response.ok) {
+                logger.warn("Analytics request failed with response:", response.body);
+            }
+        })
+            .catch((error) => {
+            logger.warn("Analytics response failed with error:", error);
+        });
+    };
+    // Socket
+    const observedTimestamp = (observedTs) => {
+        const max = maxObservedTimestamp();
+        if (max === undefined || max.lessThanOrEqual(observedTs)) {
+            maxObservedTimestamp.set(observedTs);
+        }
+    };
+    const hasSyncedPastLastReconnect = () => {
+        const rt = peek(runtime);
+        return (rt.requestsOlderThanRestart.size === 0 &&
+            rt.outstandingQueriesOlderThanRestart.size === 0 &&
+            !rt.outstandingAuthOlderThanRestart);
+    };
+    const onOpen = (reconnectMetadata) => {
+        const rt = peek(runtime);
+        mark("convexWebSocketOpen");
+        socket.send({
+            ...reconnectMetadata,
+            type: "Connect",
+            sessionId: rt.sessionId,
+            maxObservedTimestamp: maxObservedTimestamp(),
+        });
+        // A new connection starts from an empty query set and no identity:
+        // re-add every query, resend mutations and reauthenticate.
+        remoteVersion.set(INITIAL_VERSION);
+        rt.paused = false;
+        rt.clearAuthOnResume = false;
+        for (const entry of rt.pending.values()) {
+            if (entry.op === "Remove")
+                forget(entry);
+            else
+                entry.op = null;
+        }
+        rt.pending.clear();
+        rt.outstandingQueriesOlderThanRestart = new Set(rt.byId.keys());
+        const querySet = {
+            type: "ModifyQuerySet",
+            baseVersion: 0,
+            newVersion: 1,
+            modifications: Array.from(rt.byId.values(), addQuery),
+        };
+        querySetVersion.set(1);
+        const token = authToken();
+        if (token === undefined) {
+            // The server starts without an identity too.
+            identityVersion.set(0);
+        }
+        else {
+            rt.outstandingAuthOlderThanRestart = true;
+            identityVersion.set(1);
+            socket.send({
+                type: "Authenticate",
+                baseVersion: 0,
+                ...token,
+            });
+        }
+        socket.send(querySet);
+        for (const message of restartRequests())
+            socket.send(message);
+    };
+    const onResume = () => {
+        const rt = peek(runtime);
+        let querySet;
+        if (rt.pending.size > 0) {
+            const baseVersion = querySetVersion();
+            querySet = {
+                type: "ModifyQuerySet",
+                baseVersion,
+                newVersion: baseVersion + 1,
+                modifications: takePending(rt),
+            };
+            querySetVersion.set(baseVersion + 1);
+        }
+        const token = authToken();
+        let authenticate;
+        if (token !== undefined) {
+            const baseVersion = identityVersion();
+            identityVersion.set(baseVersion + 1);
+            authenticate = {
+                type: "Authenticate",
+                baseVersion,
+                ...token,
+            };
+        }
+        else if (rt.clearAuthOnResume) {
+            const baseVersion = identityVersion();
+            identityVersion.set(baseVersion + 1);
+            authenticate = { type: "Authenticate", tokenType: "None", baseVersion };
+        }
+        rt.clearAuthOnResume = false;
+        rt.paused = false;
+        if (authenticate)
+            socket.send(authenticate);
+        if (querySet)
+            socket.send(querySet);
+        for (const message of resumeRequests())
+            socket.send(message);
+    };
+    const onTransition = (message) => {
+        const rt = peek(runtime);
+        observedTimestamp(message.endVersion.ts);
+        auth.onTransition(message);
+        const start = message.startVersion;
+        const current = remoteVersion();
+        if (current.querySet !== start.querySet ||
+            current.ts.notEquals(start.ts) ||
+            current.identity !== start.identity) {
+            throw new Error(`Invalid start version: ${start.ts.toString()}:${start.querySet}:${start.identity}, transitioning from ${current.ts.toString()}:${current.querySet}:${current.identity}`);
+        }
+        const changed = [];
+        const removed = new Set();
+        for (const modification of message.modifications) {
+            rt.outstandingQueriesOlderThanRestart.delete(modification.queryId);
+            // Results for queries already unsubscribed are dropped.
+            const entry = rt.byId.get(modification.queryId);
+            if (entry === undefined)
+                continue;
+            switch (modification.type) {
+                case "QueryUpdated": {
+                    for (const line of modification.logLines) {
+                        logForFunction(logger, "info", "query", entry.udfPath, line);
+                    }
+                    entry.server = {
+                        success: true,
+                        value: jsonToConvex(modification.value ?? null),
+                        logLines: modification.logLines,
+                    };
+                    if (modification.journal !== undefined) {
+                        entry.journal = modification.journal;
+                    }
+                    break;
+                }
+                case "QueryFailed": {
+                    for (const line of modification.logLines) {
+                        logForFunction(logger, "info", "query", entry.udfPath, line);
+                    }
+                    const { errorData } = modification;
+                    entry.server = {
+                        success: false,
+                        errorMessage: modification.errorMessage,
+                        errorData: errorData !== undefined ? jsonToConvex(errorData) : undefined,
+                        logLines: modification.logLines,
+                    };
+                    if (modification.journal !== undefined) {
+                        entry.journal = modification.journal;
+                    }
+                    break;
+                }
+                case "QueryRemoved": {
+                    entry.server = undefined;
+                    removed.add(entry);
+                    break;
+                }
+                default: {
+                    modification;
+                    throw new Error(`Invalid modification ${modification.type}`);
+                }
+            }
+            changed.push(entry);
+        }
+        remoteVersion.set(message.endVersion);
+        ingest(changed, removeCompleted(message.endVersion.ts), removed);
+    };
+    const onMessage = (serverMessage) => {
+        const rt = peek(runtime);
+        // Once per client: metrics grow with reconnects.
+        if (!rt.firstMessageReceived) {
+            rt.firstMessageReceived = true;
+            mark("convexFirstMessageReceived");
+            if (debug) {
+                socket.send({
+                    type: "Event",
+                    eventType: "ClientConnect",
+                    event: getMarksReport(rt.sessionId),
+                });
+            }
+        }
+        switch (serverMessage.type) {
+            case "Transition": {
+                onTransition(serverMessage);
+                break;
+            }
+            case "MutationResponse": {
+                if (serverMessage.success) {
+                    observedTimestamp(serverMessage.ts);
+                }
+                const completed = onResponse(serverMessage);
+                if (completed !== null) {
+                    ingest([], new Map([[completed.requestId, completed.result]]));
+                }
+                break;
+            }
+            case "ActionResponse": {
+                onResponse(serverMessage);
+                break;
+            }
+            case "AuthError": {
+                auth.onAuthError(serverMessage);
+                break;
+            }
+            case "FatalError": {
+                const error = logFatalError(logger, serverMessage.error);
+                void socket.terminate();
+                throw error;
+            }
+            default: {
+                serverMessage;
+            }
+        }
+        return hasSyncedPastLastReconnect();
+    };
+    const socket = reatomSocket(wsUri, { webSocketConstructor, logger, debug }, {
+        onOpen,
+        onResume,
+        onMessage,
+        onServerDisconnectError: options.onServerDisconnectError,
+    }, `${name}.socket`);
+    const auth = reatomAuth(authSync, {
+        logger,
+        refreshTokenLeewaySeconds: options.authRefreshTokenLeewaySeconds ?? 10,
+        initialAuthTokenReuse: options.initialAuthTokenReuse ?? false,
+    }, `${name}.auth`);
+    /** Opens the socket on first use in this context. */
+    const start = () => {
+        const rt = peek(runtime);
+        if (rt.started || rt.closed)
+            return;
+        rt.started = true;
+        if (hasWindow && options.unsavedChangesWarning !== false) {
+            // Prompt on tab close while requests are unconfirmed.
+            rt.onBeforeUnload = wrap((e) => {
+                if (!hasIncompleteRequests())
+                    return;
+                e.preventDefault();
+                // Most browsers don't show this message, but some still need it set.
+                const confirmationMessage = "Are you sure you want to leave? Your changes may not be saved.";
+                (e || window.event).returnValue = confirmationMessage;
+                return confirmationMessage;
+            }, rt.root);
+            window.addEventListener("beforeunload", rt.onBeforeUnload);
+        }
+        socket.start();
+        mark("convexClientConstructed");
+        // Wait for the first auth token.
+        if (options.expectAuth)
+            authSync.pauseSocket();
+    };
+    const connectionState = computed(() => {
+        const pending = requests();
+        let inflightMutations = 0;
+        for (const current of pending.values()) {
+            if (current.message.type === "Mutation")
+                inflightMutations++;
+        }
+        return {
+            hasInflightRequests: pending.size > 0,
+            isWebSocketConnected: socket.state().state === "ready",
+            hasEverConnected: socket.hasEverConnected(),
+            connectionCount: socket.connectionCount(),
+            connectionRetries: socket.retries(),
+            timeOfOldestInflightRequest: timeOfOldestInflightRequest(pending),
+            inflightMutations,
+            inflightActions: pending.size - inflightMutations,
+        };
+    }, `${name}.connectionState`).extend(withConnectionHooks(start, noop));
+    const authClaims = computed(() => {
+        const token = authToken();
+        if (token?.tokenType !== "User")
+            return undefined;
+        let decoded;
+        try {
+            decoded = jwtDecode(token.value);
+        }
+        catch {
+            decoded = {};
+        }
+        return { token: token.value, decoded };
+    }, `${name}.authClaims`);
+    const enqueueMutation = (udfPath, args, mutationOptions, componentPath) => {
+        start();
+        const mutationArgs = parseArgs(args);
+        tryReportLongDisconnect();
+        const rt = peek(runtime);
+        const requestId = rt.nextRequestId++;
+        const optimisticUpdate = mutationOptions?.optimisticUpdate;
+        if (optimisticUpdate !== undefined) {
+            applyOptimisticUpdate((store) => {
+                const result = optimisticUpdate(store, mutationArgs);
+                if (result instanceof Promise) {
+                    logger.warn("Optimistic update handler returned a Promise. Optimistic updates should be synchronous.");
+                }
+            }, requestId);
+        }
+        const mutationPromise = request({
+            type: "Mutation",
+            requestId,
+            udfPath,
+            componentPath,
+            args: [convexToJson(mutationArgs)],
+        });
+        return { requestId, mutationPromise };
+    };
+    const actionInternal = (udfPath, args, componentPath) => {
+        start();
+        const actionArgs = parseArgs(args);
+        const requestId = peek(runtime).nextRequestId++;
+        tryReportLongDisconnect();
+        return request({
+            type: "Action",
+            requestId,
+            udfPath,
+            componentPath,
+            args: [convexToJson(actionArgs)],
+        });
+    };
+    const runMutation = action(async (udfPath, args, mutationOptions) => {
+        const result = await wrap(enqueueMutation(udfPath, args, mutationOptions).mutationPromise);
+        if (!result.success)
+            throw functionError("mutation", udfPath, result);
+        return result.value;
+    }, `${name}.mutation`);
+    const runAction = action(async (udfPath, args) => {
+        const result = await wrap(actionInternal(udfPath, args));
+        if (!result.success)
+            throw functionError("action", udfPath, result);
+        return result.value;
+    }, `${name}.action`);
+    const setAuth = action((fetchToken, onChange, onRefreshChange) => {
+        start();
+        isAuthenticated.set(null);
+        isRefreshingAuth.set(false);
+        // The flow outlives the caller's frame, so it runs in the root.
+        wrap(() => void auth.setConfig(fetchToken, (value) => {
+            isAuthenticated.set(value);
+            onChange?.(value);
+        }, (value) => {
+            isRefreshingAuth.set(value);
+            onRefreshChange?.(value);
+        }), peek(runtime).root)();
+    }, `${name}.setAuth`);
+    const clearAuth = action(() => {
+        start();
+        auth.stop();
+        // Forget the token before resuming a pause for a token fetch, so the
+        // resume doesn't send it, then tell the server.
+        authToken.set(undefined);
+        socket.resume();
+        socket.tryRestart();
+        authSync.clearAuth();
+        isAuthenticated.set(false);
+        isRefreshingAuth.set(false);
+    }, `${name}.clearAuth`);
+    const setAdminAuth = action((value, fakeUserIdentity) => {
+        start();
+        socket.send(setAuthToken({
+            tokenType: "Admin",
+            value,
+            impersonating: fakeUserIdentity,
+        }));
+    }, `${name}.setAdminAuth`);
+    const close = action(() => {
+        const rt = peek(runtime);
+        rt.closed = true;
+        auth.stop();
+        if (rt.onBeforeUnload) {
+            window.removeEventListener("beforeunload", rt.onBeforeUnload);
+            rt.onBeforeUnload = null;
+        }
+        if (!rt.started)
+            return Promise.resolve();
+        return socket.terminate();
+    }, `${name}.close`);
+    /** The paginated query for `options`, created on first use. */
+    const paginatedQueryEntry = (udfPath, args, paginatedOptions) => {
+        const canonical = canonicalizeUdfPath(udfPath);
+        const token = serializePaginatedPathAndArgs(canonical, args, paginatedOptions);
+        const { paginated } = peek(runtime);
+        const existing = paginated.get(token);
+        if (existing !== undefined)
+            return existing;
+        const created = reatomPaginatedQuery((pageUdfPath, pageArgs, paginationOpts) => queryEntry(pageUdfPath, { ...pageArgs, paginationOpts }), canonical, args, paginatedOptions, `${name}.paginatedQuery#${canonical}`);
+        paginated.set(created);
+        return created;
+    };
+    /** A result held locally, with optimistic updates applied. */
+    const rawQueryResultByToken = (queryToken) => {
+        const entry = lookup(queryToken);
+        return entry !== undefined
+            ? entry.visible
+            : peek(runtime).overlay.get(queryToken)?.result;
+    };
+    /** Like {@link rawQueryResultByToken}, but throws a failed query's error. */
+    const localQueryResultByToken = (queryToken) => {
+        const result = rawQueryResultByToken(queryToken);
+        if (result === undefined)
+            return undefined;
+        if (result.success)
+            return result.value;
+        const udfPath = lookup(queryToken)?.udfPath ??
+            peek(runtime).overlay.get(queryToken).udfPath;
+        throw functionError("query", udfPath, result);
+    };
+    const client = {
+        name,
+        url: address,
+        connectionState,
+        isAuthenticated,
+        isRefreshingAuth,
+        authClaims,
+        socketState: socket.state,
+        query: (query, args, queryOptions) => queryEntry(functionName(query), parseArgs(args), queryOptions),
+        paginatedQuery: (query, args, paginatedOptions) => paginatedQueryEntry(functionName(query), parseArgs(args), {
+            initialNumItems: paginatedOptions.initialNumItems,
+            id: paginatedOptions.id ?? -1,
+        }),
+        mutation: (mutation, args, mutationOptions) => runMutation(functionName(mutation), args, mutationOptions),
+        action: (action, args) => runAction(functionName(action), args),
+        setAuth,
+        clearAuth,
+        close,
+    };
+    INTERNALS.set(client, {
+        setAdminAuth,
+        localQueryResultByToken,
+        rawQueryResultByToken,
+        hasLocalQueryResultByToken: (queryToken) => rawQueryResultByToken(queryToken) !== undefined,
+        queryJournal: (queryToken) => {
+            const entry = lookup(queryToken);
+            return entry?.id === null ? undefined : entry?.journal;
+        },
+        queryEntry,
+        retainQuery: (entry) => {
+            const queryEntry = entry;
+            if (queryEntry.retained++ === 0 && !queryEntry.connected) {
+                connectEntry(queryEntry);
+            }
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                if (--queryEntry.retained === 0 && !queryEntry.connected) {
+                    disconnectEntry(queryEntry);
+                }
+            };
+        },
+        paginatedQueryEntry,
+        enqueueMutation,
+        actionInternal,
+        addOnTransitionHandler: (handler) => {
+            const { transitionHandlers } = peek(runtime);
+            transitionHandlers.add(handler);
+            return () => transitionHandlers.delete(handler);
+        },
+        start,
+        sessionId: () => peek(runtime).sessionId,
+        nextRequestId: () => peek(runtime).nextRequestId,
+        hasAuth: () => authToken() !== undefined,
+        maxObservedTimestamp: () => maxObservedTimestamp(),
+        authState: () => auth.state().state,
+        optimisticUpdates: () => optimisticUpdates().length,
+    });
+    return client;
+}
+const INTERNALS = new WeakMap();
+/** @internal */
+export function internals(client) {
+    const found = INTERNALS.get(client);
+    if (!found)
+        throw new Error("Not a client created by reatomConvexClient");
+    return found;
+}