@reatomized/convex 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Convex, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# @reatomized/convex
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [Convex](https://convex.dev) sync client whose state lives in
+[Reatom](https://github.com/reatom/reatom) v1001 atoms: queries, paginated
+queries, the connection and auth. It replaces `convex/browser`'s WebSocket
+client and nothing else, so keep the `convex` package for your functions, the
+CLI and codegen.
+
+```sh
+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.
+
+## Usage
+
+```ts
+import { reatomConvexClient } from "@reatomized/convex";
+import { atom, computed } from "@reatom/core";
+import { api } from "../convex/_generated/api";
+import type { Id } from "../convex/_generated/dataModel";
+
+const convex = reatomConvexClient(import.meta.env.VITE_CONVEX_URL);
+
+const noteId = atom<Id<"notes"> | null>(null);
+const note = computed(() => {
+  const id = noteId();
+  return id ? convex.query(api.notes.get, { id }).data() : undefined;
+});
+```
+
+- `convex.query(ref, args)` returns the entry for that function and arguments,
+  the same object for equal arguments. Its `result`, `data`, `error` and
+  `status` are atoms. Reading one in a subscribed graph subscribes the query on
+  the server; once nothing reads it, the query is unsubscribed.
+- Query set changes made in one microtask go out as one `ModifyQuerySet`. In the
+  example above, changing `noteId` sends one message that adds the new query and
+  removes the old one.
+- `convex.paginatedQuery(ref, args, { initialNumItems })` has `results`,
+  `status` and `error` atoms and a `loadMore` action. Equal arguments share
+  their pages; pass `id` for a separate page list.
+- `convex.mutation(ref, args, { optimisticUpdate })` and
+  `convex.action(ref, args)` return promises and run as Reatom actions. A failed
+  call rejects with a `ConvexError` from `convex/values` when the function threw
+  one.
+- `connectionState`, `isAuthenticated` (`null` while a token waits for the
+  server), `isRefreshingAuth`, `authClaims` and `socketState` are atoms.
+  `setAuth`, `clearAuth` and `close` are actions.
+
+State is per Reatom context: call the client inside a frame, and each context
+gets its own connection. The socket opens on first use in a context.
+
+There are no React hooks. Read the atoms through your Reatom view binding, such
+as `@reatom/react` or `@reatom/jsx`.
+
+## Node
+
+With `@reatom/core@1001.3.0` loaded, Node never exits on its own, so a script
+that uses this client hangs after its work is done. The fix is on Reatom's
+`v1001` branch; install that build in projects with such scripts (npm 12
+installs from a URL only with `--allow-remote`):
+
+```sh
+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`.
+
+## Differences from convex/browser 1.48.0
+
+- Query set changes are batched per microtask instead of sent one per subscribe
+  and unsubscribe.
+- A transition updates the queries it names. Optimistic updates replay only
+  while some are pending. convex/browser rebuilds and diffs every result on each
+  transition, which makes mounting N queries cost O(N²).
+- `clearAuth` stops the auth flow. In convex/browser a refetch scheduled before
+  `clearAuth` still runs and can authenticate the old session again.
+- When a token fetch returns `null` for a signed-in client, the client sends the
+  server `Authenticate` without a token. convex/browser drops that message while
+  the socket is paused for the fetch, so the server keeps the old identity.
+- With `expectAuth`, a socket that opened before the first token sends `Connect`
+  once the token arrives. convex/browser never sends it, and `hasEverConnected`
+  stays false.
+- A failed page of a paginated query lands in its `error` atom. In
+  convex/browser it throws out of the WebSocket message handler.
+- Server results stay visible across a reconnect until the new connection
+  answers.
+- Minified, the client is 13.8 KiB gzip, or 19.0 KiB with the parts of
+  `convex/values` and `convex/server` it uses, against 15.8 KiB for
+  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.
+[CONTRIBUTING.md](https://github.com/reatomized/convex/blob/reatom/CONTRIBUTING.md#performance)
+has the full table and how it was measured.
+
+## Development
+
+The repository is a fork of
+[convex/convex-js](https://github.com/convex/convex-js) cut down to this client
+and the upstream sync helpers it reuses. Server and value utilities are imported
+directly from the official `convex` peer in both source and builds.
+[CONTRIBUTING.md](https://github.com/reatomized/convex/blob/reatom/CONTRIBUTING.md)
+covers the layout, the parity tests against upstream's client, syncing with
+upstream, and releases.
+
+Apache-2.0, like convex-js.

package/dist/browser/logging.d.ts

@@ -0,0 +1,39 @@
+import { ConvexError, Value } from "convex/values";
+import { FunctionFailure } from "./sync/function_result.js";
+export type UdfType = "query" | "mutation" | "action" | "any";
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * A logger that can be used to log messages. By default, this is a wrapper
+ * around `console`, but can be configured to not log at all or to log somewhere
+ * else.
+ */
+export type Logger = {
+    logVerbose(...args: any[]): void;
+    log(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+};
+export declare class DefaultLogger implements Logger {
+    private _onLogLineFuncs;
+    private _verbose;
+    constructor(options: {
+        verbose: boolean;
+    });
+    addLogLineListener(func: (level: LogLevel, ...args: any[]) => void): () => void;
+    logVerbose(...args: any[]): void;
+    log(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+}
+export declare function instantiateDefaultLogger(options: {
+    verbose: boolean;
+}): Logger;
+export declare function instantiateNoopLogger(options: {
+    verbose: boolean;
+}): Logger;
+export declare function logForFunction(logger: Logger, type: "info" | "error", source: UdfType, udfPath: string, message: string | {
+    errorData: Value;
+}): void;
+export declare function logFatalError(logger: Logger, message: string): Error;
+export declare function createHybridErrorStacktrace(source: UdfType, udfPath: string, result: FunctionFailure): string;
+export declare function forwardData(result: FunctionFailure, error: ConvexError<string>): ConvexError<string>;

package/dist/browser/logging.js

@@ -0,0 +1,117 @@
+// This is blue #9 from https://www.radix-ui.com/docs/colors/palette-composition/the-scales
+// It must look good in both light and dark mode.
+const INFO_COLOR = "color:rgb(0, 145, 255)";
+function prefix_for_source(source) {
+    switch (source) {
+        case "query":
+            return "Q";
+        case "mutation":
+            return "M";
+        case "action":
+            return "A";
+        case "any":
+            return "?";
+    }
+}
+export class DefaultLogger {
+    _onLogLineFuncs;
+    _verbose;
+    constructor(options) {
+        this._onLogLineFuncs = {};
+        this._verbose = options.verbose;
+    }
+    addLogLineListener(func) {
+        let id = Math.random().toString(36).substring(2, 15);
+        for (let i = 0; i < 10; i++) {
+            if (this._onLogLineFuncs[id] === undefined) {
+                break;
+            }
+            id = Math.random().toString(36).substring(2, 15);
+        }
+        this._onLogLineFuncs[id] = func;
+        return () => {
+            delete this._onLogLineFuncs[id];
+        };
+    }
+    logVerbose(...args) {
+        if (this._verbose) {
+            for (const func of Object.values(this._onLogLineFuncs)) {
+                func("debug", `${new Date().toISOString()}`, ...args);
+            }
+        }
+    }
+    log(...args) {
+        for (const func of Object.values(this._onLogLineFuncs)) {
+            func("info", ...args);
+        }
+    }
+    warn(...args) {
+        for (const func of Object.values(this._onLogLineFuncs)) {
+            func("warn", ...args);
+        }
+    }
+    error(...args) {
+        for (const func of Object.values(this._onLogLineFuncs)) {
+            func("error", ...args);
+        }
+    }
+}
+export function instantiateDefaultLogger(options) {
+    const logger = new DefaultLogger(options);
+    logger.addLogLineListener((level, ...args) => {
+        switch (level) {
+            case "debug":
+                console.debug(...args);
+                break;
+            case "info":
+                console.log(...args);
+                break;
+            case "warn":
+                console.warn(...args);
+                break;
+            case "error":
+                console.error(...args);
+                break;
+            default: {
+                level;
+                console.log(...args);
+            }
+        }
+    });
+    return logger;
+}
+export function instantiateNoopLogger(options) {
+    return new DefaultLogger(options);
+}
+export function logForFunction(logger, type, source, udfPath, message) {
+    const prefix = prefix_for_source(source);
+    if (typeof message === "object") {
+        message = `ConvexError ${JSON.stringify(message.errorData, null, 2)}`;
+    }
+    if (type === "info") {
+        const match = message.match(/^\[.*?\] /);
+        if (match === null) {
+            logger.error(`[CONVEX ${prefix}(${udfPath})] Could not parse console.log`);
+            return;
+        }
+        const level = message.slice(1, match[0].length - 2);
+        const args = message.slice(match[0].length);
+        logger.log(`%c[CONVEX ${prefix}(${udfPath})] [${level}]`, INFO_COLOR, args);
+    }
+    else {
+        logger.error(`[CONVEX ${prefix}(${udfPath})] ${message}`);
+    }
+}
+export function logFatalError(logger, message) {
+    const errorMessage = `[CONVEX FATAL ERROR] ${message}`;
+    logger.error(errorMessage);
+    return new Error(errorMessage);
+}
+export function createHybridErrorStacktrace(source, udfPath, result) {
+    const prefix = prefix_for_source(source);
+    return `[CONVEX ${prefix}(${udfPath})] ${result.errorMessage}\n  Called by client`;
+}
+export function forwardData(result, error) {
+    error.data = result.errorData;
+    return error;
+}

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

@@ -0,0 +1,75 @@
+import { Logger } from "../logging.js";
+import { AuthError, Transition } from "../sync/protocol.js";
+/**
+ * An async function returning a JWT. Depending on the auth providers
+ * configured in convex/auth.config.ts, this may be a JWT-encoded OpenID
+ * Connect Identity Token or a traditional JWT.
+ *
+ * `forceRefreshToken` is `true` if the server rejected a previously
+ * returned token or the token is anticipated to expiring soon
+ * based on its `exp` time.
+ *
+ * See {@link ConvexReactClient.setAuth}.
+ *
+ * @public
+ */
+export type AuthTokenFetcher = (args: {
+    forceRefreshToken: boolean;
+}) => Promise<string | null | undefined>;
+export type AuthConfig = {
+    fetchToken: AuthTokenFetcher;
+    onAuthChange: (isAuthenticated: boolean) => void;
+    onRefreshChange?: ((isRefreshing: boolean) => void) | undefined;
+};
+export type AuthState = {
+    state: "noAuth";
+} | {
+    state: "waitingForServerConfirmationOfCachedToken";
+    config: AuthConfig;
+    hasRetried: boolean;
+} | {
+    state: "initialRefetch";
+    config: AuthConfig;
+} | {
+    state: "waitingForServerConfirmationOfFreshToken";
+    config: AuthConfig;
+    hadAuth: boolean;
+    token: string;
+} | {
+    state: "waitingForScheduledRefetch";
+    config: AuthConfig;
+    refetchTokenTimeoutId: ReturnType<typeof setTimeout>;
+} | {
+    state: "notRefetching";
+    config: AuthConfig;
+};
+/** The client's side of auth: its identity state and the socket. */
+export type AuthSync = {
+    isCurrentOrNewerAuthVersion(version: number): boolean;
+    markAuthCompletion(): void;
+    token(): string | undefined;
+    hasAuth(): boolean;
+    /** Sends `Authenticate` with the token. */
+    authenticate(token: string): void;
+    /** Forgets the token without sending anything; the socket is stopped. */
+    dropAuth(): void;
+    /** Forgets the token and sends `Authenticate` with none. */
+    clearAuth(): void;
+    stopSocket(): Promise<void>;
+    tryRestartSocket(): void;
+    pauseSocket(): void;
+    resumeSocket(): void;
+};
+export declare function reatomAuth(sync: AuthSync, options: {
+    logger: Logger;
+    refreshTokenLeewaySeconds: number;
+    initialAuthTokenReuse: boolean;
+}, 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>;
+    onTransition(serverMessage: Transition): void;
+    onAuthError(serverMessage: AuthError): void;
+    stop(): void;
+};
+export type ReatomAuth = ReturnType<typeof reatomAuth>;