convex 1.41.0 → 1.42.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "convex",
   "description": "Client for the Convex Cloud",
-  "version": "1.41.0",
+  "version": "1.42.0",
   "author": "Convex, Inc. <no-reply@convex.dev>",
   "homepage": "https://convex.dev",
   "repository": {
@@ -171,7 +171,7 @@
   "dependencies": {
     "esbuild": "0.27.0",
     "prettier": "^3.0.0",
-    "ws": "8.20.1"
+    "ws": "8.21.0"
   },
   "peerDependencies": {
     "@auth0/auth0-react": "^2.0.1",
@@ -266,13 +266,13 @@
     "serve-handler": "~6.1.6",
     "shx": "~0.4.0",
     "skott": "~0.35.4",
-    "tar": "^7.5.11",
+    "tar": "^7.5.16",
     "tsx": "^4.19.4",
     "typedoc": "^0.24.6",
     "typescript": "~5.0.3",
     "typescript-eslint": "~8.57.0",
     "vitest": "^4.1.0",
-    "undici": "7.24.0",
+    "undici": "7.28.0",
     "wait-for-expect": "~4.0.0",
     "zod": "^3.24.0",
     "zod-to-json-schema": "^3.24.0"

package/src/cli/env.ts

@@ -164,18 +164,25 @@ const envRemoveCmd = new Command("remove")
   });
 
 const envListCmd = new Command("list")
-  .summary("List all variables and their values")
+  .summary("List all environment variables and their values")
   .description(
     [
-      "• List all variables: `npx convex env list`",
+      "• List all variables and their values: `npx convex env list`",
+      "• List only variable names (no values): `npx convex env list --names-only`",
       "• Save all variables to a file: `npx convex env list > .env.convex`",
       "• Append to a file: `npx convex env list >> .env.convex`",
     ].join("\n"),
   )
+  .option(
+    "--names-only",
+    "List only the names of environment variables, without their values",
+  )
   .configureHelp({ showGlobalOptions: true })
   .allowExcessArguments(false)
-  .action(async (_options, cmd) => {
-    const options = cmd.optsWithGlobals();
+  .action(async (cmdOptions, cmd) => {
+    // Note: We use `as` here because optsWithGlobals() type inference doesn't
+    // include global options from the parent command (added via addDeploymentSelectionOptions)
+    const options = cmd.optsWithGlobals() as DeploymentSelectionOptions;
     const { ctx, deployment } = await selectEnvDeployment(options);
     await ensureHasConvexDependency(ctx, "env list");
     await withRunningBackend({
@@ -183,7 +190,9 @@ const envListCmd = new Command("list")
       deployment,
       action: async () => {
         const backend = deploymentEnvBackend(ctx, deployment);
-        await envList(ctx, backend);
+        await envList(ctx, backend, {
+          namesOnly: cmdOptions.namesOnly ?? false,
+        });
       },
     });
   });
@@ -198,7 +207,8 @@ export const env = new Command("env")
       "• Set interactively: `npx convex env set NAME`",
       "• Set multiple from file: `npx convex env set --from-file .env`",
       "• Unset a variable: `npx convex env remove NAME`",
-      "• List all variables: `npx convex env list`",
+      "• List all variables and their values: `npx convex env list`",
+      "• List only variable names (no values): `npx convex env list --names-only`",
       "• Print a variable's value: `npx convex env get NAME`",
       "",
       "By default, this sets and views variables on your dev deployment.",

package/src/cli/envDefault.ts

@@ -141,24 +141,29 @@ const envDefaultRemove = addEnvDefaultOptions(
 
 const envDefaultList = addEnvDefaultOptions(
   new Command("list")
-    .summary("List all default variables")
+    .summary("List all default environment variables and their values")
     .description(
       [
-        "List all default variables.",
-        "",
-        "• `npx convex env default list`",
+        "• List all default variables and their values: `npx convex env default list`",
+        "• List only default variable names (no values): `npx convex env default list --names-only`",
         "",
         "The deployment type is determined by the current deployment (local maps to dev), or by --type if provided.",
       ].join("\n"),
     )
+    .option(
+      "--names-only",
+      "List only the names of environment variables, without their values",
+    )
     .configureHelp({ showGlobalOptions: true })
     .allowExcessArguments(false),
-).action(async (_options, cmd) => {
+).action(async (cmdOptions, cmd) => {
   const options = cmd.optsWithGlobals() as DeploymentSelectionOptions &
     EnvDefaultExtraOptions;
   const { ctx, backend } = await resolveEnvDefaultBackend(options);
   await ensureHasConvexDependency(ctx, "env default list");
-  await envList(ctx, backend);
+  await envList(ctx, backend, {
+    namesOnly: cmdOptions.namesOnly ?? false,
+  });
 });
 
 export const envDefault = new Command("default")
@@ -171,7 +176,8 @@ export const envDefault = new Command("default")
       "",
       "• Set a default variable: `npx convex env default set NAME 'value'`",
       "• Unset a default variable: `npx convex env default remove NAME`",
-      "• List all default variables: `npx convex env default list`",
+      "• List all default variables and their values: `npx convex env default list`",
+      "• List only default variable names (no values): `npx convex env default list --names-only`",
       "• Print a default variable's value: `npx convex env default get NAME`",
     ].join("\n"),
   )

package/src/cli/insights.ts

@@ -101,6 +101,7 @@ export const insights = new Command("insights")
   )
   .allowExcessArguments(false)
   .option("--details", "Show recent events for each insight", false)
+  .option("--json", "Output insights as JSON", false)
   .addDeploymentSelectionOptions(actionDescription("Show insights for"))
   .showHelpAfterError()
   .action(async (cmdOptions) => {
@@ -145,6 +146,17 @@ export const insights = new Command("insights")
       "?view=insights",
     );
 
+    if (cmdOptions.json) {
+      logOutput(
+        JSON.stringify(
+          { deploymentName, dashboardUrl, insights: insightsList },
+          null,
+          2,
+        ),
+      );
+      return;
+    }
+
     if (insightsList.length === 0) {
       logOutput(
         chalk.green(

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

@@ -0,0 +1,60 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import type { Context } from "../../bundler/context.js";
+import { envList, type EnvVar, type EnvVarBackend } from "./env.js";
+
+const logMocks = vi.hoisted(() => ({
+  logFailure: vi.fn(),
+  logFinishedStep: vi.fn(),
+  logMessage: vi.fn(),
+  logOutput: vi.fn(),
+}));
+
+vi.mock("../../bundler/log.js", () => ({
+  logFailure: logMocks.logFailure,
+  logFinishedStep: logMocks.logFinishedStep,
+  logMessage: logMocks.logMessage,
+  logOutput: logMocks.logOutput,
+}));
+
+function fakeBackend(envs: EnvVar[]): EnvVarBackend {
+  return {
+    get() {
+      return Promise.resolve(null);
+    },
+    list() {
+      return Promise.resolve(envs);
+    },
+    update() {
+      return Promise.reject(new Error("Unexpected update"));
+    },
+    notice: "",
+  };
+}
+
+describe("envList", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  test("prints only names without values or warnings when namesOnly is true", async () => {
+    await envList(
+      {} as Context,
+      fakeBackend([
+        { name: "PLAIN", value: "plain-value" },
+        { name: "DANGEROUS", value: "secret'value#fragment" },
+      ]),
+      { namesOnly: true },
+    );
+
+    expect(logMocks.logOutput.mock.calls).toEqual([["PLAIN"], ["DANGEROUS"]]);
+    expect(logMocks.logMessage).not.toHaveBeenCalled();
+
+    const emitted = [
+      ...logMocks.logOutput.mock.calls.flat(),
+      ...logMocks.logMessage.mock.calls.flat(),
+    ].join("\n");
+    expect(emitted).not.toContain("plain-value");
+    expect(emitted).not.toContain("secret'value#fragment");
+    expect(emitted).not.toContain("Warning (");
+  });
+});

package/src/cli/lib/env.ts

@@ -171,13 +171,21 @@ export async function envRemove(
   );
 }
 
-export async function envList(ctx: Context, backend: EnvVarBackend) {
+export async function envList(
+  ctx: Context,
+  backend: EnvVarBackend,
+  options?: { namesOnly?: boolean },
+) {
   const envs = await backend.list();
   if (envs.length === 0) {
     logMessage(`No environment variables set${backend.notice}`);
     return;
   }
   for (const { name, value } of envs) {
+    if (options?.namesOnly) {
+      logOutput(name);
+      continue;
+    }
     const { formatted, warning } = formatEnvValueForDotfile(value);
     if (warning) {
       logMessage(`Warning (${name}): ${warning}`);

package/src/cli/lib/login.ts

@@ -5,6 +5,7 @@ import {
   logAndHandleFetchError,
   throwingFetch,
   isWebContainer,
+  typedPlatformClient,
 } from "./utils/utils.js";
 import open from "open";
 import { chalkStderr } from "chalk";
@@ -37,12 +38,6 @@ custom.setHttpOptionsDefaults({
   timeout: parseInt(process.env.OPENID_CLIENT_TIMEOUT || "10000"),
 });
 
-interface AuthorizeArgs {
-  authnToken: string;
-  deviceName: string;
-  anonymousId?: string | undefined;
-}
-
 export async function checkAuthorization(
   ctx: Context,
   acceptOptIns: boolean,
@@ -390,18 +385,23 @@ export async function performLogin(
     });
   }
 
-  const authorizeArgs: AuthorizeArgs = {
-    authnToken: accessToken!,
-    deviceName: deviceName,
-    anonymousId: anonymousId,
-  };
-  const data = await bigBrainAPI({
-    ctx,
-    method: "POST",
-    path: "authorize",
-    data: authorizeArgs,
+  // Exchange the WorkOS access token for a Convex personal access token.
+  ctx._updateBigBrainAuth({
+    accessToken: accessToken!,
+    kind: "accessToken",
+    header: `Bearer ${accessToken!}`,
   });
-  const globalConfig = { accessToken: data.accessToken };
+  const response = await typedPlatformClient(ctx).POST(
+    "/create_personal_access_token",
+    {
+      // `anonymousId` links a prior anonymous session to this account. It's
+      // intentionally absent from the generated platform API types,
+      // so cast to pass it through.
+      body: { name: deviceName, anonymousId } as { name: string },
+    },
+  );
+  const newAccessToken = response.data!.accessToken;
+  const globalConfig = { accessToken: newAccessToken };
   try {
     await modifyGlobalConfig(ctx, globalConfig);
     const path = globalConfigPath();
@@ -416,7 +416,7 @@ export async function performLogin(
   }
 
   logVerbose(`performLogin: updating big brain auth after login`);
-  await updateBigBrainAuthAfterLogin(ctx, data.accessToken);
+  await updateBigBrainAuthAfterLogin(ctx, newAccessToken);
 
   logVerbose(`performLogin: checking opt ins, acceptOptIns: ${acceptOptIns}`);
   // Do opt in to TOS and Privacy Policy stuff

package/src/cli/lib/logs.ts

@@ -5,7 +5,7 @@ import { nextBackoff } from "./dev.js";
 import chalk, { chalkStderr } from "chalk";
 import { stripVTControlCharacters } from "node:util";
 import { format } from "node:util";
-import { deploymentFetch } from "./utils/utils.js";
+import { deploymentFetch, ThrowingFetchError } from "./utils/utils.js";
 import { FunctionExecution } from "./apiTypes.js";
 
 export type LogMode = "always" | "pause-on-deploy" | "disable";
@@ -122,7 +122,12 @@ export async function watchLogs(
           options?.jsonl,
         );
       }
-    } catch {
+    } catch (e) {
+      // A 403 means the admin key isn't authorized for this deployment.
+      // Retrying won't help, so surface the error and fail immediately.
+      if (e instanceof ThrowingFetchError && e.response.status === 403) {
+        return await e.handle(ctx);
+      }
       numFailures += 1;
     }
     // Handle backoff

package/src/cli/lib/run.ts

@@ -11,7 +11,11 @@ import {
 import { Value, convexToJson, jsonToConvex } from "../../values/value.js";
 import { Context, OneoffCtx } from "../../bundler/context.js";
 import { logFinishedStep, logMessage, logOutput } from "../../bundler/log.js";
-import { waitForever, waitUntilCalled } from "./utils/utils.js";
+import {
+  permissionDeniedErrorMessage,
+  waitForever,
+  waitUntilCalled,
+} from "./utils/utils.js";
 import JSON5 from "json5";
 import path from "path";
 import { readProjectConfig } from "./config.js";
@@ -59,6 +63,15 @@ export async function runFunctionAndLog(
   } catch (err) {
     const errorMessage = (err as Error).toString().trim();
 
+    const permissionError = permissionDeniedErrorMessage(errorMessage);
+    if (permissionError !== null) {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage: chalkStderr.red(permissionError),
+      });
+    }
+
     if (errorMessage.includes("Could not find function")) {
       const functions = (await runSystemQuery(ctx, {
         deploymentUrl: args.deploymentUrl,
@@ -377,7 +390,7 @@ export async function subscribeAndLog(
 }
 
 export async function subscribe(
-  _ctx: Context,
+  ctx: Context,
   args: {
     deploymentUrl: string;
     adminKey: string;
@@ -399,7 +412,28 @@ export async function subscribe(
     args.deploymentUrl,
     (updatedQueries) => {
       for (const queryToken of updatedQueries) {
-        args.callbacks?.onChange?.(client.localQueryResultByToken(queryToken)!);
+        let result: Value;
+        try {
+          result = client.localQueryResultByToken(queryToken)!;
+        } catch (err) {
+          // A failed query (e.g. a permission error) throws here. Surface
+          // permission errors cleanly instead of an uncaught stack trace, and
+          // let any other error propagate as before.
+          const permissionError = permissionDeniedErrorMessage(
+            (err as Error).toString(),
+          );
+          if (permissionError !== null) {
+            void ctx.crash({
+              exitCode: 1,
+              errorType: "fatal",
+              printedMessage: chalkStderr.red(permissionError),
+            });
+            return;
+          }
+          // eslint-disable-next-line no-restricted-syntax
+          throw err;
+        }
+        args.callbacks?.onChange?.(result);
       }
     },
     {

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

@@ -101,6 +101,52 @@ export function readDeployKeyFromEnv(
   return fromDeployKey || fromToken || undefined;
 }
 
+// The prefix the backend's `require_operation` checks use when an identity
+// lacks a permission. The full message names the missing permission, e.g.
+// `You do not have permission to perform this operation (deployment:data:view).`
+const PERMISSION_DENIED_MESSAGE_PREFIX =
+  "You do not have permission to perform this operation";
+
+function deployKeyPermissionAdvice(): string | null {
+  // Name whichever env var is actually set. `CONVEX_DEPLOY_KEY` takes
+  // precedence over `CONVEX_DEPLOYMENT_TOKEN` when both are present.
+  const envVarName = process.env[CONVEX_DEPLOY_KEY_ENV_VAR_NAME]
+    ? CONVEX_DEPLOY_KEY_ENV_VAR_NAME
+    : process.env[CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME]
+      ? CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME
+      : null;
+  if (envVarName === null) {
+    return null;
+  }
+  return `This is determined by the permissions granted to ${envVarName}.`;
+}
+
+/**
+ * Detects a server-side authorization failure (a `require_operation` error,
+ * surfaced both as an HTTP 403 and as an error from a system UDF query) and
+ * produces a clean, single-line message naming the missing permission. When a
+ * deploy key is in use, appends advice for configuring its permissions.
+ *
+ * Returns `null` if `errorMessage` is not a permission error, so callers can
+ * fall back to their normal error handling.
+ */
+export function permissionDeniedErrorMessage(
+  errorMessage: string,
+): string | null {
+  const index = errorMessage.indexOf(PERMISSION_DENIED_MESSAGE_PREFIX);
+  if (index === -1) {
+    return null;
+  }
+  // Drop any wrapping context (e.g. the `[CONVEX Q(...)]` prefix) and stack
+  // trace, keeping just the permission sentence.
+  let msg = errorMessage.slice(index).split("\n")[0].trim();
+  const advice = deployKeyPermissionAdvice();
+  if (advice) {
+    msg = `${msg}\n${advice}`;
+  }
+  return msg;
+}
+
 export function parsePositiveInteger(value: string) {
   const parsedValue = parseInteger(value);
   if (parsedValue <= 0) {
@@ -177,6 +223,16 @@ export class ThrowingFetchError extends Error {
     } else if (this.response.status === 401) {
       error_type = "fatal";
       msg = `${msg}\nAuthenticate with \`npx convex dev\``;
+    } else if (this.response.status === 403) {
+      error_type = "fatal";
+      // Surface the missing permission cleanly (e.g. the server includes the
+      // required action like `deployment:data:view`) instead of the noisy
+      // "Error fetching ..." wrapper.
+      msg = this.serverErrorData?.message ?? msg;
+      const advice = deployKeyPermissionAdvice();
+      if (advice) {
+        msg = `${msg}\n${advice}`;
+      }
     } else if (this.response.status === 404) {
       error_type = "fatal";
       msg = `${msg}: ${this.response.url}`;

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.0";

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.