convex 1.41.0 → 1.42.0

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

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