convex 1.34.1 → 1.35.0

package/src/server/components/index.ts

@@ -94,6 +94,7 @@ export type ComponentDefinition<Exports extends ComponentExports = any> = {
     definition: Definition,
     options?: {
       name?: string;
+      httpPrefix?: string;
     },
   ): InstalledComponent<Definition>;
 
@@ -128,6 +129,7 @@ export type AppDefinition = {
     definition: Definition,
     options?: {
       name?: string;
+      httpPrefix?: string;
     },
   ): InstalledComponent<Definition>;
 };
@@ -143,6 +145,7 @@ type CommonDefinitionData = {
     string,
     ImportedComponentDefinition,
     Record<string, any> | null,
+    string | undefined,
   ][];
   _exportTree: ExportTree;
 };
@@ -152,7 +155,9 @@ type ComponentDefinitionData = CommonDefinitionData & {
   _name: string;
   _onInitCallbacks: Record<string, (argsStr: string) => string>;
 };
-type AppDefinitionData = CommonDefinitionData;
+type AppDefinitionData = CommonDefinitionData & {
+  _httpPrefix?: string;
+};
 
 /**
  * Used to refer to an already-installed component.
@@ -204,6 +209,7 @@ function use<Definition extends ComponentDefinition<any>>(
   definition: Definition,
   options?: {
     name?: string;
+    httpPrefix?: string;
   },
 ): InstalledComponent<Definition> {
   // At runtime an imported component will have this shape.
@@ -232,7 +238,21 @@ function use<Definition extends ComponentDefinition<any>>(
     throw new Error("Component name cannot be empty.");
   }
 
-  this._childComponents.push([name, importedComponentDefinition, {}]);
+  const httpPrefix = options?.httpPrefix;
+  if (httpPrefix !== undefined) {
+    if (!httpPrefix.startsWith("/")) {
+      throw new Error(
+        `httpPrefix must start with "/". Received: "${httpPrefix}"`,
+      );
+    }
+  }
+
+  this._childComponents.push([
+    name,
+    importedComponentDefinition,
+    {},
+    httpPrefix,
+  ]);
   return new InstalledComponent(definition, name);
 }
 
@@ -255,10 +275,14 @@ function exportAppForAnalysis(
 ): AppDefinitionAnalysis {
   const definitionType = { type: "app" as const };
   const childComponents = serializeChildComponents(this._childComponents);
+  const httpMounts = buildHttpMounts(this._childComponents);
   return {
     definitionType,
+    ...(this._httpPrefix !== undefined
+      ? { httpPrefix: normalizeHttpPrefix(this._httpPrefix) }
+      : {}),
     childComponents: childComponents as any,
-    httpMounts: {},
+    httpMounts,
     exports: serializeExportTree(this._exportTree),
   };
 }
@@ -277,11 +301,35 @@ function serializeExportTree(tree: ExportTree): any {
   return { type: "branch", branch };
 }
 
+function normalizeHttpPrefix(prefix: string): string {
+  // Ensure the prefix ends with "/" as required by HttpMountPath in Rust.
+  return prefix.endsWith("/") ? prefix : prefix + "/";
+}
+
+function buildHttpMounts(
+  childComponents: [
+    string,
+    ImportedComponentDefinition,
+    Record<string, any> | null,
+    string | undefined,
+  ][],
+): Record<string, string> {
+  const httpMounts: Record<string, string> = {};
+  for (const [name, , , httpPrefix] of childComponents) {
+    if (httpPrefix !== undefined) {
+      const normalized = normalizeHttpPrefix(httpPrefix);
+      httpMounts[normalized] = `_reference/childComponent/${name}`;
+    }
+  }
+  return httpMounts;
+}
+
 function serializeChildComponents(
   childComponents: [
     string,
     ImportedComponentDefinition,
     Record<string, any> | null,
+    string | undefined,
   ][],
 ): {
   name: string;
@@ -289,6 +337,7 @@ function serializeChildComponents(
   args: [string, { type: "value"; value: string }][] | null;
 }[] {
   return childComponents.map(([name, definition, p]) => {
+    // Note: httpPrefix (4th element) is used separately in buildHttpMounts()
     let args: [string, { type: "value"; value: string }][] | null = null;
     if (p !== null) {
       args = [];
@@ -335,11 +384,12 @@ function exportComponentForAnalysis(
     args,
   };
   const childComponents = serializeChildComponents(this._childComponents);
+  const httpMounts = buildHttpMounts(this._childComponents);
   return {
     name: this._name,
     definitionType,
     childComponents: childComponents as any,
-    httpMounts: {},
+    httpMounts,
     exports: serializeExportTree(this._exportTree),
   };
 }
@@ -394,11 +444,18 @@ export function defineComponent<Exports extends ComponentExports = any>(
  * This is a feature of components, which are in beta.
  * This API is unstable and may change in subsequent releases.
  */
-export function defineApp(): AppDefinition {
+export function defineApp(options?: { httpPrefix?: string }): AppDefinition {
+  const httpPrefix = options?.httpPrefix;
+  if (httpPrefix !== undefined && !httpPrefix.startsWith("/")) {
+    throw new Error(
+      `httpPrefix must start with "/". Received: "${httpPrefix}"`,
+    );
+  }
   const ret: RuntimeAppDefinition = {
     _isRoot: true,
     _childComponents: [],
     _exportTree: {},
+    ...(httpPrefix !== undefined ? { _httpPrefix: httpPrefix } : {}),
 
     export: exportAppForAnalysis,
     use,

package/src/server/data_model.ts

@@ -1,4 +1,5 @@
 import { Value } from "../values/index.js";
+import type { SystemIndexes } from "./system_fields.js";
 
 // Document Types  /////////////////////////////////////////////////////////////
 
@@ -262,7 +263,7 @@ export type AnyDataModel = {
   [tableName: string]: {
     document: any;
     fieldPaths: GenericFieldPaths;
-    indexes: {};
+    indexes: SystemIndexes;
     searchIndexes: {};
     vectorIndexes: {};
   };

package/src/server/impl/meta_impl.ts

@@ -0,0 +1,74 @@
+import { jsonToConvex } from "../../values/index.js";
+import {
+  ActionMeta,
+  MutationMeta,
+  QueryMeta,
+  FunctionMetadata,
+  TransactionMetrics,
+} from "../meta.js";
+import { performAsyncSyscall } from "./syscall.js";
+
+async function getTransactionMetrics(): Promise<TransactionMetrics> {
+  let syscallJSON;
+  try {
+    syscallJSON = await performAsyncSyscall("1.0/getTransactionMetrics", {});
+  } catch (e: any) {
+    if (e.message?.includes("Unknown async operation")) {
+      throw new Error(
+        "getTransactionMetrics() can only be called from a query or mutation. " +
+          "It is not available in actions or outside of a Convex function.",
+      );
+    }
+    throw e;
+  }
+  return jsonToConvex(syscallJSON) as any;
+}
+
+async function getFunctionMetadata(): Promise<{
+  name: string;
+  componentPath: string;
+}> {
+  const { name, componentPath } = await performAsyncSyscall(
+    "1.0/getFunctionMetadata",
+    {},
+  );
+  return { name, componentPath };
+}
+
+export function setupQueryMeta(
+  visibility: FunctionMetadata["visibility"],
+): QueryMeta {
+  return {
+    getFunctionMetadata: async () => ({
+      ...(await getFunctionMetadata()),
+      type: "query",
+      visibility,
+    }),
+    getTransactionMetrics,
+  };
+}
+
+export function setupMutationMeta(
+  visibility: FunctionMetadata["visibility"],
+): MutationMeta {
+  return {
+    getFunctionMetadata: async () => ({
+      ...(await getFunctionMetadata()),
+      type: "mutation",
+      visibility,
+    }),
+    getTransactionMetrics,
+  };
+}
+
+export function setupActionMeta(
+  visibility: FunctionMetadata["visibility"],
+): ActionMeta {
+  return {
+    getFunctionMetadata: async () => ({
+      ...(await getFunctionMetadata()),
+      type: "action",
+      visibility,
+    }),
+  };
+}

package/src/server/impl/registration_impl.ts

@@ -11,6 +11,7 @@ import { GenericDataModel } from "../data_model.js";
 import {
   ActionBuilder,
   DefaultFunctionArgs,
+  FunctionVisibility,
   GenericActionCtx,
   GenericMutationCtx,
   GenericQueryCtx,
@@ -39,10 +40,15 @@ import { parseArgs } from "../../common/index.js";
 import { performAsyncSyscall } from "./syscall.js";
 import { asObjectValidator } from "../../values/validator.js";
 import { getFunctionAddress } from "../components/paths.js";
+import {
+  setupQueryMeta,
+  setupMutationMeta,
+  setupActionMeta,
+} from "./meta_impl.js";
 
 async function invokeMutation<
   F extends (ctx: GenericMutationCtx<GenericDataModel>, ...args: any) => any,
->(func: F, argsStr: string) {
+>(func: F, argsStr: string, visibility: FunctionVisibility) {
   // TODO(presley): Change the function signature and propagate the requestId from Rust.
   // Ok, to mock it out for now, since queries are only running in V8.
   const requestId = "";
@@ -52,6 +58,7 @@ async function invokeMutation<
     auth: setupAuth(requestId),
     storage: setupStorageWriter(requestId),
     scheduler: setupMutationScheduler(),
+    meta: setupMutationMeta(visibility),
 
     runQuery: (reference: any, args?: any) => runUdf("query", reference, args),
     runMutation: (reference: any, args?: any) =>
@@ -247,7 +254,7 @@ export const mutationGeneric: MutationBuilder<any, "public"> = ((
   assertNotBrowser();
   func.isMutation = true;
   func.isPublic = true;
-  func.invokeMutation = (argsStr) => invokeMutation(handler, argsStr);
+  func.invokeMutation = (argsStr) => invokeMutation(handler, argsStr, "public");
   func.exportArgs = exportArgs(functionDefinition);
   func.exportReturns = exportReturns(functionDefinition);
   func._handler = handler;
@@ -308,7 +315,8 @@ export const internalMutationGeneric: MutationBuilder<any, "internal"> = ((
   assertNotBrowser();
   func.isMutation = true;
   func.isInternal = true;
-  func.invokeMutation = (argsStr) => invokeMutation(handler, argsStr);
+  func.invokeMutation = (argsStr) =>
+    invokeMutation(handler, argsStr, "internal");
   func.exportArgs = exportArgs(functionDefinition);
   func.exportReturns = exportReturns(functionDefinition);
   func._handler = handler;
@@ -317,7 +325,7 @@ export const internalMutationGeneric: MutationBuilder<any, "internal"> = ((
 
 async function invokeQuery<
   F extends (ctx: GenericQueryCtx<GenericDataModel>, ...args: any) => any,
->(func: F, argsStr: string) {
+>(func: F, argsStr: string, visibility: FunctionVisibility) {
   // TODO(presley): Change the function signature and propagate the requestId from Rust.
   // Ok, to mock it out for now, since queries are only running in V8.
   const requestId = "";
@@ -326,6 +334,7 @@ async function invokeQuery<
     db: setupReader(),
     auth: setupAuth(requestId),
     storage: setupStorageReader(requestId),
+    meta: setupQueryMeta(visibility),
     runQuery: (reference: any, args?: any) => runUdf("query", reference, args),
   };
   const result = await invokeFunction(func, queryCtx, args as any);
@@ -403,7 +412,7 @@ export const queryGeneric: QueryBuilder<any, "public"> = ((
   assertNotBrowser();
   func.isQuery = true;
   func.isPublic = true;
-  func.invokeQuery = (argsStr) => invokeQuery(handler, argsStr);
+  func.invokeQuery = (argsStr) => invokeQuery(handler, argsStr, "public");
   func.exportArgs = exportArgs(functionDefinition);
   func.exportReturns = exportReturns(functionDefinition);
   func._handler = handler;
@@ -470,7 +479,8 @@ export const internalQueryGeneric: QueryBuilder<any, "internal"> = ((
   assertNotBrowser();
   func.isQuery = true;
   func.isInternal = true;
-  func.invokeQuery = (argsStr) => invokeQuery(handler as any, argsStr);
+  func.invokeQuery = (argsStr) =>
+    invokeQuery(handler as any, argsStr, "internal");
   func.exportArgs = exportArgs(functionDefinition);
   func.exportReturns = exportReturns(functionDefinition);
   func._handler = handler;
@@ -479,7 +489,7 @@ export const internalQueryGeneric: QueryBuilder<any, "internal"> = ((
 
 async function invokeAction<
   F extends (ctx: GenericActionCtx<GenericDataModel>, ...args: any) => any,
->(func: F, requestId: string, argsStr: string) {
+>(func: F, requestId: string, argsStr: string, visibility: FunctionVisibility) {
   const args = jsonToConvex(JSON.parse(argsStr));
   const calls = setupActionCalls(requestId);
   const ctx = {
@@ -488,6 +498,7 @@ async function invokeAction<
     scheduler: setupActionScheduler(requestId),
     storage: setupStorageActionWriter(requestId),
     vectorSearch: setupActionVectorSearch(requestId) as any,
+    meta: setupActionMeta(visibility),
   };
   const result = await invokeFunction(func, ctx, args as any);
   return JSON.stringify(convexToJson(result === undefined ? null : result));
@@ -577,7 +588,7 @@ export const actionGeneric: ActionBuilder<any, "public"> = ((
   func.isAction = true;
   func.isPublic = true;
   func.invokeAction = (requestId, argsStr) =>
-    invokeAction(handler, requestId, argsStr);
+    invokeAction(handler, requestId, argsStr, "public");
   func.exportArgs = exportArgs(functionDefinition);
   func.exportReturns = exportReturns(functionDefinition);
   func._handler = handler;
@@ -650,7 +661,7 @@ export const internalActionGeneric: ActionBuilder<any, "internal"> = ((
   func.isAction = true;
   func.isInternal = true;
   func.invokeAction = (requestId, argsStr) =>
-    invokeAction(handler, requestId, argsStr);
+    invokeAction(handler, requestId, argsStr, "internal");
   func.exportArgs = exportArgs(functionDefinition);
   func.exportReturns = exportReturns(functionDefinition);
   func._handler = handler;
@@ -670,6 +681,7 @@ async function invokeHttpAction<
     storage: setupStorageActionWriter(requestId),
     scheduler: setupActionScheduler(requestId),
     vectorSearch: setupActionVectorSearch(requestId) as any,
+    meta: setupActionMeta("public"),
   };
   return await invokeFunction(func, ctx, [request]);
 }

package/src/server/index.ts

@@ -103,6 +103,14 @@ export {
   internalMutationGeneric,
   internalQueryGeneric,
 } from "./impl/registration_impl.js";
+export type {
+  TransactionMetric,
+  TransactionMetrics,
+  FunctionMetadata,
+  QueryMeta,
+  MutationMeta,
+  ActionMeta,
+} from "./meta.js";
 export type { IndexRange, IndexRangeBuilder } from "./index_range_builder.js";
 export * from "./pagination.js";
 export type { OrderedQuery, Query, QueryInitializer } from "./query.js";

package/src/server/meta.ts

@@ -0,0 +1,76 @@
+import { FunctionType } from "./api.js";
+import { FunctionVisibility } from "./registration.js";
+
+/**
+ * Used and remaining amounts for a single transaction limit.
+ *
+ * @public
+ */
+export type TransactionMetric = {
+  used: number;
+  remaining: number;
+};
+
+/**
+ * The remaining headroom for a transaction before hitting limits.
+ *
+ * See https://docs.convex.dev/production/state/limits
+ *
+ * @public
+ */
+export type TransactionMetrics = {
+  bytesRead: TransactionMetric;
+  bytesWritten: TransactionMetric;
+  databaseQueries: TransactionMetric;
+  documentsRead: TransactionMetric;
+  documentsWritten: TransactionMetric;
+  functionsScheduled: TransactionMetric;
+  scheduledFunctionArgsBytes: TransactionMetric;
+};
+
+/**
+ * Metadata about the currently executing Convex function.
+ *
+ * @public
+ */
+export type FunctionMetadata = {
+  /**
+   * The name of the function, in the format `"path/to/module:functionName"`
+   */
+  name: string;
+  /**
+   * The path of the component this function belongs to.
+   * This is an empty string `""` for the app.
+   */
+  componentPath: string;
+  /** Whether it's a query, mutation, or action. */
+  type: FunctionType;
+  /** Whether the function is public or internal. */
+  visibility: FunctionVisibility;
+};
+
+/**
+ * Extra context available in Convex query functions.
+ *
+ * @public
+ */
+export interface QueryMeta {
+  getFunctionMetadata(): Promise<FunctionMetadata>;
+  getTransactionMetrics(): Promise<TransactionMetrics>;
+}
+
+/**
+ * Extra context available in Convex mutation functions.
+ *
+ * @public
+ */
+export interface MutationMeta extends QueryMeta {}
+
+/**
+ * Extra context available in Convex action functions.
+ *
+ * @public
+ */
+export interface ActionMeta {
+  getFunctionMetadata(): Promise<FunctionMetadata>;
+}

package/src/server/registration.ts

@@ -8,6 +8,7 @@ import {
   StorageReader,
   StorageWriter,
 } from "./index.js";
+import { ActionMeta, MutationMeta, QueryMeta } from "./meta.js";
 import {
   FunctionReference,
   FunctionReturnType,
@@ -147,6 +148,9 @@ export interface GenericMutationCtx<DataModel extends GenericDataModel> {
     mutation: Mutation,
     ...args: OptionalRestArgs<Mutation>
   ) => Promise<FunctionReturnType<Mutation>>;
+
+  /** @internal */
+  meta: MutationMeta;
 }
 
 /**
@@ -238,6 +242,9 @@ export interface GenericQueryCtx<DataModel extends GenericDataModel> {
     query: Query,
     ...args: OptionalRestArgs<Query>
   ) => Promise<FunctionReturnType<Query>>;
+
+  /** @internal */
+  meta: QueryMeta;
 }
 
 /**
@@ -398,6 +405,9 @@ export interface GenericActionCtx<DataModel extends GenericDataModel> {
       VectorSearchQuery<NamedTableInfo<DataModel, TableName>, IndexName>
     >,
   ): Promise<Array<{ _id: Id<TableName>; _score: number }>>;
+
+  /** @internal */
+  meta: ActionMeta;
 }
 
 /**

package/src/server/schema.test.ts

@@ -7,8 +7,16 @@ import {
   defineSchema,
   defineTable,
   DataModelFromSchemaDefinition,
+  GenericSchema,
+  SchemaDefinition,
 } from "./schema.js";
 import { v, Infer } from "../values/validator.js";
+import {
+  AnyDataModel,
+  GenericDataModel,
+  IndexNames,
+  NamedTableInfo,
+} from "./data_model.js";
 
 describe("DataModelFromSchemaDefinition", () => {
   test("defineSchema produces the correct data model for basic types", () => {
@@ -405,7 +413,7 @@ describe("DataModelFromSchemaDefinition", () => {
       [tableName: string]: {
         document: any;
         fieldPaths: string;
-        indexes: {};
+        indexes: SystemIndexes;
         searchIndexes: {};
         vectorIndexes: {};
       };
@@ -890,6 +898,75 @@ describe("defineSchema/defineTable expose table validators", () => {
   });
 });
 
+describe("GenericSchema assignability", () => {
+  test("DataModelFromSchemaDefinition<GenericSchema> extends GenericDataModel", () => {
+    type GenericDM = DataModelFromSchemaDefinition<
+      SchemaDefinition<GenericSchema, boolean>
+    >;
+    type _check = GenericDM extends GenericDataModel ? true : false;
+    assert<Equals<_check, true>>();
+  });
+
+  test("a specific schema’s DataModel extends GenericDataModel", () => {
+    const specificSchema = defineSchema({
+      users: defineTable({ name: v.string() }).index("by_name", ["name"]),
+    });
+    type SpecificDM = DataModelFromSchemaDefinition<typeof specificSchema>;
+
+    // This is the key assignability check: specific DataModels must extend
+    // GenericDataModel so that generic code can accept any schema.
+    type _check = SpecificDM extends GenericDataModel ? true : false;
+    assert<Equals<_check, true>>();
+  });
+
+  test("SchemaDefinition<SpecificSchema> extends SchemaDefinition<GenericSchema, boolean>", () => {
+    const specificSchema = defineSchema({
+      messages: defineTable({ body: v.string() }),
+    });
+    type SpecificSD = typeof specificSchema;
+    type GenericSD = SchemaDefinition<GenericSchema, boolean>;
+
+    type _check = SpecificSD extends GenericSD ? true : false;
+    assert<Equals<_check, true>>();
+  });
+
+  test("specific DM from boolean-strict schema extends generic DM", () => {
+    // This mirrors the convexTest() return type: Schema is specific, but
+    // StrictTableNameTypes is widened to boolean.
+    const specificSchema = defineSchema({
+      users: defineTable({ name: v.string() }).index("by_name", ["name"]),
+    });
+    type SpecificDM = DataModelFromSchemaDefinition<
+      SchemaDefinition<(typeof specificSchema)["tables"], boolean>
+    >;
+    type GenericDM = DataModelFromSchemaDefinition<
+      SchemaDefinition<GenericSchema, boolean>
+    >;
+
+    // The specific DM must extend the generic DM for TestConvex covariance.
+    type _check = SpecificDM extends GenericDM ? true : false;
+    assert<Equals<_check, true>>();
+  });
+
+  test("AnyDataModel exposes system indexes", () => {
+    // AnyDataModel is used as the DataModel when no schema is defined.
+    // Verify that system indexes (by_id, by_creation_time) are available,
+    // since every table always has them.
+    type AnyTable = NamedTableInfo<AnyDataModel, string>;
+    type AnyIndexNames = IndexNames<AnyTable>;
+    type _check = "by_id" | "by_creation_time" extends AnyIndexNames
+      ? true
+      : false;
+    assert<Equals<_check, true>>();
+  });
+
+  // SpecificDM extends GenericDM because:
+  // 1. GenericSchema uses TableDefinition defaults (Validator<any,any,any>)
+  //    producing document: any and fieldPaths: any
+  // 2. AnyDataModel includes SystemIndexes, so the loose variant's index
+  //    signature satisfies GenericDM's SystemIndexes requirement
+});
+
 test("defineTable fails if it can’t export the validator", () => {
   const table = defineTable(
     // @ts-expect-error