convex_rules

Convex guidelines

Function guidelines

Http endpoint syntax

• HTTP endpoints are defined in convex/http.ts and require an httpAction decorator. For example:

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.

Validators

• Below is an example of an array validator:

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:

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(),
      }),
    ),
  ),
});

• Here are the valid Convex types along with their respective validators:

  Convex Type	TS/JS type	Example Usage	Validator for argument validation and schemas	Notes
  Id	string	doc._id	v.id(tableName)
  Null	null	null	v.null()	JavaScript's undefined is not a valid Convex value. Functions the return undefined or do not return will return null when called from a client. Use null instead.
  Int64	bigint	3n	v.int64()	Int64s only support BigInts between -2^63 and 2^63-1. Convex supports bigints in most modern browsers.
  Float64	number	3.1	v.number()	Convex supports all IEEE-754 double-precision floating point numbers (such as NaNs). Inf and NaN are JSON serialized as strings.
  Boolean	boolean	true	v.boolean()
  String	string	"abc"	v.string()	Strings are stored as UTF-8 and must be valid Unicode sequences. Strings must be smaller than the 1MB total size limit when encoded as UTF-8.
  Bytes	ArrayBuffer	new ArrayBuffer(8)	v.bytes()	Convex supports first class bytestrings, passed in as ArrayBuffers. Bytestrings must be smaller than the 1MB total size limit for Convex types.
  Array	Array	[1, 3.2, "abc"]	v.array(values)	Arrays can have at most 8192 values.
  Object	Object	{a: "abc"}	v.object({property: value})	Convex only supports "plain old JavaScript objects" (objects that do not have a custom prototype). Objects can have at most 1024 entries. Field names must be nonempty and not start with "$" or "_".

| Record | Record | {"a": "1", "b": "2"} | v.record(keys, values) | Records are objects at runtime, but can have dynamic keys. Keys must be only ASCII characters, nonempty, and not start with "$" or "_". |