|
| 1 | +declare const Convex: { |
| 2 | + syscall: (op: string, jsonArgs: string) => string; |
| 3 | + asyncSyscall: (op: string, jsonArgs: string) => Promise<string>; |
| 4 | + jsSyscall: (op: string, args: Record<string, any>) => any; |
| 5 | + op: (opName: string, ...args: any[]) => any; |
| 6 | +}; |
| 7 | +/** |
| 8 | + * Perform a syscall, taking in a JSON-encodable object as an argument, serializing with |
| 9 | + * JSON.stringify, calling into Rust, and then parsing the response as a JSON-encodable |
| 10 | + * value. If one of your arguments is a Convex value, you must call `convexToJson` on it |
| 11 | + * before passing it to this function, and if the return value has a Convex value, you're |
| 12 | + * also responsible for calling `jsonToConvex`: This layer only deals in JSON. |
| 13 | + */ |
| 14 | + |
| 15 | +export function performSyscall(op: string, arg: Record<string, any>): any { |
| 16 | + if (typeof Convex === "undefined" || Convex.syscall === undefined) { |
| 17 | + throw new Error( |
| 18 | + "The Convex execution environment is being unexpectedly run outside of a Convex backend.", |
| 19 | + ); |
| 20 | + } |
| 21 | + const resultStr = Convex.syscall(op, JSON.stringify(arg)); |
| 22 | + return JSON.parse(resultStr); |
| 23 | +} |
| 24 | + |
| 25 | +export async function performAsyncSyscall( |
| 26 | + op: string, |
| 27 | + arg: Record<string, any>, |
| 28 | +): Promise<any> { |
| 29 | + if (typeof Convex === "undefined" || Convex.asyncSyscall === undefined) { |
| 30 | + throw new Error( |
| 31 | + "The Convex database and auth objects are being used outside of a Convex backend. " + |
| 32 | + "Did you mean to use `useQuery` or `useMutation` to call a Convex function?", |
| 33 | + ); |
| 34 | + } |
| 35 | + let resultStr; |
| 36 | + try { |
| 37 | + resultStr = await Convex.asyncSyscall(op, JSON.stringify(arg)); |
| 38 | + } catch (e: any) { |
| 39 | + // Rethrow the exception since the error coming from the async syscall layer |
| 40 | + // doesn't have a stack trace associated with it. |
| 41 | + throw new Error(e.message); |
| 42 | + } |
| 43 | + return JSON.parse(resultStr); |
| 44 | +} |
| 45 | + |
| 46 | +/** |
| 47 | + * Call into a "JS" syscall. Like `performSyscall`, this calls a dynamically linked |
| 48 | + * function set up in the Convex function execution. Unlike `performSyscall`, the |
| 49 | + * arguments do not need to be JSON-encodable and neither does the return value. |
| 50 | + * |
| 51 | + * @param op |
| 52 | + * @param arg |
| 53 | + * @returns |
| 54 | + */ |
| 55 | +export function performJsSyscall(op: string, arg: Record<string, any>): any { |
| 56 | + if (typeof Convex === "undefined" || Convex.jsSyscall === undefined) { |
| 57 | + throw new Error( |
| 58 | + "The Convex execution environment is being unexpectedly run outside of a Convex backend.", |
| 59 | + ); |
| 60 | + } |
| 61 | + return Convex.jsSyscall(op, arg); |
| 62 | +} |
| 63 | + |
| 64 | +/** |
| 65 | + * Perform an "op" -- this is similar to `performSyscall` in many ways (it takes in |
| 66 | + * and returns JSON, and calls into Rust). However unlike syscalls, ops do not |
| 67 | + * need to be backwards compatible with `convex/server` since they are only used |
| 68 | + * within JS code that is pushed with their Rust implementations. (i.e. udf-runtime |
| 69 | + * and system UDFs) |
| 70 | + * |
| 71 | + * @param op |
| 72 | + * @param arg |
| 73 | + * @returns |
| 74 | + */ |
| 75 | +export function performOp(op: string, ...args: any[]): any { |
| 76 | + if (typeof Convex === "undefined" || Convex.op === undefined) { |
| 77 | + throw new Error( |
| 78 | + "The Convex execution environment is being unexpectedly run outside of a Convex backend.", |
| 79 | + ); |
| 80 | + } |
| 81 | + return Convex.op(op, ...args); |
| 82 | +} |
0 commit comments