convex 1.45.0-alpha.0 → 1.46.0

package/src/server/cron.ts

@@ -1,9 +1,19 @@
-import { getFunctionName, OptionalRestArgs } from "../server/api.js";
+import {
+  FunctionReference_future,
+  getFunctionName,
+  OptionalRestArgs,
+} from "../server/api.js";
 import { parseArgs } from "../common/index.js";
 import { convexToJson, JSONValue, Value } from "../values/index.js";
 import { getFunctionAddress } from "./components/paths.js";
 import { SchedulableFunctionReference } from "./scheduler.js";
 
+// Mirrors the constraint on `Scheduler.runAfter` and `Scheduler.runAt`, which
+// is module-local to `scheduler.ts`.
+type SchedulableFunctionReferenceCompat =
+  | SchedulableFunctionReference
+  | FunctionReference_future<"mutation" | "action", "public" | "internal">;
+
 type CronSchedule = {
   type: "cron";
   cron: string;
@@ -238,8 +248,8 @@ function validatedOptionalMinuteOfHour(n: number | undefined) {
 // call shapes apart by whether the second argument resolves to a function
 // reference (the way the scheduler syscalls do) rather than a schedule object.
 function isSchedulableFunctionReference(
-  arg: Hourly | SchedulableFunctionReference,
-): arg is SchedulableFunctionReference {
+  arg: Hourly | SchedulableFunctionReferenceCompat,
+): arg is SchedulableFunctionReferenceCompat {
   try {
     getFunctionAddress(arg);
     return true;
@@ -280,7 +290,7 @@ export class Crons {
   schedule(
     cronIdentifier: string,
     schedule: Schedule,
-    functionReference: SchedulableFunctionReference,
+    functionReference: SchedulableFunctionReferenceCompat,
     args?: Record<string, Value>,
   ) {
     const cronArgs = parseArgs(args);
@@ -304,11 +314,11 @@ export class Crons {
    *
    * @param identifier - A unique name for this scheduled job.
    * @param schedule - The time between runs for this scheduled job.
-   * @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 - The arguments to the function.
    */
-  interval<FuncRef extends SchedulableFunctionReference>(
+  interval<FuncRef extends SchedulableFunctionReferenceCompat>(
     cronIdentifier: string,
     schedule: Interval,
     functionReference: FuncRef,
@@ -353,22 +363,22 @@ export class Crons {
    * @param cronIdentifier - A unique name for this scheduled job.
    * @param schedule - What minute (UTC) of each hour to run this function. May
    * be omitted to let Convex pick a minute and spread runs across the hour.
-   * @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 - The arguments to the function.
    */
-  hourly<FuncRef extends SchedulableFunctionReference>(
+  hourly<FuncRef extends SchedulableFunctionReferenceCompat>(
     cronIdentifier: string,
     functionReference: FuncRef,
     ...args: OptionalRestArgs<FuncRef>
   ): void;
-  hourly<FuncRef extends SchedulableFunctionReference>(
+  hourly<FuncRef extends SchedulableFunctionReferenceCompat>(
     cronIdentifier: string,
     schedule: Hourly,
     functionReference: FuncRef,
     ...args: OptionalRestArgs<FuncRef>
   ): void;
-  hourly<FuncRef extends SchedulableFunctionReference>(
+  hourly<FuncRef extends SchedulableFunctionReferenceCompat>(
     cronIdentifier: string,
     scheduleOrFunctionReference: Hourly | FuncRef,
     functionReferenceOrArg?: FuncRef | Record<string, Value>,
@@ -414,11 +424,11 @@ export class Crons {
    *
    * @param cronIdentifier - A unique name for this scheduled job.
    * @param schedule - What time (UTC) each day to run this function.
-   * @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 - The arguments to the function.
    */
-  daily<FuncRef extends SchedulableFunctionReference>(
+  daily<FuncRef extends SchedulableFunctionReferenceCompat>(
     cronIdentifier: string,
     schedule: Daily,
     functionReference: FuncRef,
@@ -453,10 +463,10 @@ export class Crons {
    *
    * @param cronIdentifier - A unique name for this scheduled job.
    * @param schedule - What day and time (UTC) each week to run this function.
-   * @param functionReference - A {@link FunctionReference} for the function
-   * to schedule.
+   * @param functionReference - A {@link FunctionReference} or
+   * {@link FunctionReference_future} for the function to schedule.
    */
-  weekly<FuncRef extends SchedulableFunctionReference>(
+  weekly<FuncRef extends SchedulableFunctionReferenceCompat>(
     cronIdentifier: string,
     schedule: Weekly,
     functionReference: FuncRef,
@@ -495,11 +505,11 @@ export class Crons {
    *
    * @param cronIdentifier - A unique name for this scheduled job.
    * @param schedule - What day and time (UTC) each month to run this function.
-   * @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 - The arguments to the function.
    */
-  monthly<FuncRef extends SchedulableFunctionReference>(
+  monthly<FuncRef extends SchedulableFunctionReferenceCompat>(
     cronIdentifier: string,
     schedule: Monthly,
     functionReference: FuncRef,
@@ -534,11 +544,11 @@ export class Crons {
    *
    * @param cronIdentifier - A unique name for this scheduled job.
    * @param cron - Cron string like `"15 7 * * *"` (Every day at 7:15 UTC)
-   * @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 - The arguments to the function.
    */
-  cron<FuncRef extends SchedulableFunctionReference>(
+  cron<FuncRef extends SchedulableFunctionReferenceCompat>(
     cronIdentifier: string,
     cron: CronString,
     functionReference: FuncRef,

package/src/server/impl/actions_impl.ts

@@ -2,7 +2,10 @@ import { convexToJson, jsonToConvex, Value } from "../../values/index.js";
 import { version } from "../../index.js";
 import { performAsyncSyscall } from "./syscall.js";
 import { parseArgs } from "../../common/index.js";
-import { FunctionReference } from "../../server/api.js";
+import {
+  FunctionReference,
+  FunctionReference_future,
+} from "../../server/api.js";
 import { getFunctionAddress } from "../components/paths.js";
 import { validateArg } from "./validate.js";
 
@@ -23,7 +26,9 @@ function syscallArgs(
 export function setupActionCalls(requestId: string) {
   return {
     runQuery: async (
-      query: FunctionReference<"query", "public" | "internal">,
+      query:
+        | FunctionReference<"query", "public" | "internal">
+        | FunctionReference_future<"query", "public" | "internal">,
       args?: Record<string, Value>,
     ): Promise<any> => {
       const result = await performAsyncSyscall(
@@ -33,7 +38,9 @@ export function setupActionCalls(requestId: string) {
       return jsonToConvex(result);
     },
     runMutation: async (
-      mutation: FunctionReference<"mutation", "public" | "internal">,
+      mutation:
+        | FunctionReference<"mutation", "public" | "internal">
+        | FunctionReference_future<"mutation", "public" | "internal">,
       args?: Record<string, Value>,
     ): Promise<any> => {
       const result = await performAsyncSyscall(
@@ -43,7 +50,9 @@ export function setupActionCalls(requestId: string) {
       return jsonToConvex(result);
     },
     runAction: async (
-      action: FunctionReference<"action", "public" | "internal">,
+      action:
+        | FunctionReference<"action", "public" | "internal">
+        | FunctionReference_future<"action", "public" | "internal">,
       args?: Record<string, Value>,
     ): Promise<any> => {
       const result = await performAsyncSyscall(
@@ -64,7 +73,9 @@ export function setupActionCalls(requestId: string) {
  * cached, so a later call retries.
  *
  * @param service - The service the credential may access.
- * @internal
+ * @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> {
   validateArg(service, 1, "getServiceToken", "service");

package/src/server/impl/meta_impl.ts

@@ -8,7 +8,7 @@ import {
   TransactionMetrics,
   DeploymentMetadata,
 } from "../meta.js";
-import { performAsyncSyscall } from "./syscall.js";
+import { performAsyncSyscall, performSyscall } from "./syscall.js";
 
 async function getTransactionMetrics(): Promise<TransactionMetrics> {
   let syscallJSON;
@@ -53,6 +53,11 @@ async function getDeploymentMetadata(): Promise<DeploymentMetadata> {
   };
 }
 
+function getSnapshotTs(): bigint {
+  const syscallJSON = performSyscall("1.0/getSnapshotTs", {});
+  return jsonToConvex(syscallJSON) as bigint;
+}
+
 async function getRequestMetadata(): Promise<RequestMetadata> {
   const { ip, userAgent, requestId, scheduledFunctionId, authToken } =
     await performAsyncSyscall("1.0/getRequestMetadata", {});
@@ -70,6 +75,7 @@ export function setupQueryMeta(
     }),
     getTransactionMetrics,
     getDeploymentMetadata,
+    getSnapshotTs,
   };
 }
 
@@ -85,6 +91,7 @@ export function setupMutationMeta(
     getTransactionMetrics,
     getDeploymentMetadata,
     getRequestMetadata,
+    getSnapshotTs,
   };
 }
 

package/src/server/impl/scheduler_impl.ts

@@ -3,15 +3,22 @@ import { version } from "../../index.js";
 import { performAsyncSyscall } from "./syscall.js";
 import { parseArgs } from "../../common/index.js";
 import { SchedulableFunctionReference, Scheduler } from "../scheduler.js";
+import { FunctionReference_future } from "../api.js";
 import { Id } from "../../values/value.js";
 import { validateArg } from "./validate.js";
 import { getFunctionAddress } from "../components/paths.js";
 
+// Mirrors the constraint on `Scheduler.runAfter` and `Scheduler.runAt`, which
+// is module-local to `scheduler.ts`.
+type SchedulableFunctionReferenceCompat =
+  | SchedulableFunctionReference
+  | FunctionReference_future<"mutation" | "action", "public" | "internal">;
+
 export function setupMutationScheduler(): Scheduler {
   return {
     runAfter: async (
       delayMs: number,
-      functionReference: SchedulableFunctionReference,
+      functionReference: SchedulableFunctionReferenceCompat,
       args?: Record<string, Value>,
     ) => {
       const syscallArgs = runAfterSyscallArgs(delayMs, functionReference, args);
@@ -19,7 +26,7 @@ export function setupMutationScheduler(): Scheduler {
     },
     runAt: async (
       ms_since_epoch_or_date: number | Date,
-      functionReference: SchedulableFunctionReference,
+      functionReference: SchedulableFunctionReferenceCompat,
       args?: Record<string, Value>,
     ) => {
       const syscallArgs = runAtSyscallArgs(
@@ -41,7 +48,7 @@ export function setupActionScheduler(requestId: string): Scheduler {
   return {
     runAfter: async (
       delayMs: number,
-      functionReference: SchedulableFunctionReference,
+      functionReference: SchedulableFunctionReferenceCompat,
       args?: Record<string, Value>,
     ) => {
       const syscallArgs = {
@@ -52,7 +59,7 @@ export function setupActionScheduler(requestId: string): Scheduler {
     },
     runAt: async (
       ms_since_epoch_or_date: number | Date,
-      functionReference: SchedulableFunctionReference,
+      functionReference: SchedulableFunctionReferenceCompat,
       args?: Record<string, Value>,
     ) => {
       const syscallArgs = {
@@ -74,7 +81,7 @@ export function setupActionScheduler(requestId: string): Scheduler {
 
 function runAfterSyscallArgs(
   delayMs: number,
-  functionReference: SchedulableFunctionReference,
+  functionReference: SchedulableFunctionReferenceCompat,
   args?: Record<string, Value>,
 ) {
   if (typeof delayMs !== "number") {
@@ -100,7 +107,7 @@ function runAfterSyscallArgs(
 
 function runAtSyscallArgs(
   ms_since_epoch_or_date: number | Date,
-  functionReference: SchedulableFunctionReference,
+  functionReference: SchedulableFunctionReferenceCompat,
   args?: Record<string, Value>,
 ) {
   let ts;

package/src/server/index.ts

@@ -103,9 +103,6 @@ export {
   internalMutationGeneric,
   internalQueryGeneric,
 } from "./impl/registration_impl.js";
-/**
- * @internal
- */
 export { getServiceToken } from "./impl/actions_impl.js";
 export type {
   TransactionMetric,
@@ -177,6 +174,7 @@ export {
 export type {
   ApiFromModules,
   AnyApi,
+  FunctionReference_future,
   FilterApi,
   FunctionType,
   FunctionReference,

package/src/server/meta.ts

@@ -133,6 +133,31 @@ export interface QueryMeta {
   getFunctionMetadata(): Promise<FunctionMetadata>;
   getTransactionMetrics(): Promise<TransactionMetrics>;
   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.
+   *
+   * 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.
+   */
+  getSnapshotTs(): bigint;
 }
 
 /**

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>>;

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,45 @@ export class TableDefinition<
     return this;
   }
 
+  /**
+   * Stage a new document validator for this table.
+   *
+   * 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()`.
+   *
+   * ```ts
+   * defineTable({
+   *   author: v.string(),
+   * }).staged({
+   *   author: v.array(v.string()),
+   * })
+   * ```
+   *
+   * TODO: link a worked staged-schema example from the docs once one exists.
+   *
+   * @param documentSchema - The proposed next type of documents stored in
+   * this table, as an object of field validators or a schema validator.
+   * @returns A {@link TableDefinition} with the staged validator attached.
+   *
+   * @internal
+   */
+  staged(
+    documentSchema:
+      | Validator<Record<string, any>, "required", any>
+      | Record<string, GenericValidator>,
+  ): 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);
+    return this.self();
+  }
+
   /**
    * Work around for https://github.com/microsoft/TypeScript/issues/57035
    */
@@ -582,6 +624,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 +642,7 @@ export class TableDefinition<
       vectorIndexes: this.vectorIndexes,
       stagedVectorIndexes: this.stagedVectorIndexes,
       documentType,
+      stagedDocumentType,
     };
   }
 }
@@ -884,6 +937,7 @@ export class SchemaDefinition<
           vectorIndexes,
           stagedVectorIndexes,
           documentType,
+          stagedDocumentType,
         } = definition.export();
         return {
           tableName,
@@ -894,6 +948,7 @@ export class SchemaDefinition<
           vectorIndexes,
           stagedVectorIndexes,
           documentType,
+          stagedDocumentType,
         };
       }),
       schemaValidation: this.schemaValidation,

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;
 }
 
 /**