@reatomized/convex 0.3.0 → 0.4.0

package/README.md

@@ -12,7 +12,7 @@ npm install @reatomized/convex convex @reatom/core
 
 `convex` and `@reatom/core` are peer dependencies. The client takes function
 references and `ConvexError` from your `convex`, and its atoms live in your
-app's Reatom context. It speaks the sync protocol of convex 1.48.0.
+app's Reatom context. It speaks the sync protocol of convex 1.49.0.
 
 ## Usage
 
@@ -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,
@@ -115,6 +115,63 @@ For another library, pass any object with `isLoading` and `session` atoms and a
 user or organization id. Pass an atom of providers to switch libraries at
 runtime.
 
+## Testing
+
+`@reatomized/convex/testing` has fakes for UI tests and stories, with no
+deployment and no socket. `reatomConvexClientFake()` is a `ReatomConvexClient`
+whose functions are handlers, registered per function reference with types from
+it:
+
+```ts
+import { loading, reatomConvexClientFake } from "@reatomized/convex/testing";
+import { atom } from "@reatom/core";
+import { ConvexError } from "convex/values";
+import { api } from "../convex/_generated/api";
+
+const convex = reatomConvexClientFake();
+const notes = atom<string[]>([], "notes");
+const ready = atom(true, "ready");
+
+convex.handleQuery(api.notes.list, () => (ready() ? notes() : loading));
+convex.handleMutation(api.notes.add, ({ text }, { identity }) => {
+  if (!identity) throw new ConvexError("Not authenticated");
+  notes.set((all) => [...all, text]);
+  return null;
+});
+```
+
+- Query handlers run inside computeds. A handler that reads atoms runs again
+  when they change, and a mutation handler that writes them updates every query
+  that reads them.
+- Returning `loading` keeps a query loading. A handler that throws fails the
+  query with that error in `error`, so a `ConvexError` keeps its `data`. Query
+  handlers are synchronous; mutation and action handlers may return promises.
+- Results go through `convexToJson`, as on the wire: `undefined` arrives as
+  `null`, and a value Convex can't send fails the call.
+- A function without a handler throws `MissingHandlerError` naming it: on read
+  for a query, at the call for a mutation or action. App code may catch that
+  throw, so the fake also logs it with `console.error` and lists it in
+  `unhandled`.
+- The second argument of a handler is `{ identity }`, like
+  `ctx.auth.getUserIdentity()`. `setAuth` takes it from the token's claims;
+  `identity` is also settable.
+- `paginatedQuery` pages through a query handler's results;
+  `paginate(items, paginationOpts)` cuts a page from an array.
+- `connected` and `isRefreshingAuth` set what the client reports.
+- Handlers and state are per Reatom context, like the real client's. Register
+  handlers inside the frame that uses them.
+
+For auth, `reatomAuthProviderFake({ identity })` is an auth library for the real
+`reatomAuthState(convex, provider)`: its token carries `identity`, so the
+handlers see who signed in, and setting `provider.identity` signs in or out. Use
+it to run the app's own auth state. `reatomAuthStateFake(status)` returns the
+shape `reatomAuthState` returns with a settable `status`, for code that takes an
+auth state and should show `loading` or `rejected` without a client.
+
+For Storybook,
+[`@reatomized/convex-storybook`](https://github.com/reatomized/convex/tree/reatom/packages/convex-storybook#readme)
+builds these fakes per story from typed `parameters.convex`.
+
 ## Node
 
 With `@reatom/core@1001.3.0` loaded, Node never exits on its own, so a script
@@ -126,8 +183,7 @@ installs from a URL only with `--allow-remote`):
 npm install --allow-remote=root @reatom/core@https://pkg.pr.new/@reatom/core@5f42184
 ```
 
-Node 22 and later have a global `WebSocket`. On Node 20, pass one, such as the
-`ws` package's, as `webSocketConstructor`.
+Convex 1.49.0 requires Node 22 or later, which has a global `WebSocket`.
 
 ## Differences from convex/browser 1.48.0
 
@@ -153,8 +209,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/fake_auth.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Auth fakes: identities carried in unsigned JWTs, an auth library session for
+ * `reatomAuthState`, and an auth state with a settable status.
+ */
+import { type Atom, type Computed } from "@reatom/core";
+import type { UserIdentity } from "convex/server";
+import type { AuthTokenFetcher } from "./auth.js";
+import type { AuthProvider, AuthStatus, ReatomAuthState } from "./auth_state.js";
+/**
+ * A `UserIdentity` for `subject`, with `issuer` `https://convex.fake` unless
+ * `claims` names another.
+ *
+ * @public
+ */
+export declare function fakeIdentity(subject: string, claims?: Omit<Partial<UserIdentity>, "subject" | "tokenIdentifier">): UserIdentity;
+/**
+ * An unsigned JWT carrying `identity` as OIDC claims, valid for an hour.
+ * `reatomConvexClientFake` reads the identity back from it.
+ *
+ * @public
+ */
+export declare function fakeToken(identity: UserIdentity): string;
+/**
+ * The identity Convex derives from a JWT's claims. A token that isn't a JWT
+ * becomes an identity whose subject is the token.
+ */
+export declare function identityFromToken(token: string): UserIdentity;
+/**
+ * An auth library session for `reatomAuthState`, set from a test.
+ *
+ * @public
+ */
+export interface AuthProviderFake extends AuthProvider {
+    /** The signed-in user, `null` when signed out. */
+    readonly identity: Atom<UserIdentity | null>;
+    readonly isLoading: Atom<boolean>;
+    /** The identity's `tokenIdentifier`. */
+    readonly session: Computed<string | null>;
+}
+/** @public */
+export type AuthProviderFakeOptions = {
+    identity?: UserIdentity | null | undefined;
+    isLoading?: boolean | undefined;
+    /**
+     * Replaces the token fetch, which returns `fakeToken(identity)`. A fetch
+     * that returns `null` makes `reatomAuthState` report `rejected`.
+     */
+    fetchToken?: AuthTokenFetcher | undefined;
+};
+/**
+ * A fake auth library for `reatomAuthState(convex, provider)`. Its token
+ * carries `identity`, so `reatomConvexClientFake` hands that identity to
+ * function handlers once `setAuth` accepts the token.
+ *
+ * ```ts
+ * const provider = reatomAuthProviderFake({ identity: fakeIdentity("alex") });
+ * const auth = reatomAuthState(convex, provider);
+ * provider.identity.set(null); // signs out
+ * ```
+ *
+ * @public
+ */
+export declare function reatomAuthProviderFake(options?: AuthProviderFakeOptions, name?: string): AuthProviderFake;
+/**
+ * The shape `reatomAuthState` returns, with a settable `status`.
+ *
+ * @public
+ */
+export interface ReatomAuthStateFake extends ReatomAuthState {
+    readonly status: Atom<AuthStatus>;
+    readonly isRefreshing: Atom<boolean>;
+}
+/**
+ * An auth state that reports `status` without a client or auth library.
+ * `isLoading` and `isAuthenticated` follow `status`.
+ *
+ * ```ts
+ * const auth = reatomAuthStateFake("loading");
+ * auth.status.set("rejected");
+ * ```
+ *
+ * @public
+ */
+export declare function reatomAuthStateFake(status?: AuthStatus, name?: string): ReatomAuthStateFake;

package/dist/browser/reatom/fake_auth.js

@@ -0,0 +1,138 @@
+/**
+ * Auth fakes: identities carried in unsigned JWTs, an auth library session for
+ * `reatomAuthState`, and an auth state with a settable status.
+ */
+import { atom, computed } from "@reatom/core";
+import { jwtDecode } from "../../vendor/jwt-decode/index.js";
+const FAKE_ISSUER = "https://convex.fake";
+/** `UserIdentity` fields and the OIDC claims Convex reads them from. */
+const CLAIMS = {
+    givenName: "given_name",
+    familyName: "family_name",
+    preferredUsername: "preferred_username",
+    profileUrl: "profile",
+    pictureUrl: "picture",
+    emailVerified: "email_verified",
+    birthday: "birthdate",
+    timezone: "zoneinfo",
+    language: "locale",
+    phoneNumber: "phone_number",
+    phoneNumberVerified: "phone_number_verified",
+    updatedAt: "updated_at",
+};
+const FIELDS = Object.fromEntries(Object.entries(CLAIMS).map(([field, claim]) => [claim, field]));
+const RESERVED = new Set(["sub", "iss", "aud", "exp", "iat", "nbf", "jti"]);
+/**
+ * A `UserIdentity` for `subject`, with `issuer` `https://convex.fake` unless
+ * `claims` names another.
+ *
+ * @public
+ */
+export function fakeIdentity(subject, claims = {}) {
+    const issuer = typeof claims.issuer === "string" ? claims.issuer : FAKE_ISSUER;
+    return {
+        ...claims,
+        subject,
+        issuer,
+        tokenIdentifier: `${issuer}|${subject}`,
+    };
+}
+const base64url = (json) => {
+    let binary = "";
+    for (const byte of new TextEncoder().encode(json)) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary)
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+};
+/**
+ * An unsigned JWT carrying `identity` as OIDC claims, valid for an hour.
+ * `reatomConvexClientFake` reads the identity back from it.
+ *
+ * @public
+ */
+export function fakeToken(identity) {
+    const { tokenIdentifier: _, subject, issuer, ...fields } = identity;
+    const claims = { sub: subject, iss: issuer };
+    for (const [field, value] of Object.entries(fields)) {
+        claims[CLAIMS[field] ?? field] = value;
+    }
+    const iat = Math.floor(Date.now() / 1000);
+    claims.iat = iat;
+    claims.exp = iat + 3600;
+    return [
+        base64url(JSON.stringify({ alg: "none", typ: "JWT" })),
+        base64url(JSON.stringify(claims)),
+        "",
+    ].join(".");
+}
+/**
+ * The identity Convex derives from a JWT's claims. A token that isn't a JWT
+ * becomes an identity whose subject is the token.
+ */
+export function identityFromToken(token) {
+    let claims;
+    try {
+        claims = jwtDecode(token);
+    }
+    catch {
+        return fakeIdentity(token);
+    }
+    const fields = {};
+    for (const [claim, value] of Object.entries(claims)) {
+        if (!RESERVED.has(claim))
+            fields[FIELDS[claim] ?? claim] = value;
+    }
+    return fakeIdentity(typeof claims.sub === "string" ? claims.sub : token, {
+        ...fields,
+        issuer: typeof claims.iss === "string" ? claims.iss : FAKE_ISSUER,
+    });
+}
+/**
+ * A fake auth library for `reatomAuthState(convex, provider)`. Its token
+ * carries `identity`, so `reatomConvexClientFake` hands that identity to
+ * function handlers once `setAuth` accepts the token.
+ *
+ * ```ts
+ * const provider = reatomAuthProviderFake({ identity: fakeIdentity("alex") });
+ * const auth = reatomAuthState(convex, provider);
+ * provider.identity.set(null); // signs out
+ * ```
+ *
+ * @public
+ */
+export function reatomAuthProviderFake(options = {}, name = "authProviderFake") {
+    const identity = atom(options.identity ?? null, `${name}.identity`);
+    return {
+        identity,
+        isLoading: atom(options.isLoading ?? false, `${name}.isLoading`),
+        session: computed(() => identity()?.tokenIdentifier ?? null, `${name}.session`),
+        fetchToken: options.fetchToken ??
+            (() => {
+                const current = identity();
+                return Promise.resolve(current ? fakeToken(current) : null);
+            }),
+    };
+}
+/**
+ * An auth state that reports `status` without a client or auth library.
+ * `isLoading` and `isAuthenticated` follow `status`.
+ *
+ * ```ts
+ * const auth = reatomAuthStateFake("loading");
+ * auth.status.set("rejected");
+ * ```
+ *
+ * @public
+ */
+export function reatomAuthStateFake(status = "authenticated", name = "authStateFake") {
+    const current = atom(status, `${name}.status`);
+    return {
+        status: current,
+        isLoading: computed(() => current() === "loading", `${name}.isLoading`),
+        isAuthenticated: computed(() => current() === "authenticated", `${name}.isAuthenticated`),
+        isRefreshing: atom(false, `${name}.isRefreshing`),
+    };
+}

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

@@ -0,0 +1,107 @@
+/**
+ * A client whose functions are handlers a test registers, for UI tests and
+ * stories without a deployment. Query handlers run inside computeds, so a
+ * handler that reads atoms re-runs when they change, and a mutation handler
+ * that writes them updates every query that reads them.
+ *
+ * Handlers and state are per Reatom context, like the real client's.
+ */
+import { type Atom } from "@reatom/core";
+import { FunctionArgs, FunctionReference, FunctionReturnType, PaginationOptions, PaginationResult, UserIdentity } from "convex/server";
+import type { ReatomConvexClient } from "./client.js";
+import type { SocketState } from "./socket.js";
+/**
+ * Return it from a query handler to keep the query loading.
+ *
+ * @public
+ */
+export declare const loading: unique symbol;
+/**
+ * What a handler knows besides its arguments, like a function's `ctx.auth`.
+ *
+ * @public
+ */
+export type FunctionContext = {
+    /**
+     * The identity of the token the client authenticated with, or the one set on
+     * `identity`; `null` without one.
+     */
+    readonly identity: UserIdentity | null;
+};
+/** @public */
+export type QueryHandler<Query extends FunctionReference<"query">> = (args: FunctionArgs<Query>, ctx: FunctionContext) => FunctionReturnType<Query> | typeof loading;
+/** @public */
+export type MutationHandler<Mutation extends FunctionReference<"mutation">> = (args: FunctionArgs<Mutation>, ctx: FunctionContext) => FunctionReturnType<Mutation> | Promise<FunctionReturnType<Mutation>>;
+/** @public */
+export type ActionHandler<Action extends FunctionReference<"action">> = (args: FunctionArgs<Action>, ctx: FunctionContext) => FunctionReturnType<Action> | Promise<FunctionReturnType<Action>>;
+type FunctionType = "query" | "mutation" | "action";
+/**
+ * A function called on a fake client without a handler. Reading such a query
+ * throws it; calling such a mutation or action throws it before returning a
+ * promise. The fake also logs it with `console.error` and lists it in
+ * `unhandled`, since app code may catch the throw.
+ *
+ * @public
+ */
+export declare class MissingHandlerError extends Error {
+    readonly type: FunctionType;
+    readonly udfPath: string;
+    constructor(type: FunctionType, udfPath: string);
+}
+/**
+ * A page of `items` for a paginated query handler. Cursors are offsets into
+ * `items`, so an item inserted before a loaded page shifts the pages after it.
+ *
+ * @public
+ */
+export declare function paginate<T>(items: readonly T[], { cursor, numItems, endCursor }: PaginationOptions): PaginationResult<T>;
+/**
+ * A {@link ReatomConvexClient} that runs registered handlers instead of
+ * talking to a deployment.
+ *
+ * @public
+ */
+export interface ReatomConvexClientFake extends ReatomConvexClient {
+    /** Set by `setAuth` and `clearAuth`; settable to skip the token flow. */
+    readonly isAuthenticated: Atom<boolean | null>;
+    readonly isRefreshingAuth: Atom<boolean>;
+    /**
+     * The identity handlers see. `setAuth` sets it from the token's claims and
+     * `clearAuth` resets it.
+     */
+    readonly identity: Atom<UserIdentity | null>;
+    readonly socketState: Atom<SocketState>;
+    /**
+     * Whether `connectionState` reports an open socket, `true` by default.
+     * Requests still run while it is `false`.
+     */
+    readonly connected: Atom<boolean>;
+    /** Functions called without a handler in the current frame, once each. */
+    readonly unhandled: readonly MissingHandlerError[];
+    /**
+     * Answer `query` with `handler`, replacing an earlier one. Queries using it
+     * run it again. Call it inside a Reatom frame.
+     */
+    handleQuery<Query extends FunctionReference<"query">>(query: Query, handler: QueryHandler<Query>): void;
+    handleMutation<Mutation extends FunctionReference<"mutation">>(mutation: Mutation, handler: MutationHandler<Mutation>): void;
+    handleAction<Action extends FunctionReference<"action">>(action: Action, handler: ActionHandler<Action>): void;
+}
+/**
+ * Create a fake client. Register handlers inside the frame that uses it:
+ *
+ * ```ts
+ * const convex = reatomConvexClientFake();
+ * const notes = atom<string[]>([], "notes");
+ * convex.handleQuery(api.notes.list, () => notes());
+ * convex.handleMutation(api.notes.add, ({ text }) => {
+ *   notes.set((all) => [...all, text]);
+ *   return null;
+ * });
+ * ```
+ *
+ * @param name - A prefix for the client's atom names.
+ *
+ * @public
+ */
+export declare function reatomConvexClientFake(name?: string): ReatomConvexClientFake;
+export {};

package/dist/browser/reatom/fake_client.js

@@ -0,0 +1,307 @@
+/**
+ * A client whose functions are handlers a test registers, for UI tests and
+ * stories without a deployment. Query handlers run inside computeds, so a
+ * handler that reads atoms re-runs when they change, and a mutation handler
+ * that writes them updates every query that reads them.
+ *
+ * Handlers and state are per Reatom context, like the real client's.
+ */
+import { action, atom, computed, context, peek, wrap, } from "@reatom/core";
+import { getFunctionName, } from "convex/server";
+import { ConvexError, convexToJson, jsonToConvex } from "convex/values";
+import { parseArgs } from "../../common/index.js";
+import { jwtDecode } from "../../vendor/jwt-decode/index.js";
+import { canonicalizeUdfPath, serializePaginatedPathAndArgs, } from "../sync/udf_path_utils.js";
+import { identityFromToken } from "./fake_auth.js";
+import { reatomPaginatedQuery } from "./paginated.js";
+/**
+ * Return it from a query handler to keep the query loading.
+ *
+ * @public
+ */
+export const loading = Symbol("loading");
+const capitalized = { query: "Query", mutation: "Mutation", action: "Action" };
+/**
+ * A function called on a fake client without a handler. Reading such a query
+ * throws it; calling such a mutation or action throws it before returning a
+ * promise. The fake also logs it with `console.error` and lists it in
+ * `unhandled`, since app code may catch the throw.
+ *
+ * @public
+ */
+export class MissingHandlerError extends Error {
+    type;
+    udfPath;
+    constructor(type, udfPath) {
+        const [module, name] = udfPath.split(":");
+        const reference = ["api", ...module.split("/"), name].join(".");
+        super(`No fake handler for ${type} ${udfPath}. Register one with handle${capitalized[type]}(${reference}, ...).`);
+        this.name = "MissingHandlerError";
+        this.type = type;
+        this.udfPath = udfPath;
+    }
+}
+/**
+ * A page of `items` for a paginated query handler. Cursors are offsets into
+ * `items`, so an item inserted before a loaded page shifts the pages after it.
+ *
+ * @public
+ */
+export function paginate(items, { cursor, numItems, endCursor }) {
+    const start = cursor === null ? 0 : Number(cursor);
+    const end = Math.min(endCursor === undefined || endCursor === null
+        ? start + numItems
+        : Number(endCursor), items.length);
+    return {
+        page: items.slice(start, end),
+        isDone: end >= items.length,
+        continueCursor: String(end),
+    };
+}
+const asError = (error) => error instanceof Error ? error : new Error(String(error));
+const functionName = (ref) => canonicalizeUdfPath(typeof ref === "string" ? ref : getFunctionName(ref));
+/**
+ * Create a fake client. Register handlers inside the frame that uses it:
+ *
+ * ```ts
+ * const convex = reatomConvexClientFake();
+ * const notes = atom<string[]>([], "notes");
+ * convex.handleQuery(api.notes.list, () => notes());
+ * convex.handleMutation(api.notes.add, ({ text }) => {
+ *   notes.set((all) => [...all, text]);
+ *   return null;
+ * });
+ * ```
+ *
+ * @param name - A prefix for the client's atom names.
+ *
+ * @public
+ */
+export function reatomConvexClientFake(name = "convex") {
+    const handlers = atom(() => ({
+        query: new Map(),
+        mutation: new Map(),
+        action: new Map(),
+    }), `${name}._handlers`);
+    const identity = atom(null, `${name}.identity`);
+    const isAuthenticated = atom(false, `${name}.isAuthenticated`);
+    const isRefreshingAuth = atom(false, `${name}.isRefreshingAuth`);
+    const authToken = atom(undefined, `${name}.authToken`);
+    /** Bumped by each `setAuth` and `clearAuth`, so a stale token is dropped. */
+    const authVersion = atom(0, `${name}._authVersion`);
+    const connected = atom(true, `${name}.connected`);
+    const inflight = atom([], `${name}._inflight`);
+    const unhandled = atom(() => [], `${name}._unhandled`);
+    const miss = (type, udfPath) => {
+        const error = new MissingHandlerError(type, udfPath);
+        const missing = peek(unhandled);
+        if (!missing.some((seen) => seen.message === error.message)) {
+            missing.push(error);
+            // A second channel: app code may catch the throw and show it as a
+            // server failure.
+            // eslint-disable-next-line no-console
+            console.error(error.message);
+        }
+        return error;
+    };
+    const register = (type, ref, handler) => {
+        const udfPath = functionName(ref);
+        handlers.set((current) => ({
+            ...current,
+            [type]: new Map(current[type]).set(udfPath, handler),
+        }));
+    };
+    const functionContext = () => ({ identity: identity() });
+    /** A handler's result as the client would receive it from the server. */
+    const received = (type, udfPath, returned) => {
+        try {
+            return jsonToConvex(convexToJson((returned === undefined ? null : returned)));
+        }
+        catch (error) {
+            throw new Error(`The fake ${type} handler for ${udfPath} returned a value Convex can't send: ${asError(error).message}`);
+        }
+    };
+    let nextTraceId = 0;
+    const entries = new Map();
+    const queryEntry = (udfPath, args) => {
+        const token = JSON.stringify({
+            udfPath,
+            args: convexToJson(args),
+        });
+        const existing = entries.get(token);
+        if (existing !== undefined)
+            return existing;
+        const trace = `${name}.query#${udfPath}#${nextTraceId++}`;
+        const outcome = computed(() => {
+            const handler = handlers().query.get(udfPath);
+            if (handler === undefined)
+                throw miss("query", udfPath);
+            let returned;
+            try {
+                returned = handler(args, functionContext());
+            }
+            catch (error) {
+                return { status: "error", error: asError(error) };
+            }
+            if (returned === loading)
+                return { status: "loading" };
+            if (returned instanceof Promise) {
+                throw new Error(`The fake query handler for ${udfPath} returned a Promise. Query handlers are synchronous: return \`loading\` until an atom the handler reads changes.`);
+            }
+            return {
+                status: "success",
+                value: received("query", udfPath, returned),
+            };
+        }, `${trace}.outcome`);
+        const entry = {
+            token,
+            udfPath,
+            args,
+            result: computed(() => {
+                const current = outcome();
+                if (current.status === "loading")
+                    return undefined;
+                if (current.status === "success") {
+                    return { success: true, value: current.value, logLines: [] };
+                }
+                const { error } = current;
+                return {
+                    success: false,
+                    errorMessage: error.message,
+                    ...(error instanceof ConvexError
+                        ? { errorData: error.data }
+                        : {}),
+                    logLines: [],
+                };
+            }, trace),
+            data: computed(() => {
+                const current = outcome();
+                return current.status === "success" ? current.value : undefined;
+            }, `${trace}.data`),
+            error: computed(() => {
+                const current = outcome();
+                return current.status === "error" ? current.error : undefined;
+            }, `${trace}.error`),
+            status: computed(() => outcome().status, `${trace}.status`),
+        };
+        entries.set(token, entry);
+        return entry;
+    };
+    const paginated = new Map();
+    const paginatedQueryEntry = (udfPath, args, options) => {
+        const token = serializePaginatedPathAndArgs(udfPath, args, options);
+        const existing = paginated.get(token);
+        if (existing !== undefined)
+            return existing;
+        const created = reatomPaginatedQuery((pageUdfPath, pageArgs, paginationOpts) => queryEntry(pageUdfPath, { ...pageArgs, paginationOpts }), udfPath, args, options, `${name}.paginatedQuery#${udfPath}#${nextTraceId++}`);
+        paginated.set(token, created);
+        return created;
+    };
+    const request = (type) => action(async (udfPath, handler, args) => {
+        const call = { type, at: new Date() };
+        inflight.set((all) => [...all, call]);
+        try {
+            // The server gets its own copy of the arguments.
+            const serverArgs = jsonToConvex(convexToJson(args));
+            const returned = handler(serverArgs, functionContext());
+            return received(type, udfPath, await wrap(Promise.resolve(returned)));
+        }
+        finally {
+            inflight.set((all) => all.filter((current) => current !== call));
+        }
+    }, `${name}.${type}`);
+    const requests = { mutation: request("mutation"), action: request("action") };
+    const call = (type, ref, args) => {
+        const udfPath = functionName(ref);
+        const handler = peek(handlers)[type].get(udfPath);
+        if (handler === undefined)
+            throw miss(type, udfPath);
+        return requests[type](udfPath, handler, parseArgs(args));
+    };
+    const setAuth = action((fetchToken, onChange, _onRefreshChange) => {
+        const version = authVersion.set((current) => current + 1);
+        isAuthenticated.set(null);
+        isRefreshingAuth.set(false);
+        // The fetch outlives the caller's frame, like the real client's flow.
+        const accept = async () => {
+            let token;
+            try {
+                token = await wrap(fetchToken({ forceRefreshToken: false }));
+            }
+            catch {
+                token = null;
+            }
+            if (authVersion() !== version)
+                return;
+            if (token === null || token === undefined) {
+                authToken.set(undefined);
+                identity.set(null);
+                isAuthenticated.set(false);
+                onChange?.(false);
+                return;
+            }
+            authToken.set(token);
+            identity.set(identityFromToken(token));
+            isAuthenticated.set(true);
+            onChange?.(true);
+        };
+        void wrap(accept, context())();
+    }, `${name}.setAuth`);
+    const clearAuth = action(() => {
+        authVersion.set((current) => current + 1);
+        authToken.set(undefined);
+        identity.set(null);
+        isAuthenticated.set(false);
+        isRefreshingAuth.set(false);
+    }, `${name}.clearAuth`);
+    const fake = {
+        name,
+        url: `fake:${name}`,
+        connectionState: computed(() => {
+            const calls = inflight();
+            return {
+                hasInflightRequests: calls.length > 0,
+                isWebSocketConnected: connected(),
+                timeOfOldestInflightRequest: calls[0]?.at ?? null,
+                hasEverConnected: true,
+                connectionCount: 1,
+                connectionRetries: 0,
+                inflightMutations: calls.filter(({ type }) => type === "mutation")
+                    .length,
+                inflightActions: calls.filter(({ type }) => type === "action").length,
+            };
+        }, `${name}.connectionState`),
+        isAuthenticated,
+        isRefreshingAuth,
+        authClaims: computed(() => {
+            const token = authToken();
+            if (token === undefined)
+                return undefined;
+            let decoded;
+            try {
+                decoded = jwtDecode(token);
+            }
+            catch {
+                decoded = {};
+            }
+            return { token, decoded };
+        }, `${name}.authClaims`),
+        socketState: atom({ state: "ready", paused: "no" }, `${name}.socketState`),
+        identity,
+        connected,
+        get unhandled() {
+            return peek(unhandled);
+        },
+        query: (query, args) => queryEntry(functionName(query), parseArgs(args)),
+        paginatedQuery: (query, args, options) => paginatedQueryEntry(functionName(query), parseArgs(args), { initialNumItems: options.initialNumItems, id: options.id ?? -1 }),
+        mutation: (mutation, args) => call("mutation", mutation, args),
+        action: (action, args) => call("action", action, args),
+        setAuth,
+        clearAuth,
+        close: action(() => Promise.resolve(), `${name}.close`),
+        handleQuery: (query, handler) => register("query", query, handler),
+        handleMutation: (mutation, handler) => register("mutation", mutation, handler),
+        handleAction: (action, handler) => register("action", action, handler),
+    };
+    return fake;
+}

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/dist/browser/reatom/testing.d.ts

@@ -0,0 +1,4 @@
+export { loading, MissingHandlerError, paginate, reatomConvexClientFake, } from "./fake_client.js";
+export type { ActionHandler, FunctionContext, MutationHandler, QueryHandler, ReatomConvexClientFake, } from "./fake_client.js";
+export { fakeIdentity, fakeToken, reatomAuthProviderFake, reatomAuthStateFake, } from "./fake_auth.js";
+export type { AuthProviderFake, AuthProviderFakeOptions, ReatomAuthStateFake, } from "./fake_auth.js";

package/dist/browser/reatom/testing.js

@@ -0,0 +1,3 @@
+// The @reatomized/convex/testing entry point: fakes for UI tests and stories.
+export { loading, MissingHandlerError, paginate, reatomConvexClientFake, } from "./fake_client.js";
+export { fakeIdentity, fakeToken, reatomAuthProviderFake, reatomAuthStateFake, } from "./fake_auth.js";

package/dist/index.d.ts

@@ -1 +1 @@
-export declare const version = "1.48.0";
+export declare const version = "1.49.0";

package/dist/index.js

@@ -1 +1 @@
-export const version = "1.48.0";
+export const version = "1.49.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reatomized/convex",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A Convex sync client with its state in Reatom atoms",
   "keywords": [
     "convex",
@@ -33,6 +33,10 @@
       "types": "./dist/browser/reatom/better_auth.d.ts",
       "default": "./dist/browser/reatom/better_auth.js"
     },
+    "./testing": {
+      "types": "./dist/browser/reatom/testing.d.ts",
+      "default": "./dist/browser/reatom/testing.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -40,22 +44,30 @@
     "README.md",
     "LICENSE"
   ],
+  "workspaces": [
+    ".",
+    "packages/*"
+  ],
   "scripts": {
-    "build": "node scripts/build.mjs",
+    "build": "node scripts/build.mjs && npm run build --workspace @reatomized/convex-storybook",
     "prepack": "node scripts/build.mjs",
-    "typecheck": "tsc --noEmit",
+    "changeset": "changeset",
+    "version-packages": "changeset version && npm install --package-lock-only --ignore-scripts --allow-remote=root",
+    "release": "changeset publish",
+    "typecheck": "tsc --noEmit && npm run typecheck --workspace @reatomized/convex-storybook",
     "test": "vitest run",
     "lint": "eslint ."
   },
   "peerDependencies": {
     "@reatom/core": "^1001.3.0",
-    "convex": "^1.48.0"
+    "convex": "^1.49.0"
   },
   "devDependencies": {
+    "@changesets/cli": "^3.0.3",
     "@eslint/js": "^9.39.0",
     "@reatom/core": "https://pkg.pr.new/@reatom/core@5f42184",
     "@types/node": "^24.0.0",
-    "convex": "1.48.0",
+    "convex": "1.49.0",
     "eslint": "^9.39.0",
     "globals": "^17.4.0",
     "happy-dom": "^20.10.0",