convex

Convex guidelines

Function guidelines

New function syntax

• ALWAYS use the new function syntax for Convex functions. For example: typescript import { query } from "./_generated/server"; import { v } from "convex/values"; export const f = query({ args: {}, returns: v.null(), handler: async (ctx, args) => { // Function body }, });

Http endpoint syntax

• HTTP endpoints are defined in convex/http.ts and require an httpAction decorator. For example: typescript import { httpRouter } from "convex/server"; import { httpAction } from "./_generated/server"; const http = httpRouter(); http.route({ path: "/echo", method: "POST", handler: httpAction(async (ctx, req) => { const body = await req.bytes(); return new Response(body, { status: 200 }); }), });

Function registration

• Use internalQuery, internalMutation, and internalAction to register internal functions. These functions are private and aren't part of an app's API. They can only be called by other Convex functions.
• Use query, mutation, and action to register public functions. These functions are part of the public API and are exposed to the public Internet. Do NOT use query, mutation, or action to register sensitive internal functions that should be kept private.
• You CANNOT register a function through the api or internal objects.
• ALWAYS include argument and return validators for all Convex functions. If a function doesn't return anything, include returns: v.null() as its output validator.
• If the JavaScript implementation of a Convex function doesn't have a return value, it implicitly returns null.

Function calling

• Use ctx.runQuery to call a query from a query, mutation, or action.

• Use ctx.runMutation to call a mutation from a mutation or action.

• Use ctx.runAction to call an action from an action.

• ONLY call an action from another action if you need to cross runtimes (e.g. from V8 to Node). Otherwise, pull out the shared code into a helper async function and call that directly instead.

• Try to use as few calls from actions to queries and mutations as possible. Queries and mutations are transactions, so splitting logic up into multiple calls introduces the risk of race conditions.

• All of these calls take in a FunctionReference. Do NOT try to pass the callee function directly into one of these calls.

• When using ctx.runQuery, ctx.runMutation, or ctx.runAction to call a function in the same file, specify a type annotation on the return value to work around TypeScript circularity limitations. For example, ``` export const f = query({ args: { name: v.string() }, returns: v.string(), handler: async (ctx, args) => { return "Hello " + args.name; }, });

                        export const g = query({
                          args: {},
                          returns: v.null(),
                          handler: async (ctx, args) => {
                            const result: string = await ctx.runQuery(api.example.f, { name: "Bob" });
                            return null;
                          },
                        });
                        ```