convex-review

name	convex-review
description	Comprehensive Convex code review checklist for production readiness. Use when auditing a Convex codebase before deployment, reviewing pull requests, or checking for security and performance issues in Convex functions.

Convex Code Review

Security Checklist

1. Argument AND Return Validators

• All public query, mutation, action have args validators
• All functions have returns validators
• No v.any() for sensitive data
• HTTP actions validate request body (Zod recommended)

Search: query({, mutation({, action({ - check each has args: AND returns:

2. Error Handling

• Uses ConvexError for user-facing errors (not plain Error)
• Error codes are structured: { code: "NOT_FOUND", message: "..." }
• No sensitive info leaked in error messages

Search: throw new Error should be throw new ConvexError

3. Access Control

• All public functions check ctx.auth.getUserIdentity() where needed
• Uses auth helpers (requireAuth, requireRole)
• No client-provided email/username for authorization
• Row-level access verified (ownership checks)

Search: ctx.auth.getUserIdentity should appear in most public functions

4. Internal Functions

• ctx.runQuery, ctx.runMutation, ctx.runAction use internal.* not api.*
• ctx.scheduler.runAfter uses internal.* not api.*
• Crons in crons.ts use internal.* not api.*

Search: api. in convex directory - should not be used for scheduling/running

5. Table Names in DB Calls

• All ctx.db.get, patch, replace, delete include table name as first arg

Search: db.get(, db.patch( - first arg should be quoted string

Performance Checklist

6. Database Queries

• No .filter() on queries (use .withIndex() or filter in code)
• .collect() only with bounded results (<1000 docs)
• Pagination for large result sets

Search: \.filter\(\(?q, \.collect\(

7. Indexes

• No redundant indexes (by_foo + by_foo_and_bar)
• All filtered queries use .withIndex()
• Index names include all fields

Review: schema.ts index definitions

8. Date.now() in Queries

• No Date.now() in query functions
• Time filtering uses boolean fields or client-passed timestamps

9. Promise Handling

• All promises awaited (ctx.scheduler, ctx.db.*)

ESLint: no-floating-promises

Architecture Checklist

10. Action Usage

• Actions have "use node"; if using Node.js APIs
• ctx.runAction only when switching runtimes
• No sequential ctx.runMutation/ctx.runQuery (combine for consistency)

11. Code Organization

• Business logic in helper functions (convex/model/)
• Public API handlers are thin wrappers
• Auth helpers in convex/lib/auth.ts

12. Transaction Consistency

• Related reads in same query/mutation
• Batch operations in single mutation
• Mutations are idempotent

Quick Regex Searches

Issue	Regex	Fix
.filter()	\.filter\(\(?q	Use .withIndex()
Missing returns	handler:.*async without returns:	Add returns:
Plain Error	throw new Error\(	Use ConvexError
Missing table name	db\.(get|patch)\([^"']	Add table name
Date.now() in query	Date\.now\(\)	Remove from queries
api.* scheduling	api\.[a-z]	Use internal.*

Production Readiness

1. Security: Validators + ConvexError + Auth checks + Internal functions
2. Performance: Indexes + Bounded queries + No Date.now()
3. Architecture: Helper functions + Proper action usage + "use node"
4. Code Quality: Awaited promises + Table names + Return validators