convex 1.42.2 → 1.43.0-alpha.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "convex",
   "description": "Client for the Convex Cloud",
-  "version": "1.42.2",
+  "version": "1.43.0-alpha.0",
   "author": "Convex, Inc. <no-reply@convex.dev>",
   "homepage": "https://convex.dev",
   "repository": {
@@ -204,10 +204,15 @@
     "@babel/types": "^7.27.1",
     "@clerk/react": "^6.4.3",
     "@commander-js/extra-typings": "^14.0.0",
-    "@convex-dev/platform": "0.1.9",
+    "@convex-dev/platform": "0.1.10",
     "@eslint/compat": "~2.0.0",
     "@eslint/eslintrc": "^3",
     "@eslint/js": "~9.39.0",
+    "@inquirer/confirm": "^6.0.4",
+    "@inquirer/input": "^5.0.4",
+    "@inquirer/search": "^4.1.0",
+    "@inquirer/select": "^5.0.4",
+    "@inquirer/testing": "^3.3.0",
     "@modelcontextprotocol/sdk": "^1.25.2",
     "@octokit/openapi-types": "~27.0.0",
     "@sentry/node": "^7.23.0",
@@ -217,11 +222,6 @@
     "@types/adm-zip": "^0.5.7",
     "@types/babel__code-frame": "^7.0.6",
     "@types/deep-equal": "1.0.4",
-    "@inquirer/confirm": "^6.0.4",
-    "@inquirer/input": "^5.0.4",
-    "@inquirer/search": "^4.1.0",
-    "@inquirer/select": "^5.0.4",
-    "@inquirer/testing": "^3.3.0",
     "@types/node": "^18.17.0",
     "@types/react": "^18.0.0",
     "@types/react-dom": "^18.0.0",
@@ -271,8 +271,8 @@
     "typedoc": "^0.24.6",
     "typescript": "~5.0.3",
     "typescript-eslint": "~8.57.0",
-    "vitest": "^4.1.0",
     "undici": "7.28.0",
+    "vitest": "^4.1.0",
     "wait-for-expect": "~4.0.0",
     "zod": "^3.24.0",
     "zod-to-json-schema": "^3.24.0"

package/schemas/convex.schema.json

@@ -180,7 +180,8 @@
     "typescriptCompiler": {
       "type": "string",
       "enum": ["tsc", "tsgo"],
-      "description": "TypeScript compiler to use for typechecking (`@typescript/native-preview` must be installed to use `tsgo`)"
+      "description": "Deprecated. Set to `tsgo` to use the TypeScript Native Preview compiler (`@typescript/native-preview`). TypeScript 7 uses the native compiler without needing this setting to be set.",
+      "deprecated": true
     },
     "authKit": {
       "$ref": "#/definitions/authKitConfig"

package/src/browser/index.ts

@@ -24,6 +24,8 @@ export type {
   ConnectionState,
   AuthTokenFetcher,
 } from "./sync/client.js";
+/** @internal */
+export type { BaseConvexClientInterface } from "./sync/client.js";
 export type { PaginationStatus } from "./sync/pagination.js";
 export type { ConvexClientOptions } from "./simple_client.js";
 export { ConvexClient } from "./simple_client.js";

package/src/browser/sync/client.test.ts

@@ -4,9 +4,16 @@
 
 import { test, expect } from "vitest";
 
-import { BaseConvexClient } from "./client.js";
+import { BaseConvexClient, BaseConvexClientInterface } from "./client.js";
 import { anyApi } from "../../server/api.js";
 
+// Compile-time assertion that `BaseConvexClient` satisfies
+// `BaseConvexClientInterface`. We can't use an `implements` clause on the class
+// because `BaseConvexClientInterface` is `@internal`: that would leak the
+// interface name into the public `.d.ts` where it has been stripped.
+const _assertBaseConvexClientImplementsInterface: BaseConvexClientInterface =
+  undefined as unknown as BaseConvexClient;
+
 test("localQueryResult reflects optimistic results", async () => {
   const client = new BaseConvexClient("http://127.0.0.1:8000", () => {
     // ignore updates.

package/src/browser/sync/client.ts

@@ -1126,3 +1126,66 @@ export class BaseConvexClient {
       });
   }
 }
+
+/**
+ * The public API of {@link BaseConvexClient}.
+ *
+ * @internal
+ */
+export interface BaseConvexClientInterface {
+  addOnTransitionHandler(fn: (transition: Transition) => void): () => void;
+
+  setAuth(
+    fetchToken: AuthTokenFetcher,
+    onChange: (isAuthenticated: boolean) => void,
+    onRefreshChange?: (isRefreshing: boolean) => void,
+  ): void;
+
+  /** @internal */
+  setAdminAuth(value: string, fakeUserIdentity?: UserIdentityAttributes): void;
+
+  clearAuth(): void;
+
+  subscribe(
+    name: string,
+    args?: Record<string, Value>,
+    options?: SubscribeOptions,
+  ): { queryToken: QueryToken; unsubscribe: () => void };
+
+  localQueryResult(
+    udfPath: string,
+    args?: Record<string, Value>,
+  ): Value | undefined;
+
+  localQueryResultByToken(queryToken: QueryToken): Value | undefined;
+
+  hasLocalQueryResultByToken(queryToken: QueryToken): boolean;
+
+  localQueryLogs(
+    udfPath: string,
+    args?: Record<string, Value>,
+  ): string[] | undefined;
+
+  queryJournal(
+    name: string,
+    args?: Record<string, Value>,
+  ): QueryJournal | undefined;
+
+  connectionState(): ConnectionState;
+
+  subscribeToConnectionState(
+    cb: (connectionState: ConnectionState) => void,
+  ): () => void;
+
+  mutation(
+    name: string,
+    args?: Record<string, Value>,
+    options?: MutationOptions,
+  ): Promise<any>;
+
+  action(name: string, args?: Record<string, Value>): Promise<any>;
+
+  close(): Promise<void>;
+
+  readonly url: string;
+}

package/src/browser/sync/paginated_query_client.test.ts

@@ -1,17 +1,150 @@
 import { test, expect, describe } from "vitest";
 
 import { BaseConvexClient } from "./client.js";
-import { QuerySetModification } from "./protocol.js";
+import {
+  ClientMessage,
+  QuerySetModification,
+  WireServerMessage,
+} from "./protocol.js";
 import {
   nodeWebSocket,
   UpdateQueue,
   withInMemoryWebSocket,
 } from "./client_node_test_helpers.js";
 import { PaginationOptions } from "../../server/pagination.js";
+import { JSONValue } from "../../values/index.js";
 import { Long } from "../../vendor/long.js";
 import { anyApi } from "../../server/index.js";
 import { PaginatedQueryClient } from "./paginated_query_client.js";
 
+/**
+ * A faithful in-memory pagination backend for the split test below. It answers
+ * each page query by slicing `data` according to the `cursor`/`endCursor` it
+ * actually receives, so the test can assert on the pages the client ends up
+ * with rather than on the arguments the client happened to send. Cursors are
+ * opaque to callers: internally they encode an offset into `data`.
+ */
+class FakePaginationServer {
+  // The client only requires each transition's startVersion to equal the
+  // previous endVersion; the querySet/ts numbers are otherwise unconstrained.
+  private querySetVersion = 0;
+  private ts = 0;
+
+  constructor(
+    private io: {
+      receive: () => Promise<ClientMessage>;
+      send: (message: WireServerMessage) => void;
+    },
+    private data: JSONValue[],
+    // A freshly loaded page (one requested without an endCursor) comes back with
+    // a `splitCursor` and `SplitRecommended` once it reaches this many items.
+    // Split halves carry an endCursor and are never re-split, so the server
+    // converges. Omit to never recommend a split.
+    private options: { splitThreshold?: number } = {},
+  ) {}
+
+  private toOffset(cursor: string | null | undefined): number {
+    return cursor === null || cursor === undefined
+      ? 0
+      : parseInt(cursor.slice(1));
+  }
+
+  private toCursor(offset: number): string {
+    return `c${offset}`;
+  }
+
+  private pageResult(paginationOpts: {
+    cursor: string | null;
+    endCursor?: string | null;
+    numItems: number;
+  }): JSONValue {
+    const start = this.toOffset(paginationOpts.cursor);
+    const hasEndCursor =
+      paginationOpts.endCursor !== null &&
+      paginationOpts.endCursor !== undefined;
+    const end = hasEndCursor
+      ? this.toOffset(paginationOpts.endCursor)
+      : Math.min(start + paginationOpts.numItems, this.data.length);
+    const page = this.data.slice(start, end);
+    const recommendSplit =
+      !hasEndCursor &&
+      this.options.splitThreshold !== undefined &&
+      page.length >= this.options.splitThreshold;
+    return {
+      page,
+      isDone: end >= this.data.length,
+      continueCursor: this.toCursor(end),
+      splitCursor: recommendSplit
+        ? this.toCursor(start + Math.floor(page.length / 2))
+        : null,
+      pageStatus: recommendSplit ? "SplitRecommended" : null,
+    };
+  }
+
+  /**
+   * Consume the connection handshake: the client's `Connect` message and the
+   * (empty) query set it sends on connecting.
+   */
+  async awaitConnect(): Promise<void> {
+    const connect = await this.io.receive();
+    if (connect.type !== "Connect") {
+      throw new Error(`Expected Connect, received ${connect.type}`);
+    }
+    const initialQuerySet = await this.io.receive();
+    if (initialQuerySet.type !== "ModifyQuerySet") {
+      throw new Error(
+        `Expected initial ModifyQuerySet, received ${initialQuerySet.type}`,
+      );
+    }
+  }
+
+  /**
+   * Receive query subscriptions until `count` new pages (Add modifications)
+   * have been requested, then answer them all in a single transition.
+   */
+  async answerNextQueries({ count }: { count: number }): Promise<void> {
+    const adds: { queryId: number; args: JSONValue[] }[] = [];
+    while (adds.length < count) {
+      const message = await this.io.receive();
+      if (message.type !== "ModifyQuerySet") {
+        throw new Error(`Expected ModifyQuerySet, received ${message.type}`);
+      }
+      for (const modification of message.modifications) {
+        if (modification.type === "Add") {
+          adds.push({ queryId: modification.queryId, args: modification.args });
+        }
+      }
+    }
+
+    const startVersion = {
+      querySet: this.querySetVersion,
+      identity: 0,
+      ts: Long.fromNumber(this.ts),
+    };
+    this.querySetVersion += 1;
+    this.ts += 1;
+    this.io.send({
+      type: "Transition",
+      startVersion,
+      endVersion: {
+        querySet: this.querySetVersion,
+        identity: 0,
+        ts: Long.fromNumber(this.ts),
+      },
+      modifications: adds.map((add) => ({
+        type: "QueryUpdated" as const,
+        queryId: add.queryId,
+        value: this.pageResult(
+          (add.args[0] as unknown as { paginationOpts: PaginationOptions })
+            .paginationOpts,
+        ),
+        logLines: [],
+        journal: null,
+      })),
+    });
+  }
+}
+
 describe("BaseConvexClient paginated queries with server mocked at ws level", () => {
   test("Subscribing and adding a page", async () => {
     await withInMemoryWebSocket(async ({ address, receive, send }) => {
@@ -231,6 +364,81 @@ describe("BaseConvexClient paginated queries with server mocked at ws level", ()
       await client.close();
     });
   });
+
+  test("Splitting a non-first page yields the correct concatenated pages", async () => {
+    await withInMemoryWebSocket(async ({ address, receive, send }) => {
+      const DATA = ["a", "b", "c", "d", "e", "f", "g", "h"];
+      // Recommend splitting any full 5-item page, so the oversized second page
+      // (loaded with numItems 5) splits while the 3-item first page does not.
+      const server = new FakePaginationServer({ receive, send }, DATA, {
+        splitThreshold: 5,
+      });
+
+      const q = new UpdateQueue();
+      const client = new BaseConvexClient(
+        address,
+        () => {}, // use paginated query client for all transitions
+        {
+          webSocketConstructor: nodeWebSocket,
+          unsavedChangesWarning: false,
+        },
+      );
+
+      const paginatedClient: PaginatedQueryClient = new PaginatedQueryClient(
+        client,
+        ({ queries, paginatedQueries }) =>
+          q.onTransition(
+            client,
+            paginatedClient,
+          )([
+            ...queries.map((t) => t.token),
+            ...paginatedQueries.map((t) => t.token),
+          ]),
+      );
+
+      const getResult = () =>
+        paginatedClient.localQueryResult(
+          "myQuery",
+          { channel: "general" },
+          { initialNumItems: 3, id: 1 },
+        );
+
+      await server.awaitConnect();
+
+      paginatedClient.subscribe(
+        "myQuery",
+        { channel: "general" },
+        { initialNumItems: 3, id: 1 },
+      );
+
+      let i = 0;
+
+      // Load the first page: DATA[0..3) = [a, b, c].
+      await server.answerNextQueries({ count: 1 });
+      await q.awaitPromiseAtIndexWithTimeout(i++);
+      expect(getResult()?.results).toEqual(["a", "b", "c"]);
+      expect(getResult()?.status).toEqual("CanLoadMore");
+
+      // Load a second page, which starts at the first page's continueCursor and
+      // comes back oversized so the server recommends a split.
+      getResult()!.loadMore(5);
+      await q.awaitPromiseAtIndexWithTimeout(i++);
+      await server.answerNextQueries({ count: 1 });
+      await q.awaitPromiseAtIndexWithTimeout(i++);
+
+      // The split subscribes two new page queries. Answer both together so the
+      // split completes in a single transition.
+      await server.answerNextQueries({ count: 2 });
+      await q.awaitPromiseAtIndexWithTimeout(i++);
+
+      // The visible pages must be the dataset exactly once, in order — no rows
+      // duplicated from re-reading the start of the dataset in a split half.
+      expect(getResult()?.results).toEqual(DATA);
+      expect(getResult()?.status).toEqual("Exhausted");
+
+      await client.close();
+    });
+  });
 });
 
 describe("BaseConvexClient paginated queries without connecting", () => {

package/src/browser/sync/paginated_query_client.ts

@@ -17,7 +17,7 @@ import {
   serializePaginatedPathAndArgs,
   canonicalizeUdfPath,
 } from "./udf_path_utils.js";
-import { BaseConvexClient, Transition } from "./client.js";
+import { BaseConvexClientInterface, Transition } from "./client.js";
 import {
   PaginatedQueryResult,
   PaginationStatus,
@@ -46,7 +46,7 @@ type LocalPaginatedQuery = {
   // Map page keys to their query subscriptions
   pageKeyToQuery: Map<
     QueryPageKey,
-    { queryToken: QueryToken; unsubscribe: () => void }
+    { queryToken: QueryToken; unsubscribe: () => void; cursor: string | null }
   >;
   ongoingSplits: Map<QueryPageKey, [QueryPageKey, QueryPageKey]>;
   skip: boolean;
@@ -74,6 +74,7 @@ export type ExtendedTransition = Transition & {
   }>;
 };
 
+/** @internal */
 export class PaginatedQueryClient {
   private paginatedQuerySet: Map<PaginatedQueryToken, LocalPaginatedQuery> =
     new Map();
@@ -81,7 +82,7 @@ export class PaginatedQueryClient {
   private lastTransitionTs: TS;
 
   constructor(
-    private client: BaseConvexClient,
+    private client: BaseConvexClientInterface,
     private onTransition: (transition: ExtendedTransition) => void,
   ) {
     // Nonsense initial value to construct synthetic Transitions
@@ -387,8 +388,11 @@ export class PaginatedQueryClient {
           continue; // Already splitting
         }
 
-        const pageToken = pageKeyToQuery.get(pageKey)!.queryToken;
-        const pageResult = getResult(pageToken);
+        const pageEntry = pageKeyToQuery.get(pageKey);
+        if (!pageEntry) {
+          throw new Error(`No page query for active pageKey ${pageKey}`);
+        }
+        const pageResult = getResult(pageEntry.queryToken);
         if (!pageResult) {
           continue;
         }
@@ -406,6 +410,7 @@ export class PaginatedQueryClient {
           this.splitPaginatedQueryPage(
             paginatedQuery,
             pageKey,
+            pageEntry.cursor,
             result.splitCursor!, // we just checked
             result.continueCursor,
           );
@@ -417,31 +422,38 @@ export class PaginatedQueryClient {
   private splitPaginatedQueryPage(
     paginatedQuery: LocalPaginatedQuery,
     pageKey: QueryPageKey,
+    // Where the page being split started.
+    startCursor: string | null,
+    // The split position - will be end of the first split page and the start
+    // of the second.
     splitCursor: string,
+    // Where the page being split ended.
     continueCursor: string | null,
   ): void {
     const splitKey1 = paginatedQuery.nextPageKey++;
     const splitKey2 = paginatedQuery.nextPageKey++;
 
     const paginationOpts: Value = {
-      cursor: continueCursor,
       numItems: paginatedQuery.options.initialNumItems,
       id: paginatedQuery.id,
     };
 
-    // First split page: same cursor as original, but add endCursor at splitCursor
+    // First split page: same cursor as the original page, ending at splitCursor
     const firstSubscription = this.client.subscribe(
       paginatedQuery.canonicalizedUdfPath,
       {
         ...paginatedQuery.args,
         paginationOpts: {
           ...paginationOpts,
-          cursor: null, // Start from beginning for first split
+          cursor: startCursor,
           endCursor: splitCursor,
         },
       },
     );
-    paginatedQuery.pageKeyToQuery.set(splitKey1, firstSubscription);
+    paginatedQuery.pageKeyToQuery.set(splitKey1, {
+      ...firstSubscription,
+      cursor: startCursor,
+    });
 
     // Second split page: cursor starts at splitCursor, endCursor is the original continueCursor
     const secondSubscription = this.client.subscribe(
@@ -455,7 +467,10 @@ export class PaginatedQueryClient {
         },
       },
     );
-    paginatedQuery.pageKeyToQuery.set(splitKey2, secondSubscription);
+    paginatedQuery.pageKeyToQuery.set(splitKey2, {
+      ...secondSubscription,
+      cursor: splitCursor,
+    });
 
     paginatedQuery.ongoingSplits.set(pageKey, [splitKey1, splitKey2]);
   }
@@ -488,7 +503,10 @@ export class PaginatedQueryClient {
     );
 
     paginatedQuery.pageKeys.push(pageKey);
-    paginatedQuery.pageKeyToQuery.set(pageKey, subscription);
+    paginatedQuery.pageKeyToQuery.set(pageKey, {
+      ...subscription,
+      cursor: continueCursor,
+    });
     return subscription;
   }
 

package/src/cli/codegen_templates/component_api.ts

@@ -9,7 +9,12 @@ import {
 } from "../lib/components/definition/directoryStructure.js";
 import { StartPushResponse } from "../lib/deployApi/startPush.js";
 import { importPath, moduleIdentifier } from "./api.js";
-import { apiComment, compareStrings, header } from "./common.js";
+import {
+  apiComment,
+  compareModulePaths,
+  compareStrings,
+  header,
+} from "./common.js";
 import {
   ComponentExports,
   EvaluatedComponentDefinition,
@@ -346,7 +351,7 @@ async function* codegenDynamicApiObjects(
   const absModulePaths = await entryPoints(ctx, componentDirectory.path);
   const modulePaths = absModulePaths
     .map((p) => path.relative(componentDirectory.path, p))
-    .sort();
+    .sort(compareModulePaths);
   for (const modulePath of modulePaths) {
     const ident = moduleIdentifier(modulePath);
     const path = importPath(modulePath);
@@ -382,7 +387,7 @@ async function* codegenDynamicApiObjectsTS(
   const absModulePaths = await entryPoints(ctx, componentDirectory.path);
   const modulePaths = absModulePaths
     .map((p) => path.relative(componentDirectory.path, p))
-    .sort();
+    .sort(compareModulePaths);
   for (const modulePath of modulePaths) {
     const ident = moduleIdentifier(modulePath);
     const path = importPath(modulePath);

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

@@ -0,0 +1,31 @@
+import { describe, test, expect } from "vitest";
+import { validatorToType } from "./validator_helpers.js";
+
+describe("validatorToType", () => {
+  test("commitTs matches Infer<v.commitTs()>, valid in any generated file", () => {
+    // Writes go through `db.vars.commitTs` (a `CommitTsPlaceholder`), so a
+    // bigint-only type would reject the intended insert/patch value.
+    expect(validatorToType({ type: "commitTs" }, false)).toEqual(
+      'bigint | import("convex/values").CommitTsPlaceholder',
+    );
+  });
+
+  test("commitTs composes into container types", () => {
+    expect(
+      validatorToType(
+        {
+          type: "object",
+          value: {
+            commitTs: { fieldType: { type: "commitTs" }, optional: false },
+          },
+        },
+        false,
+      ),
+    ).toEqual(
+      '{ commitTs: bigint | import("convex/values").CommitTsPlaceholder }',
+    );
+    expect(
+      validatorToType({ type: "array", value: { type: "commitTs" } }, false),
+    ).toEqual('Array<bigint | import("convex/values").CommitTsPlaceholder>');
+  });
+});

package/src/cli/codegen_templates/validator_helpers.ts

@@ -21,6 +21,12 @@ export function validatorToType(
     return "number";
   } else if (validator.type === "bigint") {
     return "bigint";
+  } else if (validator.type === "commitTs") {
+    // Match `Infer<v.commitTs()>`: the field holds a bigint once committed,
+    // but writes go through `db.vars.commitTs` (a `CommitTsPlaceholder`) and
+    // same-mutation read-backs yield the placeholder. The inline import keeps
+    // this valid in every generated file regardless of its header imports.
+    return 'bigint | import("convex/values").CommitTsPlaceholder';
   } else if (validator.type === "boolean") {
     return "boolean";
   } else if (validator.type === "string") {

package/src/cli/deployment.ts

@@ -2,10 +2,13 @@ import { Command } from "@commander-js/extra-typings";
 import { deploymentSelect } from "./deploymentSelect.js";
 import { deploymentCreate } from "./deploymentCreate.js";
 import { deploymentToken } from "./deploymentToken.js";
+import { usage, usageLimits } from "./usageLimits.js";
 
 export const deployment = new Command("deployment")
   .summary("Manage deployments")
   .description("Manage deployments in your project.")
   .addCommand(deploymentSelect)
   .addCommand(deploymentCreate)
-  .addCommand(deploymentToken);
+  .addCommand(deploymentToken)
+  .addCommand(usage)
+  .addCommand(usageLimits);

package/src/cli/deploymentCreate.test.ts

@@ -9,7 +9,7 @@ import {
   selectRegion,
   logNoDefaultRegionMessage,
 } from "./lib/utils/utils.js";
-import { PlatformProjectDetails } from "@convex-dev/platform/managementApi";
+import { ProjectResponse } from "@convex-dev/platform/managementApi";
 import {
   DeploymentSelection,
   getDeploymentSelection,
@@ -190,7 +190,7 @@ const fakeProject = {
   createTime: 0,
   name: "My Project",
   teamSlug: "my-team",
-} satisfies PlatformProjectDetails;
+} satisfies ProjectResponse;
 
 const createdDeployment = {
   kind: "cloud" as const,

package/src/cli/deploymentCreate.ts

@@ -20,7 +20,7 @@ import {
   typedBigBrainClient,
   typedPlatformClient,
 } from "./lib/utils/utils.js";
-import { PlatformProjectDetails } from "@convex-dev/platform/managementApi";
+import { ProjectResponse } from "@convex-dev/platform/managementApi";
 import { getTeamAndProjectFromPreviewAdminKey } from "./lib/deployment.js";
 import { saveSelectedDeployment } from "./deploymentSelect.js";
 import { promptOptions, promptString } from "./lib/utils/prompts.js";
@@ -710,7 +710,7 @@ function parseLocalCreateTarget(
 async function resolveProject(
   ctx: Context,
   deploymentSelection: DeploymentSelection,
-): Promise<PlatformProjectDetails> {
+): Promise<ProjectResponse> {
   switch (deploymentSelection.kind) {
     case "existingDeployment": {
       const { deploymentFields } = deploymentSelection.deploymentToActOn;