convex 1.46.0 → 1.47.0

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

@@ -517,6 +517,23 @@ export async function selectRegionOrUseDefault(
   return selectedRegionName;
 }
 
+// Mirrors the order of `REGION_PRESENTATION` in
+// `npm-packages/dashboard/src/lib/regions.ts`, so both region pickers list
+// regions in the same order.
+const REGION_ORDER: string[] = [
+  "aws-us-east-1",
+  "aws-eu-west-1",
+  "aws-ca-central-1",
+  "aws-ap-southeast-2",
+];
+
+// Regions missing from `REGION_ORDER` (e.g. newly launched ones) go last, in
+// server order, since `Array.prototype.sort` is stable.
+function regionSortIndex(regionName: string): number {
+  const index = REGION_ORDER.indexOf(regionName);
+  return index === -1 ? REGION_ORDER.length : index;
+}
+
 export async function selectRegion(
   ctx: Context,
   teamId: number,
@@ -538,12 +555,7 @@ export async function selectRegion(
       name: item.displayName,
       value: item.name,
     }))
-    .sort((a, b) => {
-      // Show US region first if it exists
-      if (a.value === "aws-us-east-1") return -1;
-      if (b.value === "aws-us-east-1") return 1;
-      return 0;
-    });
+    .sort((a, b) => regionSortIndex(a.value) - regionSortIndex(b.value));
   return await promptOptions(ctx, {
     message: `Where should this ${deploymentType} deployment run?`,
     suffix: `\n${chalkStderr.gray(
@@ -559,16 +571,18 @@ export async function hasProject(
   projectSlug: string,
 ) {
   try {
-    const projects: Project[] = (
-      await typedBigBrainClient(ctx).GET("/teams/{team_slug}/projects", {
+    await typedPlatformClient(ctx, { throw: true }).GET(
+      "/teams/{team_id_or_slug}/projects/{project_slug}",
+      {
         params: {
           path: {
-            team_slug: teamSlug,
+            team_id_or_slug: teamSlug,
+            project_slug: projectSlug,
           },
         },
-      })
-    ).data!;
-    return !!projects.find((project) => project.slug === projectSlug);
+      },
+    );
+    return true;
   } catch {
     return false;
   }
@@ -581,19 +595,27 @@ export async function hasProjects(ctx: Context) {
 export async function validateOrSelectProject(
   ctx: Context,
   projectSlug: string | undefined,
-  teamSlug: string,
+  teamId: number,
   singleProjectPrompt: string,
   multiProjectPrompt: string,
 ): Promise<string | null> {
-  const projects: Project[] = (
-    await typedBigBrainClient(ctx).GET("/teams/{team_slug}/projects", {
-      params: {
-        path: {
-          team_slug: teamSlug,
+  const projects: Project[] = [];
+  const client = typedPlatformClient(ctx);
+  let cursor: string | undefined;
+  do {
+    const { items, pagination } = (
+      await client.GET("/teams/{team_id}/projects", {
+        params: {
+          path: { team_id: teamId },
+          query: cursor === undefined ? {} : { cursor },
         },
-      },
-    })
-  ).data!;
+      })
+    ).data!;
+    projects.push(...items);
+    cursor = pagination.hasMore
+      ? (pagination.nextCursor ?? undefined)
+      : undefined;
+  } while (cursor !== undefined);
   if (projects.length === 0) {
     return await ctx.crash({
       exitCode: 1,
@@ -996,6 +1018,27 @@ export function formatSize(n: number): string {
   return `${formatted} ${BYTE_UNITS[unitIndex]}`;
 }
 
+/**
+ * Read an integer override from the environment, falling back to
+ * `defaultValue` when the variable is unset. The whole value must be a
+ * base-10 integer: `parseInt` would read a typo like `100_000` or `100k` as
+ * 100 and silently move the threshold, so anything else is rejected with a
+ * warning instead.
+ */
+export function integerFromEnv(envVar: string, defaultValue: number): number {
+  const envValue = process.env[envVar];
+  if (envValue === undefined) {
+    return defaultValue;
+  }
+  if (!/^[+-]?\d+$/.test(envValue.trim())) {
+    logWarning(
+      `Ignoring ${envVar}=${JSON.stringify(envValue)}: expected an integer, using ${defaultValue}`,
+    );
+    return defaultValue;
+  }
+  return Number(envValue);
+}
+
 export function formatDuration(ms: number): string {
   const twoDigits = (n: number, unit: string) =>
     `${n.toLocaleString("en-US", { maximumFractionDigits: 2 })}${unit}`;

package/src/cli/projectCreate.ts

@@ -64,7 +64,7 @@ async function runProjectCreate(
   logMessage(
     chalkStderr.gray(
       `Next, add a deployment with ` +
-        `\`npx convex deployment create ${team.slug}:${projectSlug}:dev --type dev\` ` +
+        `\`npx convex deployment create ${team.slug}:${projectSlug}:dev/my-feature --type dev --select\` ` +
         `(pass \`--region us\` to choose a region).`,
     ),
   );

package/src/index.ts

@@ -1 +1 @@
-export const version = "1.46.0";
+export const version = "1.47.0";

package/src/server/impl/actions_impl.ts

@@ -64,26 +64,46 @@ export function setupActionCalls(requestId: string) {
   };
 }
 
+/**
+ * A Convex-managed service. The backend decides which names it accepts; this
+ * type lists the ones the current release knows about.
+ */
+export type ServiceName = "ai-gateway";
+
 /**
  * Get a short-lived credential for calling a Convex-managed service.
  *
  * This function can only be called while an action is running. The credential
  * is scoped to the current deployment and should be sent as a bearer token.
- * Repeated calls in the same action reuse one token; a failed mint is not
- * cached, so a later call retries.
+ * The action runtime caches and refreshes credentials as needed, so call
+ * this function whenever making a service request.
  *
  * @param service - The service the credential may access.
  * @returns A JWT to send as `Authorization: Bearer <token>`. Keep it inside
  * the action: don't return it to clients or store it in environment
  * variables.
  */
-export async function getServiceToken(service: "ai-gateway"): Promise<string> {
+export async function getServiceToken(service: ServiceName): Promise<string> {
   validateArg(service, 1, "getServiceToken", "service");
-  if (service !== "ai-gateway") {
-    throw new Error(`Unsupported service "${String(service)}"`);
-  }
   return await performAsyncSyscall("1.0/createServiceToken", {
     service,
     version,
   });
 }
+
+/**
+ * Get the base URL of a Convex-managed service.
+ *
+ * This function can only be called while an action is running. Pair it with
+ * {@link getServiceToken} to reach the service.
+ *
+ * @param service - The service to address.
+ * @returns The service's origin, without a trailing slash.
+ */
+export async function getServiceUrl(service: ServiceName): Promise<string> {
+  validateArg(service, 1, "getServiceUrl", "service");
+  return await performAsyncSyscall("1.0/getServiceUrl", {
+    service,
+    version,
+  });
+}

package/src/server/impl/storage_impl.ts

@@ -6,6 +6,7 @@ import {
   StorageWriter,
 } from "../storage.js";
 import { version } from "../../index.js";
+import { fromByteArray, toByteArray } from "../../values/base64.js";
 import { performAsyncSyscall, performJsSyscall } from "./syscall.js";
 import { validateArg } from "./validate.js";
 
@@ -45,6 +46,35 @@ export function setupStorageWriter(requestId: string): StorageWriter {
         storageId,
       });
     },
+    store: async (blob: Blob, options?: { sha256?: string }) => {
+      if (!(blob instanceof Blob)) {
+        throw new Error(
+          "store() expects a Blob. If you are trying to store a Request, `await request.blob()` will give you the correct input.",
+        );
+      }
+      const bytes = new Uint8Array(await blob.arrayBuffer());
+      return await performAsyncSyscall("1.0/storageStore", {
+        requestId,
+        version,
+        blob: fromByteArray(bytes),
+        contentType: blob.type,
+        sha256: options?.sha256,
+      });
+    },
+    get: async (storageId: FileStorageId) => {
+      const result: { blob: string; contentType: string | null } | null =
+        await performAsyncSyscall("1.0/storageGet", {
+          requestId,
+          version,
+          storageId,
+        });
+      if (result === null) {
+        return null;
+      }
+      return new Blob([toByteArray(result.blob)], {
+        type: result.contentType ?? "",
+      });
+    },
     getUrl: reader.getUrl,
     getMetadata: reader.getMetadata,
   };

package/src/server/index.ts

@@ -103,7 +103,11 @@ export {
   internalMutationGeneric,
   internalQueryGeneric,
 } from "./impl/registration_impl.js";
-export { getServiceToken } from "./impl/actions_impl.js";
+export {
+  getServiceToken,
+  getServiceUrl,
+  type ServiceName,
+} from "./impl/actions_impl.js";
 export type {
   TransactionMetric,
   TransactionMetrics,

package/src/server/meta.ts

@@ -26,6 +26,14 @@ export type TransactionMetrics = {
   documentsWritten: TransactionMetric;
   functionsScheduled: TransactionMetric;
   scheduledFunctionArgsBytes: TransactionMetric;
+  /** @internal */
+  filesWritten: TransactionMetric;
+  /** @internal */
+  fileWriteBytes: TransactionMetric;
+  /** @internal */
+  filesRead: TransactionMetric;
+  /** @internal */
+  fileReadBytes: TransactionMetric;
 };
 
 /**
@@ -43,6 +51,14 @@ export interface TransactionLimits {
   documentsWritten?: number;
   functionsScheduled?: number;
   scheduledFunctionArgsBytes?: number;
+  /** @internal */
+  filesWritten?: number;
+  /** @internal */
+  fileWriteBytes?: number;
+  /** @internal */
+  filesRead?: number;
+  /** @internal */
+  fileReadBytes?: number;
 }
 
 /**
@@ -130,18 +146,30 @@ export type RequestMetadata = {
  * @public
  */
 export interface QueryMeta {
+  /**
+   * Metadata about the currently executing Convex function.
+   */
   getFunctionMetadata(): Promise<FunctionMetadata>;
+  /**
+   * The remaining headroom for a transaction before hitting limits.
+   *
+   * See https://docs.convex.dev/production/state/limits
+   */
   getTransactionMetrics(): Promise<TransactionMetrics>;
+  /**
+   * Metadata about the deployment this function is running on.
+   */
   getDeploymentMetadata(): Promise<DeploymentMetadata>;
   /**
-   * @internal
    * Returns the timestamp of the database snapshot this transaction reads
    * from, in nanoseconds.
    *
    * All commits at or before this timestamp are observable within the
    * transaction, and no later commits are. The value is fixed for the
    * lifetime of the transaction and shared with all nested `runMutation` and
-   * `runQuery` calls.
+   * non-stale `runQuery` calls. If a nested query is called with
+   * `useStaleSnapshot: true`, then the nested query may in a future backend
+   * version choose an older snapshotTs.
    *
    * It is on the same clock as `db.vars.commitTs`: documents observable in
    * this transaction have `commitTs` values at or before this timestamp, and
@@ -156,6 +184,8 @@ export interface QueryMeta {
    * Note: this should not be compared to `_creationTime` or `Date.now()`, as
    * those are based on wall-clock time rather than the database clock, and
    * aren't guaranteed to follow commit order.
+   *
+   * Docs: https://docs.convex.dev/database/advanced/commit-timestamp
    */
   getSnapshotTs(): bigint;
 }
@@ -166,6 +196,15 @@ export interface QueryMeta {
  * @public
  */
 export interface MutationMeta extends QueryMeta {
+  /**
+   * Metadata about the HTTP request that triggered the current function execution.
+   *
+   * `ip` and `userAgent` are `null` when the function was not triggered by an
+   * HTTP request (e.g. scheduled jobs or cron jobs).
+   *
+   * Functions called from within a function (i.e. using `runMutation`) will have
+   * the same request metadata as the parent function.
+   */
   getRequestMetadata(): Promise<RequestMetadata>;
 }
 
@@ -175,7 +214,22 @@ export interface MutationMeta extends QueryMeta {
  * @public
  */
 export interface ActionMeta {
+  /**
+   * Metadata about the currently executing Convex function.
+   */
   getFunctionMetadata(): Promise<FunctionMetadata>;
+  /**
+   * Metadata about the deployment this function is running on.
+   */
   getDeploymentMetadata(): Promise<DeploymentMetadata>;
+  /**
+   * Metadata about the HTTP request that triggered the current function execution.
+   *
+   * `ip` and `userAgent` are `null` when the function was not triggered by an
+   * HTTP request (e.g. scheduled jobs or cron jobs).
+   *
+   * Functions called from within a function (i.e. using `runMutation` or
+   * `runAction`) will have the same request metadata as the parent function.
+   */
   getRequestMetadata(): Promise<RequestMetadata>;
 }

package/src/server/registration.ts

@@ -1234,6 +1234,11 @@ export type HttpActionBuilder = (
 ) => PublicHttpAction;
 
 export interface AdvancedRunQueryOptions {
+  /**
+   * Custom limits for a nested transaction. Each field specifies the absolute
+   * maximum allowed for the nested function call. Values are capped at the
+   * global transaction limits, so they can only lower limits, never raise them.
+   */
   transactionLimits?: TransactionLimits;
   /**
    * Run a query on a recent snapshot of the database that is not guaranteed
@@ -1244,6 +1249,11 @@ export interface AdvancedRunQueryOptions {
    * 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.
+   *
+   * To determine the snapshot of the nested query, you can call
+   * `ctx.meta.getSnapshotTs()` from within the stale snapshot query. To
+   * compare to the parent mutation's snapshot timestamp, you can return that
+   * value from the query and call `ctx.meta.getSnapshotTs()` from the parent.
    */
   useStaleSnapshot?: boolean;
 }

package/src/server/schema.ts

@@ -561,41 +561,63 @@ export class TableDefinition<
   }
 
   /**
-   * Stage a new document validator for this table.
+   * Stage changes to this table's document validator.
    *
    * Convex validates the staged validator against the table's existing
    * documents in the background, while the validator passed to
-   * {@link defineTable} remains the one enforced on reads and writes. Once
-   * the background validation succeeds, make the staged validator the
-   * table's validator and remove `.staged()`.
+   * {@link defineTable} remains the one enforced on writes. Once
+   * the background validation succeeds, apply the staged changes
+   * and remove `.staged()`.
+   *
+   * For an object validator, pass only the fields to add or replace. Fields
+   * omitted from the changes keep their enforced validators.
+   * Set a field to `undefined` to remove it from the staged validator.
+   * For nested objects, you must specify the full object validator.
    *
    * ```ts
    * defineTable({
-   *   author: v.string(),
+   *   apple: v.string(),
+   *   banana: v.number(),
+   *   legacy: v.optional(v.string()),
    * }).staged({
-   *   author: v.array(v.string()),
+   *   banana: v.union(v.string(), v.number()),
+   *   legacy: undefined,
    * })
    * ```
    *
-   * TODO: link a worked staged-schema example from the docs once one exists.
+   * See [Staged validators](https://docs.convex.dev/database/schemas#staged-validators).
    *
-   * @param documentSchema - The proposed next type of documents stored in
-   * this table, as an object of field validators or a schema validator.
+   * @param documentSchema - Field changes for a table defined as an object or
+   * `v.any()`, or a full schema validator specifying the proposed next document
+   * type. Use a full schema validator for a table defined as a union.
    * @returns A {@link TableDefinition} with the staged validator attached.
-   *
-   * @internal
    */
   staged(
     documentSchema:
       | Validator<Record<string, any>, "required", any>
-      | Record<string, GenericValidator>,
+      | Record<string, GenericValidator | undefined>,
   ): TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes> {
     if (this.stagedValidator !== undefined) {
       throw new Error("Table cannot have more than one staged validator.");
     }
-    this.stagedValidator = isValidator(documentSchema)
-      ? documentSchema
-      : v.object(documentSchema);
+    if (isValidator(documentSchema)) {
+      this.stagedValidator = documentSchema;
+    } else {
+      if (this.validator.kind !== "object" && this.validator.kind !== "any") {
+        throw new Error(
+          "Specifying top-level field changes is only supported for simple table definitions. For a table defined with a union or record validator, you must stage a fully defined object or union validator.",
+        );
+      }
+      const enforcedFields =
+        this.validator.kind === "object" ? this.validator.fields : {};
+      const fields: Record<string, GenericValidator> = Object.fromEntries(
+        Object.entries({ ...enforcedFields, ...documentSchema }).filter(
+          (entry): entry is [string, GenericValidator] =>
+            entry[1] !== undefined,
+        ),
+      );
+      this.stagedValidator = v.object(fields);
+    }
     return this.self();
   }
 

package/src/server/storage.ts

@@ -194,6 +194,23 @@ export interface StorageWriter extends StorageReader {
   delete<T extends StorageId>(
     storageId: T extends { __tableName: any } ? never : T,
   ): Promise<void>;
+
+  /**
+   * @internal
+   */
+  // TODO: move `store` from StorageActionWriter to StorageWriter when mutation
+  // file storage access is ready for release
+  store(
+    blob: Blob,
+    options?: { sha256?: string },
+  ): Promise<GenericId<"_storage">>;
+
+  /**
+   * @internal
+   */
+  // TODO: move `get` from StorageActionWriter to StorageWriter when mutation
+  // file storage access is ready for release
+  get(storageId: GenericId<"_storage">): Promise<Blob | null>;
 }
 
 /**

package/src/values/validators.ts

@@ -641,7 +641,7 @@ export class VRecord<
       throw new Error("Record validator cannot have optional values");
     }
     if (!key.isConvexValidator || !value.isConvexValidator) {
-      throw new Error("Key and value of v.record() but be validators");
+      throw new Error("Key and value of v.record() must be validators");
     }
     this.key = key;
     this.value = value;

package/src/values/value.ts

@@ -311,13 +311,17 @@ const MAX_VALUE_FOR_ERROR_LEN = 16384;
 export function stringifyValueForError(value: any) {
   const str = JSON.stringify(value, (_key, value) => {
     if (value === undefined) {
-      // By default `JSON.stringify` converts undefined, functions, symbols,
-      // Infinity, and NaN to null which produces a confusing error message.
-      // We deal with `undefined` specifically because it's the most common.
-      // Ideally we'd use a pretty-printing library that prints `undefined`
-      // (no quotes), but it might not be worth the bundle size cost.
+      // JSON.stringify omits undefined object properties and converts undefined
+      // array elements to null. Preserve them in error messages.
       return "undefined";
     }
+    if (typeof value === "function") {
+      // A fixed placeholder also works for functions with custom string coercion.
+      return "[Function]";
+    }
+    if (typeof value === "symbol") {
+      return String(value);
+    }
     if (typeof value === "bigint") {
       // `JSON.stringify` throws on bigints by default.
       return `${value.toString()}n`;