anthropic_convex_rules

<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 }, }); </new_function_syntax> <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 }); }), }); - HTTP endpoints are always registered at the exact path you specify in the path field. For example, if you specify /api/someRoute, the endpoint will be registered at /api/someRoute. </http_endpoint_syntax> - Below is an example of an array validator: ```typescript import { mutation } from "./_generated/server"; import { v } from "convex/values";

                        export default mutation({
                        args: {
                            simpleArray: v.array(v.union(v.string(), v.number())),
                        },
                        handler: async (ctx, args) => {
                            //...
                        },
                        });
                        ```
  - Below is an example of a schema with validators that codify a discriminated union type:
                        ```typescript
                        import { defineSchema, defineTable } from "convex/server";
                        import { v } from "convex/values";

                        export default defineSchema({
                            results: defineTable(
                                v.union(
                                    v.object({
                                        kind: v.literal("error"),
                                        errorMessage: v.string(),
                                    }),
                                    v.object({
                                        kind: v.literal("success"),
                                        value: v.number(),
                                    }),
                                ),
                            )
                        });
                        ```
</validators>
<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. These functions are always imported from `./_generated/server`.
  - 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. This includes all of `query`, `internalQuery`, `mutation`, `internalMutation`, `action`, and `internalAction`. 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_registration>
<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;
                          },
                        });
                        ```
</function_calling>
<function_references>
  - Function references are pointers to registered Convex functions.
  - Use the `api` object defined by the framework in `convex/_generated/api.ts` to call public functions registered with `query`, `mutation`, or `action`.
  - Use the `internal` object defined by the framework in `convex/_generated/api.ts` to call internal (or private) functions registered with `internalQuery`, `internalMutation`, or `internalAction`.
  - Convex uses file-based routing, so a public function defined in `convex/example.ts` named `f` has a function reference of `api.example.f`.
  - A private function defined in `convex/example.ts` named `g` has a function reference of `internal.example.g`.
  - Functions can also registered within directories nested within the `convex/` folder. For example, a public function `h` defined in `convex/messages/access.ts` has a function reference of `api.messages.access.h`.
</function_references>
<api_design>
  - Convex uses file-based routing, so thoughtfully organize files with public query, mutation, or action functions within the `convex/` directory.
  - Use `query`, `mutation`, and `action` to define public functions.
  - Use `internalQuery`, `internalMutation`, and `internalAction` to define private, internal functions.
</api_design>
<pagination>
  - Paginated queries are queries that return a list of results in incremental pages.
  - You can define pagination using the following syntax: