convex 1.46.0 → 1.47.0

package/dist/cjs/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/index.ts"],
-  "sourcesContent": ["export const version = \"1.46.0\";\n"],
+  "sourcesContent": ["export const version = \"1.47.0\";\n"],
   "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,MAAM,UAAU;",
   "names": []
 }

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

@@ -19,6 +19,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var actions_impl_exports = {};
 __export(actions_impl_exports, {
   getServiceToken: () => getServiceToken,
+  getServiceUrl: () => getServiceUrl,
   setupActionCalls: () => setupActionCalls
 });
 module.exports = __toCommonJS(actions_impl_exports);
@@ -64,12 +65,16 @@ function setupActionCalls(requestId) {
 }
 async function getServiceToken(service) {
   (0, import_validate.validateArg)(service, 1, "getServiceToken", "service");
-  if (service !== "ai-gateway") {
-    throw new Error(`Unsupported service "${String(service)}"`);
-  }
   return await (0, import_syscall.performAsyncSyscall)("1.0/createServiceToken", {
     service,
     version: import__.version
   });
 }
+async function getServiceUrl(service) {
+  (0, import_validate.validateArg)(service, 1, "getServiceUrl", "service");
+  return await (0, import_syscall.performAsyncSyscall)("1.0/getServiceUrl", {
+    service,
+    version: import__.version
+  });
+}
 //# sourceMappingURL=actions_impl.js.map

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/server/impl/actions_impl.ts"],
-  "sourcesContent": ["import { convexToJson, jsonToConvex, Value } from \"../../values/index.js\";\nimport { version } from \"../../index.js\";\nimport { performAsyncSyscall } from \"./syscall.js\";\nimport { parseArgs } from \"../../common/index.js\";\nimport {\n  FunctionReference,\n  FunctionReference_future,\n} from \"../../server/api.js\";\nimport { getFunctionAddress } from \"../components/paths.js\";\nimport { validateArg } from \"./validate.js\";\n\nfunction syscallArgs(\n  requestId: string,\n  functionReference: any,\n  args?: Record<string, Value>,\n) {\n  const address = getFunctionAddress(functionReference);\n  return {\n    ...address,\n    args: convexToJson(parseArgs(args)),\n    version,\n    requestId,\n  };\n}\n\nexport function setupActionCalls(requestId: string) {\n  return {\n    runQuery: async (\n      query:\n        | FunctionReference<\"query\", \"public\" | \"internal\">\n        | FunctionReference_future<\"query\", \"public\" | \"internal\">,\n      args?: Record<string, Value>,\n    ): Promise<any> => {\n      const result = await performAsyncSyscall(\n        \"1.0/actions/query\",\n        syscallArgs(requestId, query, args),\n      );\n      return jsonToConvex(result);\n    },\n    runMutation: async (\n      mutation:\n        | FunctionReference<\"mutation\", \"public\" | \"internal\">\n        | FunctionReference_future<\"mutation\", \"public\" | \"internal\">,\n      args?: Record<string, Value>,\n    ): Promise<any> => {\n      const result = await performAsyncSyscall(\n        \"1.0/actions/mutation\",\n        syscallArgs(requestId, mutation, args),\n      );\n      return jsonToConvex(result);\n    },\n    runAction: async (\n      action:\n        | FunctionReference<\"action\", \"public\" | \"internal\">\n        | FunctionReference_future<\"action\", \"public\" | \"internal\">,\n      args?: Record<string, Value>,\n    ): Promise<any> => {\n      const result = await performAsyncSyscall(\n        \"1.0/actions/action\",\n        syscallArgs(requestId, action, args),\n      );\n      return jsonToConvex(result);\n    },\n  };\n}\n\n/**\n * Get a short-lived credential for calling a Convex-managed service.\n *\n * This function can only be called while an action is running. The credential\n * is scoped to the current deployment and should be sent as a bearer token.\n * Repeated calls in the same action reuse one token; a failed mint is not\n * cached, so a later call retries.\n *\n * @param service - The service the credential may access.\n * @returns A JWT to send as `Authorization: Bearer <token>`. Keep it inside\n * the action: don't return it to clients or store it in environment\n * variables.\n */\nexport async function getServiceToken(service: \"ai-gateway\"): Promise<string> {\n  validateArg(service, 1, \"getServiceToken\", \"service\");\n  if (service !== \"ai-gateway\") {\n    throw new Error(`Unsupported service \"${String(service)}\"`);\n  }\n  return await performAsyncSyscall(\"1.0/createServiceToken\", {\n    service,\n    version,\n  });\n}\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,oBAAkD;AAClD,eAAwB;AACxB,qBAAoC;AACpC,oBAA0B;AAK1B,mBAAmC;AACnC,sBAA4B;AAE5B,SAAS,YACP,WACA,mBACA,MACA;AACA,QAAM,cAAU,iCAAmB,iBAAiB;AACpD,SAAO;AAAA,IACL,GAAG;AAAA,IACH,UAAM,gCAAa,yBAAU,IAAI,CAAC;AAAA,IAClC;AAAA,IACA;AAAA,EACF;AACF;AAEO,SAAS,iBAAiB,WAAmB;AAClD,SAAO;AAAA,IACL,UAAU,OACR,OAGA,SACiB;AACjB,YAAM,SAAS,UAAM;AAAA,QACnB;AAAA,QACA,YAAY,WAAW,OAAO,IAAI;AAAA,MACpC;AACA,iBAAO,4BAAa,MAAM;AAAA,IAC5B;AAAA,IACA,aAAa,OACX,UAGA,SACiB;AACjB,YAAM,SAAS,UAAM;AAAA,QACnB;AAAA,QACA,YAAY,WAAW,UAAU,IAAI;AAAA,MACvC;AACA,iBAAO,4BAAa,MAAM;AAAA,IAC5B;AAAA,IACA,WAAW,OACT,QAGA,SACiB;AACjB,YAAM,SAAS,UAAM;AAAA,QACnB;AAAA,QACA,YAAY,WAAW,QAAQ,IAAI;AAAA,MACrC;AACA,iBAAO,4BAAa,MAAM;AAAA,IAC5B;AAAA,EACF;AACF;AAeA,eAAsB,gBAAgB,SAAwC;AAC5E,mCAAY,SAAS,GAAG,mBAAmB,SAAS;AACpD,MAAI,YAAY,cAAc;AAC5B,UAAM,IAAI,MAAM,wBAAwB,OAAO,OAAO,CAAC,GAAG;AAAA,EAC5D;AACA,SAAO,UAAM,oCAAoB,0BAA0B;AAAA,IACzD;AAAA,IACA;AAAA,EACF,CAAC;AACH;",
+  "sourcesContent": ["import { convexToJson, jsonToConvex, Value } from \"../../values/index.js\";\nimport { version } from \"../../index.js\";\nimport { performAsyncSyscall } from \"./syscall.js\";\nimport { parseArgs } from \"../../common/index.js\";\nimport {\n  FunctionReference,\n  FunctionReference_future,\n} from \"../../server/api.js\";\nimport { getFunctionAddress } from \"../components/paths.js\";\nimport { validateArg } from \"./validate.js\";\n\nfunction syscallArgs(\n  requestId: string,\n  functionReference: any,\n  args?: Record<string, Value>,\n) {\n  const address = getFunctionAddress(functionReference);\n  return {\n    ...address,\n    args: convexToJson(parseArgs(args)),\n    version,\n    requestId,\n  };\n}\n\nexport function setupActionCalls(requestId: string) {\n  return {\n    runQuery: async (\n      query:\n        | FunctionReference<\"query\", \"public\" | \"internal\">\n        | FunctionReference_future<\"query\", \"public\" | \"internal\">,\n      args?: Record<string, Value>,\n    ): Promise<any> => {\n      const result = await performAsyncSyscall(\n        \"1.0/actions/query\",\n        syscallArgs(requestId, query, args),\n      );\n      return jsonToConvex(result);\n    },\n    runMutation: async (\n      mutation:\n        | FunctionReference<\"mutation\", \"public\" | \"internal\">\n        | FunctionReference_future<\"mutation\", \"public\" | \"internal\">,\n      args?: Record<string, Value>,\n    ): Promise<any> => {\n      const result = await performAsyncSyscall(\n        \"1.0/actions/mutation\",\n        syscallArgs(requestId, mutation, args),\n      );\n      return jsonToConvex(result);\n    },\n    runAction: async (\n      action:\n        | FunctionReference<\"action\", \"public\" | \"internal\">\n        | FunctionReference_future<\"action\", \"public\" | \"internal\">,\n      args?: Record<string, Value>,\n    ): Promise<any> => {\n      const result = await performAsyncSyscall(\n        \"1.0/actions/action\",\n        syscallArgs(requestId, action, args),\n      );\n      return jsonToConvex(result);\n    },\n  };\n}\n\n/**\n * A Convex-managed service. The backend decides which names it accepts; this\n * type lists the ones the current release knows about.\n */\nexport type ServiceName = \"ai-gateway\";\n\n/**\n * Get a short-lived credential for calling a Convex-managed service.\n *\n * This function can only be called while an action is running. The credential\n * is scoped to the current deployment and should be sent as a bearer token.\n * The action runtime caches and refreshes credentials as needed, so call\n * this function whenever making a service request.\n *\n * @param service - The service the credential may access.\n * @returns A JWT to send as `Authorization: Bearer <token>`. Keep it inside\n * the action: don't return it to clients or store it in environment\n * variables.\n */\nexport async function getServiceToken(service: ServiceName): Promise<string> {\n  validateArg(service, 1, \"getServiceToken\", \"service\");\n  return await performAsyncSyscall(\"1.0/createServiceToken\", {\n    service,\n    version,\n  });\n}\n\n/**\n * Get the base URL of a Convex-managed service.\n *\n * This function can only be called while an action is running. Pair it with\n * {@link getServiceToken} to reach the service.\n *\n * @param service - The service to address.\n * @returns The service's origin, without a trailing slash.\n */\nexport async function getServiceUrl(service: ServiceName): Promise<string> {\n  validateArg(service, 1, \"getServiceUrl\", \"service\");\n  return await performAsyncSyscall(\"1.0/getServiceUrl\", {\n    service,\n    version,\n  });\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,oBAAkD;AAClD,eAAwB;AACxB,qBAAoC;AACpC,oBAA0B;AAK1B,mBAAmC;AACnC,sBAA4B;AAE5B,SAAS,YACP,WACA,mBACA,MACA;AACA,QAAM,cAAU,iCAAmB,iBAAiB;AACpD,SAAO;AAAA,IACL,GAAG;AAAA,IACH,UAAM,gCAAa,yBAAU,IAAI,CAAC;AAAA,IAClC;AAAA,IACA;AAAA,EACF;AACF;AAEO,SAAS,iBAAiB,WAAmB;AAClD,SAAO;AAAA,IACL,UAAU,OACR,OAGA,SACiB;AACjB,YAAM,SAAS,UAAM;AAAA,QACnB;AAAA,QACA,YAAY,WAAW,OAAO,IAAI;AAAA,MACpC;AACA,iBAAO,4BAAa,MAAM;AAAA,IAC5B;AAAA,IACA,aAAa,OACX,UAGA,SACiB;AACjB,YAAM,SAAS,UAAM;AAAA,QACnB;AAAA,QACA,YAAY,WAAW,UAAU,IAAI;AAAA,MACvC;AACA,iBAAO,4BAAa,MAAM;AAAA,IAC5B;AAAA,IACA,WAAW,OACT,QAGA,SACiB;AACjB,YAAM,SAAS,UAAM;AAAA,QACnB;AAAA,QACA,YAAY,WAAW,QAAQ,IAAI;AAAA,MACrC;AACA,iBAAO,4BAAa,MAAM;AAAA,IAC5B;AAAA,EACF;AACF;AAqBA,eAAsB,gBAAgB,SAAuC;AAC3E,mCAAY,SAAS,GAAG,mBAAmB,SAAS;AACpD,SAAO,UAAM,oCAAoB,0BAA0B;AAAA,IACzD;AAAA,IACA;AAAA,EACF,CAAC;AACH;AAWA,eAAsB,cAAc,SAAuC;AACzE,mCAAY,SAAS,GAAG,iBAAiB,SAAS;AAClD,SAAO,UAAM,oCAAoB,qBAAqB;AAAA,IACpD;AAAA,IACA;AAAA,EACF,CAAC;AACH;",
   "names": []
 }

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

@@ -24,6 +24,7 @@ __export(storage_impl_exports, {
 });
 module.exports = __toCommonJS(storage_impl_exports);
 var import__ = require("../../index.js");
+var import_base64 = require("../../values/base64.js");
 var import_syscall = require("./syscall.js");
 var import_validate = require("./validate.js");
 function setupStorageReader(requestId) {
@@ -61,6 +62,34 @@ function setupStorageWriter(requestId) {
         storageId
       });
     },
+    store: async (blob, options) => {
+      if (!(blob instanceof Blob)) {
+        throw new Error(
+          "store() expects a Blob. If you are trying to store a Request, `await request.blob()` will give you the correct input."
+        );
+      }
+      const bytes = new Uint8Array(await blob.arrayBuffer());
+      return await (0, import_syscall.performAsyncSyscall)("1.0/storageStore", {
+        requestId,
+        version: import__.version,
+        blob: (0, import_base64.fromByteArray)(bytes),
+        contentType: blob.type,
+        sha256: options?.sha256
+      });
+    },
+    get: async (storageId) => {
+      const result = await (0, import_syscall.performAsyncSyscall)("1.0/storageGet", {
+        requestId,
+        version: import__.version,
+        storageId
+      });
+      if (result === null) {
+        return null;
+      }
+      return new Blob([(0, import_base64.toByteArray)(result.blob)], {
+        type: result.contentType ?? ""
+      });
+    },
     getUrl: reader.getUrl,
     getMetadata: reader.getMetadata
   };

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/server/impl/storage_impl.ts"],
-  "sourcesContent": ["import {\n  FileMetadata,\n  StorageActionWriter,\n  FileStorageId,\n  StorageReader,\n  StorageWriter,\n} from \"../storage.js\";\nimport { version } from \"../../index.js\";\nimport { performAsyncSyscall, performJsSyscall } from \"./syscall.js\";\nimport { validateArg } from \"./validate.js\";\n\nexport function setupStorageReader(requestId: string): StorageReader {\n  return {\n    getUrl: async (storageId: FileStorageId) => {\n      validateArg(storageId, 1, \"getUrl\", \"storageId\");\n      return await performAsyncSyscall(\"1.0/storageGetUrl\", {\n        requestId,\n        version,\n        storageId,\n      });\n    },\n    getMetadata: async (storageId: FileStorageId): Promise<FileMetadata> => {\n      return await performAsyncSyscall(\"1.0/storageGetMetadata\", {\n        requestId,\n        version,\n        storageId,\n      });\n    },\n  };\n}\n\nexport function setupStorageWriter(requestId: string): StorageWriter {\n  const reader = setupStorageReader(requestId);\n  return {\n    generateUploadUrl: async () => {\n      return await performAsyncSyscall(\"1.0/storageGenerateUploadUrl\", {\n        requestId,\n        version,\n      });\n    },\n    delete: async (storageId: FileStorageId) => {\n      await performAsyncSyscall(\"1.0/storageDelete\", {\n        requestId,\n        version,\n        storageId,\n      });\n    },\n    getUrl: reader.getUrl,\n    getMetadata: reader.getMetadata,\n  };\n}\n\nexport function setupStorageActionWriter(\n  requestId: string,\n): StorageActionWriter {\n  const writer = setupStorageWriter(requestId);\n  return {\n    ...writer,\n    store: async (blob: Blob, options?: { sha256?: string }) => {\n      return await performJsSyscall(\"storage/storeBlob\", {\n        requestId,\n        version,\n        blob,\n        options,\n      });\n    },\n    get: async (storageId: FileStorageId) => {\n      return await performJsSyscall(\"storage/getBlob\", {\n        requestId,\n        version,\n        storageId,\n      });\n    },\n  };\n}\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,eAAwB;AACxB,qBAAsD;AACtD,sBAA4B;AAErB,SAAS,mBAAmB,WAAkC;AACnE,SAAO;AAAA,IACL,QAAQ,OAAO,cAA6B;AAC1C,uCAAY,WAAW,GAAG,UAAU,WAAW;AAC/C,aAAO,UAAM,oCAAoB,qBAAqB;AAAA,QACpD;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH;AAAA,IACA,aAAa,OAAO,cAAoD;AACtE,aAAO,UAAM,oCAAoB,0BAA0B;AAAA,QACzD;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAEO,SAAS,mBAAmB,WAAkC;AACnE,QAAM,SAAS,mBAAmB,SAAS;AAC3C,SAAO;AAAA,IACL,mBAAmB,YAAY;AAC7B,aAAO,UAAM,oCAAoB,gCAAgC;AAAA,QAC/D;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH;AAAA,IACA,QAAQ,OAAO,cAA6B;AAC1C,gBAAM,oCAAoB,qBAAqB;AAAA,QAC7C;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH;AAAA,IACA,QAAQ,OAAO;AAAA,IACf,aAAa,OAAO;AAAA,EACtB;AACF;AAEO,SAAS,yBACd,WACqB;AACrB,QAAM,SAAS,mBAAmB,SAAS;AAC3C,SAAO;AAAA,IACL,GAAG;AAAA,IACH,OAAO,OAAO,MAAY,YAAkC;AAC1D,aAAO,UAAM,iCAAiB,qBAAqB;AAAA,QACjD;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH;AAAA,IACA,KAAK,OAAO,cAA6B;AACvC,aAAO,UAAM,iCAAiB,mBAAmB;AAAA,QAC/C;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AACF;",
+  "sourcesContent": ["import {\n  FileMetadata,\n  StorageActionWriter,\n  FileStorageId,\n  StorageReader,\n  StorageWriter,\n} from \"../storage.js\";\nimport { version } from \"../../index.js\";\nimport { fromByteArray, toByteArray } from \"../../values/base64.js\";\nimport { performAsyncSyscall, performJsSyscall } from \"./syscall.js\";\nimport { validateArg } from \"./validate.js\";\n\nexport function setupStorageReader(requestId: string): StorageReader {\n  return {\n    getUrl: async (storageId: FileStorageId) => {\n      validateArg(storageId, 1, \"getUrl\", \"storageId\");\n      return await performAsyncSyscall(\"1.0/storageGetUrl\", {\n        requestId,\n        version,\n        storageId,\n      });\n    },\n    getMetadata: async (storageId: FileStorageId): Promise<FileMetadata> => {\n      return await performAsyncSyscall(\"1.0/storageGetMetadata\", {\n        requestId,\n        version,\n        storageId,\n      });\n    },\n  };\n}\n\nexport function setupStorageWriter(requestId: string): StorageWriter {\n  const reader = setupStorageReader(requestId);\n  return {\n    generateUploadUrl: async () => {\n      return await performAsyncSyscall(\"1.0/storageGenerateUploadUrl\", {\n        requestId,\n        version,\n      });\n    },\n    delete: async (storageId: FileStorageId) => {\n      await performAsyncSyscall(\"1.0/storageDelete\", {\n        requestId,\n        version,\n        storageId,\n      });\n    },\n    store: async (blob: Blob, options?: { sha256?: string }) => {\n      if (!(blob instanceof Blob)) {\n        throw new Error(\n          \"store() expects a Blob. If you are trying to store a Request, `await request.blob()` will give you the correct input.\",\n        );\n      }\n      const bytes = new Uint8Array(await blob.arrayBuffer());\n      return await performAsyncSyscall(\"1.0/storageStore\", {\n        requestId,\n        version,\n        blob: fromByteArray(bytes),\n        contentType: blob.type,\n        sha256: options?.sha256,\n      });\n    },\n    get: async (storageId: FileStorageId) => {\n      const result: { blob: string; contentType: string | null } | null =\n        await performAsyncSyscall(\"1.0/storageGet\", {\n          requestId,\n          version,\n          storageId,\n        });\n      if (result === null) {\n        return null;\n      }\n      return new Blob([toByteArray(result.blob)], {\n        type: result.contentType ?? \"\",\n      });\n    },\n    getUrl: reader.getUrl,\n    getMetadata: reader.getMetadata,\n  };\n}\n\nexport function setupStorageActionWriter(\n  requestId: string,\n): StorageActionWriter {\n  const writer = setupStorageWriter(requestId);\n  return {\n    ...writer,\n    store: async (blob: Blob, options?: { sha256?: string }) => {\n      return await performJsSyscall(\"storage/storeBlob\", {\n        requestId,\n        version,\n        blob,\n        options,\n      });\n    },\n    get: async (storageId: FileStorageId) => {\n      return await performJsSyscall(\"storage/getBlob\", {\n        requestId,\n        version,\n        storageId,\n      });\n    },\n  };\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,eAAwB;AACxB,oBAA2C;AAC3C,qBAAsD;AACtD,sBAA4B;AAErB,SAAS,mBAAmB,WAAkC;AACnE,SAAO;AAAA,IACL,QAAQ,OAAO,cAA6B;AAC1C,uCAAY,WAAW,GAAG,UAAU,WAAW;AAC/C,aAAO,UAAM,oCAAoB,qBAAqB;AAAA,QACpD;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH;AAAA,IACA,aAAa,OAAO,cAAoD;AACtE,aAAO,UAAM,oCAAoB,0BAA0B;AAAA,QACzD;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAEO,SAAS,mBAAmB,WAAkC;AACnE,QAAM,SAAS,mBAAmB,SAAS;AAC3C,SAAO;AAAA,IACL,mBAAmB,YAAY;AAC7B,aAAO,UAAM,oCAAoB,gCAAgC;AAAA,QAC/D;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH;AAAA,IACA,QAAQ,OAAO,cAA6B;AAC1C,gBAAM,oCAAoB,qBAAqB;AAAA,QAC7C;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH;AAAA,IACA,OAAO,OAAO,MAAY,YAAkC;AAC1D,UAAI,EAAE,gBAAgB,OAAO;AAC3B,cAAM,IAAI;AAAA,UACR;AAAA,QACF;AAAA,MACF;AACA,YAAM,QAAQ,IAAI,WAAW,MAAM,KAAK,YAAY,CAAC;AACrD,aAAO,UAAM,oCAAoB,oBAAoB;AAAA,QACnD;AAAA,QACA;AAAA,QACA,UAAM,6BAAc,KAAK;AAAA,QACzB,aAAa,KAAK;AAAA,QAClB,QAAQ,SAAS;AAAA,MACnB,CAAC;AAAA,IACH;AAAA,IACA,KAAK,OAAO,cAA6B;AACvC,YAAM,SACJ,UAAM,oCAAoB,kBAAkB;AAAA,QAC1C;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AACH,UAAI,WAAW,MAAM;AACnB,eAAO;AAAA,MACT;AACA,aAAO,IAAI,KAAK,KAAC,2BAAY,OAAO,IAAI,CAAC,GAAG;AAAA,QAC1C,MAAM,OAAO,eAAe;AAAA,MAC9B,CAAC;AAAA,IACH;AAAA,IACA,QAAQ,OAAO;AAAA,IACf,aAAa,OAAO;AAAA,EACtB;AACF;AAEO,SAAS,yBACd,WACqB;AACrB,QAAM,SAAS,mBAAmB,SAAS;AAC3C,SAAO;AAAA,IACL,GAAG;AAAA,IACH,OAAO,OAAO,MAAY,YAAkC;AAC1D,aAAO,UAAM,iCAAiB,qBAAqB;AAAA,QACjD;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH;AAAA,IACA,KAAK,OAAO,cAA6B;AACvC,aAAO,UAAM,iCAAiB,mBAAmB;AAAA,QAC/C;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AACF;",
   "names": []
 }

package/dist/cjs/server/index.js

@@ -36,6 +36,7 @@ __export(server_exports, {
   getFunctionAddress: () => import_components3.getFunctionAddress,
   getFunctionName: () => import_api.getFunctionName,
   getServiceToken: () => import_actions_impl.getServiceToken,
+  getServiceUrl: () => import_actions_impl.getServiceUrl,
   httpActionGeneric: () => import_registration_impl.httpActionGeneric,
   httpRouter: () => import_router.httpRouter,
   internalActionGeneric: () => import_registration_impl.internalActionGeneric,

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/server/index.ts"],
-  "sourcesContent": ["/**\n * Utilities for implementing server-side Convex query and mutation functions.\n *\n * ## Usage\n *\n * ### Code Generation\n *\n * This module is typically used alongside generated server code.\n *\n * To generate the server code, run `npx convex dev` in your Convex project.\n * This will create a `convex/_generated/server.js` file with the following\n * functions, typed for your schema:\n * - [query](https://docs.convex.dev/generated-api/server#query)\n * - [mutation](https://docs.convex.dev/generated-api/server#mutation)\n *\n * If you aren't using TypeScript and code generation, you can use these untyped\n * functions instead:\n * - {@link queryGeneric}\n * - {@link mutationGeneric}\n *\n * ### Example\n *\n * Convex functions are defined by using either the `query` or\n * `mutation` wrappers.\n *\n * Queries receive a `db` that implements the {@link GenericDatabaseReader} interface.\n *\n * ```js\n * import { query } from \"./_generated/server\";\n *\n * export default query({\n *   handler: async ({ db }, { arg1, arg2 }) => {\n *     // Your (read-only) code here!\n *   },\n * });\n * ```\n *\n * If your function needs to write to the database, such as inserting, updating,\n * or deleting documents, use `mutation` instead which provides a `db` that\n * implements the {@link GenericDatabaseWriter} interface.\n *\n * ```js\n * import { mutation } from \"./_generated/server\";\n *\n * export default mutation({\n *   handler: async ({ db }, { arg1, arg2 }) => {\n *     // Your mutation code here!\n *   },\n * });\n * ```\n * @module\n */\n\nexport type {\n  Auth,\n  AuthConfig,\n  AuthProvider,\n  UserIdentity,\n  UserIdentityAttributes,\n} from \"./authentication.js\";\nexport * from \"./database.js\";\nexport type {\n  GenericDocument,\n  GenericFieldPaths,\n  GenericIndexFields,\n  GenericTableIndexes,\n  GenericSearchIndexConfig,\n  GenericTableSearchIndexes,\n  GenericVectorIndexConfig,\n  GenericTableVectorIndexes,\n  FieldTypeFromFieldPath,\n  FieldTypeFromFieldPathInner,\n  GenericTableInfo,\n  DocumentByInfo,\n  FieldPaths,\n  Indexes,\n  IndexNames,\n  NamedIndex,\n  SearchIndexes,\n  SearchIndexNames,\n  NamedSearchIndex,\n  VectorIndexes,\n  VectorIndexNames,\n  NamedVectorIndex,\n  GenericDataModel,\n  AnyDataModel,\n  TableNamesInDataModel,\n  NamedTableInfo,\n  DocumentByName,\n} from \"./data_model.js\";\n\nexport type {\n  Expression,\n  ExpressionOrValue,\n  FilterBuilder,\n} from \"./filter_builder.js\";\nexport {\n  actionGeneric,\n  httpActionGeneric,\n  mutationGeneric,\n  queryGeneric,\n  internalActionGeneric,\n  internalMutationGeneric,\n  internalQueryGeneric,\n} from \"./impl/registration_impl.js\";\nexport { getServiceToken } from \"./impl/actions_impl.js\";\nexport type {\n  TransactionMetric,\n  TransactionMetrics,\n  TransactionLimits,\n  FunctionMetadata,\n  DeploymentMetadata,\n  RequestMetadata,\n  QueryMeta,\n  MutationMeta,\n  ActionMeta,\n} from \"./meta.js\";\nexport type { IndexRange, IndexRangeBuilder } from \"./index_range_builder.js\";\nexport * from \"./pagination.js\";\nexport type { OrderedQuery, Query, QueryInitializer } from \"./query.js\";\nexport type {\n  AdvancedRunQueryOptions,\n  ArgsArray,\n  DefaultFunctionArgs,\n  FunctionVisibility,\n  ActionBuilder,\n  MutationBuilder,\n  MutationBuilderWithTable,\n  QueryBuilder,\n  QueryBuilderWithTable,\n  HttpActionBuilder,\n  GenericActionCtx,\n  GenericMutationCtx,\n  GenericMutationCtxWithTable,\n  GenericQueryCtx,\n  GenericQueryCtxWithTable,\n  RegisteredAction,\n  RegisteredMutation,\n  RegisteredQuery,\n  PublicHttpAction,\n  UnvalidatedFunction,\n  ValidatedFunction,\n  ReturnValueForOptionalValidator,\n  ArgsArrayForOptionalValidator,\n  ArgsArrayToObject,\n  DefaultArgsForOptionalValidator,\n} from \"./registration.js\";\nexport * from \"./search_filter_builder.js\";\nexport * from \"./storage.js\";\nexport type { Scheduler, SchedulableFunctionReference } from \"./scheduler.js\";\nexport { cronJobs } from \"./cron.js\";\nexport type { CronJob, Crons } from \"./cron.js\";\nexport type {\n  SystemFields,\n  IdField,\n  WithoutSystemFields,\n  WithOptionalSystemFields,\n  SystemIndexes,\n  IndexTiebreakerField,\n} from \"./system_fields.js\";\nexport { httpRouter, HttpRouter, ROUTABLE_HTTP_METHODS } from \"./router.js\";\nexport type {\n  RoutableMethod,\n  RouteSpec,\n  RouteSpecWithPath,\n  RouteSpecWithPathPrefix,\n} from \"./router.js\";\nexport {\n  anyApi,\n  getFunctionName,\n  makeFunctionReference,\n  filterApi,\n} from \"./api.js\";\nexport type {\n  ApiFromModules,\n  AnyApi,\n  FunctionReference_future,\n  FilterApi,\n  FunctionType,\n  FunctionReference,\n  FunctionArgs,\n  OptionalRestArgs,\n  PartialApi,\n  ArgsAndOptions,\n  FunctionReturnType,\n  ValidatorTypeToReturnType,\n} from \"./api.js\";\nexport {\n  defineApp,\n  defineComponent,\n  componentsGeneric,\n  createFunctionHandle,\n  type AnyChildComponents,\n  type EnvDefinition,\n  type EnvFromDefinition,\n  type EnvFromAppDefinition,\n  type AppDefinition,\n} from \"./components/index.js\";\n/**\n * @internal\n */\nexport { currentSystemUdfInComponent } from \"./components/index.js\";\nexport { getFunctionAddress } from \"./components/index.js\";\nexport type {\n  ComponentDefinition,\n  AnyComponents,\n  FunctionHandle,\n} from \"./components/index.js\";\n\n/**\n * @internal\n */\nexport type { Index, SearchIndex, VectorIndex } from \"./schema.js\";\n\nexport { log } from \"./log.js\";\nexport type { AuditLogBody, AuditLogValue } from \"./audit_logging.js\";\n\nexport type {\n  SearchIndexConfig,\n  VectorIndexConfig,\n  TableDefinition,\n  SchemaDefinition,\n  DefineSchemaOptions,\n  GenericSchema,\n  DataModelFromSchemaDefinition,\n  SystemDataModel,\n  SystemTableNames,\n  DocValidator,\n  SystemFieldValidators,\n} from \"./schema.js\";\nexport { defineTable, defineSchema, docValidator } from \"./schema.js\";\n\nexport type {\n  VectorSearch,\n  VectorSearchQuery,\n  VectorFilterBuilder,\n  FilterExpression,\n} from \"./vector_search.js\";\n\n/**\n * @public\n */\nexport type { BetterOmit, Expand } from \"../type_utils.js\";\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;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;AAAA;AAAA;AAAA;AAAA;AAAA;AA4DA,2BAAc,0BA5Dd;AAgGA,+BAQO;AACP,0BAAgC;AAahC,2BAAc,4BAtHd;AAmJA,2BAAc,uCAnJd;AAoJA,2BAAc,yBApJd;AAsJA,kBAAyB;AAUzB,oBAA8D;AAO9D,iBAKO;AAeP,wBAUO;AAIP,IAAAA,qBAA4C;AAC5C,IAAAA,qBAAmC;AAYnC,iBAAoB;AAgBpB,oBAAwD;",
+  "sourcesContent": ["/**\n * Utilities for implementing server-side Convex query and mutation functions.\n *\n * ## Usage\n *\n * ### Code Generation\n *\n * This module is typically used alongside generated server code.\n *\n * To generate the server code, run `npx convex dev` in your Convex project.\n * This will create a `convex/_generated/server.js` file with the following\n * functions, typed for your schema:\n * - [query](https://docs.convex.dev/generated-api/server#query)\n * - [mutation](https://docs.convex.dev/generated-api/server#mutation)\n *\n * If you aren't using TypeScript and code generation, you can use these untyped\n * functions instead:\n * - {@link queryGeneric}\n * - {@link mutationGeneric}\n *\n * ### Example\n *\n * Convex functions are defined by using either the `query` or\n * `mutation` wrappers.\n *\n * Queries receive a `db` that implements the {@link GenericDatabaseReader} interface.\n *\n * ```js\n * import { query } from \"./_generated/server\";\n *\n * export default query({\n *   handler: async ({ db }, { arg1, arg2 }) => {\n *     // Your (read-only) code here!\n *   },\n * });\n * ```\n *\n * If your function needs to write to the database, such as inserting, updating,\n * or deleting documents, use `mutation` instead which provides a `db` that\n * implements the {@link GenericDatabaseWriter} interface.\n *\n * ```js\n * import { mutation } from \"./_generated/server\";\n *\n * export default mutation({\n *   handler: async ({ db }, { arg1, arg2 }) => {\n *     // Your mutation code here!\n *   },\n * });\n * ```\n * @module\n */\n\nexport type {\n  Auth,\n  AuthConfig,\n  AuthProvider,\n  UserIdentity,\n  UserIdentityAttributes,\n} from \"./authentication.js\";\nexport * from \"./database.js\";\nexport type {\n  GenericDocument,\n  GenericFieldPaths,\n  GenericIndexFields,\n  GenericTableIndexes,\n  GenericSearchIndexConfig,\n  GenericTableSearchIndexes,\n  GenericVectorIndexConfig,\n  GenericTableVectorIndexes,\n  FieldTypeFromFieldPath,\n  FieldTypeFromFieldPathInner,\n  GenericTableInfo,\n  DocumentByInfo,\n  FieldPaths,\n  Indexes,\n  IndexNames,\n  NamedIndex,\n  SearchIndexes,\n  SearchIndexNames,\n  NamedSearchIndex,\n  VectorIndexes,\n  VectorIndexNames,\n  NamedVectorIndex,\n  GenericDataModel,\n  AnyDataModel,\n  TableNamesInDataModel,\n  NamedTableInfo,\n  DocumentByName,\n} from \"./data_model.js\";\n\nexport type {\n  Expression,\n  ExpressionOrValue,\n  FilterBuilder,\n} from \"./filter_builder.js\";\nexport {\n  actionGeneric,\n  httpActionGeneric,\n  mutationGeneric,\n  queryGeneric,\n  internalActionGeneric,\n  internalMutationGeneric,\n  internalQueryGeneric,\n} from \"./impl/registration_impl.js\";\nexport {\n  getServiceToken,\n  getServiceUrl,\n  type ServiceName,\n} from \"./impl/actions_impl.js\";\nexport type {\n  TransactionMetric,\n  TransactionMetrics,\n  TransactionLimits,\n  FunctionMetadata,\n  DeploymentMetadata,\n  RequestMetadata,\n  QueryMeta,\n  MutationMeta,\n  ActionMeta,\n} from \"./meta.js\";\nexport type { IndexRange, IndexRangeBuilder } from \"./index_range_builder.js\";\nexport * from \"./pagination.js\";\nexport type { OrderedQuery, Query, QueryInitializer } from \"./query.js\";\nexport type {\n  AdvancedRunQueryOptions,\n  ArgsArray,\n  DefaultFunctionArgs,\n  FunctionVisibility,\n  ActionBuilder,\n  MutationBuilder,\n  MutationBuilderWithTable,\n  QueryBuilder,\n  QueryBuilderWithTable,\n  HttpActionBuilder,\n  GenericActionCtx,\n  GenericMutationCtx,\n  GenericMutationCtxWithTable,\n  GenericQueryCtx,\n  GenericQueryCtxWithTable,\n  RegisteredAction,\n  RegisteredMutation,\n  RegisteredQuery,\n  PublicHttpAction,\n  UnvalidatedFunction,\n  ValidatedFunction,\n  ReturnValueForOptionalValidator,\n  ArgsArrayForOptionalValidator,\n  ArgsArrayToObject,\n  DefaultArgsForOptionalValidator,\n} from \"./registration.js\";\nexport * from \"./search_filter_builder.js\";\nexport * from \"./storage.js\";\nexport type { Scheduler, SchedulableFunctionReference } from \"./scheduler.js\";\nexport { cronJobs } from \"./cron.js\";\nexport type { CronJob, Crons } from \"./cron.js\";\nexport type {\n  SystemFields,\n  IdField,\n  WithoutSystemFields,\n  WithOptionalSystemFields,\n  SystemIndexes,\n  IndexTiebreakerField,\n} from \"./system_fields.js\";\nexport { httpRouter, HttpRouter, ROUTABLE_HTTP_METHODS } from \"./router.js\";\nexport type {\n  RoutableMethod,\n  RouteSpec,\n  RouteSpecWithPath,\n  RouteSpecWithPathPrefix,\n} from \"./router.js\";\nexport {\n  anyApi,\n  getFunctionName,\n  makeFunctionReference,\n  filterApi,\n} from \"./api.js\";\nexport type {\n  ApiFromModules,\n  AnyApi,\n  FunctionReference_future,\n  FilterApi,\n  FunctionType,\n  FunctionReference,\n  FunctionArgs,\n  OptionalRestArgs,\n  PartialApi,\n  ArgsAndOptions,\n  FunctionReturnType,\n  ValidatorTypeToReturnType,\n} from \"./api.js\";\nexport {\n  defineApp,\n  defineComponent,\n  componentsGeneric,\n  createFunctionHandle,\n  type AnyChildComponents,\n  type EnvDefinition,\n  type EnvFromDefinition,\n  type EnvFromAppDefinition,\n  type AppDefinition,\n} from \"./components/index.js\";\n/**\n * @internal\n */\nexport { currentSystemUdfInComponent } from \"./components/index.js\";\nexport { getFunctionAddress } from \"./components/index.js\";\nexport type {\n  ComponentDefinition,\n  AnyComponents,\n  FunctionHandle,\n} from \"./components/index.js\";\n\n/**\n * @internal\n */\nexport type { Index, SearchIndex, VectorIndex } from \"./schema.js\";\n\nexport { log } from \"./log.js\";\nexport type { AuditLogBody, AuditLogValue } from \"./audit_logging.js\";\n\nexport type {\n  SearchIndexConfig,\n  VectorIndexConfig,\n  TableDefinition,\n  SchemaDefinition,\n  DefineSchemaOptions,\n  GenericSchema,\n  DataModelFromSchemaDefinition,\n  SystemDataModel,\n  SystemTableNames,\n  DocValidator,\n  SystemFieldValidators,\n} from \"./schema.js\";\nexport { defineTable, defineSchema, docValidator } from \"./schema.js\";\n\nexport type {\n  VectorSearch,\n  VectorSearchQuery,\n  VectorFilterBuilder,\n  FilterExpression,\n} from \"./vector_search.js\";\n\n/**\n * @public\n */\nexport type { BetterOmit, Expand } from \"../type_utils.js\";\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;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;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA4DA,2BAAc,0BA5Dd;AAgGA,+BAQO;AACP,0BAIO;AAaP,2BAAc,4BA1Hd;AAuJA,2BAAc,uCAvJd;AAwJA,2BAAc,yBAxJd;AA0JA,kBAAyB;AAUzB,oBAA8D;AAO9D,iBAKO;AAeP,wBAUO;AAIP,IAAAA,qBAA4C;AAC5C,IAAAA,qBAAmC;AAYnC,iBAAoB;AAgBpB,oBAAwD;",
   "names": ["import_components"]
 }

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/server/meta.ts"],
-  "sourcesContent": ["import { FunctionType } from \"./api.js\";\nimport { FunctionVisibility } from \"./registration.js\";\n\n/**\n * Used and remaining amounts for a single transaction limit.\n *\n * @public\n */\nexport type TransactionMetric = {\n  used: number;\n  remaining: number;\n};\n\n/**\n * The remaining headroom for a transaction before hitting limits.\n *\n * See https://docs.convex.dev/production/state/limits\n *\n * @public\n */\nexport type TransactionMetrics = {\n  bytesRead: TransactionMetric;\n  bytesWritten: TransactionMetric;\n  databaseQueries: TransactionMetric;\n  documentsRead: TransactionMetric;\n  documentsWritten: TransactionMetric;\n  functionsScheduled: TransactionMetric;\n  scheduledFunctionArgsBytes: TransactionMetric;\n};\n\n/**\n * Custom limits for a nested transaction. Each field specifies the absolute\n * maximum allowed for the nested function call. Values are capped at the\n * global transaction limits, so they can only lower limits, never raise them.\n *\n * @public\n */\nexport interface TransactionLimits {\n  bytesRead?: number;\n  bytesWritten?: number;\n  databaseQueries?: number;\n  documentsRead?: number;\n  documentsWritten?: number;\n  functionsScheduled?: number;\n  scheduledFunctionArgsBytes?: number;\n}\n\n/**\n * Metadata about the currently executing Convex function.\n *\n * @public\n */\nexport type FunctionMetadata = {\n  /**\n   * The name of the function, in the format `\"path/to/module:functionName\"`\n   */\n  name: string;\n  /**\n   * The path of the component this function belongs to.\n   * This is an empty string `\"\"` for the app.\n   */\n  componentPath: string;\n  /** Whether it's a query, mutation, or action. */\n  type: FunctionType;\n  /** Whether the function is public or internal. */\n  visibility: FunctionVisibility;\n};\n\n/**\n * Metadata about the deployment this function is running on.\n *\n * @public\n */\nexport type DeploymentMetadata = {\n  /**\n   * The deployment name, e.g. `\"tall-tiger-123\"` for cloud deployments,\n   * `\"local-my_team-my_project\"` for local deployments, or\n   * `\"anonymous-*\"` for anonymous deployments.\n   */\n  name: string;\n  /**\n   * The deployment region, e.g. `\"aws-us-east-1\"`.\n   * `null` for local and self-hosted deployments.\n   */\n  region: string | null;\n  /**\n   * The deployment class, e.g. `\"s16\"`, `\"s256\"`, `\"d1024\"`, or `\"d2048\"`.\n   */\n  class: \"s16\" | \"s256\" | \"d1024\" | \"d2048\";\n};\n\n/**\n * Metadata about the HTTP request that triggered the current function execution.\n *\n * `ip` and `userAgent` are `null` when the function was not triggered by an\n * HTTP request (e.g. scheduled jobs or cron jobs).\n *\n * Functions called from within a function (i.e. using `runMutation` or\n * `runAction`) will have the same request metadata as the parent function.\n *\n * @public\n */\nexport type RequestMetadata = {\n  ip: string | null;\n  userAgent: string | null;\n  requestId: string;\n  /**\n   * The ID of the scheduled function document (in `_scheduled_functions`) that\n   * this execution belongs to, or `null` otherwise.\n   *\n   * This is set for the scheduled function itself and for any functions it\n   * calls (e.g. a mutation invoked via `runMutation` by a scheduled action),\n   * propagating the top-level scheduled function's ID down the call tree. It is\n   * `null` when the function was not scheduled.\n   */\n  scheduledFunctionId: string | null;\n  /**\n   * The raw auth token (a JWT) the request was authenticated with, or `null`\n   * when the request was unauthenticated or authenticated with an admin key.\n   *\n   * This is the same token that `ctx.auth.getUserIdentity()` derives its\n   * attributes from.\n   */\n  authToken: string | null;\n};\n\n/**\n * Extra context available in Convex query functions.\n *\n * @public\n */\nexport interface QueryMeta {\n  getFunctionMetadata(): Promise<FunctionMetadata>;\n  getTransactionMetrics(): Promise<TransactionMetrics>;\n  getDeploymentMetadata(): Promise<DeploymentMetadata>;\n  /**\n   * @internal\n   * Returns the timestamp of the database snapshot this transaction reads\n   * from, in nanoseconds.\n   *\n   * All commits at or before this timestamp are observable within the\n   * transaction, and no later commits are. The value is fixed for the\n   * lifetime of the transaction and shared with all nested `runMutation` and\n   * `runQuery` calls.\n   *\n   * It is on the same clock as `db.vars.commitTs`: documents observable in\n   * this transaction have `commitTs` values at or before this timestamp, and\n   * no new documents will be written with a `commitTs` at or below this,\n   * including from the current transaction. When reading documents with an\n   * index in commitTs order, you can use this as an upper bound to prevent\n   * conflicting with racing inserts.\n   *\n   * Since the timestamp differs on every execution, calling this in a query\n   * limits caching of the query's result the same way `Date.now()` does.\n   *\n   * Note: this should not be compared to `_creationTime` or `Date.now()`, as\n   * those are based on wall-clock time rather than the database clock, and\n   * aren't guaranteed to follow commit order.\n   */\n  getSnapshotTs(): bigint;\n}\n\n/**\n * Extra context available in Convex mutation functions.\n *\n * @public\n */\nexport interface MutationMeta extends QueryMeta {\n  getRequestMetadata(): Promise<RequestMetadata>;\n}\n\n/**\n * Extra context available in Convex action functions.\n *\n * @public\n */\nexport interface ActionMeta {\n  getFunctionMetadata(): Promise<FunctionMetadata>;\n  getDeploymentMetadata(): Promise<DeploymentMetadata>;\n  getRequestMetadata(): Promise<RequestMetadata>;\n}\n"],
+  "sourcesContent": ["import { FunctionType } from \"./api.js\";\nimport { FunctionVisibility } from \"./registration.js\";\n\n/**\n * Used and remaining amounts for a single transaction limit.\n *\n * @public\n */\nexport type TransactionMetric = {\n  used: number;\n  remaining: number;\n};\n\n/**\n * The remaining headroom for a transaction before hitting limits.\n *\n * See https://docs.convex.dev/production/state/limits\n *\n * @public\n */\nexport type TransactionMetrics = {\n  bytesRead: TransactionMetric;\n  bytesWritten: TransactionMetric;\n  databaseQueries: TransactionMetric;\n  documentsRead: TransactionMetric;\n  documentsWritten: TransactionMetric;\n  functionsScheduled: TransactionMetric;\n  scheduledFunctionArgsBytes: TransactionMetric;\n  /** @internal */\n  filesWritten: TransactionMetric;\n  /** @internal */\n  fileWriteBytes: TransactionMetric;\n  /** @internal */\n  filesRead: TransactionMetric;\n  /** @internal */\n  fileReadBytes: TransactionMetric;\n};\n\n/**\n * Custom limits for a nested transaction. Each field specifies the absolute\n * maximum allowed for the nested function call. Values are capped at the\n * global transaction limits, so they can only lower limits, never raise them.\n *\n * @public\n */\nexport interface TransactionLimits {\n  bytesRead?: number;\n  bytesWritten?: number;\n  databaseQueries?: number;\n  documentsRead?: number;\n  documentsWritten?: number;\n  functionsScheduled?: number;\n  scheduledFunctionArgsBytes?: number;\n  /** @internal */\n  filesWritten?: number;\n  /** @internal */\n  fileWriteBytes?: number;\n  /** @internal */\n  filesRead?: number;\n  /** @internal */\n  fileReadBytes?: number;\n}\n\n/**\n * Metadata about the currently executing Convex function.\n *\n * @public\n */\nexport type FunctionMetadata = {\n  /**\n   * The name of the function, in the format `\"path/to/module:functionName\"`\n   */\n  name: string;\n  /**\n   * The path of the component this function belongs to.\n   * This is an empty string `\"\"` for the app.\n   */\n  componentPath: string;\n  /** Whether it's a query, mutation, or action. */\n  type: FunctionType;\n  /** Whether the function is public or internal. */\n  visibility: FunctionVisibility;\n};\n\n/**\n * Metadata about the deployment this function is running on.\n *\n * @public\n */\nexport type DeploymentMetadata = {\n  /**\n   * The deployment name, e.g. `\"tall-tiger-123\"` for cloud deployments,\n   * `\"local-my_team-my_project\"` for local deployments, or\n   * `\"anonymous-*\"` for anonymous deployments.\n   */\n  name: string;\n  /**\n   * The deployment region, e.g. `\"aws-us-east-1\"`.\n   * `null` for local and self-hosted deployments.\n   */\n  region: string | null;\n  /**\n   * The deployment class, e.g. `\"s16\"`, `\"s256\"`, `\"d1024\"`, or `\"d2048\"`.\n   */\n  class: \"s16\" | \"s256\" | \"d1024\" | \"d2048\";\n};\n\n/**\n * Metadata about the HTTP request that triggered the current function execution.\n *\n * `ip` and `userAgent` are `null` when the function was not triggered by an\n * HTTP request (e.g. scheduled jobs or cron jobs).\n *\n * Functions called from within a function (i.e. using `runMutation` or\n * `runAction`) will have the same request metadata as the parent function.\n *\n * @public\n */\nexport type RequestMetadata = {\n  ip: string | null;\n  userAgent: string | null;\n  requestId: string;\n  /**\n   * The ID of the scheduled function document (in `_scheduled_functions`) that\n   * this execution belongs to, or `null` otherwise.\n   *\n   * This is set for the scheduled function itself and for any functions it\n   * calls (e.g. a mutation invoked via `runMutation` by a scheduled action),\n   * propagating the top-level scheduled function's ID down the call tree. It is\n   * `null` when the function was not scheduled.\n   */\n  scheduledFunctionId: string | null;\n  /**\n   * The raw auth token (a JWT) the request was authenticated with, or `null`\n   * when the request was unauthenticated or authenticated with an admin key.\n   *\n   * This is the same token that `ctx.auth.getUserIdentity()` derives its\n   * attributes from.\n   */\n  authToken: string | null;\n};\n\n/**\n * Extra context available in Convex query functions.\n *\n * @public\n */\nexport interface QueryMeta {\n  /**\n   * Metadata about the currently executing Convex function.\n   */\n  getFunctionMetadata(): Promise<FunctionMetadata>;\n  /**\n   * The remaining headroom for a transaction before hitting limits.\n   *\n   * See https://docs.convex.dev/production/state/limits\n   */\n  getTransactionMetrics(): Promise<TransactionMetrics>;\n  /**\n   * Metadata about the deployment this function is running on.\n   */\n  getDeploymentMetadata(): Promise<DeploymentMetadata>;\n  /**\n   * Returns the timestamp of the database snapshot this transaction reads\n   * from, in nanoseconds.\n   *\n   * All commits at or before this timestamp are observable within the\n   * transaction, and no later commits are. The value is fixed for the\n   * lifetime of the transaction and shared with all nested `runMutation` and\n   * non-stale `runQuery` calls. If a nested query is called with\n   * `useStaleSnapshot: true`, then the nested query may in a future backend\n   * version choose an older snapshotTs.\n   *\n   * It is on the same clock as `db.vars.commitTs`: documents observable in\n   * this transaction have `commitTs` values at or before this timestamp, and\n   * no new documents will be written with a `commitTs` at or below this,\n   * including from the current transaction. When reading documents with an\n   * index in commitTs order, you can use this as an upper bound to prevent\n   * conflicting with racing inserts.\n   *\n   * Since the timestamp differs on every execution, calling this in a query\n   * limits caching of the query's result the same way `Date.now()` does.\n   *\n   * Note: this should not be compared to `_creationTime` or `Date.now()`, as\n   * those are based on wall-clock time rather than the database clock, and\n   * aren't guaranteed to follow commit order.\n   *\n   * Docs: https://docs.convex.dev/database/advanced/commit-timestamp\n   */\n  getSnapshotTs(): bigint;\n}\n\n/**\n * Extra context available in Convex mutation functions.\n *\n * @public\n */\nexport interface MutationMeta extends QueryMeta {\n  /**\n   * Metadata about the HTTP request that triggered the current function execution.\n   *\n   * `ip` and `userAgent` are `null` when the function was not triggered by an\n   * HTTP request (e.g. scheduled jobs or cron jobs).\n   *\n   * Functions called from within a function (i.e. using `runMutation`) will have\n   * the same request metadata as the parent function.\n   */\n  getRequestMetadata(): Promise<RequestMetadata>;\n}\n\n/**\n * Extra context available in Convex action functions.\n *\n * @public\n */\nexport interface ActionMeta {\n  /**\n   * Metadata about the currently executing Convex function.\n   */\n  getFunctionMetadata(): Promise<FunctionMetadata>;\n  /**\n   * Metadata about the deployment this function is running on.\n   */\n  getDeploymentMetadata(): Promise<DeploymentMetadata>;\n  /**\n   * Metadata about the HTTP request that triggered the current function execution.\n   *\n   * `ip` and `userAgent` are `null` when the function was not triggered by an\n   * HTTP request (e.g. scheduled jobs or cron jobs).\n   *\n   * Functions called from within a function (i.e. using `runMutation` or\n   * `runAction`) will have the same request metadata as the parent function.\n   */\n  getRequestMetadata(): Promise<RequestMetadata>;\n}\n"],
   "mappings": ";;;;;;;;;;;;;;AAAA;AAAA;",
   "names": []
 }

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/server/registration.ts"],
-  "sourcesContent": ["import {\n  Auth,\n  GenericDatabaseReader,\n  GenericDatabaseReaderWithTable,\n  GenericDatabaseWriter,\n  GenericDatabaseWriterWithTable,\n  StorageActionWriter,\n  StorageReader,\n  StorageWriter,\n} from \"./index.js\";\nimport {\n  ActionMeta,\n  MutationMeta,\n  QueryMeta,\n  TransactionLimits,\n} from \"./meta.js\";\nimport {\n  ArgsAndOptions,\n  FunctionReturnType,\n  OptionalRestArgs,\n  ValidatorTypeToReturnType,\n  FunctionReference,\n  FunctionReference_future,\n} from \"../server/api.js\";\nimport {\n  GenericValidator,\n  Infer,\n  ObjectType,\n  PropertyValidators,\n} from \"../values/validator.js\";\nimport { Id } from \"../values/value.js\";\nimport {\n  GenericDataModel,\n  NamedTableInfo,\n  TableNamesInDataModel,\n  VectorIndexNames,\n} from \"./data_model.js\";\nimport { Scheduler } from \"./scheduler.js\";\nimport { VectorSearchQuery } from \"./vector_search.js\";\nimport { Expand } from \"../type_utils.js\";\nimport { Validator } from \"../values/validators.js\";\n\n/**\n * A set of services for use within Convex mutation functions.\n *\n * The mutation context is passed as the first argument to any Convex mutation\n * function run on the server. Mutations run **transactionally**, all reads\n * and writes within a single mutation are atomic and isolated.\n *\n * You should generally use the `MutationCtx` type from\n * `\"./_generated/server\"`.\n *\n * @example\n * ```typescript\n * import { mutation } from \"./_generated/server\";\n * import { internal } from \"./_generated/api\";\n * import { v } from \"convex/values\";\n *\n * export const createTask = mutation({\n *   args: { text: v.string() },\n *   returns: v.id(\"tasks\"),\n *   handler: async (ctx, args) => {\n *     // ctx.db: read and write documents\n *     const taskId = await ctx.db.insert(\"tasks\", { text: args.text, completed: false });\n *\n *     // ctx.auth: check the authenticated user\n *     const identity = await ctx.auth.getUserIdentity();\n *\n *     // ctx.scheduler: schedule functions for later\n *     await ctx.scheduler.runAfter(0, internal.notifications.send, { taskId });\n *\n *     return taskId;\n *   },\n * });\n * ```\n *\n * @public\n */\nexport interface GenericMutationCtx<DataModel extends GenericDataModel> {\n  /**\n   * A utility for reading and writing data in the database.\n   *\n   * Use `ctx.db.insert()`, `ctx.db.patch()`, `ctx.db.replace()`, and\n   * `ctx.db.delete()` to write data. Use `ctx.db.get()` and `ctx.db.query()`\n   * to read data. All operations within a mutation are atomic.\n   */\n  db: GenericDatabaseWriter<DataModel>;\n\n  /**\n   * Information about the currently authenticated user.\n   *\n   * Call `await ctx.auth.getUserIdentity()` to get the current user's identity,\n   * or `null` if the user is not authenticated.\n   */\n  auth: Auth;\n\n  /**\n   * A utility for reading and writing files in storage.\n   *\n   * Use `ctx.storage.generateUploadUrl()` to create an upload URL for clients,\n   * `ctx.storage.getUrl(storageId)` to get a URL for a stored file,\n   * or `ctx.storage.delete(storageId)` to remove one.\n   */\n  storage: StorageWriter;\n\n  /**\n   * A utility for scheduling Convex functions to run in the future.\n   *\n   * @example\n   * ```typescript\n   * // Schedule an action to run immediately after this mutation commits:\n   * await ctx.scheduler.runAfter(0, internal.emails.sendWelcome, { userId });\n   *\n   * // Schedule a cleanup to run in 24 hours:\n   * await ctx.scheduler.runAfter(24 * 60 * 60 * 1000, internal.tasks.cleanup, {});\n   * ```\n   */\n  scheduler: Scheduler;\n\n  /**\n   * Call a query function within the same transaction.\n   *\n   * The query runs within the same transaction as the calling mutation,\n   * seeing a consistent snapshot of the database. Requires a\n   * {@link FunctionReference} (e.g., `api.myModule.myQuery` or\n   * `internal.myModule.myQuery`).\n   *\n   * NOTE: Often you can extract shared logic into a helper function instead.\n   * `runQuery` incurs overhead of running argument and return value validation,\n   * and creating a new isolated JS context.\n   *\n   * @example\n   * ```typescript\n   * const user = await ctx.runQuery(internal.users.getUser, { userId });\n   * ```\n   */\n  runQuery: <\n    Query extends\n      | FunctionReference<\"query\", \"public\" | \"internal\">\n      | FunctionReference_future<\"query\", \"public\" | \"internal\">,\n  >(\n    query: Query,\n    ...args: ArgsAndOptions<Query, AdvancedRunQueryOptions>\n  ) => Promise<FunctionReturnType<Query>>;\n\n  /**\n   * Call a mutation function within the same transaction.\n   *\n   * The mutation runs in a sub-transaction, so if it throws an error, all of\n   * its writes will be rolled back. Requires a {@link FunctionReference}.\n   *\n   * NOTE: Often you can extract shared logic into a helper function instead.\n   * `runMutation` incurs overhead of running argument and return value\n   * validation, and creating a new isolated JS context.\n   */\n  runMutation: <\n    Mutation extends\n      | FunctionReference<\"mutation\", \"public\" | \"internal\">\n      | FunctionReference_future<\"mutation\", \"public\" | \"internal\">,\n  >(\n    mutation: Mutation,\n    ...args: ArgsAndOptions<Mutation, { transactionLimits?: TransactionLimits }>\n  ) => Promise<FunctionReturnType<Mutation>>;\n\n  meta: MutationMeta;\n}\n\n/**\n * A set of services for use within Convex mutation functions.\n *\n * The mutation context is passed as the first argument to any Convex mutation\n * function run on the server.\n *\n * You should generally use the `MutationCtx` type from\n * `\"./_generated/server\"`.\n *\n * @public\n */\nexport type GenericMutationCtxWithTable<DataModel extends GenericDataModel> =\n  Omit<GenericMutationCtx<DataModel>, \"db\"> & {\n    db: GenericDatabaseWriterWithTable<DataModel>;\n  };\n\n/**\n * A set of services for use within Convex query functions.\n *\n * The query context is passed as the first argument to any Convex query\n * function run on the server. Queries are **read-only**, they can read from\n * the database but cannot write. They are also **reactive**, when used with\n * `useQuery` on the client, the result automatically updates when data changes.\n *\n * You should generally use the `QueryCtx` type from\n * `\"./_generated/server\"`.\n *\n * @example\n * ```typescript\n * import { query } from \"./_generated/server\";\n * import { v } from \"convex/values\";\n *\n * export const listTasks = query({\n *   args: {},\n *   returns: v.array(v.object({\n *     _id: v.id(\"tasks\"),\n *     _creationTime: v.number(),\n *     text: v.string(),\n *     completed: v.boolean(),\n *   })),\n *   handler: async (ctx, args) => {\n *     // ctx.db: read-only database access\n *     return await ctx.db.query(\"tasks\").order(\"desc\").take(100);\n *   },\n * });\n * ```\n *\n * @public\n */\nexport interface GenericQueryCtx<DataModel extends GenericDataModel> {\n  /**\n   * A utility for reading data in the database.\n   *\n   * Use `ctx.db.get(table, id)` to fetch a single document by ID, or\n   * `ctx.db.query(\"tableName\")` to query multiple documents with filtering\n   * and ordering. Queries are read-only, no write methods are available.\n   */\n  db: GenericDatabaseReader<DataModel>;\n\n  /**\n   * Information about the currently authenticated user.\n   *\n   * Call `await ctx.auth.getUserIdentity()` to get the current user's identity,\n   * or `null` if the user is not authenticated.\n   */\n  auth: Auth;\n\n  /**\n   * A utility for reading files in storage.\n   *\n   * Use `ctx.storage.getUrl(storageId)` to get a URL for a stored file.\n   */\n  storage: StorageReader;\n\n  /**\n   * Call a query function within the same transaction.\n   *\n   * The query runs within the same read snapshot. Requires a\n   * {@link FunctionReference} (e.g., `api.myModule.myQuery` or\n   * `internal.myModule.myQuery`).\n   *\n   * NOTE: Often you can extract shared logic into a helper function instead.\n   * `runQuery` incurs overhead of running argument and return value validation,\n   * and creating a new isolated JS context.\n   */\n  runQuery: <\n    Query extends\n      | FunctionReference<\"query\", \"public\" | \"internal\">\n      | FunctionReference_future<\"query\", \"public\" | \"internal\">,\n  >(\n    query: Query,\n    ...args: ArgsAndOptions<Query, { transactionLimits?: TransactionLimits }>\n  ) => Promise<FunctionReturnType<Query>>;\n\n  meta: QueryMeta;\n}\n\n/**\n * A set of services for use within Convex query functions.\n *\n * The query context is passed as the first argument to any Convex query\n * function run on the server.\n *\n * This differs from the {@link MutationCtx} because all of the services are\n * read-only.\n *\n *\n * @public\n */\nexport type GenericQueryCtxWithTable<DataModel extends GenericDataModel> = Omit<\n  GenericQueryCtx<DataModel>,\n  \"db\"\n> & {\n  db: GenericDatabaseReaderWithTable<DataModel>;\n};\n\n/**\n * A set of services for use within Convex action functions.\n *\n * The action context is passed as the first argument to any Convex action\n * run on the server. Actions can call external APIs and use Node.js libraries,\n * but do **not** have direct database access (`ctx.db` is not available).\n * Use `ctx.runQuery` and `ctx.runMutation` to interact with the database.\n *\n * You should generally use the `ActionCtx` type from\n * `\"./_generated/server\"`.\n *\n * @example\n * ```typescript\n * import { action } from \"./_generated/server\";\n * import { internal } from \"./_generated/api\";\n * import { v } from \"convex/values\";\n *\n * export const processPayment = action({\n *   args: { orderId: v.id(\"orders\"), amount: v.number() },\n *   returns: v.null(),\n *   handler: async (ctx, args) => {\n *     // Read data via ctx.runQuery:\n *     const order = await ctx.runQuery(internal.orders.get, { id: args.orderId });\n *\n *     // Call external API:\n *     const result = await fetch(\"https://api.stripe.com/v1/charges\", { ... });\n *\n *     // Write results back via ctx.runMutation:\n *     await ctx.runMutation(internal.orders.markPaid, { id: args.orderId });\n *\n *     return null;\n *   },\n * });\n * ```\n *\n * **Common mistake:** `ctx.db` is not available in actions. Do not try to\n * access it, use `ctx.runQuery` and `ctx.runMutation` instead.\n *\n * @public\n */\nexport interface GenericActionCtx<DataModel extends GenericDataModel> {\n  /**\n   * Run the Convex query with the given name and arguments.\n   *\n   * Each `runQuery` call is a separate read transaction. Consider using an\n   * {@link internalQuery} to prevent users from calling the query directly.\n   *\n   * @example\n   * ```typescript\n   * const user = await ctx.runQuery(internal.users.get, { userId });\n   * ```\n   *\n   * @param query - A {@link FunctionReference} for the query to run.\n   * @param args - The arguments to the query function.\n   * @returns A promise of the query's result.\n   */\n  runQuery<\n    Query extends\n      | FunctionReference<\"query\", \"public\" | \"internal\">\n      | FunctionReference_future<\"query\", \"public\" | \"internal\">,\n  >(\n    query: Query,\n    ...args: OptionalRestArgs<Query>\n  ): Promise<FunctionReturnType<Query>>;\n\n  /**\n   * Run the Convex mutation with the given name and arguments.\n   *\n   * Each `runMutation` call is a separate write transaction. Consider using\n   * an {@link internalMutation} to prevent users from calling it directly.\n   *\n   * @example\n   * ```typescript\n   * await ctx.runMutation(internal.orders.markPaid, { id: orderId });\n   * ```\n   *\n   * @param mutation - A {@link FunctionReference} for the mutation to run.\n   * @param args - The arguments to the mutation function.\n   * @returns A promise of the mutation's result.\n   */\n  runMutation<\n    Mutation extends\n      | FunctionReference<\"mutation\", \"public\" | \"internal\">\n      | FunctionReference_future<\"mutation\", \"public\" | \"internal\">,\n  >(\n    mutation: Mutation,\n    ...args: OptionalRestArgs<Mutation>\n  ): Promise<FunctionReturnType<Mutation>>;\n\n  /**\n   * Run the Convex action with the given name and arguments.\n   *\n   * **Important:** Only use `runAction` when you need to cross runtimes\n   * (e.g., calling a `\"use node\"` action from the default Convex runtime).\n   * For code in the same runtime, extract shared logic into a plain\n   * TypeScript helper function instead, `runAction` has significant\n   * overhead (separate function call, separate resource allocation).\n   *\n   * Consider using an {@link internalAction} to prevent users from calling the\n   * action directly.\n   *\n   * @param action - A {@link FunctionReference} for the action to run.\n   * @param args - The arguments to the action function.\n   * @returns A promise of the action's result.\n   */\n  runAction<\n    Action extends\n      | FunctionReference<\"action\", \"public\" | \"internal\">\n      | FunctionReference_future<\"action\", \"public\" | \"internal\">,\n  >(\n    action: Action,\n    ...args: OptionalRestArgs<Action>\n  ): Promise<FunctionReturnType<Action>>;\n\n  /**\n   * A utility for scheduling Convex functions to run in the future.\n   */\n  scheduler: Scheduler;\n\n  /**\n   * Information about the currently authenticated user.\n   */\n  auth: Auth;\n\n  /**\n   * A utility for reading and writing files in storage.\n   */\n  storage: StorageActionWriter;\n\n  /**\n   * Run a vector search on the given table and index.\n   *\n   * @param tableName - The name of the table to query.\n   * @param indexName - The name of the vector index on the table to query.\n   * @param query - A {@link VectorSearchQuery} containing the vector to query,\n   * the number of results to return, and any filters.\n   * @returns A promise of IDs and scores for the documents with the nearest\n   * vectors\n   */\n  vectorSearch<\n    TableName extends TableNamesInDataModel<DataModel>,\n    IndexName extends VectorIndexNames<NamedTableInfo<DataModel, TableName>>,\n  >(\n    tableName: TableName,\n    indexName: IndexName,\n    query: Expand<\n      VectorSearchQuery<NamedTableInfo<DataModel, TableName>, IndexName>\n    >,\n  ): Promise<Array<{ _id: Id<TableName>; _score: number }>>;\n\n  meta: ActionMeta;\n}\n\n/**\n * The default arguments type for a Convex query, mutation, or action function.\n *\n * Convex functions always take an arguments object that maps the argument\n * names to their values.\n *\n * @public\n */\nexport type DefaultFunctionArgs = Record<string, unknown>;\n\n/**\n * The arguments array for a function that takes arguments.\n *\n * This is an array of a single {@link DefaultFunctionArgs} element.\n */\ntype OneArgArray<ArgsObject extends DefaultFunctionArgs = DefaultFunctionArgs> =\n  [ArgsObject];\n\n/**\n * The arguments to a function that takes no arguments (just an empty array).\n */\ntype NoArgsArray = [];\n\n/**\n * An array of arguments to a Convex function.\n *\n * Convex functions can take either a single {@link DefaultFunctionArgs} object or no\n * args at all.\n *\n * @public\n */\nexport type ArgsArray = OneArgArray | NoArgsArray;\n\n/**\n * A type for the empty object `{}`.\n *\n * Note that we don't use `type EmptyObject = {}` because that matches every object.\n */\nexport type EmptyObject = Record<string, never>;\n\n/**\n * Convert an {@link ArgsArray} into a single object type.\n *\n * Empty arguments arrays are converted to {@link EmptyObject}.\n * @public\n */\nexport type ArgsArrayToObject<Args extends ArgsArray> =\n  Args extends OneArgArray<infer ArgsObject> ? ArgsObject : EmptyObject;\n\n/**\n * A type representing the visibility of a Convex function.\n *\n * @public\n */\nexport type FunctionVisibility = \"public\" | \"internal\";\n\n/**\n * Given a {@link FunctionVisibility}, should this function have `isPublic: true`\n * or `isInternal: true`?\n */\ntype VisibilityProperties<Visiblity extends FunctionVisibility> = {\n  /** Phantom type marker; not present at runtime. */\n  _visibility: Visiblity;\n} & (Visiblity extends \"public\"\n  ? {\n      isPublic: true;\n    }\n  : {\n      isInternal: true;\n    });\n\n/**\n * A mutation function that is part of this app.\n *\n * You can create a mutation by wrapping your function in\n * {@link mutationGeneric} or {@link internalMutationGeneric} and exporting it.\n *\n * @public\n */\nexport type RegisteredMutation<\n  Visibility extends FunctionVisibility,\n  Args extends DefaultFunctionArgs,\n  Returns,\n> = {\n  isConvexFunction: true;\n  isMutation: true;\n\n  /** @internal */\n  invokeMutation(argsStr: string): Promise<string>;\n\n  /** @internal */\n  exportArgs(): string;\n\n  /** @internal */\n  exportReturns(): string;\n\n  /** @internal */\n  _handler: (ctx: GenericMutationCtx<any>, args: Args) => Returns;\n} & VisibilityProperties<Visibility>;\n\n/**\n * A query function that is part of this app.\n *\n * You can create a query by wrapping your function in\n * {@link queryGeneric} or {@link internalQueryGeneric} and exporting it.\n *\n * @public\n */\nexport type RegisteredQuery<\n  Visibility extends FunctionVisibility,\n  Args extends DefaultFunctionArgs,\n  Returns,\n> = {\n  isConvexFunction: true;\n  isQuery: true;\n\n  /** @internal */\n  invokeQuery(argsStr: string): Promise<string>;\n\n  /** @internal */\n  exportArgs(): string;\n\n  /** @internal */\n  exportReturns(): string;\n\n  /** @internal */\n  _handler: (ctx: GenericQueryCtx<any>, args: Args) => Returns;\n} & VisibilityProperties<Visibility>;\n\n/**\n * An action that is part of this app.\n *\n * You can create an action by wrapping your function in\n * {@link actionGeneric} or {@link internalActionGeneric} and exporting it.\n *\n * @public\n */\nexport type RegisteredAction<\n  Visibility extends FunctionVisibility,\n  Args extends DefaultFunctionArgs,\n  Returns,\n> = {\n  isConvexFunction: true;\n  isAction: true;\n\n  /** @internal */\n  invokeAction(requestId: string, argsStr: string): Promise<string>;\n\n  /** @internal */\n  exportArgs(): string;\n\n  /** @internal */\n  exportReturns(): string;\n\n  /** @internal */\n  _handler: (ctx: GenericActionCtx<any>, args: Args) => Returns;\n} & VisibilityProperties<Visibility>;\n\n/**\n * An HTTP action that is part of this app's public API.\n *\n * You can create public HTTP actions by wrapping your function in\n * {@link httpActionGeneric} and exporting it.\n *\n * @public\n */\nexport type PublicHttpAction = {\n  isHttp: true;\n\n  /** @internal */\n  invokeHttpAction(request: Request): Promise<Response>;\n  /** @internal */\n  _handler: (ctx: GenericActionCtx<any>, request: Request) => Promise<Response>;\n};\n\n/**\n * @deprecated -- See the type definition for `MutationBuilder` or similar for\n * the types used for defining Convex functions.\n *\n * The definition of a Convex query, mutation, or action function without\n * argument validation.\n *\n * Convex functions always take a context object as their first argument\n * and an (optional) args object as their second argument.\n *\n * This can be written as a function like:\n * ```js\n * import { query } from \"./_generated/server\";\n *\n * export const func = query(({ db }, { arg }) => {...});\n * ```\n * or as an object like:\n *\n * ```js\n * import { query } from \"./_generated/server\";\n *\n * export const func = query({\n *   handler: ({ db }, { arg }) => {...},\n * });\n * ```\n * See {@link ValidatedFunction} to add argument validation.\n *\n * @public\n */\nexport type UnvalidatedFunction<Ctx, Args extends ArgsArray, Returns> =\n  | ((ctx: Ctx, ...args: Args) => Returns)\n  | {\n      handler: (ctx: Ctx, ...args: Args) => Returns;\n    };\n\n/**\n * @deprecated -- See the type definition for `MutationBuilder` or similar for\n * the types used for defining Convex functions.\n *\n * The definition of a Convex query, mutation, or action function with argument\n * validation.\n *\n * Argument validation allows you to assert that the arguments to this function\n * are the expected type.\n *\n * Example:\n *\n * ```js\n * import { query } from \"./_generated/server\";\n * import { v } from \"convex/values\";\n *\n * export const func = query({\n *   args: {\n *     arg: v.string()\n *   },\n *   handler: ({ db }, { arg }) => {...},\n * });\n * ```\n *\n * **For security, argument validation should be added to all public functions in\n * production apps.**\n *\n * See {@link UnvalidatedFunction} for functions without argument validation.\n * @public\n */\nexport interface ValidatedFunction<\n  Ctx,\n  ArgsValidator extends PropertyValidators,\n  Returns,\n> {\n  /**\n   * A validator for the arguments of this function.\n   *\n   * This is an object mapping argument names to validators constructed with\n   * {@link values.v}.\n   *\n   * ```js\n   * import { v } from \"convex/values\";\n   *\n   * const args = {\n   *   stringArg: v.string(),\n   *   optionalNumberArg: v.optional(v.number()),\n   * }\n   * ```\n   */\n  args: ArgsValidator;\n\n  /**\n   * The implementation of this function.\n   *\n   * This is a function that takes in the appropriate context and arguments\n   * and produces some result.\n   *\n   * @param ctx - The context object. This is one of {@link QueryCtx},\n   * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n   * @param args - The arguments object for this function. This will match\n   * the type defined by the argument validator.\n   * @returns\n   */\n  handler: (ctx: Ctx, args: ObjectType<ArgsValidator>) => Returns;\n}\n\n/**\n * There are multiple syntaxes for defining a Convex function:\n * ```\n *  - query(async (ctx, args) => {...})\n *  - query({ handler: async (ctx, args) => {...} })\n *  - query({ args: { a: v.string }, handler: async (ctx, args) => {...} } })\n *  - query({ args: { a: v.string }, returns: v.string(), handler: async (ctx, args) => {...} } })\n *```\n *\n * In each of these, we want to correctly infer the type for the arguments and\n * return value, preferring the type derived from a validator if it's provided.\n *\n * To avoid having a separate overload for each, which would show up in error messages,\n * we use the type params -- ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs.\n *\n * The type for ReturnValue and OneOrZeroArgs are constrained by the type or ArgsValidator and\n * ReturnsValidator if they're present, and inferred from any explicit type annotations to the\n * arguments or return value of the function.\n *\n * Below are a few utility types to get the appropriate type constraints based on\n * an optional validator.\n *\n * Additional tricks:\n * - We use Validator | void instead of Validator | undefined because the latter does\n * not work with `strictNullChecks` since it's equivalent to just `Validator`.\n * - We use a tuple type of length 1 to avoid distribution over the union\n *  https://github.com/microsoft/TypeScript/issues/29368#issuecomment-453529532\n */\n\nexport type ReturnValueForOptionalValidator<\n  ReturnsValidator extends Validator<any, any, any> | PropertyValidators | void,\n> = [ReturnsValidator] extends [Validator<any, any, any>]\n  ? ValidatorTypeToReturnType<Infer<ReturnsValidator>>\n  : [ReturnsValidator] extends [PropertyValidators]\n    ? ValidatorTypeToReturnType<ObjectType<ReturnsValidator>>\n    : any;\n\nexport type ArgsArrayForOptionalValidator<\n  ArgsValidator extends GenericValidator | PropertyValidators | void,\n> = [ArgsValidator] extends [Validator<any, any, any>]\n  ? OneArgArray<Infer<ArgsValidator>>\n  : [ArgsValidator] extends [PropertyValidators]\n    ? OneArgArray<ObjectType<ArgsValidator>>\n    : ArgsArray;\n\nexport type DefaultArgsForOptionalValidator<\n  ArgsValidator extends GenericValidator | PropertyValidators | void,\n> = [ArgsValidator] extends [Validator<any, any, any>]\n  ? [Infer<ArgsValidator>]\n  : [ArgsValidator] extends [PropertyValidators]\n    ? [ObjectType<ArgsValidator>]\n    : OneArgArray;\n\n/**\n * Internal type helper used by Convex code generation.\n *\n * Used to give {@link mutationGeneric} a type specific to your data model.\n * @public\n */\nexport type MutationBuilder<\n  DataModel extends GenericDataModel,\n  Visibility extends FunctionVisibility,\n> = {\n  <\n    ArgsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnValue extends ReturnValueForOptionalValidator<ReturnsValidator> = any,\n    OneOrZeroArgs extends ArgsArrayForOptionalValidator<ArgsValidator> =\n      DefaultArgsForOptionalValidator<ArgsValidator>,\n  >(\n    mutation:\n      | {\n          /**\n           * Argument validation.\n           *\n           * Examples:\n           *\n           * ```\n           * args: {}\n           * args: { input: v.optional(v.number()) }\n           * args: { message: v.string(), author: v.id(\"authors\") }\n           * args: { messages: v.array(v.string()) }\n           * ```\n           */\n          args?: ArgsValidator;\n          /**\n           * The return value validator.\n           *\n           * Examples:\n           *\n           * ```\n           * returns: v.null()\n           * returns: v.string()\n           * returns: { message: v.string(), author: v.id(\"authors\") }\n           * returns: v.array(v.string())\n           * ```\n           */\n          returns?: ReturnsValidator;\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          handler: (\n            ctx: GenericMutationCtx<DataModel>,\n            ...args: OneOrZeroArgs\n          ) => ReturnValue;\n        }\n      | {\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          (\n            ctx: GenericMutationCtx<DataModel>,\n            ...args: OneOrZeroArgs\n          ): ReturnValue;\n        },\n  ): RegisteredMutation<\n    Visibility,\n    ArgsArrayToObject<OneOrZeroArgs>,\n    ReturnValue\n  >;\n};\n\n/**\n * Internal type helper used by Convex code generation.\n *\n * Used to give {@link mutationGeneric} a type specific to your data model.\n * @public\n */\nexport type MutationBuilderWithTable<\n  DataModel extends GenericDataModel,\n  Visibility extends FunctionVisibility,\n> = {\n  <\n    ArgsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnValue extends ReturnValueForOptionalValidator<ReturnsValidator> = any,\n    OneOrZeroArgs extends ArgsArrayForOptionalValidator<ArgsValidator> =\n      DefaultArgsForOptionalValidator<ArgsValidator>,\n  >(\n    mutation:\n      | {\n          /**\n           * Argument validation.\n           *\n           * Examples:\n           *\n           * ```\n           * args: {}\n           * args: { input: v.optional(v.number()) }\n           * args: { message: v.string(), author: v.id(\"authors\") }\n           * args: { messages: v.array(v.string()) }\n           * ```\n           */\n          args?: ArgsValidator;\n          /**\n           * The return value validator.\n           *\n           * Examples:\n           *\n           * ```\n           * returns: v.null()\n           * returns: v.string()\n           * returns: { message: v.string(), author: v.id(\"authors\") }\n           * returns: v.array(v.string())\n           * ```\n           */\n          returns?: ReturnsValidator;\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          handler: (\n            ctx: GenericMutationCtxWithTable<DataModel>,\n            ...args: OneOrZeroArgs\n          ) => ReturnValue;\n        }\n      | {\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          (\n            ctx: GenericMutationCtxWithTable<DataModel>,\n            ...args: OneOrZeroArgs\n          ): ReturnValue;\n        },\n  ): RegisteredMutation<\n    Visibility,\n    ArgsArrayToObject<OneOrZeroArgs>,\n    ReturnValue\n  >;\n};\n\n/**\n * Internal type helper used by Convex code generation.\n *\n * Used to give {@link queryGeneric} a type specific to your data model.\n * @public\n */\nexport type QueryBuilder<\n  DataModel extends GenericDataModel,\n  Visibility extends FunctionVisibility,\n> = {\n  <\n    ArgsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnValue extends ReturnValueForOptionalValidator<ReturnsValidator> = any,\n    OneOrZeroArgs extends ArgsArrayForOptionalValidator<ArgsValidator> =\n      DefaultArgsForOptionalValidator<ArgsValidator>,\n  >(\n    query:\n      | {\n          /**\n           * Argument validation.\n           *\n           * Examples:\n           *\n           * ```\n           * args: {}\n           * args: { input: v.optional(v.number()) }\n           * args: { message: v.string(), author: v.id(\"authors\") }\n           * args: { messages: v.array(v.string()) }\n           * ```\n           */\n          args?: ArgsValidator;\n          /**\n           * The return value validator.\n           *\n           * Examples:\n           *\n           * ```\n           * returns: v.null()\n           * returns: v.string()\n           * returns: { message: v.string(), author: v.id(\"authors\") }\n           * returns: v.array(v.string())\n           * ```\n           */\n          returns?: ReturnsValidator;\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          handler: (\n            ctx: GenericQueryCtx<DataModel>,\n            ...args: OneOrZeroArgs\n          ) => ReturnValue;\n        }\n      | {\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          (\n            ctx: GenericQueryCtx<DataModel>,\n            ...args: OneOrZeroArgs\n          ): ReturnValue;\n        },\n  ): RegisteredQuery<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>;\n};\n\n/**\n * Internal type helper used by Convex code generation.\n *\n * Used to give {@link queryGeneric} a type specific to your data model.\n * @public\n */\nexport type QueryBuilderWithTable<\n  DataModel extends GenericDataModel,\n  Visibility extends FunctionVisibility,\n> = {\n  <\n    ArgsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnValue extends ReturnValueForOptionalValidator<ReturnsValidator> = any,\n    OneOrZeroArgs extends ArgsArrayForOptionalValidator<ArgsValidator> =\n      DefaultArgsForOptionalValidator<ArgsValidator>,\n  >(\n    query:\n      | {\n          /**\n           * Argument validation.\n           *\n           * Examples:\n           *\n           * ```\n           * args: {}\n           * args: { input: v.optional(v.number()) }\n           * args: { message: v.string(), author: v.id(\"authors\") }\n           * args: { messages: v.array(v.string()) }\n           * ```\n           */\n          args?: ArgsValidator;\n          /**\n           * The return value validator.\n           *\n           * Examples:\n           *\n           * ```\n           * returns: v.null()\n           * returns: v.string()\n           * returns: { message: v.string(), author: v.id(\"authors\") }\n           * returns: v.array(v.string())\n           * ```\n           */\n          returns?: ReturnsValidator;\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          handler: (\n            ctx: GenericQueryCtxWithTable<DataModel>,\n            ...args: OneOrZeroArgs\n          ) => ReturnValue;\n        }\n      | {\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          (\n            ctx: GenericQueryCtxWithTable<DataModel>,\n            ...args: OneOrZeroArgs\n          ): ReturnValue;\n        },\n  ): RegisteredQuery<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>;\n};\n\n/**\n * Internal type helper used by Convex code generation.\n *\n * Used to give {@link actionGeneric} a type specific to your data model.\n * @public\n */\nexport type ActionBuilder<\n  DataModel extends GenericDataModel,\n  Visibility extends FunctionVisibility,\n> = {\n  <\n    ArgsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnValue extends ReturnValueForOptionalValidator<ReturnsValidator> = any,\n    OneOrZeroArgs extends ArgsArrayForOptionalValidator<ArgsValidator> =\n      DefaultArgsForOptionalValidator<ArgsValidator>,\n  >(\n    func:\n      | {\n          /**\n           * Argument validation.\n           *\n           * Examples:\n           *\n           * ```\n           * args: {}\n           * args: { input: v.optional(v.number()) }\n           * args: { message: v.string(), author: v.id(\"authors\") }\n           * args: { messages: v.array(v.string()) }\n           * ```\n           *\n           */\n          args?: ArgsValidator;\n          /**\n           * The return value validator.\n           *\n           * Examples:\n           *\n           * ```\n           * returns: v.null()\n           * returns: v.string()\n           * returns: { message: v.string(), author: v.id(\"authors\") }\n           * returns: v.array(v.string())\n           * ```\n           */\n          returns?: ReturnsValidator;\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          handler: (\n            ctx: GenericActionCtx<DataModel>,\n            ...args: OneOrZeroArgs\n          ) => ReturnValue;\n        }\n      | {\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          (\n            ctx: GenericActionCtx<DataModel>,\n            ...args: OneOrZeroArgs\n          ): ReturnValue;\n        },\n  ): RegisteredAction<\n    Visibility,\n    ArgsArrayToObject<OneOrZeroArgs>,\n    ReturnValue\n  >;\n};\n\n/**\n * Internal type helper used by Convex code generation.\n *\n * Used to give {@link httpActionGeneric} a type specific to your data model\n * and functions.\n * @public\n */\nexport type HttpActionBuilder = (\n  func: (ctx: GenericActionCtx<any>, request: Request) => Promise<Response>,\n) => PublicHttpAction;\n\nexport interface AdvancedRunQueryOptions {\n  transactionLimits?: TransactionLimits;\n  /**\n   * Run a query on a recent snapshot of the database that is not guaranteed\n   * to be up-to-date when this transaction commits.\n   *\n   * This is an advanced feature which can introduce subtle race conditions,\n   * so its use is generally discouraged except for specific use-cases where\n   * database read conflicts are expected, e.g. reading from an append-only\n   * table with immutable records where the only read conflicts are from\n   * concurrent appends.\n   */\n  useStaleSnapshot?: boolean;\n}\n"],
+  "sourcesContent": ["import {\n  Auth,\n  GenericDatabaseReader,\n  GenericDatabaseReaderWithTable,\n  GenericDatabaseWriter,\n  GenericDatabaseWriterWithTable,\n  StorageActionWriter,\n  StorageReader,\n  StorageWriter,\n} from \"./index.js\";\nimport {\n  ActionMeta,\n  MutationMeta,\n  QueryMeta,\n  TransactionLimits,\n} from \"./meta.js\";\nimport {\n  ArgsAndOptions,\n  FunctionReturnType,\n  OptionalRestArgs,\n  ValidatorTypeToReturnType,\n  FunctionReference,\n  FunctionReference_future,\n} from \"../server/api.js\";\nimport {\n  GenericValidator,\n  Infer,\n  ObjectType,\n  PropertyValidators,\n} from \"../values/validator.js\";\nimport { Id } from \"../values/value.js\";\nimport {\n  GenericDataModel,\n  NamedTableInfo,\n  TableNamesInDataModel,\n  VectorIndexNames,\n} from \"./data_model.js\";\nimport { Scheduler } from \"./scheduler.js\";\nimport { VectorSearchQuery } from \"./vector_search.js\";\nimport { Expand } from \"../type_utils.js\";\nimport { Validator } from \"../values/validators.js\";\n\n/**\n * A set of services for use within Convex mutation functions.\n *\n * The mutation context is passed as the first argument to any Convex mutation\n * function run on the server. Mutations run **transactionally**, all reads\n * and writes within a single mutation are atomic and isolated.\n *\n * You should generally use the `MutationCtx` type from\n * `\"./_generated/server\"`.\n *\n * @example\n * ```typescript\n * import { mutation } from \"./_generated/server\";\n * import { internal } from \"./_generated/api\";\n * import { v } from \"convex/values\";\n *\n * export const createTask = mutation({\n *   args: { text: v.string() },\n *   returns: v.id(\"tasks\"),\n *   handler: async (ctx, args) => {\n *     // ctx.db: read and write documents\n *     const taskId = await ctx.db.insert(\"tasks\", { text: args.text, completed: false });\n *\n *     // ctx.auth: check the authenticated user\n *     const identity = await ctx.auth.getUserIdentity();\n *\n *     // ctx.scheduler: schedule functions for later\n *     await ctx.scheduler.runAfter(0, internal.notifications.send, { taskId });\n *\n *     return taskId;\n *   },\n * });\n * ```\n *\n * @public\n */\nexport interface GenericMutationCtx<DataModel extends GenericDataModel> {\n  /**\n   * A utility for reading and writing data in the database.\n   *\n   * Use `ctx.db.insert()`, `ctx.db.patch()`, `ctx.db.replace()`, and\n   * `ctx.db.delete()` to write data. Use `ctx.db.get()` and `ctx.db.query()`\n   * to read data. All operations within a mutation are atomic.\n   */\n  db: GenericDatabaseWriter<DataModel>;\n\n  /**\n   * Information about the currently authenticated user.\n   *\n   * Call `await ctx.auth.getUserIdentity()` to get the current user's identity,\n   * or `null` if the user is not authenticated.\n   */\n  auth: Auth;\n\n  /**\n   * A utility for reading and writing files in storage.\n   *\n   * Use `ctx.storage.generateUploadUrl()` to create an upload URL for clients,\n   * `ctx.storage.getUrl(storageId)` to get a URL for a stored file,\n   * or `ctx.storage.delete(storageId)` to remove one.\n   */\n  storage: StorageWriter;\n\n  /**\n   * A utility for scheduling Convex functions to run in the future.\n   *\n   * @example\n   * ```typescript\n   * // Schedule an action to run immediately after this mutation commits:\n   * await ctx.scheduler.runAfter(0, internal.emails.sendWelcome, { userId });\n   *\n   * // Schedule a cleanup to run in 24 hours:\n   * await ctx.scheduler.runAfter(24 * 60 * 60 * 1000, internal.tasks.cleanup, {});\n   * ```\n   */\n  scheduler: Scheduler;\n\n  /**\n   * Call a query function within the same transaction.\n   *\n   * The query runs within the same transaction as the calling mutation,\n   * seeing a consistent snapshot of the database. Requires a\n   * {@link FunctionReference} (e.g., `api.myModule.myQuery` or\n   * `internal.myModule.myQuery`).\n   *\n   * NOTE: Often you can extract shared logic into a helper function instead.\n   * `runQuery` incurs overhead of running argument and return value validation,\n   * and creating a new isolated JS context.\n   *\n   * @example\n   * ```typescript\n   * const user = await ctx.runQuery(internal.users.getUser, { userId });\n   * ```\n   */\n  runQuery: <\n    Query extends\n      | FunctionReference<\"query\", \"public\" | \"internal\">\n      | FunctionReference_future<\"query\", \"public\" | \"internal\">,\n  >(\n    query: Query,\n    ...args: ArgsAndOptions<Query, AdvancedRunQueryOptions>\n  ) => Promise<FunctionReturnType<Query>>;\n\n  /**\n   * Call a mutation function within the same transaction.\n   *\n   * The mutation runs in a sub-transaction, so if it throws an error, all of\n   * its writes will be rolled back. Requires a {@link FunctionReference}.\n   *\n   * NOTE: Often you can extract shared logic into a helper function instead.\n   * `runMutation` incurs overhead of running argument and return value\n   * validation, and creating a new isolated JS context.\n   */\n  runMutation: <\n    Mutation extends\n      | FunctionReference<\"mutation\", \"public\" | \"internal\">\n      | FunctionReference_future<\"mutation\", \"public\" | \"internal\">,\n  >(\n    mutation: Mutation,\n    ...args: ArgsAndOptions<Mutation, { transactionLimits?: TransactionLimits }>\n  ) => Promise<FunctionReturnType<Mutation>>;\n\n  meta: MutationMeta;\n}\n\n/**\n * A set of services for use within Convex mutation functions.\n *\n * The mutation context is passed as the first argument to any Convex mutation\n * function run on the server.\n *\n * You should generally use the `MutationCtx` type from\n * `\"./_generated/server\"`.\n *\n * @public\n */\nexport type GenericMutationCtxWithTable<DataModel extends GenericDataModel> =\n  Omit<GenericMutationCtx<DataModel>, \"db\"> & {\n    db: GenericDatabaseWriterWithTable<DataModel>;\n  };\n\n/**\n * A set of services for use within Convex query functions.\n *\n * The query context is passed as the first argument to any Convex query\n * function run on the server. Queries are **read-only**, they can read from\n * the database but cannot write. They are also **reactive**, when used with\n * `useQuery` on the client, the result automatically updates when data changes.\n *\n * You should generally use the `QueryCtx` type from\n * `\"./_generated/server\"`.\n *\n * @example\n * ```typescript\n * import { query } from \"./_generated/server\";\n * import { v } from \"convex/values\";\n *\n * export const listTasks = query({\n *   args: {},\n *   returns: v.array(v.object({\n *     _id: v.id(\"tasks\"),\n *     _creationTime: v.number(),\n *     text: v.string(),\n *     completed: v.boolean(),\n *   })),\n *   handler: async (ctx, args) => {\n *     // ctx.db: read-only database access\n *     return await ctx.db.query(\"tasks\").order(\"desc\").take(100);\n *   },\n * });\n * ```\n *\n * @public\n */\nexport interface GenericQueryCtx<DataModel extends GenericDataModel> {\n  /**\n   * A utility for reading data in the database.\n   *\n   * Use `ctx.db.get(table, id)` to fetch a single document by ID, or\n   * `ctx.db.query(\"tableName\")` to query multiple documents with filtering\n   * and ordering. Queries are read-only, no write methods are available.\n   */\n  db: GenericDatabaseReader<DataModel>;\n\n  /**\n   * Information about the currently authenticated user.\n   *\n   * Call `await ctx.auth.getUserIdentity()` to get the current user's identity,\n   * or `null` if the user is not authenticated.\n   */\n  auth: Auth;\n\n  /**\n   * A utility for reading files in storage.\n   *\n   * Use `ctx.storage.getUrl(storageId)` to get a URL for a stored file.\n   */\n  storage: StorageReader;\n\n  /**\n   * Call a query function within the same transaction.\n   *\n   * The query runs within the same read snapshot. Requires a\n   * {@link FunctionReference} (e.g., `api.myModule.myQuery` or\n   * `internal.myModule.myQuery`).\n   *\n   * NOTE: Often you can extract shared logic into a helper function instead.\n   * `runQuery` incurs overhead of running argument and return value validation,\n   * and creating a new isolated JS context.\n   */\n  runQuery: <\n    Query extends\n      | FunctionReference<\"query\", \"public\" | \"internal\">\n      | FunctionReference_future<\"query\", \"public\" | \"internal\">,\n  >(\n    query: Query,\n    ...args: ArgsAndOptions<Query, { transactionLimits?: TransactionLimits }>\n  ) => Promise<FunctionReturnType<Query>>;\n\n  meta: QueryMeta;\n}\n\n/**\n * A set of services for use within Convex query functions.\n *\n * The query context is passed as the first argument to any Convex query\n * function run on the server.\n *\n * This differs from the {@link MutationCtx} because all of the services are\n * read-only.\n *\n *\n * @public\n */\nexport type GenericQueryCtxWithTable<DataModel extends GenericDataModel> = Omit<\n  GenericQueryCtx<DataModel>,\n  \"db\"\n> & {\n  db: GenericDatabaseReaderWithTable<DataModel>;\n};\n\n/**\n * A set of services for use within Convex action functions.\n *\n * The action context is passed as the first argument to any Convex action\n * run on the server. Actions can call external APIs and use Node.js libraries,\n * but do **not** have direct database access (`ctx.db` is not available).\n * Use `ctx.runQuery` and `ctx.runMutation` to interact with the database.\n *\n * You should generally use the `ActionCtx` type from\n * `\"./_generated/server\"`.\n *\n * @example\n * ```typescript\n * import { action } from \"./_generated/server\";\n * import { internal } from \"./_generated/api\";\n * import { v } from \"convex/values\";\n *\n * export const processPayment = action({\n *   args: { orderId: v.id(\"orders\"), amount: v.number() },\n *   returns: v.null(),\n *   handler: async (ctx, args) => {\n *     // Read data via ctx.runQuery:\n *     const order = await ctx.runQuery(internal.orders.get, { id: args.orderId });\n *\n *     // Call external API:\n *     const result = await fetch(\"https://api.stripe.com/v1/charges\", { ... });\n *\n *     // Write results back via ctx.runMutation:\n *     await ctx.runMutation(internal.orders.markPaid, { id: args.orderId });\n *\n *     return null;\n *   },\n * });\n * ```\n *\n * **Common mistake:** `ctx.db` is not available in actions. Do not try to\n * access it, use `ctx.runQuery` and `ctx.runMutation` instead.\n *\n * @public\n */\nexport interface GenericActionCtx<DataModel extends GenericDataModel> {\n  /**\n   * Run the Convex query with the given name and arguments.\n   *\n   * Each `runQuery` call is a separate read transaction. Consider using an\n   * {@link internalQuery} to prevent users from calling the query directly.\n   *\n   * @example\n   * ```typescript\n   * const user = await ctx.runQuery(internal.users.get, { userId });\n   * ```\n   *\n   * @param query - A {@link FunctionReference} for the query to run.\n   * @param args - The arguments to the query function.\n   * @returns A promise of the query's result.\n   */\n  runQuery<\n    Query extends\n      | FunctionReference<\"query\", \"public\" | \"internal\">\n      | FunctionReference_future<\"query\", \"public\" | \"internal\">,\n  >(\n    query: Query,\n    ...args: OptionalRestArgs<Query>\n  ): Promise<FunctionReturnType<Query>>;\n\n  /**\n   * Run the Convex mutation with the given name and arguments.\n   *\n   * Each `runMutation` call is a separate write transaction. Consider using\n   * an {@link internalMutation} to prevent users from calling it directly.\n   *\n   * @example\n   * ```typescript\n   * await ctx.runMutation(internal.orders.markPaid, { id: orderId });\n   * ```\n   *\n   * @param mutation - A {@link FunctionReference} for the mutation to run.\n   * @param args - The arguments to the mutation function.\n   * @returns A promise of the mutation's result.\n   */\n  runMutation<\n    Mutation extends\n      | FunctionReference<\"mutation\", \"public\" | \"internal\">\n      | FunctionReference_future<\"mutation\", \"public\" | \"internal\">,\n  >(\n    mutation: Mutation,\n    ...args: OptionalRestArgs<Mutation>\n  ): Promise<FunctionReturnType<Mutation>>;\n\n  /**\n   * Run the Convex action with the given name and arguments.\n   *\n   * **Important:** Only use `runAction` when you need to cross runtimes\n   * (e.g., calling a `\"use node\"` action from the default Convex runtime).\n   * For code in the same runtime, extract shared logic into a plain\n   * TypeScript helper function instead, `runAction` has significant\n   * overhead (separate function call, separate resource allocation).\n   *\n   * Consider using an {@link internalAction} to prevent users from calling the\n   * action directly.\n   *\n   * @param action - A {@link FunctionReference} for the action to run.\n   * @param args - The arguments to the action function.\n   * @returns A promise of the action's result.\n   */\n  runAction<\n    Action extends\n      | FunctionReference<\"action\", \"public\" | \"internal\">\n      | FunctionReference_future<\"action\", \"public\" | \"internal\">,\n  >(\n    action: Action,\n    ...args: OptionalRestArgs<Action>\n  ): Promise<FunctionReturnType<Action>>;\n\n  /**\n   * A utility for scheduling Convex functions to run in the future.\n   */\n  scheduler: Scheduler;\n\n  /**\n   * Information about the currently authenticated user.\n   */\n  auth: Auth;\n\n  /**\n   * A utility for reading and writing files in storage.\n   */\n  storage: StorageActionWriter;\n\n  /**\n   * Run a vector search on the given table and index.\n   *\n   * @param tableName - The name of the table to query.\n   * @param indexName - The name of the vector index on the table to query.\n   * @param query - A {@link VectorSearchQuery} containing the vector to query,\n   * the number of results to return, and any filters.\n   * @returns A promise of IDs and scores for the documents with the nearest\n   * vectors\n   */\n  vectorSearch<\n    TableName extends TableNamesInDataModel<DataModel>,\n    IndexName extends VectorIndexNames<NamedTableInfo<DataModel, TableName>>,\n  >(\n    tableName: TableName,\n    indexName: IndexName,\n    query: Expand<\n      VectorSearchQuery<NamedTableInfo<DataModel, TableName>, IndexName>\n    >,\n  ): Promise<Array<{ _id: Id<TableName>; _score: number }>>;\n\n  meta: ActionMeta;\n}\n\n/**\n * The default arguments type for a Convex query, mutation, or action function.\n *\n * Convex functions always take an arguments object that maps the argument\n * names to their values.\n *\n * @public\n */\nexport type DefaultFunctionArgs = Record<string, unknown>;\n\n/**\n * The arguments array for a function that takes arguments.\n *\n * This is an array of a single {@link DefaultFunctionArgs} element.\n */\ntype OneArgArray<ArgsObject extends DefaultFunctionArgs = DefaultFunctionArgs> =\n  [ArgsObject];\n\n/**\n * The arguments to a function that takes no arguments (just an empty array).\n */\ntype NoArgsArray = [];\n\n/**\n * An array of arguments to a Convex function.\n *\n * Convex functions can take either a single {@link DefaultFunctionArgs} object or no\n * args at all.\n *\n * @public\n */\nexport type ArgsArray = OneArgArray | NoArgsArray;\n\n/**\n * A type for the empty object `{}`.\n *\n * Note that we don't use `type EmptyObject = {}` because that matches every object.\n */\nexport type EmptyObject = Record<string, never>;\n\n/**\n * Convert an {@link ArgsArray} into a single object type.\n *\n * Empty arguments arrays are converted to {@link EmptyObject}.\n * @public\n */\nexport type ArgsArrayToObject<Args extends ArgsArray> =\n  Args extends OneArgArray<infer ArgsObject> ? ArgsObject : EmptyObject;\n\n/**\n * A type representing the visibility of a Convex function.\n *\n * @public\n */\nexport type FunctionVisibility = \"public\" | \"internal\";\n\n/**\n * Given a {@link FunctionVisibility}, should this function have `isPublic: true`\n * or `isInternal: true`?\n */\ntype VisibilityProperties<Visiblity extends FunctionVisibility> = {\n  /** Phantom type marker; not present at runtime. */\n  _visibility: Visiblity;\n} & (Visiblity extends \"public\"\n  ? {\n      isPublic: true;\n    }\n  : {\n      isInternal: true;\n    });\n\n/**\n * A mutation function that is part of this app.\n *\n * You can create a mutation by wrapping your function in\n * {@link mutationGeneric} or {@link internalMutationGeneric} and exporting it.\n *\n * @public\n */\nexport type RegisteredMutation<\n  Visibility extends FunctionVisibility,\n  Args extends DefaultFunctionArgs,\n  Returns,\n> = {\n  isConvexFunction: true;\n  isMutation: true;\n\n  /** @internal */\n  invokeMutation(argsStr: string): Promise<string>;\n\n  /** @internal */\n  exportArgs(): string;\n\n  /** @internal */\n  exportReturns(): string;\n\n  /** @internal */\n  _handler: (ctx: GenericMutationCtx<any>, args: Args) => Returns;\n} & VisibilityProperties<Visibility>;\n\n/**\n * A query function that is part of this app.\n *\n * You can create a query by wrapping your function in\n * {@link queryGeneric} or {@link internalQueryGeneric} and exporting it.\n *\n * @public\n */\nexport type RegisteredQuery<\n  Visibility extends FunctionVisibility,\n  Args extends DefaultFunctionArgs,\n  Returns,\n> = {\n  isConvexFunction: true;\n  isQuery: true;\n\n  /** @internal */\n  invokeQuery(argsStr: string): Promise<string>;\n\n  /** @internal */\n  exportArgs(): string;\n\n  /** @internal */\n  exportReturns(): string;\n\n  /** @internal */\n  _handler: (ctx: GenericQueryCtx<any>, args: Args) => Returns;\n} & VisibilityProperties<Visibility>;\n\n/**\n * An action that is part of this app.\n *\n * You can create an action by wrapping your function in\n * {@link actionGeneric} or {@link internalActionGeneric} and exporting it.\n *\n * @public\n */\nexport type RegisteredAction<\n  Visibility extends FunctionVisibility,\n  Args extends DefaultFunctionArgs,\n  Returns,\n> = {\n  isConvexFunction: true;\n  isAction: true;\n\n  /** @internal */\n  invokeAction(requestId: string, argsStr: string): Promise<string>;\n\n  /** @internal */\n  exportArgs(): string;\n\n  /** @internal */\n  exportReturns(): string;\n\n  /** @internal */\n  _handler: (ctx: GenericActionCtx<any>, args: Args) => Returns;\n} & VisibilityProperties<Visibility>;\n\n/**\n * An HTTP action that is part of this app's public API.\n *\n * You can create public HTTP actions by wrapping your function in\n * {@link httpActionGeneric} and exporting it.\n *\n * @public\n */\nexport type PublicHttpAction = {\n  isHttp: true;\n\n  /** @internal */\n  invokeHttpAction(request: Request): Promise<Response>;\n  /** @internal */\n  _handler: (ctx: GenericActionCtx<any>, request: Request) => Promise<Response>;\n};\n\n/**\n * @deprecated -- See the type definition for `MutationBuilder` or similar for\n * the types used for defining Convex functions.\n *\n * The definition of a Convex query, mutation, or action function without\n * argument validation.\n *\n * Convex functions always take a context object as their first argument\n * and an (optional) args object as their second argument.\n *\n * This can be written as a function like:\n * ```js\n * import { query } from \"./_generated/server\";\n *\n * export const func = query(({ db }, { arg }) => {...});\n * ```\n * or as an object like:\n *\n * ```js\n * import { query } from \"./_generated/server\";\n *\n * export const func = query({\n *   handler: ({ db }, { arg }) => {...},\n * });\n * ```\n * See {@link ValidatedFunction} to add argument validation.\n *\n * @public\n */\nexport type UnvalidatedFunction<Ctx, Args extends ArgsArray, Returns> =\n  | ((ctx: Ctx, ...args: Args) => Returns)\n  | {\n      handler: (ctx: Ctx, ...args: Args) => Returns;\n    };\n\n/**\n * @deprecated -- See the type definition for `MutationBuilder` or similar for\n * the types used for defining Convex functions.\n *\n * The definition of a Convex query, mutation, or action function with argument\n * validation.\n *\n * Argument validation allows you to assert that the arguments to this function\n * are the expected type.\n *\n * Example:\n *\n * ```js\n * import { query } from \"./_generated/server\";\n * import { v } from \"convex/values\";\n *\n * export const func = query({\n *   args: {\n *     arg: v.string()\n *   },\n *   handler: ({ db }, { arg }) => {...},\n * });\n * ```\n *\n * **For security, argument validation should be added to all public functions in\n * production apps.**\n *\n * See {@link UnvalidatedFunction} for functions without argument validation.\n * @public\n */\nexport interface ValidatedFunction<\n  Ctx,\n  ArgsValidator extends PropertyValidators,\n  Returns,\n> {\n  /**\n   * A validator for the arguments of this function.\n   *\n   * This is an object mapping argument names to validators constructed with\n   * {@link values.v}.\n   *\n   * ```js\n   * import { v } from \"convex/values\";\n   *\n   * const args = {\n   *   stringArg: v.string(),\n   *   optionalNumberArg: v.optional(v.number()),\n   * }\n   * ```\n   */\n  args: ArgsValidator;\n\n  /**\n   * The implementation of this function.\n   *\n   * This is a function that takes in the appropriate context and arguments\n   * and produces some result.\n   *\n   * @param ctx - The context object. This is one of {@link QueryCtx},\n   * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n   * @param args - The arguments object for this function. This will match\n   * the type defined by the argument validator.\n   * @returns\n   */\n  handler: (ctx: Ctx, args: ObjectType<ArgsValidator>) => Returns;\n}\n\n/**\n * There are multiple syntaxes for defining a Convex function:\n * ```\n *  - query(async (ctx, args) => {...})\n *  - query({ handler: async (ctx, args) => {...} })\n *  - query({ args: { a: v.string }, handler: async (ctx, args) => {...} } })\n *  - query({ args: { a: v.string }, returns: v.string(), handler: async (ctx, args) => {...} } })\n *```\n *\n * In each of these, we want to correctly infer the type for the arguments and\n * return value, preferring the type derived from a validator if it's provided.\n *\n * To avoid having a separate overload for each, which would show up in error messages,\n * we use the type params -- ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs.\n *\n * The type for ReturnValue and OneOrZeroArgs are constrained by the type or ArgsValidator and\n * ReturnsValidator if they're present, and inferred from any explicit type annotations to the\n * arguments or return value of the function.\n *\n * Below are a few utility types to get the appropriate type constraints based on\n * an optional validator.\n *\n * Additional tricks:\n * - We use Validator | void instead of Validator | undefined because the latter does\n * not work with `strictNullChecks` since it's equivalent to just `Validator`.\n * - We use a tuple type of length 1 to avoid distribution over the union\n *  https://github.com/microsoft/TypeScript/issues/29368#issuecomment-453529532\n */\n\nexport type ReturnValueForOptionalValidator<\n  ReturnsValidator extends Validator<any, any, any> | PropertyValidators | void,\n> = [ReturnsValidator] extends [Validator<any, any, any>]\n  ? ValidatorTypeToReturnType<Infer<ReturnsValidator>>\n  : [ReturnsValidator] extends [PropertyValidators]\n    ? ValidatorTypeToReturnType<ObjectType<ReturnsValidator>>\n    : any;\n\nexport type ArgsArrayForOptionalValidator<\n  ArgsValidator extends GenericValidator | PropertyValidators | void,\n> = [ArgsValidator] extends [Validator<any, any, any>]\n  ? OneArgArray<Infer<ArgsValidator>>\n  : [ArgsValidator] extends [PropertyValidators]\n    ? OneArgArray<ObjectType<ArgsValidator>>\n    : ArgsArray;\n\nexport type DefaultArgsForOptionalValidator<\n  ArgsValidator extends GenericValidator | PropertyValidators | void,\n> = [ArgsValidator] extends [Validator<any, any, any>]\n  ? [Infer<ArgsValidator>]\n  : [ArgsValidator] extends [PropertyValidators]\n    ? [ObjectType<ArgsValidator>]\n    : OneArgArray;\n\n/**\n * Internal type helper used by Convex code generation.\n *\n * Used to give {@link mutationGeneric} a type specific to your data model.\n * @public\n */\nexport type MutationBuilder<\n  DataModel extends GenericDataModel,\n  Visibility extends FunctionVisibility,\n> = {\n  <\n    ArgsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnValue extends ReturnValueForOptionalValidator<ReturnsValidator> = any,\n    OneOrZeroArgs extends ArgsArrayForOptionalValidator<ArgsValidator> =\n      DefaultArgsForOptionalValidator<ArgsValidator>,\n  >(\n    mutation:\n      | {\n          /**\n           * Argument validation.\n           *\n           * Examples:\n           *\n           * ```\n           * args: {}\n           * args: { input: v.optional(v.number()) }\n           * args: { message: v.string(), author: v.id(\"authors\") }\n           * args: { messages: v.array(v.string()) }\n           * ```\n           */\n          args?: ArgsValidator;\n          /**\n           * The return value validator.\n           *\n           * Examples:\n           *\n           * ```\n           * returns: v.null()\n           * returns: v.string()\n           * returns: { message: v.string(), author: v.id(\"authors\") }\n           * returns: v.array(v.string())\n           * ```\n           */\n          returns?: ReturnsValidator;\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          handler: (\n            ctx: GenericMutationCtx<DataModel>,\n            ...args: OneOrZeroArgs\n          ) => ReturnValue;\n        }\n      | {\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          (\n            ctx: GenericMutationCtx<DataModel>,\n            ...args: OneOrZeroArgs\n          ): ReturnValue;\n        },\n  ): RegisteredMutation<\n    Visibility,\n    ArgsArrayToObject<OneOrZeroArgs>,\n    ReturnValue\n  >;\n};\n\n/**\n * Internal type helper used by Convex code generation.\n *\n * Used to give {@link mutationGeneric} a type specific to your data model.\n * @public\n */\nexport type MutationBuilderWithTable<\n  DataModel extends GenericDataModel,\n  Visibility extends FunctionVisibility,\n> = {\n  <\n    ArgsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnValue extends ReturnValueForOptionalValidator<ReturnsValidator> = any,\n    OneOrZeroArgs extends ArgsArrayForOptionalValidator<ArgsValidator> =\n      DefaultArgsForOptionalValidator<ArgsValidator>,\n  >(\n    mutation:\n      | {\n          /**\n           * Argument validation.\n           *\n           * Examples:\n           *\n           * ```\n           * args: {}\n           * args: { input: v.optional(v.number()) }\n           * args: { message: v.string(), author: v.id(\"authors\") }\n           * args: { messages: v.array(v.string()) }\n           * ```\n           */\n          args?: ArgsValidator;\n          /**\n           * The return value validator.\n           *\n           * Examples:\n           *\n           * ```\n           * returns: v.null()\n           * returns: v.string()\n           * returns: { message: v.string(), author: v.id(\"authors\") }\n           * returns: v.array(v.string())\n           * ```\n           */\n          returns?: ReturnsValidator;\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          handler: (\n            ctx: GenericMutationCtxWithTable<DataModel>,\n            ...args: OneOrZeroArgs\n          ) => ReturnValue;\n        }\n      | {\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          (\n            ctx: GenericMutationCtxWithTable<DataModel>,\n            ...args: OneOrZeroArgs\n          ): ReturnValue;\n        },\n  ): RegisteredMutation<\n    Visibility,\n    ArgsArrayToObject<OneOrZeroArgs>,\n    ReturnValue\n  >;\n};\n\n/**\n * Internal type helper used by Convex code generation.\n *\n * Used to give {@link queryGeneric} a type specific to your data model.\n * @public\n */\nexport type QueryBuilder<\n  DataModel extends GenericDataModel,\n  Visibility extends FunctionVisibility,\n> = {\n  <\n    ArgsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnValue extends ReturnValueForOptionalValidator<ReturnsValidator> = any,\n    OneOrZeroArgs extends ArgsArrayForOptionalValidator<ArgsValidator> =\n      DefaultArgsForOptionalValidator<ArgsValidator>,\n  >(\n    query:\n      | {\n          /**\n           * Argument validation.\n           *\n           * Examples:\n           *\n           * ```\n           * args: {}\n           * args: { input: v.optional(v.number()) }\n           * args: { message: v.string(), author: v.id(\"authors\") }\n           * args: { messages: v.array(v.string()) }\n           * ```\n           */\n          args?: ArgsValidator;\n          /**\n           * The return value validator.\n           *\n           * Examples:\n           *\n           * ```\n           * returns: v.null()\n           * returns: v.string()\n           * returns: { message: v.string(), author: v.id(\"authors\") }\n           * returns: v.array(v.string())\n           * ```\n           */\n          returns?: ReturnsValidator;\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          handler: (\n            ctx: GenericQueryCtx<DataModel>,\n            ...args: OneOrZeroArgs\n          ) => ReturnValue;\n        }\n      | {\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          (\n            ctx: GenericQueryCtx<DataModel>,\n            ...args: OneOrZeroArgs\n          ): ReturnValue;\n        },\n  ): RegisteredQuery<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>;\n};\n\n/**\n * Internal type helper used by Convex code generation.\n *\n * Used to give {@link queryGeneric} a type specific to your data model.\n * @public\n */\nexport type QueryBuilderWithTable<\n  DataModel extends GenericDataModel,\n  Visibility extends FunctionVisibility,\n> = {\n  <\n    ArgsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnValue extends ReturnValueForOptionalValidator<ReturnsValidator> = any,\n    OneOrZeroArgs extends ArgsArrayForOptionalValidator<ArgsValidator> =\n      DefaultArgsForOptionalValidator<ArgsValidator>,\n  >(\n    query:\n      | {\n          /**\n           * Argument validation.\n           *\n           * Examples:\n           *\n           * ```\n           * args: {}\n           * args: { input: v.optional(v.number()) }\n           * args: { message: v.string(), author: v.id(\"authors\") }\n           * args: { messages: v.array(v.string()) }\n           * ```\n           */\n          args?: ArgsValidator;\n          /**\n           * The return value validator.\n           *\n           * Examples:\n           *\n           * ```\n           * returns: v.null()\n           * returns: v.string()\n           * returns: { message: v.string(), author: v.id(\"authors\") }\n           * returns: v.array(v.string())\n           * ```\n           */\n          returns?: ReturnsValidator;\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          handler: (\n            ctx: GenericQueryCtxWithTable<DataModel>,\n            ...args: OneOrZeroArgs\n          ) => ReturnValue;\n        }\n      | {\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          (\n            ctx: GenericQueryCtxWithTable<DataModel>,\n            ...args: OneOrZeroArgs\n          ): ReturnValue;\n        },\n  ): RegisteredQuery<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>;\n};\n\n/**\n * Internal type helper used by Convex code generation.\n *\n * Used to give {@link actionGeneric} a type specific to your data model.\n * @public\n */\nexport type ActionBuilder<\n  DataModel extends GenericDataModel,\n  Visibility extends FunctionVisibility,\n> = {\n  <\n    ArgsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnsValidator extends\n      | PropertyValidators\n      | Validator<any, \"required\", any>\n      | void,\n    ReturnValue extends ReturnValueForOptionalValidator<ReturnsValidator> = any,\n    OneOrZeroArgs extends ArgsArrayForOptionalValidator<ArgsValidator> =\n      DefaultArgsForOptionalValidator<ArgsValidator>,\n  >(\n    func:\n      | {\n          /**\n           * Argument validation.\n           *\n           * Examples:\n           *\n           * ```\n           * args: {}\n           * args: { input: v.optional(v.number()) }\n           * args: { message: v.string(), author: v.id(\"authors\") }\n           * args: { messages: v.array(v.string()) }\n           * ```\n           *\n           */\n          args?: ArgsValidator;\n          /**\n           * The return value validator.\n           *\n           * Examples:\n           *\n           * ```\n           * returns: v.null()\n           * returns: v.string()\n           * returns: { message: v.string(), author: v.id(\"authors\") }\n           * returns: v.array(v.string())\n           * ```\n           */\n          returns?: ReturnsValidator;\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          handler: (\n            ctx: GenericActionCtx<DataModel>,\n            ...args: OneOrZeroArgs\n          ) => ReturnValue;\n        }\n      | {\n          /**\n           * The implementation of this function.\n           *\n           * This is a function that takes in the appropriate context and arguments\n           * and produces some result.\n           *\n           * @param ctx - The context object. This is one of {@link QueryCtx},\n           * {@link MutationCtx}, or {@link ActionCtx} depending on the function type.\n           * @param args - The arguments object for this function. This will match\n           * the type defined by the argument validator if provided.\n           * @returns\n           */\n          (\n            ctx: GenericActionCtx<DataModel>,\n            ...args: OneOrZeroArgs\n          ): ReturnValue;\n        },\n  ): RegisteredAction<\n    Visibility,\n    ArgsArrayToObject<OneOrZeroArgs>,\n    ReturnValue\n  >;\n};\n\n/**\n * Internal type helper used by Convex code generation.\n *\n * Used to give {@link httpActionGeneric} a type specific to your data model\n * and functions.\n * @public\n */\nexport type HttpActionBuilder = (\n  func: (ctx: GenericActionCtx<any>, request: Request) => Promise<Response>,\n) => PublicHttpAction;\n\nexport interface AdvancedRunQueryOptions {\n  /**\n   * Custom limits for a nested transaction. Each field specifies the absolute\n   * maximum allowed for the nested function call. Values are capped at the\n   * global transaction limits, so they can only lower limits, never raise them.\n   */\n  transactionLimits?: TransactionLimits;\n  /**\n   * Run a query on a recent snapshot of the database that is not guaranteed\n   * to be up-to-date when this transaction commits.\n   *\n   * This is an advanced feature which can introduce subtle race conditions,\n   * so its use is generally discouraged except for specific use-cases where\n   * database read conflicts are expected, e.g. reading from an append-only\n   * table with immutable records where the only read conflicts are from\n   * concurrent appends.\n   *\n   * To determine the snapshot of the nested query, you can call\n   * `ctx.meta.getSnapshotTs()` from within the stale snapshot query. To\n   * compare to the parent mutation's snapshot timestamp, you can return that\n   * value from the query and call `ctx.meta.getSnapshotTs()` from the parent.\n   */\n  useStaleSnapshot?: boolean;\n}\n"],
   "mappings": ";;;;;;;;;;;;;;AAAA;AAAA;",
   "names": []
 }

package/dist/cjs/server/schema.js

@@ -117,35 +117,57 @@ class TableDefinition {
     return this;
   }
   /**
-   * Stage a new document validator for this table.
+   * Stage changes to this table's document validator.
    *
    * Convex validates the staged validator against the table's existing
    * documents in the background, while the validator passed to
-   * {@link defineTable} remains the one enforced on reads and writes. Once
-   * the background validation succeeds, make the staged validator the
-   * table's validator and remove `.staged()`.
+   * {@link defineTable} remains the one enforced on writes. Once
+   * the background validation succeeds, apply the staged changes
+   * and remove `.staged()`.
+   *
+   * For an object validator, pass only the fields to add or replace. Fields
+   * omitted from the changes keep their enforced validators.
+   * Set a field to `undefined` to remove it from the staged validator.
+   * For nested objects, you must specify the full object validator.
    *
    * ```ts
    * defineTable({
-   *   author: v.string(),
+   *   apple: v.string(),
+   *   banana: v.number(),
+   *   legacy: v.optional(v.string()),
    * }).staged({
-   *   author: v.array(v.string()),
+   *   banana: v.union(v.string(), v.number()),
+   *   legacy: undefined,
    * })
    * ```
    *
-   * TODO: link a worked staged-schema example from the docs once one exists.
+   * See [Staged validators](https://docs.convex.dev/database/schemas#staged-validators).
    *
-   * @param documentSchema - The proposed next type of documents stored in
-   * this table, as an object of field validators or a schema validator.
+   * @param documentSchema - Field changes for a table defined as an object or
+   * `v.any()`, or a full schema validator specifying the proposed next document
+   * type. Use a full schema validator for a table defined as a union.
    * @returns A {@link TableDefinition} with the staged validator attached.
-   *
-   * @internal
    */
   staged(documentSchema) {
     if (this.stagedValidator !== void 0) {
       throw new Error("Table cannot have more than one staged validator.");
     }
-    this.stagedValidator = (0, import_validator.isValidator)(documentSchema) ? documentSchema : import_validator.v.object(documentSchema);
+    if ((0, import_validator.isValidator)(documentSchema)) {
+      this.stagedValidator = documentSchema;
+    } else {
+      if (this.validator.kind !== "object" && this.validator.kind !== "any") {
+        throw new Error(
+          "Specifying top-level field changes is only supported for simple table definitions. For a table defined with a union or record validator, you must stage a fully defined object or union validator."
+        );
+      }
+      const enforcedFields = this.validator.kind === "object" ? this.validator.fields : {};
+      const fields = Object.fromEntries(
+        Object.entries({ ...enforcedFields, ...documentSchema }).filter(
+          (entry) => entry[1] !== void 0
+        )
+      );
+      this.stagedValidator = import_validator.v.object(fields);
+    }
     return this.self();
   }
   /**