convex 1.42.2 → 1.43.0-alpha.0

package/dist/cjs/server/cron.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/server/cron.ts"],
-  "sourcesContent": ["import { getFunctionName, OptionalRestArgs } from \"../server/api.js\";\nimport { parseArgs } from \"../common/index.js\";\nimport { convexToJson, JSONValue, Value } from \"../values/index.js\";\nimport { SchedulableFunctionReference } from \"./scheduler.js\";\n\ntype CronSchedule = {\n  type: \"cron\";\n  cron: string;\n};\n/** @public */\nexport type IntervalSchedule =\n  | { type: \"interval\"; seconds: number }\n  | { type: \"interval\"; minutes: number }\n  | { type: \"interval\"; hours: number };\n/** @public */\nexport type HourlySchedule = {\n  type: \"hourly\";\n  minuteUTC: number;\n};\n/** @public */\nexport type DailySchedule = {\n  type: \"daily\";\n  hourUTC: number;\n  minuteUTC: number;\n};\nconst DAYS_OF_WEEK = [\n  \"sunday\",\n  \"monday\",\n  \"tuesday\",\n  \"wednesday\",\n  \"thursday\",\n  \"friday\",\n  \"saturday\",\n] as const;\ntype DayOfWeek = (typeof DAYS_OF_WEEK)[number];\n/** @public */\nexport type WeeklySchedule = {\n  type: \"weekly\";\n  dayOfWeek: DayOfWeek;\n  hourUTC: number;\n  minuteUTC: number;\n};\n/** @public */\nexport type MonthlySchedule = {\n  type: \"monthly\";\n  day: number;\n  hourUTC: number;\n  minuteUTC: number;\n};\n\n// Duplicating types so docstrings are visible in signatures:\n// `Expand<Omit<MonthlySchedule, \"type\">>` doesn't preserve docstrings.\n// When we get to TypeScript 4.9, `satisfies` would go nicely here.\n\n/** @public */\nexport type Interval =\n  | {\n      /**\n       * Run a job every `seconds` seconds, beginning\n       * when the job is first deployed to Convex.\n       */\n      seconds: number;\n      minutes?: undefined;\n      hours?: undefined;\n    }\n  | {\n      /**\n       * Run a job every `minutes` minutes, beginning\n       * when the job is first deployed to Convex.\n       */\n      minutes: number;\n      seconds?: undefined;\n      hours?: undefined;\n    }\n  | {\n      /**\n       * Run a job every `hours` hours, beginning when\n       * when the job is first deployed to Convex.\n       */\n      hours: number;\n      seconds?: undefined;\n      minutes?: undefined;\n    };\n\n/** @public */\nexport type Hourly = {\n  /**\n   * Minutes past the hour, 0-59.\n   */\n  minuteUTC: number;\n};\n\n/** @public */\nexport type Daily = {\n  /**\n   * 0-23, hour of day. Remember, this is UTC.\n   */\n  hourUTC: number;\n  /**\n   * 0-59, minute of hour. Remember, this is UTC.\n   */\n  minuteUTC: number;\n};\n\n/** @public */\nexport type Monthly = {\n  /**\n   * 1-31, day of month. Days greater that 28 will not run every month.\n   */\n  day: number;\n  /**\n   * 0-23, hour of day. Remember to convert from your own time zone to UTC.\n   */\n  hourUTC: number;\n  /**\n   * 0-59, minute of hour. Remember to convert from your own time zone to UTC.\n   */\n  minuteUTC: number;\n};\n/** @public */\nexport type Weekly = {\n  /**\n   * \"monday\", \"tuesday\", etc.\n   */\n  dayOfWeek: DayOfWeek;\n  /**\n   * 0-23, hour of day. Remember to convert from your own time zone to UTC.\n   */\n  hourUTC: number;\n  /**\n   * 0-59, minute of hour. Remember to convert from your own time zone to UTC.\n   */\n  minuteUTC: number;\n};\n\n/** @public */\nexport type Schedule =\n  | CronSchedule\n  | IntervalSchedule\n  | HourlySchedule\n  | DailySchedule\n  | WeeklySchedule\n  | MonthlySchedule;\n\n/**\n * A schedule to run a Convex mutation or action on.\n * You can schedule Convex functions to run regularly with\n * {@link interval} and exporting it.\n *\n * @public\n **/\nexport interface CronJob {\n  name: string;\n  args: JSONValue;\n  schedule: Schedule;\n}\n\n/**\n * Create a CronJobs object to schedule recurring tasks.\n *\n * ```js\n * // convex/crons.js\n * import { cronJobs } from 'convex/server';\n * import { api } from \"./_generated/api\";\n *\n * const crons = cronJobs();\n * crons.weekly(\n *   \"weekly re-engagement email\",\n *   {\n *     hourUTC: 17, // (9:30am Pacific/10:30am Daylight Savings Pacific)\n *     minuteUTC: 30,\n *   },\n *   api.emails.send\n * )\n * export default crons;\n * ```\n *\n * @public\n */\nexport const cronJobs = () => new Crons();\n\n/**\n * @public\n *\n * This is a cron string. They're complicated!\n */\ntype CronString = string;\n\nfunction validateIntervalNumber(n: number) {\n  if (!Number.isInteger(n) || n <= 0) {\n    throw new Error(\"Interval must be an integer greater than 0\");\n  }\n}\n\nfunction validatedDayOfMonth(n: number) {\n  if (!Number.isInteger(n) || n < 1 || n > 31) {\n    throw new Error(\"Day of month must be an integer from 1 to 31\");\n  }\n  return n;\n}\n\nfunction validatedDayOfWeek(s: string) {\n  if (!DAYS_OF_WEEK.includes(s as DayOfWeek)) {\n    throw new Error('Day of week must be a string like \"monday\".');\n  }\n  return s as DayOfWeek;\n}\n\nfunction validatedHourOfDay(n: number) {\n  if (!Number.isInteger(n) || n < 0 || n > 23) {\n    throw new Error(\"Hour of day must be an integer from 0 to 23\");\n  }\n  return n;\n}\n\nfunction validatedMinuteOfHour(n: number) {\n  if (!Number.isInteger(n) || n < 0 || n > 59) {\n    throw new Error(\"Minute of hour must be an integer from 0 to 59\");\n  }\n  return n;\n}\n\nfunction validatedCronString(s: string) {\n  return s;\n}\n\nfunction validatedCronIdentifier(s: string) {\n  if (!s.match(/^[ -~]*$/)) {\n    throw new Error(\n      `Invalid cron identifier ${s}: use ASCII letters that are not control characters`,\n    );\n  }\n  return s;\n}\n\n/**\n * A class for scheduling cron jobs.\n *\n * To learn more see the documentation at https://docs.convex.dev/scheduling/cron-jobs\n *\n * @public\n */\nexport class Crons {\n  crons: Record<string, CronJob>;\n  isCrons: true;\n  constructor() {\n    this.isCrons = true;\n    this.crons = {};\n  }\n\n  /** @internal */\n  schedule(\n    cronIdentifier: string,\n    schedule: Schedule,\n    functionReference: SchedulableFunctionReference,\n    args?: Record<string, Value>,\n  ) {\n    const cronArgs = parseArgs(args);\n    validatedCronIdentifier(cronIdentifier);\n    if (cronIdentifier in this.crons) {\n      throw new Error(`Cron identifier registered twice: ${cronIdentifier}`);\n    }\n    this.crons[cronIdentifier] = {\n      name: getFunctionName(functionReference),\n      args: [convexToJson(cronArgs)],\n      schedule: schedule,\n    };\n  }\n\n  /**\n   * Schedule a mutation or action to run at some interval.\n   *\n   * ```js\n   * crons.interval(\"Clear presence data\", {seconds: 30}, api.presence.clear);\n   * ```\n   *\n   * @param identifier - A unique name for this scheduled job.\n   * @param schedule - The time between runs for this scheduled job.\n   * @param functionReference - A {@link FunctionReference} for the function\n   * to schedule.\n   * @param args - The arguments to the function.\n   */\n  interval<FuncRef extends SchedulableFunctionReference>(\n    cronIdentifier: string,\n    schedule: Interval,\n    functionReference: FuncRef,\n    ...args: OptionalRestArgs<FuncRef>\n  ) {\n    const s = schedule;\n    const hasSeconds = +(\"seconds\" in s && s.seconds !== undefined);\n    const hasMinutes = +(\"minutes\" in s && s.minutes !== undefined);\n    const hasHours = +(\"hours\" in s && s.hours !== undefined);\n    const total = hasSeconds + hasMinutes + hasHours;\n    if (total !== 1) {\n      throw new Error(\"Must specify one of seconds, minutes, or hours\");\n    }\n    if (hasSeconds) {\n      validateIntervalNumber(schedule.seconds!);\n    } else if (hasMinutes) {\n      validateIntervalNumber(schedule.minutes!);\n    } else if (hasHours) {\n      validateIntervalNumber(schedule.hours!);\n    }\n    this.schedule(\n      cronIdentifier,\n      { ...schedule, type: \"interval\" },\n      functionReference,\n      ...args,\n    );\n  }\n\n  /**\n   * Schedule a mutation or action to run on an hourly basis.\n   *\n   * ```js\n   * crons.hourly(\n   *   \"Reset high scores\",\n   *   {\n   *     minuteUTC: 30,\n   *   },\n   *   api.scores.reset\n   * )\n   * ```\n   *\n   * @param cronIdentifier - A unique name for this scheduled job.\n   * @param schedule - What time (UTC) each day to run this function.\n   * @param functionReference - A {@link FunctionReference} for the function\n   * to schedule.\n   * @param args - The arguments to the function.\n   */\n  hourly<FuncRef extends SchedulableFunctionReference>(\n    cronIdentifier: string,\n    schedule: Hourly,\n    functionReference: FuncRef,\n    ...args: OptionalRestArgs<FuncRef>\n  ) {\n    const minuteUTC = validatedMinuteOfHour(schedule.minuteUTC);\n    this.schedule(\n      cronIdentifier,\n      { minuteUTC, type: \"hourly\" },\n      functionReference,\n      ...args,\n    );\n  }\n\n  /**\n   * Schedule a mutation or action to run on a daily basis.\n   *\n   * ```js\n   * crons.daily(\n   *   \"Reset high scores\",\n   *   {\n   *     hourUTC: 17, // (9:30am Pacific/10:30am Daylight Savings Pacific)\n   *     minuteUTC: 30,\n   *   },\n   *   api.scores.reset\n   * )\n   * ```\n   *\n   * @param cronIdentifier - A unique name for this scheduled job.\n   * @param schedule - What time (UTC) each day to run this function.\n   * @param functionReference - A {@link FunctionReference} for the function\n   * to schedule.\n   * @param args - The arguments to the function.\n   */\n  daily<FuncRef extends SchedulableFunctionReference>(\n    cronIdentifier: string,\n    schedule: Daily,\n    functionReference: FuncRef,\n    ...args: OptionalRestArgs<FuncRef>\n  ) {\n    const hourUTC = validatedHourOfDay(schedule.hourUTC);\n    const minuteUTC = validatedMinuteOfHour(schedule.minuteUTC);\n    this.schedule(\n      cronIdentifier,\n      { hourUTC, minuteUTC, type: \"daily\" },\n      functionReference,\n      ...args,\n    );\n  }\n\n  /**\n   * Schedule a mutation or action to run on a weekly basis.\n   *\n   * ```js\n   * crons.weekly(\n   *   \"Weekly re-engagement email\",\n   *   {\n   *     dayOfWeek: \"Tuesday\",\n   *     hourUTC: 17, // (9:30am Pacific/10:30am Daylight Savings Pacific)\n   *     minuteUTC: 30,\n   *   },\n   *   api.emails.send\n   * )\n   * ```\n   *\n   * @param cronIdentifier - A unique name for this scheduled job.\n   * @param schedule - What day and time (UTC) each week to run this function.\n   * @param functionReference - A {@link FunctionReference} for the function\n   * to schedule.\n   */\n  weekly<FuncRef extends SchedulableFunctionReference>(\n    cronIdentifier: string,\n    schedule: Weekly,\n    functionReference: FuncRef,\n    ...args: OptionalRestArgs<FuncRef>\n  ) {\n    const dayOfWeek = validatedDayOfWeek(schedule.dayOfWeek);\n    const hourUTC = validatedHourOfDay(schedule.hourUTC);\n    const minuteUTC = validatedMinuteOfHour(schedule.minuteUTC);\n    this.schedule(\n      cronIdentifier,\n      { dayOfWeek, hourUTC, minuteUTC, type: \"weekly\" },\n      functionReference,\n      ...args,\n    );\n  }\n\n  /**\n   * Schedule a mutation or action to run on a monthly basis.\n   *\n   * Note that some months have fewer days than others, so e.g. a function\n   * scheduled to run on the 30th will not run in February.\n   *\n   * ```js\n   * crons.monthly(\n   *   \"Bill customers at \",\n   *   {\n   *     hourUTC: 17, // (9:30am Pacific/10:30am Daylight Savings Pacific)\n   *     minuteUTC: 30,\n   *     day: 1,\n   *   },\n   *   api.billing.billCustomers\n   * )\n   * ```\n   *\n   * @param cronIdentifier - A unique name for this scheduled job.\n   * @param schedule - What day and time (UTC) each month to run this function.\n   * @param functionReference - A {@link FunctionReference} for the function\n   * to schedule.\n   * @param args - The arguments to the function.\n   */\n  monthly<FuncRef extends SchedulableFunctionReference>(\n    cronIdentifier: string,\n    schedule: Monthly,\n    functionReference: FuncRef,\n    ...args: OptionalRestArgs<FuncRef>\n  ) {\n    const day = validatedDayOfMonth(schedule.day);\n    const hourUTC = validatedHourOfDay(schedule.hourUTC);\n    const minuteUTC = validatedMinuteOfHour(schedule.minuteUTC);\n    this.schedule(\n      cronIdentifier,\n      { day, hourUTC, minuteUTC, type: \"monthly\" },\n      functionReference,\n      ...args,\n    );\n  }\n\n  /**\n   * Schedule a mutation or action to run on a recurring basis.\n   *\n   * Like the unix command `cron`, Sunday is 0, Monday is 1, etc.\n   *\n   * ```\n   *  \u250C\u2500 minute (0 - 59)\n   *  \u2502 \u250C\u2500 hour (0 - 23)\n   *  \u2502 \u2502 \u250C\u2500 day of the month (1 - 31)\n   *  \u2502 \u2502 \u2502 \u250C\u2500 month (1 - 12)\n   *  \u2502 \u2502 \u2502 \u2502 \u250C\u2500 day of the week (0 - 6) (Sunday to Saturday)\n   * \"* * * * *\"\n   * ```\n   *\n   * @param cronIdentifier - A unique name for this scheduled job.\n   * @param cron - Cron string like `\"15 7 * * *\"` (Every day at 7:15 UTC)\n   * @param functionReference - A {@link FunctionReference} for the function\n   * to schedule.\n   * @param args - The arguments to the function.\n   */\n  cron<FuncRef extends SchedulableFunctionReference>(\n    cronIdentifier: string,\n    cron: CronString,\n    functionReference: FuncRef,\n    ...args: OptionalRestArgs<FuncRef>\n  ) {\n    const c = validatedCronString(cron);\n    this.schedule(\n      cronIdentifier,\n      { cron: c, type: \"cron\" },\n      functionReference,\n      ...args,\n    );\n  }\n\n  /** @internal */\n  export() {\n    return JSON.stringify(this.crons);\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import { getFunctionName, OptionalRestArgs } from \"../server/api.js\";\nimport { parseArgs } from \"../common/index.js\";\nimport { convexToJson, JSONValue, Value } from \"../values/index.js\";\nimport { getFunctionAddress } from \"./components/paths.js\";\nimport { SchedulableFunctionReference } from \"./scheduler.js\";\n\ntype CronSchedule = {\n  type: \"cron\";\n  cron: string;\n};\n/** @public */\nexport type IntervalSchedule =\n  | { type: \"interval\"; seconds: number }\n  | { type: \"interval\"; minutes: number }\n  | { type: \"interval\"; hours: number };\n/** @public */\nexport type HourlySchedule = {\n  type: \"hourly\";\n  minuteUTC?: number;\n};\n/** @public */\nexport type DailySchedule = {\n  type: \"daily\";\n  hourUTC: number;\n  minuteUTC?: number;\n};\nconst DAYS_OF_WEEK = [\n  \"sunday\",\n  \"monday\",\n  \"tuesday\",\n  \"wednesday\",\n  \"thursday\",\n  \"friday\",\n  \"saturday\",\n] as const;\ntype DayOfWeek = (typeof DAYS_OF_WEEK)[number];\n/** @public */\nexport type WeeklySchedule = {\n  type: \"weekly\";\n  dayOfWeek: DayOfWeek;\n  hourUTC: number;\n  minuteUTC?: number;\n};\n/** @public */\nexport type MonthlySchedule = {\n  type: \"monthly\";\n  day: number;\n  hourUTC: number;\n  minuteUTC?: number;\n};\n\n// Duplicating types so docstrings are visible in signatures:\n// `Expand<Omit<MonthlySchedule, \"type\">>` doesn't preserve docstrings.\n// When we get to TypeScript 4.9, `satisfies` would go nicely here.\n\n/** @public */\nexport type Interval =\n  | {\n      /**\n       * Run a job every `seconds` seconds, beginning\n       * when the job is first deployed to Convex.\n       */\n      seconds: number;\n      minutes?: undefined;\n      hours?: undefined;\n    }\n  | {\n      /**\n       * Run a job every `minutes` minutes, beginning\n       * when the job is first deployed to Convex.\n       */\n      minutes: number;\n      seconds?: undefined;\n      hours?: undefined;\n    }\n  | {\n      /**\n       * Run a job every `hours` hours, beginning when\n       * when the job is first deployed to Convex.\n       */\n      hours: number;\n      seconds?: undefined;\n      minutes?: undefined;\n    };\n\n/** @public */\nexport type Hourly = {\n  /**\n   * Minutes past the hour, 0-59. If omitted, Convex picks a minute for you\n   * and spreads runs across the hour so your job isn't tied to the busy top\n   * of the hour.\n   */\n  minuteUTC?: number;\n};\n\n/** @public */\nexport type Daily = {\n  /**\n   * 0-23, hour of day. Remember, this is UTC.\n   */\n  hourUTC: number;\n  /**\n   * 0-59, minute of hour. Remember, this is UTC. If omitted, Convex picks a\n   * minute for you and spreads runs across the hour.\n   */\n  minuteUTC?: number;\n};\n\n/** @public */\nexport type Monthly = {\n  /**\n   * 1-31, day of month. Days greater that 28 will not run every month.\n   */\n  day: number;\n  /**\n   * 0-23, hour of day. Remember to convert from your own time zone to UTC.\n   */\n  hourUTC: number;\n  /**\n   * 0-59, minute of hour. Remember to convert from your own time zone to UTC.\n   * If omitted, Convex picks a minute for you and spreads runs across the\n   * hour.\n   */\n  minuteUTC?: number;\n};\n/** @public */\nexport type Weekly = {\n  /**\n   * \"monday\", \"tuesday\", etc.\n   */\n  dayOfWeek: DayOfWeek;\n  /**\n   * 0-23, hour of day. Remember to convert from your own time zone to UTC.\n   */\n  hourUTC: number;\n  /**\n   * 0-59, minute of hour. Remember to convert from your own time zone to UTC.\n   * If omitted, Convex picks a minute for you and spreads runs across the\n   * hour.\n   */\n  minuteUTC?: number;\n};\n\n/** @public */\nexport type Schedule =\n  | CronSchedule\n  | IntervalSchedule\n  | HourlySchedule\n  | DailySchedule\n  | WeeklySchedule\n  | MonthlySchedule;\n\n/**\n * A schedule to run a Convex mutation or action on.\n * You can schedule Convex functions to run regularly with\n * {@link interval} and exporting it.\n *\n * @public\n **/\nexport interface CronJob {\n  name: string;\n  args: JSONValue;\n  schedule: Schedule;\n}\n\n/**\n * Create a CronJobs object to schedule recurring tasks.\n *\n * ```js\n * // convex/crons.js\n * import { cronJobs } from 'convex/server';\n * import { api } from \"./_generated/api\";\n *\n * const crons = cronJobs();\n * crons.weekly(\n *   \"weekly re-engagement email\",\n *   {\n *     hourUTC: 17, // (9:30am Pacific/10:30am Daylight Savings Pacific)\n *     minuteUTC: 30,\n *   },\n *   api.emails.send\n * )\n * export default crons;\n * ```\n *\n * @public\n */\nexport const cronJobs = () => new Crons();\n\n/**\n * @public\n *\n * This is a cron string. They're complicated!\n */\ntype CronString = string;\n\nfunction validateIntervalNumber(n: number) {\n  if (!Number.isInteger(n) || n <= 0) {\n    throw new Error(\"Interval must be an integer greater than 0\");\n  }\n}\n\nfunction validatedDayOfMonth(n: number) {\n  if (!Number.isInteger(n) || n < 1 || n > 31) {\n    throw new Error(\"Day of month must be an integer from 1 to 31\");\n  }\n  return n;\n}\n\nfunction validatedDayOfWeek(s: string) {\n  if (!DAYS_OF_WEEK.includes(s as DayOfWeek)) {\n    throw new Error('Day of week must be a string like \"monday\".');\n  }\n  return s as DayOfWeek;\n}\n\nfunction validatedHourOfDay(n: number) {\n  if (!Number.isInteger(n) || n < 0 || n > 23) {\n    throw new Error(\"Hour of day must be an integer from 0 to 23\");\n  }\n  return n;\n}\n\nfunction validatedMinuteOfHour(n: number) {\n  if (!Number.isInteger(n) || n < 0 || n > 59) {\n    throw new Error(\"Minute of hour must be an integer from 0 to 59\");\n  }\n  return n;\n}\n\n// `minuteUTC` is optional: when omitted the backend picks a minute per job and\n// spreads runs across the hour. Only validate when a minute was provided.\nfunction validatedOptionalMinuteOfHour(n: number | undefined) {\n  return n === undefined ? undefined : validatedMinuteOfHour(n);\n}\n\n// `crons.hourly()` lets the schedule object be omitted entirely. Tell the two\n// call shapes apart by whether the second argument resolves to a function\n// reference (the way the scheduler syscalls do) rather than a schedule object.\nfunction isSchedulableFunctionReference(\n  arg: Hourly | SchedulableFunctionReference,\n): arg is SchedulableFunctionReference {\n  try {\n    getFunctionAddress(arg);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nfunction validatedCronString(s: string) {\n  return s;\n}\n\nfunction validatedCronIdentifier(s: string) {\n  if (!s.match(/^[ -~]*$/)) {\n    throw new Error(\n      `Invalid cron identifier ${s}: use ASCII letters that are not control characters`,\n    );\n  }\n  return s;\n}\n\n/**\n * A class for scheduling cron jobs.\n *\n * To learn more see the documentation at https://docs.convex.dev/scheduling/cron-jobs\n *\n * @public\n */\nexport class Crons {\n  crons: Record<string, CronJob>;\n  isCrons: true;\n  constructor() {\n    this.isCrons = true;\n    this.crons = {};\n  }\n\n  /** @internal */\n  schedule(\n    cronIdentifier: string,\n    schedule: Schedule,\n    functionReference: SchedulableFunctionReference,\n    args?: Record<string, Value>,\n  ) {\n    const cronArgs = parseArgs(args);\n    validatedCronIdentifier(cronIdentifier);\n    if (cronIdentifier in this.crons) {\n      throw new Error(`Cron identifier registered twice: ${cronIdentifier}`);\n    }\n    this.crons[cronIdentifier] = {\n      name: getFunctionName(functionReference),\n      args: [convexToJson(cronArgs)],\n      schedule: schedule,\n    };\n  }\n\n  /**\n   * Schedule a mutation or action to run at some interval.\n   *\n   * ```js\n   * crons.interval(\"Clear presence data\", {seconds: 30}, api.presence.clear);\n   * ```\n   *\n   * @param identifier - A unique name for this scheduled job.\n   * @param schedule - The time between runs for this scheduled job.\n   * @param functionReference - A {@link FunctionReference} for the function\n   * to schedule.\n   * @param args - The arguments to the function.\n   */\n  interval<FuncRef extends SchedulableFunctionReference>(\n    cronIdentifier: string,\n    schedule: Interval,\n    functionReference: FuncRef,\n    ...args: OptionalRestArgs<FuncRef>\n  ) {\n    const s = schedule;\n    const hasSeconds = +(\"seconds\" in s && s.seconds !== undefined);\n    const hasMinutes = +(\"minutes\" in s && s.minutes !== undefined);\n    const hasHours = +(\"hours\" in s && s.hours !== undefined);\n    const total = hasSeconds + hasMinutes + hasHours;\n    if (total !== 1) {\n      throw new Error(\"Must specify one of seconds, minutes, or hours\");\n    }\n    if (hasSeconds) {\n      validateIntervalNumber(schedule.seconds!);\n    } else if (hasMinutes) {\n      validateIntervalNumber(schedule.minutes!);\n    } else if (hasHours) {\n      validateIntervalNumber(schedule.hours!);\n    }\n    this.schedule(\n      cronIdentifier,\n      { ...schedule, type: \"interval\" },\n      functionReference,\n      ...args,\n    );\n  }\n\n  /**\n   * Schedule a mutation or action to run on an hourly basis.\n   *\n   * ```js\n   * crons.hourly(\n   *   \"Reset high scores\",\n   *   {\n   *     minuteUTC: 30,\n   *   },\n   *   api.scores.reset\n   * )\n   * ```\n   *\n   * @param cronIdentifier - A unique name for this scheduled job.\n   * @param schedule - What minute (UTC) of each hour to run this function. May\n   * be omitted to let Convex pick a minute and spread runs across the hour.\n   * @param functionReference - A {@link FunctionReference} for the function\n   * to schedule.\n   * @param args - The arguments to the function.\n   */\n  hourly<FuncRef extends SchedulableFunctionReference>(\n    cronIdentifier: string,\n    functionReference: FuncRef,\n    ...args: OptionalRestArgs<FuncRef>\n  ): void;\n  hourly<FuncRef extends SchedulableFunctionReference>(\n    cronIdentifier: string,\n    schedule: Hourly,\n    functionReference: FuncRef,\n    ...args: OptionalRestArgs<FuncRef>\n  ): void;\n  hourly<FuncRef extends SchedulableFunctionReference>(\n    cronIdentifier: string,\n    scheduleOrFunctionReference: Hourly | FuncRef,\n    functionReferenceOrArg?: FuncRef | Record<string, Value>,\n    ...args: any[]\n  ): void {\n    // The schedule object may be omitted, so the second argument is either the\n    // function reference (no schedule) or the schedule.\n    if (isSchedulableFunctionReference(scheduleOrFunctionReference)) {\n      this.schedule(\n        cronIdentifier,\n        { type: \"hourly\" },\n        scheduleOrFunctionReference,\n        functionReferenceOrArg as Record<string, Value> | undefined,\n      );\n      return;\n    }\n    const minuteUTC = validatedOptionalMinuteOfHour(\n      scheduleOrFunctionReference.minuteUTC,\n    );\n    this.schedule(\n      cronIdentifier,\n      minuteUTC === undefined\n        ? { type: \"hourly\" }\n        : { minuteUTC, type: \"hourly\" },\n      functionReferenceOrArg as FuncRef,\n      ...args,\n    );\n  }\n\n  /**\n   * Schedule a mutation or action to run on a daily basis.\n   *\n   * ```js\n   * crons.daily(\n   *   \"Reset high scores\",\n   *   {\n   *     hourUTC: 17, // (9:30am Pacific/10:30am Daylight Savings Pacific)\n   *     minuteUTC: 30,\n   *   },\n   *   api.scores.reset\n   * )\n   * ```\n   *\n   * @param cronIdentifier - A unique name for this scheduled job.\n   * @param schedule - What time (UTC) each day to run this function.\n   * @param functionReference - A {@link FunctionReference} for the function\n   * to schedule.\n   * @param args - The arguments to the function.\n   */\n  daily<FuncRef extends SchedulableFunctionReference>(\n    cronIdentifier: string,\n    schedule: Daily,\n    functionReference: FuncRef,\n    ...args: OptionalRestArgs<FuncRef>\n  ) {\n    const hourUTC = validatedHourOfDay(schedule.hourUTC);\n    const minuteUTC = validatedOptionalMinuteOfHour(schedule.minuteUTC);\n    this.schedule(\n      cronIdentifier,\n      minuteUTC === undefined\n        ? { hourUTC, type: \"daily\" }\n        : { hourUTC, minuteUTC, type: \"daily\" },\n      functionReference,\n      ...args,\n    );\n  }\n\n  /**\n   * Schedule a mutation or action to run on a weekly basis.\n   *\n   * ```js\n   * crons.weekly(\n   *   \"Weekly re-engagement email\",\n   *   {\n   *     dayOfWeek: \"Tuesday\",\n   *     hourUTC: 17, // (9:30am Pacific/10:30am Daylight Savings Pacific)\n   *     minuteUTC: 30,\n   *   },\n   *   api.emails.send\n   * )\n   * ```\n   *\n   * @param cronIdentifier - A unique name for this scheduled job.\n   * @param schedule - What day and time (UTC) each week to run this function.\n   * @param functionReference - A {@link FunctionReference} for the function\n   * to schedule.\n   */\n  weekly<FuncRef extends SchedulableFunctionReference>(\n    cronIdentifier: string,\n    schedule: Weekly,\n    functionReference: FuncRef,\n    ...args: OptionalRestArgs<FuncRef>\n  ) {\n    const dayOfWeek = validatedDayOfWeek(schedule.dayOfWeek);\n    const hourUTC = validatedHourOfDay(schedule.hourUTC);\n    const minuteUTC = validatedOptionalMinuteOfHour(schedule.minuteUTC);\n    this.schedule(\n      cronIdentifier,\n      minuteUTC === undefined\n        ? { dayOfWeek, hourUTC, type: \"weekly\" }\n        : { dayOfWeek, hourUTC, minuteUTC, type: \"weekly\" },\n      functionReference,\n      ...args,\n    );\n  }\n\n  /**\n   * Schedule a mutation or action to run on a monthly basis.\n   *\n   * Note that some months have fewer days than others, so e.g. a function\n   * scheduled to run on the 30th will not run in February.\n   *\n   * ```js\n   * crons.monthly(\n   *   \"Bill customers at \",\n   *   {\n   *     hourUTC: 17, // (9:30am Pacific/10:30am Daylight Savings Pacific)\n   *     minuteUTC: 30,\n   *     day: 1,\n   *   },\n   *   api.billing.billCustomers\n   * )\n   * ```\n   *\n   * @param cronIdentifier - A unique name for this scheduled job.\n   * @param schedule - What day and time (UTC) each month to run this function.\n   * @param functionReference - A {@link FunctionReference} for the function\n   * to schedule.\n   * @param args - The arguments to the function.\n   */\n  monthly<FuncRef extends SchedulableFunctionReference>(\n    cronIdentifier: string,\n    schedule: Monthly,\n    functionReference: FuncRef,\n    ...args: OptionalRestArgs<FuncRef>\n  ) {\n    const day = validatedDayOfMonth(schedule.day);\n    const hourUTC = validatedHourOfDay(schedule.hourUTC);\n    const minuteUTC = validatedOptionalMinuteOfHour(schedule.minuteUTC);\n    this.schedule(\n      cronIdentifier,\n      minuteUTC === undefined\n        ? { day, hourUTC, type: \"monthly\" }\n        : { day, hourUTC, minuteUTC, type: \"monthly\" },\n      functionReference,\n      ...args,\n    );\n  }\n\n  /**\n   * Schedule a mutation or action to run on a recurring basis.\n   *\n   * Like the unix command `cron`, Sunday is 0, Monday is 1, etc.\n   *\n   * ```\n   *  \u250C\u2500 minute (0 - 59)\n   *  \u2502 \u250C\u2500 hour (0 - 23)\n   *  \u2502 \u2502 \u250C\u2500 day of the month (1 - 31)\n   *  \u2502 \u2502 \u2502 \u250C\u2500 month (1 - 12)\n   *  \u2502 \u2502 \u2502 \u2502 \u250C\u2500 day of the week (0 - 6) (Sunday to Saturday)\n   * \"* * * * *\"\n   * ```\n   *\n   * @param cronIdentifier - A unique name for this scheduled job.\n   * @param cron - Cron string like `\"15 7 * * *\"` (Every day at 7:15 UTC)\n   * @param functionReference - A {@link FunctionReference} for the function\n   * to schedule.\n   * @param args - The arguments to the function.\n   */\n  cron<FuncRef extends SchedulableFunctionReference>(\n    cronIdentifier: string,\n    cron: CronString,\n    functionReference: FuncRef,\n    ...args: OptionalRestArgs<FuncRef>\n  ) {\n    const c = validatedCronString(cron);\n    this.schedule(\n      cronIdentifier,\n      { cron: c, type: \"cron\" },\n      functionReference,\n      ...args,\n    );\n  }\n\n  /** @internal */\n  export() {\n    return JSON.stringify(this.crons);\n  }\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,iBAAkD;AAClD,oBAA0B;AAC1B,oBAA+C;AAC/C,mBAAmC;AAuBnC,MAAM,eAAe;AAAA,EACnB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAyJO,MAAM,WAAW,MAAM,IAAI,MAAM;AASxC,SAAS,uBAAuB,GAAW;AACzC,MAAI,CAAC,OAAO,UAAU,CAAC,KAAK,KAAK,GAAG;AAClC,UAAM,IAAI,MAAM,4CAA4C;AAAA,EAC9D;AACF;AAEA,SAAS,oBAAoB,GAAW;AACtC,MAAI,CAAC,OAAO,UAAU,CAAC,KAAK,IAAI,KAAK,IAAI,IAAI;AAC3C,UAAM,IAAI,MAAM,8CAA8C;AAAA,EAChE;AACA,SAAO;AACT;AAEA,SAAS,mBAAmB,GAAW;AACrC,MAAI,CAAC,aAAa,SAAS,CAAc,GAAG;AAC1C,UAAM,IAAI,MAAM,6CAA6C;AAAA,EAC/D;AACA,SAAO;AACT;AAEA,SAAS,mBAAmB,GAAW;AACrC,MAAI,CAAC,OAAO,UAAU,CAAC,KAAK,IAAI,KAAK,IAAI,IAAI;AAC3C,UAAM,IAAI,MAAM,6CAA6C;AAAA,EAC/D;AACA,SAAO;AACT;AAEA,SAAS,sBAAsB,GAAW;AACxC,MAAI,CAAC,OAAO,UAAU,CAAC,KAAK,IAAI,KAAK,IAAI,IAAI;AAC3C,UAAM,IAAI,MAAM,gDAAgD;AAAA,EAClE;AACA,SAAO;AACT;AAIA,SAAS,8BAA8B,GAAuB;AAC5D,SAAO,MAAM,SAAY,SAAY,sBAAsB,CAAC;AAC9D;AAKA,SAAS,+BACP,KACqC;AACrC,MAAI;AACF,yCAAmB,GAAG;AACtB,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,SAAS,oBAAoB,GAAW;AACtC,SAAO;AACT;AAEA,SAAS,wBAAwB,GAAW;AAC1C,MAAI,CAAC,EAAE,MAAM,UAAU,GAAG;AACxB,UAAM,IAAI;AAAA,MACR,2BAA2B,CAAC;AAAA,IAC9B;AAAA,EACF;AACA,SAAO;AACT;AASO,MAAM,MAAM;AAAA,EAGjB,cAAc;AAFd;AACA;AAEE,SAAK,UAAU;AACf,SAAK,QAAQ,CAAC;AAAA,EAChB;AAAA;AAAA,EAGA,SACE,gBACA,UACA,mBACA,MACA;AACA,UAAM,eAAW,yBAAU,IAAI;AAC/B,4BAAwB,cAAc;AACtC,QAAI,kBAAkB,KAAK,OAAO;AAChC,YAAM,IAAI,MAAM,qCAAqC,cAAc,EAAE;AAAA,IACvE;AACA,SAAK,MAAM,cAAc,IAAI;AAAA,MAC3B,UAAM,4BAAgB,iBAAiB;AAAA,MACvC,MAAM,KAAC,4BAAa,QAAQ,CAAC;AAAA,MAC7B;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAeA,SACE,gBACA,UACA,sBACG,MACH;AACA,UAAM,IAAI;AACV,UAAM,aAAa,EAAE,aAAa,KAAK,EAAE,YAAY;AACrD,UAAM,aAAa,EAAE,aAAa,KAAK,EAAE,YAAY;AACrD,UAAM,WAAW,EAAE,WAAW,KAAK,EAAE,UAAU;AAC/C,UAAM,QAAQ,aAAa,aAAa;AACxC,QAAI,UAAU,GAAG;AACf,YAAM,IAAI,MAAM,gDAAgD;AAAA,IAClE;AACA,QAAI,YAAY;AACd,6BAAuB,SAAS,OAAQ;AAAA,IAC1C,WAAW,YAAY;AACrB,6BAAuB,SAAS,OAAQ;AAAA,IAC1C,WAAW,UAAU;AACnB,6BAAuB,SAAS,KAAM;AAAA,IACxC;AACA,SAAK;AAAA,MACH;AAAA,MACA,EAAE,GAAG,UAAU,MAAM,WAAW;AAAA,MAChC;AAAA,MACA,GAAG;AAAA,IACL;AAAA,EACF;AAAA,EAiCA,OACE,gBACA,6BACA,2BACG,MACG;AAGN,QAAI,+BAA+B,2BAA2B,GAAG;AAC/D,WAAK;AAAA,QACH;AAAA,QACA,EAAE,MAAM,SAAS;AAAA,QACjB;AAAA,QACA;AAAA,MACF;AACA;AAAA,IACF;AACA,UAAM,YAAY;AAAA,MAChB,4BAA4B;AAAA,IAC9B;AACA,SAAK;AAAA,MACH;AAAA,MACA,cAAc,SACV,EAAE,MAAM,SAAS,IACjB,EAAE,WAAW,MAAM,SAAS;AAAA,MAChC;AAAA,MACA,GAAG;AAAA,IACL;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAsBA,MACE,gBACA,UACA,sBACG,MACH;AACA,UAAM,UAAU,mBAAmB,SAAS,OAAO;AACnD,UAAM,YAAY,8BAA8B,SAAS,SAAS;AAClE,SAAK;AAAA,MACH;AAAA,MACA,cAAc,SACV,EAAE,SAAS,MAAM,QAAQ,IACzB,EAAE,SAAS,WAAW,MAAM,QAAQ;AAAA,MACxC;AAAA,MACA,GAAG;AAAA,IACL;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAsBA,OACE,gBACA,UACA,sBACG,MACH;AACA,UAAM,YAAY,mBAAmB,SAAS,SAAS;AACvD,UAAM,UAAU,mBAAmB,SAAS,OAAO;AACnD,UAAM,YAAY,8BAA8B,SAAS,SAAS;AAClE,SAAK;AAAA,MACH;AAAA,MACA,cAAc,SACV,EAAE,WAAW,SAAS,MAAM,SAAS,IACrC,EAAE,WAAW,SAAS,WAAW,MAAM,SAAS;AAAA,MACpD;AAAA,MACA,GAAG;AAAA,IACL;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA0BA,QACE,gBACA,UACA,sBACG,MACH;AACA,UAAM,MAAM,oBAAoB,SAAS,GAAG;AAC5C,UAAM,UAAU,mBAAmB,SAAS,OAAO;AACnD,UAAM,YAAY,8BAA8B,SAAS,SAAS;AAClE,SAAK;AAAA,MACH;AAAA,MACA,cAAc,SACV,EAAE,KAAK,SAAS,MAAM,UAAU,IAChC,EAAE,KAAK,SAAS,WAAW,MAAM,UAAU;AAAA,MAC/C;AAAA,MACA,GAAG;AAAA,IACL;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAsBA,KACE,gBACA,MACA,sBACG,MACH;AACA,UAAM,IAAI,oBAAoB,IAAI;AAClC,SAAK;AAAA,MACH;AAAA,MACA,EAAE,MAAM,GAAG,MAAM,OAAO;AAAA,MACxB;AAAA,MACA,GAAG;AAAA,IACL;AAAA,EACF;AAAA;AAAA,EAGA,SAAS;AACP,WAAO,KAAK,UAAU,KAAK,KAAK;AAAA,EAClC;AACF;",
   "names": []
 }

package/dist/cjs/server/database.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/server/database.ts"],
-  "sourcesContent": ["import { GenericId } from \"../values/index.js\";\nimport {\n  DocumentByName,\n  GenericDataModel,\n  NamedTableInfo,\n  TableNamesInDataModel,\n} from \"./data_model.js\";\nimport { QueryInitializer } from \"./query.js\";\nimport { SystemDataModel } from \"./schema.js\";\nimport {\n  WithOptionalSystemFields,\n  WithoutSystemFields,\n} from \"./system_fields.js\";\n\ninterface BaseDatabaseReader<DataModel extends GenericDataModel> {\n  /**\n   * Fetch a single document from the database by table name and\n   * {@link values.GenericId}.\n   *\n   * @example\n   * ```typescript\n   * const user = await ctx.db.get(\"users\", userId);\n   * ```\n   *\n   * @param table - The name of the table to fetch the document from.\n   * @param id - The {@link values.GenericId} of the document to fetch from the database.\n   * @returns - The {@link GenericDocument} of the document at the given {@link values.GenericId}, or `null` if it no longer exists.\n   */\n  get<TableName extends TableNamesInDataModel<DataModel>>(\n    table: TableName,\n    id: GenericId<NonUnion<TableName>>,\n  ): Promise<DocumentByName<DataModel, TableName> | null>;\n\n  /**\n   * Fetch a single document from the database by its {@link values.GenericId}.\n   *\n   * Supported for backwards compatibility. Prefer `db.get(tableName, id)` in\n   * new code, or `db.system.get(tableName, id)` for system tables.\n   *\n   * @param id - The {@link values.GenericId} of the document to fetch from the database.\n   * @returns - The {@link GenericDocument} of the document at the given {@link values.GenericId}, or `null` if it no longer exists.\n   */\n  get<TableName extends TableNamesInDataModel<DataModel>>(\n    id: GenericId<TableName>,\n  ): Promise<DocumentByName<DataModel, TableName> | null>;\n\n  /**\n   * Begin a query for the given table name.\n   *\n   * Queries don't execute immediately, so calling this method and extending its\n   * query are free until the results are actually used.\n   *\n   * @param tableName - The name of the table to query.\n   * @returns - A {@link QueryInitializer} object to start building a query.\n   */\n  query<TableName extends TableNamesInDataModel<DataModel>>(\n    tableName: TableName,\n  ): QueryInitializer<NamedTableInfo<DataModel, TableName>>;\n\n  /**\n   * Returns the string ID format for the ID in a given table, or null if the ID\n   * is from a different table or is not a valid ID.\n   *\n   * This accepts the string ID format as well as the `.toString()` representation\n   * of the legacy class-based ID format.\n   *\n   * This does not guarantee that the ID exists (i.e. `db.get(tableName, id)` may return `null`).\n   *\n   * @param tableName - The name of the table.\n   * @param id - The ID string.\n   */\n  normalizeId<TableName extends TableNamesInDataModel<DataModel>>(\n    tableName: TableName,\n    id: string,\n  ): GenericId<TableName> | null;\n}\n\ninterface BaseDatabaseReaderWithTable<DataModel extends GenericDataModel> {\n  /**\n   * Scope the database to a specific table.\n   */\n  table<TableName extends TableNamesInDataModel<DataModel>>(\n    tableName: TableName,\n  ): BaseTableReader<DataModel, TableName>;\n}\n\nexport interface BaseTableReader<\n  DataModel extends GenericDataModel,\n  TableName extends TableNamesInDataModel<DataModel>,\n> {\n  /**\n   * Fetch a single document from the table by its {@link values.GenericId}.\n   *\n   * @param id - The {@link values.GenericId} of the document to fetch from the database.\n   * @returns - The {@link GenericDocument} of the document at the given {@link values.GenericId}, or `null` if it no longer exists.\n   */\n  get(\n    id: GenericId<TableName>,\n  ): Promise<DocumentByName<DataModel, TableName> | null>;\n\n  /**\n   * Begin a query for the table.\n   *\n   * Queries don't execute immediately, so calling this method and extending its\n   * query are free until the results are actually used.\n   *\n   * @returns - A {@link QueryInitializer} object to start building a query.\n   */\n  query(): QueryInitializer<NamedTableInfo<DataModel, TableName>>;\n}\n\n/**\n * An interface to read from the database within Convex query functions.\n *\n * Available as `ctx.db` in queries (read-only) and mutations (read-write).\n * You should generally use the `DatabaseReader` type from\n * `\"./_generated/server\"`.\n *\n * The two entry points are:\n *   - {@link GenericDatabaseReader.get}, which fetches a single document\n *     by table name and {@link values.GenericId}.\n *   - {@link GenericDatabaseReader.query}, which starts building a query.\n *\n * @example\n * ```typescript\n * // Fetch a single document by ID:\n * const user = await ctx.db.get(\"users\", userId);\n *\n * // Query documents with an index:\n * const messages = await ctx.db\n *   .query(\"messages\")\n *   .withIndex(\"by_channel\", (q) => q.eq(\"channelId\", channelId))\n *   .order(\"desc\")\n *   .take(50);\n * ```\n *\n * **Best practice:** Use `.withIndex()` instead of `.filter()` for efficient\n * queries. Define indexes in your schema for fields you query frequently.\n *\n * @see https://docs.convex.dev/database/reading-data\n * @public\n */\nexport interface GenericDatabaseReader<\n  DataModel extends GenericDataModel,\n> extends BaseDatabaseReader<DataModel> {\n  /**\n   * An interface to read from the system tables within Convex query functions.\n   *\n   * System tables include `_storage` (file metadata) and\n   * `_scheduled_functions` (scheduled function state). Use `ctx.db.system.get()`\n   * and `ctx.db.system.query()` just like regular tables.\n   *\n   * @example\n   * ```typescript\n   * // Get file metadata from the _storage system table:\n   * const metadata = await ctx.db.system.get(\"_storage\", storageId);\n   * // metadata has: _id, _creationTime, contentType, sha256, size\n   * ```\n   *\n   * @public\n   */\n  system: BaseDatabaseReader<SystemDataModel>;\n}\n\nexport interface GenericDatabaseReaderWithTable<\n  DataModel extends GenericDataModel,\n> extends BaseDatabaseReaderWithTable<DataModel> {\n  /**\n   * An interface to read from the system tables within Convex query functions\n   *\n   * The two entry points are:\n   *   - {@link GenericDatabaseReader.get}, which fetches a single document\n   *     by its {@link values.GenericId}.\n   *   - {@link GenericDatabaseReader.query}, which starts building a query.\n   *\n   * @public\n   */\n  system: BaseDatabaseReaderWithTable<SystemDataModel>;\n}\n\n/**\n * An interface to read from and write to the database within Convex mutation\n * functions.\n *\n * Available as `ctx.db` in mutations. You should generally use the\n * `DatabaseWriter` type from `\"./_generated/server\"`.\n *\n * Extends {@link GenericDatabaseReader}\n * with write operations. All reads and writes within a single mutation are\n * executed **atomically**, you never have to worry about partial writes\n * leaving your data in an inconsistent state.\n *\n * @example\n * ```typescript\n * // Insert a new document:\n * const userId = await ctx.db.insert(\"users\", { name: \"Alice\", email: \"alice@example.com\" });\n *\n * // Update specific fields (shallow merge):\n * await ctx.db.patch(\"users\", userId, { name: \"Alice Smith\" });\n *\n * // Replace entire document (all non-system fields):\n * await ctx.db.replace(\"users\", userId, { name: \"Bob\", email: \"bob@example.com\" });\n *\n * // Delete a document:\n * await ctx.db.delete(\"users\", userId);\n *\n * // Delete multiple documents (collect first, then delete each):\n * const oldTasks = await ctx.db\n *   .query(\"tasks\")\n *   .withIndex(\"by_completed\", (q) => q.eq(\"completed\", true))\n *   .collect();\n * for (const task of oldTasks) {\n *   await ctx.db.delete(\"tasks\", task._id);\n * }\n * ```\n *\n * @see https://docs.convex.dev/database/writing-data\n * @public\n */\nexport interface GenericDatabaseWriter<\n  DataModel extends GenericDataModel,\n> extends GenericDatabaseReader<DataModel> {\n  /**\n   * Insert a new document into a table.\n   *\n   * @example\n   * ```typescript\n   * const taskId = await ctx.db.insert(\"tasks\", {\n   *   text: \"Buy groceries\",\n   *   completed: false,\n   * });\n   * ```\n   *\n   * @param table - The name of the table to insert a new document into.\n   * @param value - The document to insert. System fields (`_id`, `_creationTime`)\n   * are added automatically and should not be included.\n   * @returns The {@link values.GenericId} of the new document.\n   */\n  insert<TableName extends TableNamesInDataModel<DataModel>>(\n    table: TableName,\n    value: WithoutSystemFields<DocumentByName<DataModel, TableName>>,\n  ): Promise<GenericId<TableName>>;\n\n  /**\n   * Patch an existing document, shallow merging it with the given partial\n   * document.\n   *\n   * New fields are added. Existing fields are overwritten. Fields set to\n   * `undefined` are removed. Fields not specified in the patch are left\n   * unchanged.\n   *\n   * This method will throw if the document does not exist.\n   *\n   * @example\n   * ```typescript\n   * // Update only the \"completed\" field, leaving other fields unchanged:\n   * await ctx.db.patch(\"tasks\", taskId, { completed: true });\n   *\n   * // Remove an optional field by setting it to undefined:\n   * await ctx.db.patch(\"tasks\", taskId, { assignee: undefined });\n   * ```\n   *\n   * **Tip:** Use `patch` for partial updates. Use `replace` when you want to\n   * overwrite the entire document.\n   *\n   * @param table - The name of the table the document is in.\n   * @param id - The {@link values.GenericId} of the document to patch.\n   * @param value - The partial document to merge into the existing document.\n   */\n  patch<TableName extends TableNamesInDataModel<DataModel>>(\n    table: TableName,\n    id: GenericId<NonUnion<TableName>>,\n    value: PatchValue<DocumentByName<DataModel, TableName>>,\n  ): Promise<void>;\n\n  /**\n   * Patch an existing document, shallow merging it with the given partial\n   * document.\n   *\n   * New fields are added. Existing fields are overwritten. Fields set to\n   * `undefined` are removed. Fields not specified in the patch are left\n   * unchanged.\n   *\n   * This method will throw if the document does not exist.\n   *\n   * Supported for backwards compatibility. Prefer `db.patch(tableName, id, value)`\n   * in new code.\n   *\n   * @param id - The {@link values.GenericId} of the document to patch.\n   * @param value - The partial document to merge into the existing document.\n   */\n  patch<TableName extends TableNamesInDataModel<DataModel>>(\n    id: GenericId<TableName>,\n    value: PatchValue<DocumentByName<DataModel, TableName>>,\n  ): Promise<void>;\n\n  /**\n   * Replace the value of an existing document, overwriting its old value\n   * completely.\n   *\n   * Unlike `patch`, which does a shallow merge, `replace` overwrites the\n   * entire document. Any fields not included in the new value will be removed\n   * (except system fields `_id` and `_creationTime`).\n   *\n   * This method will throw if the document does not exist.\n   *\n   * @example\n   * ```typescript\n   * // Replace the entire document:\n   * await ctx.db.replace(\"users\", userId, {\n   *   name: \"New Name\",\n   *   email: \"new@example.com\",\n   * });\n   * ```\n   *\n   * @param table - The name of the table the document is in.\n   * @param id - The {@link values.GenericId} of the document to replace.\n   * @param value - The new document. System fields can be omitted.\n   */\n  replace<TableName extends TableNamesInDataModel<DataModel>>(\n    table: TableName,\n    id: GenericId<NonUnion<TableName>>,\n    value: WithOptionalSystemFields<DocumentByName<DataModel, TableName>>,\n  ): Promise<void>;\n\n  /**\n   * Replace the value of an existing document, overwriting its old value\n   * completely.\n   *\n   * Unlike `patch`, which does a shallow merge, `replace` overwrites the\n   * entire document.\n   *\n   * Supported for backwards compatibility. Prefer `db.replace(tableName, id, value)`\n   * in new code.\n   *\n   * @param id - The {@link values.GenericId} of the document to replace.\n   * @param value - The new document. System fields can be omitted.\n   */\n  replace<TableName extends TableNamesInDataModel<DataModel>>(\n    id: GenericId<TableName>,\n    value: WithOptionalSystemFields<DocumentByName<DataModel, TableName>>,\n  ): Promise<void>;\n\n  /**\n   * Delete an existing document.\n   *\n   * @example\n   * ```typescript\n   * await ctx.db.delete(\"tasks\", taskId);\n   * ```\n   *\n   * @param table - The name of the table the document is in.\n   * @param id - The {@link values.GenericId} of the document to remove.\n   */\n  delete<TableName extends TableNamesInDataModel<DataModel>>(\n    table: TableName,\n    id: GenericId<NonUnion<TableName>>,\n  ): Promise<void>;\n\n  /**\n   * Delete an existing document.\n   *\n   * Supported for backwards compatibility. Prefer `db.delete(tableName, id)` in\n   * new code.\n   *\n   * **Note:** Convex queries do not support `.delete()` directly on query\n   * results. To delete multiple documents, `.collect()` them first, then\n   * delete each one individually.\n   *\n   * @param id - The {@link values.GenericId} of the document to remove.\n   */\n  delete(id: GenericId<TableNamesInDataModel<DataModel>>): Promise<void>;\n}\n\n/**\n * An interface to read from and write to the database within Convex mutation\n * functions.\n *\n * You should generally use the `DatabaseWriter` type from\n * `\"./_generated/server\"`.\n *\n * Convex guarantees that all writes within a single mutation are\n * executed atomically, so you never have to worry about partial writes leaving\n * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)\n * for the guarantees Convex provides your functions.\n *\n * @public\n */\nexport interface GenericDatabaseWriterWithTable<\n  DataModel extends GenericDataModel,\n> extends GenericDatabaseReaderWithTable<DataModel> {\n  /**\n   * Scope the database to a specific table.\n   */\n  table<TableName extends TableNamesInDataModel<DataModel>>(\n    tableName: TableName,\n  ): BaseTableWriter<DataModel, TableName>;\n}\n\nexport interface BaseTableWriter<\n  DataModel extends GenericDataModel,\n  TableName extends TableNamesInDataModel<DataModel>,\n> extends BaseTableReader<DataModel, TableName> {\n  /**\n   * Insert a new document into the table.\n   *\n   * @param value - The {@link values.Value} to insert into the given table.\n   * @returns - {@link values.GenericId} of the new document.\n   */\n  insert(\n    value: WithoutSystemFields<DocumentByName<DataModel, TableName>>,\n  ): Promise<GenericId<TableName>>;\n\n  /**\n   * Patch an existing document, shallow merging it with the given partial\n   * document.\n   *\n   * New fields are added. Existing fields are overwritten. Fields set to\n   * `undefined` are removed.\n   *\n   * @param id - The {@link values.GenericId} of the document to patch.\n   * @param value - The partial {@link GenericDocument} to merge into the specified document. If this new value\n   * specifies system fields like `_id`, they must match the document's existing field values.\n   */\n  patch(\n    id: GenericId<TableName>,\n    value: PatchValue<DocumentByName<DataModel, TableName>>,\n  ): Promise<void>;\n\n  /**\n   * Replace the value of an existing document, overwriting its old value.\n   *\n   * @param id - The {@link values.GenericId} of the document to replace.\n   * @param value - The new {@link GenericDocument} for the document. This value can omit the system fields,\n   * and the database will fill them in.\n   */\n  replace(\n    id: GenericId<TableName>,\n    value: WithOptionalSystemFields<DocumentByName<DataModel, TableName>>,\n  ): Promise<void>;\n\n  /**\n   * Delete an existing document.\n   *\n   * @param id - The {@link values.GenericId} of the document to remove.\n   */\n  delete(id: GenericId<TableName>): Promise<void>;\n}\n\n/**\n * This prevents TypeScript from inferring that the generic `TableName` type is\n * a union type when `table` and `id` disagree.\n */\ntype NonUnion<T> = T extends never // `never` is the bottom type for TypeScript unions\n  ? never\n  : T;\n\n/**\n * This is like Partial, but it also allows undefined to be passed to optional\n * fields when `exactOptionalPropertyTypes` is enabled in the tsconfig.\n */\ntype PatchValue<T> = {\n  [P in keyof T]?: undefined extends T[P] ? T[P] | undefined : T[P];\n};\n"],
+  "sourcesContent": ["import { GenericId } from \"../values/index.js\";\nimport { CommitTsPlaceholder } from \"../values/value.js\";\nimport {\n  DocumentByName,\n  GenericDataModel,\n  NamedTableInfo,\n  TableNamesInDataModel,\n} from \"./data_model.js\";\nimport { QueryInitializer } from \"./query.js\";\nimport { SystemDataModel } from \"./schema.js\";\nimport {\n  WithOptionalSystemFields,\n  WithoutSystemFields,\n} from \"./system_fields.js\";\n\ninterface BaseDatabaseReader<DataModel extends GenericDataModel> {\n  /**\n   * Fetch a single document from the database by table name and\n   * {@link values.GenericId}.\n   *\n   * @example\n   * ```typescript\n   * const user = await ctx.db.get(\"users\", userId);\n   * ```\n   *\n   * @param table - The name of the table to fetch the document from.\n   * @param id - The {@link values.GenericId} of the document to fetch from the database.\n   * @returns - The {@link GenericDocument} of the document at the given {@link values.GenericId}, or `null` if it no longer exists.\n   */\n  get<TableName extends TableNamesInDataModel<DataModel>>(\n    table: TableName,\n    id: GenericId<NonUnion<TableName>>,\n  ): Promise<DocumentByName<DataModel, TableName> | null>;\n\n  /**\n   * Fetch a single document from the database by its {@link values.GenericId}.\n   *\n   * Supported for backwards compatibility. Prefer `db.get(tableName, id)` in\n   * new code, or `db.system.get(tableName, id)` for system tables.\n   *\n   * @param id - The {@link values.GenericId} of the document to fetch from the database.\n   * @returns - The {@link GenericDocument} of the document at the given {@link values.GenericId}, or `null` if it no longer exists.\n   */\n  get<TableName extends TableNamesInDataModel<DataModel>>(\n    id: GenericId<TableName>,\n  ): Promise<DocumentByName<DataModel, TableName> | null>;\n\n  /**\n   * Begin a query for the given table name.\n   *\n   * Queries don't execute immediately, so calling this method and extending its\n   * query are free until the results are actually used.\n   *\n   * @param tableName - The name of the table to query.\n   * @returns - A {@link QueryInitializer} object to start building a query.\n   */\n  query<TableName extends TableNamesInDataModel<DataModel>>(\n    tableName: TableName,\n  ): QueryInitializer<NamedTableInfo<DataModel, TableName>>;\n\n  /**\n   * Returns the string ID format for the ID in a given table, or null if the ID\n   * is from a different table or is not a valid ID.\n   *\n   * This accepts the string ID format as well as the `.toString()` representation\n   * of the legacy class-based ID format.\n   *\n   * This does not guarantee that the ID exists (i.e. `db.get(tableName, id)` may return `null`).\n   *\n   * @param tableName - The name of the table.\n   * @param id - The ID string.\n   */\n  normalizeId<TableName extends TableNamesInDataModel<DataModel>>(\n    tableName: TableName,\n    id: string,\n  ): GenericId<TableName> | null;\n}\n\ninterface BaseDatabaseReaderWithTable<DataModel extends GenericDataModel> {\n  /**\n   * Scope the database to a specific table.\n   */\n  table<TableName extends TableNamesInDataModel<DataModel>>(\n    tableName: TableName,\n  ): BaseTableReader<DataModel, TableName>;\n}\n\nexport interface BaseTableReader<\n  DataModel extends GenericDataModel,\n  TableName extends TableNamesInDataModel<DataModel>,\n> {\n  /**\n   * Fetch a single document from the table by its {@link values.GenericId}.\n   *\n   * @param id - The {@link values.GenericId} of the document to fetch from the database.\n   * @returns - The {@link GenericDocument} of the document at the given {@link values.GenericId}, or `null` if it no longer exists.\n   */\n  get(\n    id: GenericId<TableName>,\n  ): Promise<DocumentByName<DataModel, TableName> | null>;\n\n  /**\n   * Begin a query for the table.\n   *\n   * Queries don't execute immediately, so calling this method and extending its\n   * query are free until the results are actually used.\n   *\n   * @returns - A {@link QueryInitializer} object to start building a query.\n   */\n  query(): QueryInitializer<NamedTableInfo<DataModel, TableName>>;\n}\n\n/**\n * An interface to read from the database within Convex query functions.\n *\n * Available as `ctx.db` in queries (read-only) and mutations (read-write).\n * You should generally use the `DatabaseReader` type from\n * `\"./_generated/server\"`.\n *\n * The two entry points are:\n *   - {@link GenericDatabaseReader.get}, which fetches a single document\n *     by table name and {@link values.GenericId}.\n *   - {@link GenericDatabaseReader.query}, which starts building a query.\n *\n * @example\n * ```typescript\n * // Fetch a single document by ID:\n * const user = await ctx.db.get(\"users\", userId);\n *\n * // Query documents with an index:\n * const messages = await ctx.db\n *   .query(\"messages\")\n *   .withIndex(\"by_channel\", (q) => q.eq(\"channelId\", channelId))\n *   .order(\"desc\")\n *   .take(50);\n * ```\n *\n * **Best practice:** Use `.withIndex()` instead of `.filter()` for efficient\n * queries. Define indexes in your schema for fields you query frequently.\n *\n * @see https://docs.convex.dev/database/reading-data\n * @public\n */\nexport interface GenericDatabaseReader<\n  DataModel extends GenericDataModel,\n> extends BaseDatabaseReader<DataModel> {\n  /**\n   * An interface to read from the system tables within Convex query functions.\n   *\n   * System tables include `_storage` (file metadata) and\n   * `_scheduled_functions` (scheduled function state). Use `ctx.db.system.get()`\n   * and `ctx.db.system.query()` just like regular tables.\n   *\n   * @example\n   * ```typescript\n   * // Get file metadata from the _storage system table:\n   * const metadata = await ctx.db.system.get(\"_storage\", storageId);\n   * // metadata has: _id, _creationTime, contentType, sha256, size\n   * ```\n   *\n   * @public\n   */\n  system: BaseDatabaseReader<SystemDataModel>;\n}\n\nexport interface GenericDatabaseReaderWithTable<\n  DataModel extends GenericDataModel,\n> extends BaseDatabaseReaderWithTable<DataModel> {\n  /**\n   * An interface to read from the system tables within Convex query functions\n   *\n   * The two entry points are:\n   *   - {@link GenericDatabaseReader.get}, which fetches a single document\n   *     by its {@link values.GenericId}.\n   *   - {@link GenericDatabaseReader.query}, which starts building a query.\n   *\n   * @public\n   */\n  system: BaseDatabaseReaderWithTable<SystemDataModel>;\n}\n\n/**\n * An interface to read from and write to the database within Convex mutation\n * functions.\n *\n * Available as `ctx.db` in mutations. You should generally use the\n * `DatabaseWriter` type from `\"./_generated/server\"`.\n *\n * Extends {@link GenericDatabaseReader}\n * with write operations. All reads and writes within a single mutation are\n * executed **atomically**, you never have to worry about partial writes\n * leaving your data in an inconsistent state.\n *\n * @example\n * ```typescript\n * // Insert a new document:\n * const userId = await ctx.db.insert(\"users\", { name: \"Alice\", email: \"alice@example.com\" });\n *\n * // Update specific fields (shallow merge):\n * await ctx.db.patch(\"users\", userId, { name: \"Alice Smith\" });\n *\n * // Replace entire document (all non-system fields):\n * await ctx.db.replace(\"users\", userId, { name: \"Bob\", email: \"bob@example.com\" });\n *\n * // Delete a document:\n * await ctx.db.delete(\"users\", userId);\n *\n * // Delete multiple documents (collect first, then delete each):\n * const oldTasks = await ctx.db\n *   .query(\"tasks\")\n *   .withIndex(\"by_completed\", (q) => q.eq(\"completed\", true))\n *   .collect();\n * for (const task of oldTasks) {\n *   await ctx.db.delete(\"tasks\", task._id);\n * }\n * ```\n *\n * @see https://docs.convex.dev/database/writing-data\n * @public\n */\nexport interface GenericDatabaseWriter<\n  DataModel extends GenericDataModel,\n> extends GenericDatabaseReader<DataModel> {\n  /**\n   * Insert a new document into a table.\n   *\n   * @example\n   * ```typescript\n   * const taskId = await ctx.db.insert(\"tasks\", {\n   *   text: \"Buy groceries\",\n   *   completed: false,\n   * });\n   * ```\n   *\n   * @param table - The name of the table to insert a new document into.\n   * @param value - The document to insert. System fields (`_id`, `_creationTime`)\n   * are added automatically and should not be included.\n   * @returns The {@link values.GenericId} of the new document.\n   */\n  insert<TableName extends TableNamesInDataModel<DataModel>>(\n    table: TableName,\n    value: WithoutSystemFields<DocumentByName<DataModel, TableName>>,\n  ): Promise<GenericId<TableName>>;\n\n  /**\n   * Patch an existing document, shallow merging it with the given partial\n   * document.\n   *\n   * New fields are added. Existing fields are overwritten. Fields set to\n   * `undefined` are removed. Fields not specified in the patch are left\n   * unchanged.\n   *\n   * This method will throw if the document does not exist.\n   *\n   * @example\n   * ```typescript\n   * // Update only the \"completed\" field, leaving other fields unchanged:\n   * await ctx.db.patch(\"tasks\", taskId, { completed: true });\n   *\n   * // Remove an optional field by setting it to undefined:\n   * await ctx.db.patch(\"tasks\", taskId, { assignee: undefined });\n   * ```\n   *\n   * **Tip:** Use `patch` for partial updates. Use `replace` when you want to\n   * overwrite the entire document.\n   *\n   * @param table - The name of the table the document is in.\n   * @param id - The {@link values.GenericId} of the document to patch.\n   * @param value - The partial document to merge into the existing document.\n   */\n  patch<TableName extends TableNamesInDataModel<DataModel>>(\n    table: TableName,\n    id: GenericId<NonUnion<TableName>>,\n    value: PatchValue<DocumentByName<DataModel, TableName>>,\n  ): Promise<void>;\n\n  /**\n   * Patch an existing document, shallow merging it with the given partial\n   * document.\n   *\n   * New fields are added. Existing fields are overwritten. Fields set to\n   * `undefined` are removed. Fields not specified in the patch are left\n   * unchanged.\n   *\n   * This method will throw if the document does not exist.\n   *\n   * Supported for backwards compatibility. Prefer `db.patch(tableName, id, value)`\n   * in new code.\n   *\n   * @param id - The {@link values.GenericId} of the document to patch.\n   * @param value - The partial document to merge into the existing document.\n   */\n  patch<TableName extends TableNamesInDataModel<DataModel>>(\n    id: GenericId<TableName>,\n    value: PatchValue<DocumentByName<DataModel, TableName>>,\n  ): Promise<void>;\n\n  /**\n   * Replace the value of an existing document, overwriting its old value\n   * completely.\n   *\n   * Unlike `patch`, which does a shallow merge, `replace` overwrites the\n   * entire document. Any fields not included in the new value will be removed\n   * (except system fields `_id` and `_creationTime`).\n   *\n   * This method will throw if the document does not exist.\n   *\n   * @example\n   * ```typescript\n   * // Replace the entire document:\n   * await ctx.db.replace(\"users\", userId, {\n   *   name: \"New Name\",\n   *   email: \"new@example.com\",\n   * });\n   * ```\n   *\n   * @param table - The name of the table the document is in.\n   * @param id - The {@link values.GenericId} of the document to replace.\n   * @param value - The new document. System fields can be omitted.\n   */\n  replace<TableName extends TableNamesInDataModel<DataModel>>(\n    table: TableName,\n    id: GenericId<NonUnion<TableName>>,\n    value: WithOptionalSystemFields<DocumentByName<DataModel, TableName>>,\n  ): Promise<void>;\n\n  /**\n   * Replace the value of an existing document, overwriting its old value\n   * completely.\n   *\n   * Unlike `patch`, which does a shallow merge, `replace` overwrites the\n   * entire document.\n   *\n   * Supported for backwards compatibility. Prefer `db.replace(tableName, id, value)`\n   * in new code.\n   *\n   * @param id - The {@link values.GenericId} of the document to replace.\n   * @param value - The new document. System fields can be omitted.\n   */\n  replace<TableName extends TableNamesInDataModel<DataModel>>(\n    id: GenericId<TableName>,\n    value: WithOptionalSystemFields<DocumentByName<DataModel, TableName>>,\n  ): Promise<void>;\n\n  /**\n   * Delete an existing document.\n   *\n   * @example\n   * ```typescript\n   * await ctx.db.delete(\"tasks\", taskId);\n   * ```\n   *\n   * @param table - The name of the table the document is in.\n   * @param id - The {@link values.GenericId} of the document to remove.\n   */\n  delete<TableName extends TableNamesInDataModel<DataModel>>(\n    table: TableName,\n    id: GenericId<NonUnion<TableName>>,\n  ): Promise<void>;\n\n  /**\n   * Delete an existing document.\n   *\n   * Supported for backwards compatibility. Prefer `db.delete(tableName, id)` in\n   * new code.\n   *\n   * **Note:** Convex queries do not support `.delete()` directly on query\n   * results. To delete multiple documents, `.collect()` them first, then\n   * delete each one individually.\n   *\n   * @param id - The {@link values.GenericId} of the document to remove.\n   */\n  delete(id: GenericId<TableNamesInDataModel<DataModel>>): Promise<void>;\n\n  /**\n   * Values that are not known until the mutation commits.\n   *\n   * @internal\n   */\n  vars: {\n    /**\n     * The placeholder for the transaction's commit timestamp. Written into a\n     * document field via `db.insert`, it resolves at commit to an int64\n     * (`bigint`) ordered by commit order. Within the writing mutation,\n     * reading the field back yields the placeholder, which cannot be used as\n     * a number.\n     */\n    commitTs: CommitTsPlaceholder;\n  };\n}\n\n/**\n * An interface to read from and write to the database within Convex mutation\n * functions.\n *\n * You should generally use the `DatabaseWriter` type from\n * `\"./_generated/server\"`.\n *\n * Convex guarantees that all writes within a single mutation are\n * executed atomically, so you never have to worry about partial writes leaving\n * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)\n * for the guarantees Convex provides your functions.\n *\n * @public\n */\nexport interface GenericDatabaseWriterWithTable<\n  DataModel extends GenericDataModel,\n> extends GenericDatabaseReaderWithTable<DataModel> {\n  /**\n   * Scope the database to a specific table.\n   */\n  table<TableName extends TableNamesInDataModel<DataModel>>(\n    tableName: TableName,\n  ): BaseTableWriter<DataModel, TableName>;\n}\n\nexport interface BaseTableWriter<\n  DataModel extends GenericDataModel,\n  TableName extends TableNamesInDataModel<DataModel>,\n> extends BaseTableReader<DataModel, TableName> {\n  /**\n   * Insert a new document into the table.\n   *\n   * @param value - The {@link values.Value} to insert into the given table.\n   * @returns - {@link values.GenericId} of the new document.\n   */\n  insert(\n    value: WithoutSystemFields<DocumentByName<DataModel, TableName>>,\n  ): Promise<GenericId<TableName>>;\n\n  /**\n   * Patch an existing document, shallow merging it with the given partial\n   * document.\n   *\n   * New fields are added. Existing fields are overwritten. Fields set to\n   * `undefined` are removed.\n   *\n   * @param id - The {@link values.GenericId} of the document to patch.\n   * @param value - The partial {@link GenericDocument} to merge into the specified document. If this new value\n   * specifies system fields like `_id`, they must match the document's existing field values.\n   */\n  patch(\n    id: GenericId<TableName>,\n    value: PatchValue<DocumentByName<DataModel, TableName>>,\n  ): Promise<void>;\n\n  /**\n   * Replace the value of an existing document, overwriting its old value.\n   *\n   * @param id - The {@link values.GenericId} of the document to replace.\n   * @param value - The new {@link GenericDocument} for the document. This value can omit the system fields,\n   * and the database will fill them in.\n   */\n  replace(\n    id: GenericId<TableName>,\n    value: WithOptionalSystemFields<DocumentByName<DataModel, TableName>>,\n  ): Promise<void>;\n\n  /**\n   * Delete an existing document.\n   *\n   * @param id - The {@link values.GenericId} of the document to remove.\n   */\n  delete(id: GenericId<TableName>): Promise<void>;\n}\n\n/**\n * This prevents TypeScript from inferring that the generic `TableName` type is\n * a union type when `table` and `id` disagree.\n */\ntype NonUnion<T> = T extends never // `never` is the bottom type for TypeScript unions\n  ? never\n  : T;\n\n/**\n * This is like Partial, but it also allows undefined to be passed to optional\n * fields when `exactOptionalPropertyTypes` is enabled in the tsconfig.\n */\ntype PatchValue<T> = {\n  [P in keyof T]?: undefined extends T[P] ? T[P] | undefined : T[P];\n};\n"],
   "mappings": ";;;;;;;;;;;;;;AAAA;AAAA;",
   "names": []
 }

package/dist/cjs/server/impl/database_impl.js

@@ -140,6 +140,9 @@ function setupWriter() {
     },
     table: (tableName) => {
       return new TableWriter(tableName, false);
+    },
+    vars: {
+      commitTs: import_value.commitTsPlaceholder
     }
   };
 }

package/dist/cjs/server/impl/database_impl.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/server/impl/database_impl.ts"],
-  "sourcesContent": ["import {\n  convexToJson,\n  GenericId,\n  jsonToConvex,\n  Value,\n} from \"../../values/index.js\";\nimport { performAsyncSyscall, performSyscall } from \"./syscall.js\";\nimport {\n  GenericDatabaseReader,\n  GenericDatabaseReaderWithTable,\n  GenericDatabaseWriter,\n  GenericDatabaseWriterWithTable,\n} from \"../database.js\";\nimport { QueryInitializerImpl } from \"./query_impl.js\";\nimport { GenericDataModel, GenericDocument } from \"../data_model.js\";\nimport { validateArg } from \"./validate.js\";\nimport { version } from \"../../index.js\";\nimport { patchValueToJson } from \"../../values/value.js\";\n\nasync function get(\n  table: string | undefined,\n  id: GenericId<string>,\n  isSystem: boolean,\n) {\n  // If the user doesn\u2019t provide any arguments, we use the new signature in the error message.\n  // We don\u2019t do argument validation on the table argument since it\u2019s not provided when using the old signature.\n  validateArg(id, 1, \"get\", \"id\");\n  if (typeof id !== \"string\") {\n    throw new Error(\n      `Invalid argument \\`id\\` for \\`db.get\\`, expected string but got '${typeof id}': ${\n        id as any\n      }`,\n    );\n  }\n  const args = {\n    id: convexToJson(id),\n    isSystem,\n    version,\n    table,\n  };\n  const syscallJSON = await performAsyncSyscall(\"1.0/get\", args);\n\n  return jsonToConvex(syscallJSON) as GenericDocument;\n}\n\nexport function setupReader(): GenericDatabaseReader<GenericDataModel> {\n  const reader = (\n    isSystem = false,\n  ): GenericDatabaseReader<GenericDataModel> &\n    GenericDatabaseReaderWithTable<GenericDataModel> => {\n    return {\n      get: async (arg0: any, arg1?: any) => {\n        return arg1 !== undefined\n          ? await get(arg0, arg1, isSystem)\n          : await get(undefined, arg0, isSystem);\n      },\n      query: (tableName: string) => {\n        return new TableReader(tableName, isSystem).query();\n      },\n      normalizeId: <TableName extends string>(\n        tableName: TableName,\n        id: string,\n      ): GenericId<TableName> | null => {\n        validateArg(tableName, 1, \"normalizeId\", \"tableName\");\n        validateArg(id, 2, \"normalizeId\", \"id\");\n        const accessingSystemTable = tableName.startsWith(\"_\");\n        if (accessingSystemTable !== isSystem) {\n          throw new Error(\n            `${\n              accessingSystemTable ? \"System\" : \"User\"\n            } tables can only be accessed from db.${\n              isSystem ? \"\" : \"system.\"\n            }normalizeId().`,\n          );\n        }\n        const syscallJSON = performSyscall(\"1.0/db/normalizeId\", {\n          table: tableName,\n          idString: id,\n        });\n        const syscallResult = jsonToConvex(syscallJSON) as any;\n        return syscallResult.id;\n      },\n      // We set the system reader on the next line\n      system: null as any,\n      table: (tableName) => {\n        return new TableReader(tableName, isSystem);\n      },\n    };\n  };\n  const { system: _, ...rest } = reader(true);\n  const r = reader();\n  r.system = rest as any;\n  return r;\n}\n\nasync function insert(tableName: string, value: any) {\n  if (tableName.startsWith(\"_\")) {\n    throw new Error(\"System tables (prefixed with `_`) are read-only.\");\n  }\n  validateArg(tableName, 1, \"insert\", \"table\");\n  validateArg(value, 2, \"insert\", \"value\");\n  const syscallJSON = await performAsyncSyscall(\"1.0/insert\", {\n    table: tableName,\n    value: convexToJson(value),\n  });\n  const syscallResult = jsonToConvex(syscallJSON) as any;\n  return syscallResult._id;\n}\n\nasync function patch(table: string | undefined, id: any, value: any) {\n  validateArg(id, 1, \"patch\", \"id\");\n  validateArg(value, 2, \"patch\", \"value\");\n  await performAsyncSyscall(\"1.0/shallowMerge\", {\n    id: convexToJson(id),\n    value: patchValueToJson(value as Value),\n    table,\n  });\n}\n\nasync function replace(table: string | undefined, id: any, value: any) {\n  validateArg(id, 1, \"replace\", \"id\");\n  validateArg(value, 2, \"replace\", \"value\");\n  await performAsyncSyscall(\"1.0/replace\", {\n    id: convexToJson(id),\n    value: convexToJson(value),\n    table,\n  });\n}\n\nasync function delete_(table: string | undefined, id: any) {\n  validateArg(id, 1, \"delete\", \"id\");\n  await performAsyncSyscall(\"1.0/remove\", {\n    id: convexToJson(id),\n    table,\n  });\n}\n\nexport function setupWriter(): GenericDatabaseWriter<GenericDataModel> &\n  GenericDatabaseWriterWithTable<GenericDataModel> {\n  const reader = setupReader();\n  return {\n    get: reader.get,\n    query: reader.query,\n    normalizeId: reader.normalizeId,\n    system: reader.system as any,\n    insert: async (table, value) => {\n      return await insert(table, value);\n    },\n    patch: async (arg0: any, arg1: any, arg2?: any) => {\n      return arg2 !== undefined\n        ? await patch(arg0, arg1, arg2)\n        : await patch(undefined, arg0, arg1);\n    },\n    replace: async (arg0: any, arg1: any, arg2?: any) => {\n      return arg2 !== undefined\n        ? await replace(arg0, arg1, arg2)\n        : await replace(undefined, arg0, arg1);\n    },\n    delete: async (arg0: any, arg1?: any) => {\n      return arg1 !== undefined\n        ? await delete_(arg0, arg1)\n        : await delete_(undefined, arg0);\n    },\n    table: (tableName) => {\n      return new TableWriter(tableName, false);\n    },\n  };\n}\n\nclass TableReader {\n  constructor(\n    protected readonly tableName: string,\n    protected readonly isSystem: boolean,\n  ) {}\n\n  async get(id: GenericId<string>) {\n    return get(this.tableName, id, this.isSystem);\n  }\n\n  query() {\n    const accessingSystemTable = this.tableName.startsWith(\"_\");\n    if (accessingSystemTable !== this.isSystem) {\n      throw new Error(\n        `${\n          accessingSystemTable ? \"System\" : \"User\"\n        } tables can only be accessed from db.${\n          this.isSystem ? \"\" : \"system.\"\n        }query().`,\n      );\n    }\n    return new QueryInitializerImpl(this.tableName);\n  }\n}\n\nclass TableWriter extends TableReader {\n  async insert(value: any) {\n    return insert(this.tableName, value);\n  }\n  async patch(id: any, value: any) {\n    return patch(this.tableName, id, value);\n  }\n  async replace(id: any, value: any) {\n    return replace(this.tableName, id, value);\n  }\n  async delete(id: any) {\n    return delete_(this.tableName, id);\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import {\n  convexToJson,\n  GenericId,\n  jsonToConvex,\n  Value,\n} from \"../../values/index.js\";\nimport { performAsyncSyscall, performSyscall } from \"./syscall.js\";\nimport {\n  GenericDatabaseReader,\n  GenericDatabaseReaderWithTable,\n  GenericDatabaseWriter,\n  GenericDatabaseWriterWithTable,\n} from \"../database.js\";\nimport { QueryInitializerImpl } from \"./query_impl.js\";\nimport { GenericDataModel, GenericDocument } from \"../data_model.js\";\nimport { validateArg } from \"./validate.js\";\nimport { version } from \"../../index.js\";\nimport { commitTsPlaceholder, patchValueToJson } from \"../../values/value.js\";\n\nasync function get(\n  table: string | undefined,\n  id: GenericId<string>,\n  isSystem: boolean,\n) {\n  // If the user doesn\u2019t provide any arguments, we use the new signature in the error message.\n  // We don\u2019t do argument validation on the table argument since it\u2019s not provided when using the old signature.\n  validateArg(id, 1, \"get\", \"id\");\n  if (typeof id !== \"string\") {\n    throw new Error(\n      `Invalid argument \\`id\\` for \\`db.get\\`, expected string but got '${typeof id}': ${\n        id as any\n      }`,\n    );\n  }\n  const args = {\n    id: convexToJson(id),\n    isSystem,\n    version,\n    table,\n  };\n  const syscallJSON = await performAsyncSyscall(\"1.0/get\", args);\n\n  return jsonToConvex(syscallJSON) as GenericDocument;\n}\n\nexport function setupReader(): GenericDatabaseReader<GenericDataModel> {\n  const reader = (\n    isSystem = false,\n  ): GenericDatabaseReader<GenericDataModel> &\n    GenericDatabaseReaderWithTable<GenericDataModel> => {\n    return {\n      get: async (arg0: any, arg1?: any) => {\n        return arg1 !== undefined\n          ? await get(arg0, arg1, isSystem)\n          : await get(undefined, arg0, isSystem);\n      },\n      query: (tableName: string) => {\n        return new TableReader(tableName, isSystem).query();\n      },\n      normalizeId: <TableName extends string>(\n        tableName: TableName,\n        id: string,\n      ): GenericId<TableName> | null => {\n        validateArg(tableName, 1, \"normalizeId\", \"tableName\");\n        validateArg(id, 2, \"normalizeId\", \"id\");\n        const accessingSystemTable = tableName.startsWith(\"_\");\n        if (accessingSystemTable !== isSystem) {\n          throw new Error(\n            `${\n              accessingSystemTable ? \"System\" : \"User\"\n            } tables can only be accessed from db.${\n              isSystem ? \"\" : \"system.\"\n            }normalizeId().`,\n          );\n        }\n        const syscallJSON = performSyscall(\"1.0/db/normalizeId\", {\n          table: tableName,\n          idString: id,\n        });\n        const syscallResult = jsonToConvex(syscallJSON) as any;\n        return syscallResult.id;\n      },\n      // We set the system reader on the next line\n      system: null as any,\n      table: (tableName) => {\n        return new TableReader(tableName, isSystem);\n      },\n    };\n  };\n  const { system: _, ...rest } = reader(true);\n  const r = reader();\n  r.system = rest as any;\n  return r;\n}\n\nasync function insert(tableName: string, value: any) {\n  if (tableName.startsWith(\"_\")) {\n    throw new Error(\"System tables (prefixed with `_`) are read-only.\");\n  }\n  validateArg(tableName, 1, \"insert\", \"table\");\n  validateArg(value, 2, \"insert\", \"value\");\n  const syscallJSON = await performAsyncSyscall(\"1.0/insert\", {\n    table: tableName,\n    value: convexToJson(value),\n  });\n  const syscallResult = jsonToConvex(syscallJSON) as any;\n  return syscallResult._id;\n}\n\nasync function patch(table: string | undefined, id: any, value: any) {\n  validateArg(id, 1, \"patch\", \"id\");\n  validateArg(value, 2, \"patch\", \"value\");\n  await performAsyncSyscall(\"1.0/shallowMerge\", {\n    id: convexToJson(id),\n    value: patchValueToJson(value as Value),\n    table,\n  });\n}\n\nasync function replace(table: string | undefined, id: any, value: any) {\n  validateArg(id, 1, \"replace\", \"id\");\n  validateArg(value, 2, \"replace\", \"value\");\n  await performAsyncSyscall(\"1.0/replace\", {\n    id: convexToJson(id),\n    value: convexToJson(value),\n    table,\n  });\n}\n\nasync function delete_(table: string | undefined, id: any) {\n  validateArg(id, 1, \"delete\", \"id\");\n  await performAsyncSyscall(\"1.0/remove\", {\n    id: convexToJson(id),\n    table,\n  });\n}\n\nexport function setupWriter(): GenericDatabaseWriter<GenericDataModel> &\n  GenericDatabaseWriterWithTable<GenericDataModel> {\n  const reader = setupReader();\n  return {\n    get: reader.get,\n    query: reader.query,\n    normalizeId: reader.normalizeId,\n    system: reader.system as any,\n    insert: async (table, value) => {\n      return await insert(table, value);\n    },\n    patch: async (arg0: any, arg1: any, arg2?: any) => {\n      return arg2 !== undefined\n        ? await patch(arg0, arg1, arg2)\n        : await patch(undefined, arg0, arg1);\n    },\n    replace: async (arg0: any, arg1: any, arg2?: any) => {\n      return arg2 !== undefined\n        ? await replace(arg0, arg1, arg2)\n        : await replace(undefined, arg0, arg1);\n    },\n    delete: async (arg0: any, arg1?: any) => {\n      return arg1 !== undefined\n        ? await delete_(arg0, arg1)\n        : await delete_(undefined, arg0);\n    },\n    table: (tableName) => {\n      return new TableWriter(tableName, false);\n    },\n    vars: {\n      commitTs: commitTsPlaceholder,\n    },\n  };\n}\n\nclass TableReader {\n  constructor(\n    protected readonly tableName: string,\n    protected readonly isSystem: boolean,\n  ) {}\n\n  async get(id: GenericId<string>) {\n    return get(this.tableName, id, this.isSystem);\n  }\n\n  query() {\n    const accessingSystemTable = this.tableName.startsWith(\"_\");\n    if (accessingSystemTable !== this.isSystem) {\n      throw new Error(\n        `${\n          accessingSystemTable ? \"System\" : \"User\"\n        } tables can only be accessed from db.${\n          this.isSystem ? \"\" : \"system.\"\n        }query().`,\n      );\n    }\n    return new QueryInitializerImpl(this.tableName);\n  }\n}\n\nclass TableWriter extends TableReader {\n  async insert(value: any) {\n    return insert(this.tableName, value);\n  }\n  async patch(id: any, value: any) {\n    return patch(this.tableName, id, value);\n  }\n  async replace(id: any, value: any) {\n    return replace(this.tableName, id, value);\n  }\n  async delete(id: any) {\n    return delete_(this.tableName, id);\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/cjs/server/log.js

@@ -25,6 +25,7 @@ var import_audit_logging = require("./audit_logging.js");
 var import_logVars = require("./logVars.js");
 const log = {
   audit: import_audit_logging.audit,
-  vars: import_logVars.vars
+  vars: import_logVars.vars,
+  internalVars: import_logVars.internalVars
 };
 //# sourceMappingURL=log.js.map

package/dist/cjs/server/log.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/server/log.ts"],
-  "sourcesContent": ["import { audit } from \"./audit_logging.js\";\nimport { vars } from \"./logVars.js\";\n\n// Type annotations are needed for the `unique symbol` types in `vars` to typecheck correctly\ninterface Log {\n  /**\n   * Emit a durable audit log. This functionality is only available for Convex\n   * Enterprise (see https://www.convex.dev/enterprise/pricing).\n   *\n   * Use dynamic variables from `log.vars` to include deferred values that will\n   * be resolved when emitting the log. Cached query hits will replay audit logs\n   * with updated values.\n   * ```ts\n   * await log.audit({\n   *   action: \"document.viewed\",\n   *   actor: { userId },\n   *   source: {\n   *     ip: log.vars.ip,\n   *     userAgent: log.vars.userAgent,\n   *   },\n   *   timestamp: log.vars.now,\n   * });\n   * ```\n   *\n   * The log body must be JSON-serializable.\n   */\n  audit: typeof audit;\n  vars: typeof vars;\n}\n\nexport const log: Log = {\n  audit,\n  vars,\n};\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,2BAAsB;AACtB,qBAAqB;AA6Bd,MAAM,MAAW;AAAA,EACtB;AAAA,EACA;AACF;",
+  "sourcesContent": ["import { audit } from \"./audit_logging.js\";\nimport { internalVars, vars } from \"./logVars.js\";\n\n// Type annotations are needed for the `unique symbol` types in `vars` to typecheck correctly\ninterface Log {\n  /**\n   * Emit a durable audit log. This functionality is only available for Convex\n   * Enterprise (see https://www.convex.dev/enterprise/pricing).\n   *\n   * Use dynamic variables from `log.vars` to include deferred values that will\n   * be resolved when emitting the log. Cached query hits will replay audit logs\n   * with updated values.\n   * ```ts\n   * await log.audit({\n   *   action: \"document.viewed\",\n   *   actor: { userId },\n   *   source: {\n   *     ip: log.vars.ip,\n   *     userAgent: log.vars.userAgent,\n   *   },\n   *   timestamp: log.vars.now,\n   * });\n   * ```\n   *\n   * The log body must be JSON-serializable.\n   */\n  audit: typeof audit;\n  vars: typeof vars;\n  /** @internal */\n  internalVars: typeof internalVars;\n}\n\nexport const log: Log = {\n  audit,\n  vars,\n  internalVars,\n};\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,2BAAsB;AACtB,qBAAmC;AA+B5B,MAAM,MAAW;AAAA,EACtB;AAAA,EACA;AAAA,EACA;AACF;",
   "names": []
 }

package/dist/cjs/server/logVars.js

@@ -18,6 +18,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var logVars_exports = {};
 __export(logVars_exports, {
+  internalVars: () => internalVars,
   varNames: () => varNames,
   vars: () => vars
 });
@@ -26,11 +27,13 @@ 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");
 const varNames = {
   [REQUEST_ID]: "requestId",
   [IP]: "ip",
   [USER_AGENT]: "userAgent",
-  [NOW]: "now"
+  [NOW]: "now",
+  [CONVEX_ACTOR]: "convexActor"
 };
 const vars = {
   /** Resolved to the request ID. */
@@ -45,4 +48,12 @@ const vars = {
    */
   now: NOW
 };
+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
+};
 //# sourceMappingURL=logVars.js.map

package/dist/cjs/server/logVars.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/server/logVars.ts"],
-  "sourcesContent": ["const REQUEST_ID = Symbol(\"var.requestId\");\nconst IP = Symbol(\"var.ip\");\nconst USER_AGENT = Symbol(\"var.userAgent\");\nconst NOW = Symbol(\"var.now\");\n\nexport type LogVar =\n  | typeof REQUEST_ID\n  | typeof IP\n  | typeof USER_AGENT\n  | typeof NOW;\n\nexport const varNames: Record<symbol, string> = {\n  [REQUEST_ID]: \"requestId\",\n  [IP]: \"ip\",\n  [USER_AGENT]: \"userAgent\",\n  [NOW]: \"now\",\n};\n\nexport const vars = {\n  /** Resolved to the request ID. */\n  requestId: REQUEST_ID,\n  /** Resolved to the client's IP address. */\n  ip: IP,\n  /** Resolved to the client's User-Agent header. */\n  userAgent: USER_AGENT,\n  /**\n   * Resolved to the current server timestamp, as milliseconds from the\n   * Unix epoch.\n   */\n  now: NOW,\n} as const;\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAAM,aAAa,OAAO,eAAe;AACzC,MAAM,KAAK,OAAO,QAAQ;AAC1B,MAAM,aAAa,OAAO,eAAe;AACzC,MAAM,MAAM,OAAO,SAAS;AAQrB,MAAM,WAAmC;AAAA,EAC9C,CAAC,UAAU,GAAG;AAAA,EACd,CAAC,EAAE,GAAG;AAAA,EACN,CAAC,UAAU,GAAG;AAAA,EACd,CAAC,GAAG,GAAG;AACT;AAEO,MAAM,OAAO;AAAA;AAAA,EAElB,WAAW;AAAA;AAAA,EAEX,IAAI;AAAA;AAAA,EAEJ,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA,EAKX,KAAK;AACP;",
+  "sourcesContent": ["const REQUEST_ID = Symbol(\"var.requestId\");\nconst IP = Symbol(\"var.ip\");\nconst USER_AGENT = Symbol(\"var.userAgent\");\nconst NOW = Symbol(\"var.now\");\nconst CONVEX_ACTOR = Symbol(\"var.convexActor\");\n\nexport type LogVar =\n  | typeof REQUEST_ID\n  | typeof IP\n  | typeof USER_AGENT\n  | typeof NOW\n  | typeof CONVEX_ACTOR;\n\nexport const varNames: Record<symbol, string> = {\n  [REQUEST_ID]: \"requestId\",\n  [IP]: \"ip\",\n  [USER_AGENT]: \"userAgent\",\n  [NOW]: \"now\",\n  [CONVEX_ACTOR]: \"convexActor\",\n};\n\nexport const vars = {\n  /** Resolved to the request ID. */\n  requestId: REQUEST_ID,\n  /** Resolved to the client's IP address. */\n  ip: IP,\n  /** Resolved to the client's User-Agent header. */\n  userAgent: USER_AGENT,\n  /**\n   * Resolved to the current server timestamp, as milliseconds from the\n   * Unix epoch.\n   */\n  now: NOW,\n} as const;\n\n/**\n * Internal-only log vars, surfaced via `log.internalVars`. These are kept out\n * of the public `log.vars` surface.\n */\nexport const internalVars = {\n  /**\n   * If the function was invoked using admin auth (either directly or while\n   * acting as an end user, e.g. from the dashboard), resolved to information\n   * about the admin. Otherwise, resolved to `null`.\n   */\n  convexActor: CONVEX_ACTOR,\n} as const;\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAAM,aAAa,OAAO,eAAe;AACzC,MAAM,KAAK,OAAO,QAAQ;AAC1B,MAAM,aAAa,OAAO,eAAe;AACzC,MAAM,MAAM,OAAO,SAAS;AAC5B,MAAM,eAAe,OAAO,iBAAiB;AAStC,MAAM,WAAmC;AAAA,EAC9C,CAAC,UAAU,GAAG;AAAA,EACd,CAAC,EAAE,GAAG;AAAA,EACN,CAAC,UAAU,GAAG;AAAA,EACd,CAAC,GAAG,GAAG;AAAA,EACP,CAAC,YAAY,GAAG;AAClB;AAEO,MAAM,OAAO;AAAA;AAAA,EAElB,WAAW;AAAA;AAAA,EAEX,IAAI;AAAA;AAAA,EAEJ,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA,EAKX,KAAK;AACP;AAMO,MAAM,eAAe;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAM1B,aAAa;AACf;",
   "names": []
 }

package/dist/cjs/server/meta.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/server/meta.ts"],
-  "sourcesContent": ["import { FunctionType } from \"./api.js\";\nimport { FunctionVisibility } from \"./registration.js\";\n\n/**\n * Used and remaining amounts for a single transaction limit.\n *\n * @public\n */\nexport type TransactionMetric = {\n  used: number;\n  remaining: number;\n};\n\n/**\n * The remaining headroom for a transaction before hitting limits.\n *\n * See https://docs.convex.dev/production/state/limits\n *\n * @public\n */\nexport type TransactionMetrics = {\n  bytesRead: TransactionMetric;\n  bytesWritten: TransactionMetric;\n  databaseQueries: TransactionMetric;\n  documentsRead: TransactionMetric;\n  documentsWritten: TransactionMetric;\n  functionsScheduled: TransactionMetric;\n  scheduledFunctionArgsBytes: TransactionMetric;\n};\n\n/**\n * Custom limits for a nested transaction. Each field specifies the absolute\n * maximum allowed for the nested function call. Values are capped at the\n * global transaction limits, so they can only lower limits, never raise them.\n *\n * @public\n */\nexport interface TransactionLimits {\n  bytesRead?: number;\n  bytesWritten?: number;\n  databaseQueries?: number;\n  documentsRead?: number;\n  documentsWritten?: number;\n  functionsScheduled?: number;\n  scheduledFunctionArgsBytes?: number;\n}\n\n/**\n * Metadata about the currently executing Convex function.\n *\n * @public\n */\nexport type FunctionMetadata = {\n  /**\n   * The name of the function, in the format `\"path/to/module:functionName\"`\n   */\n  name: string;\n  /**\n   * The path of the component this function belongs to.\n   * This is an empty string `\"\"` for the app.\n   */\n  componentPath: string;\n  /** Whether it's a query, mutation, or action. */\n  type: FunctionType;\n  /** Whether the function is public or internal. */\n  visibility: FunctionVisibility;\n};\n\n/**\n * Metadata about the deployment this function is running on.\n *\n * @public\n */\nexport type DeploymentMetadata = {\n  /**\n   * The deployment name, e.g. `\"tall-tiger-123\"` for cloud deployments,\n   * `\"local-my_team-my_project\"` for local deployments, or\n   * `\"anonymous-*\"` for anonymous deployments.\n   */\n  name: string;\n  /**\n   * The deployment region, e.g. `\"aws-us-east-1\"`.\n   * `null` for local and self-hosted deployments.\n   */\n  region: string | null;\n  /**\n   * The deployment class, e.g. `\"s16\"`, `\"s256\"`, or `\"d1024\"`.\n   */\n  class: \"s16\" | \"s256\" | \"d1024\";\n};\n\n/**\n * Metadata about the HTTP request that triggered the current function execution.\n *\n * `ip` and `userAgent` are `null` when the function was not triggered by an\n * HTTP request (e.g. scheduled jobs or cron jobs).\n *\n * Functions called from within a function (i.e. using `runMutation` or\n * `runAction`) will have the same request metadata as the parent function.\n *\n * @public\n */\nexport type RequestMetadata = {\n  ip: string | null;\n  userAgent: string | null;\n  requestId: string;\n  /**\n   * The ID of the scheduled function document (in `_scheduled_functions`) that\n   * this execution belongs to, or `null` otherwise.\n   *\n   * This is set for the scheduled function itself and for any functions it\n   * calls (e.g. a mutation invoked via `runMutation` by a scheduled action),\n   * propagating the top-level scheduled function's ID down the call tree. It is\n   * `null` when the function was not scheduled.\n   */\n  scheduledFunctionId: string | null;\n  /**\n   * The raw auth token (a JWT) the request was authenticated with, or `null`\n   * when the request was unauthenticated or authenticated with an admin key.\n   *\n   * This is the same token that `ctx.auth.getUserIdentity()` derives its\n   * attributes from.\n   */\n  authToken: string | null;\n};\n\n/**\n * Extra context available in Convex query functions.\n *\n * @public\n */\nexport interface QueryMeta {\n  getFunctionMetadata(): Promise<FunctionMetadata>;\n  getTransactionMetrics(): Promise<TransactionMetrics>;\n  getDeploymentMetadata(): Promise<DeploymentMetadata>;\n}\n\n/**\n * Extra context available in Convex mutation functions.\n *\n * @public\n */\nexport interface MutationMeta extends QueryMeta {\n  getRequestMetadata(): Promise<RequestMetadata>;\n}\n\n/**\n * Extra context available in Convex action functions.\n *\n * @public\n */\nexport interface ActionMeta {\n  getFunctionMetadata(): Promise<FunctionMetadata>;\n  getDeploymentMetadata(): Promise<DeploymentMetadata>;\n  getRequestMetadata(): Promise<RequestMetadata>;\n}\n"],
+  "sourcesContent": ["import { FunctionType } from \"./api.js\";\nimport { FunctionVisibility } from \"./registration.js\";\n\n/**\n * Used and remaining amounts for a single transaction limit.\n *\n * @public\n */\nexport type TransactionMetric = {\n  used: number;\n  remaining: number;\n};\n\n/**\n * The remaining headroom for a transaction before hitting limits.\n *\n * See https://docs.convex.dev/production/state/limits\n *\n * @public\n */\nexport type TransactionMetrics = {\n  bytesRead: TransactionMetric;\n  bytesWritten: TransactionMetric;\n  databaseQueries: TransactionMetric;\n  documentsRead: TransactionMetric;\n  documentsWritten: TransactionMetric;\n  functionsScheduled: TransactionMetric;\n  scheduledFunctionArgsBytes: TransactionMetric;\n};\n\n/**\n * Custom limits for a nested transaction. Each field specifies the absolute\n * maximum allowed for the nested function call. Values are capped at the\n * global transaction limits, so they can only lower limits, never raise them.\n *\n * @public\n */\nexport interface TransactionLimits {\n  bytesRead?: number;\n  bytesWritten?: number;\n  databaseQueries?: number;\n  documentsRead?: number;\n  documentsWritten?: number;\n  functionsScheduled?: number;\n  scheduledFunctionArgsBytes?: number;\n}\n\n/**\n * Metadata about the currently executing Convex function.\n *\n * @public\n */\nexport type FunctionMetadata = {\n  /**\n   * The name of the function, in the format `\"path/to/module:functionName\"`\n   */\n  name: string;\n  /**\n   * The path of the component this function belongs to.\n   * This is an empty string `\"\"` for the app.\n   */\n  componentPath: string;\n  /** Whether it's a query, mutation, or action. */\n  type: FunctionType;\n  /** Whether the function is public or internal. */\n  visibility: FunctionVisibility;\n};\n\n/**\n * Metadata about the deployment this function is running on.\n *\n * @public\n */\nexport type DeploymentMetadata = {\n  /**\n   * The deployment name, e.g. `\"tall-tiger-123\"` for cloud deployments,\n   * `\"local-my_team-my_project\"` for local deployments, or\n   * `\"anonymous-*\"` for anonymous deployments.\n   */\n  name: string;\n  /**\n   * The deployment region, e.g. `\"aws-us-east-1\"`.\n   * `null` for local and self-hosted deployments.\n   */\n  region: string | null;\n  /**\n   * The deployment class, e.g. `\"s16\"`, `\"s256\"`, `\"d1024\"`, or `\"d2048\"`.\n   */\n  class: \"s16\" | \"s256\" | \"d1024\" | \"d2048\";\n};\n\n/**\n * Metadata about the HTTP request that triggered the current function execution.\n *\n * `ip` and `userAgent` are `null` when the function was not triggered by an\n * HTTP request (e.g. scheduled jobs or cron jobs).\n *\n * Functions called from within a function (i.e. using `runMutation` or\n * `runAction`) will have the same request metadata as the parent function.\n *\n * @public\n */\nexport type RequestMetadata = {\n  ip: string | null;\n  userAgent: string | null;\n  requestId: string;\n  /**\n   * The ID of the scheduled function document (in `_scheduled_functions`) that\n   * this execution belongs to, or `null` otherwise.\n   *\n   * This is set for the scheduled function itself and for any functions it\n   * calls (e.g. a mutation invoked via `runMutation` by a scheduled action),\n   * propagating the top-level scheduled function's ID down the call tree. It is\n   * `null` when the function was not scheduled.\n   */\n  scheduledFunctionId: string | null;\n  /**\n   * The raw auth token (a JWT) the request was authenticated with, or `null`\n   * when the request was unauthenticated or authenticated with an admin key.\n   *\n   * This is the same token that `ctx.auth.getUserIdentity()` derives its\n   * attributes from.\n   */\n  authToken: string | null;\n};\n\n/**\n * Extra context available in Convex query functions.\n *\n * @public\n */\nexport interface QueryMeta {\n  getFunctionMetadata(): Promise<FunctionMetadata>;\n  getTransactionMetrics(): Promise<TransactionMetrics>;\n  getDeploymentMetadata(): Promise<DeploymentMetadata>;\n}\n\n/**\n * Extra context available in Convex mutation functions.\n *\n * @public\n */\nexport interface MutationMeta extends QueryMeta {\n  getRequestMetadata(): Promise<RequestMetadata>;\n}\n\n/**\n * Extra context available in Convex action functions.\n *\n * @public\n */\nexport interface ActionMeta {\n  getFunctionMetadata(): Promise<FunctionMetadata>;\n  getDeploymentMetadata(): Promise<DeploymentMetadata>;\n  getRequestMetadata(): Promise<RequestMetadata>;\n}\n"],
   "mappings": ";;;;;;;;;;;;;;AAAA;AAAA;",
   "names": []
 }

package/dist/cjs/values/compare.js

@@ -21,6 +21,7 @@ __export(compare_exports, {
   compareValues: () => compareValues
 });
 module.exports = __toCommonJS(compare_exports);
+var import_value = require("./value.js");
 var import_compare_utf8 = require("./compare_utf8.js");
 function compareValues(k1, k2) {
   return compareAsTuples(makeComparable(k1), makeComparable(k2));
@@ -133,6 +134,9 @@ function makeComparable(v) {
   if (typeof v === "bigint") {
     return [2, v];
   }
+  if (v instanceof import_value.CommitTsPlaceholder) {
+    return [2, import_value.MAX_INT64];
+  }
   if (typeof v === "number") {
     return [3, v];
   }
@@ -150,6 +154,6 @@ function makeComparable(v) {
   }
   const keys = Object.keys(v).sort();
   const pojo = keys.map((k) => [k, v[k]]);
-  return [8, pojo.map(makeComparable)];
+  return [9, pojo.map(makeComparable)];
 }
 //# sourceMappingURL=compare.js.map

package/dist/cjs/values/compare.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/values/compare.ts"],
-  "sourcesContent": ["import { Value } from \"./value.js\";\nimport { compareUTF8 } from \"./compare_utf8.js\";\n\nexport function compareValues(k1: Value | undefined, k2: Value | undefined) {\n  return compareAsTuples(makeComparable(k1), makeComparable(k2));\n}\n\nfunction compareAsTuples<T>(a: [number, T], b: [number, T]): number {\n  if (a[0] === b[0]) {\n    return compareSameTypeValues(a[1], b[1]);\n  } else if (a[0] < b[0]) {\n    return -1;\n  }\n  return 1;\n}\n\nfunction compareSameTypeValues<T>(v1: T, v2: T): number {\n  if (v1 === undefined || v1 === null) {\n    return 0;\n  }\n  if (typeof v1 === \"number\") {\n    if (typeof v2 !== \"number\") {\n      throw new Error(`Unexpected type ${v2 as any}`);\n    }\n    return compareNumbers(v1, v2);\n  }\n  if (typeof v1 === \"string\") {\n    if (typeof v2 !== \"string\") {\n      throw new Error(`Unexpected type ${v2 as any}`);\n    }\n    return compareUTF8(v1, v2);\n  }\n  if (\n    typeof v1 === \"bigint\" ||\n    typeof v1 === \"boolean\" ||\n    typeof v1 === \"string\"\n  ) {\n    return v1 < v2 ? -1 : v1 === v2 ? 0 : 1;\n  }\n  if (!Array.isArray(v1) || !Array.isArray(v2)) {\n    throw new Error(`Unexpected type ${v1 as any}`);\n  }\n  for (let i = 0; i < v1.length && i < v2.length; i++) {\n    const cmp = compareAsTuples(v1[i], v2[i]);\n    if (cmp !== 0) {\n      return cmp;\n    }\n  }\n  if (v1.length < v2.length) {\n    return -1;\n  }\n  if (v1.length > v2.length) {\n    return 1;\n  }\n  return 0;\n}\n\nfunction compareNumbers(v1: number, v2: number): number {\n  // Handle NaN values\n  if (isNaN(v1) || isNaN(v2)) {\n    // Create DataViews for bit-level comparison\n    const buffer1 = new ArrayBuffer(8);\n    const buffer2 = new ArrayBuffer(8);\n    new DataView(buffer1).setFloat64(0, v1, /* little-endian */ true);\n    new DataView(buffer2).setFloat64(0, v2, /* little-endian */ true);\n\n    // Read as BigInt to compare bits\n    const v1Bits = BigInt(\n      new DataView(buffer1).getBigInt64(0, /* little-endian */ true),\n    );\n    const v2Bits = BigInt(\n      new DataView(buffer2).getBigInt64(0, /* little-endian */ true),\n    );\n\n    // The sign bit is the most significant bit (bit 63)\n    const v1Sign = (v1Bits & 0x8000000000000000n) !== 0n;\n    const v2Sign = (v2Bits & 0x8000000000000000n) !== 0n;\n\n    // If one value is NaN and the other isn't, use sign bits first\n    if (isNaN(v1) !== isNaN(v2)) {\n      // If v1 is NaN, compare based on sign bits\n      if (isNaN(v1)) {\n        return v1Sign ? -1 : 1;\n      }\n      // If v2 is NaN, compare based on sign bits\n      return v2Sign ? 1 : -1;\n    }\n\n    // If both are NaN, compare their binary representations\n    if (v1Sign !== v2Sign) {\n      return v1Sign ? -1 : 1; // true means negative\n    }\n    return v1Bits < v2Bits ? -1 : v1Bits === v2Bits ? 0 : 1;\n  }\n\n  if (Object.is(v1, v2)) {\n    return 0;\n  }\n\n  if (Object.is(v1, -0)) {\n    return Object.is(v2, 0) ? -1 : -Math.sign(v2);\n  }\n  if (Object.is(v2, -0)) {\n    return Object.is(v1, 0) ? 1 : Math.sign(v1);\n  }\n\n  // Handle regular number comparison\n  return v1 < v2 ? -1 : 1;\n}\n\n// Returns an array which can be compared to other arrays as if they were tuples.\n// For example, [1, null] < [2, 1n] means null sorts before all bigints\n// And [3, 5] < [3, 6] means floats sort as expected\n// And [7, [[5, \"a\"]]] < [7, [[5, \"a\"], [5, \"b\"]]] means arrays sort as expected\nfunction makeComparable(v: Value | undefined): [number, any] {\n  if (v === undefined) {\n    return [0, undefined];\n  }\n  if (v === null) {\n    return [1, null];\n  }\n  if (typeof v === \"bigint\") {\n    return [2, v];\n  }\n  if (typeof v === \"number\") {\n    return [3, v];\n  }\n  if (typeof v === \"boolean\") {\n    return [4, v];\n  }\n  if (typeof v === \"string\") {\n    return [5, v];\n  }\n  if (v instanceof ArrayBuffer) {\n    return [6, Array.from(new Uint8Array(v)).map(makeComparable)];\n  }\n  if (Array.isArray(v)) {\n    return [7, v.map(makeComparable)];\n  }\n  // Otherwise, it's an POJO.\n  const keys = Object.keys(v).sort();\n  const pojo: Value[] = keys.map((k) => [k, v[k]!]);\n  return [8, pojo.map(makeComparable)];\n}\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,0BAA4B;AAErB,SAAS,cAAc,IAAuB,IAAuB;AAC1E,SAAO,gBAAgB,eAAe,EAAE,GAAG,eAAe,EAAE,CAAC;AAC/D;AAEA,SAAS,gBAAmB,GAAgB,GAAwB;AAClE,MAAI,EAAE,CAAC,MAAM,EAAE,CAAC,GAAG;AACjB,WAAO,sBAAsB,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;AAAA,EACzC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG;AACtB,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAEA,SAAS,sBAAyB,IAAO,IAAe;AACtD,MAAI,OAAO,UAAa,OAAO,MAAM;AACnC,WAAO;AAAA,EACT;AACA,MAAI,OAAO,OAAO,UAAU;AAC1B,QAAI,OAAO,OAAO,UAAU;AAC1B,YAAM,IAAI,MAAM,mBAAmB,EAAS,EAAE;AAAA,IAChD;AACA,WAAO,eAAe,IAAI,EAAE;AAAA,EAC9B;AACA,MAAI,OAAO,OAAO,UAAU;AAC1B,QAAI,OAAO,OAAO,UAAU;AAC1B,YAAM,IAAI,MAAM,mBAAmB,EAAS,EAAE;AAAA,IAChD;AACA,eAAO,iCAAY,IAAI,EAAE;AAAA,EAC3B;AACA,MACE,OAAO,OAAO,YACd,OAAO,OAAO,aACd,OAAO,OAAO,UACd;AACA,WAAO,KAAK,KAAK,KAAK,OAAO,KAAK,IAAI;AAAA,EACxC;AACA,MAAI,CAAC,MAAM,QAAQ,EAAE,KAAK,CAAC,MAAM,QAAQ,EAAE,GAAG;AAC5C,UAAM,IAAI,MAAM,mBAAmB,EAAS,EAAE;AAAA,EAChD;AACA,WAAS,IAAI,GAAG,IAAI,GAAG,UAAU,IAAI,GAAG,QAAQ,KAAK;AACnD,UAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC;AACxC,QAAI,QAAQ,GAAG;AACb,aAAO;AAAA,IACT;AAAA,EACF;AACA,MAAI,GAAG,SAAS,GAAG,QAAQ;AACzB,WAAO;AAAA,EACT;AACA,MAAI,GAAG,SAAS,GAAG,QAAQ;AACzB,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAEA,SAAS,eAAe,IAAY,IAAoB;AAEtD,MAAI,MAAM,EAAE,KAAK,MAAM,EAAE,GAAG;AAE1B,UAAM,UAAU,IAAI,YAAY,CAAC;AACjC,UAAM,UAAU,IAAI,YAAY,CAAC;AACjC,QAAI,SAAS,OAAO,EAAE;AAAA,MAAW;AAAA,MAAG;AAAA;AAAA,MAAwB;AAAA,IAAI;AAChE,QAAI,SAAS,OAAO,EAAE;AAAA,MAAW;AAAA,MAAG;AAAA;AAAA,MAAwB;AAAA,IAAI;AAGhE,UAAM,SAAS;AAAA,MACb,IAAI,SAAS,OAAO,EAAE;AAAA,QAAY;AAAA;AAAA,QAAuB;AAAA,MAAI;AAAA,IAC/D;AACA,UAAM,SAAS;AAAA,MACb,IAAI,SAAS,OAAO,EAAE;AAAA,QAAY;AAAA;AAAA,QAAuB;AAAA,MAAI;AAAA,IAC/D;AAGA,UAAM,UAAU,SAAS,yBAAyB;AAClD,UAAM,UAAU,SAAS,yBAAyB;AAGlD,QAAI,MAAM,EAAE,MAAM,MAAM,EAAE,GAAG;AAE3B,UAAI,MAAM,EAAE,GAAG;AACb,eAAO,SAAS,KAAK;AAAA,MACvB;AAEA,aAAO,SAAS,IAAI;AAAA,IACtB;AAGA,QAAI,WAAW,QAAQ;AACrB,aAAO,SAAS,KAAK;AAAA,IACvB;AACA,WAAO,SAAS,SAAS,KAAK,WAAW,SAAS,IAAI;AAAA,EACxD;AAEA,MAAI,OAAO,GAAG,IAAI,EAAE,GAAG;AACrB,WAAO;AAAA,EACT;AAEA,MAAI,OAAO,GAAG,IAAI,EAAE,GAAG;AACrB,WAAO,OAAO,GAAG,IAAI,CAAC,IAAI,KAAK,CAAC,KAAK,KAAK,EAAE;AAAA,EAC9C;AACA,MAAI,OAAO,GAAG,IAAI,EAAE,GAAG;AACrB,WAAO,OAAO,GAAG,IAAI,CAAC,IAAI,IAAI,KAAK,KAAK,EAAE;AAAA,EAC5C;AAGA,SAAO,KAAK,KAAK,KAAK;AACxB;AAMA,SAAS,eAAe,GAAqC;AAC3D,MAAI,MAAM,QAAW;AACnB,WAAO,CAAC,GAAG,MAAS;AAAA,EACtB;AACA,MAAI,MAAM,MAAM;AACd,WAAO,CAAC,GAAG,IAAI;AAAA,EACjB;AACA,MAAI,OAAO,MAAM,UAAU;AACzB,WAAO,CAAC,GAAG,CAAC;AAAA,EACd;AACA,MAAI,OAAO,MAAM,UAAU;AACzB,WAAO,CAAC,GAAG,CAAC;AAAA,EACd;AACA,MAAI,OAAO,MAAM,WAAW;AAC1B,WAAO,CAAC,GAAG,CAAC;AAAA,EACd;AACA,MAAI,OAAO,MAAM,UAAU;AACzB,WAAO,CAAC,GAAG,CAAC;AAAA,EACd;AACA,MAAI,aAAa,aAAa;AAC5B,WAAO,CAAC,GAAG,MAAM,KAAK,IAAI,WAAW,CAAC,CAAC,EAAE,IAAI,cAAc,CAAC;AAAA,EAC9D;AACA,MAAI,MAAM,QAAQ,CAAC,GAAG;AACpB,WAAO,CAAC,GAAG,EAAE,IAAI,cAAc,CAAC;AAAA,EAClC;AAEA,QAAM,OAAO,OAAO,KAAK,CAAC,EAAE,KAAK;AACjC,QAAM,OAAgB,KAAK,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAE,CAAC;AAChD,SAAO,CAAC,GAAG,KAAK,IAAI,cAAc,CAAC;AACrC;",
+  "sourcesContent": ["import { CommitTsPlaceholder, MAX_INT64, Value } from \"./value.js\";\nimport { compareUTF8 } from \"./compare_utf8.js\";\n\nexport function compareValues(k1: Value | undefined, k2: Value | undefined) {\n  return compareAsTuples(makeComparable(k1), makeComparable(k2));\n}\n\nfunction compareAsTuples<T>(a: [number, T], b: [number, T]): number {\n  if (a[0] === b[0]) {\n    return compareSameTypeValues(a[1], b[1]);\n  } else if (a[0] < b[0]) {\n    return -1;\n  }\n  return 1;\n}\n\nfunction compareSameTypeValues<T>(v1: T, v2: T): number {\n  if (v1 === undefined || v1 === null) {\n    return 0;\n  }\n  if (typeof v1 === \"number\") {\n    if (typeof v2 !== \"number\") {\n      throw new Error(`Unexpected type ${v2 as any}`);\n    }\n    return compareNumbers(v1, v2);\n  }\n  if (typeof v1 === \"string\") {\n    if (typeof v2 !== \"string\") {\n      throw new Error(`Unexpected type ${v2 as any}`);\n    }\n    return compareUTF8(v1, v2);\n  }\n  if (\n    typeof v1 === \"bigint\" ||\n    typeof v1 === \"boolean\" ||\n    typeof v1 === \"string\"\n  ) {\n    return v1 < v2 ? -1 : v1 === v2 ? 0 : 1;\n  }\n  if (!Array.isArray(v1) || !Array.isArray(v2)) {\n    throw new Error(`Unexpected type ${v1 as any}`);\n  }\n  for (let i = 0; i < v1.length && i < v2.length; i++) {\n    const cmp = compareAsTuples(v1[i], v2[i]);\n    if (cmp !== 0) {\n      return cmp;\n    }\n  }\n  if (v1.length < v2.length) {\n    return -1;\n  }\n  if (v1.length > v2.length) {\n    return 1;\n  }\n  return 0;\n}\n\nfunction compareNumbers(v1: number, v2: number): number {\n  // Handle NaN values\n  if (isNaN(v1) || isNaN(v2)) {\n    // Create DataViews for bit-level comparison\n    const buffer1 = new ArrayBuffer(8);\n    const buffer2 = new ArrayBuffer(8);\n    new DataView(buffer1).setFloat64(0, v1, /* little-endian */ true);\n    new DataView(buffer2).setFloat64(0, v2, /* little-endian */ true);\n\n    // Read as BigInt to compare bits\n    const v1Bits = BigInt(\n      new DataView(buffer1).getBigInt64(0, /* little-endian */ true),\n    );\n    const v2Bits = BigInt(\n      new DataView(buffer2).getBigInt64(0, /* little-endian */ true),\n    );\n\n    // The sign bit is the most significant bit (bit 63)\n    const v1Sign = (v1Bits & 0x8000000000000000n) !== 0n;\n    const v2Sign = (v2Bits & 0x8000000000000000n) !== 0n;\n\n    // If one value is NaN and the other isn't, use sign bits first\n    if (isNaN(v1) !== isNaN(v2)) {\n      // If v1 is NaN, compare based on sign bits\n      if (isNaN(v1)) {\n        return v1Sign ? -1 : 1;\n      }\n      // If v2 is NaN, compare based on sign bits\n      return v2Sign ? 1 : -1;\n    }\n\n    // If both are NaN, compare their binary representations\n    if (v1Sign !== v2Sign) {\n      return v1Sign ? -1 : 1; // true means negative\n    }\n    return v1Bits < v2Bits ? -1 : v1Bits === v2Bits ? 0 : 1;\n  }\n\n  if (Object.is(v1, v2)) {\n    return 0;\n  }\n\n  if (Object.is(v1, -0)) {\n    return Object.is(v2, 0) ? -1 : -Math.sign(v2);\n  }\n  if (Object.is(v2, -0)) {\n    return Object.is(v1, 0) ? 1 : Math.sign(v1);\n  }\n\n  // Handle regular number comparison\n  return v1 < v2 ? -1 : 1;\n}\n\n// Returns an array which can be compared to other arrays as if they were tuples.\n// For example, [1, null] < [2, 1n] means null sorts before all bigints\n// And [3, 5] < [3, 6] means floats sort as expected\n// And [7, [[5, \"a\"]]] < [7, [[5, \"a\"], [5, \"b\"]]] means arrays sort as expected\nfunction makeComparable(v: Value | undefined): [number, any] {\n  if (v === undefined) {\n    return [0, undefined];\n  }\n  if (v === null) {\n    return [1, null];\n  }\n  if (typeof v === \"bigint\") {\n    return [2, v];\n  }\n  if (v instanceof CommitTsPlaceholder) {\n    return [2, MAX_INT64];\n  }\n  if (typeof v === \"number\") {\n    return [3, v];\n  }\n  if (typeof v === \"boolean\") {\n    return [4, v];\n  }\n  if (typeof v === \"string\") {\n    return [5, v];\n  }\n  if (v instanceof ArrayBuffer) {\n    return [6, Array.from(new Uint8Array(v)).map(makeComparable)];\n  }\n  if (Array.isArray(v)) {\n    return [7, v.map(makeComparable)];\n  }\n  // Otherwise, it's an POJO.\n  const keys = Object.keys(v).sort();\n  const pojo: Value[] = keys.map((k) => [k, v[k]!]);\n  return [9, pojo.map(makeComparable)];\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAAsD;AACtD,0BAA4B;AAErB,SAAS,cAAc,IAAuB,IAAuB;AAC1E,SAAO,gBAAgB,eAAe,EAAE,GAAG,eAAe,EAAE,CAAC;AAC/D;AAEA,SAAS,gBAAmB,GAAgB,GAAwB;AAClE,MAAI,EAAE,CAAC,MAAM,EAAE,CAAC,GAAG;AACjB,WAAO,sBAAsB,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;AAAA,EACzC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG;AACtB,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAEA,SAAS,sBAAyB,IAAO,IAAe;AACtD,MAAI,OAAO,UAAa,OAAO,MAAM;AACnC,WAAO;AAAA,EACT;AACA,MAAI,OAAO,OAAO,UAAU;AAC1B,QAAI,OAAO,OAAO,UAAU;AAC1B,YAAM,IAAI,MAAM,mBAAmB,EAAS,EAAE;AAAA,IAChD;AACA,WAAO,eAAe,IAAI,EAAE;AAAA,EAC9B;AACA,MAAI,OAAO,OAAO,UAAU;AAC1B,QAAI,OAAO,OAAO,UAAU;AAC1B,YAAM,IAAI,MAAM,mBAAmB,EAAS,EAAE;AAAA,IAChD;AACA,eAAO,iCAAY,IAAI,EAAE;AAAA,EAC3B;AACA,MACE,OAAO,OAAO,YACd,OAAO,OAAO,aACd,OAAO,OAAO,UACd;AACA,WAAO,KAAK,KAAK,KAAK,OAAO,KAAK,IAAI;AAAA,EACxC;AACA,MAAI,CAAC,MAAM,QAAQ,EAAE,KAAK,CAAC,MAAM,QAAQ,EAAE,GAAG;AAC5C,UAAM,IAAI,MAAM,mBAAmB,EAAS,EAAE;AAAA,EAChD;AACA,WAAS,IAAI,GAAG,IAAI,GAAG,UAAU,IAAI,GAAG,QAAQ,KAAK;AACnD,UAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC;AACxC,QAAI,QAAQ,GAAG;AACb,aAAO;AAAA,IACT;AAAA,EACF;AACA,MAAI,GAAG,SAAS,GAAG,QAAQ;AACzB,WAAO;AAAA,EACT;AACA,MAAI,GAAG,SAAS,GAAG,QAAQ;AACzB,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAEA,SAAS,eAAe,IAAY,IAAoB;AAEtD,MAAI,MAAM,EAAE,KAAK,MAAM,EAAE,GAAG;AAE1B,UAAM,UAAU,IAAI,YAAY,CAAC;AACjC,UAAM,UAAU,IAAI,YAAY,CAAC;AACjC,QAAI,SAAS,OAAO,EAAE;AAAA,MAAW;AAAA,MAAG;AAAA;AAAA,MAAwB;AAAA,IAAI;AAChE,QAAI,SAAS,OAAO,EAAE;AAAA,MAAW;AAAA,MAAG;AAAA;AAAA,MAAwB;AAAA,IAAI;AAGhE,UAAM,SAAS;AAAA,MACb,IAAI,SAAS,OAAO,EAAE;AAAA,QAAY;AAAA;AAAA,QAAuB;AAAA,MAAI;AAAA,IAC/D;AACA,UAAM,SAAS;AAAA,MACb,IAAI,SAAS,OAAO,EAAE;AAAA,QAAY;AAAA;AAAA,QAAuB;AAAA,MAAI;AAAA,IAC/D;AAGA,UAAM,UAAU,SAAS,yBAAyB;AAClD,UAAM,UAAU,SAAS,yBAAyB;AAGlD,QAAI,MAAM,EAAE,MAAM,MAAM,EAAE,GAAG;AAE3B,UAAI,MAAM,EAAE,GAAG;AACb,eAAO,SAAS,KAAK;AAAA,MACvB;AAEA,aAAO,SAAS,IAAI;AAAA,IACtB;AAGA,QAAI,WAAW,QAAQ;AACrB,aAAO,SAAS,KAAK;AAAA,IACvB;AACA,WAAO,SAAS,SAAS,KAAK,WAAW,SAAS,IAAI;AAAA,EACxD;AAEA,MAAI,OAAO,GAAG,IAAI,EAAE,GAAG;AACrB,WAAO;AAAA,EACT;AAEA,MAAI,OAAO,GAAG,IAAI,EAAE,GAAG;AACrB,WAAO,OAAO,GAAG,IAAI,CAAC,IAAI,KAAK,CAAC,KAAK,KAAK,EAAE;AAAA,EAC9C;AACA,MAAI,OAAO,GAAG,IAAI,EAAE,GAAG;AACrB,WAAO,OAAO,GAAG,IAAI,CAAC,IAAI,IAAI,KAAK,KAAK,EAAE;AAAA,EAC5C;AAGA,SAAO,KAAK,KAAK,KAAK;AACxB;AAMA,SAAS,eAAe,GAAqC;AAC3D,MAAI,MAAM,QAAW;AACnB,WAAO,CAAC,GAAG,MAAS;AAAA,EACtB;AACA,MAAI,MAAM,MAAM;AACd,WAAO,CAAC,GAAG,IAAI;AAAA,EACjB;AACA,MAAI,OAAO,MAAM,UAAU;AACzB,WAAO,CAAC,GAAG,CAAC;AAAA,EACd;AACA,MAAI,aAAa,kCAAqB;AACpC,WAAO,CAAC,GAAG,sBAAS;AAAA,EACtB;AACA,MAAI,OAAO,MAAM,UAAU;AACzB,WAAO,CAAC,GAAG,CAAC;AAAA,EACd;AACA,MAAI,OAAO,MAAM,WAAW;AAC1B,WAAO,CAAC,GAAG,CAAC;AAAA,EACd;AACA,MAAI,OAAO,MAAM,UAAU;AACzB,WAAO,CAAC,GAAG,CAAC;AAAA,EACd;AACA,MAAI,aAAa,aAAa;AAC5B,WAAO,CAAC,GAAG,MAAM,KAAK,IAAI,WAAW,CAAC,CAAC,EAAE,IAAI,cAAc,CAAC;AAAA,EAC9D;AACA,MAAI,MAAM,QAAQ,CAAC,GAAG;AACpB,WAAO,CAAC,GAAG,EAAE,IAAI,cAAc,CAAC;AAAA,EAClC;AAEA,QAAM,OAAO,OAAO,KAAK,CAAC,EAAE,KAAK;AACjC,QAAM,OAAgB,KAAK,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAE,CAAC;AAChD,SAAO,CAAC,GAAG,KAAK,IAAI,cAAc,CAAC;AACrC;",
   "names": []
 }

package/dist/cjs/values/index.js

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var values_exports = {};
 __export(values_exports, {
   Base64: () => Base64,
+  CommitTsPlaceholder: () => import_value.CommitTsPlaceholder,
   asObjectValidator: () => import_validator.asObjectValidator,
   compareValues: () => import_compare.compareValues,
   convexToJson: () => import_value.convexToJson,

package/dist/cjs/values/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/values/index.ts"],
-  "sourcesContent": ["/**\n * Utilities for working with values stored in Convex.\n *\n * You can see the full set of supported types at\n * [Types](https://docs.convex.dev/using/types).\n * @module\n */\n\nexport { convexToJson, jsonToConvex } from \"./value.js\";\nexport type {\n  Id as GenericId,\n  JSONValue,\n  Value,\n  NumericValue,\n} from \"./value.js\";\nexport { v, asObjectValidator } from \"./validator.js\";\nexport type {\n  AsObjectValidator,\n  GenericValidator,\n  ObjectType,\n  PropertyValidators,\n} from \"./validator.js\";\nexport type {\n  ValidatorJSON,\n  RecordKeyValidatorJSON,\n  RecordValueValidatorJSON,\n  ObjectFieldType,\n  Validator,\n  OptionalProperty,\n  VId,\n  VFloat64,\n  VInt64,\n  VBoolean,\n  VBytes,\n  VString,\n  VNull,\n  VAny,\n  VObject,\n  VLiteral,\n  VArray,\n  VRecord,\n  VUnion,\n  VOptional,\n} from \"./validators.js\";\nimport * as Base64 from \"./base64.js\";\nexport { Base64 };\nexport type { Infer } from \"./validator.js\";\nexport * from \"./errors.js\";\nexport { compareValues } from \"./compare.js\";\nexport { getConvexSize, getDocumentSize } from \"./size.js\";\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAQA,mBAA2C;AAO3C,uBAAqC;AA6BrC,aAAwB;AAGxB,2BAAc,wBA/Cd;AAgDA,qBAA8B;AAC9B,kBAA+C;",
+  "sourcesContent": ["/**\n * Utilities for working with values stored in Convex.\n *\n * You can see the full set of supported types at\n * [Types](https://docs.convex.dev/using/types).\n * @module\n */\n\nexport { convexToJson, jsonToConvex, CommitTsPlaceholder } from \"./value.js\";\nexport type {\n  Id as GenericId,\n  JSONValue,\n  Value,\n  NumericValue,\n} from \"./value.js\";\nexport { v, asObjectValidator } from \"./validator.js\";\nexport type {\n  AsObjectValidator,\n  GenericValidator,\n  ObjectType,\n  PropertyValidators,\n} from \"./validator.js\";\nexport type {\n  ValidatorJSON,\n  RecordKeyValidatorJSON,\n  RecordValueValidatorJSON,\n  ObjectFieldType,\n  Validator,\n  OptionalProperty,\n  VId,\n  VFloat64,\n  VInt64,\n  VCommitTs,\n  VBoolean,\n  VBytes,\n  VString,\n  VNull,\n  VAny,\n  VObject,\n  VLiteral,\n  VArray,\n  VRecord,\n  VUnion,\n  VOptional,\n} from \"./validators.js\";\nimport * as Base64 from \"./base64.js\";\nexport { Base64 };\nexport type { Infer } from \"./validator.js\";\nexport * from \"./errors.js\";\nexport { compareValues } from \"./compare.js\";\nexport { getConvexSize, getDocumentSize } from \"./size.js\";\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAQA,mBAAgE;AAOhE,uBAAqC;AA8BrC,aAAwB;AAGxB,2BAAc,wBAhDd;AAiDA,qBAA8B;AAC9B,kBAA+C;",
   "names": []
 }

package/dist/cjs/values/size.js

@@ -24,6 +24,7 @@ __export(size_exports, {
   getDocumentSize: () => getDocumentSize
 });
 module.exports = __toCommonJS(size_exports);
+var import_value = require("./value.js");
 var import_common = require("../common/index.js");
 function getConvexSize(value) {
   if (value === void 0) {
@@ -38,6 +39,9 @@ function getConvexSize(value) {
   if (typeof value === "bigint") {
     return 9;
   }
+  if (value instanceof import_value.CommitTsPlaceholder) {
+    return 9;
+  }
   if (typeof value === "number") {
     return 9;
   }

package/dist/cjs/values/size.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/values/size.ts"],
-  "sourcesContent": ["/**\n * Calculate the size of a Convex value in bytes.\n *\n * This matches the Rust implementation in crates/value/src/ which is used\n * to compute bandwidth and document size limits.\n *\n * Size formula by type:\n * - Undefined: 0 bytes (not a valid Convex value, but returns 0 for convenience)\n * - Null: 1 byte (type marker)\n * - Boolean: 1 byte (type marker, value stored in marker)\n * - Int64 (bigint): 9 bytes (1 type marker + 8 bytes for 64-bit value)\n * - Float64 (number): 9 bytes (1 type marker + 8 bytes for 64-bit value)\n * - String: 2 + string.length bytes (1 type marker + UTF-8 bytes + 1 null terminator)\n * - Bytes (ArrayBuffer): 2 + bytes.length bytes (1 type marker + bytes + 1 terminator)\n * - Array: 2 + sum(element sizes) bytes (1 type marker + elements + 1 terminator)\n * - Object: 2 + sum(field_name.length + 1 + value.size) bytes\n *           (1 type marker + (field_name + null terminator + value)* + 1 terminator)\n *\n * For documents with system fields (_id and _creationTime), the size includes:\n * - _id field: 4 bytes (field name + null) + string size (2 + 31+ chars)\n * - _creationTime field: 14 bytes (field name + null) + 9 bytes (Float64)\n *\n * @module\n */\n\nimport type { Value } from \"./value.js\";\nimport { isSimpleObject } from \"../common/index.js\";\n\n/**\n * Calculate the size in bytes of a Convex value.\n *\n * This matches how Convex calculates document size for bandwidth tracking\n * and size limit enforcement.\n *\n * @param value - A Convex value to measure\n * @returns The size in bytes\n *\n * @public\n */\nexport function getConvexSize(value: Value | undefined): number {\n  if (value === undefined) {\n    return 0;\n  }\n  if (value === null) {\n    return 1;\n  }\n  if (typeof value === \"boolean\") {\n    return 1;\n  }\n  if (typeof value === \"bigint\") {\n    // Int64: 1 byte type marker + 8 bytes value\n    return 9;\n  }\n  if (typeof value === \"number\") {\n    // Float64: 1 byte type marker + 8 bytes value\n    return 9;\n  }\n  if (typeof value === \"string\") {\n    // String: 1 byte type marker + UTF-8 bytes + 1 byte null terminator\n    // Use TextEncoder to get the actual UTF-8 byte length\n    return 2 + getUtf8ByteLength(value);\n  }\n  if (value instanceof ArrayBuffer) {\n    // Bytes: 1 byte type marker + byte array length + 1 byte terminator\n    return 2 + value.byteLength;\n  }\n  if (Array.isArray(value)) {\n    // Array: 1 byte type marker + sum of element sizes + 1 byte terminator\n    let size = 2; // marker + terminator\n    for (const element of value) {\n      size += getConvexSize(element);\n    }\n    return size;\n  }\n  if (isSimpleObject(value)) {\n    // Object: 1 byte type marker + sum(field_name + null + value) + 1 byte terminator\n    let size = 2; // marker + terminator\n    for (const [key, val] of Object.entries(value)) {\n      if (val !== undefined) {\n        // field name length + null terminator + value size\n        size += getUtf8ByteLength(key) + 1 + getConvexSize(val);\n      }\n    }\n    return size;\n  }\n\n  throw new Error(`Unsupported value type: ${typeof value}`);\n}\n\n/**\n * Threshold above which we use TextEncoder instead of manual counting.\n * For short strings, the JS loop is ~15x faster due to avoiding allocation.\n * For long strings (500+ chars), TextEncoder's native implementation wins.\n */\nconst UTF8_LENGTH_THRESHOLD = 500;\n\n/**\n * Get the UTF-8 byte length of a string.\n *\n * For short strings, counts bytes directly from UTF-16 code units to avoid allocation.\n * For long strings, uses native TextEncoder which is faster despite allocation.\n *\n * @internal\n */\nfunction getUtf8ByteLength(str: string): number {\n  // For long strings, native TextEncoder is faster despite allocation\n  if (str.length > UTF8_LENGTH_THRESHOLD) {\n    return new TextEncoder().encode(str).length;\n  }\n\n  // For short strings, avoid allocation overhead with manual counting\n  let bytes = 0;\n  for (let i = 0; i < str.length; i++) {\n    const code = str.charCodeAt(i);\n    if (code < 0x80) {\n      // ASCII: 1 byte\n      bytes += 1;\n    } else if (code < 0x800) {\n      // 2-byte UTF-8\n      bytes += 2;\n    } else if (code >= 0xd800 && code <= 0xdbff) {\n      // High surrogate - part of a surrogate pair encoding a code point >= U+10000\n      // These are encoded as 4 bytes in UTF-8\n      bytes += 4;\n      i++; // Skip the low surrogate\n    } else {\n      // 3-byte UTF-8 (includes low surrogates if encountered alone, which is invalid but handled)\n      bytes += 3;\n    }\n  }\n  return bytes;\n}\n\n// Note: The exact _id size varies based on the table number:\n// - Tables 1-127: 31 char ID\n// - Tables 128-16383: 32 char ID\n// We use 32 chars as a typical value (tables 128-16383).\nexport const SYSTEM_FIELD_ID_ESTIMATE = 38;\n// _creationTime: field name (14) + Float64 (9)\nexport const SYSTEM_FIELD_CREATION_TIME_SIZE = 23;\n\n/**\n * Calculate the size of a document including system fields.\n *\n * If your value already has _id and _creationTime fields, this will count them\n * in the normal size calculation. Otherwise, it adds the constant overhead\n * for system fields.\n *\n * @param value - A Convex object (document body)\n * @param options - Options for size calculation\n * @returns The size in bytes\n *\n * @public\n */\nexport function getDocumentSize(\n  value: Record<string, Value>,\n  options?: {\n    /**\n     * @internal\n     * Length of the _id field if it is missing. Defaults to standard length.\n     */\n    customIdLength?: number;\n  },\n): number {\n  const baseSize = getConvexSize(value);\n\n  // Check if system fields are already present\n  const hasId = \"_id\" in value && value[\"_id\"] !== undefined;\n  const hasCreationTime =\n    \"_creationTime\" in value && value[\"_creationTime\"] !== undefined;\n\n  if (hasId && hasCreationTime) {\n    return baseSize;\n  }\n\n  // Add size for missing system fields\n  let additionalSize = 0;\n\n  if (!hasId) {\n    if (options?.customIdLength) {\n      // 4 bytes for _id field name + 2 bytes for string overhead.\n      additionalSize += options.customIdLength + 6;\n    } else {\n      additionalSize += SYSTEM_FIELD_ID_ESTIMATE;\n    }\n  }\n\n  if (!hasCreationTime) {\n    additionalSize += SYSTEM_FIELD_CREATION_TIME_SIZE;\n  }\n\n  // The base size includes 2 bytes for object markers, but we need to account\n  // for adding new fields to an existing object structure\n  return baseSize + additionalSize;\n}\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA0BA,oBAA+B;AAaxB,SAAS,cAAc,OAAkC;AAC9D,MAAI,UAAU,QAAW;AACvB,WAAO;AAAA,EACT;AACA,MAAI,UAAU,MAAM;AAClB,WAAO;AAAA,EACT;AACA,MAAI,OAAO,UAAU,WAAW;AAC9B,WAAO;AAAA,EACT;AACA,MAAI,OAAO,UAAU,UAAU;AAE7B,WAAO;AAAA,EACT;AACA,MAAI,OAAO,UAAU,UAAU;AAE7B,WAAO;AAAA,EACT;AACA,MAAI,OAAO,UAAU,UAAU;AAG7B,WAAO,IAAI,kBAAkB,KAAK;AAAA,EACpC;AACA,MAAI,iBAAiB,aAAa;AAEhC,WAAO,IAAI,MAAM;AAAA,EACnB;AACA,MAAI,MAAM,QAAQ,KAAK,GAAG;AAExB,QAAI,OAAO;AACX,eAAW,WAAW,OAAO;AAC3B,cAAQ,cAAc,OAAO;AAAA,IAC/B;AACA,WAAO;AAAA,EACT;AACA,UAAI,8BAAe,KAAK,GAAG;AAEzB,QAAI,OAAO;AACX,eAAW,CAAC,KAAK,GAAG,KAAK,OAAO,QAAQ,KAAK,GAAG;AAC9C,UAAI,QAAQ,QAAW;AAErB,gBAAQ,kBAAkB,GAAG,IAAI,IAAI,cAAc,GAAG;AAAA,MACxD;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAEA,QAAM,IAAI,MAAM,2BAA2B,OAAO,KAAK,EAAE;AAC3D;AAOA,MAAM,wBAAwB;AAU9B,SAAS,kBAAkB,KAAqB;AAE9C,MAAI,IAAI,SAAS,uBAAuB;AACtC,WAAO,IAAI,YAAY,EAAE,OAAO,GAAG,EAAE;AAAA,EACvC;AAGA,MAAI,QAAQ;AACZ,WAAS,IAAI,GAAG,IAAI,IAAI,QAAQ,KAAK;AACnC,UAAM,OAAO,IAAI,WAAW,CAAC;AAC7B,QAAI,OAAO,KAAM;AAEf,eAAS;AAAA,IACX,WAAW,OAAO,MAAO;AAEvB,eAAS;AAAA,IACX,WAAW,QAAQ,SAAU,QAAQ,OAAQ;AAG3C,eAAS;AACT;AAAA,IACF,OAAO;AAEL,eAAS;AAAA,IACX;AAAA,EACF;AACA,SAAO;AACT;AAMO,MAAM,2BAA2B;AAEjC,MAAM,kCAAkC;AAexC,SAAS,gBACd,OACA,SAOQ;AACR,QAAM,WAAW,cAAc,KAAK;AAGpC,QAAM,QAAQ,SAAS,SAAS,MAAM,KAAK,MAAM;AACjD,QAAM,kBACJ,mBAAmB,SAAS,MAAM,eAAe,MAAM;AAEzD,MAAI,SAAS,iBAAiB;AAC5B,WAAO;AAAA,EACT;AAGA,MAAI,iBAAiB;AAErB,MAAI,CAAC,OAAO;AACV,QAAI,SAAS,gBAAgB;AAE3B,wBAAkB,QAAQ,iBAAiB;AAAA,IAC7C,OAAO;AACL,wBAAkB;AAAA,IACpB;AAAA,EACF;AAEA,MAAI,CAAC,iBAAiB;AACpB,sBAAkB;AAAA,EACpB;AAIA,SAAO,WAAW;AACpB;",
+  "sourcesContent": ["/**\n * Calculate the size of a Convex value in bytes.\n *\n * This matches the Rust implementation in crates/value/src/ which is used\n * to compute bandwidth and document size limits.\n *\n * Size formula by type:\n * - Undefined: 0 bytes (not a valid Convex value, but returns 0 for convenience)\n * - Null: 1 byte (type marker)\n * - Boolean: 1 byte (type marker, value stored in marker)\n * - Int64 (bigint): 9 bytes (1 type marker + 8 bytes for 64-bit value)\n * - Float64 (number): 9 bytes (1 type marker + 8 bytes for 64-bit value)\n * - String: 2 + string.length bytes (1 type marker + UTF-8 bytes + 1 null terminator)\n * - Bytes (ArrayBuffer): 2 + bytes.length bytes (1 type marker + bytes + 1 terminator)\n * - Array: 2 + sum(element sizes) bytes (1 type marker + elements + 1 terminator)\n * - Object: 2 + sum(field_name.length + 1 + value.size) bytes\n *           (1 type marker + (field_name + null terminator + value)* + 1 terminator)\n *\n * For documents with system fields (_id and _creationTime), the size includes:\n * - _id field: 4 bytes (field name + null) + string size (2 + 31+ chars)\n * - _creationTime field: 14 bytes (field name + null) + 9 bytes (Float64)\n *\n * @module\n */\n\nimport { CommitTsPlaceholder, type Value } from \"./value.js\";\nimport { isSimpleObject } from \"../common/index.js\";\n\n/**\n * Calculate the size in bytes of a Convex value.\n *\n * This matches how Convex calculates document size for bandwidth tracking\n * and size limit enforcement.\n *\n * @param value - A Convex value to measure\n * @returns The size in bytes\n *\n * @public\n */\nexport function getConvexSize(value: Value | undefined): number {\n  if (value === undefined) {\n    return 0;\n  }\n  if (value === null) {\n    return 1;\n  }\n  if (typeof value === \"boolean\") {\n    return 1;\n  }\n  if (typeof value === \"bigint\") {\n    // Int64: 1 byte type marker + 8 bytes value\n    return 9;\n  }\n  if (value instanceof CommitTsPlaceholder) {\n    // Same as bigint\n    return 9;\n  }\n  if (typeof value === \"number\") {\n    // Float64: 1 byte type marker + 8 bytes value\n    return 9;\n  }\n  if (typeof value === \"string\") {\n    // String: 1 byte type marker + UTF-8 bytes + 1 byte null terminator\n    // Use TextEncoder to get the actual UTF-8 byte length\n    return 2 + getUtf8ByteLength(value);\n  }\n  if (value instanceof ArrayBuffer) {\n    // Bytes: 1 byte type marker + byte array length + 1 byte terminator\n    return 2 + value.byteLength;\n  }\n  if (Array.isArray(value)) {\n    // Array: 1 byte type marker + sum of element sizes + 1 byte terminator\n    let size = 2; // marker + terminator\n    for (const element of value) {\n      size += getConvexSize(element);\n    }\n    return size;\n  }\n  if (isSimpleObject(value)) {\n    // Object: 1 byte type marker + sum(field_name + null + value) + 1 byte terminator\n    let size = 2; // marker + terminator\n    for (const [key, val] of Object.entries(value)) {\n      if (val !== undefined) {\n        // field name length + null terminator + value size\n        size += getUtf8ByteLength(key) + 1 + getConvexSize(val);\n      }\n    }\n    return size;\n  }\n\n  throw new Error(`Unsupported value type: ${typeof value}`);\n}\n\n/**\n * Threshold above which we use TextEncoder instead of manual counting.\n * For short strings, the JS loop is ~15x faster due to avoiding allocation.\n * For long strings (500+ chars), TextEncoder's native implementation wins.\n */\nconst UTF8_LENGTH_THRESHOLD = 500;\n\n/**\n * Get the UTF-8 byte length of a string.\n *\n * For short strings, counts bytes directly from UTF-16 code units to avoid allocation.\n * For long strings, uses native TextEncoder which is faster despite allocation.\n *\n * @internal\n */\nfunction getUtf8ByteLength(str: string): number {\n  // For long strings, native TextEncoder is faster despite allocation\n  if (str.length > UTF8_LENGTH_THRESHOLD) {\n    return new TextEncoder().encode(str).length;\n  }\n\n  // For short strings, avoid allocation overhead with manual counting\n  let bytes = 0;\n  for (let i = 0; i < str.length; i++) {\n    const code = str.charCodeAt(i);\n    if (code < 0x80) {\n      // ASCII: 1 byte\n      bytes += 1;\n    } else if (code < 0x800) {\n      // 2-byte UTF-8\n      bytes += 2;\n    } else if (code >= 0xd800 && code <= 0xdbff) {\n      // High surrogate - part of a surrogate pair encoding a code point >= U+10000\n      // These are encoded as 4 bytes in UTF-8\n      bytes += 4;\n      i++; // Skip the low surrogate\n    } else {\n      // 3-byte UTF-8 (includes low surrogates if encountered alone, which is invalid but handled)\n      bytes += 3;\n    }\n  }\n  return bytes;\n}\n\n// Note: The exact _id size varies based on the table number:\n// - Tables 1-127: 31 char ID\n// - Tables 128-16383: 32 char ID\n// We use 32 chars as a typical value (tables 128-16383).\nexport const SYSTEM_FIELD_ID_ESTIMATE = 38;\n// _creationTime: field name (14) + Float64 (9)\nexport const SYSTEM_FIELD_CREATION_TIME_SIZE = 23;\n\n/**\n * Calculate the size of a document including system fields.\n *\n * If your value already has _id and _creationTime fields, this will count them\n * in the normal size calculation. Otherwise, it adds the constant overhead\n * for system fields.\n *\n * @param value - A Convex object (document body)\n * @param options - Options for size calculation\n * @returns The size in bytes\n *\n * @public\n */\nexport function getDocumentSize(\n  value: Record<string, Value>,\n  options?: {\n    /**\n     * @internal\n     * Length of the _id field if it is missing. Defaults to standard length.\n     */\n    customIdLength?: number;\n  },\n): number {\n  const baseSize = getConvexSize(value);\n\n  // Check if system fields are already present\n  const hasId = \"_id\" in value && value[\"_id\"] !== undefined;\n  const hasCreationTime =\n    \"_creationTime\" in value && value[\"_creationTime\"] !== undefined;\n\n  if (hasId && hasCreationTime) {\n    return baseSize;\n  }\n\n  // Add size for missing system fields\n  let additionalSize = 0;\n\n  if (!hasId) {\n    if (options?.customIdLength) {\n      // 4 bytes for _id field name + 2 bytes for string overhead.\n      additionalSize += options.customIdLength + 6;\n    } else {\n      additionalSize += SYSTEM_FIELD_ID_ESTIMATE;\n    }\n  }\n\n  if (!hasCreationTime) {\n    additionalSize += SYSTEM_FIELD_CREATION_TIME_SIZE;\n  }\n\n  // The base size includes 2 bytes for object markers, but we need to account\n  // for adding new fields to an existing object structure\n  return baseSize + additionalSize;\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAyBA,mBAAgD;AAChD,oBAA+B;AAaxB,SAAS,cAAc,OAAkC;AAC9D,MAAI,UAAU,QAAW;AACvB,WAAO;AAAA,EACT;AACA,MAAI,UAAU,MAAM;AAClB,WAAO;AAAA,EACT;AACA,MAAI,OAAO,UAAU,WAAW;AAC9B,WAAO;AAAA,EACT;AACA,MAAI,OAAO,UAAU,UAAU;AAE7B,WAAO;AAAA,EACT;AACA,MAAI,iBAAiB,kCAAqB;AAExC,WAAO;AAAA,EACT;AACA,MAAI,OAAO,UAAU,UAAU;AAE7B,WAAO;AAAA,EACT;AACA,MAAI,OAAO,UAAU,UAAU;AAG7B,WAAO,IAAI,kBAAkB,KAAK;AAAA,EACpC;AACA,MAAI,iBAAiB,aAAa;AAEhC,WAAO,IAAI,MAAM;AAAA,EACnB;AACA,MAAI,MAAM,QAAQ,KAAK,GAAG;AAExB,QAAI,OAAO;AACX,eAAW,WAAW,OAAO;AAC3B,cAAQ,cAAc,OAAO;AAAA,IAC/B;AACA,WAAO;AAAA,EACT;AACA,UAAI,8BAAe,KAAK,GAAG;AAEzB,QAAI,OAAO;AACX,eAAW,CAAC,KAAK,GAAG,KAAK,OAAO,QAAQ,KAAK,GAAG;AAC9C,UAAI,QAAQ,QAAW;AAErB,gBAAQ,kBAAkB,GAAG,IAAI,IAAI,cAAc,GAAG;AAAA,MACxD;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAEA,QAAM,IAAI,MAAM,2BAA2B,OAAO,KAAK,EAAE;AAC3D;AAOA,MAAM,wBAAwB;AAU9B,SAAS,kBAAkB,KAAqB;AAE9C,MAAI,IAAI,SAAS,uBAAuB;AACtC,WAAO,IAAI,YAAY,EAAE,OAAO,GAAG,EAAE;AAAA,EACvC;AAGA,MAAI,QAAQ;AACZ,WAAS,IAAI,GAAG,IAAI,IAAI,QAAQ,KAAK;AACnC,UAAM,OAAO,IAAI,WAAW,CAAC;AAC7B,QAAI,OAAO,KAAM;AAEf,eAAS;AAAA,IACX,WAAW,OAAO,MAAO;AAEvB,eAAS;AAAA,IACX,WAAW,QAAQ,SAAU,QAAQ,OAAQ;AAG3C,eAAS;AACT;AAAA,IACF,OAAO;AAEL,eAAS;AAAA,IACX;AAAA,EACF;AACA,SAAO;AACT;AAMO,MAAM,2BAA2B;AAEjC,MAAM,kCAAkC;AAexC,SAAS,gBACd,OACA,SAOQ;AACR,QAAM,WAAW,cAAc,KAAK;AAGpC,QAAM,QAAQ,SAAS,SAAS,MAAM,KAAK,MAAM;AACjD,QAAM,kBACJ,mBAAmB,SAAS,MAAM,eAAe,MAAM;AAEzD,MAAI,SAAS,iBAAiB;AAC5B,WAAO;AAAA,EACT;AAGA,MAAI,iBAAiB;AAErB,MAAI,CAAC,OAAO;AACV,QAAI,SAAS,gBAAgB;AAE3B,wBAAkB,QAAQ,iBAAiB;AAAA,IAC7C,OAAO;AACL,wBAAkB;AAAA,IACpB;AAAA,EACF;AAEA,MAAI,CAAC,iBAAiB;AACpB,sBAAkB;AAAA,EACpB;AAIA,SAAO,WAAW;AACpB;",
   "names": []
 }

package/dist/cjs/values/validator.js

@@ -103,6 +103,17 @@ const v = {
   int64: () => {
     return new import_validators.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 import_validators.VCommitTs({ isOptional: "required" });
+  },
   /**
    * Validates that the value is a `boolean`.
    */