@reatomized/convex 0.3.1 → 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
 
@@ -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
 

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/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.1",
+  "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",