function-creator

Convex Function Creator

Generate secure, type-safe Convex functions following all best practices.

When to Use

• Creating new query functions (read data)
• Creating new mutation functions (write data)
• Creating new action functions (external APIs, long-running)
• Adding API endpoints to your Convex backend

Function Types

Queries (Read-Only)

• Can only read from database
• Cannot modify data or call external APIs
• Cached and reactive
• Run in transactions

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

export const getTask = query({
  args: { taskId: v.id('tasks') },
  returns: v.union(
    v.object({
      _id: v.id('tasks'),
      text: v.string(),
      completed: v.boolean(),
    }),
    v.null(),
  ),
  handler: async (ctx, args) => {
    return await ctx.db.get(args.taskId)
  },
})

Mutations (Transactional Writes)

• Can read and write to database
• Cannot call external APIs
• Run in ACID transactions
• Automatic retries on conflicts

import { mutation } from './_generated/server'
import { v } from 'convex/values'

export const createTask = mutation({
  args: {
    text: v.string(),
    priority: v.optional(
      v.union(v.literal('low'), v.literal('medium'), v.literal('high')),
    ),
  },
  returns: v.id('tasks'),
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity()
    if (!identity) throw new Error('Not authenticated')

    return await ctx.db.insert('tasks', {
      text: args.text,
      priority: args.priority ?? 'medium',
      completed: false,
      createdAt: Date.now(),
    })
  },
})

Actions (External + Non-Transactional)

• Can call external APIs (fetch, AI, etc.)
• Can call mutations via ctx.runMutation
• Cannot directly access database
• No automatic retries
• Use "use node" directive when needing Node.js APIs

Important: If your action needs Node.js-specific APIs (crypto, third-party SDKs, etc.), add "use node" at the top of the file. Files with "use node" can ONLY contain actions, not queries or mutations.

'use node' // Required for Node.js APIs like OpenAI SDK

import { action } from './_generated/server'
import { api } from './_generated/api'
import { v } from 'convex/values'
import OpenAI from 'openai'

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })

export const generateTaskSuggestion = action({
  args: { prompt: v.string() },
  returns: v.string(),
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity()
    if (!identity) throw new Error('Not authenticated')

    // Call OpenAI (requires "use node")
    const completion = await openai.chat.completions.create({
      model: 'gpt-4',
      messages: [{ role: 'user', content: args.prompt }],
    })

    const suggestion = completion.choices[0].message.content

    // Write to database via mutation
    await ctx.runMutation(api.tasks.createTask, {
      text: suggestion,
    })

    return suggestion
  },
})

Note: If you only need basic fetch (no Node.js APIs), you can omit "use node". But for third-party SDKs, crypto, or other Node.js features, you must use it.

Required Components

1. Argument Validation

Always define args with validators:

args: {
  id: v.id("tasks"),
  text: v.string(),
  count: v.number(),
  enabled: v.boolean(),
  tags: v.array(v.string()),
  metadata: v.optional(v.object({
    key: v.string(),
  })),
}

2. Return Type Validation

Always define returns:

returns: v.object({
  _id: v.id('tasks'),
  text: v.string(),
})

// Or for arrays
returns: v.array(
  v.object({
    /* ... */
  }),
)

// Or for nullable
returns: v.union(
  v.object({
    /* ... */
  }),
  v.null(),
)

3. Authentication Check

Always verify auth in public functions:

const identity = await ctx.auth.getUserIdentity()
if (!identity) {
  throw new Error('Not authenticated')
}

4. Authorization Check

Always verify ownership/permissions:

const task = await ctx.db.get(args.taskId)
if (!task) {
  throw new Error('Task not found')
}

if (task.userId !== user._id) {
  throw new Error('Unauthorized')
}

Complete Examples

Secure Query with Auth

export const getMyTasks = query({
  args: {
    status: v.optional(v.union(v.literal('active'), v.literal('completed'))),
  },
  returns: v.array(
    v.object({
      _id: v.id('tasks'),
      text: v.string(),
      completed: v.boolean(),
    }),
  ),
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity()
    if (!identity) throw new Error('Not authenticated')

    const user = await ctx.db
      .query('users')
      .withIndex('by_token', (q) =>
        q.eq('tokenIdentifier', identity.tokenIdentifier),
      )
      .unique()

    if (!user) throw new Error('User not found')

    let query = ctx.db
      .query('tasks')
      .withIndex('by_user', (q) => q.eq('userId', user._id))

    const tasks = await query.collect()

    if (args.status) {
      return tasks.filter((t) =>
        args.status === 'completed' ? t.completed : !t.completed,
      )
    }

    return tasks
  },
})

Secure Mutation with Validation

export const updateTask = mutation({
  args: {
    taskId: v.id('tasks'),
    text: v.optional(v.string()),
    completed: v.optional(v.boolean()),
  },
  returns: v.id('tasks'),
  handler: async (ctx, args) => {
    // 1. Authentication
    const identity = await ctx.auth.getUserIdentity()
    if (!identity) throw new Error('Not authenticated')

    // 2. Get user
    const user = await ctx.db
      .query('users')
      .withIndex('by_token', (q) =>
        q.eq('tokenIdentifier', identity.tokenIdentifier),
      )
      .unique()

    if (!user) throw new Error('User not found')

    // 3. Get resource
    const task = await ctx.db.get(args.taskId)
    if (!task) throw new Error('Task not found')

    // 4. Authorization
    if (task.userId !== user._id) {
      throw new Error('Unauthorized')
    }

    // 5. Update
    const updates: Partial<typeof task> = {}
    if (args.text !== undefined) updates.text = args.text
    if (args.completed !== undefined) updates.completed = args.completed

    await ctx.db.patch(args.taskId, updates)
    return args.taskId
  },
})

Action Calling External API

Create separate file for actions that need Node.js:

// convex/taskActions.ts
'use node' // Required for SendGrid SDK

import { action } from './_generated/server'
import { api } from './_generated/api'
import { v } from 'convex/values'
import sendgrid from '@sendgrid/mail'

sendgrid.setApiKey(process.env.SENDGRID_API_KEY)

export const sendTaskReminder = action({
  args: { taskId: v.id('tasks') },
  returns: v.boolean(),
  handler: async (ctx, args) => {
    // 1. Auth
    const identity = await ctx.auth.getUserIdentity()
    if (!identity) throw new Error('Not authenticated')

    // 2. Get data via query
    const task = await ctx.runQuery(api.tasks.getTask, {
      taskId: args.taskId,
    })

    if (!task) throw new Error('Task not found')

    // 3. Call external service (using Node.js SDK)
    await sendgrid.send({
      to: identity.email,
      from: 'noreply@example.com',
      subject: 'Task Reminder',
      text: `Don't forget: ${task.text}`,
    })

    // 4. Update via mutation
    await ctx.runMutation(api.tasks.markReminderSent, {
      taskId: args.taskId,
    })

    return true
  },
})

Note: Keep queries and mutations in convex/tasks.ts (without "use node"), and actions that need Node.js in convex/taskActions.ts (with "use node").

Internal Functions

For backend-only functions (called by scheduler, other functions):

import { internalMutation } from './_generated/server'

export const processExpiredTasks = internalMutation({
  args: {},
  handler: async (ctx) => {
    // No auth needed - only callable from backend
    const now = Date.now()
    const expired = await ctx.db
      .query('tasks')
      .withIndex('by_due_date', (q) => q.lt('dueDate', now))
      .collect()

    for (const task of expired) {
      await ctx.db.patch(task._id, { status: 'expired' })
    }
  },
})

Checklist

• [ ] args defined with validators
• [ ] returns defined with validator
• [ ] Authentication check (ctx.auth.getUserIdentity())
• [ ] Authorization check (ownership/permissions)
• [ ] All promises awaited
• [ ] Indexed queries (no .filter() on queries)
• [ ] Error handling with descriptive messages
• [ ] Scheduled functions use internal.* not api.*
• [ ] If using Node.js APIs: "use node" at top of file
• [ ] If file has "use node": Only actions (no queries/mutations)
• [ ] Actions in separate file from queries/mutations when using "use node"