convex 1.43.0 → 1.44.0

package/src/server/impl/actions_impl.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { version } from "../../index.js";
+import * as syscall from "./syscall.js";
+import { getServiceToken } from "./actions_impl.js";
+
+vi.mock("./syscall.js", () => ({
+  performAsyncSyscall: vi.fn(),
+}));
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("getServiceToken", () => {
+  test("requires a service", async () => {
+    await expect(
+      getServiceToken(undefined as unknown as "ai-gateway"),
+    ).rejects.toThrow("Must provide arg 1 `service` to `getServiceToken`");
+    expect(syscall.performAsyncSyscall).not.toHaveBeenCalled();
+  });
+
+  test("requests an LLM token for the current action", async () => {
+    vi.mocked(syscall.performAsyncSyscall).mockResolvedValue("jwt");
+
+    const token = await getServiceToken("ai-gateway");
+
+    expect(token).toBe("jwt");
+    expect(syscall.performAsyncSyscall).toHaveBeenCalledWith(
+      "1.0/createServiceToken",
+      {
+        service: "ai-gateway",
+        version,
+      },
+    );
+  });
+
+  test("rejects the former service spelling", async () => {
+    await expect(getServiceToken("ai" as "ai-gateway")).rejects.toThrow(
+      'Unsupported service "ai"',
+    );
+    expect(syscall.performAsyncSyscall).not.toHaveBeenCalled();
+  });
+
+  test("rejects unsupported services before issuing a syscall", async () => {
+    await expect(getServiceToken("other" as "ai-gateway")).rejects.toThrow(
+      'Unsupported service "other"',
+    );
+    expect(syscall.performAsyncSyscall).not.toHaveBeenCalled();
+  });
+
+  test("preserves syscall errors", async () => {
+    const error = new Error(
+      "Unknown async operation 1.0/createServiceToken with args {}",
+    );
+    vi.mocked(syscall.performAsyncSyscall).mockRejectedValue(error);
+
+    await expect(getServiceToken("ai-gateway")).rejects.toBe(error);
+  });
+});

package/src/server/impl/actions_impl.ts

@@ -4,6 +4,7 @@ import { performAsyncSyscall } from "./syscall.js";
 import { parseArgs } from "../../common/index.js";
 import { FunctionReference } from "../../server/api.js";
 import { getFunctionAddress } from "../components/paths.js";
+import { validateArg } from "./validate.js";
 
 function syscallArgs(
   requestId: string,
@@ -53,3 +54,25 @@ export function setupActionCalls(requestId: string) {
     },
   };
 }
+
+/**
+ * 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.
+ *
+ * @param service - The service the credential may access.
+ * @internal
+ */
+export async function getServiceToken(service: "ai-gateway"): 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,
+  });
+}

package/src/server/index.ts

@@ -103,6 +103,10 @@ export {
   internalMutationGeneric,
   internalQueryGeneric,
 } from "./impl/registration_impl.js";
+/**
+ * @internal
+ */
+export { getServiceToken } from "./impl/actions_impl.js";
 export type {
   TransactionMetric,
   TransactionMetrics,
@@ -223,8 +227,10 @@ export type {
   DataModelFromSchemaDefinition,
   SystemDataModel,
   SystemTableNames,
+  DocValidator,
+  SystemFieldValidators,
 } from "./schema.js";
-export { defineTable, defineSchema } from "./schema.js";
+export { defineTable, defineSchema, docValidator } from "./schema.js";
 
 export type {
   VectorSearch,

package/src/server/schema.test.ts

@@ -9,6 +9,7 @@ import {
   DataModelFromSchemaDefinition,
   GenericSchema,
   SchemaDefinition,
+  docValidator,
 } from "./schema.js";
 import { v, Infer } from "../values/validator.js";
 import {
@@ -903,6 +904,103 @@ describe("defineSchema/defineTable expose table validators", () => {
   });
 });
 
+describe("docValidator", () => {
+  const objectSchema = defineSchema({
+    messages: defineTable({ body: v.string(), author: v.id("users") }),
+  });
+
+  const unionSchema = defineSchema({
+    results: defineTable(
+      v.union(
+        v.object({ kind: v.literal("error"), message: v.string() }),
+        v.object({ kind: v.literal("success"), value: v.number() }),
+      ),
+    ),
+  });
+
+  test("adds system fields to an object table", () => {
+    const doc = docValidator("messages", objectSchema.tables.messages);
+    const expected = v.object({
+      _id: v.id("messages"),
+      _creationTime: v.number(),
+      body: v.string(),
+      author: v.id("users"),
+    });
+    expect(doc.json).toEqual(expected.json);
+    assert<Equals<Infer<typeof doc>, Infer<typeof expected>>>();
+  });
+
+  test("adds system fields to each member of a union table", () => {
+    const doc = docValidator("results", unionSchema.tables.results);
+    const systemFields = {
+      _id: v.id("results"),
+      _creationTime: v.number(),
+    };
+    const expected = v.union(
+      v.object({
+        ...systemFields,
+        kind: v.literal("error"),
+        message: v.string(),
+      }),
+      v.object({
+        ...systemFields,
+        kind: v.literal("success"),
+        value: v.number(),
+      }),
+    );
+    expect(doc.json).toEqual(expected.json);
+    assert<Equals<Infer<typeof doc>, Infer<typeof expected>>>();
+    // The members stay individually typed, so they can be narrowed.
+    assert<
+      Equals<
+        Infer<(typeof doc.members)[0]>,
+        Infer<(typeof expected.members)[0]>
+      >
+    >();
+  });
+
+  test("passes through v.any()", () => {
+    const anySchema = defineSchema({ anything: defineTable(v.any()) });
+    const doc = docValidator("anything", anySchema.tables.anything);
+    expect(doc.json).toEqual(v.any().json);
+  });
+
+  test("rejects a table whose documents are not objects", () => {
+    const table = defineTable(v.array(v.string()) as any);
+    expect(() => docValidator("bad", table)).toThrow(
+      'Invalid validator for table "bad"',
+    );
+  });
+});
+
+describe("SchemaDefinition.doc/.id", () => {
+  const schema = defineSchema({
+    messages: defineTable({ body: v.string() }),
+    users: defineTable({ name: v.string() }),
+  });
+
+  test("doc matches docValidator", () => {
+    const actual = schema.doc("messages");
+    const expected = docValidator("messages", schema.tables.messages);
+    expect(actual.json).toEqual(expected.json);
+    assert<Equals<typeof actual, typeof expected>>();
+  });
+
+  test("id is typed to the table", () => {
+    const actual = schema.id("users");
+    const expected = v.id("users");
+    expect(actual.json).toEqual(expected.json);
+    assert<Equals<typeof actual, typeof expected>>();
+  });
+
+  test("only accepts tables in the schema", () => {
+    // @ts-expect-error "nonexistent" is not a table in the schema.
+    expect(() => schema.doc("nonexistent")).toThrow("is not in this schema");
+    // @ts-expect-error "nonexistent" is not a table in the schema.
+    expect(() => schema.id("nonexistent")).toThrow("is not in this schema");
+  });
+});
+
 describe("GenericSchema assignability", () => {
   test("DataModelFromSchemaDefinition<GenericSchema> extends GenericDataModel", () => {
     type GenericDM = DataModelFromSchemaDefinition<

package/src/server/schema.ts

@@ -42,13 +42,20 @@ import {
   SystemIndexes,
 } from "../server/system_fields.js";
 import { Expand } from "../type_utils.js";
+import { GenericId } from "../values/index.js";
 import {
   GenericValidator,
   ObjectType,
   isValidator,
   v,
 } from "../values/validator.js";
-import { VObject, Validator } from "../values/validators.js";
+import {
+  VFloat64,
+  VId,
+  VObject,
+  VUnion,
+  Validator,
+} from "../values/validators.js";
 
 /**
  * Extract all of the index field paths within a {@link Validator}.
@@ -657,6 +664,121 @@ export function defineTable<
   }
 }
 
+/**
+ * The validators for the system fields Convex adds to every document.
+ *
+ * @public
+ */
+export type SystemFieldValidators<TableName extends string> = {
+  _id: VId<GenericId<TableName>>;
+  _creationTime: VFloat64<number>;
+};
+
+/**
+ * Add the system field validators to an object validator, leaving any other
+ * validator untouched.
+ */
+type WithSystemFieldValidators<
+  TableName extends string,
+  DocumentType extends Validator<any, any, any>,
+> =
+  DocumentType extends VObject<infer Type, infer Fields, any, any>
+    ? VObject<
+        Expand<IdField<TableName> & SystemFields & Type>,
+        Expand<SystemFieldValidators<TableName> & Fields>
+      >
+    : DocumentType;
+
+/**
+ * The validator for whole documents of a table: the table's own validator with
+ * the `_id` and `_creationTime` system fields added.
+ *
+ * For a table defined with a union, the system fields are added to each member
+ * of the union.
+ *
+ * @public
+ */
+export type DocValidator<
+  TableName extends string,
+  DocumentType extends Validator<any, any, any>,
+> =
+  DocumentType extends VUnion<any, infer Members, any, any>
+    ? {
+        [Index in keyof Members]: WithSystemFieldValidators<
+          TableName,
+          Members[Index]
+        >;
+      } extends infer NewMembers extends Validator<any, "required", any>[]
+      ? VUnion<
+          WithSystemFieldValidators<TableName, Members[number]>["type"],
+          NewMembers
+        >
+      : never
+    : WithSystemFieldValidators<TableName, DocumentType>;
+
+function addSystemFields(
+  tableName: string,
+  validator: GenericValidator,
+): GenericValidator {
+  switch (validator.kind) {
+    case "object":
+      return validator.extend({
+        _id: v.id(tableName),
+        _creationTime: v.number(),
+      });
+    case "union":
+      return v.union(
+        ...validator.members.map((member) =>
+          addSystemFields(tableName, member),
+        ),
+      );
+    // `v.any()` already permits the system fields.
+    case "any":
+      return validator;
+    default:
+      throw new Error(
+        `Invalid validator for table "${tableName}": a table's documents must be objects, or a union of objects (see https://docs.convex.dev/database/schemas)`,
+      );
+  }
+}
+
+/**
+ * Build the validator for whole documents of a table, by adding the `_id` and
+ * `_creationTime` system fields to the table's own validator.
+ *
+ * Prefer {@link SchemaDefinition.doc} when you have the schema in hand: it
+ * checks the table name against the schema.
+ *
+ * @example
+ * ```ts
+ * const messageDoc = docValidator("messages", schema.tables.messages);
+ *
+ * export const get = query({
+ *   args: { id: v.id("messages") },
+ *   returns: v.union(messageDoc, v.null()),
+ *   handler: (ctx, args) => ctx.db.get(args.id),
+ * });
+ * ```
+ *
+ * @param tableName - The name of the table, used for the `_id` validator.
+ * @param table - The {@link TableDefinition} for that table.
+ * @returns A validator matching documents of the table.
+ *
+ * @public
+ */
+export function docValidator<
+  TableName extends string,
+  Table extends TableDefinition<any, any, any, any>,
+>(
+  tableName: TableName,
+  table: Table,
+): DocValidator<TableName, Table["validator"]> {
+  return addSystemFields(tableName, table.validator) as DocValidator<
+    TableName,
+    Table["validator"]
+  >;
+}
+
 /**
  * A type describing the schema of a Convex project.
  *
@@ -666,6 +788,24 @@ export function defineTable<
  */
 export type GenericSchema = Record<string, TableDefinition>;
 
+function tableInSchema<
+  Schema extends GenericSchema,
+  TableName extends keyof Schema & string,
+>(
+  schema: SchemaDefinition<Schema, boolean>,
+  tableName: TableName,
+): Schema[TableName] {
+  const table = schema.tables[tableName];
+  if (table === undefined) {
+    throw new Error(
+      `Table "${tableName}" is not in this schema. Tables in this schema: ${Object.keys(
+        schema.tables,
+      ).join(", ")}`,
+    );
+  }
+  return table;
+}
+
 /**
  *
  * The definition of a Convex project schema.
@@ -690,6 +830,43 @@ export class SchemaDefinition<
       options?.schemaValidation === undefined ? true : options.schemaValidation;
   }
 
+  /**
+   * The validator for whole documents of a table in this schema: the table's
+   * own validator with the `_id` and `_creationTime` system fields added.
+   *
+   * @example
+   * ```ts
+   * export const get = query({
+   *   args: { id: schema.id("messages") },
+   *   returns: v.union(schema.doc("messages"), v.null()),
+   *   handler: (ctx, args) => ctx.db.get(args.id),
+   * });
+   * ```
+   *
+   * @param tableName - The name of a table in this schema.
+   * @returns A validator matching documents of that table.
+   */
+  doc<TableName extends keyof Schema & string>(
+    tableName: TableName,
+  ): DocValidator<TableName, Schema[TableName]["validator"]> {
+    return docValidator(tableName, tableInSchema(this, tableName));
+  }
+
+  /**
+   * The validator for IDs of a table in this schema.
+   *
+   * Same as `v.id(tableName)`, but only accepts tables in this schema.
+   *
+   * @param tableName - The name of a table in this schema.
+   * @returns A validator matching IDs of that table.
+   */
+  id<TableName extends keyof Schema & string>(
+    tableName: TableName,
+  ): VId<GenericId<TableName>> {
+    tableInSchema(this, tableName);
+    return v.id(tableName);
+  }
+
   /**
    * Export the contents of this definition.
    *