chat-io: Instructions file for GitHub Copilot

Convex guidelines

Function guidelines

New function syntax

• ALWAYS use the new function syntax for Convex functions. For example:

import { v } from "convex/values";
import { query } from "./_generated/server";

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:

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 { v } from "convex/values";
import { mutation } from "./_generated/server";

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

• Always use the v.null() validator when returning a null value. Below is an example query that returns a null value:

import { v } from "convex/values";
import { query } from "./_generated/server";

export const exampleQuery = query({
  args: {},
  returns: v.null(),
  handler: async (ctx, args) => {
    console.log("This query returns a null value");
    return null;
  },
});