convex 1.41.0 → 1.42.1

package/src/cli/program.ts

@@ -21,6 +21,7 @@ import { logout } from "./logout.js";
 import { logs } from "./logs.js";
 import { mcp } from "./mcp.js";
 import { networkTest } from "./network_test.js";
+import { project } from "./project.js";
 import { reinit } from "./reinit.js";
 import { run } from "./run.js";
 import { typecheck } from "./typecheck.js";
@@ -51,6 +52,7 @@ export function buildProgram() {
       .addCommand(env)
       .addCommand(data)
       .addCommand(deployment)
+      .addCommand(project)
       .addCommand(codegen)
       .addCommand(update)
       .addCommand(logout)

package/src/cli/project.ts

@@ -0,0 +1,7 @@
+import { Command } from "@commander-js/extra-typings";
+import { projectCreate } from "./projectCreate.js";
+
+export const project = new Command("project")
+  .summary("Manage projects")
+  .description("Manage projects in your team.")
+  .addCommand(projectCreate);

package/src/cli/projectCreate.ts

@@ -0,0 +1,99 @@
+import { Command, Option } from "@commander-js/extra-typings";
+import { oneoffContext } from "../bundler/context.js";
+import { logFinishedStep, logMessage, showSpinner } from "../bundler/log.js";
+import { chalkStderr } from "chalk";
+import { createProject } from "./lib/api.js";
+import { ensureAuthCanCreateDeployment } from "./lib/deploymentSelection.js";
+import { validateOrSelectTeam } from "./lib/utils/utils.js";
+import { promptString } from "./lib/utils/prompts.js";
+import { projectDashboardUrl } from "./lib/dashboard.js";
+
+type ProjectCreateOptions = {
+  team?: string | undefined;
+};
+
+async function runProjectCreate(
+  nameArg: string | undefined,
+  options: ProjectCreateOptions,
+): Promise<void> {
+  const ctx = await oneoffContext({
+    url: undefined,
+    adminKey: undefined,
+    envFile: undefined,
+  });
+
+  // Creating a project goes through the platform API, which accepts personal
+  // access tokens and project keys but not deployment/preview deploy keys.
+  // Fail fast (and clearly) for the unsupported keys rather than surfacing an
+  // opaque error later.
+  await ensureAuthCanCreateDeployment(ctx);
+
+  const { team } = await validateOrSelectTeam(ctx, options.team, "Team:");
+
+  let projectName = nameArg;
+  if (!projectName) {
+    if (!process.stdin.isTTY) {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage:
+          "Specify a project name:\n" + "  `npx convex project create my-app`",
+      });
+    }
+    projectName = await promptString(ctx, {
+      message: "Project name:",
+    });
+  }
+
+  showSpinner(`Creating project ${projectName}...`);
+  // `project create` only creates the project. Provisioning a deployment is a
+  // separate, explicit step (`npx convex deployment create`) so this command
+  // doesn't have to mirror every deployment setting (region, class, ...).
+  const { projectSlug } = await createProject(ctx, {
+    teamId: team.id,
+    projectName,
+    deploymentToProvision: null,
+  });
+
+  logFinishedStep(
+    `Created project ${chalkStderr.bold(projectSlug)} in team ` +
+      `${chalkStderr.bold(team.slug)}, manage it at ${chalkStderr.bold(
+        projectDashboardUrl(team.slug, projectSlug),
+      )}`,
+  );
+  logMessage(
+    chalkStderr.gray(
+      `Next, add a deployment with ` +
+        `\`npx convex deployment create ${team.slug}:${projectSlug}:dev --type dev\` ` +
+        `(pass \`--region us\` to choose a region).`,
+    ),
+  );
+}
+
+export const projectCreate = new Command("create")
+  .summary("Create a new project")
+  .description(
+    [
+      "Create a new project.",
+      "",
+      "Provisioning a deployment is a separate step — after creating the",
+      "project, run `npx convex deployment create` to add one.",
+      "",
+      "• Create a project in your only team: `npx convex project create my-app`",
+      "• Pick the team: `npx convex project create my-app --team my-team`",
+    ].join("\n"),
+  )
+  .allowExcessArguments(false)
+  .argument(
+    "[name]",
+    "The name of the new project. Prompted for when omitted in an " +
+      "interactive terminal; required otherwise.",
+  )
+  .addOption(
+    new Option(
+      "--team <team_slug>",
+      "The team to create the project in. Defaults to your only team, or " +
+        "prompts when you belong to several.",
+    ),
+  )
+  .action(runProjectCreate);

package/src/index.ts

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

package/src/react/ConvexAuthState.test.tsx

@@ -198,6 +198,7 @@ test("Tokens are used to schedule refetch", async () => {
 function mockServerConfirmsAuth(
   client: ConvexReactClient,
   oldIdentityVersion: number,
+  clientClockSkew?: number,
 ) {
   act(() => {
     const querySetVersion = client.sync["remoteQuerySet"]["version"];
@@ -212,6 +213,7 @@ function mockServerConfirmsAuth(
         identity: oldIdentityVersion + 1,
       },
       modifications: [],
+      ...(clientClockSkew !== undefined ? { clientClockSkew } : {}),
     });
   });
 }
@@ -539,3 +541,146 @@ test("stop() during reauth notifies isRefreshing false", async () => {
 
   expect(onRefreshChange).toHaveBeenCalledWith(false);
 });
+
+// --- initialAuthTokenReuse tests ---
+// When enabled, the cached token is reused after server confirmation
+// (no immediate fresh-token fetch), and the refetch is scheduled using
+// the server's clientClockSkew to estimate remaining lifetime.
+// The server computes clientClockSkew = clientTs - serverReceiveTs:
+// negative means client behind, positive means ahead. Connect latency
+// makes the skew more negative (conservative).
+
+test("initialAuthTokenReuse: sends only one Authenticate", async () => {
+  const client = new ConvexReactClient("https://127.0.0.1:3001", {
+    initialAuthTokenReuse: true,
+  });
+  const tokenLifetimeSeconds = 60;
+  let tokenId = 0;
+  const tokenFetcher = vi.fn(async () =>
+    jwtEncode(
+      { iat: 1234500, exp: 1234500 + tokenLifetimeSeconds },
+      "secret" + tokenId++,
+    ),
+  );
+
+  const sendMessageSpy = vi.spyOn(
+    client.sync["webSocketManager"],
+    "sendMessage",
+  );
+
+  const onAuthChange = vi.fn();
+  void client.setAuth(tokenFetcher, onAuthChange);
+
+  await flushPromises();
+  mockServerConfirmsAuth(client, 0);
+  await flushPromises();
+
+  expect(onAuthChange).toHaveBeenCalledWith(true);
+
+  const authenticateMessages = sendMessageSpy.mock.calls.filter(
+    ([msg]) => msg.type === "Authenticate",
+  );
+  expect(authenticateMessages).toHaveLength(1);
+
+  await client.close();
+});
+
+test("initialAuthTokenReuse: clock skew adjusts schedule for partially-expired token", async () => {
+  const client = new ConvexReactClient("https://127.0.0.1:3001", {
+    initialAuthTokenReuse: true,
+  });
+  const defaultLeewaySeconds = 10;
+  const tokenLifetimeSeconds = 60;
+  const tokenAgeOnServer = 30;
+  const clientClockSkewMs = 0;
+  const clientNow = Date.now() / 1000;
+  const serverNow = clientNow;
+  const tokenFetcher = vi.fn(async () =>
+    jwtEncode(
+      {
+        iat: serverNow - tokenAgeOnServer,
+        exp: serverNow - tokenAgeOnServer + tokenLifetimeSeconds,
+      },
+      "secret",
+    ),
+  );
+  void client.setAuth(tokenFetcher, () => {});
+
+  await flushPromises();
+  mockServerConfirmsAuth(client, 0, clientClockSkewMs);
+
+  expect(tokenFetcher).toHaveBeenCalledTimes(1);
+
+  const expectedDelay =
+    (tokenLifetimeSeconds - tokenAgeOnServer - defaultLeewaySeconds) * 1000;
+
+  vi.advanceTimersByTime(expectedDelay - 1);
+  expect(tokenFetcher).toHaveBeenCalledTimes(1);
+
+  vi.advanceTimersByTime(1);
+  expect(tokenFetcher).toHaveBeenCalledTimes(2);
+});
+
+test("initialAuthTokenReuse: clock skew triggers immediate refetch for nearly-expired token", async () => {
+  const client = new ConvexReactClient("https://127.0.0.1:3001", {
+    initialAuthTokenReuse: true,
+  });
+  const tokenLifetimeSeconds = 60;
+  const clientClockSkewMs = -50_000;
+  const clientNow = Date.now() / 1000;
+  const serverNow = clientNow - clientClockSkewMs / 1000;
+  const tokenFetcher = vi.fn(async () =>
+    jwtEncode(
+      {
+        iat: serverNow - 55,
+        exp: serverNow - 55 + tokenLifetimeSeconds,
+      },
+      "secret",
+    ),
+  );
+  void client.setAuth(tokenFetcher, () => {});
+
+  await flushPromises();
+  mockServerConfirmsAuth(client, 0, clientClockSkewMs);
+
+  expect(tokenFetcher).toHaveBeenCalledTimes(1);
+
+  vi.advanceTimersByTime(1);
+  expect(tokenFetcher).toHaveBeenCalledTimes(2);
+});
+
+test("initialAuthTokenReuse: clock skew corrects for client clock behind server", async () => {
+  const client = new ConvexReactClient("https://127.0.0.1:3001", {
+    initialAuthTokenReuse: true,
+  });
+  const defaultLeewaySeconds = 10;
+  const tokenLifetimeSeconds = 60;
+  const tokenAgeOnServer = 30;
+  const clientClockSkewMs = -20_000;
+  const clientNow = Date.now() / 1000;
+  const serverNow = clientNow - clientClockSkewMs / 1000;
+  const tokenFetcher = vi.fn(async () =>
+    jwtEncode(
+      {
+        iat: serverNow - tokenAgeOnServer,
+        exp: serverNow - tokenAgeOnServer + tokenLifetimeSeconds,
+      },
+      "secret",
+    ),
+  );
+  void client.setAuth(tokenFetcher, () => {});
+
+  await flushPromises();
+  mockServerConfirmsAuth(client, 0, clientClockSkewMs);
+
+  expect(tokenFetcher).toHaveBeenCalledTimes(1);
+
+  const expectedDelay =
+    (tokenLifetimeSeconds - tokenAgeOnServer - defaultLeewaySeconds) * 1000;
+
+  vi.advanceTimersByTime(expectedDelay - 1);
+  expect(tokenFetcher).toHaveBeenCalledTimes(1);
+
+  vi.advanceTimersByTime(1);
+  expect(tokenFetcher).toHaveBeenCalledTimes(2);
+});

package/src/server/database.ts

@@ -14,7 +14,13 @@ import {
 
 interface BaseDatabaseReader<DataModel extends GenericDataModel> {
   /**
-   * Fetch a single document from the database by its {@link values.GenericId}.
+   * Fetch a single document from the database by table name and
+   * {@link values.GenericId}.
+   *
+   * @example
+   * ```typescript
+   * const user = await ctx.db.get("users", userId);
+   * ```
    *
    * @param table - The name of the table to fetch the document from.
    * @param id - The {@link values.GenericId} of the document to fetch from the database.
@@ -28,6 +34,9 @@ interface BaseDatabaseReader<DataModel extends GenericDataModel> {
   /**
    * Fetch a single document from the database by its {@link values.GenericId}.
    *
+   * Supported for backwards compatibility. Prefer `db.get(tableName, id)` in
+   * new code, or `db.system.get(tableName, id)` for system tables.
+   *
    * @param id - The {@link values.GenericId} of the document to fetch from the database.
    * @returns - The {@link GenericDocument} of the document at the given {@link values.GenericId}, or `null` if it no longer exists.
    */
@@ -55,7 +64,7 @@ interface BaseDatabaseReader<DataModel extends GenericDataModel> {
    * This accepts the string ID format as well as the `.toString()` representation
    * of the legacy class-based ID format.
    *
-   * This does not guarantee that the ID exists (i.e. `db.get(id)` may return `null`).
+   * This does not guarantee that the ID exists (i.e. `db.get(tableName, id)` may return `null`).
    *
    * @param tableName - The name of the table.
    * @param id - The ID string.
@@ -109,7 +118,7 @@ export interface BaseTableReader<
  *
  * The two entry points are:
  *   - {@link GenericDatabaseReader.get}, which fetches a single document
- *     by its {@link values.GenericId}.
+ *     by table name and {@link values.GenericId}.
  *   - {@link GenericDatabaseReader.query}, which starts building a query.
  *
  * @example
@@ -272,6 +281,9 @@ export interface GenericDatabaseWriter<DataModel extends GenericDataModel>
    *
    * This method will throw if the document does not exist.
    *
+   * Supported for backwards compatibility. Prefer `db.patch(tableName, id, value)`
+   * in new code.
+   *
    * @param id - The {@link values.GenericId} of the document to patch.
    * @param value - The partial document to merge into the existing document.
    */
@@ -316,6 +328,9 @@ export interface GenericDatabaseWriter<DataModel extends GenericDataModel>
    * Unlike `patch`, which does a shallow merge, `replace` overwrites the
    * entire document.
    *
+   * Supported for backwards compatibility. Prefer `db.replace(tableName, id, value)`
+   * in new code.
+   *
    * @param id - The {@link values.GenericId} of the document to replace.
    * @param value - The new document. System fields can be omitted.
    */
@@ -343,6 +358,9 @@ export interface GenericDatabaseWriter<DataModel extends GenericDataModel>
   /**
    * Delete an existing document.
    *
+   * Supported for backwards compatibility. Prefer `db.delete(tableName, id)` in
+   * new code.
+   *
    * **Note:** Convex queries do not support `.delete()` directly on query
    * results. To delete multiple documents, `.collect()` them first, then
    * delete each one individually.

package/src/server/impl/meta_impl.ts

@@ -34,7 +34,10 @@ async function getFunctionMetadata(): Promise<{
     "1.0/getFunctionMetadata",
     {},
   );
-  return { name, componentPath };
+  return {
+    name,
+    componentPath,
+  };
 }
 
 async function getDeploymentMetadata(): Promise<DeploymentMetadata> {
@@ -51,11 +54,9 @@ async function getDeploymentMetadata(): Promise<DeploymentMetadata> {
 }
 
 async function getRequestMetadata(): Promise<RequestMetadata> {
-  const { ip, userAgent, requestId } = await performAsyncSyscall(
-    "1.0/getRequestMetadata",
-    {},
-  );
-  return { ip, userAgent, requestId };
+  const { ip, userAgent, requestId, scheduledFunctionId } =
+    await performAsyncSyscall("1.0/getRequestMetadata", {});
+  return { ip, userAgent, requestId, scheduledFunctionId };
 }
 
 export function setupQueryMeta(

package/src/server/impl/registration_impl.ts

@@ -61,7 +61,9 @@ async function invokeMutation<
     meta: setupMutationMeta(visibility),
 
     runQuery: (reference: any, args?: any, options?: any) =>
-      runUdf("query", reference, args, options?.transactionLimits),
+      options?.useStaleSnapshot
+        ? runUdf("snapshotQuery", reference, args, options?.transactionLimits)
+        : runUdf("query", reference, args, options?.transactionLimits),
     runMutation: (reference: any, args?: any, options?: any) =>
       runUdf("mutation", reference, args, options?.transactionLimits),
   };
@@ -336,8 +338,14 @@ async function invokeQuery<
     auth: setupAuth(requestId),
     storage: setupStorageReader(requestId),
     meta: setupQueryMeta(visibility),
-    runQuery: (reference: any, args?: any, options?: any) =>
-      runUdf("query", reference, args, options?.transactionLimits),
+    runQuery: (reference: any, args?: any, options?: any) => {
+      if (options?.useStaleSnapshot) {
+        throw new Error(
+          "`useStaleSnapshot` is only supported in mutations, not queries.",
+        );
+      }
+      return runUdf("query", reference, args, options?.transactionLimits);
+    },
   };
   const result = await invokeFunction(func, queryCtx, args as any);
   validateReturnValue(result);
@@ -492,7 +500,6 @@ export const internalQueryGeneric: QueryBuilder<any, "internal"> = ((
 async function invokeAction<
   F extends (ctx: GenericActionCtx<GenericDataModel>, ...args: any) => any,
 >(func: F, requestId: string, argsStr: string, visibility: FunctionVisibility) {
-  (globalThis as any).Convex?.setupPerformance?.();
   const args = jsonToConvex(JSON.parse(argsStr));
   const calls = setupActionCalls(requestId);
   const ctx = {
@@ -674,7 +681,6 @@ export const internalActionGeneric: ActionBuilder<any, "internal"> = ((
 async function invokeHttpAction<
   F extends (ctx: GenericActionCtx<GenericDataModel>, request: Request) => any,
 >(func: F, request: Request) {
-  (globalThis as any).Convex?.setupPerformance?.();
   // TODO(presley): Change the function signature and propagate the requestId from Rust.
   // Ok, to mock it out for now, since http endpoints are only running in V8.
   const requestId = "";

package/src/server/index.ts

@@ -118,6 +118,7 @@ export type { IndexRange, IndexRangeBuilder } from "./index_range_builder.js";
 export * from "./pagination.js";
 export type { OrderedQuery, Query, QueryInitializer } from "./query.js";
 export type {
+  AdvancedRunQueryOptions,
   ArgsArray,
   DefaultFunctionArgs,
   FunctionVisibility,

package/src/server/meta.ts

@@ -104,6 +104,16 @@ export type RequestMetadata = {
   ip: string | null;
   userAgent: string | null;
   requestId: string;
+  /**
+   * The ID of the scheduled function document (in `_scheduled_functions`) that
+   * this execution belongs to, or `null` otherwise.
+   *
+   * This is set for the scheduled function itself and for any functions it
+   * calls (e.g. a mutation invoked via `runMutation` by a scheduled action),
+   * propagating the top-level scheduled function's ID down the call tree. It is
+   * `null` when the function was not scheduled.
+   */
+  scheduledFunctionId: string | null;
 };
 
 /**

package/src/server/query.ts

@@ -106,7 +106,7 @@ export interface QueryInitializer<TableInfo extends GenericTableInfo>
 /**
  * The {@link Query} interface allows functions to read values out of the database.
  *
- * **If you only need to load an object by ID, use `db.get(id)` instead.**
+ * **If you only need to load an object by ID, use `db.get(tableName, id)` instead.**
  *
  * Executing a query consists of calling
  * 1. (Optional) {@link Query.order} to define the order

package/src/server/registration.test.ts

@@ -1,11 +1,14 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 import { test, describe, expect } from "vitest";
-import { assert, Equals } from "../test/type_testing.js";
+import { assert, assertFalse, Equals } from "../test/type_testing.js";
 import { v } from "../values/validator.js";
 import {
   ActionBuilder,
   ApiFromModules,
   DefaultFunctionArgs,
+  GenericDataModel,
+  GenericMutationCtx,
+  GenericQueryCtx,
   QueryBuilder,
   actionGeneric,
   mutationGeneric,
@@ -563,3 +566,24 @@ describe("argument and return value validators can be objects or validators", ()
     expect(JSON.parse(returnString)).toEqual(expectedReturnsExport);
   });
 });
+
+describe("useStaleSnapshot availability", () => {
+  type MutationRunQueryOptions = NonNullable<
+    Parameters<GenericMutationCtx<GenericDataModel>["runQuery"]>[2]
+  >;
+  type QueryRunQueryOptions = NonNullable<
+    Parameters<GenericQueryCtx<GenericDataModel>["runQuery"]>[2]
+  >;
+
+  test("available on mutation ctx runQuery options", () => {
+    assert<
+      "useStaleSnapshot" extends keyof MutationRunQueryOptions ? true : false
+    >();
+  });
+
+  test("not available on query ctx runQuery options", () => {
+    assertFalse<
+      "useStaleSnapshot" extends keyof QueryRunQueryOptions ? true : false
+    >();
+  });
+});

package/src/server/registration.ts

@@ -135,7 +135,7 @@ export interface GenericMutationCtx<DataModel extends GenericDataModel> {
    */
   runQuery: <Query extends FunctionReference<"query", "public" | "internal">>(
     query: Query,
-    ...args: ArgsAndOptions<Query, { transactionLimits?: TransactionLimits }>
+    ...args: ArgsAndOptions<Query, AdvancedRunQueryOptions>
   ) => Promise<FunctionReturnType<Query>>;
 
   /**
@@ -1211,3 +1211,18 @@ export type ActionBuilder<
 export type HttpActionBuilder = (
   func: (ctx: GenericActionCtx<any>, request: Request) => Promise<Response>,
 ) => PublicHttpAction;
+
+export interface AdvancedRunQueryOptions {
+  transactionLimits?: TransactionLimits;
+  /**
+   * Run a query on a recent snapshot of the database that is not guaranteed
+   * to be up-to-date when this transaction commits.
+   *
+   * This is an advanced feature which can introduce subtle race conditions,
+   * so its use is generally discouraged except for specific use-cases where
+   * database read conflicts are expected, e.g. reading from an append-only
+   * table with immutable records where the only read conflicts are from
+   * concurrent appends.
+   */
+  useStaleSnapshot?: boolean;
+}

package/src/server/storage.ts

@@ -1,16 +1,28 @@
 import { GenericId } from "../values/index.js";
 
 /**
- * A reference to a file in storage.
+ * @deprecated This ID format is no longer returned by stable file storage APIs. Use `Id<"_storage">` instead.
  *
- * This is used in the {@link StorageReader} and {@link StorageWriter} which are accessible in
- * Convex queries and mutations via {@link QueryCtx} and {@link MutationCtx} respectively.
+ * The old ID format used by Convex file storage.
+ *
+ * ⚠️ Security warning: Anyone that has knows to this ID can download the underlying file
+ * from `https://<deployment>.convex.cloud/api/storage/<storageId>`.
+ * (Note that it’s safe to share the new ID format, `Id<"_storage">`, to anyone).
  *
  * @public
  */
 export type StorageId = string;
+
+/**
+ * @deprecated This type is only necessary for backwards compatibility with Convex versions that
+ * pre-date `convex@1.6.0`. Use `Id<"_storage">` instead.
+ */
 export type FileStorageId = GenericId<"_storage"> | StorageId;
+
 /**
+ * @deprecated This type is only returned by {@link StorageReader.getUrl | storage.getUrl}.
+ *   To get the details of a document, use `ctx.db.system.get("_storage", storageId)` instead.
+ *
  * Metadata for a single file as returned by {@link StorageReader.getMetadata | storage.getMetadata}.
  *
  * @public
@@ -18,6 +30,13 @@ export type FileStorageId = GenericId<"_storage"> | StorageId;
 export type FileMetadata = {
   /**
    * ID for referencing the file (eg. via {@link StorageReader.getUrl | storage.getUrl})
+   *
+   * This is an older ID format that is no longer returned by stable file storage APIs.
+   * Consider using `Id<"_storage">` instead.
+   *
+   * ⚠️ Security warning: Anyone that has knows to this ID can download the underlying file
+   * from `https://<deployment>.convex.cloud/api/storage/<storageId>`.
+   * (Note that it’s safe to share the new ID format, `Id<"_storage">`, to anyone).
    */
   storageId: StorageId;
   /**

package/src/server/system_fields.ts

@@ -46,7 +46,7 @@ export type WithOptionalSystemFields<Document extends GenericDocument> = Expand<
  * @public
  */
 export type SystemIndexes = {
-  // Note `db.get(id)` is simpler and equivalent to a query on `by_id`.
+  // Note `db.get(tableName, id)` is simpler and equivalent to a query on `by_id`.
   // Unless the query is being built dynamically, or doing manual pagination.
   by_id: ["_id"];