Web Dev Cody

Web Dev Cody guides viewers in creating a comprehensive full stack file storage application on YouTube. The tutorial covers features like organizations, file upload, management, role-based authorization, authentication, cron deletes, favorites, trash functionality, and various UI components such as dialogs, modals, toasts, dropdowns, and more. 

Build a File Storage App with Role Based Authorization (Next.js, Shadcn, Typescript)

When developing Convex apps with TypeScript, you’ll achieve the fastest iteration cycle and best developer experience once you’ve streamlined how schema enforcement, argument validation, and end-to-end type hinting all work together in your app. 

In the first post in this series, the [Types and Validators cookbook](https://stack.convex.dev/types-cookbook), we shared several basic patterns & best practices for organizing your codebase to share types & validators from your schema, which becomes the central source of truth for your data model. 

In this post, we’ll take it one step further and introduce a few more advanced techniques & helpers to accelerate the development workflow in your Convex projects.  

## Review: reuse schema field declarations

As mentioned in the [previous post](https://stack.convex.dev/types-cookbook), you can define validators describing your data model in your schema file, then export them for use across your codebase like so: 

```tsx
// in convex/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export const recipeFields = {
  name: v.string(),
  course: v.union(
    v.literal("appetizer"),
    v.literal("main"),
    v.literal("dessert")
  ),
  ingredients: v.array(v.string()),
  steps: v.array(v.string()),
};

export default defineSchema({
  recipes: defineTable(recipeFields).index("by_course", ["course"]),
});
```

The exported object can then be used wherever you need data of the same shape, for example to validate arguments of an `addRecipe` mutation that inserts a new document:

```tsx
// in convex/recipes.ts
import { mutation } from "./_generated/server";
import { recipeFields } from "./schema";

export const addRecipe = mutation({
  args: recipeFields,
  handler: async (ctx, args) => {
    return await ctx.db.insert("recipes", args);
  },
});
```

And to ensure your frontend is also typed accordingly, the generated `Doc<table>` generic type, along with handy utilities like `WithoutSystemFields<document>`, ensures your client-side code matches the data model defined by your schema:

```tsx
// in src/NewRecipePage.tsx

import { api } from "../convex/_generated/api";
import type { Doc } from "../convex/_generated/dataModel";
import type { WithoutSystemFields } from "convex/server";

export function SaveRecipeButton({
  recipeData,
}: {
  recipeData: WithoutSystemFields<Doc<"recipes">>,
}) {
  const createRecipe = useMutation(api.recipes.create);
  const onClick = () => createRecipe(recipeData);
  return <button onClick={onClick}>Save recipe</button>;
}
```

## Put TS utility types to work

Sometimes you only want to work with a specific subset of the fields for a given table. On the client side, you can use TypeScript’s builtin [`Pick`](https://www.typescriptlang.org/docs/handbook/utility-types.html#picktype-keys) and [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys) utility types to specify exactly which fields are needed:

```tsx
// in src/Cookbook.tsx
type RecipeSummary = Pick<Doc<"recipes">, "name" | "course">;
type UncategorizedRecipe = Omit<Doc<"recipes">, "course">;

function RecipeHeader({ recipe }: { recipe: RecipeSummary }) {
  return (
    <h1>
      {recipe.name} ({recipe.course})
    </h1>
  );
}

function RecipeDetails({ recipe }: { recipe: UncategorizedRecipe }) {
  return (
    <p>
      {recipe.name}: {recipe.steps.length} steps
    </p>
  );
}
```

Similarly, you can use TypeScript’s builtin [`Partial`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype) to make an all-fields-optional type for those cases where you’re not sure which subset of a document might be needed. This comes in handy when patching documents, for example: 

```tsx
// in src/Cookbook.tsx
import { useMutation } from "convex/react";
import { api } from "../convex/_generated/api";
import type { Id, Doc } from "../convex/_generated/dataModel";

function RecipeEditor({ recipeId: Id<'recipes'> }) {
	const updateRecipe = useMutation(api.recipes.update);
	
	// in response to some user input...
  const newData: Partial<Doc<'recipes'>> = { 
		name:  'Sweeter recipe name',
		course: 'dessert'
  });
	updateRecipe(recipeId, newData);
}

```

## Choose validator subsets with object destructuring

Similar to `Pick` in TypeScript, object de-structuring helps you derive subsets of the validators exported from your schema, and use these to validate function arguments:

```tsx
// in convex/recipes.ts
import { query} from "./_generated/server";
import { recipeFields } from "./schema";

const { course } = recipeFields;

export const findRecipesByCourse = query({
  args: { course },
  handler: async (ctx, args) => {
    return await ctx.db
      .query("recipes")
      .withIndex("by_course", (q) => q.eq("course", args.course))
      .collect();
  },
});
```

And analogous to TypeScript’s `Omit`, combining de-structuring with the rest operator (`...`) lets you ignore certain field validators and work with just those that remain:

```tsx
// in convex/recipes.ts
import { mutation } from "./_generated/server";
import { recipeFields } from "./schema";

const { course, ...recipeWithoutCourse } = recipeFields

export const addDessert = mutation({
  args: recipeWithoutCourse,
  handler: async (ctx, args) => {
    return await ctx.db.insert("recipes", { ...args, course: "dessert" });
  },
});
```

## `Table` helper for schema definition & validation

<GitHubRepo url="https://github.com/get-convex/convex-helpers" />


The  [`convex-helpers`](https://github.com/get-convex/convex-helpers) library provides a convenient [`Table` helper](https://github.com/get-convex/convex-helpers/blob/main/packages/convex-helpers/server/index.ts) to codify the pattern of splitting validator fields out of table definitions. 

`Table` accepts a `fields` argument defining your field validators (just like you’d pass to `defineTable`):

```tsx
// convex/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";
import { Table } from "convex-helpers/server"; // npm i convex-helpers

export const Recipes = Table("recipes", {
  name: v.string(),
  course: v.union(
    v.literal("appetizer"),
    v.literal("main"),
    v.literal("dessert")
  ),
  ingredients: v.array(v.string()),
  steps: v.array(v.string()),
});

export default defineSchema({
  recipes: Recipes.table.index("by_course", ["course"]),
});
```

 

The object returned by `Table` provides easy access to not only the table itself, which can then be passed to `defineSchema()`, but also the corresponding validators you’ve defined, with or without the system fields `_id` and `_creationTime` which are automatically added to the table’s documents:

```tsx
Recipes.table; // object returned by defineTable(), passed to defineSchema()
Recipes.withoutSystemFields; // the user-defined field validators
Recipes.withSystemFields; // those validators plus _id and _creationTime
Recipes.doc; // v.object() validator for the table's docs (incl. system fields)
```

These can be used as needed in your Convex functions. For example, for a `addRecipe` mutation that inserts a new document into the table, you can use `.withoutSystemFields` to validate the incoming table data:

```tsx
// convex/recipes.ts
import { mutation, action } from "./_generated/server";
import { Recipes } from "./schema";

export const addRecipe = mutation({
  args: Recipes.withoutSystemFields,
  handler: async (ctx, args) => {
    return await ctx.db.insert("recipes", args);
  },
});
```

When you need to pass a whole document in as a function argument, after getting it from the database,  `.doc` provides the corresponding object validator. For example, say you have a  `generateThumbnail` action to [generate an AI image](https://stack.convex.dev/using-dall-e-from-convex) based on a recipe document:

```tsx
// in convex/recipes.ts
import { action } from "./_generated/server";
import { internal } from "./_generated/api";

export const generateThumbnail = action({
  args: {
    recipe: Recipes.doc,
  },
  handler: async (ctx, args) => {
    const imgStorageId = await generateDallE(
      `A recipe named ${args.recipe.name} made with ` +
      args.recipe.ingredients.join(", ")
    );
    await ctx.runMutation(internal.recipes.addImage, { 
      recipeId: args.recipe._id,
      imgStorageId,
    });
  },
});
```

### `.doc` vs. `.withSystemFields`: A quick note on `v.object()`

While `.withSystemFields` is a regular old object (which just happens to have field names as keys and `Validator`s as values), `.doc` provides the `ObjectValidator` corresponding to the `.withSystemFields` object. 

In other words, `Recipes.doc` is equivalent to `v.object(Recipes.withSystemFields)`.  

```tsx
// To accept a whole document as an argument:
args: {
    recipe: Recipes.doc, // <- you can't pass Recipes.withSystemFields here, as each arg expects a validator, not an object
}

// To accept each of the fields as separate arguments:
args: Recipes.withSystemFields // <- you can't pass Recipes.doc here, as args expects an object, not a validator

```

You can use the `.doc` validator when passing entire documents as function arguments, and  `.withSystemFields`  when you need a JS object, for instance to destructure or spread arguments as described earlier. It’s currently not possible to “unwrap” a `v.object()` to get the individual field validators, though that might be supported in the future.

## Recap: DRY validators & types

With a few TS & JS builtins and `convex-helpers` utilities, you can streamline your argument validator definitions, minimizing repetition across your Convex codebase.

- Expose your tables’ field validators defined in `convex/schema.ts` for use in functions
- Use Convex generic types like `Doc` , and TS utility types like `Pick` & `Omit`, to get the (sub)sets of fields you need in TypeScript
- Use object destructuring & the rest operator (`...`) to get the (sub)sets of fields you need for argument validation in Convex functions
- Use the `Table` helper from `convex-helpers` for easy access to the defined table and the corresponding validators for its documents, with or without system fields

If you found these tips useful, or have any of your own you’d like to share with other developers in the Convex community, please jump on [Discord](https://www.convex.dev/community) and let us know!


A few more advanced techniques & helpers to further reduce duplication and accelerate your Convex workflow.

Argument Validation without Repetition

Tag along as WebDevCody participates in LearnWithJason's coding challenge where 4 developers use the same technologies to create the best project possible in 4 hours.

The most exciting 4 hour coding challenge

Want to use [Zod](https://zod.dev/) with your TypeScript project to validate function arguments? Read on to see how, along with resources to allow you to specify Zod validation for <QuickConvex /> server function arguments. Want to jump right into code? It’s [down here](#using-zod-for-argument-validation-server-side).

# What is Zod?

[Zod](https://zod.dev/) by their own definition is:

> TypeScript-first schema validation with static type inference
> 

It lets you define the format of data and validate it. It’s often used for form validation on a website or argument validation on a server. It can be used in JavaScript, but a big benefit comes from providing great TypeScript types to avoid duplicating a type definition from a validation specification. 

For terminology, I’m using the term “validate” here. They like to say “[parse, don’t validate](https://zod.dev/#:~:text=parse%2C%20don%27t%20validate),” but that nuance isn’t important to how we’ll talk about it.[^1] The important thing is you have:

[^1]: For those curious, the distinction they draw is that parsing returns data with the new type, whereas validation only checks the type of an object, which leaves the type unchanged from the language’s perspective.

```jsx
const untrustedData: any;
const trustedData = z.string().email().parse(untrustedData);
```

If your untrustedData is an email, hooray! You have a safe value to use. If not, it will throw a `ZodError` which, in the case of form validation, you can catch to inform the user which field is invalid.

## Why use Zod?

Zod allow you to:

- Validate types at runtime: remember that defining TypeScript types doesn’t guarantee that the values at runtime will match! Especially when receiving JSON payloads, it’s important to ensure the data matches your expectation.
- Avoid repeating type definitions and data validators.
- Do the same runtime validation on the client and server: doing it on the client allows you to give the user quick feedback, and doing it on the server guards against malformed requests and untrusted clients.

## How to use Zod

You can install Zod:

```bash
npm i zod
```

Then define your schema, like:

```jsx
const myData: z.object({
	email: z.string().email(),
  num: z.number().min(0),
  bool: z.boolean().default(false),
  array: z.array(z.string()),
  object: z.object({ a: z.string(), b: z.number() }),
  union: z.union([z.string(), z.number()]),
});
```

And parse (validate) the data:

```jsx
// Throws when the data is invalid
const result = myData.parse(untrustedData);
// Returns an error object instead
const { success, error, data } = myData.safeParse(untrustedData);
```

# Using Zod for argument validation server-side

When you want to validate your endpoint’s arguments, you can do it manually on the data passed in by your framework. However, it’s more powerful to expose this data, so it can also inform end-to-end type safety, for instance with tRPC or <QuickConvex />.

## Using Zod with tRPC

For tRPC projects, you can provide a Zod object to `.input`:

```jsx
const t = initTRPC.create();
 
const appRouter = t.router({
  greeting: t.publicProcedure
    .input(z.object({ name: z.string() }))
    .query((opts) => {
      const { input } = opts;
      return `Hello ${input.name}`;
  }),
});
```

## Using Zod with Convex

With Convex, argument validation is usually done with the same validators used to define your [database schema](https://docs.convex.dev/database/schemas) (note the `v` instead of `z`!):

```jsx
export const greeting = query({
  args: { name: v.string() },
  handler: async (ctx, args) => {
    return `Hello ${args.name}`;
  }
});
```

However, if you’re already using Zod elsewhere in your project, or want to validate more refined types, wouldn’t it be nice to validate your arguments with the same object? To make this possible, I wrote some helpers.

```bash
npm i convex-helpers@latest
```

These build off of [this post](https://stack.convex.dev/custom-functions) where I show how to customize functions generally. See that post for the details on the API and why it’s preferable to typical middleware.

If you aren’t doing any customization and just want to use Zod arguments, you can use the functions exported from `convex-helpers/server/zod`:

```jsx
import { z } from "zod";
import { NoOp } from "convex-helpers/server/customFunctions";
import { zCustomQuery } from "convex-helpers/server/zod";
import { query } from "./_generated/server";

// Make this once, to use anywhere you would have used `query`
const zQuery = zCustomQuery(query, NoOp);

export const greeting = zQuery({
  args: { name: z.string() },
  handler: async (_ctx, args) => {
    return `Hello ${args.name}`;
  },
});
```

Let’s walk through what’s happening:

1. First we make `zQuery`, which is like `query` but modified by `zCustomQuery` to accept Zod arguments, along with any customization you provide in the second argument. We’re passing `NoOp` which doesn’t modify the defined query endpoint’s arguments (a.k.a. no-op or identity function).
2. We use `zQuery` like we’d normally use `query` , but this time we get to pass in zod validators for arguments.

Internally, this does two things:

1. It turns the Zod validator into a Convex validator using `zodToConvex`. This allows Convex to know generally what types the function expects (which helps suggest arguments when you [run your functions from the Dashboard](https://docs.convex.dev/dashboard/deployments/functions#running-functions)). This also allows Convex to validate the `v.id("tablename")` type, which ensures IDs match the expected table name.
2. It runs the Zod validator before the function runs, since Zod types can be more specific than Convex types (e.g. `z.string().email()` vs. `v.string()`).

<BuildWithConvex />

## `v.id(tablename)` → `zid(tablename)`

When you want to validate a [Convex Document ID](https://docs.convex.dev/database/document-ids), since Zod doesn’t have a built-in type, you can use `zid`:

```jsx
...
import { zCustomQuery, zid } from "convex-helpers/server/zod";

const zQuery = zCustomQuery(query, NoOp)

export const getUser = zQuery({
  args: {userId: zid("users")},
  handler: async (ctx, args) => {
    const user = await ctx.db.get(args.userId);
    return user && { id: user._id, name: user.name };
  },
});
```

This creates a `v.id` validator under the hood, which ensures you don’t return data from the wrong table if someone passes an ID to another table to `getUser`.

However, note that `zid` doesn’t do the table name validation when you do `.parse()`. It does this by converting it into a `v.id` which is passed to the Convex argument validation. So keep in mind that if you’re validating a `zid` in a browser, it will only check that it is a string.

## Output validation

In addition to validating function inputs, you can also use Zod to validate the output data, similar to defining an explicit TypeScript return type on your function. While this is less critical, since the data you return is generally more trusted than what’s provided by a user, it does have a nice benefit of ***limiting*** what you return. If your return TypeScript type is `{ name: string }` and you return a `User: { name: string, email: string }`, then TypeScript will say it’s ok, but you would be leaking the user’s email, since TypeScript’s typing on objects isn’t exact. By specifying a Zod validator for your output, it will both set the TypeScript return type, but also strip out fields that you don’t specify. For example:

```jsx
const user = { name: "Sam", email: "sam@example.com" };
const output = z.object({ name: z.string() });
const limited = output.parse(user);
console.log(limited)
// { name: 'Sam' }
```

To do this you could just do it in your function:

```jsx
export const getUser = zQuery({
  args: {userId: zid("users")},
  handler: async (ctx, args) => {
    const user = (await ctx.db.get(args.userId))!;
    const output = z.object({ name: z.string() });
    return output.parse(user);
  },
});
```

But with the `zCustomQuery` , `zCustomMutation`, or `zCustomAction`, you can specify it like:

```jsx
export const getUser = zQuery({
  args: {userId: zid("users")},
  handler: async (ctx, args) => {
    const user = (await ctx.db.get(args.userId))!;
    return user;
  },
  output: z.object({ name: z.string() }),
});
```

Note: `zid` won’t do table name validation on return types at this time.

## Customizing the function

Similar to [`customFunctions` described here](https://stack.convex.dev/custom-functions), you can customize `zCustomFunction`.

Here we modify the `ctx` object passed into `greeting`:

```jsx
import { z } from "zod";
import { customCtx } from "convex-helpers/server/customFunctions";
import { zCustomQuery } from "convex-helpers/server/zod";
import { query } from "./_generated/server";
import { getUser } from "./users";

const userQuery = zCustomQuery(
  query,
  customCtx(async (ctx) => {
    const user = await getUser(ctx);
    return { user };
  })
);

export const greeting = userQuery({
  args: { greeting: z.string() },
  handler: async (ctx, args) => {
    return `${args.greeting} ${ctx.user.name}`;
  },
});
```

Here we add `session` to the `ctx` , stripping off `sessionId` from the arguments:

```jsx
const zQuery = zCustomQuery(query, {
  args: { sessionId: v.id("sessions") },
  input: async (ctx, args) => {
    const session = await ctx.db.get(args.sessionId);
    return { ctx: { ...ctx, session }, args: {} };
  },
});
```

Note: we use normal Convex validators (`v.`) for the customization, so it is easy to extend behavior with helpers that don’t use Zod.

## Error handling

If an error occurs, it will throw a [`ConvexError`](https://docs.convex.dev/functions/error-handling/application-errors#throwing-application-errors) with `{ ZodError }` as the data. This allows you to inspect the full error object on the client-side, without leaking the server’s stack trace.

## Can I use Zod to define my database types too?

With the `zodToConvex` function, you can turn your Zod validators into Convex types that not only work in argument validation, but also can be used to define tables (via `defineTable`, see [here](https://docs.convex.dev/database/schemas)). Is this a good idea? It depends. 

The data at rest is guaranteed to match the defined schema (assuming you have [schema enforcement turned on](https://docs.convex.dev/database/schemas#options)). However, if your Zod type is more refined (like a `z.string().email()`), then there isn’t a guarantee that the data at rest matches it. For some types, like `z.tuple`, the definition looks more like `z.array(z.union([...]))`. 

### So what can you do?

- You can wrap `ctx.db` in mutations to validate the more specific data types before writing data, using a wrapper like `convex-helpers/server/rowLevelSecurity`. This can ensure the **new** data you’re writing is the right format.
- You can wrap `ctx.db` in queries & mutations to validate the data on reads. This will ensure the data you retrieve is the right format. It’s an open question how you should handle invalid data on reads. If you change your schema and read an old invalid value, you could fail the request, omit the result, or try to transform it into the right shape. This is pretty messy.
- You can run a migration over your data, validating the Zod schema when you change it. Similar to other migrations, I’d suggest first changing the data writers to validate on insert, then run a migration over older documents and manually resolve errors.

Note: if a developer edits data in the dashboard or uploads data via the CLI, your validators won’t run. The validation here is best effort, and up to you. 

### What would I do?

I’d use Zod validation for server arguments, and trust that the server code will write valid data. If it’s very important, I’d consolidates those writes to a function where I manually validate the data & business logic before writing it. If your server is modifying a lot of data that needs to be a certain shape, consider validating it right there. If I had more specific types that I expect from the data (e.g. z.tuple), I’d use Zod on the read side to give better types while asserting the structure. 

I might use `zodToConvex` to define the table schema from the Zod types, but I’d add a big comment block making it clear that the validation isn’t guaranteed. I do like that my table definition would be more self-documenting. An `.email()` is more meaningful than `v.string()`.

# In summary

We looked at using Zod to validate function arguments (and more) to provide both type safety and runtime data validation for your TypeScript projects. By using `convex-helpers` you can validate your Convex functions, and translate from a Zod schema to a Convex validator. If you want to see the code, you can check it out / fork it / submit a PR here:

<GitHubRepo url="https://github.com/get-convex/convex-helpers" />


Use Zod with TypeScript for argument validation on your server functions allows you to both protect against invalid data, and define TypeScript types that propagate to your client. This can now be used as an alternative to the built-in argument validation on Convex.

Zod with TypeScript for Server-side Validation and End-to-End Types

As you become a seasoned Convex developer, you’ll see first-hand how fantastic the developer experience becomes when you’ve got types on your side. The end-to-end TypeScript as you build, and the consistency and security you get from Convex [schema enforcement](https://docs.convex.dev/database/schemas#validators) and [argument validation](https://docs.convex.dev/functions/args-validation) at runtime give you the tools to develop safely with types to help catch bugs early.

However, if you don’t know some of the tricks we’ll show you, your code may feel cumbersome to write. For example, say you’re building a cookbook app and have defined a `recipes` table in your schema. You specify the table’s fields using validators accessed from the `v` object exposed by `convex/values`: 

```tsx
// convex/schema.ts
import { v } from "convex/values";
import { defineSchema, defineTable } from "convex/server";

export default defineSchema({
  recipes: defineTable({
    name: v.string(),
		course: v.union(
			v.literal('appetizer'), 
			v.literal('main'),
			v.literal('dessert')
		),
		ingredients: v.array(v.string()),
		steps: v.array(v.string())
  }).index("by_course", ["course"]),
});
```

Your function to add a new recipe argument validators might look like:

```tsx
// in convex/recipes.ts
import { v } from "convex/values";
import { mutation } from "./_generated/server";

export const addRecipe = mutation({
  args: {
    name: v.string(),
		course: v.union(
			v.literal('appetizer'), 
			v.literal('main'),
			v.literal('dessert')
		),
		ingredients: v.array(v.string()),
		steps: v.array(v.string()),
  },
  handler: async (ctx, args) => {
    return await ctx.db.insert("recipes", args);
  },
});
```

And for a regular TypeScript function, you might find yourself defining types like:

```tsx
type Course = 'appetizer' | 'main' | 'dessert';

type Recipe = {
	name: string,
	course: Course,
	ingredients: string[],
	steps: string[],
};

async function getIngredientsForCourse(recipes: Recipe[], course: Course) {
   ...
}
```

As you can see, you may get frustrated repeatedly defining the same validators in your schema and functions, and redeclaring similar TypeScript types in different parts of your codebase. Is there a better way? Yes!

The Convex Test Kitchen has cooked up some convenient recipes for busy fullstack chefs like you! Keep these tasty typing tricks at hand, and you’ll be whipping up the types & validators you need in no time - without any cookie-cutter repetition.

## Dish out types from your `DataModel` with `Doc` and `Id`

Once you’ve [defined a schema](https://docs.convex.dev/database/schemas) for your database (or [generated](https://docs.convex.dev/dashboard/deployments/data#generating-a-schema) one from existing data), Convex will serve up your data types on a silver platter! 

Convex code generation automatically creates types for all the documents in your tables, exposed via the `Doc<"tablename">` generic type from `convex/_generated/dataModel`. The data model also exposes an `Id<"tablename">` generic type corresponding to a valid [document ID](https://docs.convex.dev/database/document-ids) for a given table. Use these types to ensure the rest of your codebase uses data consistent with your schema:

```tsx
// in src/Cookbook.tsx
import { useQuery } from "convex/react";
import { api } from "../convex/_generated/api";
import type { Doc, Id } from "../convex/_generated/dataModel";

export function Cookbook() {
  const recipes = useQuery(api.recipes.list);
  return recipes?.map((r) => <RecipePreview recipe={r} />);
}

export function RecipePreview({ recipe }: { recipe: Doc<"recipes"> }) {
  return (
    <div>
      {recipe.name} ({recipe.course})
    </div>
  );
}

function RecipeDetails({ id }: { id: Id<"recipes"> }) {
  const recipe = useQuery(api.recipes.getById, { id });

  return (recipe && (
    <div>
      <h1>{recipe.name}</h1>
      <h2>{recipe.course}</h2>
      <ShoppingList ingredients={recipe.ingredients} />
      <Instructions steps={recipe.steps} />
    </div>
  ));
}
```

This `Id<"tablename">` type corresponds to values accepted by `v.id("tablename")` :

```tsx
// in convex/recipes.ts
import { v } from "convex/values";
import { query } from "./_generated/server";

export const getById = query({
  args: {
    id: v.id("recipes"),
  },
  handler: async (ctx, args) => {
    return await ctx.db.get(args.id);
  },
});
```

## Keep validators from going stale

As we’ve seen, the `v` validators are used not only in your schema but also to [validate arguments](https://docs.convex.dev/functions/args-validation) passed in to your Convex functions. If all you need is a single [`v.id`](http://v.id) that’s no sweat, but what about when arguments should match your schema definitions? For example:

```tsx
// in convex/recipes.ts
import { query } from "./_generated/server";
import { v } from "convex/values";

export const listByCourse = query({
  args: {
    course: v.union(
			v.literal("appetizer"), 
			v.literal("main"),
			v.literal("dessert")
		),
  },
  handler: async (ctx, args) => {
    return await ctx.db.query("recipes")
			.withIndex("by_course", (q) => q.eq("course", args.course))
			.collect();
  },
});
```

This doesn’t smell so good; it duplicates the `course` validator from your schema, which means not only did you have to repeat yourself (ugh), you also gave yourself the burden to remember to update this function whenever you update your schema (double ugh)!

To keep arguments in sync with schema changes, refactor `convex/schema.ts` to first define and export your field validators, then use them to define your tables:

```tsx
// convex/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export const courseValidator = v.union(
	v.literal('appetizer'), 
	v.literal('main'),
	v.literal('dessert')
);

export default defineSchema({
  recipes: defineTable({
	  name: v.string(),
	  course: courseValidator,
	  ingredients: v.array(v.string()),
	  steps: v.array(v.string()),
	}).index("by_course", ["course"]),
});
```

Now you can reuse those validators in your Convex functions as needed:

```tsx
// in convex/recipes.ts
import { query } from "./_generated/server";
import { courseValidator } from "convex/schema.ts";

export const listByCourse = query({
  args: {
    course: courseValidator
  },
  handler: async (ctx, args) => {
    return await ctx.db.query("recipes")
			.withIndex("by_course", (q) => q.eq("course", args.course)
			.collect();
  },
});
```

This keeps data consistent throughout your entire backend. 

Pro tip: once you get the hang of this pattern, you might drop the "Validator," just "course" - it's cleaner.

But how can you make sure that other parts of your codebase, say, your frontend UI, are using TypeScript types that match those validators?

## Add a drop of ~~vanilla~~ TypeScript extract

For exactly that purpose, `convex.values` also provides a handy `Infer` type that lets you [extract TS types from your validators](https://docs.convex.dev/functions/args-validation#extracting-typescript-types):  

```tsx
// in convex/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v, Infer } from "convex/values";

export const courseValidator = v.union(
  v.literal('appetizer'), 
  v.literal('main'),
  v.literal('dessert')
);
export type Course = Infer<typeof courseValidator>;

// ...
```

You can expose the extracted types for use in other parts of your codebase: 

```tsx
// in src/Menu.tsx
import { useState } from "react";
import type { Course } from '../convex/schema.ts';

export default function Menu() {
  const [course, setCourse] = useState<Course>('main');

  // Then, in response to some user input...
  setCourse('side dish'); // TS error: invalid Course!
  // ...
}
```

## Sift out the system fields

The generated `Doc` type seen earlier includes the “system fields” automatically added by Convex to every document: `_id` and `_creationTime`. But often, for example when creating a new document, you want to make sure those fields aren’t included in your data. The `"convex/server"` module provides a handy `WithoutSystemFields<document>` generic type for just such a situation:

```tsx
// in src/NewRecipePage.tsx

import { api } from "../convex/_generated/api";
import type { Doc } from "../convex/_generated/dataModel";
import type { WithoutSystemFields } from "convex/server";

export function SaveRecipeButton({ recipeData }: 
	{ recipeData: WithoutSystemFields<Doc<"recipes">> }
) {
  const createRecipe = useMutation(api.recipes.create);
  return (
    <button onClick={() => createRecipe(recipeData)}>
      Save recipe
    </button>
  );
}
```

But what about the corresponding argument validator? Rather than redefine the same shape of data that you’ve already defined in your schema, you can refactor your schema to export an object with the field validators for a given table, and import that object for use in your functions:

```tsx
// in convex/schema.ts
// ...
export const recipeFields = {
  name: v.string(),
  course: courseValidator,
  ingredients: v.array(v.string()),
  steps: v.array(v.string()),
};

export default defineSchema({
  recipes: defineTable(recipeFields)
    .index("by_course", ["course"]),
});
```

```tsx
// in convex/recipes.ts
// ...
import { recipeFields } from "./schema";

export const addRecipe = mutation({
  args: recipeFields,
  handler: async (ctx, args) => {
    return await ctx.db.insert("recipes", args);
  },
});
```

No repetition needed, and any changes to the shape of the `recipes` table will percolate automatically from `schema.ts`. Now we’re cooking! By the way, if you like this pattern, you’ll probably like Ian’s `Table` utility in the convex-helpers npm package - post on it coming soon.

## Boiling it all down

To recap, with a little bit of reorganization your Convex codebase can be sweeter than ever, with no repetition or risk of stale data shapes! 

- In `schema.ts` , define and export your document fields and their validators separately, then pass them in to `defineTable()`
- In your Convex functions, validate arguments with the imported validators from your schema instead of repeating yourself
- In your frontend, use Convex-generated types `Doc<table>` and `Id<table>`, along with type utilities like `Infer<validator>` and `WithoutSystemFields<doc>`to convert your schema-defined validators to the TypeScript types you need

Hungry for more tidbits like this to help manage, modify, and manipulate your types and validators? Stay tuned for more recipes in the next post in this series!

It can be tough to wrangle types to behave how you want them to. Thankfully, Convex was designed to make the experience with types perfect. Learn why that's the case here.

Types and Validators in TypeScript: A Convex Cookbook

Convex provides automatic type safety all the way from your database schema to your React app. How does it work? Hint: we use some wild TypeScript.