convex 1.42.3 → 1.43.0-alpha.1

package/src/server/cron.ts

@@ -1,6 +1,7 @@
 import { 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";
 
 type CronSchedule = {
@@ -15,13 +16,13 @@ export type IntervalSchedule =
 /** @public */
 export type HourlySchedule = {
   type: "hourly";
-  minuteUTC: number;
+  minuteUTC?: number;
 };
 /** @public */
 export type DailySchedule = {
   type: "daily";
   hourUTC: number;
-  minuteUTC: number;
+  minuteUTC?: number;
 };
 const DAYS_OF_WEEK = [
   "sunday",
@@ -38,14 +39,14 @@ export type WeeklySchedule = {
   type: "weekly";
   dayOfWeek: DayOfWeek;
   hourUTC: number;
-  minuteUTC: number;
+  minuteUTC?: number;
 };
 /** @public */
 export type MonthlySchedule = {
   type: "monthly";
   day: number;
   hourUTC: number;
-  minuteUTC: number;
+  minuteUTC?: number;
 };
 
 // Duplicating types so docstrings are visible in signatures:
@@ -85,9 +86,11 @@ export type Interval =
 /** @public */
 export type Hourly = {
   /**
-   * Minutes past the hour, 0-59.
+   * Minutes past the hour, 0-59. If omitted, Convex picks a minute for you
+   * and spreads runs across the hour so your job isn't tied to the busy top
+   * of the hour.
    */
-  minuteUTC: number;
+  minuteUTC?: number;
 };
 
 /** @public */
@@ -97,9 +100,10 @@ export type Daily = {
    */
   hourUTC: number;
   /**
-   * 0-59, minute of hour. Remember, this is UTC.
+   * 0-59, minute of hour. Remember, this is UTC. If omitted, Convex picks a
+   * minute for you and spreads runs across the hour.
    */
-  minuteUTC: number;
+  minuteUTC?: number;
 };
 
 /** @public */
@@ -114,8 +118,10 @@ export type Monthly = {
   hourUTC: number;
   /**
    * 0-59, minute of hour. Remember to convert from your own time zone to UTC.
+   * If omitted, Convex picks a minute for you and spreads runs across the
+   * hour.
    */
-  minuteUTC: number;
+  minuteUTC?: number;
 };
 /** @public */
 export type Weekly = {
@@ -129,8 +135,10 @@ export type Weekly = {
   hourUTC: number;
   /**
    * 0-59, minute of hour. Remember to convert from your own time zone to UTC.
+   * If omitted, Convex picks a minute for you and spreads runs across the
+   * hour.
    */
-  minuteUTC: number;
+  minuteUTC?: number;
 };
 
 /** @public */
@@ -220,6 +228,26 @@ function validatedMinuteOfHour(n: number) {
   return n;
 }
 
+// `minuteUTC` is optional: when omitted the backend picks a minute per job and
+// spreads runs across the hour. Only validate when a minute was provided.
+function validatedOptionalMinuteOfHour(n: number | undefined) {
+  return n === undefined ? undefined : validatedMinuteOfHour(n);
+}
+
+// `crons.hourly()` lets the schedule object be omitted entirely. Tell the two
+// 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 {
+  try {
+    getFunctionAddress(arg);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function validatedCronString(s: string) {
   return s;
 }
@@ -323,22 +351,49 @@ export class Crons {
    * ```
    *
    * @param cronIdentifier - A unique name for this scheduled job.
-   * @param schedule - What time (UTC) each day to run this function.
+   * @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 args - The arguments to the function.
    */
+  hourly<FuncRef extends SchedulableFunctionReference>(
+    cronIdentifier: string,
+    functionReference: FuncRef,
+    ...args: OptionalRestArgs<FuncRef>
+  ): void;
   hourly<FuncRef extends SchedulableFunctionReference>(
     cronIdentifier: string,
     schedule: Hourly,
     functionReference: FuncRef,
     ...args: OptionalRestArgs<FuncRef>
-  ) {
-    const minuteUTC = validatedMinuteOfHour(schedule.minuteUTC);
+  ): void;
+  hourly<FuncRef extends SchedulableFunctionReference>(
+    cronIdentifier: string,
+    scheduleOrFunctionReference: Hourly | FuncRef,
+    functionReferenceOrArg?: FuncRef | Record<string, Value>,
+    ...args: any[]
+  ): void {
+    // The schedule object may be omitted, so the second argument is either the
+    // function reference (no schedule) or the schedule.
+    if (isSchedulableFunctionReference(scheduleOrFunctionReference)) {
+      this.schedule(
+        cronIdentifier,
+        { type: "hourly" },
+        scheduleOrFunctionReference,
+        functionReferenceOrArg as Record<string, Value> | undefined,
+      );
+      return;
+    }
+    const minuteUTC = validatedOptionalMinuteOfHour(
+      scheduleOrFunctionReference.minuteUTC,
+    );
     this.schedule(
       cronIdentifier,
-      { minuteUTC, type: "hourly" },
-      functionReference,
+      minuteUTC === undefined
+        ? { type: "hourly" }
+        : { minuteUTC, type: "hourly" },
+      functionReferenceOrArg as FuncRef,
       ...args,
     );
   }
@@ -370,10 +425,12 @@ export class Crons {
     ...args: OptionalRestArgs<FuncRef>
   ) {
     const hourUTC = validatedHourOfDay(schedule.hourUTC);
-    const minuteUTC = validatedMinuteOfHour(schedule.minuteUTC);
+    const minuteUTC = validatedOptionalMinuteOfHour(schedule.minuteUTC);
     this.schedule(
       cronIdentifier,
-      { hourUTC, minuteUTC, type: "daily" },
+      minuteUTC === undefined
+        ? { hourUTC, type: "daily" }
+        : { hourUTC, minuteUTC, type: "daily" },
       functionReference,
       ...args,
     );
@@ -407,10 +464,12 @@ export class Crons {
   ) {
     const dayOfWeek = validatedDayOfWeek(schedule.dayOfWeek);
     const hourUTC = validatedHourOfDay(schedule.hourUTC);
-    const minuteUTC = validatedMinuteOfHour(schedule.minuteUTC);
+    const minuteUTC = validatedOptionalMinuteOfHour(schedule.minuteUTC);
     this.schedule(
       cronIdentifier,
-      { dayOfWeek, hourUTC, minuteUTC, type: "weekly" },
+      minuteUTC === undefined
+        ? { dayOfWeek, hourUTC, type: "weekly" }
+        : { dayOfWeek, hourUTC, minuteUTC, type: "weekly" },
       functionReference,
       ...args,
     );
@@ -448,10 +507,12 @@ export class Crons {
   ) {
     const day = validatedDayOfMonth(schedule.day);
     const hourUTC = validatedHourOfDay(schedule.hourUTC);
-    const minuteUTC = validatedMinuteOfHour(schedule.minuteUTC);
+    const minuteUTC = validatedOptionalMinuteOfHour(schedule.minuteUTC);
     this.schedule(
       cronIdentifier,
-      { day, hourUTC, minuteUTC, type: "monthly" },
+      minuteUTC === undefined
+        ? { day, hourUTC, type: "monthly" }
+        : { day, hourUTC, minuteUTC, type: "monthly" },
       functionReference,
       ...args,
     );

package/src/server/database.ts

@@ -1,4 +1,5 @@
 import { GenericId } from "../values/index.js";
+import { CommitTsPlaceholder } from "../values/value.js";
 import {
   DocumentByName,
   GenericDataModel,
@@ -370,6 +371,20 @@ export interface GenericDatabaseWriter<
    * @param id - The {@link values.GenericId} of the document to remove.
    */
   delete(id: GenericId<TableNamesInDataModel<DataModel>>): Promise<void>;
+
+  /**
+   * Values that are not known until the mutation commits.
+   */
+  vars: {
+    /**
+     * The placeholder for the transaction's commit timestamp. Written into a
+     * document field via `db.insert`, it resolves at commit to an int64
+     * (`bigint`) ordered by commit order. Within the writing mutation,
+     * reading the field back yields the placeholder, which cannot be used as
+     * a number.
+     */
+    commitTs: CommitTsPlaceholder;
+  };
 }
 
 /**

package/src/server/impl/database_impl.ts

@@ -15,7 +15,7 @@ import { QueryInitializerImpl } from "./query_impl.js";
 import { GenericDataModel, GenericDocument } from "../data_model.js";
 import { validateArg } from "./validate.js";
 import { version } from "../../index.js";
-import { patchValueToJson } from "../../values/value.js";
+import { commitTsPlaceholder, patchValueToJson } from "../../values/value.js";
 
 async function get(
   table: string | undefined,
@@ -164,6 +164,9 @@ export function setupWriter(): GenericDatabaseWriter<GenericDataModel> &
     table: (tableName) => {
       return new TableWriter(tableName, false);
     },
+    vars: {
+      commitTs: commitTsPlaceholder,
+    },
   };
 }
 

package/src/server/log.ts

@@ -1,5 +1,5 @@
 import { audit } from "./audit_logging.js";
-import { vars } from "./logVars.js";
+import { internalVars, vars } from "./logVars.js";
 
 // Type annotations are needed for the `unique symbol` types in `vars` to typecheck correctly
 interface Log {
@@ -26,9 +26,12 @@ interface Log {
    */
   audit: typeof audit;
   vars: typeof vars;
+  /** @internal */
+  internalVars: typeof internalVars;
 }
 
 export const log: Log = {
   audit,
   vars,
+  internalVars,
 };

package/src/server/logVars.ts

@@ -2,18 +2,21 @@ const REQUEST_ID = Symbol("var.requestId");
 const IP = Symbol("var.ip");
 const USER_AGENT = Symbol("var.userAgent");
 const NOW = Symbol("var.now");
+const CONVEX_ACTOR = Symbol("var.convexActor");
 
 export type LogVar =
   | typeof REQUEST_ID
   | typeof IP
   | typeof USER_AGENT
-  | typeof NOW;
+  | typeof NOW
+  | typeof CONVEX_ACTOR;
 
 export const varNames: Record<symbol, string> = {
   [REQUEST_ID]: "requestId",
   [IP]: "ip",
   [USER_AGENT]: "userAgent",
   [NOW]: "now",
+  [CONVEX_ACTOR]: "convexActor",
 };
 
 export const vars = {
@@ -29,3 +32,16 @@ export const vars = {
    */
   now: NOW,
 } as const;
+
+/**
+ * Internal-only log vars, surfaced via `log.internalVars`. These are kept out
+ * of the public `log.vars` surface.
+ */
+export const internalVars = {
+  /**
+   * If the function was invoked using admin auth (either directly or while
+   * acting as an end user, e.g. from the dashboard), resolved to information
+   * about the admin. Otherwise, resolved to `null`.
+   */
+  convexActor: CONVEX_ACTOR,
+} as const;

package/src/server/schema.test.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
-import { GenericId } from "../values/index.js";
+import { CommitTsPlaceholder, GenericId } from "../values/index.js";
 import { describe, expect, test } from "vitest";
 import { assert, Equals } from "../test/type_testing.js";
 import { SystemIndexes } from "./system_fields.js";
@@ -27,6 +27,7 @@ describe("DataModelFromSchemaDefinition", () => {
         number: v.number(),
         float64: v.float64(),
         int64: v.int64(),
+        commitTs: v.commitTs(),
         boolean: v.boolean(),
         string: v.string(),
         bytes: v.bytes(),
@@ -43,6 +44,7 @@ describe("DataModelFromSchemaDefinition", () => {
       number: number;
       float64: number;
       int64: bigint;
+      commitTs: bigint | CommitTsPlaceholder;
       boolean: boolean;
       string: string;
       array: boolean[];
@@ -57,6 +59,7 @@ describe("DataModelFromSchemaDefinition", () => {
       | "number"
       | "float64"
       | "int64"
+      | "commitTs"
       | "boolean"
       | "string"
       | "bytes"
@@ -743,6 +746,7 @@ describe("JsonTypesFromSchema", () => {
       numberField: v.number(),
       float64Field: v.float64(),
       int64Field: v.int64(),
+      commitTsField: v.commitTs(),
       booleanField: v.boolean(),
       stringField: v.string(),
       bytesField: v.bytes(),
@@ -766,6 +770,7 @@ describe("JsonTypesFromSchema", () => {
         numberField: { fieldType: { type: "number" }, optional: false },
         float64Field: { fieldType: { type: "number" }, optional: false },
         int64Field: { fieldType: { type: "bigint" }, optional: false },
+        commitTsField: { fieldType: { type: "commitTs" }, optional: false },
         booleanField: { fieldType: { type: "boolean" }, optional: false },
         stringField: { fieldType: { type: "string" }, optional: false },
         bytesField: { fieldType: { type: "bytes" }, optional: false },

package/src/values/compare.ts

@@ -1,4 +1,4 @@
-import { Value } from "./value.js";
+import { CommitTsPlaceholder, MAX_INT64, Value } from "./value.js";
 import { compareUTF8 } from "./compare_utf8.js";
 
 export function compareValues(k1: Value | undefined, k2: Value | undefined) {
@@ -122,6 +122,9 @@ function makeComparable(v: Value | undefined): [number, any] {
   if (typeof v === "bigint") {
     return [2, v];
   }
+  if (v instanceof CommitTsPlaceholder) {
+    return [2, MAX_INT64];
+  }
   if (typeof v === "number") {
     return [3, v];
   }
@@ -140,5 +143,5 @@ function makeComparable(v: Value | undefined): [number, any] {
   // Otherwise, it's an POJO.
   const keys = Object.keys(v).sort();
   const pojo: Value[] = keys.map((k) => [k, v[k]!]);
-  return [8, pojo.map(makeComparable)];
+  return [9, pojo.map(makeComparable)];
 }

package/src/values/index.ts

@@ -6,7 +6,7 @@
  * @module
  */
 
-export { convexToJson, jsonToConvex } from "./value.js";
+export { convexToJson, jsonToConvex, CommitTsPlaceholder } from "./value.js";
 export type {
   Id as GenericId,
   JSONValue,
@@ -30,6 +30,7 @@ export type {
   VId,
   VFloat64,
   VInt64,
+  VCommitTs,
   VBoolean,
   VBytes,
   VString,

package/src/values/size.test.ts

@@ -5,6 +5,7 @@ import {
   SYSTEM_FIELD_CREATION_TIME_SIZE,
   SYSTEM_FIELD_ID_ESTIMATE,
 } from "./size.js";
+import { commitTsPlaceholder } from "./value.js";
 
 /**
  * Tests for getConvexSize JS-specific behavior.
@@ -16,6 +17,10 @@ describe("getConvexSize", () => {
     expect(getConvexSize(undefined)).toBe(0);
   });
 
+  test("commit timestamp placeholder sized as resolved Int64", () => {
+    expect(getConvexSize(commitTsPlaceholder)).toBe(9);
+  });
+
   test("long strings use TextEncoder path (>500 chars)", () => {
     // This tests the JS-specific optimization for long strings
     const longAscii = "a".repeat(1000);

package/src/values/size.ts

@@ -23,7 +23,7 @@
  * @module
  */
 
-import type { Value } from "./value.js";
+import { CommitTsPlaceholder, type Value } from "./value.js";
 import { isSimpleObject } from "../common/index.js";
 
 /**
@@ -51,6 +51,10 @@ export function getConvexSize(value: Value | undefined): number {
     // Int64: 1 byte type marker + 8 bytes value
     return 9;
   }
+  if (value instanceof CommitTsPlaceholder) {
+    // Same as bigint
+    return 9;
+  }
   if (typeof value === "number") {
     // Float64: 1 byte type marker + 8 bytes value
     return 9;

package/src/values/validator.test.ts

@@ -1,4 +1,4 @@
-import { GenericId } from "../values/index.js";
+import { CommitTsPlaceholder, GenericId } from "../values/index.js";
 import { describe, test, expect } from "vitest";
 import { assert, Equals } from "../test/type_testing.js";
 import { v, Infer } from "../values/validator.js";
@@ -56,6 +56,21 @@ describe("Validators", () => {
     >();
   });
 
+  test("commitTs validator", () => {
+    const commitTs = v.commitTs();
+    expect(commitTs.kind).toEqual("commitTs");
+    expect(commitTs.json).toEqual({ type: "commitTs" });
+    assert<Equals<Infer<typeof commitTs>, bigint | CommitTsPlaceholder>>();
+
+    const _optionalCommitTs = v.optional(v.commitTs());
+    assert<
+      Equals<
+        Infer<typeof _optionalCommitTs>,
+        bigint | CommitTsPlaceholder | undefined
+      >
+    >();
+  });
+
   test("Most validators don't accept optional validators as children", () => {
     const optional = v.optional(v.string());
     const required = v.string();

package/src/values/validator.ts

@@ -8,6 +8,7 @@ import {
   VBytes,
   VFloat64,
   VId,
+  VCommitTs,
   VInt64,
   VLiteral,
   VNull,
@@ -206,6 +207,18 @@ export const v = {
     return new VInt64({ isOptional: "required" });
   },
 
+  /**
+   * Validates that the value is a commit timestamp: an int64 (`bigint`)
+   * assigned from the transaction's commit timestamp.
+   *
+   * An index on a field with this validator orders documents by commit order.
+   * Accepts any int64 value; write `db.vars.commitTs` to have the field
+   * resolve to the commit timestamp when the mutation commits.
+   */
+  commitTs: () => {
+    return new VCommitTs({ isOptional: "required" });
+  },
+
   /**
    * Validates that the value is a `boolean`.
    */

package/src/values/validators.ts

@@ -1,7 +1,7 @@
 import { Expand } from "../type_utils.js";
 import { GenericId } from "./index.js";
 import { GenericValidator, ObjectType } from "./validator.js";
-import { JSONValue, convexToJson } from "./value.js";
+import { CommitTsPlaceholder, JSONValue, convexToJson } from "./value.js";
 
 type TableNameFromType<T> =
   T extends GenericId<infer TableName> ? TableName : string;
@@ -155,6 +155,30 @@ export class VInt64<
   }
 }
 
+/**
+ * The type of the `v.commitTs()` validator.
+ */
+export class VCommitTs<
+  Type = bigint | CommitTsPlaceholder,
+  IsOptional extends OptionalProperty = "required",
+> extends BaseValidator<Type, IsOptional> {
+  /**
+   * The kind of validator, `"commitTs"`.
+   */
+  readonly kind = "commitTs" as const;
+
+  /** @internal */
+  get json(): ValidatorJSON {
+    return { type: this.kind };
+  }
+  /** @internal */
+  asOptional() {
+    return new VCommitTs<Type | undefined, "optional">({
+      isOptional: "optional",
+    });
+  }
+}
+
 /**
  * The type of the `v.boolean()` validator.
  */
@@ -653,6 +677,8 @@ export type VOptional<T extends Validator<any, OptionalProperty, any>> =
     ? VFloat64<Type | undefined, "optional">
   : T extends VInt64<infer Type, OptionalProperty>
     ? VInt64<Type | undefined, "optional">
+  : T extends VCommitTs<infer Type, OptionalProperty>
+    ? VCommitTs<Type | undefined, "optional">
   : T extends VBoolean<infer Type, OptionalProperty>
     ? VBoolean<Type | undefined, "optional">
   : T extends VNull<infer Type, OptionalProperty>
@@ -712,6 +738,7 @@ export type Validator<
   | VString<Type, IsOptional>
   | VFloat64<Type, IsOptional>
   | VInt64<Type, IsOptional>
+  | VCommitTs<Type, IsOptional>
   | VBoolean<Type, IsOptional>
   | VNull<Type, IsOptional>
   | VAny<Type, IsOptional>
@@ -750,6 +777,7 @@ export type ValidatorJSON =
   | { type: "null" }
   | { type: "number" }
   | { type: "bigint" }
+  | { type: "commitTs" }
   | { type: "boolean" }
   | { type: "string" }
   | { type: "bytes" }

package/src/values/value.test.ts

@@ -8,6 +8,7 @@ import {
   modernBigIntToBase64,
   convexToJson,
   jsonToConvex,
+  commitTsPlaceholder,
 } from "./value.js";
 import { compareValues } from "./compare.js";
 
@@ -88,6 +89,36 @@ describe("jsonToConvex", () => {
   });
 });
 
+describe("commit timestamp sentinel", () => {
+  test("round trips through JSON as the singleton", () => {
+    const decoded = jsonToConvex({ property: { $commitTs: null } }) as any;
+    expect(decoded.property).toBe(commitTsPlaceholder);
+    expect(convexToJson({ property: commitTsPlaceholder as any })).toEqual({
+      property: { $commitTs: null },
+    });
+  });
+
+  test("rejects malformed tokens", () => {
+    expect(() => jsonToConvex({ $commitTs: 1 } as any)).toThrow(
+      /Malformed \$commitTs/,
+    );
+    // A `$commitTs` key alongside other fields is not the token; it's an
+    // invalid field name.
+    expect(() => jsonToConvex({ $commitTs: null, x: 1 })).toThrow(/reserved/);
+  });
+
+  test("throws on coercion", () => {
+    expect(() => Number(commitTsPlaceholder)).toThrow(/unresolved/);
+    expect(() => (commitTsPlaceholder as any) + 1n).toThrow(/unresolved/);
+    expect(() => JSON.stringify({ commitTs: commitTsPlaceholder })).toThrow(
+      /unresolved/,
+    );
+    expect(`${commitTsPlaceholder as any}`).toEqual(
+      "[unresolved commit timestamp]",
+    );
+  });
+});
+
 describe("bigints in Safari 14", () => {
   test("roundtrips BigInt even in Safari 14", () => {
     // https://caniuse.com/mdn-javascript_builtins_dataview_setbigint64
@@ -194,4 +225,8 @@ describe("compare", () => {
       }
     }
   });
+
+  test("commit timestamp placeholders compare equal", () => {
+    expect(compareValues(commitTsPlaceholder, commitTsPlaceholder)).toEqual(0);
+  });
 });