convex-helpers（凸辅助器）

convex-helpers

NPM: convex-helpers | Repo: https://github.com/get-convex/convex-helpers

Installation

npm install convex-helpers
# Zod validation: npm install zod
# Hono endpoints: npm install hono

Quick Import Reference

// Core utilities
import { asyncMap, pruneNull, nullThrows, pick, omit } from "convex-helpers";

// Custom function builders
import { customQuery, customMutation, customAction, customCtx, NoOp } from "convex-helpers/server/customFunctions";

// Relationship traversal
import { getOrThrow, getAll, getAllOrThrow, getOneFrom, getOneFromOrThrow, getManyFrom, getManyVia, getManyViaOrThrow } from "convex-helpers/server/relationships";

// Row-level security
import { wrapDatabaseReader, wrapDatabaseWriter } from "convex-helpers/server/rowLevelSecurity";

// Zod validation (v4)
import { zCustomQuery, zCustomMutation, zid } from "convex-helpers/server/zod4";

// Validator utilities
import { literals, nullable, partial, deprecated, brandedString, systemFields, withSystemFields, doc, typedV, validate } from "convex-helpers/validators";

// Filter, pagination, streams
import { filter } from "convex-helpers/server/filter";
import { getPage, paginator } from "convex-helpers/server/pagination";
import { stream, mergedStream } from "convex-helpers/server/stream";

// Triggers
import { Triggers } from "convex-helpers/server/triggers";

// CRUD
import { crud } from "convex-helpers/server/crud";

// CORS & Hono
import { corsRouter } from "convex-helpers/server/cors";
import { HonoWithConvex, HttpRouterWithHono } from "convex-helpers/server/hono";

// React hooks
import { makeUseQueryWithStatus } from "convex-helpers/react";
import { ConvexQueryCacheProvider, useQuery, usePaginatedQuery } from "convex-helpers/react/cache";
import { SessionProvider, useSessionQuery, useSessionMutation } from "convex-helpers/react/sessions";

Helper Selection Guide

Core Patterns

Authentication wrapper (most common pattern)

import { customQuery, customCtx } from "convex-helpers/server/customFunctions";
import { query } from "./_generated/server";

export const authenticatedQuery = customQuery(query, {
  input: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    if (!user) throw new Error("Not authenticated");
    return { ctx: { ...ctx, user }, args };
  },
});

// Usage
export const myQuery = authenticatedQuery({
  args: { id: v.id("posts") },
  handler: async (ctx, { id }) => {
    // ctx.user available
    return ctx.db.get(id);
  },
});

Relationship loading

import { asyncMap } from "convex-helpers";
import { getOneFromOrThrow, getManyFrom, getManyViaOrThrow } from "convex-helpers/server/relationships";

// Requires indexes named after the field: .index("userId", ["userId"])
const author = await getOneFromOrThrow(ctx.db, "authors", "userId", user._id);
const posts = await getManyFrom(ctx.db, "posts", "authorId", author._id);
const categories = await getManyViaOrThrow(ctx.db, "postCategories", "categoryId", "postId", post._id);

// Nested loading
const postsWithComments = await asyncMap(posts, async (post) => ({
  ...post,
  comments: await getManyFrom(ctx.db, "comments", "postId", post._id),
}));

Validator shorthands

import { literals, nullable, partial } from "convex-helpers/validators";

// Instead of v.union(v.literal("a"), v.literal("b"))
status: literals("active", "inactive", "archived")

// Instead of v.union(v.null(), v.string())
email: nullable(v.string())

// Make all fields optional (for patches)
const patchValidator = partial({ name: v.string(), age: v.number() });

Best Practices

1. Custom functions are the foundation — most helpers (RLS, sessions, triggers) build on customQuery/customMutation. Define your builders early.
2. Index your database — relationship helpers, pagination, and streams all require indexes on queried fields.
3. Prefer built-in when sufficient — use built-in .filter() and .paginate() unless you need JS predicates or multiple paginations.
4. Security first — use internal functions for CRUD, add RLS before exposing publicly, validate all inputs.
5. Use asyncMap for parallel fetches — await asyncMap(ids, id => ctx.db.get(id)) runs in parallel.
6. Limit stream reads — always set maximumRowsRead when using filterWith to prevent scanning entire tables.

Deprecated Helpers (use components instead)

CLI Tools

# Generate TypeScript API spec for external repos
npx convex-helpers ts-api-spec
npx convex-helpers ts-api-spec --prod

# Generate OpenAPI spec
npx convex-helpers open-api-spec