@reatomized/convex 0.3.0 → 0.3.1

package/README.md

@@ -24,11 +24,11 @@ import type { Id } from "../convex/_generated/dataModel";
 
 const convex = reatomConvexClient(import.meta.env.VITE_CONVEX_URL);
 
-const noteId = atom<Id<"notes"> | null>(null);
+const noteId = atom<Id<"notes"> | null>(null, "noteId");
 const note = computed(() => {
   const id = noteId();
   return id ? convex.query(api.notes.get, { id }).data() : undefined;
-});
+}, "note");
 ```
 
 - `convex.query(ref, args)` returns the entry for that function and arguments,
@@ -153,8 +153,9 @@ Node 22 and later have a global `WebSocket`. On Node 20, pass one, such as the
   convex/browser's `BaseConvexClient`. The Reatom functions it uses add 4.6 KiB,
   shared with the rest of the app.
 
-With 1000 components each running its own query in Chromium, mounting takes 9.24
-ms against 65.5 ms for convex/react, unmounting 1.99 ms against 9.87 ms.
+With 1000 components each running its own query in Chromium and @reatom/jsx
+rendering, mounting takes 6.28 ms against 54.2 ms for convex/react, unmounting
+0.75 ms against 7.93 ms.
 [CONTRIBUTING.md](https://github.com/reatomized/convex/blob/reatom/CONTRIBUTING.md#performance)
 has the full table and how it was measured.
 

package/dist/browser/reatom/auth.d.ts

@@ -67,7 +67,7 @@ export declare function reatomAuth(sync: AuthSync, options: {
 }, name: string): {
     /** The auth state machine. */
     state: import("@reatom/core").Atom<AuthState, [newState: AuthState]>;
-    setConfig(fetchToken: AuthTokenFetcher, onChange: (isAuthenticated: boolean) => void, onRefreshChange?: ((isRefreshing: boolean) => void) | undefined): Promise<void>;
+    setConfig: import("@reatom/core").GAction<(fetchToken: AuthTokenFetcher, onChange: (isAuthenticated: boolean) => void, onRefreshChange?: ((isRefreshing: boolean) => void) | undefined) => Promise<void>>;
     onTransition(serverMessage: Transition): void;
     onAuthError(serverMessage: AuthError): void;
     stop(): void;

package/dist/browser/reatom/auth.js

@@ -10,7 +10,7 @@
  * server's clock skew. When the server rejects a token, the socket stops, a
  * fresh token is fetched and sent, and the socket restarts.
  */
-import { atom, context, peek, wrap } from "@reatom/core";
+import { action, atom, context, peek, wrap } from "@reatom/core";
 import { jwtDecode } from "../../vendor/jwt-decode/index.js";
 // setTimeout takes a 32-bit delay, about 24 days.
 const MAXIMUM_REFRESH_DELAY = 20 * 24 * 60 * 60 * 1000; // 20 days
@@ -124,6 +124,8 @@ export function reatomAuth(sync, options, name) {
             logger.warn(`Refetching auth token immediately, configured leeway ${refreshTokenLeewaySeconds}s is larger than the token's lifetime ${tokenValiditySeconds}s`);
             delay = 0;
         }
+        // Owned by the auth state machine, not a query subscription. Changing
+        // config or stopping auth cancels this in resetAuthState.
         const refetchTokenTimeoutId = setTimeout(wrap(() => {
             logVerbose("running scheduled token refetch");
             void refetchToken();
@@ -137,7 +139,7 @@ export function reatomAuth(sync, options, name) {
     };
     // Force-fetches a token and schedules the next refetch once the server
     // confirms it, so an active client never has to reauthenticate.
-    const refetchToken = async () => {
+    const refetchToken = action(async () => {
         const current = state();
         if (current.state === "noAuth")
             return;
@@ -171,10 +173,10 @@ export function reatomAuth(sync, options, name) {
         // In case a scheduled refetch ran during a reauthentication.
         logVerbose("restarting WS after auth token fetch (if currently stopped)");
         sync.tryRestartSocket();
-    };
+    }, `${name}._refetchToken`);
     // Like `refetchToken`, but with the socket stopped so requests don't retry
     // with the rejected token.
-    const tryToReauthenticate = async (serverMessage) => {
+    const tryToReauthenticate = action(async (serverMessage) => {
         logVerbose(`attempting to reauthenticate: ${serverMessage.error}`);
         const current = state();
         const rt = peek(runtime);
@@ -230,40 +232,41 @@ export function reatomAuth(sync, options, name) {
             setAndReportAuthFailed(latest.config.onAuthChange);
         }
         sync.tryRestartSocket();
-    };
+    }, `${name}._reauthenticate`);
+    const setConfig = action(async (fetchToken, onChange, onRefreshChange) => {
+        resetAuthState();
+        logVerbose("pausing WS for auth token fetch");
+        sync.pauseSocket();
+        const token = await wrap(fetchTokenAndGuardAgainstRace(fetchToken, {
+            forceRefreshToken: false,
+        }));
+        if (token.isFromOutdatedConfig)
+            return;
+        const config = {
+            fetchToken,
+            onAuthChange: onChange,
+            onRefreshChange,
+        };
+        if (token.value) {
+            setAuthState({
+                state: "waitingForServerConfirmationOfCachedToken",
+                config,
+                hasRetried: false,
+            });
+            sync.authenticate(token.value);
+        }
+        else {
+            setAuthState({ state: "initialRefetch", config });
+            // Try again with `forceRefreshToken: true`.
+            await wrap(refetchToken());
+        }
+        logVerbose("resuming WS after auth token fetch");
+        sync.resumeSocket();
+    }, `${name}.setConfig`);
     return {
         /** The auth state machine. */
         state,
-        async setConfig(fetchToken, onChange, onRefreshChange) {
-            resetAuthState();
-            logVerbose("pausing WS for auth token fetch");
-            sync.pauseSocket();
-            const token = await wrap(fetchTokenAndGuardAgainstRace(fetchToken, {
-                forceRefreshToken: false,
-            }));
-            if (token.isFromOutdatedConfig)
-                return;
-            const config = {
-                fetchToken,
-                onAuthChange: onChange,
-                onRefreshChange,
-            };
-            if (token.value) {
-                setAuthState({
-                    state: "waitingForServerConfirmationOfCachedToken",
-                    config,
-                    hasRetried: false,
-                });
-                sync.authenticate(token.value);
-            }
-            else {
-                setAuthState({ state: "initialRefetch", config });
-                // Try again with `forceRefreshToken: true`.
-                await wrap(refetchToken());
-            }
-            logVerbose("resuming WS after auth token fetch");
-            sync.resumeSocket();
-        },
+        setConfig,
         onTransition(serverMessage) {
             // Stale: the client has moved on to a newer identity.
             if (!sync.isCurrentOrNewerAuthVersion(serverMessage.endVersion.identity)) {

package/dist/browser/reatom/better_auth.js

@@ -4,7 +4,7 @@
  * `ConvexBetterAuthProvider`. Sign in and out through the better-auth client
  * itself; its session store tells this provider.
  */
-import { action, atom, computed, peek, withAsync, withConnectHook, wrap, } from "@reatom/core";
+import { abortVar, action, atom, computed, peek, withAsync, withConnectHook, wrap, } from "@reatom/core";
 /**
  * With `crossDomainClient()`, an OAuth sign-in comes back with a one-time
  * token in the `ott` query param; the provider trades it for the session.
@@ -25,7 +25,7 @@ export function reatomBetterAuthProvider(authClient, options = {}, name = "bette
     // Boxed, so the atom holds the request rather than its result.
     const pending = atom(null, `${name}._pending`);
     const state = atom(() => authClient.useSession.get(), `${name}.sessionState`).extend(withConnectHook((target) => {
-        void start();
+        void abortVar.spawn(start);
         return authClient.useSession.subscribe(wrap((value) => {
             const previous = peek(target).data?.session?.id;
             target.set(value);

package/dist/browser/reatom/client.js

@@ -121,11 +121,11 @@ export function reatomConvexClient(address, options = {}, name = "convex") {
     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`);
+    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`);
+    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`);
     /**
@@ -139,6 +139,9 @@ export function reatomConvexClient(address, options = {}, name = "convex") {
     const requests = atom(new Map(), `${name}.requests`);
     /** Optimistic updates of mutations the client has not seen reflected yet. */
     const optimisticUpdates = atom([], `${name}.optimisticUpdates`);
+    let nextTraceId = 0;
+    // Transport handles and query indexes are mutable per-context bookkeeping.
+    // Public results are atoms; these indexes deliberately are not rollback state.
     const runtime = atom(() => ({
         root: context(),
         started: false,
@@ -317,7 +320,7 @@ export function reatomConvexClient(address, options = {}, name = "convex") {
         rt.pending.clear();
         return modifications;
     };
-    const flush = () => {
+    const flush = action(() => {
         const rt = peek(runtime);
         rt.flushScheduled = false;
         if (rt.pending.size === 0 || rt.paused || rt.closed)
@@ -331,7 +334,7 @@ export function reatomConvexClient(address, options = {}, name = "convex") {
         };
         querySetVersion.set(baseVersion + 1);
         socket.send(modification);
-    };
+    }, `${name}._flush`);
     const scheduleFlush = (rt) => {
         if (rt.flushScheduled)
             return;
@@ -376,7 +379,7 @@ export function reatomConvexClient(address, options = {}, name = "convex") {
     };
     const createEntry = (rt, token, udfPath, args, queryOptions) => {
         const visible = rt.overlay.get(token)?.result;
-        const result = atom(visible, `${name}.query#${udfPath}`);
+        const result = atom(visible, `${name}.query#${udfPath}#${nextTraceId++}`);
         let data;
         let error;
         let status;
@@ -827,7 +830,7 @@ export function reatomConvexClient(address, options = {}, name = "convex") {
         remoteVersion.set(message.endVersion);
         ingest(changed, removeCompleted(message.endVersion.ts), removed);
     };
-    const onMessage = (serverMessage) => {
+    const onMessage = action((serverMessage) => {
         const rt = peek(runtime);
         // Once per client: metrics grow with reconnects.
         if (!rt.firstMessageReceived) {
@@ -874,7 +877,7 @@ export function reatomConvexClient(address, options = {}, name = "convex") {
             }
         }
         return hasSyncedPastLastReconnect();
-    };
+    }, `${name}._onMessage`);
     const socket = reatomSocket(wsUri, { webSocketConstructor, logger, debug }, {
         onOpen,
         onResume,
@@ -1044,7 +1047,7 @@ export function reatomConvexClient(address, options = {}, name = "convex") {
         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}`);
+        const created = reatomPaginatedQuery((pageUdfPath, pageArgs, paginationOpts) => queryEntry(pageUdfPath, { ...pageArgs, paginationOpts }), canonical, args, paginatedOptions, `${name}.paginatedQuery#${canonical}#${nextTraceId++}`);
         paginated.set(created);
         return created;
     };

package/dist/browser/reatom/connection_hooks.d.ts

@@ -1,11 +1,7 @@
-import type { AtomLike, Ext } from "@reatom/core";
+import { type AtomLike, type Ext } from "@reatom/core";
 /**
- * Calls `connect` when `target` gains its first subscriber and `disconnect`
- * when it loses the last one. `target` must have no other connect hook.
- *
- * Sets Reatom's internal `onConnect` slot to plain functions: Reatom's queue
- * calls them in the context's root frame. Unlike `withConnectHook` this makes
- * no actions, AbortController or AbortError per connection, which matters
- * with thousands of queries.
+ * Composes with other public Reatom connection hooks. Client work belongs to
+ * the context, not to a subscriber's abort scope; losing a subscription must
+ * not cancel a socket operation or a scheduled query-set flush.
  */
 export declare const withConnectionHooks: <Target extends AtomLike<any, any[], any>>(connect: () => void, disconnect: () => void) => Ext<Target, Target>;

package/dist/browser/reatom/connection_hooks.js

@@ -1,15 +1,10 @@
+import { abortVar, withConnectHook, } from "@reatom/core";
 /**
- * Calls `connect` when `target` gains its first subscriber and `disconnect`
- * when it loses the last one. `target` must have no other connect hook.
- *
- * Sets Reatom's internal `onConnect` slot to plain functions: Reatom's queue
- * calls them in the context's root frame. Unlike `withConnectHook` this makes
- * no actions, AbortController or AbortError per connection, which matters
- * with thousands of queries.
+ * Composes with other public Reatom connection hooks. Client work belongs to
+ * the context, not to a subscriber's abort scope; losing a subscription must
+ * not cancel a socket operation or a scheduled query-set flush.
  */
-export const withConnectionHooks = (connect, disconnect) => (target) => {
-    target.__reatom.onConnect = Object.assign(() => connect(), {
-        abort: () => disconnect(),
-    });
-    return target;
-};
+export const withConnectionHooks = (connect, disconnect) => withConnectHook(() => {
+    abortVar.spawn(connect);
+    return disconnect;
+});

package/dist/browser/reatom/convex_auth.js

@@ -8,7 +8,7 @@
  * verifier, signs in. `auth:signOut` ends the server session. Storage keys and
  * formats are `@convex-dev/auth/react`'s, so its sessions carry over.
  */
-import { action, atom, computed, peek, withAsync, withConnectHook, wrap, } from "@reatom/core";
+import { abortVar, action, atom, computed, peek, onEvent, sleep, withAsync, withConnectHook, wrap, } from "@reatom/core";
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 import { jwtDecode } from "../../vendor/jwt-decode/index.js";
@@ -48,16 +48,12 @@ export function reatomConvexAuthProvider(convex, options = {}, name = `${convex.
         ? storage().removeItem(key(base))
         : storage().setItem(key(base), value));
     const token = atom(null, `${name}.token`).extend(withConnectHook(() => {
-        void start();
-        const stopFollowing = followStorage();
-        const stopWarning = warnOnUnload();
-        return () => {
-            stopFollowing?.();
-            stopWarning?.();
-        };
+        void abortVar.spawn(start);
+        followStorage();
+        warnOnUnload();
     }));
     const restoring = atom(true, `${name}._restoring`).extend(withConnectHook(() => {
-        void start();
+        void abortVar.spawn(start);
     }));
     const isRefreshingToken = atom(false, `${name}.isRefreshingToken`);
     const started = atom(false, `${name}._started`);
@@ -95,7 +91,7 @@ export function reatomConvexAuthProvider(convex, options = {}, name = `${convex.
                 if (!(error instanceof TypeError) || retry >= RETRY_BACKOFF.length)
                     throw error;
                 const delay = RETRY_BACKOFF[retry] + RETRY_JITTER * Math.random();
-                await wrap(new Promise((resolve) => setTimeout(resolve, delay)));
+                await wrap(sleep(delay));
             }
         }
     };
@@ -188,27 +184,23 @@ export function reatomConvexAuthProvider(convex, options = {}, name = `${convex.
     const followStorage = () => {
         if (typeof window === "undefined")
             return undefined;
-        const listener = wrap((event) => {
+        return onEvent(window, "storage", (event) => {
             if (event.storageArea !== storage() || event.key !== key(JWT_KEY))
                 return;
             // Each key comes as its own event; the refresh token stays in storage.
             apply(event.newValue);
         });
-        window.addEventListener("storage", listener);
-        return () => window.removeEventListener("storage", listener);
     };
     // Leaving during a refresh token exchange can lose the new pair.
     const warnOnUnload = () => {
         if (typeof window === "undefined")
             return undefined;
-        const listener = wrap((event) => {
+        return onEvent(window, "beforeunload", (event) => {
             if (!peek(isRefreshingToken))
                 return;
             event.preventDefault();
             event.returnValue = true;
         });
-        window.addEventListener("beforeunload", listener);
-        return () => window.removeEventListener("beforeunload", listener);
     };
     return {
         isLoading,

package/dist/browser/reatom/socket.js

@@ -72,7 +72,7 @@ export function reatomSocket(uri, options, callbacks, name) {
     const state = atom({ state: "disconnected" }, `${name}.state`);
     const connectionCount = atom(0, `${name}.connectionCount`);
     /** Consecutive failed connections, reset once the client syncs past a reconnect. */
-    const retries = atom(0, `${name}.retries`);
+    const retries = atom(0, `${name}._retries`);
     const hasEverConnected = atom(false, `${name}.hasEverConnected`);
     const runtime = atom(() => ({
         root: context(),
@@ -150,6 +150,8 @@ export function reatomSocket(uri, options, callbacks, name) {
         }
         return transition;
     };
+    // Socket timers outlive individual subscribers. terminate clears both
+    // inactivity and reconnect timers; each reschedule cancels its predecessor.
     const resetServerInactivityTimeout = () => {
         if (state().state === "terminated")
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reatomized/convex",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "A Convex sync client with its state in Reatom atoms",
   "keywords": [
     "convex",