convex 1.42.1 → 1.42.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "convex",
   "description": "Client for the Convex Cloud",
-  "version": "1.42.1",
+  "version": "1.42.2",
   "author": "Convex, Inc. <no-reply@convex.dev>",
   "homepage": "https://convex.dev",
   "repository": {
@@ -248,7 +248,7 @@
     "fetch-retry": "~6.0.0",
     "find-up": "^8.0.0",
     "globals": "~17.4.0",
-    "happy-dom": "~20.8.0",
+    "happy-dom": "~20.10.0",
     "jsdom": "~28.1.0",
     "json5": "~2.2.3",
     "knip": "~5.86.0",

package/src/browser/simple_client.ts

@@ -1,12 +1,4 @@
 import { validateDeploymentUrl } from "../common/index.js";
-import {
-  BaseConvexClient,
-  BaseConvexClientOptions,
-  MutationOptions,
-  PaginatedQueryToken,
-  QueryToken,
-  UserIdentityAttributes,
-} from "./index.js";
 import {
   FunctionArgs,
   FunctionReference,
@@ -15,13 +7,23 @@ import {
 } from "../server/index.js";
 import { getFunctionName } from "../server/api.js";
 import { AuthTokenFetcher } from "./sync/authentication_manager.js";
-import { ConnectionState } from "./sync/client.js";
+import {
+  BaseConvexClient,
+  BaseConvexClientOptions,
+  ConnectionState,
+  MutationOptions,
+} from "./sync/client.js";
 import {
   ExtendedTransition,
   PaginatedQueryClient,
 } from "./sync/paginated_query_client.js";
 import { PaginatedQueryResult } from "./sync/pagination.js";
-import { serializedQueryTokenIsPaginated } from "./sync/udf_path_utils.js";
+import { UserIdentityAttributes } from "./sync/protocol.js";
+import {
+  PaginatedQueryToken,
+  QueryToken,
+  serializedQueryTokenIsPaginated,
+} from "./sync/udf_path_utils.js";
 
 // In Node.js builds this points to a bundled WebSocket implementation. If no
 // WebSocket implementation is manually specified or globally available,

package/src/cli/codegen_templates/common.test.ts

@@ -0,0 +1,52 @@
+import { describe, test, expect } from "vitest";
+import { compareModulePaths } from "./common.js";
+
+describe("compareModulePaths", () => {
+  test("matches default sort order for forward slash paths", () => {
+    const paths = ["fooBaz.ts", "foo/bar.ts", "foo.ts"];
+    expect([...paths].sort(compareModulePaths)).toEqual([...paths].sort());
+  });
+
+  test("orders Windows paths identically to their POSIX equivalents", () => {
+    const posixPaths = ["fooBaz.ts", "foo/bar.ts", "foo.ts"];
+    const windowsPaths = posixPaths.map((p) => p.replace(/\//g, "\\"));
+
+    const sortedPosix = [...posixPaths].sort(compareModulePaths);
+    const sortedWindows = [...windowsPaths].sort(compareModulePaths);
+
+    expect(sortedPosix).toEqual(["foo.ts", "foo/bar.ts", "fooBaz.ts"]);
+    expect(sortedWindows.map((p) => p.replace(/\\/g, "/"))).toEqual(
+      sortedPosix,
+    );
+  });
+
+  test("default sort diverges on this input, demonstrating the bug", () => {
+    // "/" (0x2F) sorts before letters while "\" (0x5C) sorts after them,
+    // so the OS-native forms of the same file set sort differently.
+    const windowsPaths = ["fooBaz.ts", "foo\\bar.ts", "foo.ts"];
+    expect([...windowsPaths].sort()).toEqual([
+      "foo.ts",
+      "fooBaz.ts",
+      "foo\\bar.ts",
+    ]);
+    expect([...windowsPaths].sort(compareModulePaths)).toEqual([
+      "foo.ts",
+      "foo\\bar.ts",
+      "fooBaz.ts",
+    ]);
+  });
+
+  test("sorts nested directories before longer sibling file names", () => {
+    const paths = ["a/b/c.ts", "aZ.ts", "a.ts", "a/b.ts"];
+    expect([...paths].sort(compareModulePaths)).toEqual([
+      "a.ts",
+      "a/b.ts",
+      "a/b/c.ts",
+      "aZ.ts",
+    ]);
+    const windows = paths.map((p) => p.replace(/\//g, "\\"));
+    expect(
+      [...windows].sort(compareModulePaths).map((p) => p.replace(/\\/g, "/")),
+    ).toEqual(["a.ts", "a/b.ts", "a/b/c.ts", "aZ.ts"]);
+  });
+});

package/src/cli/codegen_templates/common.ts

@@ -43,3 +43,20 @@ const collator = new Intl.Collator("en-US", {
 export function compareStrings(a: string, b: string): number {
   return collator.compare(a, b);
 }
+
+/**
+ * Comparison function for sorting module paths in codegen output.
+ *
+ * Compares the forward slash normalized form of each path so the resulting
+ * order is identical on every platform. Sorting OS-native paths directly
+ * diverges on Windows because "\" (0x5C) sorts after letters while "/"
+ * (0x2F) sorts before them. Uses plain code unit comparison to match the
+ * default Array.prototype.sort() order these paths sorted with on POSIX.
+ *
+ * Usage: modulePaths.sort(compareModulePaths)
+ */
+export function compareModulePaths(a: string, b: string): number {
+  const aNormalized = a.replace(/\\/g, "/");
+  const bNormalized = b.replace(/\\/g, "/");
+  return aNormalized < bNormalized ? -1 : aNormalized > bNormalized ? 1 : 0;
+}

package/src/cli/dev.test.ts

@@ -0,0 +1,157 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import path from "path";
+import { nodeFs } from "../bundler/fs.js";
+import { dev } from "./dev.js";
+import { deploymentCredentialsOrConfigure } from "./configure.js";
+
+// In-memory filesystem — populated in beforeEach.
+let testFiles: Map<string, string>;
+// Everything written to stderr during a test, so we can assert on error output.
+let stderr: string;
+
+vi.mock("../bundler/fs.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../bundler/fs.js")>();
+  return {
+    ...actual,
+    nodeFs: {
+      ...actual.nodeFs,
+      exists: vi.fn(),
+      readUtf8File: vi.fn(),
+      writeUtf8File: vi.fn(),
+      mkdir: vi.fn(),
+    },
+  };
+});
+
+// `deploymentCredentialsOrConfigure` is where the CLI prompts the user to
+// create or select a project. We stub it out so we can assert *whether* it gets
+// reached — the whole point of the fast-fail check is that it should not.
+vi.mock("./configure.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./configure.js")>();
+  return {
+    ...actual,
+    deploymentCredentialsOrConfigure: vi.fn(),
+  };
+});
+
+// Avoid actually pushing if the action ever gets that far.
+vi.mock("./lib/dev.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./lib/dev.js")>();
+  return {
+    ...actual,
+    devAgainstDeployment: vi.fn(),
+  };
+});
+
+vi.mock("dotenv", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("dotenv")>();
+  return {
+    ...actual,
+    config: vi.fn(),
+  };
+});
+
+vi.mock("@sentry/node", () => ({
+  captureException: vi.fn(),
+  captureMessage: vi.fn(),
+  close: vi.fn(),
+}));
+
+describe("npx convex dev", () => {
+  let savedEnv: NodeJS.ProcessEnv;
+
+  beforeEach(() => {
+    savedEnv = { ...process.env };
+    process.env = {};
+
+    testFiles = new Map();
+    stderr = "";
+
+    vi.resetAllMocks();
+
+    vi.mocked(nodeFs.exists).mockImplementation((p: string) =>
+      testFiles.has(path.resolve(p)),
+    );
+    vi.mocked(nodeFs.readUtf8File).mockImplementation((p: string) => {
+      const content = testFiles.get(path.resolve(p));
+      if (content === undefined) {
+        const err: any = new Error(
+          `ENOENT: no such file or directory, open '${p}'`,
+        );
+        err.code = "ENOENT";
+        throw err;
+      }
+      return content;
+    });
+    vi.mocked(nodeFs.writeUtf8File).mockImplementation(
+      (p: string, content: string) => {
+        testFiles.set(path.resolve(p), content);
+      },
+    );
+
+    // `crash` calls `process.exit`; make it throw so `parseAsync` rejects.
+    vi.spyOn(process, "exit").mockImplementation((() => {
+      throw new Error("the CLI tried to exit the process");
+    }) as any);
+    vi.spyOn(process.stderr, "write").mockImplementation((chunk: any) => {
+      stderr += chunk.toString();
+      return true;
+    });
+  });
+
+  afterEach(() => {
+    process.env = savedEnv;
+    vi.restoreAllMocks();
+  });
+
+  it("fails fast without prompting to create/select a project when run outside a Convex project", async () => {
+    // A package.json with no `convex` dependency: this directory is not a
+    // Convex project.
+    testFiles.set(
+      path.resolve("package.json"),
+      JSON.stringify({ name: "not-a-convex-app", dependencies: {} }),
+    );
+
+    await expect(dev.parseAsync([], { from: "user" })).rejects.toThrow(
+      "the CLI tried to exit the process",
+    );
+
+    // The error must mention how to fix it...
+    expect(stderr).toContain("add `convex` to your package.json");
+    // ...and crucially, it must happen *before* we ever ask the user to create
+    // or select a project.
+    expect(deploymentCredentialsOrConfigure).not.toHaveBeenCalled();
+  });
+
+  it("fails fast when there is no package.json at all", async () => {
+    // Empty directory: no package.json.
+    await expect(dev.parseAsync([], { from: "user" })).rejects.toThrow(
+      "the CLI tried to exit the process",
+    );
+
+    expect(deploymentCredentialsOrConfigure).not.toHaveBeenCalled();
+  });
+
+  it("proceeds to project configuration once the Convex dependency check passes", async () => {
+    testFiles.set(
+      path.resolve("package.json"),
+      JSON.stringify({
+        name: "convex-app",
+        dependencies: { convex: "^1.0.0" },
+      }),
+    );
+
+    // Short-circuit right at the project-selection step so we don't run the
+    // rest of the dev flow; reaching this proves the dependency check passed.
+    const sentinel = new Error("reached project configuration");
+    vi.mocked(deploymentCredentialsOrConfigure).mockRejectedValue(sentinel);
+
+    // `--configure` skips deployment selection and goes straight to
+    // `deploymentCredentialsOrConfigure`.
+    await expect(
+      dev.parseAsync(["--configure"], { from: "user" }),
+    ).rejects.toThrow("reached project configuration");
+
+    expect(deploymentCredentialsOrConfigure).toHaveBeenCalledTimes(1);
+  });
+});

package/src/cli/dev.ts

@@ -9,6 +9,7 @@ import { devAgainstDeployment } from "./lib/dev.js";
 import {
   CONVEX_DEPLOYMENT_ENV_VAR_NAME,
   CONVEX_SELF_HOSTED_URL_VAR_NAME,
+  ensureHasConvexDependency,
 } from "./lib/utils/utils.js";
 import {
   getDeploymentSelection,
@@ -210,6 +211,12 @@ Same format as .env.local or .env files, and overrides them.`,
 
     const devOptions = await normalizeDevOptions(ctx, cmdOptions);
 
+    // Check that we're in a Convex project (a package.json with a `convex`
+    // dependency) before doing anything else, so we fail fast with a clear
+    // error instead of prompting to create/select a project and only then
+    // crashing because there's nothing to push.
+    await ensureHasConvexDependency(ctx, "run `npx convex dev`");
+
     if (cmdOptions.configure === undefined) {
       if (cmdOptions.team || cmdOptions.project || cmdOptions.devDeployment)
         return await ctx.crash({

package/src/cli/generatedApi.ts

@@ -405,7 +405,6 @@ export interface components {
             createTime: number;
             devDeploymentName?: string | null;
             id: components["schemas"]["ProjectId"];
-            isDemo: boolean;
             name: components["schemas"]["ProjectName"];
             prodDeploymentName?: string | null;
             slug: components["schemas"]["ProjectSlug"];

package/src/cli/lib/api.ts

@@ -35,7 +35,6 @@ export type Project = {
   id: number;
   name: string;
   slug: string;
-  isDemo: boolean;
 };
 
 type AdminKey = string;

package/src/cli/lib/codegen.ts

@@ -4,6 +4,7 @@ import { withTmpDir, TempDir } from "../../bundler/fs.js";
 import { entryPoints } from "../../bundler/index.js";
 import { apiCodegen } from "../codegen_templates/api.js";
 import { apiCjsCodegen } from "../codegen_templates/api_cjs.js";
+import { compareModulePaths } from "../codegen_templates/common.js";
 import {
   dynamicDataModelDTS,
   dynamicDataModelTS,
@@ -846,7 +847,7 @@ async function doApiCodegen(
   const absModulePaths = await entryPoints(ctx, functionsDir);
   const modulePaths = absModulePaths
     .map((p) => path.relative(functionsDir, p))
-    .sort();
+    .sort(compareModulePaths);
 
   const writtenFiles: string[] = [];
 

package/src/cli/lib/config.test.ts

@@ -257,10 +257,7 @@ test("parseProjectConfig - top-level validation", async () => {
     null,
     "✖ Expected `convex.json` to contain an object\n",
   );
-  await assertParseError(
-    [],
-    "✖ Expected `convex.json` to contain an object\n",
-  );
+  await assertParseError([], "✖ Expected `convex.json` to contain an object\n");
 });
 
 test("ensureConvexFunctionsDir - creates functions directory", async () => {

package/src/cli/lib/utils/utils.ts

@@ -602,18 +602,10 @@ export async function validateOrSelectProject(
     });
   }
   if (!projectSlug) {
-    const nonDemoProjects = projects.filter((project) => !project.isDemo);
-    if (nonDemoProjects.length === 0) {
-      return await ctx.crash({
-        exitCode: 1,
-        errorType: "fatal",
-        printedMessage: `No existing non-demo projects! Run this command again and choose "create a new project."`,
-      });
-    }
     // Prompt the user to select project.
-    switch (nonDemoProjects.length) {
+    switch (projects.length) {
       case 1: {
-        const project = nonDemoProjects[0];
+        const project = projects[0];
         const confirmed = await promptYesNo(ctx, {
           message: `${singleProjectPrompt} ${project.name} (${project.slug})?`,
         });
@@ -621,12 +613,12 @@ export async function validateOrSelectProject(
         if (!confirmed) {
           return null;
         }
-        return nonDemoProjects[0].slug;
+        return projects[0].slug;
       }
       default:
         return await promptSearch(ctx, {
           message: multiProjectPrompt,
-          choices: nonDemoProjects.map((project: Project) => ({
+          choices: projects.map((project: Project) => ({
             name: `${project.name} (${project.slug})`,
             value: project.slug,
           })),

package/src/index.ts

@@ -1 +1 @@
-export const version = "1.42.1";
+export const version = "1.42.2";

package/src/react/client.ts

@@ -287,7 +287,22 @@ export interface MutationOptions<Args extends Record<string, Value>> {
  *
  * @public
  */
-export interface ConvexReactClientOptions extends BaseConvexClientOptions {}
+export interface ConvexReactClientOptions extends BaseConvexClientOptions {
+  /**
+   * An already-constructed {@link BaseConvexClient} to use instead of
+   * constructing one internally. When provided, this client (and its
+   * derived {@link PaginatedQueryClient}) is used for all operations.
+   *
+   * @internal
+   */
+  baseClient?: BaseConvexClient;
+
+  // FIXME: Ideally we define `ConvexReactClientOptions` as
+  // `type ConvexReactClientOptions = BaseConvexClientOptions | { baseClient: BaseConvexClient }`
+  // so that callers won’t try to set `BaseConvexClientOptions` attributes that are ineffective.
+  // But since `baseClient` is internal at the moment, I don’t think we can do that.
+  // We can fix this if we ever make `baseClient` public.
+}
 
 /**
  * A Convex client for use within React.
@@ -367,11 +382,13 @@ export class ConvexReactClient {
       return this.cachedSync;
     }
     // BaseConvexClient and paginated query client are always created together.
-    this.cachedSync = new BaseConvexClient(
-      this.address,
-      () => {}, // Use the PaginatedQueryClient's transition instead.
-      this.options,
-    );
+    this.cachedSync =
+      this.options.baseClient ??
+      new BaseConvexClient(
+        this.address,
+        () => {}, // Use the PaginatedQueryClient's transition instead.
+        this.options,
+      );
     if (this.adminAuth) {
       this.cachedSync.setAdminAuth(this.adminAuth, this.fakeUserIdentity);
     }

package/src/react/client_provided_base_client.test.tsx

@@ -0,0 +1,56 @@
+import { test, expect, describe, vi } from "vitest";
+import ws from "ws";
+
+import { ConvexReactClient } from "./client.js";
+import { anyApi } from "../server/api.js";
+import { BaseConvexClient } from "../browser/index.js";
+
+const address = "https://127.0.0.1:3001";
+
+// A minimal subclass of `BaseConvexClient` used to prove that a
+// caller-provided `BaseConvexClient` (of any subclass) can be plugged into a
+// `ConvexReactClient` via the `client` option.
+class MinimalBaseConvexClient extends BaseConvexClient {}
+
+const testBaseConvexClient = () =>
+  new MinimalBaseConvexClient(address, () => {}, {
+    webSocketConstructor: ws as unknown as typeof WebSocket,
+  });
+
+describe("ConvexReactClient with a provided BaseConvexClient", () => {
+  test("uses the provided client as its `sync` client", () => {
+    const baseClient = testBaseConvexClient();
+    const client = new ConvexReactClient(address, { baseClient });
+    expect(client.sync).toBe(baseClient);
+  });
+
+  test("applies setAdminAuth called before the client is lazily instantiated", () => {
+    const baseClient = testBaseConvexClient();
+    const setAdminAuthSpy = vi.spyOn(baseClient, "setAdminAuth");
+    const client = new ConvexReactClient(address, { baseClient });
+    client.setAdminAuth("admin-token");
+    expect(setAdminAuthSpy).not.toHaveBeenCalled();
+
+    // Accessing `sync` lazily instantiates the client, applying admin auth.
+    expect(client.sync).toBe(baseClient);
+    expect(setAdminAuthSpy).toHaveBeenCalledWith("admin-token", undefined);
+  });
+
+  test("queries and mutations work through the provided client", async () => {
+    const baseClient = testBaseConvexClient();
+    const client = new ConvexReactClient(address, { baseClient });
+
+    void client.mutation(
+      anyApi.myMutation.default,
+      {},
+      {
+        optimisticUpdate: (localStore) => {
+          localStore.setQuery(anyApi.myQuery.default, {}, "queryResult");
+        },
+      },
+    );
+
+    const queryResult = client.query(anyApi.myQuery.default, {});
+    expect(await queryResult).toStrictEqual("queryResult");
+  });
+});

package/src/react-clerk/ConvexProviderWithClerk.tsx

@@ -22,6 +22,7 @@ type UseAuth = () => {
   // We don't use these properties but they should trigger a new token fetch.
   orgId: string | undefined | null;
   orgRole: string | undefined | null;
+  sessionId: string | undefined | null;
   sessionClaims: Record<string, unknown> | undefined | null;
 };
 
@@ -66,6 +67,7 @@ function useUseAuthFromClerk(useAuth: UseAuth) {
           getToken,
           orgId,
           orgRole,
+          sessionId,
           sessionClaims,
         } = useAuth();
         const fetchAccessToken = useCallback(
@@ -91,7 +93,7 @@ function useUseAuthFromClerk(useAuth: UseAuth) {
           // Anything else from the JWT Clerk wants to be reactive goes here too.
           // Clerk's Expo useAuth hook is not memoized so we don't include getToken.
           // eslint-disable-next-line react-hooks/exhaustive-deps
-          [orgId, orgRole],
+          [orgId, orgRole, sessionId],
         );
         return useMemo(
           () => ({

package/src/server/database.ts

@@ -140,8 +140,9 @@ export interface BaseTableReader<
  * @see https://docs.convex.dev/database/reading-data
  * @public
  */
-export interface GenericDatabaseReader<DataModel extends GenericDataModel>
-  extends BaseDatabaseReader<DataModel> {
+export interface GenericDatabaseReader<
+  DataModel extends GenericDataModel,
+> extends BaseDatabaseReader<DataModel> {
   /**
    * An interface to read from the system tables within Convex query functions.
    *
@@ -216,8 +217,9 @@ export interface GenericDatabaseReaderWithTable<
  * @see https://docs.convex.dev/database/writing-data
  * @public
  */
-export interface GenericDatabaseWriter<DataModel extends GenericDataModel>
-  extends GenericDatabaseReader<DataModel> {
+export interface GenericDatabaseWriter<
+  DataModel extends GenericDataModel,
+> extends GenericDatabaseReader<DataModel> {
   /**
    * Insert a new document into a table.
    *

package/src/server/impl/meta_impl.ts

@@ -54,9 +54,9 @@ async function getDeploymentMetadata(): Promise<DeploymentMetadata> {
 }
 
 async function getRequestMetadata(): Promise<RequestMetadata> {
-  const { ip, userAgent, requestId, scheduledFunctionId } =
+  const { ip, userAgent, requestId, scheduledFunctionId, authToken } =
     await performAsyncSyscall("1.0/getRequestMetadata", {});
-  return { ip, userAgent, requestId, scheduledFunctionId };
+  return { ip, userAgent, requestId, scheduledFunctionId, authToken };
 }
 
 export function setupQueryMeta(

package/src/server/impl/query_impl.ts

@@ -41,9 +41,7 @@ type SerializedQuery = {
   operators: Array<QueryOperator>;
 };
 
-export class QueryInitializerImpl
-  implements QueryInitializer<GenericTableInfo>
-{
+export class QueryInitializerImpl implements QueryInitializer<GenericTableInfo> {
   private tableName: string;
 
   constructor(tableName: string) {

package/src/server/meta.ts

@@ -114,6 +114,14 @@ export type RequestMetadata = {
    * `null` when the function was not scheduled.
    */
   scheduledFunctionId: string | null;
+  /**
+   * The raw auth token (a JWT) the request was authenticated with, or `null`
+   * when the request was unauthenticated or authenticated with an admin key.
+   *
+   * This is the same token that `ctx.auth.getUserIdentity()` derives its
+   * attributes from.
+   */
+  authToken: string | null;
 };
 
 /**

package/src/server/query.ts

@@ -26,8 +26,9 @@ import { SearchFilter, SearchFilterBuilder } from "./search_filter_builder.js";
  *
  * @public
  */
-export interface QueryInitializer<TableInfo extends GenericTableInfo>
-  extends Query<TableInfo> {
+export interface QueryInitializer<
+  TableInfo extends GenericTableInfo,
+> extends Query<TableInfo> {
   /**
    * Query by reading all of the values out of this table.
    *
@@ -163,8 +164,9 @@ export interface QueryInitializer<TableInfo extends GenericTableInfo>
  *
  * @public
  */
-export interface Query<TableInfo extends GenericTableInfo>
-  extends OrderedQuery<TableInfo> {
+export interface Query<
+  TableInfo extends GenericTableInfo,
+> extends OrderedQuery<TableInfo> {
   /**
    * Define the order of the query output.
    *
@@ -179,8 +181,9 @@ export interface Query<TableInfo extends GenericTableInfo>
  *
  * @public
  */
-export interface OrderedQuery<TableInfo extends GenericTableInfo>
-  extends AsyncIterable<DocumentByInfo<TableInfo>> {
+export interface OrderedQuery<
+  TableInfo extends GenericTableInfo,
+> extends AsyncIterable<DocumentByInfo<TableInfo>> {
   /**
    * Filter the query output, returning only the values for which `predicate` evaluates to true.
    *