convex 1.42.3 → 1.43.0-alpha.0

package/dist/esm/cli/usageLimits.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/cli/usageLimits.ts"],
+  "sourcesContent": ["import { Command, Option } from \"@commander-js/extra-typings\";\nimport { Context } from \"../bundler/context.js\";\nimport { logFinishedStep, logMessage, logOutput } from \"../bundler/log.js\";\nimport { DeploymentSelectionOptions } from \"./lib/api.js\";\nimport { actionDescription } from \"./lib/command.js\";\nimport { ensureHasConvexDependency } from \"./lib/utils/utils.js\";\nimport { withRunningBackend } from \"./lib/localDeployment/run.js\";\nimport { selectEnvDeployment } from \"./env.js\";\nimport {\n  compareMetricNames,\n  createUsageLimit,\n  deleteUsageLimit,\n  findUsageLimitByKey,\n  getCurrentUsage,\n  listUsageLimits,\n  listUsageLimitsWithStatus,\n  metricLabel,\n  updateUsageLimit,\n  USAGE_LIMIT_METRICS,\n  USAGE_LIMIT_TYPES,\n  USAGE_LIMIT_WINDOWS,\n  UsageLimitStatus,\n} from \"./lib/usageLimits.js\";\n\nasync function parseLimit(ctx: Context, value: string): Promise<number> {\n  const limit = Number(value);\n  if (!Number.isInteger(limit) || limit < 1) {\n    return ctx.crash({\n      exitCode: 1,\n      errorType: \"fatal\",\n      printedMessage: `error: --limit must be a positive integer, got \"${value}\".`,\n    });\n  }\n  return limit;\n}\n\nfunction formatTable(\n  header: string[],\n  rows: string[][],\n  rightAlign: number[] = [],\n): string {\n  const right = new Set(rightAlign);\n  const widths = header.map((cell, i) =>\n    Math.max(cell.length, ...rows.map((row) => (row[i] ?? \"\").length)),\n  );\n  const pad = (cell: string, i: number) =>\n    right.has(i) ? cell.padStart(widths[i]) : cell.padEnd(widths[i]);\n  const rule = (left: string, mid: string, r: string) =>\n    left + widths.map((w) => \"\\u2500\".repeat(w + 2)).join(mid) + r;\n  const line = (cells: string[]) =>\n    \"\\u2502 \" +\n    cells.map((cell, i) => pad(cell ?? \"\", i)).join(\" \\u2502 \") +\n    \" \\u2502\";\n  return [\n    rule(\"\\u250c\", \"\\u252c\", \"\\u2510\"),\n    line(header),\n    rule(\"\\u251c\", \"\\u253c\", \"\\u2524\"),\n    ...rows.map(line),\n    rule(\"\\u2514\", \"\\u2534\", \"\\u2518\"),\n  ].join(\"\\n\");\n}\n\nconst NUMBER_FORMAT_COMPACT = new Intl.NumberFormat(\"en-US\", {\n  notation: \"compact\",\n  compactDisplay: \"short\",\n  maximumFractionDigits: 3,\n});\nfunction formatNumberCompact(value: number): string {\n  const formatted = NUMBER_FORMAT_COMPACT.format(value);\n  return formatted === \"-0\" ? \"0\" : formatted;\n}\n\n// Exact, thousands-separated amount for prose (success messages), where a\n// precise value reads clearer than the compact table form.\nconst LIMIT_FORMAT = new Intl.NumberFormat(\"en-US\");\nfunction formatLimitAmount(value: number): string {\n  return LIMIT_FORMAT.format(value);\n}\n\nconst NUMBER_FORMAT = new Intl.NumberFormat(\"en-US\");\nfunction formatNumber(value: number): string {\n  const formatted = NUMBER_FORMAT.format(value);\n  return formatted === \"-0\" ? \"0\" : formatted;\n}\n\nfunction unitFor(amount: number, unit: string): string {\n  return amount === 1 && unit === \"calls\" ? \"call\" : unit;\n}\n\nfunction formatAmount(value: number, unit: string | null): string {\n  return unit === null\n    ? formatNumberCompact(value)\n    : `${formatNumberCompact(value)} ${unitFor(value, unit)}`;\n}\n\nfunction usageLimitRow(limit: UsageLimitStatus): string[] {\n  const currentUsage =\n    limit.currentUsage === null\n      ? \"\\u2014\"\n      : `${formatAmount(limit.currentUsage, limit.unit)} (${formatNumber(\n          Math.round((limit.currentUsage / limit.limit) * 100),\n        )}%)`;\n  return [\n    metricLabel(limit.metric),\n    limit.window,\n    limit.limitType,\n    formatAmount(limit.limit, limit.unit),\n    currentUsage,\n    limit.enabled ? \"yes\" : \"no\",\n    limit.triggered ? \"yes\" : \"no\",\n  ];\n}\n\n// The (metric, window, type) triple uniquely identifies a usage limit. `set`\n// requires all three plus a limit; `update`/`remove` reuse them to locate an\n// existing limit without needing its opaque id.\nconst metricOption = new Option(\n  \"--metric <metric>\",\n  \"The metric to limit.\",\n).choices(USAGE_LIMIT_METRICS);\nconst windowOption = new Option(\n  \"--window <window>\",\n  \"The window the limit is measured over.\",\n).choices(USAGE_LIMIT_WINDOWS);\nconst typeOption = new Option(\n  \"--type <type>\",\n  \"`warning` only notifies; `disable` pauses the deployment when exceeded.\",\n).choices(USAGE_LIMIT_TYPES);\n\nfunction seedStatusMessage(\n  seedStatus: \"pending\" | \"partial\" | \"failed\",\n): string {\n  return seedStatus === \"failed\"\n    ? \"We couldn't load this deployment's historical usage, so the usage shown below may understate its actual usage. Limits are still enforced going forward.\"\n    : \"Historical usage is still being loaded, so the usage shown below may understate this deployment's actual usage. Check back shortly for accurate totals.\";\n}\n\nconst listCmd = new Command(\"list\")\n  .summary(\"List configured usage limits\")\n  .description(\n    [\n      \"List the usage limits configured on your deployment.\",\n      \"\",\n      \"\u2022 List all usage limits: `npx convex deployment usage-limits list`\",\n      \"\u2022 Print as JSON: `npx convex deployment usage-limits list --json`\",\n    ].join(\"\\n\"),\n  )\n  .option(\"--json\", \"Output the usage limits as JSON.\")\n  .configureHelp({ showGlobalOptions: true })\n  .allowExcessArguments(false)\n  .action(async (cmdOptions, cmd) => {\n    const options = cmd.optsWithGlobals() as DeploymentSelectionOptions & {\n      json?: boolean;\n    };\n    const { ctx, deployment } = await selectEnvDeployment(options);\n    await ensureHasConvexDependency(ctx, \"deployment usage-limits list\");\n    await withRunningBackend({\n      ctx,\n      deployment,\n      action: async () => {\n        const { limits, seedStatus } = await listUsageLimitsWithStatus(\n          ctx,\n          deployment,\n        );\n        if (cmdOptions.json) {\n          logOutput(JSON.stringify(limits, null, 2));\n          return;\n        }\n        if (limits.length === 0) {\n          logMessage(\n            `No usage limits configured${deployment.deploymentNotice}.`,\n          );\n          return;\n        }\n        // \"Triggered\" is derived from reported usage, which a non-`complete`\n        // backfill may understate.\n        if (seedStatus !== \"complete\") {\n          logMessage(seedStatusMessage(seedStatus));\n        }\n        logOutput(\n          formatTable(\n            [\n              \"Metric\",\n              \"Window\",\n              \"Type\",\n              \"Limit\",\n              \"Current Usage\",\n              \"Active\",\n              \"Triggered\",\n            ],\n            limits.map(usageLimitRow),\n            [3, 4],\n          ),\n        );\n      },\n    });\n  });\n\nconst setCmd = new Command(\"set\")\n  .summary(\"Create or update a usage limit\")\n  .description(\n    [\n      \"Create a usage limit, or update the existing one for the same\",\n      \"(metric, window, type). At most one limit exists per combination.\",\n      \"\",\n      \"\u2022 Set the amount (creates or replaces it):\",\n      \"  `npx convex deployment usage-limits set --metric functionCalls --window day --type disable --limit 1000000`\",\n      \"\u2022 Deactivate without deleting: add `--inactive` (use `--active` to re-enable).\",\n      \"\u2022 Toggle active state without changing the amount: omit `--limit`.\",\n    ].join(\"\\n\"),\n  )\n  .addOption(metricOption.makeOptionMandatory())\n  .addOption(windowOption.makeOptionMandatory())\n  .addOption(typeOption.makeOptionMandatory())\n  .option(\n    \"--limit <limit>\",\n    \"The limit amount, in the metric's native units. Required when creating; kept as-is when omitted while updating.\",\n  )\n  .option(\"--active\", \"Enforce the limit (the default for a new limit).\")\n  .option(\"--inactive\", \"Create or leave the limit unenforced.\")\n  .configureHelp({ showGlobalOptions: true })\n  .allowExcessArguments(false)\n  .action(async (cmdOptions, cmd) => {\n    const options = cmd.optsWithGlobals() as DeploymentSelectionOptions;\n    const { ctx, deployment } = await selectEnvDeployment(options);\n    await ensureHasConvexDependency(ctx, \"deployment usage-limits set\");\n    if (cmdOptions.active && cmdOptions.inactive) {\n      return ctx.crash({\n        exitCode: 1,\n        errorType: \"fatal\",\n        printedMessage: \"error: Pass at most one of --active and --inactive.\",\n      });\n    }\n    const newLimit =\n      cmdOptions.limit === undefined\n        ? undefined\n        : await parseLimit(ctx, cmdOptions.limit);\n    await withRunningBackend({\n      ctx,\n      deployment,\n      action: async () => {\n        const existing = (await listUsageLimits(ctx, deployment)).find(\n          (l) =>\n            l.metric === cmdOptions.metric &&\n            l.window === cmdOptions.window &&\n            l.limitType === cmdOptions.type,\n        );\n        const label = `${cmdOptions.type} usage limit on ${metricLabel(cmdOptions.metric)} per ${cmdOptions.window}`;\n\n        // No existing limit: create one. A limit amount is required.\n        if (existing === undefined) {\n          if (newLimit === undefined) {\n            return ctx.crash({\n              exitCode: 1,\n              errorType: \"fatal\",\n              printedMessage:\n                \"error: --limit is required when creating a usage limit.\",\n            });\n          }\n          const enabled = !cmdOptions.inactive;\n          const created = await createUsageLimit(ctx, deployment, {\n            metric: cmdOptions.metric,\n            window: cmdOptions.window,\n            limitType: cmdOptions.type,\n            limit: newLimit,\n            enabled,\n          });\n          logFinishedStep(\n            `Created ${label}: ${formatLimitAmount(created.limit)}, ${created.enabled ? \"active\" : \"inactive\"}${deployment.deploymentNotice}.`,\n          );\n          return;\n        }\n\n        // Existing limit: update it, surfacing exactly which fields changed.\n        const enabled = cmdOptions.active\n          ? true\n          : cmdOptions.inactive\n            ? false\n            : existing.enabled;\n        const limit = newLimit ?? existing.limit;\n        const changes: string[] = [];\n        if (limit !== existing.limit) {\n          changes.push(\n            `limit ${formatLimitAmount(existing.limit)} \\u2192 ${formatLimitAmount(limit)}`,\n          );\n        }\n        if (enabled !== existing.enabled) {\n          changes.push(\n            `${existing.enabled ? \"active\" : \"inactive\"} \\u2192 ${enabled ? \"active\" : \"inactive\"}`,\n          );\n        }\n        if (changes.length === 0) {\n          logFinishedStep(\n            `No changes to ${label} (${formatLimitAmount(existing.limit)}, ${existing.enabled ? \"active\" : \"inactive\"})${deployment.deploymentNotice}.`,\n          );\n          return;\n        }\n        await updateUsageLimit(ctx, deployment, existing.id, {\n          metric: existing.metric,\n          window: existing.window,\n          limitType: existing.limitType,\n          limit,\n          enabled,\n        });\n        logFinishedStep(\n          `Updated ${label}: ${changes.join(\", \")}${deployment.deploymentNotice}.`,\n        );\n      },\n    });\n  });\n\nconst removeCmd = new Command(\"remove\")\n  .alias(\"rm\")\n  .alias(\"delete\")\n  .summary(\"Delete a usage limit\")\n  .description(\n    [\n      \"Delete a usage limit, identified by its (metric, window, type).\",\n      \"\",\n      \"\u2022 `npx convex deployment usage-limits remove --metric functionCalls --window day --type warning`\",\n    ].join(\"\\n\"),\n  )\n  .addOption(metricOption.makeOptionMandatory())\n  .addOption(windowOption.makeOptionMandatory())\n  .addOption(typeOption.makeOptionMandatory())\n  .configureHelp({ showGlobalOptions: true })\n  .allowExcessArguments(false)\n  .action(async (cmdOptions, cmd) => {\n    const options = cmd.optsWithGlobals() as DeploymentSelectionOptions;\n    const { ctx, deployment } = await selectEnvDeployment(options);\n    await ensureHasConvexDependency(ctx, \"deployment usage-limits remove\");\n    await withRunningBackend({\n      ctx,\n      deployment,\n      action: async () => {\n        const existing = await findUsageLimitByKey(ctx, deployment, {\n          metric: cmdOptions.metric,\n          window: cmdOptions.window,\n          limitType: cmdOptions.type,\n        });\n        await deleteUsageLimit(ctx, deployment, existing.id);\n        logFinishedStep(\n          `Deleted ${existing.limitType} usage limit on ${metricLabel(existing.metric)} per ${existing.window}${deployment.deploymentNotice}.`,\n        );\n      },\n    });\n  });\n\nexport const usage = new Command(\"usage\")\n  .summary(\"Show current usage for each metric\")\n  .description(\n    [\n      \"Show usage so far in the current day and calendar month for every metric.\",\n      \"\",\n      \"\u2022 Show current usage: `npx convex deployment usage`\",\n      \"\u2022 Print as JSON: `npx convex deployment usage --json`\",\n    ].join(\"\\n\"),\n  )\n  .option(\"--json\", \"Output the usage as JSON.\")\n  .configureHelp({ showGlobalOptions: true })\n  .allowExcessArguments(false)\n  .addDeploymentSelectionOptions(actionDescription(\"Show current usage for\"))\n  .action(async (cmdOptions, cmd) => {\n    const options = cmd.optsWithGlobals() as DeploymentSelectionOptions & {\n      json?: boolean;\n    };\n    const { ctx, deployment } = await selectEnvDeployment(options);\n    await ensureHasConvexDependency(ctx, \"deployment usage\");\n    await withRunningBackend({\n      ctx,\n      deployment,\n      action: async () => {\n        const usage = await getCurrentUsage(ctx, deployment);\n        if (cmdOptions.json) {\n          logOutput(JSON.stringify(usage, null, 2));\n          return;\n        }\n        // A non-`complete` backfill means the numbers can understate reality.\n        if (usage.seedStatus !== \"complete\") {\n          logMessage(seedStatusMessage(usage.seedStatus));\n        }\n        logOutput(\n          formatTable(\n            [\"Metric\", \"Day\", \"Month\"],\n            Object.entries(usage.metrics)\n              .sort(([a], [b]) => compareMetricNames(a, b))\n              .map(([metric, m]) => [\n                metricLabel(metric),\n                formatAmount(m.usage.current_day, m.unit),\n                formatAmount(m.usage.current_month, m.unit),\n              ]),\n          ),\n        );\n      },\n    });\n  });\n\nexport const usageLimits = new Command(\"usage-limits\")\n  .summary(\"List and configure deployment usage limits\")\n  .description(\n    [\n      \"List and configure usage limits on your deployment.\",\n      \"\",\n      \"A usage limit either warns or pauses your deployment when a metric\",\n      \"(function calls, database bandwidth, \u2026) crosses a threshold within a\",\n      \"daily or monthly window. Each limit is identified by its\",\n      \"(metric, window, type).\",\n      \"\",\n      \"\u2022 List usage limits: `npx convex deployment usage-limits list`\",\n      \"\u2022 Create or update one: `npx convex deployment usage-limits set --metric functionCalls --window day --type disable --limit 1000000`\",\n      \"\u2022 Delete one: `npx convex deployment usage-limits remove --metric functionCalls --window day --type disable`\",\n    ].join(\"\\n\"),\n  )\n  .addCommand(listCmd)\n  .addCommand(setCmd)\n  .addCommand(removeCmd)\n  .helpCommand(false)\n  .addDeploymentSelectionOptions(\n    actionDescription(\"List and configure usage limits on\"),\n  );\n"],
+  "mappings": "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",
+  "names": ["enabled", "usage"]
+}

package/dist/esm/index.js

@@ -1,3 +1,3 @@
 "use strict";
-export const version = "1.42.3";
+export const version = "1.43.0-alpha.0";
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/index.ts"],
-  "sourcesContent": ["export const version = \"1.42.3\";\n"],
+  "sourcesContent": ["export const version = \"1.43.0-alpha.0\";"],
   "mappings": ";AAAO,aAAM,UAAU;",
   "names": []
 }

package/dist/esm/server/components/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/server/components/index.ts"],
-  "sourcesContent": ["import { PropertyValidators } from \"../../values/index.js\";\nimport { version } from \"../../index.js\";\nimport {\n  AnyFunctionReference,\n  FunctionReference,\n  FunctionType,\n} from \"../api.js\";\nimport { performAsyncSyscall } from \"../impl/syscall.js\";\nimport { DefaultFunctionArgs } from \"../registration.js\";\nimport {\n  AppDefinitionAnalysis,\n  ComponentDefinitionAnalysis,\n  ComponentDefinitionType,\n} from \"./definition.js\";\nimport {\n  getFunctionAddress,\n  setReferencePath,\n  toReferencePath,\n} from \"./paths.js\";\nimport type {\n  Validator,\n  VLiteral,\n  VOptional,\n  VString,\n  VUnion,\n} from \"../../values/validators.js\";\nimport type { Infer } from \"../../values/validator.js\";\nimport { isValidator } from \"../../values/validator.js\";\nimport type { Expand } from \"../../type_utils.js\";\nexport { getFunctionAddress } from \"./paths.js\";\n\n/**\n * A serializable reference to a Convex function.\n * Passing a this reference to another component allows that component to call this\n * function during the current function execution or at any later time.\n * Function handles are used like `api.folder.function` FunctionReferences,\n * e.g. `ctx.scheduler.runAfter(0, functionReference, args)`.\n *\n * A function reference is stable across code pushes but it's possible\n * the Convex function it refers to might no longer exist.\n *\n * This is a feature of components, which are in beta.\n * This API is unstable and may change in subsequent releases.\n */\nexport type FunctionHandle<\n  Type extends FunctionType,\n  Args extends DefaultFunctionArgs = any,\n  ReturnType = any,\n> = string & FunctionReference<Type, \"internal\", Args, ReturnType>;\n\n/**\n * Create a serializable reference to a Convex function.\n * Passing a this reference to another component allows that component to call this\n * function during the current function execution or at any later time.\n * Function handles are used like `api.folder.function` FunctionReferences,\n * e.g. `ctx.scheduler.runAfter(0, functionReference, args)`.\n *\n * A function reference is stable across code pushes but it's possible\n * the Convex function it refers to might no longer exist.\n *\n * This is a feature of components, which are in beta.\n * This API is unstable and may change in subsequent releases.\n */\nexport async function createFunctionHandle<\n  Type extends FunctionType,\n  Args extends DefaultFunctionArgs,\n  ReturnType,\n>(\n  functionReference: FunctionReference<\n    Type,\n    \"public\" | \"internal\",\n    Args,\n    ReturnType\n  >,\n): Promise<FunctionHandle<Type, Args, ReturnType>> {\n  const address = getFunctionAddress(functionReference);\n  return await performAsyncSyscall(\"1.0/createFunctionHandle\", {\n    ...address,\n    version,\n  });\n}\n\ninterface ComponentExports {\n  [key: string]: FunctionReference<any, any, any, any> | ComponentExports;\n}\n\n/**\n * An object of this type should be the default export of a\n * convex.config.ts file in a component definition directory.\n *\n * This is a feature of components, which are in beta.\n * This API is unstable and may change in subsequent releases.\n */\nexport type ComponentDefinition<\n  Exports extends ComponentExports = any,\n  Env extends EnvDefinition = {},\n> = {\n  /**\n   * Install a component with the given definition in this component definition.\n   *\n   * Takes a component definition and an optional name.\n   *\n   * For editor tooling this method expects a {@link ComponentDefinition}\n   * but at runtime the object that is imported will be a {@link ImportedComponentDefinition}\n   */\n  use<Definition extends ComponentDefinition<any, any>>(\n    definition: Definition,\n    options?: UseOptions<Definition>,\n  ): InstalledComponent<Definition>;\n\n  /**\n   * Internal type-only property tracking exports provided.\n   *\n   * @deprecated This is a type-only property, don't use it.\n   */\n  __exports: Exports;\n\n  /**\n   * References to this component's declared env vars. Pass one of these in\n   * `app.use(child, { env: { ... } })` to bind a child's env var by\n   * reference to this component's env var.\n   */\n  env: EnvRefFromDefinition<Env>;\n\n  /**\n   * Internal type-only property tracking env definition.\n   *\n   * @deprecated This is a type-only property, don't use it.\n   */\n  __env: Env;\n};\n\ntype ComponentDefinitionExports<T extends ComponentDefinition<any, any>> =\n  T[\"__exports\"];\n\ntype ComponentDefinitionEnv<T extends ComponentDefinition<any, any>> =\n  T[\"__env\"];\n\n/**\n * Options for installing a component via `app.use()` or `component.use()`.\n *\n * If the component declares required env vars, the `env` property is required.\n */\ntype UseOptions<Definition extends ComponentDefinition<any, any>> =\n  keyof ComponentDefinitionEnv<Definition> extends never\n    ? { name?: string; httpPrefix?: string }\n    : {\n        name?: string;\n        httpPrefix?: string;\n        env: UseOptionsEnv<ComponentDefinitionEnv<Definition>>;\n      };\n\ntype UseOptionsEnv<E extends EnvDefinition> = Expand<\n  {\n    [K in keyof E as E[K] extends VOptional<any> ? never : K]:\n      | Infer<E[K]>\n      | EnvRef;\n  } & {\n    [K in keyof E as E[K] extends VOptional<any> ? K : never]?:\n      | Infer<E[K]>\n      | EnvRef\n      | undefined;\n  }\n>;\n\n/**\n * A string-like validator: `v.string()`, a string `v.literal(\"...\")`, or a\n * `v.union(...)` of those (recursively). Component env vars are serialized\n * as strings on the wire, so only string-typed validators are allowed.\n *\n * @public\n */\nexport type StringLikeValidator =\n  | VString<string, \"required\">\n  | VLiteral<string, \"required\">\n  | VUnion<string, Validator<any, \"required\", any>[], \"required\">;\n\n/**\n * A definition of environment variables for the app.\n *\n * Maps environment variable names to string-like validators. Use\n * `v.string()` for a plain string, `v.literal(\"a\")` for an enum value, or\n * `v.union(v.literal(\"a\"), v.literal(\"b\"))` for an enum. Wrap in\n * `v.optional(...)` for optional vars.\n *\n * @example\n * ```typescript\n * import { defineApp } from \"convex/server\";\n * import { v } from \"convex/values\";\n *\n * const app = defineApp({\n *   env: {\n *     OPENAI_API_KEY: v.string(),\n *     DEBUG_MODE: v.optional(v.string()),\n *   },\n * });\n * ```\n *\n * @public\n */\nexport type EnvDefinition = Record<\n  string,\n  StringLikeValidator | VOptional<StringLikeValidator>\n>;\n\n/**\n * Compute the typed environment object from an {@link EnvDefinition}.\n *\n * Required entries get the validator's inferred string type; optional\n * entries are `T | undefined`.\n *\n * @public\n */\nexport type EnvFromDefinition<E extends EnvDefinition> = Expand<\n  {\n    [K in keyof E as E[K] extends VOptional<any> ? never : K]: Infer<E[K]>;\n  } & {\n    [K in keyof E as E[K] extends VOptional<any> ? K : never]?:\n      | Infer<E[K]>\n      | undefined;\n  }\n>;\n\n/**\n * A reference to a parent-declared env var, produced by `app.env.<NAME>` or\n * `component.env.<NAME>`. Pass this in `use(child, { env: { ... } })` to\n * bind a child's declared env var to the parent's env var by reference\n * instead of snapshotting its current value.\n *\n * @public\n */\nexport type EnvRef<K extends string = string> = { __envVarRef: K };\n\n/**\n * Compute the typed `env` namespace object from an {@link EnvDefinition}.\n * Each declared name maps to an {@link EnvRef} for that name.\n *\n * @public\n */\nexport type EnvRefFromDefinition<E extends EnvDefinition> = {\n  [K in keyof E & string]: EnvRef<K>;\n};\n\n/**\n * Extract the typed environment from an {@link AppDefinition}.\n *\n * @public\n */\nexport type EnvFromAppDefinition<A> =\n  A extends AppDefinition<infer E>\n    ? EnvFromDefinition<E>\n    : Record<string, never>;\n\n/**\n * An object of this type should be the default export of a\n * convex.config.ts file in a component-aware convex directory.\n *\n * This is a feature of components, which are in beta.\n * This API is unstable and may change in subsequent releases.\n */\nexport type AppDefinition<Env extends EnvDefinition = EnvDefinition> = {\n  /**\n   * Install a component with the given definition in this component definition.\n   *\n   * Takes a component definition and an optional name.\n   *\n   * For editor tooling this method expects a {@link ComponentDefinition}\n   * but at runtime the object that is imported will be a {@link ImportedComponentDefinition}\n   */\n  use<Definition extends ComponentDefinition<any, any>>(\n    definition: Definition,\n    options?: UseOptions<Definition>,\n  ): InstalledComponent<Definition>;\n\n  /**\n   * References to this app's declared env vars. Pass one of these in\n   * `app.use(child, { env: { ... } })` to bind a child's env var by\n   * reference to this app's env var.\n   */\n  env: EnvRefFromDefinition<Env>;\n\n  /**\n   * Internal type-only property tracking env definition.\n   *\n   * @deprecated This is a type-only property, don't use it.\n   */\n  __env: Env;\n};\n\ninterface ExportTree {\n  // Tree with serialized `Reference`s as leaves.\n  [key: string]: string | ExportTree;\n}\n\ntype CommonDefinitionData = {\n  _isRoot: boolean;\n  _childComponents: [\n    string,\n    ImportedComponentDefinition,\n    Record<string, any> | null,\n    string | undefined,\n  ][];\n  _exportTree: ExportTree;\n};\n\ntype ComponentDefinitionData = CommonDefinitionData & {\n  _env: PropertyValidators;\n  _name: string;\n  _onInitCallbacks: Record<string, (argsStr: string) => string>;\n};\ntype AppDefinitionData = CommonDefinitionData & {\n  _httpPrefix?: string;\n  _env?: EnvDefinition;\n};\n\n/**\n * Used to refer to an already-installed component.\n */\nclass InstalledComponent<Definition extends ComponentDefinition<any, any>> {\n  /**\n   * @internal\n   */\n  _definition: Definition;\n\n  /**\n   * @internal\n   */\n  _name: string;\n\n  constructor(definition: Definition, name: string) {\n    this._definition = definition;\n    this._name = name;\n    setReferencePath(this, `_reference/childComponent/${name}`);\n  }\n\n  get exports(): ComponentDefinitionExports<Definition> {\n    return createExports(this._name, []);\n  }\n}\n\nfunction createExports(name: string, pathParts: string[]): any {\n  const handler: ProxyHandler<any> = {\n    get(_, prop: string | symbol) {\n      if (typeof prop === \"string\") {\n        const newParts = [...pathParts, prop];\n        return createExports(name, newParts);\n      } else if (prop === toReferencePath) {\n        let reference = `_reference/childComponent/${name}`;\n        for (const part of pathParts) {\n          reference += `/${part}`;\n        }\n        return reference;\n      } else {\n        return undefined;\n      }\n    },\n  };\n  return new Proxy({}, handler);\n}\n\nfunction createEnvRefs(\n  ownerLabel: string,\n  declared: Record<string, any> | undefined,\n): any {\n  const handler: ProxyHandler<any> = {\n    get(_, prop: string | symbol) {\n      if (typeof prop !== \"string\") {\n        return undefined;\n      }\n      if (!declared || !Object.prototype.hasOwnProperty.call(declared, prop)) {\n        throw new Error(\n          `Env var \"${prop}\" is not declared on ${ownerLabel}. Add it to the \\`env\\` option of ${ownerLabel === \"this app\" ? \"defineApp\" : \"defineComponent\"}.`,\n        );\n      }\n      return { __envVarRef: prop };\n    },\n  };\n  return new Proxy({}, handler);\n}\n\nfunction isEnvRef(value: unknown): value is EnvRef {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    typeof (value as EnvRef).__envVarRef === \"string\"\n  );\n}\n\nfunction use<Definition extends ComponentDefinition<any, any>>(\n  this: CommonDefinitionData,\n  definition: Definition,\n  options?: {\n    name?: string;\n    httpPrefix?: string;\n    env?: Record<string, any>;\n  },\n): InstalledComponent<Definition> {\n  // At runtime an imported component will have this shape.\n  const importedComponentDefinition =\n    definition as unknown as ImportedComponentDefinition;\n  if (typeof importedComponentDefinition.componentDefinitionPath !== \"string\") {\n    throw new Error(\n      \"Component definition does not have the required componentDefinitionPath property. This code only works in Convex runtime.\",\n    );\n  }\n  const name =\n    options?.name ??\n    // added recently\n    importedComponentDefinition.defaultName ??\n    // can be removed once backend is out\n    importedComponentDefinition.componentDefinitionPath.split(\"/\").pop()!;\n\n  if (typeof name !== \"string\") {\n    throw new Error(\n      `Component name must be a string. Received: ${typeof name}`,\n    );\n  }\n  if (name.length === 0) {\n    // \"\" is used internally as the name for the root component, so\n    // users shouldn't try to define child components with an empty name.\n    throw new Error(\"Component name cannot be empty.\");\n  }\n\n  const httpPrefix = options?.httpPrefix;\n  if (httpPrefix !== undefined) {\n    if (!httpPrefix.startsWith(\"/\")) {\n      throw new Error(\n        `httpPrefix must start with \"/\". Received: \"${httpPrefix}\"`,\n      );\n    }\n  }\n\n  const envValues: Record<string, any> = {};\n  if (options?.env) {\n    for (const [key, value] of Object.entries(options.env)) {\n      if (value !== undefined) {\n        envValues[key] = value;\n      }\n    }\n  }\n\n  this._childComponents.push([\n    name,\n    importedComponentDefinition,\n    envValues,\n    httpPrefix,\n  ]);\n  return new InstalledComponent(definition, name);\n}\n\n/**\n * The runtime type of a ComponentDefinition. TypeScript will claim\n * the default export of a module like \"cool-component/convex.config.js\"\n * is a `@link ComponentDefinition}, but during component definition evaluation\n * this is its type instead.\n *\n * This is a feature of components, which are in beta.\n * This API is unstable and may change in subsequent releases.\n */\nexport type ImportedComponentDefinition = {\n  componentDefinitionPath: string;\n  defaultName: string;\n};\n\nfunction exportAppForAnalysis(\n  this: ComponentDefinition<any, any> & AppDefinitionData,\n): AppDefinitionAnalysis {\n  const definitionType = { type: \"app\" as const };\n  const childComponents = serializeChildComponents(this._childComponents);\n  const httpMounts = buildHttpMounts(this._childComponents);\n  const envVars = this._env\n    ? Object.entries(this._env).map(\n        ([name, validator]) =>\n          [\n            name,\n            {\n              type: \"value\" as const,\n              value: JSON.stringify(validator.json),\n              ...(validator.isOptional === \"optional\"\n                ? { optional: true }\n                : {}),\n            },\n          ] as [string, { type: \"value\"; value: string; optional?: boolean }],\n      )\n    : undefined;\n  return {\n    definitionType,\n    ...(this._httpPrefix !== undefined\n      ? { httpPrefix: normalizeHttpPrefix(this._httpPrefix) }\n      : {}),\n    childComponents: childComponents as any,\n    httpMounts,\n    exports: serializeExportTree(this._exportTree),\n    ...(envVars !== undefined ? { envVars } : {}),\n  };\n}\n\nfunction serializeExportTree(tree: ExportTree): any {\n  const branch: any[] = [];\n  for (const [key, child] of Object.entries(tree)) {\n    let node;\n    if (typeof child === \"string\") {\n      node = { type: \"leaf\", leaf: child };\n    } else {\n      node = serializeExportTree(child);\n    }\n    branch.push([key, node]);\n  }\n  return { type: \"branch\", branch };\n}\n\nfunction normalizeHttpPrefix(prefix: string): string {\n  // Ensure the prefix ends with \"/\" as required by HttpMountPath in Rust.\n  return prefix.endsWith(\"/\") ? prefix : prefix + \"/\";\n}\n\nfunction buildHttpMounts(\n  childComponents: [\n    string,\n    ImportedComponentDefinition,\n    Record<string, any> | null,\n    string | undefined,\n  ][],\n): Record<string, string> {\n  const httpMounts: Record<string, string> = {};\n  for (const [name, , , httpPrefix] of childComponents) {\n    if (httpPrefix !== undefined) {\n      const normalized = normalizeHttpPrefix(httpPrefix);\n      httpMounts[normalized] = `_reference/childComponent/${name}`;\n    }\n  }\n  return httpMounts;\n}\n\ntype SerializedEnvArg =\n  | { type: \"value\"; value: string }\n  | { type: \"envVar\"; name: string };\n\nfunction serializeChildComponents(\n  childComponents: [\n    string,\n    ImportedComponentDefinition,\n    Record<string, any> | null,\n    string | undefined,\n  ][],\n): {\n  name: string;\n  path: string;\n  env: [string, SerializedEnvArg][] | null;\n}[] {\n  return childComponents.map(([name, definition, p]) => {\n    // Note: httpPrefix (4th element) is used separately in buildHttpMounts()\n    let env: [string, SerializedEnvArg][] | null = null;\n    if (p !== null) {\n      env = [];\n      for (const [name, value] of Object.entries(p)) {\n        if (value === undefined) {\n          continue;\n        }\n        if (isEnvRef(value)) {\n          env.push([name, { type: \"envVar\", name: value.__envVarRef }]);\n        } else if (typeof value === \"string\") {\n          env.push([name, { type: \"value\", value }]);\n        } else {\n          throw new Error(\n            `Env var \"${name}\" must be a string or an env var reference. ` +\n              `Received: ${typeof value}`,\n          );\n        }\n      }\n    }\n    // we know that components carry this extra information\n    const path = definition.componentDefinitionPath;\n    if (!path)\n      throw new Error(\n        \"no .componentPath for component definition \" +\n          JSON.stringify(definition, null, 2),\n      );\n\n    return {\n      name: name!,\n      path: path!,\n      args: [],\n      env,\n    };\n  });\n}\n\nfunction exportComponentForAnalysis(\n  this: ComponentDefinition<any, any> & ComponentDefinitionData,\n): ComponentDefinitionAnalysis {\n  const envVars = Object.entries(this._env).map(\n    ([name, validator]) =>\n      [\n        name,\n        {\n          type: \"value\" as const,\n          value: JSON.stringify((validator as any).json),\n          ...((validator as any).isOptional === \"optional\"\n            ? { optional: true }\n            : {}),\n        },\n      ] as [string, { type: \"value\"; value: string; optional?: boolean }],\n  );\n  const definitionType: ComponentDefinitionType = {\n    type: \"childComponent\" as const,\n    name: this._name,\n    args: [],\n  };\n  const childComponents = serializeChildComponents(this._childComponents);\n  const httpMounts = buildHttpMounts(this._childComponents);\n  return {\n    name: this._name,\n    definitionType,\n    childComponents: childComponents as any,\n    httpMounts,\n    exports: serializeExportTree(this._exportTree),\n    ...(envVars.length > 0 ? { envVars } : {}),\n  };\n}\n\n// This is what is actually contained in a ComponentDefinition.\ntype RuntimeComponentDefinition = Omit<\n  ComponentDefinition<any, any>,\n  \"__exports\" | \"__env\"\n> &\n  ComponentDefinitionData & {\n    export: () => ComponentDefinitionAnalysis;\n  };\ntype RuntimeAppDefinition = Omit<AppDefinition<any>, \"__env\"> &\n  AppDefinitionData & {\n    export: () => AppDefinitionAnalysis;\n  };\n\n/**\n * Define a component, a piece of a Convex deployment with namespaced resources.\n *\n * Optionally define typed environment variables that will be available via\n * the `env` export from `_generated/server` in all Convex functions within\n * this component. Values are passed by the parent via\n * `app.use(component, { env: { ... } })`.\n *\n * @param name Name must be alphanumeric plus underscores. Typically these are\n * lowercase with underscores like `\"onboarding_flow_tracker\"`.\n *\n * This is a feature of components, which are in beta.\n * This API is unstable and may change in subsequent releases.\n */\nexport function defineComponent<\n  Exports extends ComponentExports = any,\n  const Env extends EnvDefinition = {},\n>(\n  name: string,\n  options?: {\n    env?: Env;\n  },\n): ComponentDefinition<Exports, Env> {\n  const envValidators: PropertyValidators = {};\n  if (options?.env) {\n    for (const [key, decl] of Object.entries(options.env)) {\n      if (decl !== null && decl !== undefined && isValidator(decl)) {\n        envValidators[key] = decl as any;\n      } else {\n        throw new Error(\n          `Environment variable \"${key}\" must be defined with a validator (e.g. v.string()).`,\n        );\n      }\n    }\n  }\n\n  const ret: RuntimeComponentDefinition = {\n    _isRoot: false,\n    _name: name,\n    _env: envValidators,\n    _childComponents: [],\n    _exportTree: {},\n    _onInitCallbacks: {},\n\n    env: createEnvRefs(`component \"${name}\"`, options?.env),\n\n    export: exportComponentForAnalysis,\n    use,\n\n    ...({} as { __exports: any; __env: any }),\n  };\n  return ret as any as ComponentDefinition<Exports, Env>;\n}\n\n/**\n * Attach components, reuseable pieces of a Convex deployment, to this Convex app.\n *\n * Optionally define typed environment variables that will be available via\n * the `env` export from `_generated/server` in all Convex functions.\n *\n * @example\n * ```typescript\n * import { defineApp } from \"convex/server\";\n * import { v } from \"convex/values\";\n *\n * const app = defineApp({\n *   env: {\n *     OPENAI_API_KEY: v.string(),\n *     DEBUG_MODE: v.optional(v.string()),\n *   },\n * });\n * export default app;\n * ```\n *\n * This is a feature of components, which are in beta.\n * This API is unstable and may change in subsequent releases.\n */\nexport function defineApp<Env extends EnvDefinition = EnvDefinition>(options?: {\n  httpPrefix?: string;\n  env?: Env;\n}): AppDefinition<Env> {\n  const httpPrefix = options?.httpPrefix;\n  if (httpPrefix !== undefined && !httpPrefix.startsWith(\"/\")) {\n    throw new Error(\n      `httpPrefix must start with \"/\". Received: \"${httpPrefix}\"`,\n    );\n  }\n  const env = options?.env;\n  if (env !== undefined) {\n    for (const [name, validator] of Object.entries(env)) {\n      if (!isValidator(validator)) {\n        throw new Error(\n          `Environment variable \"${name}\" must be defined with a validator (e.g. v.string()).`,\n        );\n      }\n    }\n  }\n  const ret: RuntimeAppDefinition = {\n    _isRoot: true,\n    _childComponents: [],\n    _exportTree: {},\n    ...(httpPrefix !== undefined ? { _httpPrefix: httpPrefix } : {}),\n    ...(env !== undefined ? { _env: env } : {}),\n\n    env: createEnvRefs(\"this app\", env),\n\n    export: exportAppForAnalysis,\n    use,\n  };\n  return ret as unknown as AppDefinition<Env>;\n}\n\ntype AnyInterfaceType = {\n  [key: string]: AnyInterfaceType;\n} & AnyFunctionReference;\nexport type AnyComponentReference = Record<string, AnyInterfaceType>;\n\nexport type AnyChildComponents = Record<string, AnyComponentReference>;\n\n/**\n * @internal\n */\nexport function currentSystemUdfInComponent(\n  componentId: string,\n): AnyComponentReference {\n  return {\n    [toReferencePath]: `_reference/currentSystemUdfInComponent/${componentId}`,\n  };\n}\n\nfunction createChildComponents(\n  root: string,\n  pathParts: string[],\n): AnyChildComponents {\n  const handler: ProxyHandler<object> = {\n    get(_, prop: string | symbol) {\n      if (typeof prop === \"string\") {\n        const newParts = [...pathParts, prop];\n        return createChildComponents(root, newParts);\n      } else if (prop === toReferencePath) {\n        if (pathParts.length < 1) {\n          const found = [root, ...pathParts].join(\".\");\n          throw new Error(\n            `API path is expected to be of the form \\`${root}.childComponent.functionName\\`. Found: \\`${found}\\``,\n          );\n        }\n        return `_reference/childComponent/` + pathParts.join(\"/\");\n      } else {\n        return undefined;\n      }\n    },\n  };\n  return new Proxy({}, handler);\n}\n\nexport const componentsGeneric = () => createChildComponents(\"components\", []);\n\nexport type AnyComponents = AnyChildComponents;\n"],
-  "mappings": "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",
+  "sourcesContent": ["import { PropertyValidators } from \"../../values/index.js\";\nimport { version } from \"../../index.js\";\nimport {\n  AnyFunctionReference,\n  FunctionReference,\n  FunctionType,\n} from \"../api.js\";\nimport { performAsyncSyscall } from \"../impl/syscall.js\";\nimport { DefaultFunctionArgs } from \"../registration.js\";\nimport {\n  AppDefinitionAnalysis,\n  ComponentDefinitionAnalysis,\n  ComponentDefinitionType,\n} from \"./definition.js\";\nimport {\n  getFunctionAddress,\n  setReferencePath,\n  toReferencePath,\n} from \"./paths.js\";\nimport type {\n  Validator,\n  VLiteral,\n  VOptional,\n  VString,\n  VUnion,\n} from \"../../values/validators.js\";\nimport type { Infer } from \"../../values/validator.js\";\nimport { isValidator } from \"../../values/validator.js\";\nimport type { Expand } from \"../../type_utils.js\";\nexport { getFunctionAddress } from \"./paths.js\";\n\n/**\n * A serializable reference to a Convex function.\n * Passing a this reference to another component allows that component to call this\n * function during the current function execution or at any later time.\n * Function handles are used like `api.folder.function` FunctionReferences,\n * e.g. `ctx.scheduler.runAfter(0, functionReference, args)`.\n *\n * A function reference is stable across code pushes but it's possible\n * the Convex function it refers to might no longer exist.\n *\n * This is a feature of components, which are in beta.\n * This API is unstable and may change in subsequent releases.\n */\nexport type FunctionHandle<\n  Type extends FunctionType,\n  Args extends DefaultFunctionArgs = any,\n  ReturnType = any,\n> = string & FunctionReference<Type, \"internal\", Args, ReturnType>;\n\n/**\n * Create a serializable reference to a Convex function.\n * Passing a this reference to another component allows that component to call this\n * function during the current function execution or at any later time.\n * Function handles are used like `api.folder.function` FunctionReferences,\n * e.g. `ctx.scheduler.runAfter(0, functionReference, args)`.\n *\n * A function reference is stable across code pushes but it's possible\n * the Convex function it refers to might no longer exist.\n *\n * This is a feature of components, which are in beta.\n * This API is unstable and may change in subsequent releases.\n */\nexport async function createFunctionHandle<\n  Type extends FunctionType,\n  Args extends DefaultFunctionArgs,\n  ReturnType,\n>(\n  functionReference: FunctionReference<\n    Type,\n    \"public\" | \"internal\",\n    Args,\n    ReturnType\n  >,\n): Promise<FunctionHandle<Type, Args, ReturnType>> {\n  const address = getFunctionAddress(functionReference);\n  return await performAsyncSyscall(\"1.0/createFunctionHandle\", {\n    ...address,\n    version,\n  });\n}\n\ninterface ComponentExports {\n  [key: string]: FunctionReference<any, any, any, any> | ComponentExports;\n}\n\n/**\n * An object of this type should be the default export of a\n * convex.config.ts file in a component definition directory.\n *\n * This is a feature of components, which are in beta.\n * This API is unstable and may change in subsequent releases.\n */\nexport type ComponentDefinition<\n  Exports extends ComponentExports = any,\n  Env extends EnvDefinition = {},\n> = {\n  /**\n   * Install a component with the given definition in this component definition.\n   *\n   * Takes a component definition and an optional name.\n   *\n   * For editor tooling this method expects a {@link ComponentDefinition}\n   * but at runtime the object that is imported will be a {@link ImportedComponentDefinition}\n   */\n  use<Definition extends ComponentDefinition<any, any>>(\n    definition: Definition,\n    ...args: UseArgs<Definition>\n  ): InstalledComponent<Definition>;\n\n  /**\n   * Internal type-only property tracking exports provided.\n   *\n   * @deprecated This is a type-only property, don't use it.\n   */\n  __exports: Exports;\n\n  /**\n   * References to this component's declared env vars. Pass one of these in\n   * `app.use(child, { env: { ... } })` to bind a child's env var by\n   * reference to this component's env var.\n   */\n  env: EnvRefFromDefinition<Env>;\n\n  /**\n   * Internal type-only property tracking env definition.\n   *\n   * @deprecated This is a type-only property, don't use it.\n   */\n  __env: Env;\n};\n\ntype ComponentDefinitionExports<T extends ComponentDefinition<any, any>> =\n  T[\"__exports\"];\n\ntype ComponentDefinitionEnv<T extends ComponentDefinition<any, any>> =\n  T[\"__env\"];\n\n/**\n * The names in an {@link EnvDefinition} whose validators are required (not\n * wrapped in `v.optional(...)`).\n */\ntype RequiredEnvKeys<E extends EnvDefinition> = {\n  [K in keyof E]: E[K] extends Validator<any, \"optional\", any> ? never : K;\n}[keyof E];\n\n/**\n * Options for installing a component via `app.use()` or `component.use()`.\n *\n * If the component declares any required env vars, the `env` property is\n * required. Otherwise it is optional, so that a component with no env vars (or\n * only optional ones) can be installed without passing `env`.\n */\ntype UseOptions<Definition extends ComponentDefinition<any, any>> =\n  RequiredEnvKeys<ComponentDefinitionEnv<Definition>> extends never\n    ? {\n        name?: string;\n        httpPrefix?: string;\n        env?: UseOptionsEnv<ComponentDefinitionEnv<Definition>>;\n      }\n    : {\n        name?: string;\n        httpPrefix?: string;\n        env: UseOptionsEnv<ComponentDefinitionEnv<Definition>>;\n      };\n\n/**\n * The arguments to `use()` after the component definition.\n *\n * When the component declares required env vars the `options` argument is\n * mandatory (so it can't be dropped to skip the required `env`); otherwise it\n * is optional.\n */\ntype UseArgs<Definition extends ComponentDefinition<any, any>> =\n  RequiredEnvKeys<ComponentDefinitionEnv<Definition>> extends never\n    ? [options?: UseOptions<Definition>]\n    : [options: UseOptions<Definition>];\n\ntype UseOptionsEnv<E extends EnvDefinition> = Expand<\n  {\n    [K in keyof E as E[K] extends Validator<any, \"optional\", any> ? never : K]:\n      | Infer<E[K]>\n      | EnvRef;\n  } & {\n    [K in keyof E as E[K] extends Validator<any, \"optional\", any>\n      ? K\n      : never]?: Infer<E[K]> | EnvRef | undefined;\n  }\n>;\n\n/**\n * A string-like validator: `v.string()`, a string `v.literal(\"...\")`, or a\n * `v.union(...)` of those (recursively). Component env vars are serialized\n * as strings on the wire, so only string-typed validators are allowed.\n *\n * @public\n */\nexport type StringLikeValidator =\n  | VString<string, \"required\">\n  | VLiteral<string, \"required\">\n  | VUnion<string, Validator<any, \"required\", any>[], \"required\">;\n\n/**\n * A definition of environment variables for the app.\n *\n * Maps environment variable names to string-like validators. Use\n * `v.string()` for a plain string, `v.literal(\"a\")` for an enum value, or\n * `v.union(v.literal(\"a\"), v.literal(\"b\"))` for an enum. Wrap in\n * `v.optional(...)` for optional vars.\n *\n * @example\n * ```typescript\n * import { defineApp } from \"convex/server\";\n * import { v } from \"convex/values\";\n *\n * const app = defineApp({\n *   env: {\n *     OPENAI_API_KEY: v.string(),\n *     DEBUG_MODE: v.optional(v.string()),\n *   },\n * });\n * ```\n *\n * @public\n */\nexport type EnvDefinition = Record<\n  string,\n  StringLikeValidator | VOptional<StringLikeValidator>\n>;\n\n/**\n * Compute the typed environment object from an {@link EnvDefinition}.\n *\n * Required entries get the validator's inferred string type; optional\n * entries are `T | undefined`.\n *\n * @public\n */\nexport type EnvFromDefinition<E extends EnvDefinition> = Expand<\n  {\n    [K in keyof E as E[K] extends Validator<any, \"optional\", any>\n      ? never\n      : K]: Infer<E[K]>;\n  } & {\n    [K in keyof E as E[K] extends Validator<any, \"optional\", any>\n      ? K\n      : never]?: Infer<E[K]> | undefined;\n  }\n>;\n\n/**\n * A reference to a parent-declared env var, produced by `app.env.<NAME>` or\n * `component.env.<NAME>`. Pass this in `use(child, { env: { ... } })` to\n * bind a child's declared env var to the parent's env var by reference\n * instead of snapshotting its current value.\n *\n * @public\n */\nexport type EnvRef<K extends string = string> = { __envVarRef: K };\n\n/**\n * Compute the typed `env` namespace object from an {@link EnvDefinition}.\n * Each declared name maps to an {@link EnvRef} for that name.\n *\n * @public\n */\nexport type EnvRefFromDefinition<E extends EnvDefinition> = {\n  [K in keyof E & string]: EnvRef<K>;\n};\n\n/**\n * Extract the typed environment from an {@link AppDefinition}.\n *\n * @public\n */\nexport type EnvFromAppDefinition<A> =\n  A extends AppDefinition<infer E>\n    ? EnvFromDefinition<E>\n    : Record<string, never>;\n\n/**\n * An object of this type should be the default export of a\n * convex.config.ts file in a component-aware convex directory.\n *\n * This is a feature of components, which are in beta.\n * This API is unstable and may change in subsequent releases.\n */\nexport type AppDefinition<Env extends EnvDefinition = EnvDefinition> = {\n  /**\n   * Install a component with the given definition in this component definition.\n   *\n   * Takes a component definition and an optional name.\n   *\n   * For editor tooling this method expects a {@link ComponentDefinition}\n   * but at runtime the object that is imported will be a {@link ImportedComponentDefinition}\n   */\n  use<Definition extends ComponentDefinition<any, any>>(\n    definition: Definition,\n    ...args: UseArgs<Definition>\n  ): InstalledComponent<Definition>;\n\n  /**\n   * References to this app's declared env vars. Pass one of these in\n   * `app.use(child, { env: { ... } })` to bind a child's env var by\n   * reference to this app's env var.\n   */\n  env: EnvRefFromDefinition<Env>;\n\n  /**\n   * Internal type-only property tracking env definition.\n   *\n   * @deprecated This is a type-only property, don't use it.\n   */\n  __env: Env;\n};\n\ninterface ExportTree {\n  // Tree with serialized `Reference`s as leaves.\n  [key: string]: string | ExportTree;\n}\n\ntype CommonDefinitionData = {\n  _isRoot: boolean;\n  _childComponents: [\n    string,\n    ImportedComponentDefinition,\n    Record<string, any> | null,\n    string | undefined,\n  ][];\n  _exportTree: ExportTree;\n};\n\ntype ComponentDefinitionData = CommonDefinitionData & {\n  _env: PropertyValidators;\n  _name: string;\n  _onInitCallbacks: Record<string, (argsStr: string) => string>;\n};\ntype AppDefinitionData = CommonDefinitionData & {\n  _httpPrefix?: string;\n  _env?: EnvDefinition;\n};\n\n/**\n * Used to refer to an already-installed component.\n */\nclass InstalledComponent<Definition extends ComponentDefinition<any, any>> {\n  /**\n   * @internal\n   */\n  _definition: Definition;\n\n  /**\n   * @internal\n   */\n  _name: string;\n\n  constructor(definition: Definition, name: string) {\n    this._definition = definition;\n    this._name = name;\n    setReferencePath(this, `_reference/childComponent/${name}`);\n  }\n\n  get exports(): ComponentDefinitionExports<Definition> {\n    return createExports(this._name, []);\n  }\n}\n\nfunction createExports(name: string, pathParts: string[]): any {\n  const handler: ProxyHandler<any> = {\n    get(_, prop: string | symbol) {\n      if (typeof prop === \"string\") {\n        const newParts = [...pathParts, prop];\n        return createExports(name, newParts);\n      } else if (prop === toReferencePath) {\n        let reference = `_reference/childComponent/${name}`;\n        for (const part of pathParts) {\n          reference += `/${part}`;\n        }\n        return reference;\n      } else {\n        return undefined;\n      }\n    },\n  };\n  return new Proxy({}, handler);\n}\n\nfunction createEnvRefs(\n  ownerLabel: string,\n  declared: Record<string, any> | undefined,\n): any {\n  const handler: ProxyHandler<any> = {\n    get(_, prop: string | symbol) {\n      if (typeof prop !== \"string\") {\n        return undefined;\n      }\n      if (!declared || !Object.prototype.hasOwnProperty.call(declared, prop)) {\n        throw new Error(\n          `Env var \"${prop}\" is not declared on ${ownerLabel}. Add it to the \\`env\\` option of ${ownerLabel === \"this app\" ? \"defineApp\" : \"defineComponent\"}.`,\n        );\n      }\n      return { __envVarRef: prop };\n    },\n  };\n  return new Proxy({}, handler);\n}\n\nfunction isEnvRef(value: unknown): value is EnvRef {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    typeof (value as EnvRef).__envVarRef === \"string\"\n  );\n}\n\nfunction use<Definition extends ComponentDefinition<any, any>>(\n  this: CommonDefinitionData,\n  definition: Definition,\n  options?: {\n    name?: string;\n    httpPrefix?: string;\n    env?: Record<string, any>;\n  },\n): InstalledComponent<Definition> {\n  // At runtime an imported component will have this shape.\n  const importedComponentDefinition =\n    definition as unknown as ImportedComponentDefinition;\n  if (typeof importedComponentDefinition.componentDefinitionPath !== \"string\") {\n    throw new Error(\n      \"Component definition does not have the required componentDefinitionPath property. This code only works in Convex runtime.\",\n    );\n  }\n  const name =\n    options?.name ??\n    // added recently\n    importedComponentDefinition.defaultName ??\n    // can be removed once backend is out\n    importedComponentDefinition.componentDefinitionPath.split(\"/\").pop()!;\n\n  if (typeof name !== \"string\") {\n    throw new Error(\n      `Component name must be a string. Received: ${typeof name}`,\n    );\n  }\n  if (name.length === 0) {\n    // \"\" is used internally as the name for the root component, so\n    // users shouldn't try to define child components with an empty name.\n    throw new Error(\"Component name cannot be empty.\");\n  }\n\n  const httpPrefix = options?.httpPrefix;\n  if (httpPrefix !== undefined) {\n    if (!httpPrefix.startsWith(\"/\")) {\n      throw new Error(\n        `httpPrefix must start with \"/\". Received: \"${httpPrefix}\"`,\n      );\n    }\n  }\n\n  const envValues: Record<string, any> = {};\n  if (options?.env) {\n    for (const [key, value] of Object.entries(options.env)) {\n      if (value !== undefined) {\n        envValues[key] = value;\n      }\n    }\n  }\n\n  this._childComponents.push([\n    name,\n    importedComponentDefinition,\n    envValues,\n    httpPrefix,\n  ]);\n  return new InstalledComponent(definition, name);\n}\n\n/**\n * The runtime type of a ComponentDefinition. TypeScript will claim\n * the default export of a module like \"cool-component/convex.config.js\"\n * is a `@link ComponentDefinition}, but during component definition evaluation\n * this is its type instead.\n *\n * This is a feature of components, which are in beta.\n * This API is unstable and may change in subsequent releases.\n */\nexport type ImportedComponentDefinition = {\n  componentDefinitionPath: string;\n  defaultName: string;\n};\n\nfunction exportAppForAnalysis(\n  this: ComponentDefinition<any, any> & AppDefinitionData,\n): AppDefinitionAnalysis {\n  const definitionType = { type: \"app\" as const };\n  const childComponents = serializeChildComponents(this._childComponents);\n  const httpMounts = buildHttpMounts(this._childComponents);\n  const envVars = this._env\n    ? Object.entries(this._env).map(\n        ([name, validator]) =>\n          [\n            name,\n            {\n              type: \"value\" as const,\n              value: JSON.stringify(validator.json),\n              ...(validator.isOptional === \"optional\"\n                ? { optional: true }\n                : {}),\n            },\n          ] as [string, { type: \"value\"; value: string; optional?: boolean }],\n      )\n    : undefined;\n  return {\n    definitionType,\n    ...(this._httpPrefix !== undefined\n      ? { httpPrefix: normalizeHttpPrefix(this._httpPrefix) }\n      : {}),\n    childComponents: childComponents as any,\n    httpMounts,\n    exports: serializeExportTree(this._exportTree),\n    ...(envVars !== undefined ? { envVars } : {}),\n  };\n}\n\nfunction serializeExportTree(tree: ExportTree): any {\n  const branch: any[] = [];\n  for (const [key, child] of Object.entries(tree)) {\n    let node;\n    if (typeof child === \"string\") {\n      node = { type: \"leaf\", leaf: child };\n    } else {\n      node = serializeExportTree(child);\n    }\n    branch.push([key, node]);\n  }\n  return { type: \"branch\", branch };\n}\n\nfunction normalizeHttpPrefix(prefix: string): string {\n  // Ensure the prefix ends with \"/\" as required by HttpMountPath in Rust.\n  return prefix.endsWith(\"/\") ? prefix : prefix + \"/\";\n}\n\nfunction buildHttpMounts(\n  childComponents: [\n    string,\n    ImportedComponentDefinition,\n    Record<string, any> | null,\n    string | undefined,\n  ][],\n): Record<string, string> {\n  const httpMounts: Record<string, string> = {};\n  for (const [name, , , httpPrefix] of childComponents) {\n    if (httpPrefix !== undefined) {\n      const normalized = normalizeHttpPrefix(httpPrefix);\n      httpMounts[normalized] = `_reference/childComponent/${name}`;\n    }\n  }\n  return httpMounts;\n}\n\ntype SerializedEnvArg =\n  | { type: \"value\"; value: string }\n  | { type: \"envVar\"; name: string };\n\nfunction serializeChildComponents(\n  childComponents: [\n    string,\n    ImportedComponentDefinition,\n    Record<string, any> | null,\n    string | undefined,\n  ][],\n): {\n  name: string;\n  path: string;\n  env: [string, SerializedEnvArg][] | null;\n}[] {\n  return childComponents.map(([name, definition, p]) => {\n    // Note: httpPrefix (4th element) is used separately in buildHttpMounts()\n    let env: [string, SerializedEnvArg][] | null = null;\n    if (p !== null) {\n      env = [];\n      for (const [name, value] of Object.entries(p)) {\n        if (value === undefined) {\n          continue;\n        }\n        if (isEnvRef(value)) {\n          env.push([name, { type: \"envVar\", name: value.__envVarRef }]);\n        } else if (typeof value === \"string\") {\n          env.push([name, { type: \"value\", value }]);\n        } else {\n          throw new Error(\n            `Env var \"${name}\" must be a string or an env var reference. ` +\n              `Received: ${typeof value}`,\n          );\n        }\n      }\n    }\n    // we know that components carry this extra information\n    const path = definition.componentDefinitionPath;\n    if (!path)\n      throw new Error(\n        \"no .componentPath for component definition \" +\n          JSON.stringify(definition, null, 2),\n      );\n\n    return {\n      name: name!,\n      path: path!,\n      args: [],\n      env,\n    };\n  });\n}\n\nfunction exportComponentForAnalysis(\n  this: ComponentDefinition<any, any> & ComponentDefinitionData,\n): ComponentDefinitionAnalysis {\n  const envVars = Object.entries(this._env).map(\n    ([name, validator]) =>\n      [\n        name,\n        {\n          type: \"value\" as const,\n          value: JSON.stringify((validator as any).json),\n          ...((validator as any).isOptional === \"optional\"\n            ? { optional: true }\n            : {}),\n        },\n      ] as [string, { type: \"value\"; value: string; optional?: boolean }],\n  );\n  const definitionType: ComponentDefinitionType = {\n    type: \"childComponent\" as const,\n    name: this._name,\n    args: [],\n  };\n  const childComponents = serializeChildComponents(this._childComponents);\n  const httpMounts = buildHttpMounts(this._childComponents);\n  return {\n    name: this._name,\n    definitionType,\n    childComponents: childComponents as any,\n    httpMounts,\n    exports: serializeExportTree(this._exportTree),\n    ...(envVars.length > 0 ? { envVars } : {}),\n  };\n}\n\n// This is what is actually contained in a ComponentDefinition.\ntype RuntimeComponentDefinition = Omit<\n  ComponentDefinition<any, any>,\n  \"__exports\" | \"__env\"\n> &\n  ComponentDefinitionData & {\n    export: () => ComponentDefinitionAnalysis;\n  };\ntype RuntimeAppDefinition = Omit<AppDefinition<any>, \"__env\"> &\n  AppDefinitionData & {\n    export: () => AppDefinitionAnalysis;\n  };\n\n/**\n * Define a component, a piece of a Convex deployment with namespaced resources.\n *\n * Optionally define typed environment variables that will be available via\n * the `env` export from `_generated/server` in all Convex functions within\n * this component. Values are passed by the parent via\n * `app.use(component, { env: { ... } })`.\n *\n * @param name Name must be alphanumeric plus underscores. Typically these are\n * lowercase with underscores like `\"onboarding_flow_tracker\"`.\n *\n * This is a feature of components, which are in beta.\n * This API is unstable and may change in subsequent releases.\n */\nexport function defineComponent<\n  Exports extends ComponentExports = any,\n  const Env extends EnvDefinition = {},\n>(\n  name: string,\n  options?: {\n    env?: Env;\n  },\n): ComponentDefinition<Exports, Env> {\n  const envValidators: PropertyValidators = {};\n  if (options?.env) {\n    for (const [key, decl] of Object.entries(options.env)) {\n      if (decl !== null && decl !== undefined && isValidator(decl)) {\n        envValidators[key] = decl as any;\n      } else {\n        throw new Error(\n          `Environment variable \"${key}\" must be defined with a validator (e.g. v.string()).`,\n        );\n      }\n    }\n  }\n\n  const ret: RuntimeComponentDefinition = {\n    _isRoot: false,\n    _name: name,\n    _env: envValidators,\n    _childComponents: [],\n    _exportTree: {},\n    _onInitCallbacks: {},\n\n    env: createEnvRefs(`component \"${name}\"`, options?.env),\n\n    export: exportComponentForAnalysis,\n    use,\n\n    ...({} as { __exports: any; __env: any }),\n  };\n  return ret as any as ComponentDefinition<Exports, Env>;\n}\n\n/**\n * Attach components, reuseable pieces of a Convex deployment, to this Convex app.\n *\n * Optionally define typed environment variables that will be available via\n * the `env` export from `_generated/server` in all Convex functions.\n *\n * @example\n * ```typescript\n * import { defineApp } from \"convex/server\";\n * import { v } from \"convex/values\";\n *\n * const app = defineApp({\n *   env: {\n *     OPENAI_API_KEY: v.string(),\n *     DEBUG_MODE: v.optional(v.string()),\n *   },\n * });\n * export default app;\n * ```\n *\n * This is a feature of components, which are in beta.\n * This API is unstable and may change in subsequent releases.\n */\nexport function defineApp<Env extends EnvDefinition = EnvDefinition>(options?: {\n  httpPrefix?: string;\n  env?: Env;\n}): AppDefinition<Env> {\n  const httpPrefix = options?.httpPrefix;\n  if (httpPrefix !== undefined && !httpPrefix.startsWith(\"/\")) {\n    throw new Error(\n      `httpPrefix must start with \"/\". Received: \"${httpPrefix}\"`,\n    );\n  }\n  const env = options?.env;\n  if (env !== undefined) {\n    for (const [name, validator] of Object.entries(env)) {\n      if (!isValidator(validator)) {\n        throw new Error(\n          `Environment variable \"${name}\" must be defined with a validator (e.g. v.string()).`,\n        );\n      }\n    }\n  }\n  const ret: RuntimeAppDefinition = {\n    _isRoot: true,\n    _childComponents: [],\n    _exportTree: {},\n    ...(httpPrefix !== undefined ? { _httpPrefix: httpPrefix } : {}),\n    ...(env !== undefined ? { _env: env } : {}),\n\n    env: createEnvRefs(\"this app\", env),\n\n    export: exportAppForAnalysis,\n    use,\n  };\n  return ret as unknown as AppDefinition<Env>;\n}\n\ntype AnyInterfaceType = {\n  [key: string]: AnyInterfaceType;\n} & AnyFunctionReference;\nexport type AnyComponentReference = Record<string, AnyInterfaceType>;\n\nexport type AnyChildComponents = Record<string, AnyComponentReference>;\n\n/**\n * @internal\n */\nexport function currentSystemUdfInComponent(\n  componentId: string,\n): AnyComponentReference {\n  return {\n    [toReferencePath]: `_reference/currentSystemUdfInComponent/${componentId}`,\n  };\n}\n\nfunction createChildComponents(\n  root: string,\n  pathParts: string[],\n): AnyChildComponents {\n  const handler: ProxyHandler<object> = {\n    get(_, prop: string | symbol) {\n      if (typeof prop === \"string\") {\n        const newParts = [...pathParts, prop];\n        return createChildComponents(root, newParts);\n      } else if (prop === toReferencePath) {\n        if (pathParts.length < 1) {\n          const found = [root, ...pathParts].join(\".\");\n          throw new Error(\n            `API path is expected to be of the form \\`${root}.childComponent.functionName\\`. Found: \\`${found}\\``,\n          );\n        }\n        return `_reference/childComponent/` + pathParts.join(\"/\");\n      } else {\n        return undefined;\n      }\n    },\n  };\n  return new Proxy({}, handler);\n}\n\nexport const componentsGeneric = () => createChildComponents(\"components\", []);\n\nexport type AnyComponents = AnyChildComponents;\n"],
+  "mappings": "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",
   "names": ["name"]
 }

package/dist/esm/server/cron.js

@@ -5,6 +5,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 import { getFunctionName } from "../server/api.js";
 import { parseArgs } from "../common/index.js";
 import { convexToJson } from "../values/index.js";
+import { getFunctionAddress } from "./components/paths.js";
 const DAYS_OF_WEEK = [
   "sunday",
   "monday",
@@ -44,6 +45,17 @@ function validatedMinuteOfHour(n) {
   }
   return n;
 }
+function validatedOptionalMinuteOfHour(n) {
+  return n === void 0 ? void 0 : validatedMinuteOfHour(n);
+}
+function isSchedulableFunctionReference(arg) {
+  try {
+    getFunctionAddress(arg);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function validatedCronString(s) {
   return s;
 }
@@ -111,31 +123,23 @@ export class Crons {
       ...args
     );
   }
-  /**
-   * Schedule a mutation or action to run on an hourly basis.
-   *
-   * ```js
-   * crons.hourly(
-   *   "Reset high scores",
-   *   {
-   *     minuteUTC: 30,
-   *   },
-   *   api.scores.reset
-   * )
-   * ```
-   *
-   * @param cronIdentifier - A unique name for this scheduled job.
-   * @param schedule - What time (UTC) each day to run this function.
-   * @param functionReference - A {@link FunctionReference} for the function
-   * to schedule.
-   * @param args - The arguments to the function.
-   */
-  hourly(cronIdentifier, schedule, functionReference, ...args) {
-    const minuteUTC = validatedMinuteOfHour(schedule.minuteUTC);
+  hourly(cronIdentifier, scheduleOrFunctionReference, functionReferenceOrArg, ...args) {
+    if (isSchedulableFunctionReference(scheduleOrFunctionReference)) {
+      this.schedule(
+        cronIdentifier,
+        { type: "hourly" },
+        scheduleOrFunctionReference,
+        functionReferenceOrArg
+      );
+      return;
+    }
+    const minuteUTC = validatedOptionalMinuteOfHour(
+      scheduleOrFunctionReference.minuteUTC
+    );
     this.schedule(
       cronIdentifier,
-      { minuteUTC, type: "hourly" },
-      functionReference,
+      minuteUTC === void 0 ? { type: "hourly" } : { minuteUTC, type: "hourly" },
+      functionReferenceOrArg,
       ...args
     );
   }
@@ -161,10 +165,10 @@ export class Crons {
    */
   daily(cronIdentifier, schedule, functionReference, ...args) {
     const hourUTC = validatedHourOfDay(schedule.hourUTC);
-    const minuteUTC = validatedMinuteOfHour(schedule.minuteUTC);
+    const minuteUTC = validatedOptionalMinuteOfHour(schedule.minuteUTC);
     this.schedule(
       cronIdentifier,
-      { hourUTC, minuteUTC, type: "daily" },
+      minuteUTC === void 0 ? { hourUTC, type: "daily" } : { hourUTC, minuteUTC, type: "daily" },
       functionReference,
       ...args
     );
@@ -192,10 +196,10 @@ export class Crons {
   weekly(cronIdentifier, schedule, functionReference, ...args) {
     const dayOfWeek = validatedDayOfWeek(schedule.dayOfWeek);
     const hourUTC = validatedHourOfDay(schedule.hourUTC);
-    const minuteUTC = validatedMinuteOfHour(schedule.minuteUTC);
+    const minuteUTC = validatedOptionalMinuteOfHour(schedule.minuteUTC);
     this.schedule(
       cronIdentifier,
-      { dayOfWeek, hourUTC, minuteUTC, type: "weekly" },
+      minuteUTC === void 0 ? { dayOfWeek, hourUTC, type: "weekly" } : { dayOfWeek, hourUTC, minuteUTC, type: "weekly" },
       functionReference,
       ...args
     );
@@ -227,10 +231,10 @@ export class Crons {
   monthly(cronIdentifier, schedule, functionReference, ...args) {
     const day = validatedDayOfMonth(schedule.day);
     const hourUTC = validatedHourOfDay(schedule.hourUTC);
-    const minuteUTC = validatedMinuteOfHour(schedule.minuteUTC);
+    const minuteUTC = validatedOptionalMinuteOfHour(schedule.minuteUTC);
     this.schedule(
       cronIdentifier,
-      { day, hourUTC, minuteUTC, type: "monthly" },
+      minuteUTC === void 0 ? { day, hourUTC, type: "monthly" } : { day, hourUTC, minuteUTC, type: "monthly" },
       functionReference,
       ...args
     );

package/dist/esm/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,SAAS,uBAAyC;AAClD,SAAS,iBAAiB;AAC1B,SAAS,oBAAsC;AAC/C,SAAS,0BAA0B;AAuBnC,MAAM,eAAe;AAAA,EACnB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAyJO,aAAM,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,uBAAmB,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,aAAM,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,WAAW,UAAU,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,MAAM,gBAAgB,iBAAiB;AAAA,MACvC,MAAM,CAAC,aAAa,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/esm/server/impl/database_impl.js

@@ -7,7 +7,7 @@ import { performAsyncSyscall, performSyscall } from "./syscall.js";
 import { QueryInitializerImpl } from "./query_impl.js";
 import { validateArg } from "./validate.js";
 import { version } from "../../index.js";
-import { patchValueToJson } from "../../values/value.js";
+import { commitTsPlaceholder, patchValueToJson } from "../../values/value.js";
 async function get(table, id, isSystem) {
   validateArg(id, 1, "get", "id");
   if (typeof id !== "string") {
@@ -120,6 +120,9 @@ export function setupWriter() {
     },
     table: (tableName) => {
       return new TableWriter(tableName, false);
+    },
+    vars: {
+      commitTs: commitTsPlaceholder
     }
   };
 }

package/dist/esm/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/esm/server/log.js

@@ -1,8 +1,9 @@
 "use strict";
 import { audit } from "./audit_logging.js";
-import { vars } from "./logVars.js";
+import { internalVars, vars } from "./logVars.js";
 export const log = {
   audit,
-  vars
+  vars,
+  internalVars
 };
 //# sourceMappingURL=log.js.map

package/dist/esm/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,SAAS,aAAa;AACtB,SAAS,YAAY;AA6Bd,aAAM,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,SAAS,aAAa;AACtB,SAAS,cAAc,YAAY;AA+B5B,aAAM,MAAW;AAAA,EACtB;AAAA,EACA;AAAA,EACA;AACF;",
   "names": []
 }

package/dist/esm/server/logVars.js

@@ -3,11 +3,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");
 export const varNames = {
   [REQUEST_ID]: "requestId",
   [IP]: "ip",
   [USER_AGENT]: "userAgent",
-  [NOW]: "now"
+  [NOW]: "now",
+  [CONVEX_ACTOR]: "convexActor"
 };
 export const vars = {
   /** Resolved to the request ID. */
@@ -22,4 +24,12 @@ export const vars = {
    */
   now: NOW
 };
+export const internalVars = {
+  /**
+   * If the function was invoked using admin auth (either directly or while
+   * acting as an end user, e.g. from the dashboard), resolved to information
+   * about the admin. Otherwise, resolved to `null`.
+   */
+  convexActor: CONVEX_ACTOR
+};
 //# sourceMappingURL=logVars.js.map

package/dist/esm/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,MAAM,aAAa,OAAO,eAAe;AACzC,MAAM,KAAK,OAAO,QAAQ;AAC1B,MAAM,aAAa,OAAO,eAAe;AACzC,MAAM,MAAM,OAAO,SAAS;AAQrB,aAAM,WAAmC;AAAA,EAC9C,CAAC,UAAU,GAAG;AAAA,EACd,CAAC,EAAE,GAAG;AAAA,EACN,CAAC,UAAU,GAAG;AAAA,EACd,CAAC,GAAG,GAAG;AACT;AAEO,aAAM,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,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,aAAM,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,aAAM,OAAO;AAAA;AAAA,EAElB,WAAW;AAAA;AAAA,EAEX,IAAI;AAAA;AAAA,EAEJ,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA,EAKX,KAAK;AACP;AAMO,aAAM,eAAe;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAM1B,aAAa;AACf;",
   "names": []
 }