connorblack / convex-helpers

A collection of useful code to complement the official packages.

convex-helpers

A collection of useful code to complement the official packages. This directory has a project with examples of using convex-helpers. You can find the npm package in ./packages/convex-helpers.

Index

In the convex-helpers npm package:	In this directory for copy-pasting:
Custom Functions	Sessions: via a server table
Relationship helpers	The withUser utility
Stateful Migrations	Testing with a local backend
Sessions: client-generatead	Presence
Row-level security	Throttling via single-flighting
Zod validation	Stable query results via useStableQuery
Hono for HTTP endpoints
CRUD
Validator utilities
Filter db queries with JS
Action retry wrapper

convex-helpers npm package

In the packages directory there's the convex-helpers directory. To use it:

 npm install convex-helpers@latest

It doesn't have all of the below features, but the ones it has can be used directly, rather than copying the code from this repo.

See the README for more details.

Running these examples:

To run these locally, run: npm i && npm run dev. This will symlink the packages/convex-helpers directory so you can edit the convex helpers source while using it in this example project. It will also run chokidar to re-compile convex-helpers on file changes. See the watch script for details.

Custom Functions

Build your own customized versions of query, mutation, and action that define custom behavior, allowing you to:

• Run authentication logic before the request starts.
• Look up commonly used data and add it to the ctx argument.
• Replace a ctx or argument field with a different value, such as a version of db that runs custom functions on data access.
• Consume arguments from the client that are not passed to the action, such as taking in an authentication parameter like an API key or session ID. These arguments must be sent up by the client along with each request.

See more in the convex-helpers README.

Zod Validation

To validate your arguments with zod instead of the built-in argument validation, you can import from convex-helpers from "convex-helpers/server/zod". Read more in the Stack post.

Server-Persisted Session Data

There are two approaches to sessions data:

1. Creating a session ID client-side and passing it up to the server on every request. This is the recommended approach and is available by importing from "convex-helpers/server/sessions". See more in the convex-helpers README.

2. Create a new session document in a sessions table for every new client, where you can store associated data. See this article on Stack for tips on how to set up and use Sessions. To use theses sessions, copy the files:

   • server/sessions.ts on the server-side to give you action utilities like ctx.runSessionQuery(...).
   • react/session.ts on the client-side to give you hooks like useSessionMutation(...).
   • You'll need to define a table in your convex/schema.ts for whatever your session data looks like. Here we just use {}.

Retrying actions

Use helper functions to retry a Convex action until it succeeds.

See the Stack post on retrying actions and the convex-helpers package README for examples and usage.

Authentication: withUser

See the Stack post on withUser

Use the withUser wrappers in your functions to easily look up a user. You'll need to add an entry in your schema similar to convex/schema.ts.

Row-level security

See the Stack post on row-level security

Use the RowLevelSecurity helper to define withQueryRLS and withMutationRLS wrappers to add row-level checks for a server-side function. Any access to db inside functions wrapped with these will check your access rules on read/insert/modify per-document.

Migrations: Data mutations

See the Stack post on migrations and the migration primer Stack post.

See the convex-helpers package for examples and usage.

Relationship helpers

See the Stack post on relationship helpers and the relationship schema structures post.

To use convex-helpers, import from "convex-helpers/server/relationships" See more in the convex-helpers README.

To copy code: Use relationships.ts to traverse database relationships in queries more cleanly.

HTTP Endpoints: Using Hono for advanced functionality

Hono is an optimized web framework you can use to define HTTP API endpoints easily (httpAction in Convex).

See the guide on Stack for tips on using Hono for HTTP endpoints.

To use convex-helpers, import from "convex-helpers/server/hono" See more in the convex-helpers README.

CRUD utilities

To generate a basic CRUD api for your tables, you can use this helper to define these functions for a given table:

• create
• read
• update
• delete
• paginate

To use convex-helpers, import { crud } from "convex-helpers/server" See more in the convex-helpers README.

Throttling client-side requests by Single-Flighting

See the Stack post on single-flighting for info on a technique to limit client requests.

You'll need the useSingleFlight.ts file, or useLatestValue.ts utilities.

Stable query results via useStableQuery

If you're fine getting stale results from queries when parameters change, check out the Stack post on useStableQuery.

You'll need the useStableQuery.ts file.

Presence

See the Stack post on implementing presence for details on how to implement presence in your app.

Related files:

• presence.ts for server-side presence functions. Intended to be modified for your application.
• usePresence.ts for client-side React hooks. Modify to match your server API.
• (optional)useTypingIndicator.ts for specifically doing typing indicator presence.
• (optional)Facepile.tsx for showing a facepile based on presence data. Intended to be used as an example to extend.

Validator utilities

When using validators for defining database schema or function arguments, these validators help:

1. Add a Table utility that defines a table and keeps references to the fields to avoid re-defining validators. To learn more about sharing validators, read this article, an extension of this article.
2. Add utilties for partial, pick and omit to match the TypeScript type utilities.
3. Add shorthand for a union of literals, a nullable field, a deprecated field, and brandedString. To learn more about branded strings see this article.
4. Make the validators look more like TypeScript types, even though they're runtime values. (This is controvercial and not required to use the above).

See more in the convex-helpers README.

Testing with a local backend

convex/example.test.ts demonstrates testing Convex functions by running them against a local backend.

See this Stack article for more information.

To set these up for yourself:

• Clone the Convex open source backend repo and follow setup instructions
• Create a clearAll function to reset data between tests (see convex/testingFunctions.ts for an example)
• Start writing tests using ConvexTestingHelper.ts
• Make sure to call clearAll between tests and configure your testing framework to run one test at a time to ensure test isolation
• npm run testFunctions can be used to run these tests. This command does the following:
  • Sets up a fresh a local backend (see backendHarness.js)
  • Sets the IS_TEST environment variable to enable calling test only functions
  • Deploys code to the backend
  • Runs the tests
  • Tears down the backend

🧑‍🏫 What is Convex?

Convex is a hosted backend platform with a built-in database that lets you write your database schema and server functions in TypeScript. Server-side database queries automatically cache and subscribe to data, powering a realtime useQuery hook in our React client. There are also clients for Python, Rust, ReactNative, and Node, as well as a straightforward HTTP API.

The database supports NoSQL-style documents with opt-in schema validation, relationships and custom indexes (including on fields in nested objects).

The query and mutation server functions have transactional, low latency access to the database and leverage our v8 runtime with determinism guardrails to provide the strongest ACID guarantees on the market: immediate consistency, serializable isolation, and automatic conflict resolution via optimistic multi-version concurrency control (OCC / MVCC).

The action server functions have access to external APIs and enable other side-effects and non-determinism in either our optimized v8 runtime or a more flexible node runtime.

Functions can run in the background via scheduling and cron jobs.

Development is cloud-first, with hot reloads for server function editing via the CLI, preview deployments, logging and exception reporting integrations, There is a dashboard UI to browse and edit data, edit environment variables, view logs, run server functions, and more.

There are built-in features for reactive pagination, file storage, reactive text search, vector search, https endpoints (for webhooks), snapshot import/export, streaming import/export, and runtime validation for function arguments and database data.

Everything scales automatically, and it’s free to start.