Getting the typescript type for a table

[pliant salmon]

How can I get the typescript type for one of my tables in my schema?

[timid sky]

Hi @pliant salmon. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

To get the TypeScript type for a table in your Convex schema, you can use the Doc type from the generated data model. Here's how to do it:

Using the Doc Type

Once you've defined a schema for your database, Convex automatically generates TypeScript types for all your tables. You can access these types using the Doc<"tablename"> generic type:

import { Doc } from "../convex/_generated/dataModel";

// Now you can use the type in your components or functions
function RecipeComponent({ recipe }: { recipe: Doc<"recipes"> }) {
  // TypeScript knows the shape of your recipe document
  return <div>{recipe.name}</div>;
}

The Doc type provides the complete document type for a specific table, including all fields defined in your schema Stack: Types and Validators in TypeScript: A Convex Cookbook.

When to Use This

This is particularly useful when:

1. Defining component props that receive documents from your database
2. Working with query results in your frontend
3. Typing variables in your Convex functions

Example with a Complete Workflow

1. First, define your schema:

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

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

2. Run npx convex dev to generate the type definitions

3. Now you can use the Doc type in your components or functions:

import { Doc } from "../convex/_generated/dataModel";

// In a React component
function RecipeDetails({ recipe }: { recipe: Doc<"recipes"> }) {
return (
<div>
<h1>{recipe.name}</h1>
<h2>{recipe.course}</h2>
<ul>
{recipe.ingredients.map((ingredient, i) => (
<li key={i}>{ingredient}</li>
))}
</ul>
</div>
);
}

This approach ensures end-to-end type safety throughout your application [Stack: End-to-end TypeScript with Convex](<https://stack.convex.dev/end-to-end-ts#the-developer-experience>).
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------

@pliant salmon Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[pliant salmon]

can i also get a subtype, such as the type for course @timid sky

[timid sky]

Let me check the knowledge base for you again. One moment! :books:

---

Yes, you can definitely get a subtype for a specific field like "course" from your Convex schema. There are several approaches to do this:

Using Infer with Validators

If you've defined validators for your fields, you can extract TypeScript types directly from them using the Infer type:

// in convex/schema.ts
import { v, Infer } from "convex/values";

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

// Extract the type from the validator
export type Course = Infer<typeof courseValidator>;
// This will be inferred as 'appetizer' | 'main' | 'dessert'

You can then import and use this type anywhere in your codebase Stack: Types and Validators in TypeScript: A Convex Cookbook.

Using TypeScript Utility Types

If you already have the Doc type for your table, you can use TypeScript's utility types to extract just the type of a specific field:

import { Doc } from "../convex/_generated/dataModel";

// Extract just the type of the "course" field
type Course = Doc<"recipes">["course"];

Or if you need multiple specific fields, you can use Pick:

// Get only the name and course fields
type RecipeSummary = Pick<Doc<"recipes">, "name" | "course">;

This approach is particularly useful when you need to work with specific subsets of your document types Stack: Argument Validation without Repetition.

The first approach (using Infer) is generally preferred when you're defining reusable validators, as it ensures your TypeScript types stay in sync with your runtime validators.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@pliant salmon Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[pliant salmon]

how can i get the validator object for the course? @timid sky

[timid sky]

Let me check the knowledge base for you again. One moment! :books:

---

To get the validator object for a specific field like "course" from your Convex schema, you can extract and export it directly from your schema definition. Here are the approaches:

Export Field Validators Directly

The most straightforward approach is to define and export your validators separately in your schema file:

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

// Define and export the validator
export const courseValidator = v.union(
  v.literal('appetizer'), 
  v.literal('main'),
  v.literal('dessert')
);

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

Then you can import and use this validator in your functions:

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

export const listByCourse = query({
  args: {
    course: courseValidator // Reuse the validator
  },
  handler: async (ctx, args) => {
    // ...
  }
});

This approach keeps your validators DRY and ensures consistency Stack: Types and Validators in TypeScript: A Convex Cookbook.

Export All Field Validators as an Object

Another approach is to define all your field validators as an object and export it:

// 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"]),
});

Then you can access the specific validator:

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

// Get just the course validator
const { course } = recipeFields;

This approach is particularly useful when you need to work with multiple fields Stack: Argument Validation without Repetition.

Using the Table Helper

For a more structured approach, you can use the Table helper from convex-helpers:

// convex/schema.ts
import { defineSchema } 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"]),
});

Then you can access individual validators through object destructuring:

// in convex/recipes.ts
import { Recipes } from "./schema";

// Get just the course validator
const { course } = Recipes.withoutSystemFields;

This approach provides additional utilities for working with your schema Stack: Argument Validation without Repetition.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@pliant salmon Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[pliant salmon]

how can i get it for the args of a mutation? @timid sky

[timid sky]

Let me check the knowledge base for you again. One moment! :books:

---

I'll explain how to get validators for the arguments of a Convex mutation.

Using Validators in Mutations

When defining a mutation in Convex, you can specify argument validators in the args property. Here are several approaches to reuse validators for mutation arguments:

1. Import Field Validators Directly

If you've exported individual field validators from your schema, you can import and use them:

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

export const updateCourse = mutation({
  args: {
    id: v.id("recipes"),
    course: courseValidator
  },
  handler: async (ctx, args) => {
    await ctx.db.patch(args.id, { course: args.course });
  }
});

2. Use Exported Field Objects

If you've exported all field validators as an object, you can destructure what you need:

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

// Destructure to get just what you need
const { course } = recipeFields;

export const updateCourse = mutation({
  args: {
    id: v.id("recipes"),
    course
  },
  handler: async (ctx, args) => {
    await ctx.db.patch(args.id, { course: args.course });
  }
});

This approach lets you pick specific validators from your schema Stack: Argument Validation without Repetition.

3. Using the Table Helper

If you're using the Table helper from convex-helpers:

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

export const updateRecipe = mutation({
args: {
id: v.id("recipes"),
// Get just the course field
course: Recipes.withoutSystemFields.course
},
handler: async (ctx, args) => {
await ctx.db.patch(args.id, { course: args.course });
}
});

// Or use the entire object for creating a new recipe
export const addRecipe = mutation({
args: Recipes.withoutSystemFields,
handler: async (ctx, args) => {
return await ctx.db.insert("recipes", args);
}
});

The `Table` helper provides convenient access to your field validators with or without system fields [Stack: Argument Validation without Repetition](<https://stack.convex.dev/argument-validation-without-repetition#table-helper-for-schema-definition--validation>).

These approaches ensure your mutations use the same validation logic as your schema, keeping your codebase DRY and consistent.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------

@pliant salmon Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[pliant salmon]

i want to do something similar to Infer but for the args of the schema @timid sky

[timid sky]

Let me check the knowledge base for you again. One moment! :books:

---

I understand you want to extract TypeScript types from your schema validators, similar to how Infer works but specifically for schema fields. There are a few approaches to accomplish this:

Using Infer with Schema Field Validators

You can use the Infer type utility with your exported schema field validators:

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

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

// Export the fields object
export const recipeFields = {
  name: v.string(),
  course: courseValidator,
  ingredients: v.array(v.string()),
  steps: v.array(v.string()),
};

// Define your schema using these fields
export default defineSchema({
  recipes: defineTable(recipeFields).index("by_course", ["course"]),
});

// Extract types from validators
export type Course = Infer<typeof courseValidator>;
export type RecipeFields = {
  name: Infer<typeof recipeFields.name>;
  course: Infer<typeof recipeFields.course>;
  ingredients: Infer<typeof recipeFields.ingredients>;
  steps: Infer<typeof recipeFields.steps>;
};

This approach lets you extract types from your validators that can be used throughout your codebase Stack: Types and Validators in TypeScript: A Convex Cookbook.

Using ObjectType for Object Validators

For object validators, you can use the ObjectType utility type:

import { v, Infer, ObjectType } 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()),
};

// Extract the type from the entire object validator
export type RecipeFields = ObjectType<typeof recipeFields>;

The `ObjectType` utility computes the type of an object from `PropertyValidators` [Convex API: Module values](<https://docs.convex.dev/api/modules/values#objecttype>).

## Using `WithoutSystemFields` for Document Types

If you want to get the type of a document without system fields (for insert/update operations):

```typescript
import { WithoutSystemFields } from "convex/server";
import { Doc } from "./_generated/dataModel";

// Type for creating/updating a recipe (without _id and _creationTime)
export type RecipeInput = WithoutSystemFields<Doc<"recipes">>;

This is particularly useful when creating helper functions for database operations Understanding Best Practices: TypeScript.

These approaches give you type-safe ways to work with your schema definitions throughout your application, ensuring consistency between your validators and TypeScript types.

Would you like me to explain any of these approaches in more detail?

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: