convex 1.45.0 → 1.47.0

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,
@@ -174,6 +178,7 @@ export {
 export type {
   ApiFromModules,
   AnyApi,
+  FunctionReference_future,
   FilterApi,
   FunctionType,
   FunctionReference,

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,9 +146,48 @@ 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>;
+  /**
+   * 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
+   * 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
+   * no new documents will be written with a `commitTs` at or below this,
+   * including from the current transaction. When reading documents with an
+   * index in commitTs order, you can use this as an upper bound to prevent
+   * conflicting with racing inserts.
+   *
+   * Since the timestamp differs on every execution, calling this in a query
+   * limits caching of the query's result the same way `Date.now()` does.
+   *
+   * 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;
 }
 
 /**
@@ -141,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>;
 }
 
@@ -150,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

@@ -16,10 +16,11 @@ import {
 } from "./meta.js";
 import {
   ArgsAndOptions,
-  FunctionReference,
   FunctionReturnType,
   OptionalRestArgs,
   ValidatorTypeToReturnType,
+  FunctionReference,
+  FunctionReference_future,
 } from "../server/api.js";
 import {
   GenericValidator,
@@ -133,7 +134,11 @@ export interface GenericMutationCtx<DataModel extends GenericDataModel> {
    * const user = await ctx.runQuery(internal.users.getUser, { userId });
    * ```
    */
-  runQuery: <Query extends FunctionReference<"query", "public" | "internal">>(
+  runQuery: <
+    Query extends
+      | FunctionReference<"query", "public" | "internal">
+      | FunctionReference_future<"query", "public" | "internal">,
+  >(
     query: Query,
     ...args: ArgsAndOptions<Query, AdvancedRunQueryOptions>
   ) => Promise<FunctionReturnType<Query>>;
@@ -149,7 +154,9 @@ export interface GenericMutationCtx<DataModel extends GenericDataModel> {
    * validation, and creating a new isolated JS context.
    */
   runMutation: <
-    Mutation extends FunctionReference<"mutation", "public" | "internal">,
+    Mutation extends
+      | FunctionReference<"mutation", "public" | "internal">
+      | FunctionReference_future<"mutation", "public" | "internal">,
   >(
     mutation: Mutation,
     ...args: ArgsAndOptions<Mutation, { transactionLimits?: TransactionLimits }>
@@ -243,7 +250,11 @@ export interface GenericQueryCtx<DataModel extends GenericDataModel> {
    * `runQuery` incurs overhead of running argument and return value validation,
    * and creating a new isolated JS context.
    */
-  runQuery: <Query extends FunctionReference<"query", "public" | "internal">>(
+  runQuery: <
+    Query extends
+      | FunctionReference<"query", "public" | "internal">
+      | FunctionReference_future<"query", "public" | "internal">,
+  >(
     query: Query,
     ...args: ArgsAndOptions<Query, { transactionLimits?: TransactionLimits }>
   ) => Promise<FunctionReturnType<Query>>;
@@ -326,7 +337,11 @@ export interface GenericActionCtx<DataModel extends GenericDataModel> {
    * @param args - The arguments to the query function.
    * @returns A promise of the query's result.
    */
-  runQuery<Query extends FunctionReference<"query", "public" | "internal">>(
+  runQuery<
+    Query extends
+      | FunctionReference<"query", "public" | "internal">
+      | FunctionReference_future<"query", "public" | "internal">,
+  >(
     query: Query,
     ...args: OptionalRestArgs<Query>
   ): Promise<FunctionReturnType<Query>>;
@@ -347,7 +362,9 @@ export interface GenericActionCtx<DataModel extends GenericDataModel> {
    * @returns A promise of the mutation's result.
    */
   runMutation<
-    Mutation extends FunctionReference<"mutation", "public" | "internal">,
+    Mutation extends
+      | FunctionReference<"mutation", "public" | "internal">
+      | FunctionReference_future<"mutation", "public" | "internal">,
   >(
     mutation: Mutation,
     ...args: OptionalRestArgs<Mutation>
@@ -369,7 +386,11 @@ export interface GenericActionCtx<DataModel extends GenericDataModel> {
    * @param args - The arguments to the action function.
    * @returns A promise of the action's result.
    */
-  runAction<Action extends FunctionReference<"action", "public" | "internal">>(
+  runAction<
+    Action extends
+      | FunctionReference<"action", "public" | "internal">
+      | FunctionReference_future<"action", "public" | "internal">,
+  >(
     action: Action,
     ...args: OptionalRestArgs<Action>
   ): Promise<FunctionReturnType<Action>>;
@@ -1213,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
@@ -1223,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/scheduler.ts

@@ -1,4 +1,8 @@
-import { FunctionReference, OptionalRestArgs } from "../server/api.js";
+import {
+  FunctionReference,
+  FunctionReference_future,
+  OptionalRestArgs,
+} from "../server/api.js";
 import { Id } from "../values/value.js";
 
 /**
@@ -13,6 +17,17 @@ export type SchedulableFunctionReference = FunctionReference<
   "public" | "internal"
 >;
 
+// What the scheduling methods accept. This is kept separate from the exported
+// `SchedulableFunctionReference` so that alias keeps describing a plain
+// reference. Existing code depending on it can still forward it to anything
+// typed with `FunctionReference` or read its `_args`. This alias is
+// module-local so that a consumer's declaration file inlines it instead of
+// importing it from a path that is not part of the package's public entry
+// points.
+type SchedulableFunctionReferenceCompat =
+  | SchedulableFunctionReference
+  | FunctionReference_future<"mutation" | "action", "public" | "internal">;
+
 /**
  * An interface to schedule Convex functions to run in the future.
  *
@@ -78,13 +93,13 @@ export interface Scheduler {
    * @param delayMs - Delay in milliseconds. Must be non-negative. If the delay
    * is zero, the scheduled function will be due to execute immediately after the
    * scheduling one completes.
-   * @param functionReference - A {@link FunctionReference} for the function
-   * to schedule.
+   * @param functionReference - A {@link FunctionReference} or
+   * {@link FunctionReference_future} for the function to schedule.
    * @param args - Arguments to call the scheduled functions with.
    * @returns The ID of the scheduled function in the `_scheduled_functions`
    * system table. Use this to cancel it later if needed.
    **/
-  runAfter<FuncRef extends SchedulableFunctionReference>(
+  runAfter<FuncRef extends SchedulableFunctionReferenceCompat>(
     delayMs: number,
     functionReference: FuncRef,
     ...args: OptionalRestArgs<FuncRef>
@@ -110,13 +125,13 @@ export interface Scheduler {
    * If the timestamp is in the past, the scheduled function will be due to
    * execute immediately after the scheduling one completes. The timestamp can't
    * be more than five years in the past or more than five years in the future.
-   * @param functionReference - A {@link FunctionReference} for the function
-   * to schedule.
+   * @param functionReference - A {@link FunctionReference} or
+   * {@link FunctionReference_future} for the function to schedule.
    * @param args - Arguments to call the scheduled functions with.
    * @returns The ID of the scheduled function in the `_scheduled_functions`
    * system table.
    **/
-  runAt<FuncRef extends SchedulableFunctionReference>(
+  runAt<FuncRef extends SchedulableFunctionReferenceCompat>(
     timestamp: number | Date,
     functionReference: FuncRef,
     ...args: OptionalRestArgs<FuncRef>

package/src/server/schema.ts

@@ -204,6 +204,9 @@ export class TableDefinition<
   private stagedVectorIndexes: VectorIndex[];
   // The type of documents stored in this table.
   validator: DocumentType;
+  // The proposed next validator for this table, validated against existing
+  // documents in the background while `validator` remains enforced.
+  private stagedValidator: Validator<any, any, any> | undefined;
 
   /**
    * @internal
@@ -557,6 +560,67 @@ export class TableDefinition<
     return this;
   }
 
+  /**
+   * 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 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({
+   *   apple: v.string(),
+   *   banana: v.number(),
+   *   legacy: v.optional(v.string()),
+   * }).staged({
+   *   banana: v.union(v.string(), v.number()),
+   *   legacy: undefined,
+   * })
+   * ```
+   *
+   * See [Staged validators](https://docs.convex.dev/database/schemas#staged-validators).
+   *
+   * @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.
+   */
+  staged(
+    documentSchema:
+      | Validator<Record<string, any>, "required", any>
+      | Record<string, GenericValidator | undefined>,
+  ): TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes> {
+    if (this.stagedValidator !== undefined) {
+      throw new Error("Table cannot have more than one staged validator.");
+    }
+    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();
+  }
+
   /**
    * Work around for https://github.com/microsoft/TypeScript/issues/57035
    */
@@ -582,6 +646,16 @@ export class TableDefinition<
       );
     }
 
+    let stagedDocumentType = undefined;
+    if (this.stagedValidator !== undefined) {
+      stagedDocumentType = this.stagedValidator.json;
+      if (typeof stagedDocumentType !== "object") {
+        throw new Error(
+          "Invalid staged validator: please make sure that the parameter of `.staged()` is valid (see https://docs.convex.dev/database/schemas)",
+        );
+      }
+    }
+
     return {
       indexes: this.indexes,
       stagedDbIndexes: this.stagedDbIndexes,
@@ -590,6 +664,7 @@ export class TableDefinition<
       vectorIndexes: this.vectorIndexes,
       stagedVectorIndexes: this.stagedVectorIndexes,
       documentType,
+      stagedDocumentType,
     };
   }
 }
@@ -884,6 +959,7 @@ export class SchemaDefinition<
           vectorIndexes,
           stagedVectorIndexes,
           documentType,
+          stagedDocumentType,
         } = definition.export();
         return {
           tableName,
@@ -894,6 +970,7 @@ export class SchemaDefinition<
           vectorIndexes,
           stagedVectorIndexes,
           documentType,
+          stagedDocumentType,
         };
       }),
       schemaValidation: this.schemaValidation,

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/validator.ts

@@ -28,7 +28,9 @@ import {
 export type GenericValidator = Validator<any, any, any>;
 
 export function isValidator(v: any): v is GenericValidator {
-  return !!v.isConvexValidator;
+  // Check for the literal `true` marker: a field map can contain a field
+  // *named* `isConvexValidator` whose value is a (truthy) validator object.
+  return v?.isConvexValidator === true;
 }
 
 /**