├── .prettierrc
├── src
    ├── vite-env.d.ts
    ├── main.tsx
    ├── hooks
    │   ├── useTypingIndicator.ts
    │   ├── useLatestValue.ts
    │   ├── useStableQuery.ts
    │   ├── useSingleFlight.ts
    │   └── usePresence.ts
    ├── fakeConvexClient
    │   ├── fakeConvexClient.d.ts
    │   └── fakeConvexClient.js
    ├── components
    │   ├── RelationshipExample.tsx
    │   ├── HonoExample.tsx
    │   ├── Counter.tsx
    │   ├── ZodFunctionsExample.tsx
    │   ├── Facepile.tsx
    │   ├── SessionsExample.tsx
    │   ├── Counter.injection.test.tsx
    │   ├── Counter.mock.test.tsx
    │   └── CacheExample.tsx
    ├── App.tsx
    └── index.css
├── .cursor
    └── worktrees.json
├── packages
    └── convex-helpers
    │   ├── .npmignore
    │   ├── server
    │       ├── _generated
    │       │   └── _ignore.ts
    │       ├── setup.test.ts
    │       ├── filter.test.ts
    │       ├── compare.ts
    │       ├── cors.test.http.ts
    │       ├── triggers.test.ts
    │       ├── sessions.ts
    │       ├── table.test.ts
    │       ├── crud.ts
    │       └── filter.ts
    │   ├── react
    │       ├── cache.ts
    │       ├── cache
    │       │   └── provider.tsx
    │       └── sessions.test.ts
    │   ├── vitest.config.mts
    │   ├── cli
    │       ├── index.ts
    │       ├── tsApiSpec.test.ts
    │       ├── openApiSpec.test.ts
    │       └── utils.ts
    │   ├── standardSchema.ts
    │   ├── browser.ts
    │   ├── index.test.ts
    │   ├── generate-exports.mjs
    │   ├── validators.test.ts
    │   ├── browser.test.ts
    │   ├── testing.ts
    │   ├── standardSchema.test.ts
    │   ├── CHANGELOG.md
    │   ├── index.ts
    │   └── package.json
├── AGENTS.md
├── convex.sh
├── index.html
├── .github
    └── workflows
    │   ├── PULL_REQUEST_TEMPLATE.md
    │   ├── cla.yml
    │   └── test.yml
├── vite.config.mts
├── convex
    ├── vitest.config.mts
    ├── _generated
    │   ├── api.js
    │   ├── dataModel.d.ts
    │   ├── api.d.ts
    │   ├── server.js
    │   └── server.d.ts
    ├── http.ts
    ├── tsconfig.json
    ├── zodFunctionsExample.ts
    ├── example.test.ts
    ├── schema.ts
    ├── testingFunctions.ts
    ├── streamsExample.ts
    ├── migrationsExample.ts
    ├── counter.ts
    ├── rlsExample.ts
    ├── README.md
    ├── presence.ts
    ├── retriesExample.ts
    └── triggersExample.ts
├── tsconfig.json
├── renovate.json
├── publish.sh
├── .gitignore
├── Justfile
├── eslint.config.mjs
├── package.json
├── backendHarness.js
├── CONTRIBUTING.md
├── scripts
    └── check_cla.py
└── .vscode
    └── convex.code-snippets


/.prettierrc:
--------------------------------------------------------------------------------
1 | {
2 |   "arrowParens": "always"
3 | }
4 | 


--------------------------------------------------------------------------------
/src/vite-env.d.ts:
--------------------------------------------------------------------------------
1 | /// <reference types="vite/client" />
2 | 


--------------------------------------------------------------------------------
/.cursor/worktrees.json:
--------------------------------------------------------------------------------
1 | {
2 |   "setup-worktree": ["npm ci"]
3 | }
4 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/.npmignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | package-lock.json
3 | *.tgz
4 | *.tsbuildinfo
5 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/server/_generated/_ignore.ts:
--------------------------------------------------------------------------------
1 | // This is only here so convex-test can detect a _generated folder
2 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/server/setup.test.ts:
--------------------------------------------------------------------------------
1 | /// <reference types="vite/client" />
2 | export const modules = import.meta.glob("./**/*.*s");
3 | 
4 | test("setup", () => {});
5 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/react/cache.ts:
--------------------------------------------------------------------------------
1 | export { ConvexQueryCacheProvider } from "./cache/provider.js";
2 | export { useQuery, useQueries, usePaginatedQuery } from "./cache/hooks.js";
3 | 


--------------------------------------------------------------------------------
/AGENTS.md:
--------------------------------------------------------------------------------
1 | When doing a task that involves modifying complex TypeScript types, run `npm run typecheck` in the root of the repository to ensure that the types are correct. Do not attempt to run `tsc` manually.
2 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/vitest.config.mts:
--------------------------------------------------------------------------------
 1 | import { defineConfig } from "vitest/config";
 2 | 
 3 | export default defineConfig({
 4 |   test: {
 5 |     environment: "edge-runtime",
 6 |     exclude: ["**/node_modules/**", "dist/**"],
 7 |     globals: true,
 8 |   },
 9 | });
10 | 


--------------------------------------------------------------------------------
/convex.sh:
--------------------------------------------------------------------------------
1 | #! /bin/sh
2 | set -e
3 | 
4 | if grep -q -E '^\s*VITE_CONVEX_URL\s*=\s*https://.*\.convex\.cloud' .env.local; then
5 |     npx convex "$@"
6 | else
7 |     npx convex "$@" --admin-key 0135d8598650f8f5cb0f30c34ec2e2bb62793bc28717c8eb6fb577996d50be5f4281b59181095065c5d0f86a2c31ddbe9b597ec62b47ded69782cd --url "http://127.0.0.1:3210"
8 | fi
9 | 


--------------------------------------------------------------------------------
/index.html:
--------------------------------------------------------------------------------
 1 | <!doctype html>
 2 | <html lang="en">
 3 |   <head>
 4 |     <meta charset="UTF-8" />
 5 |     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 6 |     <title>Convex Helpers</title>
 7 |   </head>
 8 |   <body>
 9 |     <div id="root"></div>
10 |     <script type="module" src="/src/main.tsx"></script>
11 |   </body>
12 | </html>
13 | 


--------------------------------------------------------------------------------
/.github/workflows/PULL_REQUEST_TEMPLATE.md:
--------------------------------------------------------------------------------
 1 | <!-- Describe your PR here. -->
 2 | 
 3 | <!--
 4 |   The following applies to third-party contributors.
 5 |   Convex employees and contractors can delete or ignore.
 6 | -->
 7 | 
 8 | ---
 9 | 
10 | By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.
11 | 


--------------------------------------------------------------------------------
/vite.config.mts:
--------------------------------------------------------------------------------
 1 | import { defineConfig } from "vitest/config";
 2 | import react from "@vitejs/plugin-react";
 3 | 
 4 | // https://vitejs.dev/config/
 5 | export default defineConfig({
 6 |   plugins: [react()],
 7 | 
 8 |   test: {
 9 |     environment: "jsdom",
10 |     exclude: ["node_modules/**", "convex/**", "packages/**"],
11 |     projects: [".", "packages/convex-helpers"],
12 |     globals: true,
13 |   },
14 | });
15 | 


--------------------------------------------------------------------------------
/convex/vitest.config.mts:
--------------------------------------------------------------------------------
 1 | import { defineConfig } from "vitest/config";
 2 | 
 3 | // https://vitejs.dev/config/
 4 | export default defineConfig({
 5 |   test: {
 6 |     environment: "edge-runtime",
 7 |     exclude: [],
 8 |     passWithNoTests: true,
 9 | 
10 |     // Only run one suite at a time because all of our tests are running against
11 |     // the same backend and we don't want to leak state.
12 |     maxWorkers: 1,
13 |     minWorkers: 1,
14 |     globals: true,
15 |   },
16 | });
17 | 


--------------------------------------------------------------------------------
/src/main.tsx:
--------------------------------------------------------------------------------
 1 | import { StrictMode } from "react";
 2 | import { createRoot } from "react-dom/client";
 3 | import "./index.css";
 4 | import App from "./App";
 5 | import { ConvexProvider, ConvexReactClient } from "convex/react";
 6 | 
 7 | const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);
 8 | 
 9 | createRoot(document.getElementById("root")!).render(
10 |   <StrictMode>
11 |     <ConvexProvider client={convex}>
12 |       <App />
13 |     </ConvexProvider>
14 |   </StrictMode>,
15 | );
16 | 


--------------------------------------------------------------------------------
/src/hooks/useTypingIndicator.ts:
--------------------------------------------------------------------------------
 1 | import { useEffect } from "react";
 2 | 
 3 | export default (
 4 |   text: string,
 5 |   updateMyPresence: (p: { typing?: boolean }) => void,
 6 | ) => {
 7 |   useEffect(() => {
 8 |     if (text.length === 0) {
 9 |       updateMyPresence({ typing: false });
10 |       return;
11 |     }
12 |     updateMyPresence({ typing: true });
13 |     const timer = setTimeout(() => updateMyPresence({ typing: false }), 1000);
14 |     return () => clearTimeout(timer);
15 |   }, [updateMyPresence, text]);
16 | };
17 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/cli/index.ts:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env node
 2 | 
 3 | import { Command } from "commander";
 4 | import { openApiSpec } from "./openApiSpec.js";
 5 | import { tsApiSpec } from "./tsApiSpec.js";
 6 | 
 7 | async function main() {
 8 |   const program = new Command();
 9 |   program
10 |     .name("convex-helpers")
11 |     .usage("<command> [options]")
12 |     .description("Run scripts in the convex-helpers library.")
13 |     .addCommand(openApiSpec)
14 |     .addCommand(tsApiSpec);
15 | 
16 |   await program.parseAsync(process.argv);
17 |   process.exit();
18 | }
19 | 
20 | void main();
21 | 


--------------------------------------------------------------------------------
/convex/_generated/api.js:
--------------------------------------------------------------------------------
 1 | /* eslint-disable */
 2 | /**
 3 |  * Generated `api` utility.
 4 |  *
 5 |  * THIS CODE IS AUTOMATICALLY GENERATED.
 6 |  *
 7 |  * To regenerate, run `npx convex dev`.
 8 |  * @module
 9 |  */
10 | 
11 | import { anyApi, componentsGeneric } from "convex/server";
12 | 
13 | /**
14 |  * A utility for referencing Convex functions in your app's API.
15 |  *
16 |  * Usage:
17 |  * ```js
18 |  * const myFunctionReference = api.myModule.myFunction;
19 |  * ```
20 |  */
21 | export const api = anyApi;
22 | export const internal = anyApi;
23 | export const components = componentsGeneric();
24 | 


--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "compilerOptions": {
 3 |     "target": "ESNext",
 4 |     "lib": ["DOM", "DOM.Iterable", "ESNext"],
 5 |     "allowJs": false,
 6 |     "skipLibCheck": true,
 7 |     "esModuleInterop": false,
 8 |     "allowSyntheticDefaultImports": true,
 9 |     "strict": true,
10 |     "forceConsistentCasingInFileNames": true,
11 |     "module": "ESNext",
12 |     "moduleResolution": "Bundler",
13 |     "resolveJsonModule": true,
14 |     "isolatedModules": true,
15 |     "noEmit": true,
16 |     "jsx": "react-jsx"
17 |   },
18 |   "include": ["./src", "./convex", "./packages/convex-helpers/**/*.test.ts"]
19 | }
20 | 


--------------------------------------------------------------------------------
/src/fakeConvexClient/fakeConvexClient.d.ts:
--------------------------------------------------------------------------------
 1 | import { ConvexReactClient } from "convex/react";
 2 | import { FunctionReference } from "convex/server";
 3 | 
 4 | export class ConvexReactClientFake extends ConvexReactClient {
 5 |   constructor();
 6 | 
 7 |   registerQueryFake<FuncRef extends FunctionReference<"query", "public">>(
 8 |     funcRef: FuncRef,
 9 |     impl: (args: FuncRef["_args"]) => FuncRef["_returnType"],
10 |   ): void;
11 |   registerMutationFake<FuncRef extends FunctionReference<"mutation", "public">>(
12 |     funcRef: FuncRef,
13 |     impl: (args: FuncRef["_args"]) => FuncRef["_returnType"],
14 |   ): void;
15 | }
16 | 


--------------------------------------------------------------------------------
/src/components/RelationshipExample.tsx:
--------------------------------------------------------------------------------
 1 | import { useMutation } from "convex/react";
 2 | import { api } from "../../convex/_generated/api";
 3 | import { useState } from "react";
 4 | 
 5 | function RelationshipExample() {
 6 |   const [worked, setWorked] = useState(false);
 7 |   const test = useMutation(api.relationshipsExample.relationshipTest);
 8 |   return (
 9 |     <div>
10 |       <h2>Relationship Test</h2>
11 |       {worked ? (
12 |         <div>Worked!</div>
13 |       ) : (
14 |         <button onClick={() => test({}).then(setWorked)}>Test</button>
15 |       )}
16 |     </div>
17 |   );
18 | }
19 | export default RelationshipExample;
20 | 


--------------------------------------------------------------------------------
/renovate.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
 3 |   "extends": ["config:best-practices"],
 4 |   "schedule": ["* 0-4 * * 1"],
 5 |   "timezone": "America/Los_Angeles",
 6 |   "prConcurrentLimit": 1,
 7 |   "packageRules": [
 8 |     {
 9 |       "groupName": "Routine updates",
10 |       "matchUpdateTypes": ["minor", "patch", "pin", "digest"],
11 |       "automerge": true
12 |     },
13 |     {
14 |       "groupName": "Major updates",
15 |       "matchUpdateTypes": ["major"],
16 |       "automerge": false
17 |     },
18 |     {
19 |       "matchDepTypes": ["devDependencies"],
20 |       "automerge": true
21 |     }
22 |   ]
23 | }
24 | 


--------------------------------------------------------------------------------
/src/components/HonoExample.tsx:
--------------------------------------------------------------------------------
 1 | import { useQuery } from "convex/react";
 2 | import { api } from "../../convex/_generated/api";
 3 | import { useEffect, useState } from "react";
 4 | 
 5 | export function HonoExample() {
 6 |   const siteUrl = useQuery(api.http.siteUrl);
 7 |   const [value, setValue] = useState("");
 8 |   useEffect(() => {
 9 |     if (!siteUrl) return;
10 |     void fetch(`${siteUrl}/`)
11 |       .then((r) => r.text())
12 |       .then(setValue);
13 |   }, [siteUrl]);
14 | 
15 |   return (
16 |     <div>
17 |       <h2>Hono Example</h2>
18 |       <p>
19 |         Value fetching from {siteUrl}/: {value}
20 |       </p>
21 |     </div>
22 |   );
23 | }
24 | 


--------------------------------------------------------------------------------
/src/components/Counter.tsx:
--------------------------------------------------------------------------------
 1 | import { api } from "../../convex/_generated/api";
 2 | import { useQuery, useMutation } from "convex/react";
 3 | import { useCallback } from "react";
 4 | 
 5 | const Counter = () => {
 6 |   const counter =
 7 |     useQuery(api.counter.getCounter, { counterName: "clicks" }) ?? 0;
 8 |   const increment = useMutation(api.counter.incrementCounter);
 9 |   const incrementByOne = useCallback(
10 |     () => increment({ counterName: "clicks", increment: 1 }),
11 |     [increment],
12 |   );
13 | 
14 |   return (
15 |     <div>
16 |       <p>
17 |         {"Here's the counter:"} {counter}
18 |       </p>
19 |       <button onClick={incrementByOne}>Add One!</button>
20 |     </div>
21 |   );
22 | };
23 | 
24 | export default Counter;
25 | 


--------------------------------------------------------------------------------
/convex/http.ts:
--------------------------------------------------------------------------------
 1 | import { HonoWithConvex, HttpRouterWithHono } from "convex-helpers/server/hono";
 2 | import { Hono } from "hono";
 3 | import { cors } from "hono/cors";
 4 | import { ActionCtx, query } from "./_generated/server";
 5 | 
 6 | const app: HonoWithConvex<ActionCtx> = new Hono();
 7 | 
 8 | app.use("/*", cors());
 9 | // See the [guide on Stack](https://stack.convex.dev/hono-with-convex)
10 | // for tips on using Hono for HTTP endpoints.
11 | app.get("/", async (c) => {
12 |   return c.json("Hello world!");
13 | });
14 | 
15 | export default new HttpRouterWithHono(app);
16 | 
17 | /**
18 |  * Helper for testing.
19 |  */
20 | export const siteUrl = query({
21 |   args: {},
22 |   handler: async () => {
23 |     return process.env.CONVEX_SITE_URL;
24 |   },
25 | });
26 | 


--------------------------------------------------------------------------------
/convex/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   /* This TypeScript project config describes the environment that
 3 |    * Convex functions run in and is used to typecheck them.
 4 |    * You can modify it, but some settings required to use Convex.
 5 |    */
 6 |   "compilerOptions": {
 7 |     /* These settings are not required by Convex and can be modified. */
 8 |     "allowJs": true,
 9 |     "strict": true,
10 | 
11 |     /* These compiler options are required by Convex */
12 |     "target": "ESNext",
13 |     "lib": ["ES2021", "dom"],
14 |     "forceConsistentCasingInFileNames": true,
15 |     "allowSyntheticDefaultImports": true,
16 |     "module": "ESNext",
17 |     "moduleResolution": "Bundler",
18 |     "isolatedModules": true,
19 |     "skipLibCheck": true,
20 |     "noEmit": true
21 |   },
22 |   "include": ["./**/*"],
23 |   "exclude": ["./_generated"]
24 | }
25 | 


--------------------------------------------------------------------------------
/.github/workflows/cla.yml:
--------------------------------------------------------------------------------
 1 | name: Check CLA in PR description
 2 | 
 3 | on:
 4 |   pull_request:
 5 |     # Run when PRs are opened, reopened, edited or updated with new commits
 6 |     types: [opened, reopened, synchronize, edited]
 7 | 
 8 | jobs:
 9 |   check-cla:
10 |     name: Check CLA in PR description
11 |     runs-on: ubuntu-latest
12 | 
13 |     steps:
14 |       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
15 | 
16 |       - name: Validate PR has CLA confirmation
17 |         # Exclude automated PRs from bots
18 |         if: ${{ (startsWith(github.head_ref, 'dependabot') || startsWith(github.head_ref, 'renovate')) == false }}
19 |         env:
20 |           PR_DESCRIPTION: ${{ github.event.pull_request.body }}
21 |           PR_AUTHOR: ${{ github.event.pull_request.user.login }}
22 |           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
23 |         run: |
24 |           ./scripts/check_cla.py
25 | 


--------------------------------------------------------------------------------
/.github/workflows/test.yml:
--------------------------------------------------------------------------------
 1 | name: Test and lint
 2 | concurrency:
 3 |   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
 4 |   cancel-in-progress: true
 5 | 
 6 | on:
 7 |   push:
 8 |     branches: [main]
 9 |   pull_request:
10 |     branches: ["**"]
11 | 
12 | jobs:
13 |   check:
14 |     name: Test and lint
15 |     runs-on: ubuntu-latest
16 |     timeout-minutes: 30
17 | 
18 |     steps:
19 |       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
20 | 
21 |       - name: Node setup
22 |         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
23 |         with:
24 |           node-version: "20.19.5"
25 | 
26 |       - name: Build
27 |         run: |
28 |           npm i
29 |           npm run build
30 | 
31 |       - name: Publish pkg-pr-new
32 |         run: |
33 |           npx pkg-pr-new publish ./packages/convex-helpers
34 | 
35 |       - name: Run lint, test, and codegen
36 |         run: |
37 |           npm run lint
38 |           npm run test
39 | 


--------------------------------------------------------------------------------
/convex/zodFunctionsExample.ts:
--------------------------------------------------------------------------------
 1 | import { zCustomQuery } from "convex-helpers/server/zod4";
 2 | import { query } from "./_generated/server";
 3 | import { NoOp } from "convex-helpers/server/customFunctions";
 4 | import { z } from "zod/v4";
 5 | 
 6 | export const zQuery = zCustomQuery(query, NoOp);
 7 | 
 8 | export const noArgs = zQuery({
 9 |   args: {},
10 |   handler: async (_ctx) => {
11 |     return "Hello world!";
12 |   },
13 | });
14 | 
15 | const stringToDate = z.codec(z.iso.datetime(), z.date(), {
16 |   decode: (isoString) => new Date(isoString),
17 |   encode: (date) => date.toISOString(),
18 | });
19 | const dateToString = z.codec(z.date(), z.iso.datetime(), {
20 |   decode: (date) => date.toISOString(),
21 |   encode: (isoString) => new Date(isoString),
22 | });
23 | 
24 | export const withArgs = zQuery({
25 |   args: {
26 |     date: stringToDate,
27 |   },
28 |   returns: {
29 |     oneDayAfter: dateToString,
30 |   },
31 |   handler: async (_ctx, args) => {
32 |     return {
33 |       oneDayAfter: new Date(args.date.getTime() + 24 * 60 * 60 * 1000),
34 |     };
35 |   },
36 | });
37 | 


--------------------------------------------------------------------------------
/convex/example.test.ts:
--------------------------------------------------------------------------------
 1 | import { api } from "./_generated/api";
 2 | import { ConvexTestingHelper } from "convex-helpers/testing";
 3 | 
 4 | describe("testingExample", () => {
 5 |   let t: ConvexTestingHelper;
 6 | 
 7 |   beforeEach(() => {
 8 |     t = new ConvexTestingHelper();
 9 |   });
10 | 
11 |   afterEach(async () => {
12 |     await t.mutation(api.testingFunctions.clearAll, {});
13 |     await t.close();
14 |   });
15 | 
16 |   test("counter", async () => {
17 |     expect(await t.query(api.counter.getCounter, { counterName: "foo" })).toBe(
18 |       0,
19 |     );
20 |     await expect(
21 |       t.query(api.counter.getCounterOrThrow, { counterName: "foo" }),
22 |     ).rejects.toThrow(/Counter not found/);
23 |     await expect(() =>
24 |       t.query(api.counter.getCounterOrThrow, { counterName: "bar" }),
25 |     ).rejects.toThrow(/Counter not found/);
26 |     await t.mutation(api.counter.incrementCounter, {
27 |       counterName: "foo",
28 |       increment: 10,
29 |     });
30 |     expect(
31 |       await t.query(api.counter.getCounterOrThrow, { counterName: "foo" }),
32 |     ).toBe(10);
33 |     expect(await t.query(api.counter.getCounter, { counterName: "foo" })).toBe(
34 |       10,
35 |     );
36 |     expect(await t.query(api.counter.getCounter, { counterName: "bar" })).toBe(
37 |       0,
38 |     );
39 |   });
40 | });
41 | 


--------------------------------------------------------------------------------
/src/App.tsx:
--------------------------------------------------------------------------------
 1 | import Counter from "./components/Counter";
 2 | import RelationshipExample from "./components/RelationshipExample";
 3 | import SessionsExample from "./components/SessionsExample";
 4 | import { HonoExample } from "./components/HonoExample";
 5 | import { StreamsExample } from "./components/StreamsExample";
 6 | import { ZodFunctionsExample } from "./components/ZodFunctionsExample";
 7 | import { SessionProvider } from "convex-helpers/react/sessions";
 8 | import { CacheExample } from "./components/CacheExample";
 9 | import { ConvexQueryCacheProvider } from "convex-helpers/react/cache";
10 | // Used for the session example if you want to store sessionId in local storage
11 | // import { useLocalStorage } from "usehooks-ts";
12 | 
13 | export default function App() {
14 |   return (
15 |     <main>
16 |       <SessionProvider
17 |       // storageKey={"ConvexSessionId"}
18 |       // useStorage={useLocalStorage}
19 |       >
20 |         <ConvexQueryCacheProvider maxIdleEntries={11} expiration={15000}>
21 |           <Counter />
22 |           <RelationshipExample />
23 |           <SessionsExample />
24 |           <HonoExample />
25 |           <CacheExample />
26 |           <StreamsExample />
27 |           <ZodFunctionsExample />
28 |         </ConvexQueryCacheProvider>
29 |       </SessionProvider>
30 |     </main>
31 |   );
32 | }
33 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/cli/tsApiSpec.test.ts:
--------------------------------------------------------------------------------
 1 | import * as ts from "typescript";
 2 | import { expect, test } from "vitest";
 3 | import { FUNCTIONS_JSON, JS_API } from "./functions.test.js";
 4 | import { generateApiSpec } from "./tsApiSpec.js";
 5 | 
 6 | // If this test fails, it means the generated code changed. Confirm that these changes are
 7 | // intentional by looking at the diff and update the string we compare against.
 8 | test("generatedCodeMatches", () => {
 9 |   const tsCode = generateApiSpec(JSON.parse(FUNCTIONS_JSON), false);
10 |   expect(
11 |     tsCode,
12 |     "The generated code has changed. Confirm that these changes are intentional\
13 |          by looking at the diff and update the comparison string if necessary.",
14 |   ).toEqual(JS_API);
15 | });
16 | 
17 | // If this test fails, you made the generated code invalid typescript.
18 | test("generatedCodeIsValid", () => {
19 |   const tsCode = generateApiSpec(JSON.parse(FUNCTIONS_JSON), false);
20 |   const result = ts.transpileModule(tsCode, {
21 |     compilerOptions: {
22 |       module: ts.ModuleKind.CommonJS,
23 |       target: ts.ScriptTarget.ESNext,
24 |     },
25 |   });
26 | 
27 |   const jsCode = result.outputText;
28 | 
29 |   // Asserts that the generated code is valid typescript. This will fail if
30 |   // the generated code is invalid.
31 |   eval(jsCode);
32 | });
33 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/cli/openApiSpec.test.ts:
--------------------------------------------------------------------------------
 1 | import fs from "fs";
 2 | import { expect, test } from "vitest";
 3 | import { generateOpenApiSpec } from "./openApiSpec.js";
 4 | import { execSync } from "child_process";
 5 | import { FUNCTIONS_JSON, OPEN_API_SPEC } from "./functions.test.js";
 6 | 
 7 | // If this test fails, it means you changed the generated OpenAPI spec. Confirm that these changes are
 8 | // intentional by looking at the diff and update the string we compare against.
 9 | test("openApiSpecMatches", () => {
10 |   const apiSpec = generateOpenApiSpec(JSON.parse(FUNCTIONS_JSON), true);
11 | 
12 |   expect(
13 |     apiSpec,
14 |     "The generated spec has changed. Confirm that these changes are intentional\
15 |          by looking at the diff and update the comparison string if necessary.",
16 |   ).toEqual(OPEN_API_SPEC);
17 | });
18 | 
19 | // If this test fails, it means the generated OpenAPI spec is no longer valid.
20 | test("generateValidSpec", async () => {
21 |   const apiSpec = generateOpenApiSpec(JSON.parse(FUNCTIONS_JSON), true);
22 | 
23 |   const testFileName = "openApiSpec.test.yaml";
24 |   fs.writeFileSync(testFileName, apiSpec, "utf-8");
25 | 
26 |   const output = execSync(`npx redocly lint ${testFileName} --format='json'`);
27 | 
28 |   fs.unlinkSync(testFileName);
29 | 
30 |   expect(JSON.parse(output.toString())["totals"]).toHaveProperty("errors", 0);
31 | });
32 | 


--------------------------------------------------------------------------------
/src/hooks/useLatestValue.ts:
--------------------------------------------------------------------------------
 1 | import { useCallback, useMemo, useRef } from "react";
 2 | 
 3 | /**
 4 |  * Promise-based access to the latest value updated.
 5 |  * Every call to nextValue will return a promise to the next value.
 6 |  * "Next value" is defined as the latest value passed to "updateValue" that
 7 |  * hasn not been returned yet.
 8 |  * @returns a function to await for a new value, and one to update the value.
 9 |  */
10 | export default function useLatestValue<T>() {
11 |   const initial = useMemo(() => {
12 |     const [promise, resolve] = makeSignal();
13 |     // We won't access data until it has been updated.
14 |     return { data: undefined as T, promise, resolve };
15 |   }, []);
16 |   const ref = useRef(initial);
17 |   const nextValue = useCallback(async () => {
18 |     await ref.current.promise;
19 |     const [promise, resolve] = makeSignal();
20 |     ref.current.promise = promise;
21 |     ref.current.resolve = resolve;
22 |     return ref.current.data;
23 |   }, [ref]);
24 | 
25 |   const updateValue = useCallback(
26 |     (data: T) => {
27 |       ref.current.data = data;
28 |       ref.current.resolve();
29 |     },
30 |     [ref],
31 |   );
32 | 
33 |   return [nextValue, updateValue] as const;
34 | }
35 | 
36 | const makeSignal = () => {
37 |   let resolve: () => void;
38 |   const promise = new Promise<void>((r) => (resolve = r));
39 |   return [promise, resolve!] as const;
40 | };
41 | 


--------------------------------------------------------------------------------
/src/components/ZodFunctionsExample.tsx:
--------------------------------------------------------------------------------
 1 | import { api } from "../../convex/_generated/api";
 2 | import { useQuery } from "convex/react";
 3 | import { useMemo } from "react";
 4 | import { z } from "zod/v4";
 5 | 
 6 | const stringToDate = z.codec(z.iso.datetime(), z.date(), {
 7 |   decode: (isoString) => new Date(isoString),
 8 |   encode: (date) => date.toISOString(),
 9 | });
10 | 
11 | export function ZodFunctionsExample() {
12 |   const now = useMemo(() => new Date(), []);
13 | 
14 |   const noArgsResult = useQuery(api.zodFunctionsExample.noArgs);
15 |   const noArgsResultEmptyArgs = useQuery(api.zodFunctionsExample.noArgs, {});
16 |   const withArgsResult = useQuery(api.zodFunctionsExample.withArgs, {
17 |     date: stringToDate.encode(now),
18 |   });
19 | 
20 |   return (
21 |     <div>
22 |       <h2>Zod Functions Example</h2>
23 |       <section>
24 |         <h3>No Args Query</h3>
25 |         <p>Result: {noArgsResult ?? "Loading..."}</p>
26 |       </section>
27 |       <section>
28 |         <h3>No Args Query (Empty Args)</h3>
29 |         <p>Result: {noArgsResultEmptyArgs ?? "Loading..."}</p>
30 |       </section>
31 |       <section>
32 |         <h3>With Args Query</h3>
33 |         {withArgsResult && (
34 |           <p>
35 |             One day after:{" "}
36 |             {stringToDate.decode(withArgsResult.oneDayAfter).toLocaleString()}
37 |           </p>
38 |         )}
39 |       </section>
40 |     </div>
41 |   );
42 | }
43 | 


--------------------------------------------------------------------------------
/src/components/Facepile.tsx:
--------------------------------------------------------------------------------
 1 | import classNames from "classnames";
 2 | import { useEffect, useState } from "react";
 3 | import { isOnline, PresenceData } from "../hooks/usePresence";
 4 | 
 5 | const UPDATE_MS = 1000;
 6 | 
 7 | type FacePileProps = {
 8 |   othersPresence?: PresenceData<{ emoji: string }>[];
 9 | };
10 | export default ({ othersPresence }: FacePileProps) => {
11 |   const [, setNow] = useState(Date.now());
12 |   useEffect(() => {
13 |     const intervalId = setInterval(() => setNow(Date.now()), UPDATE_MS);
14 |     return () => clearInterval(intervalId);
15 |   }, [setNow]);
16 |   return (
17 |     <div className="isolate flex -space-x-2 overflow-hidden">
18 |       {othersPresence
19 |         ?.slice(0, 5)
20 |         .map((presence) => ({
21 |           ...presence,
22 |           online: isOnline(presence),
23 |         }))
24 |         .sort((presence1, presence2) =>
25 |           presence1.online === presence2.online
26 |             ? presence1.created - presence2.created
27 |             : Number(presence1.online) - Number(presence2.online),
28 |         )
29 |         .map((presence) => (
30 |           <span
31 |             className={classNames(
32 |               "relative inline-block h-6 w-6 rounded-full bg-white ring-2 ring-white text-xl",
33 |               { grayscale: !presence.online },
34 |             )}
35 |             key={presence.created}
36 |             title={
37 |               presence.online
38 |                 ? "Online"
39 |                 : "Last seen " + new Date(presence.updated).toDateString()
40 |             }
41 |           >
42 |             {presence.data.emoji}
43 |           </span>
44 |         ))}
45 |     </div>
46 |   );
47 | };
48 | 


--------------------------------------------------------------------------------
/convex/schema.ts:
--------------------------------------------------------------------------------
 1 | import { defineSchema, defineTable } from "convex/server";
 2 | import { v } from "convex/values";
 3 | import { migrationsTable } from "convex-helpers/server/migrations";
 4 | 
 5 | export default defineSchema({
 6 |   users: defineTable({
 7 |     name: v.string(),
 8 |     age: v.number(),
 9 |     tokenIdentifier: v.string(),
10 |   }).index("tokenIdentifier", ["tokenIdentifier"]),
11 |   join_table_example: defineTable({
12 |     userId: v.id("users"),
13 |     presenceId: v.id("presence"),
14 |   }).index("by_userId", ["userId"]),
15 |   join_storage_example: defineTable({
16 |     userId: v.id("users"),
17 |     storageId: v.id("_storage"),
18 |   })
19 |     .index("storageId", ["storageId"])
20 |     .index("userId_storageId", ["userId", "storageId"]),
21 |   presence: defineTable({
22 |     user: v.string(),
23 |     room: v.string(),
24 |     updated: v.number(),
25 |     data: v.any(),
26 |   })
27 |     // Index for fetching presence data
28 |     .index("room_updated", ["room", "updated"])
29 |     // Index for updating presence data
30 |     .index("user_room", ["user", "room"]),
31 |   counter_table: defineTable({ name: v.string(), counter: v.number() }),
32 |   sum_table: defineTable({ sum: v.number() }),
33 |   notes: defineTable({ session: v.string(), note: v.string() }),
34 |   migrations: migrationsTable,
35 |   privateMessages: defineTable({
36 |     from: v.string(),
37 |     to: v.string(),
38 |     message: v.string(),
39 |     // we have creation time, but let's say we want to store it separately
40 |     sentAt: v.number(),
41 |   })
42 |     // inbox
43 |     .index("to", ["to", "sentAt"])
44 |     // outbox
45 |     .index("from", ["from", "sentAt"])
46 |     // pairwise
47 |     .index("from_to", ["from", "to", "sentAt"]),
48 | });
49 | 


--------------------------------------------------------------------------------
/convex/_generated/dataModel.d.ts:
--------------------------------------------------------------------------------
 1 | /* eslint-disable */
 2 | /**
 3 |  * Generated data model types.
 4 |  *
 5 |  * THIS CODE IS AUTOMATICALLY GENERATED.
 6 |  *
 7 |  * To regenerate, run `npx convex dev`.
 8 |  * @module
 9 |  */
10 | 
11 | import type {
12 |   DataModelFromSchemaDefinition,
13 |   DocumentByName,
14 |   TableNamesInDataModel,
15 |   SystemTableNames,
16 | } from "convex/server";
17 | import type { GenericId } from "convex/values";
18 | import schema from "../schema.js";
19 | 
20 | /**
21 |  * The names of all of your Convex tables.
22 |  */
23 | export type TableNames = TableNamesInDataModel<DataModel>;
24 | 
25 | /**
26 |  * The type of a document stored in Convex.
27 |  *
28 |  * @typeParam TableName - A string literal type of the table name (like "users").
29 |  */
30 | export type Doc<TableName extends TableNames> = DocumentByName<
31 |   DataModel,
32 |   TableName
33 | >;
34 | 
35 | /**
36 |  * An identifier for a document in Convex.
37 |  *
38 |  * Convex documents are uniquely identified by their `Id`, which is accessible
39 |  * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
40 |  *
41 |  * Documents can be loaded using `db.get(id)` in query and mutation functions.
42 |  *
43 |  * IDs are just strings at runtime, but this type can be used to distinguish them from other
44 |  * strings when type checking.
45 |  *
46 |  * @typeParam TableName - A string literal type of the table name (like "users").
47 |  */
48 | export type Id<TableName extends TableNames | SystemTableNames> =
49 |   GenericId<TableName>;
50 | 
51 | /**
52 |  * A type describing your Convex data model.
53 |  *
54 |  * This type includes information about what tables you have, the type of
55 |  * documents stored in those tables, and the indexes defined on them.
56 |  *
57 |  * This type is used to parameterize methods like `queryGeneric` and
58 |  * `mutationGeneric` to make them type-safe.
59 |  */
60 | export type DataModel = DataModelFromSchemaDefinition<typeof schema>;
61 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/standardSchema.ts:
--------------------------------------------------------------------------------
 1 | import type { GenericDatabaseReader } from "convex/server";
 2 | 
 3 | import type { Infer, Validator } from "convex/values";
 4 | 
 5 | import type { StandardSchemaV1 } from "@standard-schema/spec";
 6 | import { validate, ValidationError } from "./validators.js";
 7 | import type { GenericDataModel } from "convex/server";
 8 | 
 9 | /**
10 |  * Convert a Convex validator to a Standard Schema.
11 |  * @param validator - The Convex validator to convert.
12 |  * @param opts - Options for the validation.
13 |  * @returns The Standard Schema validator with the type of the Convex validator.
14 |  */
15 | export function toStandardSchema<V extends Validator<any, any, any>>(
16 |   validator: V,
17 |   opts?: {
18 |     /* If provided, v.id validation will check that the id is for the table. */
19 |     db?: GenericDatabaseReader<GenericDataModel>;
20 |     /* If true, allow fields that are not in an object validator. */
21 |     allowUnknownFields?: boolean;
22 |     /* A prefix for the path of the value being validated, for error reporting.
23 |     This is mostly used for recursive calls, do not set it manually unless you
24 |     are validating a value at a sub-path within some parent object. */
25 |     _pathPrefix?: string;
26 |   },
27 | ): StandardSchemaV1<Infer<V>> {
28 |   return {
29 |     "~standard": {
30 |       version: 1,
31 |       vendor: "convex-helpers",
32 |       validate: (value) => {
33 |         try {
34 |           validate(validator, value, { ...opts, throw: true });
35 |           return { value } as StandardSchemaV1.SuccessResult<Infer<V>>;
36 |         } catch (e) {
37 |           if (e instanceof ValidationError) {
38 |             return {
39 |               issues: [
40 |                 {
41 |                   message: e.message,
42 |                   path: e.path ? e.path.split(".") : undefined,
43 |                 },
44 |               ],
45 |             } as StandardSchemaV1.FailureResult;
46 |           }
47 |           throw e;
48 |         }
49 |       },
50 |     },
51 |   };
52 | }
53 | 


--------------------------------------------------------------------------------
/publish.sh:
--------------------------------------------------------------------------------
 1 | #! /bin/bash
 2 | 
 3 | set -e
 4 | 
 5 | rm -rf packages/convex-helpers/node_modules
 6 | npm i
 7 | npm run clean
 8 | npm run build
 9 | npm i
10 | npm run lint
11 | npm run test
12 | git diff --exit-code || {
13 |   echo "Uncommitted changes found. Commit or stash them before publishing."
14 |   exit 1
15 | }
16 | function cleanup() {
17 |   git checkout -- :/packages/convex-helpers/package.json
18 | }
19 | trap cleanup EXIT
20 | 
21 | pushd packages/convex-helpers >/dev/null
22 | if [ "$1" == "alpha" ]; then
23 |   npm version prerelease --preid alpha
24 | else
25 |   npm version patch
26 | fi
27 | current=$(npm pkg get version | tr -d '"')
28 | popd >/dev/null
29 | 
30 | cat <<EOF
31 | Test it:
32 |   - Add some example usage to the outer convex-helpers repo.
33 |   - Run \`npm pack\` in /dist and install it elsewhere from the .tgz file.
34 | EOF
35 | echo "Latest versions:"
36 | npm view convex-helpers@latest version
37 | npm view convex-helpers@alpha version
38 | 
39 | read -r -p "Enter the new version number (hit enter for $current): " version
40 | 
41 | pushd packages/convex-helpers >/dev/null
42 | if [ -n "$version" ]; then
43 |   npm pkg set version="$version"
44 | else
45 |   version=$current
46 | fi
47 | 
48 | cp package.json dist/
49 | 
50 | cd dist
51 | if (echo "$version" | grep alpha >/dev/null); then
52 |   npm publish --tag alpha --dry-run
53 | else
54 |   npm publish --dry-run
55 | fi
56 | popd >/dev/null
57 | echo "^^^ DRY RUN ^^^"
58 | read -r -p "Publish $version to npm? (y/n): " publish
59 | if [ "$publish" = "y" ]; then
60 |   npm i
61 |   pushd packages/convex-helpers/dist >/dev/null
62 |   if (echo "$version" | grep alpha >/dev/null); then
63 |     npm publish --tag alpha
64 |   else
65 |     npm publish
66 |   fi
67 |   popd >/dev/null
68 |   git add package.json package-lock.json packages/convex-helpers/package.json
69 |   # If there's nothing to commit, continue
70 |   git commit -m "npm $version" || true
71 |   git tag "npm/$version"
72 |   git push origin "npm/$version"
73 |   git push
74 | else
75 |   echo "Aborted."
76 | fi
77 | 


--------------------------------------------------------------------------------
/convex/testingFunctions.ts:
--------------------------------------------------------------------------------
 1 | import {
 2 |   customAction,
 3 |   customMutation,
 4 |   customQuery,
 5 | } from "convex-helpers/server/customFunctions";
 6 | import { action, mutation, query } from "./_generated/server";
 7 | import schema from "./schema";
 8 | 
 9 | // Wrappers to use for function that should only be called from tests
10 | export const testingQuery = customQuery(query, {
11 |   args: {},
12 |   input: async (_ctx, _args) => {
13 |     if (process.env.IS_TEST === undefined) {
14 |       throw new Error(
15 |         "Calling a test only function in an unexpected environment",
16 |       );
17 |     }
18 |     return { ctx: {}, args: {} };
19 |   },
20 | });
21 | 
22 | export const testingMutation = customMutation(mutation, {
23 |   args: {},
24 |   input: async (_ctx, _args, { devOnly }: { devOnly: boolean }) => {
25 |     if (process.env.IS_TEST === undefined) {
26 |       throw new Error(
27 |         "Calling a test only function in an unexpected environment",
28 |       );
29 |     }
30 |     if (devOnly && process.env.IS_PROD) {
31 |       throw new Error("This function is only available in development");
32 |     }
33 |     return { ctx: {}, args: {} };
34 |   },
35 | });
36 | 
37 | export const testingAction = customAction(action, {
38 |   args: {},
39 |   input: async (_ctx, _args) => {
40 |     if (process.env.IS_TEST === undefined) {
41 |       throw new Error(
42 |         "Calling a test only function in an unexpected environment",
43 |       );
44 |     }
45 |     return { ctx: {}, args: {} };
46 |   },
47 | });
48 | 
49 | export const clearAll = testingMutation({
50 |   devOnly: true,
51 |   handler: async ({ db, scheduler, storage }) => {
52 |     for (const table of Object.keys(schema.tables)) {
53 |       const docs = await db.query(table as any).collect();
54 |       await Promise.all(docs.map((doc) => db.delete(doc._id)));
55 |     }
56 |     const scheduled = await db.system.query("_scheduled_functions").collect();
57 |     await Promise.all(scheduled.map((s) => scheduler.cancel(s._id)));
58 |     const storedFiles = await db.system.query("_storage").collect();
59 |     await Promise.all(storedFiles.map((s) => storage.delete(s._id)));
60 |   },
61 | });
62 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
  1 | .npmrc
  2 | 
  3 | # Or our local env
  4 | .env.local
  5 | 
  6 | # Logs
  7 | logs
  8 | *.log
  9 | npm-debug.log*
 10 | yarn-debug.log*
 11 | yarn-error.log*
 12 | lerna-debug.log*
 13 | 
 14 | # Diagnostic reports (https://nodejs.org/api/report.html)
 15 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
 16 | 
 17 | # Runtime data
 18 | pids
 19 | *.pid
 20 | *.seed
 21 | *.pid.lock
 22 | 
 23 | # Directory for instrumented libs generated by jscoverage/JSCover
 24 | lib-cov
 25 | 
 26 | # Coverage directory used by tools like istanbul
 27 | coverage
 28 | *.lcov
 29 | 
 30 | # nyc test coverage
 31 | .nyc_output
 32 | 
 33 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
 34 | .grunt
 35 | 
 36 | # Bower dependency directory (https://bower.io/)
 37 | bower_components
 38 | 
 39 | # node-waf configuration
 40 | .lock-wscript
 41 | 
 42 | # Compiled binary addons (https://nodejs.org/api/addons.html)
 43 | build/Release
 44 | 
 45 | # Dependency directories
 46 | node_modules/
 47 | jspm_packages/
 48 | 
 49 | # TypeScript v1 declaration files
 50 | typings/
 51 | 
 52 | # TypeScript cache
 53 | *.tsbuildinfo
 54 | 
 55 | # Optional npm cache directory
 56 | .npm
 57 | 
 58 | # Optional eslint cache
 59 | .eslintcache
 60 | 
 61 | # Microbundle cache
 62 | .rpt2_cache/
 63 | .rts2_cache_cjs/
 64 | .rts2_cache_es/
 65 | .rts2_cache_umd/
 66 | 
 67 | # Optional REPL history
 68 | .node_repl_history
 69 | 
 70 | # Output of 'npm pack'
 71 | *.tgz
 72 | 
 73 | # Yarn Integrity file
 74 | .yarn-integrity
 75 | 
 76 | # dotenv environment variables file
 77 | .env
 78 | .env.test
 79 | 
 80 | # parcel-bundler cache (https://parceljs.org/)
 81 | .cache
 82 | 
 83 | # Next.js build output
 84 | .next
 85 | 
 86 | # Nuxt.js build / generate output
 87 | .nuxt
 88 | dist
 89 | 
 90 | # Gatsby files
 91 | .cache/
 92 | # Comment in the public line in if your project uses Gatsby and *not* Next.js
 93 | # https://nextjs.org/blog/next-9-1#public-directory-support
 94 | # public
 95 | 
 96 | # vuepress build output
 97 | .vuepress/dist
 98 | 
 99 | # Serverless directories
100 | .serverless/
101 | 
102 | # FuseBox cache
103 | .fusebox/
104 | 
105 | # DynamoDB Local files
106 | .dynamodb/
107 | 
108 | # TernJS port file
109 | .tern-port
110 | tsconfig.tsbuildinfo
111 | convex-local-backend*
112 | .mypy_cache
113 | __pycache__/
114 | 


--------------------------------------------------------------------------------
/src/fakeConvexClient/fakeConvexClient.js:
--------------------------------------------------------------------------------
 1 | import { getFunctionName } from "convex/server";
 2 | 
 3 | // A Mock convex client
 4 | export class ConvexReactClientFake {
 5 |   constructor() {
 6 |     this.queries = {};
 7 |     this.mutations = {};
 8 |     this.actions = {};
 9 |   }
10 | 
11 |   registerQueryFake(funcRef, impl) {
12 |     this.queries[getFunctionName(funcRef)] = impl;
13 |   }
14 |   registerMutationFake(funcRef, impl) {
15 |     this.mutations[getFunctionName(funcRef)] = impl;
16 |   }
17 | 
18 |   async setAuth() {
19 |     throw new Error("Auth is not implemented");
20 |   }
21 | 
22 |   clearAuth() {
23 |     throw new Error("Auth is not implemented");
24 |   }
25 | 
26 |   watchQuery(functionReference, args) {
27 |     const name = getFunctionName(functionReference);
28 |     return {
29 |       localQueryResult: () => {
30 |         const query = this.queries && this.queries[name];
31 |         if (query) {
32 |           return query(args);
33 |         }
34 |         throw new Error(
35 |           `Unexpected query: ${name}. Try providing a function for this query in the mock client constructor.`,
36 |         );
37 |       },
38 |       onUpdate: () => () => ({
39 |         unsubscribe: () => null,
40 |       }),
41 |       journal: () => {
42 |         throw new Error("Pagination is not implemented");
43 |       },
44 |     };
45 |   }
46 | 
47 |   mutation(functionReference, args) {
48 |     const name = getFunctionName(functionReference);
49 |     const mutation = this.mutations && this.mutations[name];
50 |     if (mutation) {
51 |       return mutation(args);
52 |     }
53 |     throw new Error(
54 |       `Unexpected mutation: ${name}. Try providing a function for this mutation in the mock client constructor.`,
55 |     );
56 |   }
57 | 
58 |   action(functionReference, args) {
59 |     const name = getFunctionName(functionReference);
60 |     const action = this.actions && this.actions[name];
61 |     if (action) {
62 |       return action(args);
63 |     }
64 |     throw new Error(
65 |       `Unexpected action: ${name}. Try providing a function for this actionin the mock client constructor.`,
66 |     );
67 |   }
68 | 
69 |   connectionState() {
70 |     return {
71 |       hasInflightRequests: false,
72 |       isWebSocketConnected: true,
73 |     };
74 |   }
75 | 
76 |   close() {
77 |     return Promise.resolve();
78 |   }
79 | }
80 | 


--------------------------------------------------------------------------------
/convex/_generated/api.d.ts:
--------------------------------------------------------------------------------
 1 | /* eslint-disable */
 2 | /**
 3 |  * Generated `api` utility.
 4 |  *
 5 |  * THIS CODE IS AUTOMATICALLY GENERATED.
 6 |  *
 7 |  * To regenerate, run `npx convex dev`.
 8 |  * @module
 9 |  */
10 | 
11 | import type * as counter from "../counter.js";
12 | import type * as http from "../http.js";
13 | import type * as migrationsExample from "../migrationsExample.js";
14 | import type * as presence from "../presence.js";
15 | import type * as relationshipsExample from "../relationshipsExample.js";
16 | import type * as retriesExample from "../retriesExample.js";
17 | import type * as rlsExample from "../rlsExample.js";
18 | import type * as sessionsExample from "../sessionsExample.js";
19 | import type * as streamsExample from "../streamsExample.js";
20 | import type * as testingFunctions from "../testingFunctions.js";
21 | import type * as triggersExample from "../triggersExample.js";
22 | import type * as zodFunctionsExample from "../zodFunctionsExample.js";
23 | 
24 | import type {
25 |   ApiFromModules,
26 |   FilterApi,
27 |   FunctionReference,
28 | } from "convex/server";
29 | 
30 | declare const fullApi: ApiFromModules<{
31 |   counter: typeof counter;
32 |   http: typeof http;
33 |   migrationsExample: typeof migrationsExample;
34 |   presence: typeof presence;
35 |   relationshipsExample: typeof relationshipsExample;
36 |   retriesExample: typeof retriesExample;
37 |   rlsExample: typeof rlsExample;
38 |   sessionsExample: typeof sessionsExample;
39 |   streamsExample: typeof streamsExample;
40 |   testingFunctions: typeof testingFunctions;
41 |   triggersExample: typeof triggersExample;
42 |   zodFunctionsExample: typeof zodFunctionsExample;
43 | }>;
44 | 
45 | /**
46 |  * A utility for referencing Convex functions in your app's public API.
47 |  *
48 |  * Usage:
49 |  * ```js
50 |  * const myFunctionReference = api.myModule.myFunction;
51 |  * ```
52 |  */
53 | export declare const api: FilterApi<
54 |   typeof fullApi,
55 |   FunctionReference<any, "public">
56 | >;
57 | 
58 | /**
59 |  * A utility for referencing Convex functions in your app's internal API.
60 |  *
61 |  * Usage:
62 |  * ```js
63 |  * const myFunctionReference = internal.myModule.myFunction;
64 |  * ```
65 |  */
66 | export declare const internal: FilterApi<
67 |   typeof fullApi,
68 |   FunctionReference<any, "internal">
69 | >;
70 | 
71 | export declare const components: {};
72 | 


--------------------------------------------------------------------------------
/src/index.css:
--------------------------------------------------------------------------------
  1 | /* reset */
  2 | * {
  3 |   margin: 0;
  4 |   padding: 0;
  5 |   border: 0;
  6 |   line-height: 1.5;
  7 | }
  8 | 
  9 | body {
 10 |   font-family:
 11 |     system-ui, "Segoe UI", Roboto, "Helvetica Neue", helvetica, sans-serif;
 12 | }
 13 | 
 14 | main {
 15 |   padding-top: 1em;
 16 |   padding-bottom: 1em;
 17 |   width: min(800px, 95vw);
 18 |   margin: 0 auto;
 19 | }
 20 | 
 21 | h1 {
 22 |   text-align: center;
 23 |   margin-bottom: 8px;
 24 |   font-size: 1.8em;
 25 |   font-weight: 500;
 26 | }
 27 | 
 28 | .badge {
 29 |   text-align: center;
 30 |   margin-bottom: 16px;
 31 | }
 32 | .badge span {
 33 |   background-color: #212529;
 34 |   color: #ffffff;
 35 |   border-radius: 6px;
 36 |   font-weight: bold;
 37 |   padding: 4px 8px 4px 8px;
 38 |   font-size: 0.75em;
 39 | }
 40 | 
 41 | ul {
 42 |   margin: 8px;
 43 |   border-radius: 8px;
 44 |   border: solid 1px lightgray;
 45 |   box-shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);
 46 | }
 47 | 
 48 | ul:empty {
 49 |   display: none;
 50 | }
 51 | 
 52 | li {
 53 |   display: flex;
 54 |   justify-content: flex-start;
 55 |   padding: 8px 16px 8px 16px;
 56 |   border-bottom: solid 1px lightgray;
 57 |   font-size: 16px;
 58 | }
 59 | 
 60 | li:last-child {
 61 |   border: 0;
 62 | }
 63 | 
 64 | li span:nth-child(1) {
 65 |   font-weight: bold;
 66 |   margin-right: 4px;
 67 |   white-space: nowrap;
 68 | }
 69 | li span:nth-child(2) {
 70 |   margin-right: 4px;
 71 |   word-break: break-word;
 72 | }
 73 | li span:nth-child(3) {
 74 |   color: #6c757d;
 75 |   margin-left: auto;
 76 |   white-space: nowrap;
 77 | }
 78 | 
 79 | form {
 80 |   display: flex;
 81 |   justify-content: center;
 82 | }
 83 | 
 84 | input:not([type]) {
 85 |   padding: 6px 12px 6px 12px;
 86 |   color: rgb(33, 37, 41);
 87 |   border: solid 1px rgb(206, 212, 218);
 88 |   border-radius: 8px;
 89 |   font-size: 16px;
 90 | }
 91 | 
 92 | input[type="submit"],
 93 | button {
 94 |   margin-left: 4px;
 95 |   background: lightblue;
 96 |   color: white;
 97 |   padding: 6px 12px 6px 12px;
 98 |   border-radius: 8px;
 99 |   font-size: 16px;
100 |   background-color: rgb(49, 108, 244);
101 | }
102 | 
103 | input[type="submit"]:hover,
104 | button:hover {
105 |   background-color: rgb(41, 93, 207);
106 | }
107 | 
108 | input[type="submit"]:disabled,
109 | button:disabled {
110 |   background-color: rgb(122, 160, 248);
111 | }
112 | 


--------------------------------------------------------------------------------
/src/hooks/useStableQuery.ts:
--------------------------------------------------------------------------------
 1 | import { useQuery, usePaginatedQuery } from "convex/react";
 2 | import { useRef } from "react";
 3 | 
 4 | /**
 5 |  * Drop-in replacement for useQuery intended to be used with a parametrized query.
 6 |  * Unlike useQuery, useStableQuery does not return undefined while loading new
 7 |  * data when the query arguments change, but instead will continue to return
 8 |  * the previously loaded data until the new data has finished loading.
 9 |  *
10 |  * See https://stack.convex.dev/help-my-app-is-overreacting for details.
11 |  *
12 |  * @param name - string naming the query function
13 |  * @param ...args - arguments to be passed to the query function
14 |  * @returns UseQueryResult
15 |  */
16 | export const useStableQuery = ((name, ...args) => {
17 |   const result = useQuery(name, ...args);
18 |   const stored = useRef(result); // ref objects are stable between rerenders
19 | 
20 |   // result is only undefined while data is loading
21 |   // if a freshly loaded result is available, use the ref to store it
22 |   if (result !== undefined) {
23 |     stored.current = result;
24 |   }
25 | 
26 |   // undefined on first load, stale data while loading, fresh data after loading
27 |   return stored.current;
28 | }) as typeof useQuery;
29 | 
30 | /**
31 |  * Drop-in replacement for usePaginatedQuery for use with a parametrized query.
32 |  * Unlike usePaginatedQuery, when query arguments change useStablePaginatedQuery
33 |  * does not return empty results and 'LoadingMore' status. Instead, it continues
34 |  * to return the previously loaded results until the new results have finished
35 |  * loading.
36 |  *
37 |  * See https://stack.convex.dev/help-my-app-is-overreacting for details.
38 |  *
39 |  * @param name - string naming the query function
40 |  * @param ...args - arguments to be passed to the query function
41 |  * @returns UsePaginatedQueryResult
42 |  */
43 | export const useStablePaginatedQuery = ((name, ...args) => {
44 |   const result = usePaginatedQuery(name, ...args);
45 |   const stored = useRef(result); // ref objects are stable between rerenders
46 | 
47 |   // If data is still loading, wait and do nothing
48 |   // If data has finished loading, store the result
49 |   if (result.status !== "LoadingMore" && result.status !== "LoadingFirstPage") {
50 |     stored.current = result;
51 |   }
52 | 
53 |   return stored.current;
54 | }) as typeof usePaginatedQuery;
55 | 


--------------------------------------------------------------------------------
/Justfile:
--------------------------------------------------------------------------------
 1 | set fallback := true
 2 | set shell := ["bash", "-uc"]
 3 | set windows-shell := ["sh", "-uc"]
 4 | 
 5 | # `just --list` (or just `just`) will print all the recipes in
 6 | # the current Justfile. `just RECIPE` will run the macro/job.
 7 | #
 8 | # In several places there are recipes for running common scripts or commands.
 9 | # Instead of `Makefile`s, Convex uses Justfiles, which are similar, but avoid
10 | # several footguns associated with Makefiles, since using make as a macro runner
11 | # can sometimes conflict with Makefiles desire to have some rudimentary
12 | # understanding of build artifacts and associated dependencies.
13 | #
14 | # Read up on just here: https://github.com/casey/just
15 | 
16 | _default:
17 |   @just --list
18 | 
19 | set positional-arguments
20 | 
21 | reset-local-backend:
22 |   rm -rf convex_local_storage && rm -f convex_local_backend.sqlite3
23 | 
24 | # (*) Run the open source convex backend, downloading first if necessary.
25 | run-local-backend:
26 |   #!/usr/bin/env sh
27 |   if [ ! -x ./convex-local-backend ]; then
28 |     if [ "$(uname)" == "Darwin" ]; then
29 |       if [ "$(uname -m)" == "arm64" ]; then
30 |         pkg=convex-local-backend-aarch64-apple-darwin.zip
31 |       elif [ "$(uname -m)" == "x86_64" ]; then
32 |         pkg=convex-local-backend-x86_64-apple-darwin.zip
33 |       fi
34 |     elif [ "$(uname -m)" == "x86_64" ]; then
35 |       pkg=convex-local-backend-x86_64-unknown-linux-gnu.zip
36 |     fi
37 |     if [ -z "$pkg" ]; then
38 |       echo "Download or build the convex-local-backend: https://github.com/get-convex/convex-backend"
39 |       exit 1
40 |     fi
41 |     curl  -L -O "https://github.com/get-convex/convex-backend/releases/latest/download/$pkg"
42 |     unzip "$pkg"
43 |   fi
44 |   ./convex-local-backend
45 | 
46 | # Taken from https://github.com/get-convex/convex-backend/blob/main/Justfile
47 | # (*) Run convex CLI commands like `convex dev` against local backend from `just run-local-backend`.
48 | # This uses the default admin key for local backends, which is safe as long as the backend is
49 | # running locally.
50 | convex *ARGS:
51 |   npx convex "$@" --admin-key 0135d8598650f8f5cb0f30c34ec2e2bb62793bc28717c8eb6fb577996d50be5f4281b59181095065c5d0f86a2c31ddbe9b597ec62b47ded69782cd --url "http://127.0.0.1:3210"
52 | 
53 | # Clears a table in the cloud backend.
54 | clear-table *ARGS:
55 |   npx convex import --table "$1" --replace --format jsonLines /dev/null "${@:2}"
56 | 


--------------------------------------------------------------------------------
/convex/streamsExample.ts:
--------------------------------------------------------------------------------
 1 | import { v } from "convex/values";
 2 | import { mutation, query } from "./_generated/server.js";
 3 | import { stream, mergedStream } from "convex-helpers/server/stream";
 4 | import schema from "./schema.js";
 5 | import { paginationOptsValidator } from "convex/server";
 6 | 
 7 | export const getInbox = query({
 8 |   args: {
 9 |     id: v.string(),
10 |     paginationOpts: paginationOptsValidator,
11 |   },
12 |   handler: async (ctx, args) => {
13 |     const messages = await stream(ctx.db, schema)
14 |       .query("privateMessages")
15 |       .withIndex("to", (q) => q.eq("to", args.id))
16 |       .order("desc")
17 |       .paginate(args.paginationOpts);
18 |     return messages;
19 |   },
20 | });
21 | 
22 | export const getOutbox = query({
23 |   args: {
24 |     id: v.string(),
25 |     paginationOpts: paginationOptsValidator,
26 |   },
27 |   handler: async (ctx, args) => {
28 |     const messages = await ctx.db
29 |       .query("privateMessages")
30 |       .withIndex("from", (q) => q.eq("from", args.id))
31 |       .order("desc")
32 |       .paginate(args.paginationOpts);
33 |     return messages;
34 |   },
35 | });
36 | 
37 | export const getMessagesBetween = query({
38 |   args: {
39 |     a: v.string(),
40 |     b: v.string(),
41 |     paginationOpts: paginationOptsValidator,
42 |   },
43 |   handler: async (ctx, args) => {
44 |     const aToB = stream(ctx.db, schema)
45 |       .query("privateMessages")
46 |       .withIndex("from_to", (q) => q.eq("from", args.a).eq("to", args.b))
47 |       .order("desc");
48 |     const bToA = stream(ctx.db, schema)
49 |       .query("privateMessages")
50 |       .withIndex("from_to", (q) => q.eq("from", args.b).eq("to", args.a))
51 |       .order("desc");
52 | 
53 |     // Both indexes have the "sentAt" field after the fields they're doing
54 |     // equality on, so they're both sorted by "sentAt" descending, so they
55 |     // can be merged together.
56 |     const messages = await mergedStream([aToB, bToA], ["sentAt"]).paginate(
57 |       args.paginationOpts,
58 |     );
59 |     return messages;
60 |   },
61 | });
62 | 
63 | export const sendMessage = mutation({
64 |   args: {
65 |     from: v.string(),
66 |     to: v.string(),
67 |     message: v.string(),
68 |   },
69 |   handler: async (ctx, args) => {
70 |     await ctx.db.insert("privateMessages", {
71 |       from: args.from,
72 |       to: args.to,
73 |       message: args.message,
74 |       sentAt: Date.now(),
75 |     });
76 |   },
77 | });
78 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/server/filter.test.ts:
--------------------------------------------------------------------------------
 1 | import { filter } from "./filter.js";
 2 | import { convexTest } from "convex-test";
 3 | import { v } from "convex/values";
 4 | import { expect, test } from "vitest";
 5 | import { defineSchema, defineTable } from "convex/server";
 6 | import { modules } from "./setup.test.js";
 7 | 
 8 | const schema = defineSchema({
 9 |   tableA: defineTable({
10 |     count: v.number(),
11 |   }),
12 |   tableB: defineTable({
13 |     tableAId: v.id("tableA"),
14 |     name: v.string(),
15 |   }),
16 | });
17 | 
18 | test("filter", async () => {
19 |   const t = convexTest(schema, modules);
20 |   await t.run(async (ctx) => {
21 |     for (let i = 0; i < 10; i++) {
22 |       const tableAId = await ctx.db.insert("tableA", { count: i });
23 |       await ctx.db.insert("tableB", { tableAId, name: String(i) });
24 |     }
25 |   });
26 |   const evens = await t.run((ctx) =>
27 |     filter(ctx.db.query("tableA"), (c) => c.count % 2 === 0).collect(),
28 |   );
29 |   expect(evens).toMatchObject([
30 |     { count: 0 },
31 |     { count: 2 },
32 |     { count: 4 },
33 |     { count: 6 },
34 |     { count: 8 },
35 |   ]);
36 |   // For comparison, even filters that were possible before, it's much more
37 |   // readable to use the JavaScript filter.
38 |   const evensBuiltin = await t.run((ctx) =>
39 |     ctx.db
40 |       .query("tableA")
41 |       .filter((q) => q.eq(q.mod(q.field("count"), 2), 0))
42 |       .collect(),
43 |   );
44 |   expect(evens).toMatchObject(evensBuiltin);
45 | 
46 |   const withLookup = await t.run((ctx) =>
47 |     filter(
48 |       ctx.db.query("tableB"),
49 |       async (c) => ((await ctx.db.get(c.tableAId))?.count ?? 0) > 5,
50 |     ).collect(),
51 |   );
52 |   expect(withLookup).toMatchObject([
53 |     { name: "6" },
54 |     { name: "7" },
55 |     { name: "8" },
56 |     { name: "9" },
57 |   ]);
58 | 
59 |   // Check that ordering works, before or after the filter.
60 |   const withOrder = await t.run((ctx) =>
61 |     filter(ctx.db.query("tableA").order("desc"), (c) => c.count > 5).collect(),
62 |   );
63 |   expect(withOrder).toMatchObject([
64 |     { count: 9 },
65 |     { count: 8 },
66 |     { count: 7 },
67 |     { count: 6 },
68 |   ]);
69 | 
70 |   const withOrderAfter = await t.run((ctx) =>
71 |     filter(ctx.db.query("tableA"), (c) => c.count > 5)
72 |       .order("desc")
73 |       .collect(),
74 |   );
75 |   expect(withOrderAfter).toMatchObject([
76 |     { count: 9 },
77 |     { count: 8 },
78 |     { count: 7 },
79 |     { count: 6 },
80 |   ]);
81 | });
82 | 


--------------------------------------------------------------------------------
/convex/migrationsExample.ts:
--------------------------------------------------------------------------------
 1 | import {
 2 |   cancelMigration,
 3 |   getStatus,
 4 |   makeMigration,
 5 |   MigrationStatus,
 6 |   startMigration,
 7 |   startMigrationsSerially,
 8 | } from "convex-helpers/server/migrations";
 9 | import { internalQuery } from "./_generated/server";
10 | import { internal } from "./_generated/api";
11 | import { v } from "convex/values";
12 | // Importing from triggers so any changes here will run triggers
13 | import { internalMutation } from "./triggersExample";
14 | 
15 | const migration = makeMigration(internalMutation, {
16 |   migrationTable: "migrations",
17 | });
18 | 
19 | export const increment = migration({
20 |   table: "counter_table",
21 |   migrateOne: (ctx, doc) => ({
22 |     counter: doc.counter + 1,
23 |   }),
24 |   customRange: (q) =>
25 |     q.withIndex("by_creation_time", (q) =>
26 |       q.lt("_creationTime", Date.now() - 1_000_000),
27 |     ),
28 | });
29 | 
30 | export const cleanUpBrokenRefs = migration({
31 |   table: "join_table_example",
32 |   migrateOne: async (ctx, doc) => {
33 |     const user = await ctx.db.get(doc.userId);
34 |     const presence = await ctx.db.get(doc.presenceId);
35 |     if (!user || !presence) {
36 |       await ctx.db.delete(doc._id);
37 |     }
38 |   },
39 | });
40 | 
41 | export const callOneDirectly = internalMutation({
42 |   args: {},
43 |   handler: async (ctx, _args) => {
44 |     // can run a migration directly within a function:
45 |     await startMigration(ctx, internal.migrationsExample.increment, {
46 |       startCursor: null,
47 |       batchSize: 10,
48 |     });
49 |   },
50 | });
51 | 
52 | // Or run all specified ones from a general script
53 | const standardMigrations = [
54 |   internal.migrationsExample.increment,
55 |   internal.migrationsExample.cleanUpBrokenRefs,
56 | ];
57 | 
58 | export const status = internalQuery({
59 |   args: {},
60 |   handler: async (ctx): Promise<MigrationStatus<"migrations">[]> => {
61 |     return await getStatus(ctx, { migrationTable: "migrations" });
62 |   },
63 | });
64 | 
65 | export const cancel = internalMutation({
66 |   args: { fn: v.string() },
67 |   handler: async (ctx, { fn }) => {
68 |     return await cancelMigration(ctx, "migrations", fn);
69 |   },
70 | });
71 | 
72 | // Incorporate into some general setup script
73 | // Call from CLI: `npx convex run migrationsExample`
74 | // As part of a deploy script:
75 | //  `npx convex deploy && npx convex run --prod migrationsExample`
76 | export default internalMutation(async (ctx) => {
77 |   await startMigrationsSerially(ctx, standardMigrations);
78 | });
79 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/browser.ts:
--------------------------------------------------------------------------------
 1 | import type { BetterOmit, EmptyObject } from "./index.js";
 2 | import type { ConvexClient, ConvexHttpClient } from "convex/browser";
 3 | import type { FunctionArgs, FunctionReturnType } from "convex/server";
 4 | import type { FunctionReference } from "convex/server";
 5 | import type { Value } from "convex/values";
 6 | 
 7 | export type ArgsArray<
 8 |   Injected extends Record<string, Value>,
 9 |   FullArgs extends Injected,
10 | > = keyof FullArgs extends keyof Injected
11 |   ? [args?: EmptyObject]
12 |   : [args: BetterOmit<FullArgs, keyof Injected>];
13 | 
14 | /**
15 |  * Inject arguments into a Convex client's calls.
16 |  *
17 |  * Useful when you want to pass an API key or session ID on many calls and don't
18 |  * want to pass the value around and add it to the arguments explicitly.
19 |  *
20 |  * e.g.
21 |  * ```ts
22 |  * const client = new ConvexClient(process.env.CONVEX_URL!);
23 |  * const apiClient = withArgs(client, { apiKey: process.env.API_KEY! });
24 |  *
25 |  * const result = await apiClient.query(api.foo.bar, { ...other args });
26 |  * ```
27 |  *
28 |  * @param client A ConvexClient instance
29 |  * @param injectedArgs Arguments to inject into each query/mutation/action call.
30 |  * @returns { query, mutation, action } functions with the injected arguments
31 |  */
32 | export function withArgs<A extends Record<string, Value>>(
33 |   client: ConvexClient | ConvexHttpClient,
34 |   injectedArgs: A,
35 | ) {
36 |   return {
37 |     query<Query extends FunctionReference<"query">>(
38 |       query: Query,
39 |       ...args: ArgsArray<A, FunctionArgs<Query>>
40 |     ): Promise<Awaited<FunctionReturnType<Query>>> {
41 |       return client.query(query, {
42 |         ...(args[0] ?? {}),
43 |         ...injectedArgs,
44 |       } as FunctionArgs<Query>);
45 |     },
46 |     mutation<Mutation extends FunctionReference<"mutation">>(
47 |       mutation: Mutation,
48 |       ...args: ArgsArray<A, FunctionArgs<Mutation>>
49 |     ): Promise<Awaited<FunctionReturnType<Mutation>>> {
50 |       return client.mutation(mutation, {
51 |         ...(args[0] ?? {}),
52 |         ...injectedArgs,
53 |       } as FunctionArgs<Mutation>);
54 |     },
55 |     action<Action extends FunctionReference<"action">>(
56 |       action: Action,
57 |       ...args: ArgsArray<A, FunctionArgs<Action>>
58 |     ): Promise<Awaited<FunctionReturnType<Action>>> {
59 |       return client.action(action, {
60 |         ...(args[0] ?? {}),
61 |         ...injectedArgs,
62 |       } as FunctionArgs<Action>);
63 |     },
64 |   };
65 | }
66 | 


--------------------------------------------------------------------------------
/convex/counter.ts:
--------------------------------------------------------------------------------
 1 | import { paginationOptsValidator } from "convex/server";
 2 | import { action, query } from "./_generated/server";
 3 | // Using mutation from triggersExample so any changes will run triggers
 4 | import { mutation } from "./triggersExample";
 5 | import { v } from "convex/values";
 6 | 
 7 | export const getCounter = query({
 8 |   args: { counterName: v.string() },
 9 |   returns: v.number(),
10 |   handler: async (ctx, { counterName }) => {
11 |     const counterDoc = await ctx.db
12 |       .query("counter_table")
13 |       .filter((q) => q.eq(q.field("name"), counterName))
14 |       .first();
15 |     return counterDoc === null ? 0 : counterDoc.counter;
16 |   },
17 | });
18 | 
19 | export const getCounters = query({
20 |   args: { count: v.number() },
21 |   handler: async ({ db }, { count }) => {
22 |     return db.query("counter_table").order("desc").take(count);
23 |   },
24 | });
25 | 
26 | export const getCountersPaginated = query({
27 |   args: { paginationOpts: paginationOptsValidator },
28 |   handler: async ({ db }, { paginationOpts }) => {
29 |     return db.query("counter_table").order("desc").paginate(paginationOpts);
30 |   },
31 | });
32 | 
33 | export const getCounterOrThrow = query({
34 |   args: {
35 |     counterName: v.string(),
36 |   },
37 |   handler: async (ctx, { counterName }): Promise<number> => {
38 |     const counterDoc = await ctx.db
39 |       .query("counter_table")
40 |       .filter((q) => q.eq(q.field("name"), counterName))
41 |       .first();
42 |     if (counterDoc === null) {
43 |       throw new Error("Counter not found");
44 |     }
45 |     return counterDoc.counter;
46 |   },
47 | });
48 | 
49 | export const upload = action({
50 |   args: { data: v.any() },
51 |   handler: async (ctx, args) => {
52 |     const id = await ctx.storage.store(args.data);
53 |     console.log(id);
54 |     return id;
55 |   },
56 | });
57 | 
58 | export const incrementCounter = mutation({
59 |   args: { counterName: v.string(), increment: v.number() },
60 |   handler: async (
61 |     ctx,
62 |     { counterName, increment }: { counterName: string; increment: number },
63 |   ) => {
64 |     const counterDoc = await ctx.db
65 |       .query("counter_table")
66 |       .filter((q) => q.eq(q.field("name"), counterName))
67 |       .first();
68 |     if (counterDoc === null) {
69 |       await ctx.db.insert("counter_table", {
70 |         name: counterName,
71 |         counter: increment,
72 |       });
73 |     } else {
74 |       counterDoc.counter += increment;
75 |       await ctx.db.replace(counterDoc._id, counterDoc);
76 |     }
77 |   },
78 | });
79 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/index.test.ts:
--------------------------------------------------------------------------------
 1 | import { v } from "convex/values";
 2 | import { withoutSystemFields, pick, omit } from "./index.js";
 3 | import { test, expect, expectTypeOf } from "vitest";
 4 | 
 5 | test("pick", () => {
 6 |   const obj = { a: "a", b: "b", c: "c" };
 7 |   const picked = pick(obj, ["a", "b"]);
 8 |   expect(picked).toEqual({ a: "a", b: "b" });
 9 |   expect(pick(obj, [])).toEqual({});
10 |   expect(pick(obj, ["a", "b", "c"])).toEqual({ a: "a", b: "b", c: "c" });
11 |   expect(pick(obj, ["a", "b", "c", "d" as any])).toEqual({
12 |     a: "a",
13 |     b: "b",
14 |     c: "c",
15 |   });
16 | 
17 |   expectTypeOf(picked).toEqualTypeOf<{ a: string; b: string }>();
18 | });
19 | 
20 | test("omit", () => {
21 |   const obj = { a: "a", b: "b", c: "c" };
22 |   const omitted = omit(obj, ["a", "b"]);
23 |   expect(omitted).toEqual({ c: "c" });
24 |   expect(omit(obj, [])).toEqual({ a: "a", b: "b", c: "c" });
25 |   expect(omit(obj, ["a", "b", "c", "d" as any])).toEqual({});
26 | 
27 |   expectTypeOf(omitted).toEqualTypeOf<{ c: string }>();
28 | });
29 | 
30 | test("withoutSystemFields", () => {
31 |   const obj = { _id: "1", _creationTime: 1, a: "a" };
32 |   const without = withoutSystemFields(obj);
33 |   expect(without).toEqual({ a: "a" });
34 | });
35 | 
36 | test("withoutSystemFields when fields aren't present", () => {
37 |   const obj = { a: "a" };
38 |   const without = withoutSystemFields(obj);
39 |   expect(without).toEqual({ a: "a" });
40 | });
41 | 
42 | test("withoutSystemFields type when it's a union", () => {
43 |   const obj = { a: "a" } as
44 |     | { a: string }
45 |     | { _id: string; _creationTime: number };
46 |   const without = withoutSystemFields(obj);
47 |   expect(without).toEqual({ a: "a" });
48 |   // eslint-disable-next-line @typescript-eslint/no-empty-object-type
49 |   expectTypeOf(without).toEqualTypeOf<{ a: string } | {}>();
50 |   const obj2 = { _id: "1", _creationTime: 1, a: "a" } as
51 |     | { _id: string; _creationTime: number; a: string }
52 |     | { _id: string; _creationTime: number; b: string };
53 |   const without2 = withoutSystemFields(obj2);
54 |   expect(without2).toEqual({ a: "a" });
55 |   expectTypeOf(without2).toEqualTypeOf<{ a: string } | { b: string }>();
56 | });
57 | 
58 | test("withoutSystemFields works on validators too", () => {
59 |   const validator = v.object({
60 |     _id: v.string(),
61 |     _creationTime: v.number(),
62 |     a: v.string(),
63 |   });
64 |   const { _id, _creationTime, ..._rest } = validator.fields;
65 |   const without = withoutSystemFields(validator.fields);
66 |   expectTypeOf(without).toEqualTypeOf<typeof _rest>();
67 | });
68 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/server/compare.ts:
--------------------------------------------------------------------------------
 1 | import type { Value } from "convex/values";
 2 | 
 3 | // Returns -1 if k1 < k2
 4 | // Returns 0 if k1 === k2
 5 | // Returns 1 if k1 > k2
 6 | export function compareValues(k1: Value | undefined, k2: Value | undefined) {
 7 |   return compareAsTuples(makeComparable(k1), makeComparable(k2));
 8 | }
 9 | 
10 | function compareAsTuples<T>(a: [number, T], b: [number, T]): number {
11 |   if (a[0] === b[0]) {
12 |     return compareSameTypeValues(a[1], b[1]);
13 |   } else if (a[0] < b[0]) {
14 |     return -1;
15 |   }
16 |   return 1;
17 | }
18 | 
19 | function compareSameTypeValues<T>(v1: T, v2: T): number {
20 |   if (v1 === undefined || v1 === null) {
21 |     return 0;
22 |   }
23 |   if (
24 |     typeof v1 === "bigint" ||
25 |     typeof v1 === "number" ||
26 |     typeof v1 === "boolean" ||
27 |     typeof v1 === "string"
28 |   ) {
29 |     return v1 < v2 ? -1 : v1 === v2 ? 0 : 1;
30 |   }
31 |   if (!Array.isArray(v1) || !Array.isArray(v2)) {
32 |     throw new Error(`Unexpected type ${v1 as any}`);
33 |   }
34 |   for (let i = 0; i < v1.length && i < v2.length; i++) {
35 |     const cmp = compareAsTuples(v1[i], v2[i]);
36 |     if (cmp !== 0) {
37 |       return cmp;
38 |     }
39 |   }
40 |   if (v1.length < v2.length) {
41 |     return -1;
42 |   }
43 |   if (v1.length > v2.length) {
44 |     return 1;
45 |   }
46 |   return 0;
47 | }
48 | 
49 | // Returns an array which can be compared to other arrays as if they were tuples.
50 | // For example, [1, null] < [2, 1n] means null sorts before all bigints
51 | // And [3, 5] < [3, 6] means floats sort as expected
52 | // And [7, [[5, "a"]]] < [7, [[5, "a"], [5, "b"]]] means arrays sort as expected
53 | function makeComparable(v: Value | undefined): [number, any] {
54 |   if (v === undefined) {
55 |     return [0, undefined];
56 |   }
57 |   if (v === null) {
58 |     return [1, null];
59 |   }
60 |   if (typeof v === "bigint") {
61 |     return [2, v];
62 |   }
63 |   if (typeof v === "number") {
64 |     if (isNaN(v)) {
65 |       // Consider all NaNs to be equal.
66 |       return [3.5, 0];
67 |     }
68 |     return [3, v];
69 |   }
70 |   if (typeof v === "boolean") {
71 |     return [4, v];
72 |   }
73 |   if (typeof v === "string") {
74 |     return [5, v];
75 |   }
76 |   if (v instanceof ArrayBuffer) {
77 |     return [6, Array.from(new Uint8Array(v)).map(makeComparable)];
78 |   }
79 |   if (Array.isArray(v)) {
80 |     return [7, v.map(makeComparable)];
81 |   }
82 |   // Otherwise, it's an POJO.
83 |   const keys = Object.keys(v).sort();
84 |   const pojo: Value[] = keys.map((k) => [k, v[k]!]);
85 |   return [8, pojo.map(makeComparable)];
86 | }
87 | 


--------------------------------------------------------------------------------
/eslint.config.mjs:
--------------------------------------------------------------------------------
 1 | import globals from "globals";
 2 | import pluginJs from "@eslint/js";
 3 | import tseslint from "typescript-eslint";
 4 | import reactPlugin from "eslint-plugin-react";
 5 | import reactHooks from "eslint-plugin-react-hooks";
 6 | import convexPlugin from "@convex-dev/eslint-plugin";
 7 | 
 8 | export default [
 9 |   { files: ["src/**/*.{js,mjs,cjs,ts,tsx}", "convex/**/*.{ts,tsx}"] },
10 |   {
11 |     ignores: [
12 |       "dist/**",
13 |       "packages/convex-helpers/dist/**",
14 |       "packages/convex-helpers/generate-exports.mjs",
15 |       "src/fakeConvexClient/fakeConvexClient.js",
16 |       "backendHarness.js",
17 |       "eslint.config.mjs",
18 |       "convex/vitest.config.mts",
19 |       "setup.cjs",
20 |       "**/_generated/",
21 |       "vite.config.mts",
22 |       "vitest.workspace.ts",
23 |     ],
24 |   },
25 |   {
26 |     files: ["convex/**/*.ts", "packages/convex-helpers/server/**/*.ts"],
27 |     ignores: ["packages/convex-helpers/server/_generated/**/*"],
28 |     plugins: {
29 |       "@convex-dev": convexPlugin,
30 |     },
31 |     rules: convexPlugin.configs.recommended[0].rules,
32 |   },
33 |   {
34 |     languageOptions: {
35 |       globals: globals.worker,
36 |       parser: tseslint.parser,
37 | 
38 |       parserOptions: {
39 |         project: ["./tsconfig.json", "./packages/convex-helpers/tsconfig.json"],
40 |         tsconfigRootDir: import.meta.dirname,
41 |       },
42 |     },
43 |   },
44 |   pluginJs.configs.recommended,
45 |   ...tseslint.configs.recommended,
46 |   {
47 |     files: [
48 |       "src/react/**/*.{jsx,tsx}",
49 |       "src/react/**/*.js",
50 |       "src/react/**/*.ts",
51 |     ],
52 |     plugins: { react: reactPlugin, "react-hooks": reactHooks },
53 |     settings: {
54 |       react: {
55 |         version: "detect",
56 |       },
57 |     },
58 |     rules: {
59 |       ...reactPlugin.configs["recommended"].rules,
60 |       "react/jsx-uses-react": "off",
61 |       "react/react-in-jsx-scope": "off",
62 |       "react/prop-types": "off",
63 |       "react-hooks/rules-of-hooks": "error",
64 |       "react-hooks/exhaustive-deps": "warn",
65 |     },
66 |   },
67 |   {
68 |     rules: {
69 |       "@typescript-eslint/no-floating-promises": "error",
70 |       "eslint-comments/no-unused-disable": "off",
71 |       "@typescript-eslint/no-explicit-any": "off",
72 | 
73 |       // allow (_arg: number) => {} and const _foo = 1;
74 |       "no-unused-vars": "off",
75 |       "no-unused-private-class-members": "warn",
76 |       "@typescript-eslint/no-unused-vars": [
77 |         "warn",
78 |         {
79 |           argsIgnorePattern: "^_",
80 |           varsIgnorePattern: "^_",
81 |         },
82 |       ],
83 |     },
84 |   },
85 | ];
86 | 


--------------------------------------------------------------------------------
/src/hooks/useSingleFlight.ts:
--------------------------------------------------------------------------------
 1 | import { useCallback, useRef } from "react";
 2 | 
 3 | /**
 4 |  * Wraps a function to single-flight invocations, using the latest args.
 5 |  *
 6 |  * Generates a function that behaves like the passed in function,
 7 |  * but only one execution runs at a time. If multiple calls are requested
 8 |  * before the current call has finished, it will use the latest arguments
 9 |  * for the next invocation.
10 |  *
11 |  * Note: some requests may never be made. If while a request is in-flight, N
12 |  * requests are made, N-1 of them will never resolve or reject the promise they
13 |  * returned. For most applications this is the desired behavior, but if you need
14 |  * all calls to eventually resolve, you can modify this code. Some behavior you
15 |  * could add, left as an exercise to the reader:
16 |  *   1. Resolve with the previous result when a request is about to be dropped.
17 |  *   2. Resolve all N requests with the result of the next request.
18 |  *   3. Do not return anything, and use this as a fire-and-forget library only.
19 |  *
20 |  * @param fn - Function to be called, with only one request in flight at a time.
21 |  * This must be a stable identifier, e.g. returned from useCallback.
22 |  * @returns Function that can be called whenever, returning a promise that will
23 |  * only resolve or throw if the underlying function gets called.
24 |  */
25 | export default function useSingleFlight<
26 |   F extends (...args: any[]) => Promise<any>,
27 | >(fn: F) {
28 |   const flightStatus = useRef({
29 |     inFlight: false,
30 |     upNext: null as null | {
31 |       fn: F;
32 |       resolve: any;
33 |       reject: any;
34 |       args: Parameters<F>;
35 |     },
36 |   });
37 | 
38 |   return useCallback(
39 |     (...args: Parameters<F>): ReturnType<F> => {
40 |       if (flightStatus.current.inFlight) {
41 |         return new Promise((resolve, reject) => {
42 |           flightStatus.current.upNext = { fn, resolve, reject, args };
43 |         }) as ReturnType<F>;
44 |       }
45 |       flightStatus.current.inFlight = true;
46 |       const firstReq = fn(...args) as ReturnType<F>;
47 |       void (async () => {
48 |         try {
49 |           await firstReq;
50 |         } finally {
51 |           // If it failed, we naively just move on to the next request.
52 |         }
53 |         while (flightStatus.current.upNext) {
54 |           const cur = flightStatus.current.upNext;
55 |           flightStatus.current.upNext = null;
56 |           await cur
57 |             .fn(...cur.args)
58 |             .then(cur.resolve)
59 |             .catch(cur.reject);
60 |         }
61 |         flightStatus.current.inFlight = false;
62 |       })();
63 |       return firstReq;
64 |     },
65 |     [fn],
66 |   );
67 | }
68 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/generate-exports.mjs:
--------------------------------------------------------------------------------
 1 | import fs from "node:fs";
 2 | import path from "node:path";
 3 | import process from "node:process";
 4 | import { fileURLToPath } from "node:url";
 5 | 
 6 | const __dirname = path.dirname(fileURLToPath(new URL(import.meta.url)));
 7 | 
 8 | function directoryContents(dirname) {
 9 |   return fs
10 |     .readdirSync(path.join(__dirname, dirname))
11 |     .filter((filename) => filename.endsWith(".ts") || filename.endsWith(".tsx"))
12 |     .filter((filename) => !filename.includes(".test"))
13 |     .map((filename) => path.join(dirname, filename));
14 | }
15 | 
16 | const EntryPointDirectories = ["react", "react/cache", "server"];
17 | function entryPointFiles() {
18 |   return [
19 |     "./index.ts",
20 |     "./browser.ts",
21 |     "./testing.ts",
22 |     "./validators.ts",
23 |     "./server.ts",
24 |     "./standardSchema.ts",
25 |     "./react.ts",
26 |     ...EntryPointDirectories.map(directoryContents).flat(),
27 |   ];
28 | }
29 | 
30 | function entryPointFromFile(source) {
31 |   let entryPoint = path.join(path.parse(source).dir, path.parse(source).name);
32 | 
33 |   if (path.parse(source).name === "index") {
34 |     entryPoint = path.parse(source).dir;
35 |   }
36 | 
37 |   if (!entryPoint.startsWith(".")) {
38 |     entryPoint = `./${entryPoint}`;
39 |   }
40 | 
41 |   return entryPoint;
42 | }
43 | 
44 | function generateExport(source) {
45 |   let extensionless = path.join(
46 |     path.parse(source).dir,
47 |     path.parse(source).name,
48 |   );
49 | 
50 |   return {
51 |     types: `./${extensionless}.d.ts`,
52 |     default: `./${extensionless}.js`,
53 |   };
54 | }
55 | 
56 | function generateExports() {
57 |   const obj = {};
58 |   for (const entryPoint of entryPointFiles()) {
59 |     obj[entryPointFromFile(entryPoint)] = generateExport(entryPoint);
60 |   }
61 |   for (const entryPointDir of EntryPointDirectories) {
62 |     obj[`./${entryPointDir}/*`] = {
63 |       types: `./${entryPointDir}/*.d.ts`,
64 |       default: `./${entryPointDir}/*.js`,
65 |     };
66 |   }
67 |   return obj;
68 | }
69 | 
70 | function checkPackageJsonExports() {
71 |   const packageJson = JSON.parse(
72 |     fs.readFileSync(path.join(__dirname, "package.json")),
73 |   );
74 |   const actual = packageJson.exports;
75 |   const expected = generateExports();
76 |   if (JSON.stringify(actual) !== JSON.stringify(expected)) {
77 |     packageJson.exports = expected;
78 |     fs.writeFileSync(
79 |       path.join(__dirname, "package.json"),
80 |       JSON.stringify(packageJson, null, 2) + "\n",
81 |     );
82 |     console.error(
83 |       "`package.json` exports are not correct and have been updated. Review and commit the changes",
84 |     );
85 |     process.exit(1);
86 |   }
87 | }
88 | 
89 | checkPackageJsonExports();
90 | 


--------------------------------------------------------------------------------
/convex/rlsExample.ts:
--------------------------------------------------------------------------------
 1 | import { crud } from "convex-helpers/server/crud";
 2 | import {
 3 |   customCtx,
 4 |   customMutation,
 5 |   customQuery,
 6 | } from "convex-helpers/server/customFunctions";
 7 | import {
 8 |   Rules,
 9 |   wrapDatabaseReader,
10 |   wrapDatabaseWriter,
11 | } from "convex-helpers/server/rowLevelSecurity";
12 | import { v } from "convex/values";
13 | import { DataModel } from "./_generated/dataModel";
14 | import { mutation, query, QueryCtx } from "./_generated/server";
15 | import schema from "./schema";
16 | 
17 | async function rlsRules(ctx: QueryCtx) {
18 |   const identity = await ctx.auth.getUserIdentity();
19 |   return {
20 |     users: {
21 |       read: async (_, user) => {
22 |         // Unauthenticated users can only read users over 18
23 |         if (!identity && user.age < 18) return false;
24 |         return true;
25 |       },
26 |       insert: async (_, _user) => {
27 |         return true;
28 |       },
29 |       modify: async (_, user) => {
30 |         if (!identity)
31 |           throw new Error("Must be authenticated to modify a user");
32 |         // Users can only modify their own user
33 |         return user.tokenIdentifier === identity.tokenIdentifier;
34 |       },
35 |     },
36 |   } satisfies Rules<QueryCtx, DataModel>;
37 | }
38 | 
39 | const queryWithRLS = customQuery(
40 |   query,
41 |   customCtx(async (ctx) => ({
42 |     db: wrapDatabaseReader(ctx, ctx.db, await rlsRules(ctx)),
43 |   })),
44 | );
45 | 
46 | const mutationWithRLS = customMutation(
47 |   mutation,
48 |   customCtx(async (ctx) => ({
49 |     db: wrapDatabaseWriter(ctx, ctx.db, await rlsRules(ctx)),
50 |   })),
51 | );
52 | 
53 | // exposing a CRUD interface for the users table.
54 | export const { create, read, update, destroy } = crud(
55 |   schema,
56 |   "users",
57 |   queryWithRLS,
58 |   mutationWithRLS,
59 | );
60 | 
61 | // Example functions that use the RLS rules transparently
62 | export const getMyUser = queryWithRLS(async (ctx) => {
63 |   const identity = await ctx.auth.getUserIdentity();
64 |   if (!identity) return null;
65 |   const me = await ctx.db
66 |     .query("users")
67 |     .withIndex("tokenIdentifier", (q) =>
68 |       q.eq("tokenIdentifier", identity.tokenIdentifier),
69 |     )
70 |     .unique();
71 |   return me;
72 | });
73 | 
74 | export const updateName = mutationWithRLS({
75 |   // Note: it's generally a bad idea to pass your own user's ID
76 |   // instead, you should just pull the user from the auth context
77 |   // but this is just an example to show that this is safe, since the RLS rules
78 |   // will prevent you from modifying other users.
79 |   args: { name: v.string(), userId: v.id("users") },
80 |   handler: async (ctx, { name, userId }) => {
81 |     await ctx.db.patch(userId, { name });
82 |   },
83 | });
84 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/cli/utils.ts:
--------------------------------------------------------------------------------
 1 | import fs from "fs";
 2 | import { spawnSync } from "child_process";
 3 | import chalk from "chalk";
 4 | import type { ValidatorJSON } from "convex/values";
 5 | import path from "path";
 6 | import os from "os";
 7 | 
 8 | type Visibility = { kind: "public" } | { kind: "internal" };
 9 | 
10 | type FunctionType = "Action" | "Mutation" | "Query" | "HttpAction";
11 | 
12 | export type FunctionSpec = {
13 |   url: string;
14 |   functions: AnalyzedFunction[];
15 | };
16 | 
17 | export type AnalyzedFunction = {
18 |   identifier: string;
19 |   functionType: FunctionType;
20 |   visibility: Visibility;
21 |   args: ValidatorJSON | null;
22 |   returns: ValidatorJSON | null;
23 | };
24 | 
25 | export function getFunctionSpec(prod?: boolean, filePath?: string) {
26 |   if (filePath && prod) {
27 |     console.error(`To use the prod flag, you can't provide a file path`);
28 |     process.exit(1);
29 |   }
30 |   let content: string;
31 |   if (filePath && !fs.existsSync(filePath)) {
32 |     console.error(chalk.red(`File ${filePath} not found`));
33 |     process.exit(1);
34 |   }
35 |   if (filePath) {
36 |     content = fs.readFileSync(filePath, "utf-8");
37 |   } else {
38 |     const tempFile = path.join(os.tmpdir(), `function-spec-${Date.now()}.json`);
39 | 
40 |     try {
41 |       const outputFd = fs.openSync(tempFile, "w");
42 |       const flags = prod ? ["--prod"] : [];
43 |       const npxCmd = process.platform === "win32" ? "npx.cmd" : "npx";
44 |       const extraOpts = process.platform === "win32" ? { shell: true } : {};
45 |       const result = spawnSync(npxCmd, ["convex", "function-spec", ...flags], {
46 |         stdio: ["inherit", outputFd, "pipe"],
47 |         encoding: "utf-8",
48 |         ...extraOpts,
49 |       });
50 | 
51 |       fs.closeSync(outputFd);
52 | 
53 |       if (result.status !== 0) {
54 |         throw new Error(result.stderr || "Failed without error message");
55 |       }
56 | 
57 |       content = fs.readFileSync(tempFile, "utf-8");
58 |     } catch (e) {
59 |       if (e instanceof Error) {
60 |         console.error(e.message);
61 |       }
62 |       console.error(
63 |         chalk.red(
64 |           "\nError retrieving function spec from your Convex deployment. " +
65 |             "Confirm that you \nare running this command from within a Convex project.\n",
66 |         ),
67 |       );
68 |       throw e;
69 |     } finally {
70 |       try {
71 |         fs.unlinkSync(tempFile);
72 |       } catch (error) {
73 |         console.warn(
74 |           chalk.yellow(
75 |             `Warning: Failed to delete temporary file ${tempFile}:`,
76 |             error instanceof Error ? error.message : "Unknown error",
77 |           ),
78 |         );
79 |       }
80 |     }
81 |   }
82 | 
83 |   return content;
84 | }
85 | 


--------------------------------------------------------------------------------
/convex/README.md:
--------------------------------------------------------------------------------
 1 | # Welcome to your Convex functions directory!
 2 | 
 3 | Write your Convex functions here.
 4 | See https://docs.convex.dev/functions for more.
 5 | 
 6 | A query function that takes two arguments looks like:
 7 | 
 8 | ```ts
 9 | // functions.js
10 | import { query } from "./_generated/server";
11 | import { v } from "convex/values";
12 | 
13 | export const myQueryFunction = query({
14 |   // Validators for arguments.
15 |   args: {
16 |     first: v.number(),
17 |     second: v.string(),
18 |   },
19 | 
20 |   // Function implementation.
21 |   handler: async (ctx, args) => {
22 |     // Read the database as many times as you need here.
23 |     // See https://docs.convex.dev/database/reading-data.
24 |     const documents = await ctx.db.query("tablename").collect();
25 | 
26 |     // Arguments passed from the client are properties of the args object.
27 |     console.log(args.first, args.second);
28 | 
29 |     // Write arbitrary JavaScript here: filter, aggregate, build derived data,
30 |     // remove non-public properties, or create new objects.
31 |     return documents;
32 |   },
33 | });
34 | ```
35 | 
36 | Using this query function in a React component looks like:
37 | 
38 | ```ts
39 | const data = useQuery(api.functions.myQueryFunction, {
40 |   first: 10,
41 |   second: "hello",
42 | });
43 | ```
44 | 
45 | A mutation function looks like:
46 | 
47 | ```ts
48 | // functions.js
49 | import { mutation } from "./_generated/server";
50 | import { v } from "convex/values";
51 | 
52 | export const myMutationFunction = mutation({
53 |   // Validators for arguments.
54 |   args: {
55 |     first: v.string(),
56 |     second: v.string(),
57 |   },
58 | 
59 |   // Function implementation.
60 |   handler: async (ctx, args) => {
61 |     // Insert or modify documents in the database here.
62 |     // Mutations can also read from the database like queries.
63 |     // See https://docs.convex.dev/database/writing-data.
64 |     const message = { body: args.first, author: args.second };
65 |     const id = await ctx.db.insert("messages", message);
66 | 
67 |     // Optionally, return a value from your mutation.
68 |     return await ctx.db.get(id);
69 |   },
70 | });
71 | ```
72 | 
73 | Using this mutation function in a React component looks like:
74 | 
75 | ```ts
76 | const mutation = useMutation(api.functions.myMutationFunction);
77 | function handleButtonPress() {
78 |   // fire and forget, the most common way to use mutations
79 |   mutation({ first: "Hello!", second: "me" });
80 |   // OR
81 |   // use the result once the mutation has completed
82 |   mutation({ first: "Hello!", second: "me" }).then((result) =>
83 |     console.log(result),
84 |   );
85 | }
86 | ```
87 | 
88 | Use the Convex CLI to push your functions to a deployment. See everything
89 | the Convex CLI can do by running `npx convex -h` in your project root
90 | directory. To learn more, launch the docs with `npx convex docs`.
91 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "convex-helpers-base",
 3 |   "private": "true",
 4 |   "description": "Home to [packages](./packages/) to complement the official convex package.",
 5 |   "scripts": {
 6 |     "init": "convex dev --until-success",
 7 |     "dev": "npm-run-all --parallel --race dev:backend dev:frontend dev:helpers test:watch",
 8 |     "dev:backend": "convex dev",
 9 |     "dev:frontend": "vite",
10 |     "dev:helpers": "cd packages/convex-helpers && npm run dev",
11 |     "predev": "npm run build",
12 |     "format": "prettier --write .",
13 |     "lint": "eslint . && npm run typecheck && prettier --check .",
14 |     "typecheck": "tsc --noEmit && cd packages/convex-helpers && npm run typecheck",
15 |     "build": "cd packages/convex-helpers && npm run build",
16 |     "clean": "rm -rf packages/convex-helpers/dist packages/convex-helpers/tsconfig.tsbuildinfo",
17 |     "pack": "cd packages/convex-helpers/dist && npm pack --pack-destination ../../..",
18 |     "test": "vitest run",
19 |     "test:watch": "vitest",
20 |     "test:debug": "vitest --inspect-brk --no-file-parallelism",
21 |     "test:coverage": "vitest run --coverage --coverage.reporter=text",
22 |     "testFunctionsExistingBackend": "just convex deploy && just convex env set IS_TEST true && vitest --run convex/example.test.ts",
23 |     "testFunctions": "node backendHarness.js 'npm run testFunctionsExistingBackend'",
24 |     "arethetypeswrong": "cd packages/convex-helpers/dist && attw $(npm pack) --ignore-rules cjs-resolves-to-esm",
25 |     "alpha": "./publish.sh alpha",
26 |     "release": "./publish.sh"
27 |   },
28 |   "dependencies": {
29 |     "classnames": "^2.3.2",
30 |     "convex": "^1.29.0",
31 |     "convex-helpers": "file:packages/convex-helpers/dist",
32 |     "hono": "^4.3.6",
33 |     "react": "^19.2.3",
34 |     "react-dom": "^19.2.3",
35 |     "usehooks-ts": "^3.1.0",
36 |     "vite": "^6.0.3 <7.0.0",
37 |     "zod": "^4.1",
38 |     "zod3": "npm:zod@~3.25.0"
39 |   },
40 |   "devDependencies": {
41 |     "@arethetypeswrong/cli": "0.18.2",
42 |     "@convex-dev/eslint-plugin": "1.0.0",
43 |     "@edge-runtime/vm": "5.0.0",
44 |     "@eslint/js": "9.39.1",
45 |     "@redocly/cli": "2.11.1",
46 |     "@standard-schema/spec": "1.0.0",
47 |     "@testing-library/react": "16.3.0",
48 |     "@types/babel__core": "7.20.5",
49 |     "@types/jest": "30.0.0",
50 |     "@types/node": "22.19.1",
51 |     "@types/react": "19.2.6",
52 |     "@types/react-dom": "19.2.3",
53 |     "@vitejs/plugin-react": "5.1.1",
54 |     "@vitest/coverage-v8": "3.2.4",
55 |     "chokidar-cli": "3.0.0",
56 |     "convex": "1.29.3",
57 |     "convex-test": "0.0.39",
58 |     "eslint": "9.39.1",
59 |     "eslint-plugin-react": "7.37.5",
60 |     "eslint-plugin-react-hooks": "7.0.1",
61 |     "globals": "16.5.0",
62 |     "jsdom": "26.1.0",
63 |     "npm-run-all2": "8.0.4",
64 |     "pkg-pr-new": "0.0.60",
65 |     "prettier": "3.6.2",
66 |     "typescript": "5.9.3",
67 |     "typescript-eslint": "8.47.0",
68 |     "vitest": "3.2.4",
69 |     "yaml": "2.8.1",
70 |     "zod-compare": "2.0.0"
71 |   }
72 | }
73 | 


--------------------------------------------------------------------------------
/src/components/SessionsExample.tsx:
--------------------------------------------------------------------------------
 1 | import {
 2 |   useSessionId,
 3 |   useSessionIdArg,
 4 |   useSessionMutation,
 5 |   useSessionPaginatedQuery,
 6 |   useSessionQuery,
 7 | } from "convex-helpers/react/sessions";
 8 | import { api } from "../../convex/_generated/api";
 9 | import { useState } from "react";
10 | import { useStableQuery } from "../hooks/useStableQuery";
11 | // import { useLocalStorage } from "usehooks-ts";
12 | 
13 | export default () => {
14 |   const [sessionId, refreshSessionId] = useSessionId();
15 |   const login = useSessionMutation(api.sessionsExample.logIn);
16 |   const logout = useSessionMutation(api.sessionsExample.logOut);
17 |   const myPresence = useSessionQuery(api.sessionsExample.myPresence);
18 |   const paginatedPresence = useSessionPaginatedQuery(
19 |     api.sessionsExample.paginatedQueryWithSession,
20 |     {},
21 |     { initialNumItems: 2 },
22 |   )!;
23 |   const joinRoom = useSessionMutation(
24 |     api.sessionsExample.joinRoom,
25 |   ).withOptimisticUpdate((store, args) => {
26 |     if (!sessionId) return;
27 |     const roomPresence = store.getQuery(api.sessionsExample.myPresence, {
28 |       sessionId,
29 |     });
30 |     store.setQuery(
31 |       api.sessionsExample.myPresence,
32 |       { sessionId },
33 |       roomPresence ? [...roomPresence, args.room] : undefined,
34 |     );
35 |   });
36 |   const [room, setRoom] = useState("");
37 |   const roomData = useStableQuery(
38 |     api.sessionsExample.roomPresence,
39 |     useSessionIdArg(room ? { room } : "skip"),
40 |   );
41 |   return (
42 |     <div>
43 |       <h2>Sessions Example</h2>
44 |       <span>{sessionId}</span>
45 |       <button
46 |         onClick={() =>
47 |           void refreshSessionId((newSessionId) => {
48 |             void login({ new: newSessionId });
49 |           })
50 |         }
51 |       >
52 |         Refresh Session Id on Log In
53 |       </button>
54 |       <form
55 |         onSubmit={(e) => {
56 |           e.preventDefault();
57 |           if (room) void joinRoom({ room });
58 |           setRoom("");
59 |         }}
60 |       >
61 |         <label>Join a room</label>
62 |         <input
63 |           type="text"
64 |           placeholder="Room name"
65 |           value={room}
66 |           onChange={(e) => setRoom(e.target.value)}
67 |         />
68 |       </form>
69 |       <p>{JSON.stringify(roomData)}</p>
70 |       <ul>{myPresence && myPresence.map((room) => <li>{room}</li>)}</ul>
71 |       <ul>
72 |         {paginatedPresence.results.map((room) => (
73 |           <li>{room.room}</li>
74 |         ))}
75 |       </ul>
76 |       <button
77 |         disabled={paginatedPresence.status !== "CanLoadMore"}
78 |         onClick={() => paginatedPresence.loadMore(2)}
79 |       >
80 |         load more
81 |       </button>
82 | 
83 |       <button
84 |         onClick={() =>
85 |           void refreshSessionId((_newSessionId) => {
86 |             void logout();
87 |           })
88 |         }
89 |       >
90 |         Delete Session Data on Log Out
91 |       </button>
92 |     </div>
93 |   );
94 | };
95 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/validators.test.ts:
--------------------------------------------------------------------------------
 1 | import { v } from "convex/values";
 2 | import { describe, expect, test, expectTypeOf } from "vitest";
 3 | import { vRequired, type VRequired } from "./validators.js";
 4 | import type { Equals } from "./index.js";
 5 | import type { Validator } from "convex/values";
 6 | 
 7 | describe("vRequired", () => {
 8 |   test("returns required validator unchanged", () => {
 9 |     testVRequired(v.string(), v.string());
10 |   });
11 | 
12 |   test("converts optional string to required", () => {
13 |     testVRequired(v.optional(v.string()), v.string());
14 |   });
15 | 
16 |   test("converts optional number to required", () => {
17 |     testVRequired(v.optional(v.float64()), v.float64());
18 |   });
19 | 
20 |   test("converts optional boolean to required", () => {
21 |     testVRequired(v.optional(v.boolean()), v.boolean());
22 |   });
23 | 
24 |   test("converts optional int64 to required", () => {
25 |     testVRequired(v.optional(v.int64()), v.int64());
26 |   });
27 | 
28 |   test("converts optional null to required", () => {
29 |     testVRequired(v.optional(v.null()), v.null());
30 |   });
31 | 
32 |   test("converts optional any to required", () => {
33 |     testVRequired(v.optional(v.any()), v.any());
34 |   });
35 | 
36 |   test("converts optional literal to required", () => {
37 |     testVRequired(v.optional(v.literal("test")), v.literal("test"));
38 |   });
39 | 
40 |   test("converts optional bytes to required", () => {
41 |     testVRequired(v.optional(v.bytes()), v.bytes());
42 |   });
43 | 
44 |   test("converts optional object to required", () => {
45 |     testVRequired(
46 |       v.optional(v.object({ name: v.string() })),
47 |       v.object({ name: v.string() }),
48 |     );
49 |   });
50 | 
51 |   test("converts optional array to required", () => {
52 |     testVRequired(v.optional(v.array(v.string())), v.array(v.string()));
53 |   });
54 | 
55 |   test("converts optional record to required", () => {
56 |     testVRequired(
57 |       v.optional(v.record(v.string(), v.number())),
58 |       v.record(v.string(), v.number()),
59 |     );
60 |   });
61 | 
62 |   test("converts optional union to required", () => {
63 |     testVRequired(
64 |       v.optional(v.union(v.string(), v.number())),
65 |       v.union(v.string(), v.number()),
66 |     );
67 |   });
68 | 
69 |   test("converts optional id to required", () => {
70 |     testVRequired(v.optional(v.id("users")), v.id("users"));
71 |   });
72 | });
73 | 
74 | function testVRequired<
75 |   T extends Validator<any, any, any>,
76 |   Expected extends Validator<any, "required", any>,
77 | >(
78 |   input: T,
79 |   expected: Expected &
80 |     (Equals<Expected, VRequired<T>> extends true
81 |       ? // eslint-disable-next-line @typescript-eslint/no-empty-object-type
82 |         {}
83 |       : "Expected type must match VRequired<Input>"),
84 | ) {
85 |   const result = vRequired(input);
86 |   expect(result).toEqual(expected);
87 |   expect(result.isOptional).toBe("required");
88 |   // This is redundant with the type check in the argument, but good for sanity
89 |   expectTypeOf(result).toEqualTypeOf(expected as any);
90 | }
91 | 


--------------------------------------------------------------------------------
/backendHarness.js:
--------------------------------------------------------------------------------
  1 | const http = require("http");
  2 | const { spawn, exec, execSync } = require("child_process");
  3 | 
  4 | // Run a command against a fresh local backend, handling setting up and tearing down the backend.
  5 | 
  6 | // Checks for a local backend running on port 3210.
  7 | const parsedUrl = new URL("http://127.0.0.1:3210");
  8 | 
  9 | async function isBackendRunning(backendUrl) {
 10 |   return new Promise((resolve) => {
 11 |     http
 12 |       .request(
 13 |         {
 14 |           hostname: backendUrl.hostname,
 15 |           port: backendUrl.port,
 16 |           path: "/version",
 17 |           method: "GET",
 18 |         },
 19 |         (res) => {
 20 |           resolve(res.statusCode === 200);
 21 |         },
 22 |       )
 23 |       .on("error", () => {
 24 |         resolve(false);
 25 |       })
 26 |       .end();
 27 |   });
 28 | }
 29 | 
 30 | function sleep(ms) {
 31 |   return new Promise((resolve) => setTimeout(resolve, ms));
 32 | }
 33 | 
 34 | const waitForLocalBackendRunning = async (backendUrl) => {
 35 |   let isRunning = await isBackendRunning(backendUrl);
 36 |   let i = 0;
 37 |   while (!isRunning) {
 38 |     if (i % 10 === 0) {
 39 |       // Progress messages every ~5 seconds
 40 |       console.log("Waiting for backend to be running...");
 41 |     }
 42 |     await sleep(500);
 43 |     isRunning = await isBackendRunning(backendUrl);
 44 |     i += 1;
 45 |   }
 46 |   return;
 47 | };
 48 | 
 49 | let backendProcess = null;
 50 | 
 51 | function cleanup() {
 52 |   if (backendProcess !== null) {
 53 |     console.log("Cleaning up running backend");
 54 |     backendProcess.kill("SIGTERM");
 55 |     execSync("just reset-local-backend");
 56 |   }
 57 | }
 58 | 
 59 | async function runWithLocalBackend(command, backendUrl) {
 60 |   const isRunning = await isBackendRunning(backendUrl);
 61 |   if (isRunning) {
 62 |     console.error(
 63 |       "Looks like local backend is already running. Cancel it and restart this command.",
 64 |     );
 65 |     process.exit(1);
 66 |   }
 67 |   execSync("just reset-local-backend");
 68 |   backendProcess = exec("CONVEX_TRACE_FILE=1 just run-local-backend");
 69 |   await waitForLocalBackendRunning(backendUrl);
 70 |   console.log("Backend running! Logs can be found in convex-local-backend.log");
 71 |   const innerCommand = new Promise((resolve) => {
 72 |     const c = spawn(command, {
 73 |       shell: true,
 74 |       stdio: "pipe",
 75 |       env: { ...process.env, FORCE_COLOR: true },
 76 |     });
 77 |     c.stdout.on("data", (data) => {
 78 |       process.stdout.write(data);
 79 |     });
 80 | 
 81 |     c.stderr.on("data", (data) => {
 82 |       process.stderr.write(data);
 83 |     });
 84 | 
 85 |     c.on("exit", (code) => {
 86 |       console.log("inner command exited with code " + code.toString());
 87 |       resolve(code);
 88 |     });
 89 |   });
 90 |   return innerCommand;
 91 | }
 92 | 
 93 | runWithLocalBackend(process.argv[2], parsedUrl)
 94 |   .then((code) => {
 95 |     cleanup();
 96 |     process.exit(code);
 97 |   })
 98 |   .catch(() => {
 99 |     cleanup();
100 |     process.exit(1);
101 |   });
102 | 


--------------------------------------------------------------------------------
/convex/presence.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Functions related to reading & writing presence data.
 3 |  *
 4 |  * Note: this file does not currently implement authorization.
 5 |  * That is left as an exercise to the reader. Some suggestions for a production
 6 |  * app:
 7 |  * - Use Convex `auth` to authenticate users rather than passing up a "user"
 8 |  * - Check that the user is allowed to be in a given room.
 9 |  */
10 | import { v } from "convex/values";
11 | import { query, mutation } from "./_generated/server";
12 | 
13 | const LIST_LIMIT = 20;
14 | 
15 | /**
16 |  * Overwrites the presence data for a given user in a room.
17 |  *
18 |  * It will also set the "updated" timestamp to now, and create the presence
19 |  * document if it doesn't exist yet.
20 |  *
21 |  * @param room - The location associated with the presence data. Examples:
22 |  * page, chat channel, game instance.
23 |  * @param user - The user associated with the presence data.
24 |  */
25 | export const update = mutation({
26 |   args: {
27 |     room: v.string(),
28 |     user: v.string(),
29 |     data: v.any(),
30 |   },
31 |   handler: async ({ db }, { room, user, data }) => {
32 |     const existing = await db
33 |       .query("presence")
34 |       .withIndex("user_room", (q) => q.eq("user", user).eq("room", room))
35 |       .unique();
36 |     if (existing) {
37 |       await db.patch(existing._id, { data, updated: Date.now() });
38 |     } else {
39 |       await db.insert("presence", {
40 |         user,
41 |         data,
42 |         room,
43 |         updated: Date.now(),
44 |       });
45 |     }
46 |   },
47 | });
48 | 
49 | /**
50 |  * Updates the "updated" timestamp for a given user's presence in a room.
51 |  *
52 |  * @param room - The location associated with the presence data. Examples:
53 |  * page, chat channel, game instance.
54 |  * @param user - The user associated with the presence data.
55 |  */
56 | export const heartbeat = mutation({
57 |   args: {
58 |     room: v.string(),
59 |     user: v.string(),
60 |   },
61 |   handler: async ({ db }, { room, user }) => {
62 |     const existing = await db
63 |       .query("presence")
64 |       .withIndex("user_room", (q) => q.eq("user", user).eq("room", room))
65 |       .unique();
66 |     if (existing) {
67 |       await db.patch(existing._id, { updated: Date.now() });
68 |     }
69 |   },
70 | });
71 | 
72 | /**
73 |  * Lists the presence data for N users in a room, ordered by recent update.
74 |  *
75 |  * @param room - The location associated with the presence data. Examples:
76 |  * page, chat channel, game instance.
77 |  * @returns A list of presence objects, ordered by recent update, limited to
78 |  * the most recent N.
79 |  */
80 | export const list = query({
81 |   args: {
82 |     room: v.string(),
83 |   },
84 |   handler: async ({ db }, { room }) => {
85 |     const presence = await db
86 |       .query("presence")
87 |       .withIndex("room_updated", (q) => q.eq("room", room))
88 |       .order("desc")
89 |       .take(LIST_LIMIT);
90 |     return presence.map(({ _creationTime, updated, user, data }) => ({
91 |       created: _creationTime,
92 |       updated,
93 |       user,
94 |       data,
95 |     }));
96 |   },
97 | });
98 | 


--------------------------------------------------------------------------------
/src/components/Counter.injection.test.tsx:
--------------------------------------------------------------------------------
 1 | import Counter from "./Counter";
 2 | import { render } from "@testing-library/react";
 3 | import { ConvexReactClientFake } from "../fakeConvexClient/fakeConvexClient";
 4 | import { ConvexProvider } from "convex/react";
 5 | import { describe, it, expect, afterEach, vi } from "vitest";
 6 | import { api } from "../../convex/_generated/api";
 7 | 
 8 | // Keep track of counter values
 9 | let counters: Record<string, number> = {};
10 | 
11 | // A function very similar to the implementation of `getCounter`
12 | const getCounter = ({ counterName }: { counterName: string }) =>
13 |   counters[counterName]!;
14 | 
15 | // A function very similar to the implementation of `incrementCounter` in `convex/counter.ts`
16 | const incrementCounter = ({
17 |   counterName,
18 |   increment,
19 | }: {
20 |   counterName: string;
21 |   increment: number;
22 | }) => {
23 |   if (counters[counterName]) {
24 |     counters[counterName] = counters[counterName]! + increment;
25 |   } else {
26 |     counters[counterName] = increment;
27 |   }
28 |   return null;
29 | };
30 | 
31 | // Wrap incrementCounter in a vitest function so we can keep track of function calls in tests
32 | const incrementCounterMock = vi.fn().mockImplementation(incrementCounter);
33 | 
34 | // Initialize the Convex mock client
35 | const mockClient = new ConvexReactClientFake();
36 | mockClient.registerQueryFake(api.counter.getCounter, getCounter);
37 | mockClient.registerMutationFake(
38 |   api.counter.incrementCounter,
39 |   incrementCounterMock,
40 | );
41 | 
42 | const setup = () =>
43 |   render(
44 |     <ConvexProvider client={mockClient}>
45 |       <Counter />
46 |     </ConvexProvider>,
47 |   );
48 | 
49 | afterEach(() => {
50 |   // Resets the counter state after every test
51 |   counters = {};
52 | 
53 |   // Resets mocks after every test
54 |   vi.restoreAllMocks();
55 | 
56 |   // Reset the dom after every test
57 |   document.getElementsByTagName("html")[0]!.innerHTML = "";
58 | });
59 | 
60 | describe("Counter", () => {
61 |   it("renders the counter", async () => {
62 |     const { getByText } = setup();
63 |     expect(getByText("Here's the counter: 0")).not.toBeNull();
64 |   });
65 | 
66 |   it("increments the counter", async () => {
67 |     const { getByRole, queryByText } = setup();
68 | 
69 |     getByRole("button").click();
70 | 
71 |     // The mocked incrementCounter function will be called.
72 |     expect(incrementCounterMock).toHaveBeenCalledOnce();
73 |     expect(incrementCounterMock).toHaveBeenCalledWith({
74 |       counterName: "clicks",
75 |       increment: 1,
76 |     });
77 | 
78 |     // The ConvexReactClientFake doesn't support reactivity,
79 |     // so we can't use it to test that components re-render with updated data.
80 |     expect(queryByText("Here's the counter: 1")).toBeNull();
81 |   });
82 | 
83 |   it("renders the counter with seeded data", async () => {
84 |     // Update the test state before rendering the component to seed the getCounter query.
85 |     incrementCounter({ counterName: "clicks", increment: 100 });
86 | 
87 |     const { getByText } = setup();
88 | 
89 |     expect(getByText("Here's the counter: 100")).not.toBeNull();
90 |   });
91 | });
92 | 


--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
 1 | # Contributing to convex-helpers
 2 | 
 3 | ## Installing dependencies for development
 4 | 
 5 | Run the following command in the _root_ of the repository (not `packages/convex-helpers`):
 6 | 
 7 | ```sh
 8 | npm install
 9 | ```
10 | 
11 | > [!NOTE]
12 | > There are two `package.json` files in the repository, one in the root and one in `packages/convex-helpers`. The dependencies in the root are a superset of all dependencies, including dependencies used during development only.
13 | 
14 | > [!IMPORTANT]
15 | > Do not run `npm install` in `packages/convex-helpers`: this might cause some dependencies to be installed twice, causing type errors.
16 | 
17 | ## Adding a helper
18 | 
19 | Adding helpers usually involves:
20 | 
21 | 1. Adding code (and corresponding .test.ts file) to:
22 |    - ./server/ if it helps write server-side code (imported in convex/)
23 |    - ./react/ for client-side code. In the future beyond react/ there can be other framework-specific client-side helpers.
24 |    - ./ if it's truly generic - can be imported client or server-side
25 | 
26 | 2. Adding the file to [the root package.json](./package.json)
27 |    or
28 |    in the following places:
29 |    1. exports in [the npm library package.json](./packages/convex-helpers/package.json)
30 |       using `node generate-exports.mjs`.
31 |    2. scripts: Update the `dev:helpers` script if it isn't being included by the existing
32 |       globs, and the `build` command if it's not included in the `cp` command.
33 | 
34 | 3. [package README.md](./packages/convex-helpers/README.md) blurb on how to use it, and a link in the TOC.
35 | 4. [root README.md](./README.md) link in the TOC.
36 | 5. Adding an example of usage in the root of this repo.
37 |    1. convex/fooExample.ts for server-side code
38 |    1. src/components/FooExample.tsx for client-side code, added in App.tsx
39 | 
40 | 6. A [Stack](https://stack.convex.dev) post on it - what problem it solves,
41 |    a blurb on how to use it. Update this README with the link when it's live.
42 | 
43 | ## Recommendations
44 | 
45 | 1. Include a block comment at the top of the file about how to use it.
46 | 2. Include jsdoc comments on exported functions etc. about how to use them.
47 | 3. Include motivation for **why** someone would use this helper, for browsing.
48 | 4. Avoid introducing too many files. Things are more discoverable within a file.
49 | 
50 | ## Releasing
51 | 
52 | Run commands from this folder (root of repo).
53 | 
54 | **NOTE**: make sure you aren't running `npm run dev` anywhere when you're
55 | publishing to avoid races with re-generating files while publishing.
56 | 
57 | In general you can run `./publish.sh` to go through the publish workflow, or
58 | `npm run release` to do a release.
59 | It will prompt you for a new version. If you've already adjusted the version,
60 | you can just hit enter.
61 | 
62 | When it shows the publish preview, ensure the files all look like they're there.
63 | After you confirm to publish, it will publish to npm, make a git commit,
64 | tag the commit with the version, and push the current branch & that tag.
65 | 
66 | ### Alpha releases
67 | 
68 | For alpha releases, you can run `./publish.sh alpha` or `npm run alpha`.
69 | 
70 | Or run this beforehand to bump the version:
71 | `npm version prerelease --preid alpha && git add package*`.
72 | Only use alpha, otherwise npm won't tag it correctly and it might suggest it as
73 | `convex-helpers@latest` instead of just as `convex-helpers@alpha`.
74 | 


--------------------------------------------------------------------------------
/scripts/check_cla.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | import os
 3 | import re
 4 | import sys
 5 | import urllib.error
 6 | import urllib.request
 7 | 
 8 | CLA_TEXT = "By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice."
 9 | ORGANIZATION = "get-convex"
10 | 
11 | def is_org_member(username, github_token):
12 |     """
13 |     Check if a user is a member of the get-convex GitHub organization.
14 |     Returns True if the user is a confirmed member.
15 |     Returns False if the user is not a member (404 response).
16 |     Returns None if the check fails (network error, API error, etc.).
17 |     """
18 |     try:
19 |         # GitHub API endpoint to check organization membership
20 |         url = f"https://api.github.com/orgs/{ORGANIZATION}/members/{username}"
21 |         
22 |         headers = {
23 |             "Accept": "application/vnd.github+json",
24 |             "X-GitHub-Api-Version": "2022-11-28"
25 |         }
26 |         
27 |         if github_token:
28 |             headers["Authorization"] = f"Bearer {github_token}"
29 |         
30 |         request = urllib.request.Request(url, headers=headers)
31 |         
32 |         # Try to fetch the membership status
33 |         # A 204 response means the user is a confirmed member
34 |         # A 404 response means the user is not a member (or membership is private)
35 |         # Other errors indicate API failure and we return None to show a warning
36 |         try:
37 |             with urllib.request.urlopen(request) as response:
38 |                 if response.status == 204:
39 |                     return True
40 |                 return None
41 |         except urllib.error.HTTPError as e:
42 |             if e.code == 404:
43 |                 # User is not a member or membership is private
44 |                 return False
45 |             # For other HTTP errors, return None to indicate failure
46 |             return None
47 |             
48 |     except Exception as e:
49 |         print(f"⚠️  Warning: Failed to check organization membership: {e}")
50 |         return None
51 | 
52 | def main():
53 |     # Get PR description
54 |     try:
55 |         PR_DESCRIPTION = os.environ["PR_DESCRIPTION"]
56 |     except KeyError:
57 |         print("❌ Error: There was no pull request description given")
58 |         sys.exit(1)
59 |     
60 |     # Get PR author username - this should always be set
61 |     PR_AUTHOR = os.environ.get("PR_AUTHOR")
62 |     GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN")
63 |     
64 |     if not PR_AUTHOR:
65 |         print("❌ Error: PR_AUTHOR environment variable not set")
66 |         sys.exit(1)
67 |     
68 |     # Check if the author is a member of get-convex organization
69 |     member_status = is_org_member(PR_AUTHOR, GITHUB_TOKEN)
70 |     
71 |     if member_status is True:
72 |         print(f"✅ Skipping CLA check: {PR_AUTHOR} is a member of the {ORGANIZATION} organization (Convex employee/contractor)")
73 |         sys.exit(0)
74 |     elif member_status is None:
75 |         print(f"⚠️  Warning: Could not verify organization membership for {PR_AUTHOR}. Proceeding with CLA check.")
76 |     
77 |     # Proceed with standard CLA check
78 |     if not re.search(re.escape(CLA_TEXT), PR_DESCRIPTION, re.MULTILINE):
79 |         print(
80 |             "❌ Pull request description does not include the required CLA text. Please add the following text to your PR description:\n\n" + CLA_TEXT
81 |         )
82 |         sys.exit(1)
83 |     
84 |     print("✅ CLA text found in PR description")
85 | 
86 | if __name__ == "__main__":
87 |     main()
88 | 


--------------------------------------------------------------------------------
/src/components/Counter.mock.test.tsx:
--------------------------------------------------------------------------------
  1 | import Counter from "./Counter";
  2 | import { render } from "@testing-library/react";
  3 | import { describe, it, expect, afterEach, vi } from "vitest";
  4 | import * as convexReact from "convex/react";
  5 | import { FunctionReference, getFunctionName } from "convex/server";
  6 | 
  7 | // Keep track of counter values
  8 | let counters: Record<string, number> = {};
  9 | 
 10 | // A function very similar to the implementation of `getCounter`
 11 | const getCounter = ({ counterName }: { counterName: string }) =>
 12 |   counters[counterName];
 13 | 
 14 | // A function very similar to the implementation of `incrementCounter` in `convex/counter.ts`
 15 | const incrementCounter = ({
 16 |   counterName,
 17 |   increment,
 18 | }: {
 19 |   counterName: string;
 20 |   increment: number;
 21 | }) => {
 22 |   if (counters[counterName]) {
 23 |     counters[counterName] = counters[counterName]! + increment;
 24 |   } else {
 25 |     counters[counterName] = increment;
 26 |   }
 27 |   return null;
 28 | };
 29 | 
 30 | // Wrap incrementCounter in a vitest function so we can keep track of function calls in tests
 31 | const incrementCounterMock = vi.fn().mockImplementation(incrementCounter);
 32 | 
 33 | vi.mock("convex/react", async () => {
 34 |   const actual = await vi.importActual<typeof convexReact>("convex/react");
 35 | 
 36 |   return {
 37 |     ...actual,
 38 |     useQuery: (
 39 |       queryName: FunctionReference<"query", "public">,
 40 |       args: Record<string, any>,
 41 |     ) => {
 42 |       if (getFunctionName(queryName) !== "counter:getCounter") {
 43 |         throw new Error("Unexpected query call!");
 44 |       }
 45 |       return getCounter(args as any);
 46 |     },
 47 |     useMutation: (mutationName: FunctionReference<"mutation", "public">) => {
 48 |       if (getFunctionName(mutationName) !== "counter:incrementCounter") {
 49 |         throw new Error("Unexpected mutation call!");
 50 |       }
 51 |       return incrementCounterMock;
 52 |     },
 53 |   };
 54 | });
 55 | 
 56 | const setup = () => render(<Counter />);
 57 | 
 58 | afterEach(() => {
 59 |   // Resets the counter state after every test
 60 |   counters = {};
 61 | 
 62 |   // Resets mocks after every test
 63 |   vi.restoreAllMocks();
 64 | 
 65 |   // Reset the dom after every test
 66 |   document.getElementsByTagName("html")[0]!.innerHTML = "";
 67 | });
 68 | 
 69 | describe("Counter", () => {
 70 |   it("renders the counter", async () => {
 71 |     const { getByText } = setup();
 72 |     expect(getByText("Here's the counter: 0")).not.toBeNull();
 73 |   });
 74 | 
 75 |   it("increments the counter", async () => {
 76 |     const { getByRole, queryByText } = setup();
 77 | 
 78 |     getByRole("button").click();
 79 | 
 80 |     // The mocked incrementCounter function will be called.
 81 |     expect(incrementCounterMock).toHaveBeenCalledOnce();
 82 |     expect(incrementCounterMock).toHaveBeenCalledWith({
 83 |       counterName: "clicks",
 84 |       increment: 1,
 85 |     });
 86 | 
 87 |     // The mocked query doesn't support reactivity,
 88 |     // so we can't use it to test that components re-render with updated data.
 89 |     expect(queryByText("Here's the counter: 1")).toBeNull();
 90 |   });
 91 | 
 92 |   it("renders the counter with seeded data", async () => {
 93 |     // Update the test state before rendering the component to seed the getCounter query.
 94 |     incrementCounter({ counterName: "clicks", increment: 100 });
 95 | 
 96 |     const { getByText } = setup();
 97 | 
 98 |     expect(getByText("Here's the counter: 100")).not.toBeNull();
 99 |   });
100 | });
101 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/browser.test.ts:
--------------------------------------------------------------------------------
  1 | import { describe, it, expect, vi, beforeEach } from "vitest";
  2 | import type { FunctionReference } from "convex/server";
  3 | import type { ConvexClient } from "convex/browser";
  4 | import { withArgs } from "./browser.js";
  5 | 
  6 | describe("withArgs", () => {
  7 |   let mockClient: ConvexClient;
  8 | 
  9 |   beforeEach(() => {
 10 |     mockClient = {
 11 |       query: vi.fn().mockResolvedValue("query-result"),
 12 |       mutation: vi.fn().mockResolvedValue("mutation-result"),
 13 |       action: vi.fn().mockResolvedValue("action-result"),
 14 |     } as unknown as ConvexClient;
 15 |   });
 16 | 
 17 |   it("should inject args into query", async () => {
 18 |     const query = {} as FunctionReference<
 19 |       "query",
 20 |       "public",
 21 |       { injected: string; extra: number },
 22 |       any
 23 |     >;
 24 |     const injectedArgs = { injected: "foo" };
 25 |     const extraArgs = { extra: 123 };
 26 | 
 27 |     const client = withArgs(mockClient, injectedArgs);
 28 |     const result = await client.query(query, extraArgs);
 29 | 
 30 |     expect(mockClient.query).toHaveBeenCalledWith(query, {
 31 |       ...extraArgs,
 32 |       ...injectedArgs,
 33 |     });
 34 |     expect(result).toBe("query-result");
 35 |   });
 36 | 
 37 |   it("should inject args into mutation", async () => {
 38 |     const mutation = {} as FunctionReference<
 39 |       "mutation",
 40 |       "public",
 41 |       { injected: string; extra: number },
 42 |       any
 43 |     >;
 44 |     const injectedArgs = { injected: "foo" };
 45 |     const extraArgs = { extra: 123 };
 46 | 
 47 |     const client = withArgs(mockClient, injectedArgs);
 48 |     const result = await client.mutation(mutation, extraArgs);
 49 | 
 50 |     expect(mockClient.mutation).toHaveBeenCalledWith(mutation, {
 51 |       ...extraArgs,
 52 |       ...injectedArgs,
 53 |     });
 54 |     expect(result).toBe("mutation-result");
 55 |   });
 56 | 
 57 |   it("should inject args into action", async () => {
 58 |     const action = {} as FunctionReference<
 59 |       "action",
 60 |       "public",
 61 |       { injected: string; extra: number },
 62 |       any
 63 |     >;
 64 |     const injectedArgs = { injected: "foo" };
 65 |     const extraArgs = { extra: 123 };
 66 | 
 67 |     const client = withArgs(mockClient, injectedArgs);
 68 |     const result = await client.action(action, extraArgs);
 69 | 
 70 |     expect(mockClient.action).toHaveBeenCalledWith(action, {
 71 |       ...extraArgs,
 72 |       ...injectedArgs,
 73 |     });
 74 |     expect(result).toBe("action-result");
 75 |   });
 76 | 
 77 |   it("should handle case when only injected args are needed", async () => {
 78 |     const query = {} as FunctionReference<
 79 |       "query",
 80 |       "public",
 81 |       { injected: string },
 82 |       any
 83 |     >;
 84 |     const injectedArgs = { injected: "foo" };
 85 | 
 86 |     const client = withArgs(mockClient, injectedArgs);
 87 |     const result = await client.query(query, {});
 88 | 
 89 |     expect(mockClient.query).toHaveBeenCalledWith(query, injectedArgs);
 90 |     expect(result).toBe("query-result");
 91 |   });
 92 | 
 93 |   it("should handle case when no extra args are provided", async () => {
 94 |     const query = {} as FunctionReference<
 95 |       "query",
 96 |       "public",
 97 |       { injected: string },
 98 |       any
 99 |     >;
100 |     const injectedArgs = { injected: "foo" };
101 | 
102 |     const client = withArgs(mockClient, injectedArgs);
103 |     const result = await client.query(query);
104 | 
105 |     expect(mockClient.query).toHaveBeenCalledWith(query, injectedArgs);
106 |     expect(result).toBe("query-result");
107 |   });
108 | });
109 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/testing.ts:
--------------------------------------------------------------------------------
  1 | import { ConvexClient } from "convex/browser";
  2 | import type {
  3 |   FunctionArgs,
  4 |   FunctionReference,
  5 |   FunctionReturnType,
  6 |   UserIdentity,
  7 | } from "convex/server";
  8 | 
  9 | /**
 10 |  * This is a helper for testing Convex functions against a locally running backend.
 11 |  *
 12 |  * An example of calling a function:
 13 |  * ```
 14 |  * const t = new ConvexTestingHelper();
 15 |  * const result = await t.query(api.foo.bar, { arg1: "baz" })
 16 |  * ```
 17 |  *
 18 |  * An example of calling a function with auth:
 19 |  * ```
 20 |  * const t = new ConvexTestingHelper();
 21 |  * const identityA = t.newIdentity({ name: "Person A"})
 22 |  * const result = await t.withIdentity(identityA).query(api.users.getProfile);
 23 |  * ```
 24 |  */
 25 | export class ConvexTestingHelper {
 26 |   private _nextSubjectId: number = 0;
 27 |   public client: ConvexClient;
 28 |   private _adminKey: string;
 29 | 
 30 |   constructor(options: { adminKey?: string; backendUrl?: string } = {}) {
 31 |     this.client = new ConvexClient(
 32 |       options.backendUrl ?? "http://127.0.0.1:3210",
 33 |     );
 34 |     this._adminKey =
 35 |       options.adminKey ??
 36 |       // default admin key for local backends - from https://github.com/get-convex/convex-backend/blob/main/Justfile
 37 |       "0135d8598650f8f5cb0f30c34ec2e2bb62793bc28717c8eb6fb577996d50be5f4281b59181095065c5d0f86a2c31ddbe9b597ec62b47ded69782cd";
 38 |   }
 39 | 
 40 |   newIdentity(
 41 |     args: Partial<Omit<UserIdentity, "tokenIdentifier">>,
 42 |   ): Omit<UserIdentity, "tokenIdentifier"> {
 43 |     const subject = `test subject ${this._nextSubjectId}`;
 44 |     this._nextSubjectId += 1;
 45 |     const issuer = "test issuer";
 46 |     return {
 47 |       ...args,
 48 |       subject,
 49 |       issuer,
 50 |     };
 51 |   }
 52 | 
 53 |   withIdentity(
 54 |     identity: Omit<UserIdentity, "tokenIdentifier">,
 55 |   ): Pick<ConvexClient, "mutation" | "action" | "query"> {
 56 |     return {
 57 |       mutation: (functionReference, args) => {
 58 |         (this.client as any).setAdminAuth(this._adminKey, identity);
 59 |         return this.client.mutation(functionReference, args).finally(() => {
 60 |           this.client.client.clearAuth();
 61 |         });
 62 |       },
 63 |       action: (functionReference, args) => {
 64 |         (this.client as any).setAdminAuth(this._adminKey, identity);
 65 |         return this.client.action(functionReference, args).finally(() => {
 66 |           this.client.client.clearAuth();
 67 |         });
 68 |       },
 69 |       query: (functionReference, args) => {
 70 |         (this.client as any).setAdminAuth(this._adminKey, identity);
 71 |         return this.client.query(functionReference, args).finally(() => {
 72 |           this.client.client.clearAuth();
 73 |         });
 74 |       },
 75 |     };
 76 |   }
 77 | 
 78 |   async mutation<Mutation extends FunctionReference<"mutation">>(
 79 |     mutation: Mutation,
 80 |     args: FunctionArgs<Mutation>,
 81 |   ): Promise<Awaited<FunctionReturnType<Mutation>>> {
 82 |     return this.client.mutation(mutation, args);
 83 |   }
 84 | 
 85 |   async query<Query extends FunctionReference<"query", "public">>(
 86 |     query: Query,
 87 |     args: FunctionArgs<Query>,
 88 |   ): Promise<Awaited<FunctionReturnType<Query>>> {
 89 |     return this.client.query(query, args);
 90 |   }
 91 | 
 92 |   async action<Action extends FunctionReference<"action">>(
 93 |     action: Action,
 94 |     args: FunctionArgs<Action>,
 95 |   ): Promise<Awaited<FunctionReturnType<Action>>> {
 96 |     return this.client.action(action, args);
 97 |   }
 98 | 
 99 |   async close(): Promise<void> {
100 |     return this.client.close();
101 |   }
102 | }
103 | 


--------------------------------------------------------------------------------
/src/hooks/usePresence.ts:
--------------------------------------------------------------------------------
 1 | import { api } from "../../convex/_generated/api";
 2 | import { useQuery, useMutation } from "convex/react";
 3 | import { Value } from "convex/values";
 4 | import { useCallback, useEffect, useState } from "react";
 5 | import useSingleFlight from "./useSingleFlight";
 6 | 
 7 | export type PresenceData<D> = {
 8 |   created: number;
 9 |   updated: number;
10 |   user: string;
11 |   data: D;
12 | };
13 | 
14 | const HEARTBEAT_PERIOD = 5000;
15 | const OLD_MS = 10000;
16 | 
17 | /**
18 |  * usePresence is a React hook for reading & writing presence data.
19 |  *
20 |  * The data is written by various users, and comes back as a list of data for
21 |  * other users in the same room. It is not meant for mission-critical data, but
22 |  * rather for optimistic metadata, like whether a user is online, typing, or
23 |  * at a certain location on a page. The data is single-flighted, and when many
24 |  * updates are requested while an update is in flight, only the latest data will
25 |  * be sent in the next request. See for more details on single-flighting:
26 |  * https://stack.convex.dev/throttling-requests-by-single-flighting
27 |  *
28 |  * Data updates are merged with previous data. This data will reflect all
29 |  * updates, not just the data that gets synchronized to the server. So if you
30 |  * update with {mug: userMug} and {typing: true}, the data will have both
31 |  * `mug` and `typing` fields set, and will be immediately reflected in the data
32 |  * returned as the first parameter.
33 |  *
34 |  * @param room - The location associated with the presence data. Examples:
35 |  * page, chat channel, game instance.
36 |  * @param user - The user associated with the presence data.
37 |  * @param initialData - The initial data to associate with the user.
38 |  * @param heartbeatPeriod? - If specified, the interval between heartbeats, in
39 |  * milliseconds. A heartbeat updates the user's presence "updated" timestamp.
40 |  * The faster the updates, the more quickly you can detect a user "left" at
41 |  * the cost of more server function calls.
42 |  * @returns A list with 1. this user's data; 2. A list of other users' data;
43 |  * 3. function to update this user's data. It will do a shallow merge.
44 |  */
45 | export const usePresence = <T extends { [key: string]: Value }>(
46 |   room: string,
47 |   user: string,
48 |   initialData: T,
49 |   heartbeatPeriod = HEARTBEAT_PERIOD,
50 | ) => {
51 |   const [data, setData] = useState(initialData);
52 |   let presence: PresenceData<T>[] | undefined = useQuery(api.presence.list, {
53 |     room,
54 |   });
55 |   if (presence) {
56 |     presence = presence.filter((p) => p.user !== user);
57 |   }
58 |   const updatePresence = useSingleFlight(useMutation(api.presence.update));
59 |   const heartbeat = useSingleFlight(useMutation(api.presence.heartbeat));
60 | 
61 |   useEffect(() => {
62 |     void updatePresence({ room, user, data });
63 |     const intervalId = setInterval(() => {
64 |       void heartbeat({ room, user });
65 |     }, heartbeatPeriod);
66 |     // Whenever we have any data change, it will get cleared.
67 |     return () => clearInterval(intervalId);
68 |   }, [updatePresence, heartbeat, room, user, data, heartbeatPeriod]);
69 | 
70 |   // Updates the data, merged with previous data state.
71 |   const updateData = useCallback((patch: Partial<T>) => {
72 |     setData((prevState) => {
73 |       return { ...prevState, ...patch };
74 |     });
75 |   }, []);
76 | 
77 |   return [data, presence, updateData] as const;
78 | };
79 | 
80 | /**
81 |  * isOnline determines a user's online status by how recently they've updated.
82 |  *
83 |  * @param presence - The presence data for one user returned from usePresence.
84 |  * @param now - If specified, the time it should consider to be "now".
85 |  * @returns True if the user has updated their presence recently.
86 |  */
87 | export const isOnline = <D>(presence: PresenceData<D>) => {
88 |   return Date.now() - presence.updated < OLD_MS;
89 | };
90 | 
91 | export default usePresence;
92 | 


--------------------------------------------------------------------------------
/convex/retriesExample.ts:
--------------------------------------------------------------------------------
 1 | import { v } from "convex/values";
 2 | import { internal } from "./_generated/api";
 3 | import { internalAction, mutation } from "./_generated/server";
 4 | 
 5 | import { makeActionRetrier } from "convex-helpers/server/retries";
 6 | 
 7 | // Export the helpers, with the name of the retry function.
 8 | export const { runWithRetries, retry } = makeActionRetrier(
 9 |   "retriesExample:retry",
10 |   { retryBackoff: 1000, log: console.warn }, // options for demo purposes.
11 | );
12 | 
13 | // This is a sample action will fail randomly based on the `failureRate`
14 | // argument. It's safe to retry since it doesn't have any side effects.
15 | export const unreliableAction = internalAction({
16 |   args: { failureRate: v.number() }, // 0.0 - 1.0
17 |   handler: async (_ctx, { failureRate }) => {
18 |     console.log("Running an action with failure rate " + failureRate);
19 |     if (Math.random() < failureRate) {
20 |       throw new Error("action failed.");
21 |     }
22 |     console.log("action succeded.");
23 |   },
24 | });
25 | 
26 | // This calls the `unreliableAction` function with retries.
27 | // Try it for yourself with:
28 | // e.g. `npx convex run retriesExample:runUnreliableActionWithRetries`
29 | export const runUnreliableActionWithRetries = mutation({
30 |   args: {},
31 |   handler: async (ctx, _args) => {
32 |     await runWithRetries(ctx, internal.retriesExample.unreliableAction, {
33 |       failureRate: 0.8,
34 |     });
35 |     // Possibly do something else besides scheduling the action,
36 |     // for instance check if the logged in user has permission to run it.
37 |     // If an error is thrown in a mutation, the transaction will be rolled back
38 |     // and the action will not be scheduled to run.
39 |   },
40 | });
41 | 
42 | // Calling an action with retries from an action works too.
43 | export const runFromAnAction = internalAction({
44 |   args: {},
45 |   handler: async (ctx) => {
46 |     const email = { to: "user@example.com", subject: "Hello", body: "World" };
47 |     await runWithRetries(
48 |       ctx,
49 |       internal.retriesExample.sendWelcomeEmail,
50 |       { email },
51 |       {
52 |         // You can limit the number of retries and wait longer between attempts
53 |         // if the action is not time sensitive and generally reliable.
54 |         // Note: generally the default options are fine.
55 | 
56 |         // After 5 failures, give up.
57 |         maxFailures: 5,
58 |         // Wait 10 seconds before retrying the first time.
59 |         retryBackoff: 10_000,
60 |         // This is the multiplier for the next wait time.
61 |         // e.g. if base is 10, the next wait time will be 10 times the previous.
62 |         base: 10,
63 |         // Wait time is then retryBackoff * base^(retryNumber).
64 |         // This will result in waiting:
65 |         // 10 seconds before retrying the first time,
66 |         // 100 seconds before retrying the second time (~1.7 minutes),
67 |         // 1000 seconds before retrying the third time (~16.7 minutes),
68 |         // 10000 seconds before retrying the fourth and final time (~2.7 hours),
69 |         // giving the action 5 chances to succeed over ~3 hours.
70 |       },
71 |     );
72 |     // Unlike in mutations, in an action the scheduler will immediately be
73 |     // given the action & parameters to run, even if there's an exception thrown
74 |     // afterwards.
75 |   },
76 | });
77 | 
78 | // This is a pretend email sending function.
79 | export const sendWelcomeEmail = internalAction({
80 |   args: {
81 |     email: v.object({ to: v.string(), subject: v.string(), body: v.string() }),
82 |   },
83 |   handler: async () => {
84 |     // If the email provider is down, it could fail.
85 |     // Hopefully it will be back up within minutes, but if it still isn't up
86 |     // hours later, it's ok to skip sending this non-essential.
87 |     // Note: If we wanted to ensure we don't send the same email twice,
88 |     // we would need something like an idempotency key to pass to the provider.
89 |   },
90 | });
91 | 


--------------------------------------------------------------------------------
/convex/_generated/server.js:
--------------------------------------------------------------------------------
 1 | /* eslint-disable */
 2 | /**
 3 |  * Generated utilities for implementing server-side Convex query and mutation functions.
 4 |  *
 5 |  * THIS CODE IS AUTOMATICALLY GENERATED.
 6 |  *
 7 |  * To regenerate, run `npx convex dev`.
 8 |  * @module
 9 |  */
10 | 
11 | import {
12 |   actionGeneric,
13 |   httpActionGeneric,
14 |   queryGeneric,
15 |   mutationGeneric,
16 |   internalActionGeneric,
17 |   internalMutationGeneric,
18 |   internalQueryGeneric,
19 | } from "convex/server";
20 | 
21 | /**
22 |  * Define a query in this Convex app's public API.
23 |  *
24 |  * This function will be allowed to read your Convex database and will be accessible from the client.
25 |  *
26 |  * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
27 |  * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
28 |  */
29 | export const query = queryGeneric;
30 | 
31 | /**
32 |  * Define a query that is only accessible from other Convex functions (but not from the client).
33 |  *
34 |  * This function will be allowed to read from your Convex database. It will not be accessible from the client.
35 |  *
36 |  * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
37 |  * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
38 |  */
39 | export const internalQuery = internalQueryGeneric;
40 | 
41 | /**
42 |  * Define a mutation in this Convex app's public API.
43 |  *
44 |  * This function will be allowed to modify your Convex database and will be accessible from the client.
45 |  *
46 |  * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
47 |  * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
48 |  */
49 | export const mutation = mutationGeneric;
50 | 
51 | /**
52 |  * Define a mutation that is only accessible from other Convex functions (but not from the client).
53 |  *
54 |  * This function will be allowed to modify your Convex database. It will not be accessible from the client.
55 |  *
56 |  * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
57 |  * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
58 |  */
59 | export const internalMutation = internalMutationGeneric;
60 | 
61 | /**
62 |  * Define an action in this Convex app's public API.
63 |  *
64 |  * An action is a function which can execute any JavaScript code, including non-deterministic
65 |  * code and code with side-effects, like calling third-party services.
66 |  * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
67 |  * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
68 |  *
69 |  * @param func - The action. It receives an {@link ActionCtx} as its first argument.
70 |  * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
71 |  */
72 | export const action = actionGeneric;
73 | 
74 | /**
75 |  * Define an action that is only accessible from other Convex functions (but not from the client).
76 |  *
77 |  * @param func - The function. It receives an {@link ActionCtx} as its first argument.
78 |  * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
79 |  */
80 | export const internalAction = internalActionGeneric;
81 | 
82 | /**
83 |  * Define an HTTP action.
84 |  *
85 |  * The wrapped function will be used to respond to HTTP requests received
86 |  * by a Convex deployment if the requests matches the path and method where
87 |  * this action is routed. Be sure to route your httpAction in `convex/http.js`.
88 |  *
89 |  * @param func - The function. It receives an {@link ActionCtx} as its first argument
90 |  * and a Fetch API `Request` object as its second.
91 |  * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
92 |  */
93 | export const httpAction = httpActionGeneric;
94 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/standardSchema.test.ts:
--------------------------------------------------------------------------------
 1 | import { z } from "zod";
 2 | import { toStandardSchema } from "./standardSchema.js";
 3 | import { v } from "convex/values";
 4 | import { expectTypeOf } from "vitest";
 5 | 
 6 | describe("toStandardSchema", () => {
 7 |   test("conforms to StandardSchemaV1 for string", () => {
 8 |     const schema = toStandardSchema(v.string());
 9 |     expect(schema).toHaveProperty("~standard");
10 |     expect(schema["~standard"]).toHaveProperty("version", 1);
11 |     expect(schema["~standard"]).toHaveProperty("vendor", "convex-helpers");
12 |     expect(typeof schema["~standard"].validate).toBe("function");
13 |   });
14 | 
15 |   test("types the same as an equivalent zod validator", () => {
16 |     const ours = toStandardSchema(v.string());
17 |     const value = ours["~standard"].validate("hello");
18 |     const zods = z.string();
19 |     const zodValue = zods["~standard"].validate("hello");
20 |     expectTypeOf(ours["~standard"]).toEqualTypeOf(zods["~standard"]);
21 |     expectTypeOf(value).toEqualTypeOf(zodValue);
22 |   });
23 | 
24 |   test("validates string type", () => {
25 |     const schema = toStandardSchema(v.string());
26 |     expect(schema["~standard"].validate("hello")).toEqual({ value: "hello" });
27 |     const fail = schema["~standard"].validate(123);
28 |     expect("issues" in fail && fail.issues).toBeTruthy();
29 |     if ("issues" in fail && fail.issues) {
30 |       expect(fail.issues[0]?.message).toMatch(/string/);
31 |     }
32 |   });
33 | 
34 |   test("validates number type", () => {
35 |     const schema = toStandardSchema(v.number());
36 |     expect(schema["~standard"].validate(42)).toEqual({ value: 42 });
37 |     const fail = schema["~standard"].validate("not a number");
38 |     expect("issues" in fail && fail.issues).toBeTruthy();
39 |     if ("issues" in fail && fail.issues) {
40 |       expect(fail.issues[0]?.message).toMatch(/number/);
41 |     }
42 |   });
43 | 
44 |   test("validates boolean type", () => {
45 |     const schema = toStandardSchema(v.boolean());
46 |     expect(schema["~standard"].validate(true)).toEqual({ value: true });
47 |     expect(schema["~standard"].validate(false)).toEqual({ value: false });
48 |     const fail = schema["~standard"].validate("not a boolean");
49 |     expect("issues" in fail && fail.issues).toBeTruthy();
50 |     if ("issues" in fail && fail.issues) {
51 |       expect(fail.issues[0]?.message).toMatch(/boolean/);
52 |     }
53 |   });
54 | 
55 |   test("validates object type", () => {
56 |     const schema = toStandardSchema(v.object({ foo: v.string() }));
57 |     expect(schema["~standard"].validate({ foo: "bar" })).toEqual({
58 |       value: { foo: "bar" },
59 |     });
60 |     const fail = schema["~standard"].validate({ foo: 123 });
61 |     expect("issues" in fail && fail.issues).toBeTruthy();
62 |     if ("issues" in fail && fail.issues) {
63 |       expect(fail.issues[0]?.message).toMatch(/string/);
64 |       expect(fail.issues[0]?.path).toEqual(["foo"]);
65 |     }
66 |   });
67 | 
68 |   test("validates nested object type", () => {
69 |     const schema = toStandardSchema(
70 |       v.object({ foo: v.object({ bar: v.string() }) }),
71 |     );
72 |     expect(schema["~standard"].validate({ foo: { bar: "baz" } })).toEqual({
73 |       value: { foo: { bar: "baz" } },
74 |     });
75 |     const fail = schema["~standard"].validate({ foo: { bar: 123 } });
76 |     expect("issues" in fail && fail.issues).toBeTruthy();
77 |     if ("issues" in fail && fail.issues) {
78 |       expect(fail.issues[0]?.message).toMatch(/string/);
79 |       expect(fail.issues[0]?.path).toEqual(["foo", "bar"]);
80 |     }
81 |   });
82 | 
83 |   test("validates array type", () => {
84 |     const schema = toStandardSchema(v.array(v.number()));
85 |     expect(schema["~standard"].validate([1, 2, 3])).toEqual({
86 |       value: [1, 2, 3],
87 |     });
88 |     const fail = schema["~standard"].validate([1, "two", 3]);
89 |     expect("issues" in fail && fail.issues).toBeTruthy();
90 |     if ("issues" in fail && fail.issues) {
91 |       expect(fail.issues[0]?.message).toMatch(/number/);
92 |     }
93 |   });
94 | });
95 | 


--------------------------------------------------------------------------------
/src/components/CacheExample.tsx:
--------------------------------------------------------------------------------
  1 | import { FC, useRef, useState } from "react";
  2 | import {
  3 |   useQuery,
  4 |   usePaginatedQuery,
  5 |   useQueries,
  6 | } from "convex-helpers/react/cache";
  7 | import { api } from "../../convex/_generated/api";
  8 | 
  9 | // Composing this with the tanstack-style useQuery:
 10 | import { makeUseQueryWithStatus } from "convex-helpers/react";
 11 | import { useMutation } from "convex/react";
 12 | const useQueryWithStatus = makeUseQueryWithStatus(useQueries);
 13 | 
 14 | export const CacheExample: FC = () => {
 15 |   const [count, setCount] = useState(4);
 16 |   const ref = useRef<HTMLInputElement>(null);
 17 |   const [skip, setSkip] = useState(true);
 18 |   const [unmounted, setUnmounted] = useState(false);
 19 |   const children = [];
 20 |   const updateCount = () => {
 21 |     const r = parseInt(ref.current!.value);
 22 |     if (!isNaN(r)) {
 23 |       setCount(Math.floor(r));
 24 |     }
 25 |     return false;
 26 |   };
 27 |   for (let i = 0; i < count; i++) {
 28 |     children.push(<Query key={i} count={i + 1} />);
 29 |   }
 30 |   return (
 31 |     <>
 32 |       <h2>Query Cache Example</h2>
 33 |       Enter a number counters to fetch:{" "}
 34 |       <input
 35 |         style={{ border: "1px solid" }}
 36 |         ref={ref}
 37 |         type="number"
 38 |         onChange={updateCount}
 39 |       />
 40 |       <ul>{children}</ul>
 41 |       <div>
 42 |         Try skipping and see that the non-skipped value is already there:
 43 |       </div>
 44 |       <button onClick={() => setSkip((skip) => !skip)}>
 45 |         {skip ? "Unskip" : "Skip"}
 46 |       </button>
 47 |       <div className="flex flex-row gap-8">
 48 |         <div className="flex-1 flex flex-col gap-2">
 49 |           <div>Regular query results</div>
 50 |           <Query count={count} skip={skip} />
 51 |           <div>Paginated query results</div>
 52 |           <Paginated skip={skip} />
 53 |         </div>
 54 |         <div className="flex-1 flex flex-col gap-2">
 55 |           <div>Alternative to skip: mounting and unmounting the component</div>
 56 |           <button onClick={() => setUnmounted((unmounted) => !unmounted)}>
 57 |             {unmounted ? "Mount" : "Unmount"}
 58 |           </button>
 59 |           {unmounted ? (
 60 |             <div>Unmounted</div>
 61 |           ) : (
 62 |             <>
 63 |               <div>Regular query results</div>
 64 |               <Query count={count} skip={false} />
 65 |               <div>Paginated query results</div>
 66 |               <Paginated skip={false} />
 67 |             </>
 68 |           )}
 69 |         </div>
 70 |       </div>
 71 |     </>
 72 |   );
 73 | };
 74 | 
 75 | const Query: FC<{ count: number; skip?: boolean }> = ({ count, skip }) => {
 76 |   const counters = useQuery(api.counter.getCounters, skip ? "skip" : { count });
 77 |   const sumWithStatus = useQueryWithStatus(
 78 |     api.counter.getCounters,
 79 |     skip ? "skip" : { count },
 80 |   );
 81 |   if (
 82 |     sumWithStatus.data !== counters ||
 83 |     sumWithStatus.isPending !== (counters === undefined) ||
 84 |     sumWithStatus.isSuccess !== (counters !== undefined)
 85 |   ) {
 86 |     throw new Error("These should never mismatch");
 87 |   }
 88 | 
 89 |   if (counters === undefined) {
 90 |     if (skip) return <li>Skipped</li>;
 91 |     return <li>Loading {count}...</li>;
 92 |   } else {
 93 |     return (
 94 |       <li>
 95 |         {count} &rarr; {counters.at(0)?.name}
 96 |         {counters.length > 1
 97 |           ? counters.length > 2
 98 |             ? `...${counters.length - 2}...${counters.at(-1)?.name}`
 99 |             : `...${counters.at(-1)?.name}`
100 |           : ""}
101 |       </li>
102 |     );
103 |   }
104 | };
105 | 
106 | function Paginated({ skip }: { skip: boolean }) {
107 |   const counters = usePaginatedQuery(
108 |     api.counter.getCountersPaginated,
109 |     skip ? "skip" : {},
110 |     { initialNumItems: 2, customPagination: true },
111 |   );
112 |   const addCounter = useMutation(api.counter.incrementCounter);
113 |   if (skip) {
114 |     return <div>Skipped</div>;
115 |   }
116 |   return (
117 |     <div>
118 |       <div>Status: {counters.status}</div>
119 |       <ul>
120 |         {counters.results.map((counter, i) => (
121 |           <li key={i}>
122 |             {counter.name}: {counter.counter}
123 |           </li>
124 |         ))}
125 |       </ul>
126 |       <button
127 |         onClick={() =>
128 |           addCounter({ counterName: "test-" + Date.now(), increment: 1 })
129 |         }
130 |       >
131 |         Add Counter
132 |       </button>
133 |       {counters.status === "CanLoadMore" && (
134 |         <button onClick={() => counters.loadMore(2)}>Load More</button>
135 |       )}
136 |     </div>
137 |   );
138 | }
139 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/server/cors.test.http.ts:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * This file is used to define the HTTP routes for the cors.test.ts file.
  3 |  * It does not contain any tests, but the .test path both excludes it from the
  4 |  * generated API spec and indicates its intent.
  5 |  */
  6 | import { httpRouter, httpActionGeneric } from "convex/server";
  7 | import { corsRouter } from "./cors.js";
  8 | 
  9 | const everythingHandler = httpActionGeneric(async () => {
 10 |   return new Response(JSON.stringify([{ fact: "Hello, world!" }]), {
 11 |     headers: {
 12 |       "Content-Type": "application/json",
 13 |     },
 14 |   });
 15 | });
 16 | 
 17 | const http = httpRouter();
 18 | const cors = corsRouter(http, {
 19 |   allowedOrigins: ["*"],
 20 | });
 21 | 
 22 | /**
 23 |  * Exact routes will match /fact exactly
 24 |  */
 25 | cors.route({
 26 |   path: "/fact",
 27 |   method: "GET",
 28 |   handler: everythingHandler,
 29 | });
 30 | 
 31 | cors.route({
 32 |   path: "/fact",
 33 |   method: "POST",
 34 |   handler: everythingHandler,
 35 | });
 36 | 
 37 | cors.route({
 38 |   path: "/fact",
 39 |   method: "PATCH",
 40 |   handler: everythingHandler,
 41 | });
 42 | 
 43 | cors.route({
 44 |   path: "/fact",
 45 |   method: "DELETE",
 46 |   handler: everythingHandler,
 47 | });
 48 | 
 49 | /**
 50 |  * Non-CORS routes
 51 |  */
 52 | http.route({
 53 |   path: "/nocors/fact",
 54 |   method: "GET",
 55 |   handler: everythingHandler,
 56 | });
 57 | 
 58 | http.route({
 59 |   path: "/nocors/fact",
 60 |   method: "POST",
 61 |   handler: everythingHandler,
 62 | });
 63 | 
 64 | /**
 65 |  * Prefix routes will match /dynamicFact/123 and /dynamicFact/456 etc.
 66 |  */
 67 | cors.route({
 68 |   pathPrefix: "/dynamicFact/",
 69 |   method: "GET",
 70 |   handler: everythingHandler,
 71 | });
 72 | 
 73 | cors.route({
 74 |   pathPrefix: "/dynamicFact/",
 75 |   method: "PATCH",
 76 |   handler: everythingHandler,
 77 | });
 78 | 
 79 | /**
 80 |  * Per-path "allowedOrigins" will override the default "allowedOrigins" for that route
 81 |  */
 82 | cors.route({
 83 |   path: "/specialRouteOnlyForThisOrigin",
 84 |   method: "GET",
 85 |   handler: httpActionGeneric(async () => {
 86 |     return new Response(
 87 |       JSON.stringify({ message: "Custom allowed origins! Wow!" }),
 88 |       {
 89 |         status: 200,
 90 |         headers: {
 91 |           "Content-Type": "application/json",
 92 |         },
 93 |       },
 94 |     );
 95 |   }),
 96 |   allowedOrigins: ["http://localhost:3000"],
 97 | });
 98 | 
 99 | /**
100 |  * Per-path "allowedOrigins" can be a function
101 |  */
102 | cors.route({
103 |   path: "/routeWithDynamicAllowedOrigins",
104 |   method: "GET",
105 |   handler: httpActionGeneric(async () => {
106 |     return new Response(
107 |       JSON.stringify({ message: "Dynamic allowed origins! Wow!" }),
108 |       {
109 |         status: 200,
110 |         headers: {
111 |           "Content-Type": "application/json",
112 |         },
113 |       },
114 |     );
115 |   }),
116 |   allowedOrigins: async (request) => {
117 |     return [request.headers.get("origin") ?? ""];
118 |   },
119 | });
120 | 
121 | /**
122 |  * Disable CORS for this route
123 |  */
124 | http.route({
125 |   path: "/routeWithoutCors",
126 |   method: "GET",
127 |   handler: httpActionGeneric(async () => {
128 |     return new Response(
129 |       JSON.stringify({ message: "No CORS allowed here, pal." }),
130 |       {
131 |         status: 200,
132 |         headers: {
133 |           "Content-Type": "application/json",
134 |         },
135 |       },
136 |     );
137 |   }),
138 | });
139 | 
140 | /**
141 |  * Test that allowed headers are correctly set.
142 |  */
143 | cors.route({
144 |   path: "/allowedHeaders",
145 |   method: "GET",
146 |   handler: everythingHandler,
147 |   allowedHeaders: ["X-Custom-Header"],
148 | });
149 | 
150 | /**
151 |  * Test that the exposed headers are correctly set.
152 |  */
153 | cors.route({
154 |   path: "/exposedHeaders",
155 |   method: "GET",
156 |   handler: everythingHandler,
157 |   exposedHeaders: ["X-Custom-Header"],
158 | });
159 | 
160 | /**
161 |  * Test that the browser cache max age is correctly set.
162 |  */
163 | cors.route({
164 |   path: "/browserCacheMaxAge",
165 |   method: "GET",
166 |   handler: everythingHandler,
167 |   browserCacheMaxAge: 60,
168 | });
169 | 
170 | /**
171 |  * Test that allow credentials works with *.
172 |  */
173 | cors.route({
174 |   path: "/allowCredentials",
175 |   method: "GET",
176 |   handler: everythingHandler,
177 |   allowCredentials: true,
178 | });
179 | 
180 | /**
181 |  * Test that allow credentials works with a specific origin.
182 |  */
183 | cors.route({
184 |   path: "/allowCredentialsWithOrigin",
185 |   method: "GET",
186 |   handler: everythingHandler,
187 |   allowCredentials: true,
188 |   allowedOrigins: ["http://localhost:3000"],
189 | });
190 | 
191 | export default http;
192 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/server/triggers.test.ts:
--------------------------------------------------------------------------------
  1 | import { customCtx, customMutation } from "./customFunctions.js";
  2 | import { Triggers } from "./triggers.js";
  3 | import { convexTest } from "convex-test";
  4 | import type {
  5 |   ApiFromModules,
  6 |   DataModelFromSchemaDefinition,
  7 |   MutationBuilder,
  8 | } from "convex/server";
  9 | import {
 10 |   anyApi,
 11 |   defineSchema,
 12 |   defineTable,
 13 |   mutationGeneric,
 14 | } from "convex/server";
 15 | import { v } from "convex/values";
 16 | import { expect, test } from "vitest";
 17 | import { modules } from "./setup.test.js";
 18 | 
 19 | const schema = defineSchema({
 20 |   users: defineTable({
 21 |     firstName: v.string(),
 22 |     lastName: v.string(),
 23 |     fullName: v.string(),
 24 |   }),
 25 |   usersExplicit: defineTable({
 26 |     firstName: v.string(),
 27 |     lastName: v.string(),
 28 |     fullName: v.string(),
 29 |   }),
 30 |   usersExplicitIncorrectTable: defineTable({
 31 |     firstName: v.string(),
 32 |     lastName: v.string(),
 33 |     fullName: v.string(),
 34 |   }),
 35 | });
 36 | type DataModel = DataModelFromSchemaDefinition<typeof schema>;
 37 | const rawMutation = mutationGeneric as MutationBuilder<DataModel, "public">;
 38 | 
 39 | const triggers = new Triggers<DataModel>();
 40 | 
 41 | triggers.register("users", async (ctx, change) => {
 42 |   if (change.newDoc) {
 43 |     const fullName = `${change.newDoc.firstName} ${change.newDoc.lastName}`;
 44 |     if (change.newDoc.fullName !== fullName) {
 45 |       await ctx.db.patch(change.id, { fullName });
 46 |     }
 47 |   }
 48 | });
 49 | triggers.register("usersExplicit", async (ctx, change) => {
 50 |   if (change.newDoc) {
 51 |     const fullName = `${change.newDoc.firstName} ${change.newDoc.lastName}`;
 52 |     if (change.newDoc.fullName !== fullName) {
 53 |       await ctx.db.patch(
 54 |         "usersExplicit",
 55 |         change.id,
 56 |         // @ts-expect-error -- patch supports 3 args since convex@1.25.4, but the type is marked as internal
 57 |         { fullName },
 58 |       );
 59 |     }
 60 |   }
 61 | });
 62 | triggers.register("usersExplicitIncorrectTable", async (ctx, change) => {
 63 |   if (change.newDoc) {
 64 |     const fullName = `${change.newDoc.firstName} ${change.newDoc.lastName}`;
 65 |     if (change.newDoc.fullName !== fullName) {
 66 |       await ctx.db.patch(
 67 |         "users",
 68 |         change.id,
 69 |         // @ts-expect-error -- patch supports 3 args since convex@1.25.4, but the type is marked as internal
 70 |         { fullName },
 71 |       );
 72 |     }
 73 |   }
 74 | });
 75 | 
 76 | const mutation = customMutation(rawMutation, customCtx(triggers.wrapDB));
 77 | 
 78 | export const createUser = mutation({
 79 |   args: { firstName: v.string(), lastName: v.string() },
 80 |   handler: async (ctx, args) => {
 81 |     return ctx.db.insert("users", {
 82 |       firstName: args.firstName,
 83 |       lastName: args.lastName,
 84 |       fullName: "",
 85 |     });
 86 |   },
 87 | });
 88 | 
 89 | export const createUserExplicit = mutation({
 90 |   args: { firstName: v.string(), lastName: v.string() },
 91 |   handler: async (ctx, args) => {
 92 |     return ctx.db.insert("usersExplicit", {
 93 |       firstName: args.firstName,
 94 |       lastName: args.lastName,
 95 |       fullName: "",
 96 |     });
 97 |   },
 98 | });
 99 | 
100 | export const createUserExplicitIncorrectTable = mutation({
101 |   args: { firstName: v.string(), lastName: v.string() },
102 |   handler: async (ctx, args) => {
103 |     return ctx.db.insert("usersExplicitIncorrectTable", {
104 |       firstName: args.firstName,
105 |       lastName: args.lastName,
106 |       fullName: "",
107 |     });
108 |   },
109 | });
110 | 
111 | const testApi: ApiFromModules<{
112 |   fns: {
113 |     createUser: typeof createUser;
114 |     createUserExplicit: typeof createUserExplicit;
115 |     createUserExplicitIncorrectTable: typeof createUserExplicitIncorrectTable;
116 |   };
117 | }>["fns"] = anyApi["triggers.test"] as any;
118 | 
119 | test("trigger denormalizes field", async () => {
120 |   const t = convexTest(schema, modules);
121 |   const userId = await t.mutation(testApi.createUser, {
122 |     firstName: "John",
123 |     lastName: "Doe",
124 |   });
125 |   await t.run(async (ctx) => {
126 |     const user = await ctx.db.get(userId);
127 |     expect(user!.fullName).toStrictEqual("John Doe");
128 |   });
129 | });
130 | 
131 | test("trigger with explicit IDs denormalizes field", async () => {
132 |   const t = convexTest(schema, modules);
133 |   const userId = await t.mutation(testApi.createUserExplicit, {
134 |     firstName: "John",
135 |     lastName: "Doe",
136 |   });
137 |   await t.run(async (ctx) => {
138 |     const user = await ctx.db.get(userId);
139 |     expect(user!.fullName).toStrictEqual("John Doe");
140 |   });
141 | });
142 | 
143 | test("trigger with wrong usage of explicit IDs fails", async () => {
144 |   const t = convexTest(schema, modules);
145 |   await expect(
146 |     t.mutation(testApi.createUserExplicitIncorrectTable, {
147 |       firstName: "John",
148 |       lastName: "Doe",
149 |     }),
150 |   ).rejects.toThrow(
151 |     "Invalid argument `id`, expected ID in table 'users' but got ID in table 'usersExplicitIncorrectTable'",
152 |   );
153 | });
154 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/CHANGELOG.md:
--------------------------------------------------------------------------------
  1 | # Changelog
  2 | 
  3 | ## 0.1.107
  4 | 
  5 | - Zod support: branded object types are now supported (credit: gary-ix)
  6 | - Fixes `skipConvexValidation` for zod custom functions to still do zod validation.
  7 | 
  8 | ## 0.1.106
  9 | 
 10 | - Update typedV to match the type of the installed convex validators for v.nullable
 11 | - Improves handling of literals() helper to keep the ordering of its members
 12 | - Improved Zod 4 handling of circular types, empty returns, and empty function args
 13 | - Zod 4 transforms can now be asynchronous
 14 | 
 15 | ## 0.1.105
 16 | 
 17 | - **convex-helpers now supports Zod 4!** (#840)
 18 |   - The new methods that support Zod 4 can be found in `convex-helpers/server/zod4`
 19 |   - Existing types and methods for Zod 3 support have been moved
 20 |     (`convex-helpers/server/zod` → `convex-helpers/server/zod3`)
 21 |   - Thanks to @ksinghal and @natedunn for their contributions to this improvement.
 22 | - Zod 3 support: fix the return types of `zodOutputToConvex` for objects and unions
 23 |   (credit: gari-ix)
 24 | - Zod 3 support: improve the type safety of `onSuccess` in custom function builders
 25 | - Sessions: If the only argument to a session function is the sessionId,
 26 |   allow omitting args in React.
 27 | 
 28 | ## 0.1.104
 29 | 
 30 | - Allows RLS to deny access by default
 31 | 
 32 | ## 0.1.103
 33 | 
 34 | - Parsing validators with optional fields and explicit { field: undefined } works
 35 | 
 36 | ## 0.1.102
 37 | 
 38 | - You can use Zod4 alongside convex-helpers.
 39 |   Note: convex-helpers/zod supports zod3 only. Zod4 support is WIP
 40 | 
 41 | ## 0.1.101
 42 | 
 43 | - Improved Zod union type (credit:Firephoenix25)
 44 | - Fixes zCustom\* function type inference regression
 45 | - Adds a helper function `addFieldsToValidator` which recursively adds fields
 46 |   to either a `{ key: v.string() }`, a `v.object(..)`, or `v.union(...` of objects/unions.
 47 | - Tightens the types when not using extra args, so it catches typos
 48 | - Removes the long-deprecated "output" argument (use `returns` instead)- Improved Zod union type (credit:Firephoenix25)
 49 | - Bumps the Convex peer dependency as we rely on compareValues (credit:nicolas)
 50 | - Exports types for QueryStream
 51 | 
 52 | ## 0.1.100
 53 | 
 54 | - Custom Functions now can take dynamic parameters for each function
 55 |   they define (e.g. each custom query providing a "role" it expects)
 56 | - Custom Functions can provide an "onSuccess" callback to do final
 57 |   things after the inner function succeeds. Throwing fails it.
 58 | - Custom Functions exposes a customCtxAndArgs utility to help with types
 59 | - Trigger DB wrapper is now an object, not a class when using
 60 |   `.wrapDB()` or `writerWithTriggers` explicitly (credit: front-depiction)
 61 | - `convexToZod` now transforms to more specific zod types (credit: Firephoenix25)
 62 | - `crud` helper works for tables with top-level unions
 63 | - `paginator` works over indexes including `undefined` values.
 64 | - `Mod` type is deprecated - renamed to `Customization`
 65 | 
 66 | ## 0.1.99
 67 | 
 68 | - Fixes LoadingMore for custom pagintation
 69 | 
 70 | ## 0.1.98
 71 | 
 72 | - `partial` now supports unions too (including recursive unions).
 73 | 
 74 | ## 0.1.97
 75 | 
 76 | - `partial` from `convex-helpers/validators` now supports either a
 77 |   v.object or POJO of validators.
 78 | 
 79 | ## 0.1.96
 80 | 
 81 | - Fix the usePaginatedQuery helper to show LoadingMore when loading
 82 |   the last page
 83 | 
 84 | ## 0.1.95
 85 | 
 86 | - Improved CORS support for server-to-server endpoints, along with more
 87 |   nuanced handling of Vary headers.
 88 |   If you want the server to continue throwing when origins don't match,
 89 |   pass `enforceAllowOrigins: true`. By default it will not throw and let
 90 |   the browser or other server decide what to do about a conflict.
 91 | 
 92 | ## 0.1.94
 93 | 
 94 | - Fix: Pagination of distinct streams
 95 | 
 96 | ## 0.1.93
 97 | 
 98 | - Changes `usePaginatedQuery` for caching to take a `customPagination`
 99 |   option instead of "fixed" vs. "grow" for now. Pass `true` when using
100 |   the `paginator` or `stream` helpers.
101 | - Adds a regular `usePaginatedQuery` to use with `stream` and `paginator`
102 |   helpers that doesn't use the subscription cache helper.
103 | 
104 | ## 0.1.92
105 | 
106 | - `usePaginatedQuery` has the default `latestPageSize` option of "fixed"
107 |   which has the first (or latest once loadMore is called) page stay a
108 |   fixed size. Today this only affects queries using `paginator` or
109 |   `stream` helpers, and will soon also be able to fix the page size for
110 |   built-in pagination too.
111 | - Fix: update type annotations of imports for tsApiApec.ts.
112 | 
113 | ## 0.1.91
114 | 
115 | - `usePaginatedQuery` is now available in the cached query helpers.
116 | - With `usePaginatedQuery`, you can pass `endCursorBehavior: "setOnLoadMore"`,
117 |   which allows seamless pagination when using `stream` and`paginator` helpers
118 |   and will allow future deprecation of the too-magical QueryJournal.
119 | - Split pages more eagerly in the custom pagination hooks to reduce bandwidth.
120 | - Fix descending multi-column index pagination for `paginator` and `streams`
121 |   helpers.
122 | 
123 | ## 0.1.90
124 | 
125 | - Support unions with `parse` and `validate(... { throws: true })`
126 | 
127 | ## 0.1.89
128 | 
129 | - `parse` validator utility
130 | 
131 | ## 0.1.88
132 | 
133 | - Support for standard schema
134 | - Allow debugging cors
135 | 
136 | ... older: check git!
137 | 


--------------------------------------------------------------------------------
/.vscode/convex.code-snippets:
--------------------------------------------------------------------------------
  1 | {
  2 |   "Convex Imports": {
  3 |     "prefix": "convex:imports",
  4 |     "body": [
  5 |       "import { v } from \"convex/values\";",
  6 |       "import { api, internal } from \"./_generated/api\";",
  7 |       "import { Doc, Id } from \"./_generated/dataModel\";",
  8 |       "import {",
  9 |       "  action,",
 10 |       "  internalAction,",
 11 |       "  internalMutation,",
 12 |       "  internalQuery,",
 13 |       "  mutation,",
 14 |       "  query,",
 15 |       "} from \"./_generated/server\";",
 16 |     ],
 17 |     "scope": "javascript,typescript",
 18 |     "isFileTemplate": true,
 19 |   },
 20 | 
 21 |   "Convex Query": {
 22 |     "prefix": "convex:query",
 23 |     "body": [
 24 |       "export const $1 = query({",
 25 |       "  args: {$2},",
 26 |       "  handler: async (ctx, args) => {",
 27 |       "    $0",
 28 |       "  },",
 29 |       "});",
 30 |     ],
 31 |     "scope": "javascript,typescript",
 32 |   },
 33 | 
 34 |   "Convex Internal Query": {
 35 |     "prefix": "convex:internalQuery",
 36 |     "body": [
 37 |       "export const $1 = internalQuery({",
 38 |       "  args: {$2},",
 39 |       "  handler: async (ctx, args) => {",
 40 |       "    $0",
 41 |       "  },",
 42 |       "});",
 43 |     ],
 44 |     "scope": "javascript,typescript",
 45 |   },
 46 | 
 47 |   "Convex Mutation": {
 48 |     "prefix": "convex:mutation",
 49 |     "body": [
 50 |       "export const $1 = mutation({",
 51 |       "  args: {$2},",
 52 |       "  handler: async (ctx, args) => {",
 53 |       "    $0",
 54 |       "  },",
 55 |       "});",
 56 |     ],
 57 |     "scope": "javascript,typescript",
 58 |   },
 59 | 
 60 |   "Convex Internal Mutation": {
 61 |     "prefix": "convex:internalMutation",
 62 |     "body": [
 63 |       "export const $1 = internalMutation({",
 64 |       "  args: {$2},",
 65 |       "  handler: async (ctx, args) => {",
 66 |       "    $0",
 67 |       "  },",
 68 |       "});",
 69 |     ],
 70 |     "scope": "javascript,typescript",
 71 |   },
 72 | 
 73 |   "Convex Action": {
 74 |     "prefix": "convex:action",
 75 |     "body": [
 76 |       "export const $1 = action({",
 77 |       "  args: {$2},",
 78 |       "  handler: async (ctx, args) => {",
 79 |       "    $0",
 80 |       "  },",
 81 |       "});",
 82 |     ],
 83 |     "scope": "javascript,typescript",
 84 |   },
 85 | 
 86 |   "Convex Internal Action": {
 87 |     "prefix": "convex:internalAction",
 88 |     "body": [
 89 |       "export const $1 = internalAction({",
 90 |       "  args: {$2},",
 91 |       "  handler: async (ctx, args) => {",
 92 |       "    $0",
 93 |       "  },",
 94 |       "});",
 95 |     ],
 96 |     "scope": "javascript,typescript",
 97 |   },
 98 | 
 99 |   "Convex Crons": {
100 |     "prefix": "convex:crons",
101 |     "body": [
102 |       "import { cronJobs } from \"convex/server\";",
103 |       "import { internal } from \"./_generated/api\";",
104 |       "import { internalMutation } from \"./_generated/server\";",
105 |       "import { v } from \"convex/values\";",
106 |       "",
107 |       "const crons = cronJobs();",
108 |       "",
109 |       "export const $1 = internalMutation({",
110 |       "  args: {},",
111 |       "  handler: async (ctx, args) => {",
112 |       "    $0",
113 |       "  },",
114 |       "});",
115 |       "",
116 |       "crons.interval(",
117 |       "  \"$1\",",
118 |       "  { seconds: $2 },",
119 |       "  internal.crons.$1,",
120 |       ");",
121 |       "",
122 |       "",
123 |       "export default crons;",
124 |     ],
125 |     "scope": "javascript,typescript",
126 |   },
127 | 
128 |   "Convex Schema": {
129 |     "prefix": "convex:schema",
130 |     "body": [
131 |       "import { defineTable, defineSchema } from \"convex/server\";",
132 |       "import { v } from \"convex/values\";",
133 |       "",
134 |       "export default defineSchema({",
135 |       "  $1: defineTable({",
136 |       "    $0",
137 |       "  }),",
138 |       "});",
139 |     ],
140 |     "scope": "javascript,typescript",
141 |   },
142 | 
143 |   "Convex HTTP": {
144 |     "prefix": "convex:http",
145 |     "body": [
146 |       "import { httpRouter } from \"convex/server\";",
147 |       "import { httpAction } from \"./_generated/server\";",
148 |       "",
149 |       "const http = httpRouter();",
150 |       "",
151 |       "http.route({",
152 |       "  path: \"/echo\",",
153 |       "  method: \"GET\",",
154 |       "  handler: httpAction(async (ctx, request) => {",
155 |       "    const t = await request.text();",
156 |       "    return new Response(\"Received: \" + t);",
157 |       "  }),",
158 |       "});",
159 |       "",
160 |       "// Convex expects the router to be the default export of `convex/http.js`.",
161 |       "export default http;",
162 |     ],
163 |     "scope": "javascript,typescript",
164 |   },
165 | 
166 |   "Convex Test": {
167 |     "prefix": "convex:test",
168 |     "body": [
169 |       "import { convexTest } from \"convex-test\";",
170 |       "import { v } from \"convex/values\";",
171 |       "import { expect, test } from \"vitest\";",
172 |       "import { api, internal } from \"./_generated/api\";",
173 |       "import { Doc, Id } from \"./_generated/dataModel\";",
174 |       "import {",
175 |       "  action,",
176 |       "  internalAction,",
177 |       "  internalMutation,",
178 |       "  internalQuery,",
179 |       "  mutation,",
180 |       "  query,",
181 |       "} from \"./_generated/server\";",
182 |       "import schema from \"./schema\";",
183 |       "",
184 |       "test(\"$1\", async () => {",
185 |       "  const t = convexTest(schema);",
186 |       "  $0",
187 |       "});",
188 |     ],
189 |     "scope": "javascript,typescript",
190 |   },
191 | }
192 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/react/cache/provider.tsx:
--------------------------------------------------------------------------------
  1 | "use client";
  2 | import { useConvex, ConvexReactClient } from "convex/react";
  3 | import type { FunctionArgs, FunctionReference } from "convex/server";
  4 | import type { FC, PropsWithChildren } from "react";
  5 | import { createContext, useMemo } from "react";
  6 | 
  7 | export const ConvexQueryCacheContext = createContext({
  8 |   registry: null as CacheRegistry | null,
  9 | });
 10 | 
 11 | /**
 12 |  * A provider that establishes a query cache context in the React render
 13 |  * tree so that cached `useQuery` calls can be used.
 14 |  *
 15 |  * @component
 16 |  * @param {ConvexQueryCacheOptions} props.options - Options for the query cache
 17 |  * @returns {Element}
 18 |  */
 19 | export const ConvexQueryCacheProvider: FC<
 20 |   PropsWithChildren<ConvexQueryCacheOptions>
 21 | > = ({ children, debug, expiration, maxIdleEntries }) => {
 22 |   const convex = useConvex();
 23 |   if (convex === undefined) {
 24 |     throw new Error(
 25 |       "Could not find Convex client! `ConvexQueryCacheProvider` must be used in the React component " +
 26 |         "tree under `ConvexProvider`. Did you forget it? " +
 27 |         "See https://docs.convex.dev/quick-start#set-up-convex-in-your-react-app",
 28 |     );
 29 |   }
 30 |   const registry = useMemo(
 31 |     () => new CacheRegistry(convex, { debug, expiration, maxIdleEntries }),
 32 |     [convex, debug, expiration, maxIdleEntries],
 33 |   );
 34 |   return (
 35 |     <ConvexQueryCacheContext.Provider value={{ registry }}>
 36 |       {children}
 37 |     </ConvexQueryCacheContext.Provider>
 38 |   );
 39 | };
 40 | 
 41 | const DEFAULT_EXPIRATION_MS = 300_000; // 5 minutes
 42 | const DEFAULT_MAX_ENTRIES = 250;
 43 | 
 44 | export type ConvexQueryCacheOptions = {
 45 |   /**
 46 |    * How long, in milliseconds, to keep the subscription to the convex
 47 |    * query alive even after all references in the app have been dropped.
 48 |    *
 49 |    * @default 300000
 50 |    */
 51 |   expiration?: number;
 52 | 
 53 |   /**
 54 |    * How many "extra" idle query subscriptions are allowed to remain
 55 |    * connected to your convex backend.
 56 |    *
 57 |    * @default Infinity
 58 |    */
 59 |   maxIdleEntries?: number;
 60 | 
 61 |   /**
 62 |    * A debug flag that will cause information about the query cache
 63 |    * to be logged to the console every 3 seconds.
 64 |    *
 65 |    * @default false
 66 |    */
 67 |   debug?: boolean;
 68 | };
 69 | 
 70 | /**
 71 |  * Implementation of the query cache.
 72 |  */
 73 | 
 74 | type SubKey = string;
 75 | type QueryKey = string;
 76 | type CachedQuery = {
 77 |   refs: Set<string>;
 78 |   evictTimer: number | null; // SetTimeout
 79 |   unsub: () => void;
 80 | };
 81 | 
 82 | // Core caching structure.
 83 | class CacheRegistry {
 84 |   queries: Map<QueryKey, CachedQuery>;
 85 |   subs: Map<SubKey, QueryKey>;
 86 |   convex: ConvexReactClient;
 87 |   timeout: number;
 88 |   maxIdleEntries: number;
 89 |   idle: number;
 90 | 
 91 |   constructor(convex: ConvexReactClient, options: ConvexQueryCacheOptions) {
 92 |     this.queries = new Map();
 93 |     this.subs = new Map();
 94 |     this.convex = convex;
 95 |     this.idle = 0;
 96 |     this.timeout = options.expiration ?? DEFAULT_EXPIRATION_MS;
 97 |     this.maxIdleEntries = options.maxIdleEntries ?? DEFAULT_MAX_ENTRIES;
 98 |     if (options.debug ?? false) {
 99 |       const weakThis = new WeakRef(this);
100 |       const debugInterval = setInterval(() => {
101 |         const r = weakThis.deref();
102 |         if (r === undefined) {
103 |           clearInterval(debugInterval);
104 |         } else {
105 |           r.debug();
106 |         }
107 |       }, 3000);
108 |     }
109 |   }
110 | 
111 |   // Enable a new subscription.
112 |   start<Query extends FunctionReference<"query">>(
113 |     id: string,
114 |     queryKey: string,
115 |     query: Query,
116 |     args: FunctionArgs<Query>,
117 |   ): void {
118 |     let entry = this.queries.get(queryKey);
119 |     this.subs.set(id, queryKey);
120 |     if (entry === undefined) {
121 |       entry = {
122 |         refs: new Set(),
123 |         evictTimer: null,
124 |         // We only need to hold open subscriptions, we don't care about updates.
125 |         unsub: this.convex.watchQuery(query, args).onUpdate(() => {}),
126 |       };
127 |       this.queries.set(queryKey, entry);
128 |     } else if (entry.evictTimer !== null) {
129 |       this.idle -= 1;
130 |       clearTimeout(entry.evictTimer);
131 |       entry.evictTimer = null;
132 |     }
133 |     entry.refs.add(id);
134 |   }
135 |   // End a previous subscription.
136 |   end(id: string) {
137 |     const queryKey = this.subs.get(id);
138 |     if (queryKey) {
139 |       this.subs.delete(id);
140 |       const cq = this.queries.get(queryKey);
141 |       cq?.refs.delete(id);
142 |       // None left?
143 |       if (cq?.refs.size === 0) {
144 |         const remove = () => {
145 |           cq.unsub();
146 |           this.queries.delete(queryKey);
147 |         };
148 |         if (this.idle == this.maxIdleEntries) {
149 |           remove();
150 |         } else {
151 |           this.idle += 1;
152 |           const evictTimer = window.setTimeout(() => {
153 |             this.idle -= 1;
154 |             remove();
155 |           }, this.timeout);
156 |           cq.evictTimer = evictTimer;
157 |         }
158 |       }
159 |     }
160 |   }
161 |   debug() {
162 |     console.log("DEBUG CACHE");
163 |     console.log(`IDLE = ${this.idle}`);
164 |     console.log(" SUBS");
165 |     for (const [k, v] of this.subs.entries()) {
166 |       console.log(`  ${k} => ${v}`);
167 |     }
168 |     console.log(" QUERIES");
169 |     for (const [k, v] of this.queries.entries()) {
170 |       console.log(`  ${k} => ${v.refs.size} refs, evict = ${v.evictTimer}`);
171 |     }
172 |     console.log("~~~~~~~~~~~~~~~~~~~~~~");
173 |   }
174 | }
175 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/server/sessions.ts:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * Allows you to persist state server-side, associated with a sessionId stored
  3 |  * on the client (in localStorage, e.g.).
  4 |  *
  5 |  * You can define your function to take in a sessionId parameter of type
  6 |  * SessionId, which is just a branded string to help avoid errors.
  7 |  * The validator is vSessionId, or you can spread the argument in for your
  8 |  * function like this:
  9 |  * ```ts
 10 |  * const myMutation = mutation({
 11 |  *   args: {
 12 |  * 	 arg1: v.number(), // whatever other args you want
 13 |  * 	 ...SessionIdArg,
 14 |  *   },
 15 |  *   handler: async (ctx, args) => {
 16 |  *     // args.sessionId is a SessionId
 17 |  *   })
 18 |  * });
 19 |  * ```
 20 |  *
 21 |  * Then, on the client side, you can use {@link useSessionMutation} to call
 22 |  * your function with the sessionId automatically passed in, like:
 23 |  * ```ts
 24 |  * const myMutation = useSessionMutation(api.myModule.myMutation);
 25 |  * ...
 26 |  * await myMutation({ arg1: 123 });
 27 |  * ```
 28 |  *
 29 |  * To codify the sessionId parameter, you can use the customFunction module to
 30 |  * create a custom mutation or query, like:
 31 |  * ```ts
 32 |  * export const sessionMutation = customMutation(mutation, {
 33 |  *   args: { ...SessionIdArg },
 34 |  *   input: (ctx, { sessionId }) => {
 35 |  *     const anonUser = await getAnonymousUser(ctx, sessionId);
 36 |  *     return { ctx: { anonUser }, args: {} };
 37 |  *   },
 38 |  * });
 39 |  * ```
 40 |  *
 41 |  * Then you can define functions like:
 42 |  * ```ts
 43 |  * export const myMutation = sessionMutation({
 44 |  * 	 args: { arg1: v.number() }, // whatever other args you want
 45 |  *   handler: async (ctx, args) => {
 46 |  *     // ctx.anonUser exists and has a type from getAnonymousUser.
 47 |  *     // args is { arg1: number }
 48 |  *   })
 49 |  * });
 50 |  * ```
 51 |  *
 52 |  * See the associated [Stack post](https://stack.convex.dev/track-sessions-without-cookies)
 53 |  * for more information.
 54 |  */
 55 | import type {
 56 |   FunctionArgs,
 57 |   FunctionReference,
 58 |   FunctionReturnType,
 59 |   GenericActionCtx,
 60 |   GenericDataModel,
 61 | } from "convex/server";
 62 | import type { Validator } from "convex/values";
 63 | import { v } from "convex/values";
 64 | import type { BetterOmit, EmptyObject } from "../index.js";
 65 | 
 66 | // Branded string type for session IDs.
 67 | export type SessionId = string & { __SessionId: true };
 68 | // Validator for session IDs.
 69 | export const vSessionId = v.string() as Validator<SessionId>;
 70 | export const SessionIdArg = { sessionId: vSessionId };
 71 | 
 72 | type SessionFunction<
 73 |   T extends "query" | "mutation" | "action",
 74 |   Args = any,
 75 | > = FunctionReference<
 76 |   T,
 77 |   "public" | "internal",
 78 |   { sessionId: SessionId } & Args,
 79 |   any
 80 | >;
 81 | 
 82 | type SessionArgsArray<
 83 |   Fn extends SessionFunction<"query" | "mutation" | "action", any>,
 84 | > = keyof FunctionArgs<Fn> extends "sessionId"
 85 |   ? [args?: EmptyObject]
 86 |   : [args: BetterOmit<FunctionArgs<Fn>, "sessionId">];
 87 | 
 88 | export interface RunSessionFunctions {
 89 |   /**
 90 |    * Run the Convex query with the given name and arguments.
 91 |    *
 92 |    * Consider using an {@link internalQuery} to prevent users from calling the
 93 |    * query directly.
 94 |    *
 95 |    * @param query - A {@link FunctionReference} for the query to run.
 96 |    * @param args - The arguments to the query function.
 97 |    * @returns A promise of the query's result.
 98 |    */
 99 |   runSessionQuery<Query extends SessionFunction<"query">>(
100 |     query: Query,
101 |     ...args: SessionArgsArray<Query>
102 |   ): Promise<FunctionReturnType<Query>>;
103 | 
104 |   /**
105 |    * Run the Convex mutation with the given name and arguments.
106 |    *
107 |    * Consider using an {@link internalMutation} to prevent users from calling
108 |    * the mutation directly.
109 |    *
110 |    * @param mutation - A {@link FunctionReference} for the mutation to run.
111 |    * @param args - The arguments to the mutation function.
112 |    * @returns A promise of the mutation's result.
113 |    */
114 |   runSessionMutation<Mutation extends SessionFunction<"mutation">>(
115 |     mutation: Mutation,
116 |     ...args: SessionArgsArray<Mutation>
117 |   ): Promise<FunctionReturnType<Mutation>>;
118 | 
119 |   /**
120 |    * Run the Convex action with the given name and arguments.
121 |    *
122 |    * Consider using an {@link internalAction} to prevent users from calling the
123 |    * action directly.
124 |    *
125 |    * @param action - A {@link FunctionReference} for the action to run.
126 |    * @param args - The arguments to the action function.
127 |    * @returns A promise of the action's result.
128 |    */
129 |   runSessionAction<Action extends SessionFunction<"action">>(
130 |     action: Action,
131 |     ...args: SessionArgsArray<Action>
132 |   ): Promise<FunctionReturnType<Action>>;
133 | }
134 | export function runSessionFunctions<DataModel extends GenericDataModel>(
135 |   ctx: GenericActionCtx<DataModel>,
136 |   sessionId: SessionId,
137 | ): RunSessionFunctions {
138 |   return {
139 |     runSessionQuery(fn, ...args) {
140 |       const argsWithSession = { ...(args[0] ?? {}), sessionId } as FunctionArgs<
141 |         typeof fn
142 |       >;
143 |       return ctx.runQuery(fn, argsWithSession);
144 |     },
145 |     runSessionMutation(fn, ...args) {
146 |       const argsWithSession = { ...(args[0] ?? {}), sessionId } as FunctionArgs<
147 |         typeof fn
148 |       >;
149 |       return ctx.runMutation(fn, argsWithSession);
150 |     },
151 |     runSessionAction(fn, ...args) {
152 |       const argsWithSession = { ...(args[0] ?? {}), sessionId } as FunctionArgs<
153 |         typeof fn
154 |       >;
155 |       return ctx.runAction(fn, argsWithSession);
156 |     },
157 |   };
158 | }
159 | 


--------------------------------------------------------------------------------
/convex/triggersExample.ts:
--------------------------------------------------------------------------------
  1 | import {
  2 |   customCtx,
  3 |   customMutation,
  4 | } from "convex-helpers/server/customFunctions";
  5 | import { DataModel, Id } from "./_generated/dataModel";
  6 | import {
  7 |   MutationCtx,
  8 |   query,
  9 |   mutation as rawMutation,
 10 |   internalMutation as rawInternalMutation,
 11 | } from "./_generated/server";
 12 | import { Triggers } from "convex-helpers/server/triggers";
 13 | import { v } from "convex/values";
 14 | import { internal } from "./_generated/api";
 15 | 
 16 | const triggers = new Triggers<DataModel, MutationCtx>();
 17 | 
 18 | // Example of a trigger that rounds up every counter to a multiple of 10,
 19 | // demonstrating that triggers can trigger themselves.
 20 | triggers.register("counter_table", async (ctx, change) => {
 21 |   if (change.operation === "insert") {
 22 |     console.log("Counter created", change.newDoc);
 23 |   }
 24 |   if (change.newDoc && change.newDoc.counter % 10 !== 0) {
 25 |     // Round up to the nearest multiple of 10, one at a time.
 26 |     // This demonstrates that triggers can trigger themselves.
 27 |     console.log("Incrementing counter to", change.newDoc.counter + 1);
 28 |     await ctx.db.patch(change.newDoc._id, {
 29 |       counter: change.newDoc.counter + 1,
 30 |     });
 31 |   }
 32 | });
 33 | 
 34 | // Call logCounterChange async after the mutation completes.
 35 | let scheduledJobId: Id<"_scheduled_functions"> | null = null;
 36 | triggers.register("counter_table", async (ctx, change) => {
 37 |   if (scheduledJobId !== null) {
 38 |     await ctx.scheduler.cancel(scheduledJobId);
 39 |   }
 40 |   if (change.newDoc) {
 41 |     console.log("scheduling logCounterChange", change.newDoc.counter);
 42 |     scheduledJobId = await ctx.scheduler.runAfter(
 43 |       0,
 44 |       internal.triggersExample.logCounterChange,
 45 |       { name: change.newDoc.name, counter: change.newDoc.counter },
 46 |     );
 47 |   }
 48 | });
 49 | 
 50 | // Track denormalized sum of all counters.
 51 | triggers.register("counter_table", async (ctx, change) => {
 52 |   const sum = await ctx.db.query("sum_table").first();
 53 |   if (!sum) {
 54 |     await ctx.db.insert("sum_table", { sum: 0 });
 55 |   }
 56 |   const sumDoc = (await ctx.db.query("sum_table").first())!;
 57 |   if (change.operation === "insert") {
 58 |     await ctx.db.patch(sumDoc._id, { sum: sumDoc.sum + change.newDoc.counter });
 59 |   } else if (change.operation === "update") {
 60 |     await ctx.db.patch(sumDoc._id, {
 61 |       sum: sumDoc.sum + change.newDoc.counter - change.oldDoc.counter,
 62 |     });
 63 |   } else if (change.operation === "delete") {
 64 |     await ctx.db.patch(sumDoc._id, { sum: sumDoc.sum - change.oldDoc.counter });
 65 |   }
 66 | });
 67 | 
 68 | export const mutation = customMutation(rawMutation, customCtx(triggers.wrapDB));
 69 | export const internalMutation = customMutation(
 70 |   rawInternalMutation,
 71 |   customCtx(triggers.wrapDB),
 72 | );
 73 | 
 74 | export const logCounterChange = internalMutation({
 75 |   args: { name: v.string(), counter: v.number() },
 76 |   handler: async (_ctx, { name, counter }) => {
 77 |     console.log(`Counter ${name} changed to ${counter}`);
 78 |   },
 79 | });
 80 | 
 81 | // This checks that many triggers happening in parallel won't race with each
 82 | // other. whatever the value ends up being, that will be the change to the sum.
 83 | export const incrementCounterRace = mutation({
 84 |   args: {},
 85 |   handler: async ({ db }) => {
 86 |     const firstCounter = await db.query("counter_table").first();
 87 |     if (!firstCounter) {
 88 |       throw new Error("No counters");
 89 |     }
 90 |     await Promise.all([
 91 |       db.patch(firstCounter._id, { counter: firstCounter.counter + 1 }),
 92 |       db.patch(firstCounter._id, { counter: firstCounter.counter + 2 }),
 93 |       db.patch(firstCounter._id, { counter: firstCounter.counter + 3 }),
 94 |     ]);
 95 |   },
 96 | });
 97 | 
 98 | export const getSum = query({
 99 |   args: {},
100 |   handler: async (ctx, _args) => {
101 |     return ctx.db.query("sum_table").first();
102 |   },
103 | });
104 | 
105 | /// Example of using triggers to implement the write side of row-level security,
106 | /// with a precomputed value `viewer` passed in to every trigger through the ctx.
107 | 
108 | const triggersWithRLS = new Triggers<
109 |   DataModel,
110 |   MutationCtx & { viewer: string | null }
111 | >();
112 | 
113 | triggersWithRLS.register("users", async (ctx, change) => {
114 |   const oldTokenIdentifier = change?.oldDoc?.tokenIdentifier;
115 |   if (oldTokenIdentifier && oldTokenIdentifier !== ctx.viewer) {
116 |     throw new Error(`You can only modify your own user`);
117 |   }
118 |   const newTokenIdentifier = change?.oldDoc?.tokenIdentifier;
119 |   if (newTokenIdentifier && newTokenIdentifier !== ctx.viewer) {
120 |     throw new Error(`You can only modify your own user`);
121 |   }
122 | });
123 | 
124 | const mutationWithRLS = customMutation(
125 |   rawMutation,
126 |   customCtx(async (ctx) => {
127 |     const viewer = (await ctx.auth.getUserIdentity())?.tokenIdentifier ?? null;
128 |     // Note: you can add more things to the ctx than the registered triggers
129 |     // require, and the types will flow through.
130 |     return triggersWithRLS.wrapDB({ ...ctx, viewer, foo: "bar" });
131 |   }),
132 | );
133 | 
134 | export const updateName = mutationWithRLS({
135 |   // Note: it's generally a bad idea to pass your own user's ID
136 |   // instead, you should just pull the user from the auth context
137 |   // but this is just an example to show that this is safe, since the RLS rules
138 |   // will prevent you from modifying other users.
139 |   args: { name: v.string(), userId: v.id("users") },
140 |   handler: async (ctx, { name, userId }) => {
141 |     // The extra type from above still comes through
142 |     console.log(ctx.foo);
143 |     await ctx.db.patch(userId, { name });
144 |   },
145 | });
146 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/server/table.test.ts:
--------------------------------------------------------------------------------
  1 | import { omit, pick, pruneNull } from "../index.js";
  2 | import { Table } from "../server.js";
  3 | import { partial } from "../validators.js";
  4 | import { convexTest } from "convex-test";
  5 | import type {
  6 |   ApiFromModules,
  7 |   DataModelFromSchemaDefinition,
  8 |   MutationBuilder,
  9 |   QueryBuilder,
 10 | } from "convex/server";
 11 | import {
 12 |   anyApi,
 13 |   defineSchema,
 14 |   internalMutationGeneric,
 15 |   internalQueryGeneric,
 16 | } from "convex/server";
 17 | import { v } from "convex/values";
 18 | import { assertType, expect, test } from "vitest";
 19 | import { modules } from "./setup.test.js";
 20 | 
 21 | // Define a table with system fields _id and _creationTime. This also returns
 22 | // helpers for working with the table in validators. See:
 23 | // https://stack.convex.dev/argument-validation-without-repetition#table-helper-for-schema-definition--validation
 24 | const Example = Table("table_example", {
 25 |   foo: v.string(),
 26 |   bar: v.union(v.number(), v.null()),
 27 |   baz: v.optional(v.boolean()),
 28 | });
 29 | 
 30 | const schema = defineSchema({
 31 |   [Example.name]: Example.table.index("by_foo", ["foo"]),
 32 | });
 33 | type DataModel = DataModelFromSchemaDefinition<typeof schema>;
 34 | const internalQuery = internalQueryGeneric as QueryBuilder<
 35 |   DataModel,
 36 |   "internal"
 37 | >;
 38 | const internalMutation = internalMutationGeneric as MutationBuilder<
 39 |   DataModel,
 40 |   "internal"
 41 | >;
 42 | 
 43 | export const allAtOnce = internalQuery({
 44 |   args: {
 45 |     id: Example._id,
 46 |     whole: Example.doc,
 47 |     insertable: v.object(Example.withoutSystemFields),
 48 |     patchable: v.object(partial(Example.withoutSystemFields)),
 49 |     replaceable: v.object({
 50 |       ...Example.withoutSystemFields,
 51 |       ...partial(Example.systemFields),
 52 |     }),
 53 |     picked: v.object(pick(Example.withSystemFields, ["foo", "bar"])),
 54 |     omitted: v.object(omit(Example.withSystemFields, ["foo"])),
 55 |   },
 56 |   handler: async (_ctx, args) => {
 57 |     return args;
 58 |   },
 59 | });
 60 | 
 61 | export const get = internalQuery({
 62 |   args: { id: Example._id },
 63 |   handler: async (ctx, args) => {
 64 |     return await ctx.db.get(args.id);
 65 |   },
 66 | });
 67 | 
 68 | export const docAsParam = internalQuery({
 69 |   args: { docs: v.array(Example.doc) },
 70 |   handler: async (ctx, args) => {
 71 |     return args.docs.map((doc) => {
 72 |       return `${doc.foo} ${doc.bar} ${doc.baz}`;
 73 |     });
 74 |   },
 75 | });
 76 | 
 77 | export const insert = internalMutation({
 78 |   args: Example.withoutSystemFields,
 79 |   handler: async (ctx, args) => {
 80 |     assertType<keyof typeof args extends "_id" ? false : true>(true);
 81 |     return ctx.db.insert(Example.name, args);
 82 |   },
 83 | });
 84 | 
 85 | export const patch = internalMutation({
 86 |   args: {
 87 |     id: Example._id,
 88 |     patch: v.object(partial(Example.withoutSystemFields)),
 89 |   },
 90 |   handler: async (ctx, args) => {
 91 |     await ctx.db.patch(args.id, args.patch);
 92 |   },
 93 | });
 94 | 
 95 | export const replace = internalMutation({
 96 |   args: {
 97 |     // You can provide the document with or without system fields.
 98 |     ...Example.withoutSystemFields,
 99 |     ...partial(Example.systemFields),
100 |     _id: Example._id,
101 |   },
102 |   handler: async (ctx, args) => {
103 |     await ctx.db.replace(args._id, args);
104 |   },
105 | });
106 | 
107 | const testApi: ApiFromModules<{
108 |   fns: {
109 |     allAtOnce: typeof allAtOnce;
110 |     get: typeof get;
111 |     docAsParam: typeof docAsParam;
112 |     insert: typeof insert;
113 |     patch: typeof patch;
114 |     replace: typeof replace;
115 |   };
116 | }>["fns"] = anyApi["table.test"] as any;
117 | 
118 | test("crud for table", async () => {
119 |   const t = convexTest(schema, modules);
120 |   const id = await t.mutation(testApi.insert, {
121 |     foo: "",
122 |     bar: null,
123 |   });
124 |   const original = await t.query(testApi.get, { id });
125 |   expect(original).toMatchObject({ foo: "", bar: null });
126 |   await t.mutation(testApi.patch, {
127 |     id,
128 |     patch: { foo: "new", baz: true },
129 |   });
130 |   const patched = await t.query(testApi.get, { id });
131 |   expect(patched).toMatchObject({ foo: "new", bar: null, baz: true });
132 |   if (!patched) throw new Error("patched is undefined");
133 |   const toReplace = { ...patched, bar: 42, _creationTime: undefined };
134 |   await t.mutation(testApi.replace, toReplace);
135 |   const replaced = await t.query(testApi.get, { id });
136 |   expect(replaced).toMatchObject({ foo: "new", bar: 42, baz: true });
137 |   expect(replaced?._id).toBe(patched._id);
138 |   const docs = await t.query(testApi.docAsParam, {
139 |     docs: pruneNull([original, patched, replaced]),
140 |   });
141 |   expect(docs).toEqual([" null undefined", "new null true", "new 42 true"]);
142 | });
143 | 
144 | test("all at once", async () => {
145 |   const t = convexTest(schema, modules);
146 |   const id = await t.mutation(testApi.insert, {
147 |     foo: "foo",
148 |     bar: 123,
149 |     baz: false,
150 |   });
151 |   const whole = await t.query(testApi.get, { id });
152 |   if (!whole) throw new Error("whole is undefined");
153 |   const { foo, ...omitted } = whole;
154 |   const all = await t.query(testApi.allAtOnce, {
155 |     id,
156 |     whole,
157 |     insertable: { foo: "insert", bar: 42 },
158 |     patchable: { foo: "patch" },
159 |     replaceable: { foo: "replace", bar: 42, baz: true },
160 |     picked: { foo, bar: null },
161 |     omitted,
162 |   });
163 |   expect(all).toMatchObject({
164 |     id,
165 |     whole,
166 |     insertable: { foo: "insert", bar: 42 },
167 |     patchable: { foo: "patch" },
168 |     replaceable: { foo: "replace", bar: 42 },
169 |     picked: { foo, bar: null },
170 |     omitted,
171 |   });
172 | });
173 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/index.ts:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * asyncMap returns the results of applying an async function over an list.
  3 |  *
  4 |  * The list can even be a promise, or an iterable like a Set.
  5 |  * @param list - Iterable object of items, e.g. an Array, Set, Object.keys
  6 |  * @param asyncTransform
  7 |  * @returns
  8 |  */
  9 | export async function asyncMap<FromType, ToType>(
 10 |   list: Iterable<FromType> | Promise<Iterable<FromType>>,
 11 |   asyncTransform: (item: FromType, index: number) => Promise<ToType>,
 12 | ): Promise<ToType[]> {
 13 |   const promises: Promise<ToType>[] = [];
 14 |   let index = 0;
 15 |   list = await list;
 16 |   for (const item of list) {
 17 |     promises.push(asyncTransform(item, index));
 18 |     index += 1;
 19 |   }
 20 |   return Promise.all(promises);
 21 | }
 22 | 
 23 | /**
 24 |  * Filters out null elements from an array.
 25 |  * @param list List of elements that might be null.
 26 |  * @returns List of elements with nulls removed.
 27 |  */
 28 | export function pruneNull<T>(list: (T | null)[]): T[] {
 29 |   return list.filter((i) => i !== null) as T[];
 30 | }
 31 | 
 32 | export class NullDocumentError extends Error {}
 33 | 
 34 | /**
 35 |  * Throws if there is a null element in the array.
 36 |  * @param list List of elements that might have a null element.
 37 |  * @returns Same list of elements with a refined type.
 38 |  */
 39 | export function nullThrows<T>(doc: T | null, message?: string): T {
 40 |   if (doc === null) {
 41 |     throw new NullDocumentError(message ?? "Unexpected null document.");
 42 |   }
 43 |   return doc;
 44 | }
 45 | 
 46 | /**
 47 |  * pick helps you pick keys from an object more concisely.
 48 |  *
 49 |  * e.g. `pick({a: v.string(), b: v.number()}, ["a"])` is equivalent to
 50 |  * `{a: v.string()}`
 51 |  * The alternative could be something like:
 52 |  * ```js
 53 |  * const obj = { a: v.string(), b: v.number() };
 54 |  * // pick does the following
 55 |  * const { a } = obj;
 56 |  * const onlyA = { a };
 57 |  * ```
 58 |  *
 59 |  * @param obj The object to pick from. Often like { a: v.string() }
 60 |  * @param keys The keys to pick from the object.
 61 |  * @returns A new object with only the keys you picked and their values.
 62 |  */
 63 | export function pick<T extends Record<string, any>, Keys extends (keyof T)[]>(
 64 |   obj: T,
 65 |   keys: Keys,
 66 | ) {
 67 |   return Object.fromEntries(
 68 |     Object.entries(obj).filter(([k]) => keys.includes(k as Keys[number])),
 69 |   ) as {
 70 |     [K in Keys[number]]: T[K];
 71 |   };
 72 | }
 73 | 
 74 | /**
 75 |  * omit helps you omit keys from an object more concisely.
 76 |  *
 77 |  * e.g. `omit({a: v.string(), b: v.number()}, ["a"])` is equivalent to
 78 |  * `{b: v.number()}`
 79 |  *
 80 |  * The alternative could be something like:
 81 |  * ```js
 82 |  * const obj = { a: v.string(), b: v.number() };
 83 |  * // omit does the following
 84 |  * const { a, ...rest } = obj;
 85 |  * const withoutA = rest;
 86 |  * ```
 87 |  *
 88 |  * @param obj The object to return a copy of without the specified keys.
 89 |  * @param keys The keys to omit from the object.
 90 |  * @returns A new object with the keys you omitted removed.
 91 |  */
 92 | export function omit<T extends Record<string, any>, Keys extends (keyof T)[]>(
 93 |   obj: T,
 94 |   keys: Keys,
 95 | ) {
 96 |   return Object.fromEntries(
 97 |     Object.entries(obj).filter(([k]) => !keys.includes(k as Keys[number])),
 98 |   ) as Expand<BetterOmit<T, Keys[number]>>;
 99 | }
100 | 
101 | /**
102 |  * Removes the _id and _creationTime fields from an object.
103 |  * This enables easily cloning a Convex document like:
104 |  * ```ts
105 |  * const doc = await db.get(id);
106 |  * const clone = withoutSystemFields(doc);
107 |  * await db.insert(table, clone);
108 |  * ```
109 |  * @param obj The object to remove the _id and _creationTime fields from.
110 |  * @returns A new object with the _id and _creationTime fields removed.
111 |  */
112 | export function withoutSystemFields<T extends Record<string, any>>(obj: T) {
113 |   return omit(obj, ["_id", "_creationTime"]);
114 | }
115 | 
116 | // Type utils:
117 | const _error = Symbol();
118 | export type ErrorMessage<Reason extends string> = Reason & {
119 |   __error: typeof _error;
120 | };
121 | 
122 | // Copied from convex/server since it wasn't exported
123 | export type EmptyObject = Record<string, never>;
124 | /**
125 |  * An `Omit<>` type that:
126 |  * 1. Applies to each element of a union.
127 |  * 2. Preserves the index signature of the underlying type.
128 |  */
129 | export type BetterOmit<T, K extends keyof T> = {
130 |   [Property in keyof T as Property extends K ? never : Property]: T[Property];
131 | };
132 | 
133 | /**
134 |  * Hack! This type causes TypeScript to simplify how it renders object types.
135 |  *
136 |  * It is functionally the identity for object types, but in practice it can
137 |  * simplify expressions like `A & B`.
138 |  */
139 | export type Expand<ObjectType extends Record<any, any>> =
140 |   ObjectType extends Record<any, any>
141 |     ? {
142 |         [Key in keyof ObjectType]: ObjectType[Key];
143 |       }
144 |     : never;
145 | 
146 | /**
147 |  * TESTS
148 |  */
149 | /**
150 |  * Tests if two types are exactly the same.
151 |  * Taken from https://github.com/Microsoft/TypeScript/issues/27024#issuecomment-421529650
152 |  * (Apache Version 2.0, January 2004)
153 |  */
154 | export type Equals<X, Y> =
155 |   (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2
156 |     ? true
157 |     : false;
158 | 
159 | /**
160 |  * A utility to validate truthiness at runtime, providing a type guard
161 |  *
162 |  * @example
163 |  * ```ts
164 |  * const x: string | null = getValue();
165 |  * assert(x);
166 |  * // x is now of type string
167 |  * ```
168 |  * @param arg A value to assert the truthiness of.
169 |  * @param message An optional message to throw if the value is not truthy.
170 |  */
171 | export function assert(value: unknown, message?: string): asserts value {
172 |   if (!value) {
173 |     throw new Error(message);
174 |   }
175 | }
176 | 


--------------------------------------------------------------------------------
/convex/_generated/server.d.ts:
--------------------------------------------------------------------------------
  1 | /* eslint-disable */
  2 | /**
  3 |  * Generated utilities for implementing server-side Convex query and mutation functions.
  4 |  *
  5 |  * THIS CODE IS AUTOMATICALLY GENERATED.
  6 |  *
  7 |  * To regenerate, run `npx convex dev`.
  8 |  * @module
  9 |  */
 10 | 
 11 | import {
 12 |   ActionBuilder,
 13 |   HttpActionBuilder,
 14 |   MutationBuilder,
 15 |   QueryBuilder,
 16 |   GenericActionCtx,
 17 |   GenericMutationCtx,
 18 |   GenericQueryCtx,
 19 |   GenericDatabaseReader,
 20 |   GenericDatabaseWriter,
 21 | } from "convex/server";
 22 | import type { DataModel } from "./dataModel.js";
 23 | 
 24 | /**
 25 |  * Define a query in this Convex app's public API.
 26 |  *
 27 |  * This function will be allowed to read your Convex database and will be accessible from the client.
 28 |  *
 29 |  * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
 30 |  * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
 31 |  */
 32 | export declare const query: QueryBuilder<DataModel, "public">;
 33 | 
 34 | /**
 35 |  * Define a query that is only accessible from other Convex functions (but not from the client).
 36 |  *
 37 |  * This function will be allowed to read from your Convex database. It will not be accessible from the client.
 38 |  *
 39 |  * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
 40 |  * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
 41 |  */
 42 | export declare const internalQuery: QueryBuilder<DataModel, "internal">;
 43 | 
 44 | /**
 45 |  * Define a mutation in this Convex app's public API.
 46 |  *
 47 |  * This function will be allowed to modify your Convex database and will be accessible from the client.
 48 |  *
 49 |  * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
 50 |  * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
 51 |  */
 52 | export declare const mutation: MutationBuilder<DataModel, "public">;
 53 | 
 54 | /**
 55 |  * Define a mutation that is only accessible from other Convex functions (but not from the client).
 56 |  *
 57 |  * This function will be allowed to modify your Convex database. It will not be accessible from the client.
 58 |  *
 59 |  * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
 60 |  * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
 61 |  */
 62 | export declare const internalMutation: MutationBuilder<DataModel, "internal">;
 63 | 
 64 | /**
 65 |  * Define an action in this Convex app's public API.
 66 |  *
 67 |  * An action is a function which can execute any JavaScript code, including non-deterministic
 68 |  * code and code with side-effects, like calling third-party services.
 69 |  * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
 70 |  * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
 71 |  *
 72 |  * @param func - The action. It receives an {@link ActionCtx} as its first argument.
 73 |  * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
 74 |  */
 75 | export declare const action: ActionBuilder<DataModel, "public">;
 76 | 
 77 | /**
 78 |  * Define an action that is only accessible from other Convex functions (but not from the client).
 79 |  *
 80 |  * @param func - The function. It receives an {@link ActionCtx} as its first argument.
 81 |  * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
 82 |  */
 83 | export declare const internalAction: ActionBuilder<DataModel, "internal">;
 84 | 
 85 | /**
 86 |  * Define an HTTP action.
 87 |  *
 88 |  * The wrapped function will be used to respond to HTTP requests received
 89 |  * by a Convex deployment if the requests matches the path and method where
 90 |  * this action is routed. Be sure to route your httpAction in `convex/http.js`.
 91 |  *
 92 |  * @param func - The function. It receives an {@link ActionCtx} as its first argument
 93 |  * and a Fetch API `Request` object as its second.
 94 |  * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
 95 |  */
 96 | export declare const httpAction: HttpActionBuilder;
 97 | 
 98 | /**
 99 |  * A set of services for use within Convex query functions.
100 |  *
101 |  * The query context is passed as the first argument to any Convex query
102 |  * function run on the server.
103 |  *
104 |  * This differs from the {@link MutationCtx} because all of the services are
105 |  * read-only.
106 |  */
107 | export type QueryCtx = GenericQueryCtx<DataModel>;
108 | 
109 | /**
110 |  * A set of services for use within Convex mutation functions.
111 |  *
112 |  * The mutation context is passed as the first argument to any Convex mutation
113 |  * function run on the server.
114 |  */
115 | export type MutationCtx = GenericMutationCtx<DataModel>;
116 | 
117 | /**
118 |  * A set of services for use within Convex action functions.
119 |  *
120 |  * The action context is passed as the first argument to any Convex action
121 |  * function run on the server.
122 |  */
123 | export type ActionCtx = GenericActionCtx<DataModel>;
124 | 
125 | /**
126 |  * An interface to read from the database within Convex query functions.
127 |  *
128 |  * The two entry points are {@link DatabaseReader.get}, which fetches a single
129 |  * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
130 |  * building a query.
131 |  */
132 | export type DatabaseReader = GenericDatabaseReader<DataModel>;
133 | 
134 | /**
135 |  * An interface to read from and write to the database within Convex mutation
136 |  * functions.
137 |  *
138 |  * Convex guarantees that all writes within a single mutation are
139 |  * executed atomically, so you never have to worry about partial writes leaving
140 |  * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
141 |  * for the guarantees Convex provides your functions.
142 |  */
143 | export type DatabaseWriter = GenericDatabaseWriter<DataModel>;
144 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/package.json:
--------------------------------------------------------------------------------
  1 | {
  2 |   "name": "convex-helpers",
  3 |   "version": "0.1.107",
  4 |   "description": "A collection of useful code to complement the official convex package.",
  5 |   "type": "module",
  6 |   "bin": {
  7 |     "convex-helpers": "bin.cjs"
  8 |   },
  9 |   "exports": {
 10 |     ".": {
 11 |       "types": "./index.d.ts",
 12 |       "default": "./index.js"
 13 |     },
 14 |     "./browser": {
 15 |       "types": "./browser.d.ts",
 16 |       "default": "./browser.js"
 17 |     },
 18 |     "./testing": {
 19 |       "types": "./testing.d.ts",
 20 |       "default": "./testing.js"
 21 |     },
 22 |     "./validators": {
 23 |       "types": "./validators.d.ts",
 24 |       "default": "./validators.js"
 25 |     },
 26 |     "./server": {
 27 |       "types": "./server.d.ts",
 28 |       "default": "./server.js"
 29 |     },
 30 |     "./standardSchema": {
 31 |       "types": "./standardSchema.d.ts",
 32 |       "default": "./standardSchema.js"
 33 |     },
 34 |     "./react": {
 35 |       "types": "./react.d.ts",
 36 |       "default": "./react.js"
 37 |     },
 38 |     "./react/cache": {
 39 |       "types": "./react/cache.d.ts",
 40 |       "default": "./react/cache.js"
 41 |     },
 42 |     "./react/sessions": {
 43 |       "types": "./react/sessions.d.ts",
 44 |       "default": "./react/sessions.js"
 45 |     },
 46 |     "./react/cache/hooks": {
 47 |       "types": "./react/cache/hooks.d.ts",
 48 |       "default": "./react/cache/hooks.js"
 49 |     },
 50 |     "./react/cache/provider": {
 51 |       "types": "./react/cache/provider.d.ts",
 52 |       "default": "./react/cache/provider.js"
 53 |     },
 54 |     "./server/compare": {
 55 |       "types": "./server/compare.d.ts",
 56 |       "default": "./server/compare.js"
 57 |     },
 58 |     "./server/cors": {
 59 |       "types": "./server/cors.d.ts",
 60 |       "default": "./server/cors.js"
 61 |     },
 62 |     "./server/crud": {
 63 |       "types": "./server/crud.d.ts",
 64 |       "default": "./server/crud.js"
 65 |     },
 66 |     "./server/customFunctions": {
 67 |       "types": "./server/customFunctions.d.ts",
 68 |       "default": "./server/customFunctions.js"
 69 |     },
 70 |     "./server/filter": {
 71 |       "types": "./server/filter.d.ts",
 72 |       "default": "./server/filter.js"
 73 |     },
 74 |     "./server/hono": {
 75 |       "types": "./server/hono.d.ts",
 76 |       "default": "./server/hono.js"
 77 |     },
 78 |     "./server/migrations": {
 79 |       "types": "./server/migrations.d.ts",
 80 |       "default": "./server/migrations.js"
 81 |     },
 82 |     "./server/pagination": {
 83 |       "types": "./server/pagination.d.ts",
 84 |       "default": "./server/pagination.js"
 85 |     },
 86 |     "./server/rateLimit": {
 87 |       "types": "./server/rateLimit.d.ts",
 88 |       "default": "./server/rateLimit.js"
 89 |     },
 90 |     "./server/relationships": {
 91 |       "types": "./server/relationships.d.ts",
 92 |       "default": "./server/relationships.js"
 93 |     },
 94 |     "./server/retries": {
 95 |       "types": "./server/retries.d.ts",
 96 |       "default": "./server/retries.js"
 97 |     },
 98 |     "./server/rowLevelSecurity": {
 99 |       "types": "./server/rowLevelSecurity.d.ts",
100 |       "default": "./server/rowLevelSecurity.js"
101 |     },
102 |     "./server/sessions": {
103 |       "types": "./server/sessions.d.ts",
104 |       "default": "./server/sessions.js"
105 |     },
106 |     "./server/stream": {
107 |       "types": "./server/stream.d.ts",
108 |       "default": "./server/stream.js"
109 |     },
110 |     "./server/triggers": {
111 |       "types": "./server/triggers.d.ts",
112 |       "default": "./server/triggers.js"
113 |     },
114 |     "./server/zod": {
115 |       "types": "./server/zod.d.ts",
116 |       "default": "./server/zod.js"
117 |     },
118 |     "./server/zod3": {
119 |       "types": "./server/zod3.d.ts",
120 |       "default": "./server/zod3.js"
121 |     },
122 |     "./server/zod4": {
123 |       "types": "./server/zod4.d.ts",
124 |       "default": "./server/zod4.js"
125 |     },
126 |     "./react/*": {
127 |       "types": "./react/*.d.ts",
128 |       "default": "./react/*.js"
129 |     },
130 |     "./react/cache/*": {
131 |       "types": "./react/cache/*.d.ts",
132 |       "default": "./react/cache/*.js"
133 |     },
134 |     "./server/*": {
135 |       "types": "./server/*.d.ts",
136 |       "default": "./server/*.js"
137 |     }
138 |   },
139 |   "scripts": {
140 |     "build:bin": "esbuild ./cli/index.ts --bundle --platform=node --external:prettier --format=cjs --outfile=dist/bin.cjs",
141 |     "build": "node generate-exports.mjs && mkdir -p dist && npm run build:bin && cp -r *.ts server react ./package.json ./tsconfig.json ./README.md ../../LICENSE ./.npmignore dist/ && cd dist/ && rm **/*.test.* && rm -r server/_generated && tsc",
142 |     "dev": "chokidar '*.ts' 'server/**/*.ts' 'react/**/*.ts*' 'tsconfig*.json' 'package.json' -i '**/*.test.ts' -c 'cd ../.. && npm run build' --initial",
143 |     "typecheck": "tsc --noEmit",
144 |     "version": "pbcopy <<<$npm_package_version; vim CHANGELOG.md && prettier --write CHANGELOG.md && git add CHANGELOG.md"
145 |   },
146 |   "repository": {
147 |     "type": "git",
148 |     "url": "git+https://github.com/get-convex/convex-helpers.git",
149 |     "directory": "packages/convex-helpers"
150 |   },
151 |   "keywords": [
152 |     "convex",
153 |     "backend",
154 |     "migrations",
155 |     "ratelimit",
156 |     "database",
157 |     "react"
158 |   ],
159 |   "author": "Ian Macartney <ian@convex.dev>",
160 |   "license": "Apache-2.0",
161 |   "bugs": {
162 |     "url": "https://github.com/get-convex/convex-helpers/issues"
163 |   },
164 |   "homepage": "https://github.com/get-convex/convex-helpers/tree/main/packages/convex-helpers/README.md",
165 |   "peerDependencies": {
166 |     "@standard-schema/spec": "^1.0.0",
167 |     "convex": "^1.25.4",
168 |     "hono": "^4.0.5",
169 |     "react": "^17.0.2 || ^18.0.0 || ^19.0.0",
170 |     "typescript": "^5.5",
171 |     "zod": "^3.25.0 || ^4.0.0"
172 |   },
173 |   "peerDependenciesMeta": {
174 |     "@standard-schema/spec": {
175 |       "optional": true
176 |     },
177 |     "hono": {
178 |       "optional": true
179 |     },
180 |     "react": {
181 |       "optional": true
182 |     },
183 |     "typescript": {
184 |       "optional": true
185 |     },
186 |     "zod": {
187 |       "optional": true
188 |     }
189 |   }
190 | }
191 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/server/crud.ts:
--------------------------------------------------------------------------------
  1 | import type {
  2 |   QueryBuilder,
  3 |   MutationBuilder,
  4 |   WithoutSystemFields,
  5 |   DocumentByName,
  6 |   RegisteredMutation,
  7 |   RegisteredQuery,
  8 |   FunctionVisibility,
  9 |   PaginationResult,
 10 |   SchemaDefinition,
 11 |   GenericSchema,
 12 |   TableNamesInDataModel,
 13 |   DataModelFromSchemaDefinition,
 14 | } from "convex/server";
 15 | import {
 16 |   paginationOptsValidator,
 17 |   internalQueryGeneric,
 18 |   internalMutationGeneric,
 19 | } from "convex/server";
 20 | import type {
 21 |   GenericId,
 22 |   Infer,
 23 |   Validator,
 24 |   VObject,
 25 |   VUnion,
 26 | } from "convex/values";
 27 | import { v } from "convex/values";
 28 | import { doc, partial, systemFields } from "../validators.js";
 29 | /**
 30 |  * Create CRUD operations for a table.
 31 |  * You can expose these operations in your API. For example, in convex/users.ts:
 32 |  *
 33 |  * ```ts
 34 |  * // in convex/users.ts
 35 |  * import { crud } from "convex-helpers/server/crud";
 36 |  * import schema from "./schema";
 37 |  *
 38 |  * export const { create, read, update, destroy } = crud(schema, "users");
 39 |  * ```
 40 |  *
 41 |  * Then you can access the functions like `internal.users.create` from actions.
 42 |  *
 43 |  * To expose these functions publicly, you can pass in custom query and
 44 |  * mutation arguments. Be careful what you expose publicly: you wouldn't want
 45 |  * any client to be able to delete users, for example.
 46 |  *
 47 |  * @param schema Your project's schema.
 48 |  * @param table The table name to create CRUD operations for.
 49 |  * @param query The query to use - use internalQuery or query from
 50 |  * "./convex/_generated/server" or a customQuery.
 51 |  * @param mutation The mutation to use - use internalMutation or mutation from
 52 |  * "./convex/_generated/server" or a customMutation.
 53 |  * @returns An object with create, read, update, and delete functions.
 54 |  * You must export these functions at the top level of your file to use them.
 55 |  */
 56 | export function crud<
 57 |   Schema extends GenericSchema,
 58 |   TableName extends TableNamesInDataModel<
 59 |     DataModelFromSchemaDefinition<SchemaDefinition<Schema, any>>
 60 |   >,
 61 |   QueryVisibility extends FunctionVisibility = "internal",
 62 |   MutationVisibility extends FunctionVisibility = "internal",
 63 | >(
 64 |   schema: SchemaDefinition<Schema, any>,
 65 |   table: TableName,
 66 |   query: QueryBuilder<
 67 |     DataModelFromSchemaDefinition<SchemaDefinition<Schema, any>>,
 68 |     QueryVisibility
 69 |   > = internalQueryGeneric as any,
 70 |   mutation: MutationBuilder<
 71 |     DataModelFromSchemaDefinition<SchemaDefinition<Schema, any>>,
 72 |     MutationVisibility
 73 |   > = internalMutationGeneric as any,
 74 | ) {
 75 |   type DataModel = DataModelFromSchemaDefinition<SchemaDefinition<Schema, any>>;
 76 |   const validator = schema.tables[table]?.validator;
 77 |   if (!validator) {
 78 |     throw new Error(
 79 |       `Table ${table} not found in schema. Did you define it in defineSchema?`,
 80 |     );
 81 |   }
 82 |   if (validator.kind !== "object" && validator.kind !== "union") {
 83 |     throw new Error("Validator must be an object or union");
 84 |   }
 85 | 
 86 |   const makeSystemFieldsOptional = <V extends Validator<any, any, any>>(
 87 |     validator: V,
 88 |   ): V => {
 89 |     if (validator.kind === "object") {
 90 |       return v.object({
 91 |         ...validator.fields,
 92 |         ...partial(systemFields(table)),
 93 |       }) as any;
 94 |     } else if (validator.kind === "union") {
 95 |       return v.union(
 96 |         ...validator.members.map((value) => makeSystemFieldsOptional(value)),
 97 |       ) as any;
 98 |     } else {
 99 |       throw new Error("Validator must be an object or union");
100 |     }
101 |   };
102 | 
103 |   return {
104 |     create: mutation({
105 |       args: makeSystemFieldsOptional(validator),
106 |       handler: async (ctx, args) => {
107 |         if ("_id" in args) delete args._id;
108 |         if ("_creationTime" in args) delete args._creationTime;
109 |         const id = await ctx.db.insert(table, args);
110 |         return (await ctx.db.get(id))!;
111 |       },
112 |     }) as RegisteredMutation<
113 |       MutationVisibility,
114 |       WithoutSystemFields<DocumentByName<DataModel, TableName>>,
115 |       Promise<DocumentByName<DataModel, TableName>>
116 |     >,
117 |     read: query({
118 |       args: { id: v.id(table) },
119 |       handler: async (ctx, args) => {
120 |         return await ctx.db.get(args.id);
121 |       },
122 |     }) as RegisteredQuery<
123 |       QueryVisibility,
124 |       { id: GenericId<TableName> },
125 |       Promise<DocumentByName<DataModel, TableName> | null>
126 |     >,
127 |     paginate: query({
128 |       args: {
129 |         paginationOpts: paginationOptsValidator,
130 |       },
131 |       handler: async (ctx, args) => {
132 |         return ctx.db.query(table).paginate(args.paginationOpts);
133 |       },
134 |     }) as RegisteredQuery<
135 |       QueryVisibility,
136 |       { paginationOpts: Infer<typeof paginationOptsValidator> },
137 |       Promise<PaginationResult<DocumentByName<DataModel, TableName>>>
138 |     >,
139 |     update: mutation({
140 |       args: {
141 |         id: v.id(table),
142 |         // this could be partial(table.withSystemFields) but keeping
143 |         // the api less coupled to Table
144 |         patch: partial(
145 |           doc(schema, table) as VObject<any, any, any> | VUnion<any, any, any>,
146 |         ),
147 |       },
148 |       handler: async (ctx, args) => {
149 |         await ctx.db.patch(
150 |           args.id,
151 |           args.patch as Partial<DocumentByName<DataModel, TableName>>,
152 |         );
153 |       },
154 |     }) as RegisteredMutation<
155 |       MutationVisibility,
156 |       {
157 |         id: GenericId<TableName>;
158 |         patch: Partial<
159 |           WithoutSystemFields<DocumentByName<DataModel, TableName>>
160 |         >;
161 |       },
162 |       Promise<void>
163 |     >,
164 |     destroy: mutation({
165 |       args: { id: v.id(table) },
166 |       handler: async (ctx, args) => {
167 |         const old = await ctx.db.get(args.id);
168 |         if (old) {
169 |           await ctx.db.delete(args.id);
170 |         }
171 |         return old;
172 |       },
173 |     }) as RegisteredMutation<
174 |       MutationVisibility,
175 |       { id: GenericId<TableName> },
176 |       Promise<null | DocumentByName<DataModel, TableName>>
177 |     >,
178 |   };
179 | }
180 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/react/sessions.test.ts:
--------------------------------------------------------------------------------
  1 | import {
  2 |   expectTypeOf,
  3 |   test,
  4 |   vi,
  5 |   describe,
  6 |   it,
  7 |   expect,
  8 |   beforeEach,
  9 | } from "vitest";
 10 | import type { FunctionReference } from "convex/server";
 11 | import type { SessionArgsArray, SessionQueryArgsArray } from "./sessions.js";
 12 | import type { EmptyObject } from "../index.js";
 13 | import type { SessionId } from "../server/sessions.js";
 14 | import { ConvexReactSessionClient } from "./sessions.js";
 15 | 
 16 | test("noop", () => {});
 17 | 
 18 | expectTypeOf<
 19 |   SessionQueryArgsArray<
 20 |     FunctionReference<
 21 |       "query",
 22 |       "public",
 23 |       { arg: string; sessionId: SessionId | null },
 24 |       any
 25 |     >
 26 |   >
 27 | >().toEqualTypeOf<[{ arg: string } | "skip"]>();
 28 | 
 29 | expectTypeOf<
 30 |   SessionQueryArgsArray<
 31 |     FunctionReference<
 32 |       "query",
 33 |       "public",
 34 |       { arg?: string; sessionId: SessionId | null },
 35 |       any
 36 |     >
 37 |   >
 38 | >().toEqualTypeOf<[args?: { arg?: string } | "skip"]>();
 39 | 
 40 | expectTypeOf<
 41 |   SessionQueryArgsArray<
 42 |     FunctionReference<"query", "public", { sessionId: SessionId | null }, any>
 43 |   >
 44 | >().toEqualTypeOf<[args?: EmptyObject | "skip" | undefined]>();
 45 | 
 46 | expectTypeOf<
 47 |   SessionArgsArray<
 48 |     FunctionReference<
 49 |       "mutation",
 50 |       "public",
 51 |       { arg: string; sessionId: SessionId },
 52 |       any
 53 |     >
 54 |   >
 55 | >().toEqualTypeOf<[{ arg: string }]>();
 56 | 
 57 | expectTypeOf<
 58 |   SessionArgsArray<
 59 |     FunctionReference<
 60 |       "mutation",
 61 |       "public",
 62 |       { arg?: string; sessionId: SessionId },
 63 |       any
 64 |     >
 65 |   >
 66 | >().toEqualTypeOf<[args?: { arg?: string }]>();
 67 | 
 68 | expectTypeOf<
 69 |   SessionArgsArray<
 70 |     FunctionReference<"mutation", "public", { sessionId: SessionId }, any>
 71 |   >
 72 | >().toEqualTypeOf<[args?: EmptyObject | undefined]>();
 73 | 
 74 | expectTypeOf<
 75 |   SessionArgsArray<
 76 |     FunctionReference<
 77 |       "query",
 78 |       "public",
 79 |       { arg: string; sessionId: SessionId },
 80 |       any
 81 |     >
 82 |   >
 83 | >().toEqualTypeOf<[{ arg: string }]>();
 84 | 
 85 | expectTypeOf<
 86 |   SessionArgsArray<
 87 |     FunctionReference<"query", "public", { sessionId: SessionId }, any>
 88 |   >
 89 | >().toEqualTypeOf<[args?: EmptyObject | undefined]>();
 90 | 
 91 | describe("ConvexSessionClient", () => {
 92 |   let mockClient: { query: any; mutation: any; action: any };
 93 |   let sessionClient: ConvexReactSessionClient;
 94 |   const sessionId = "test-session-id" as SessionId;
 95 | 
 96 |   beforeEach(() => {
 97 |     mockClient = {
 98 |       query: vi.fn().mockResolvedValue("query-result"),
 99 |       mutation: vi.fn().mockResolvedValue("mutation-result"),
100 |       action: vi.fn().mockResolvedValue("action-result"),
101 |     };
102 |     sessionClient = new ConvexReactSessionClient("http://localhost:3000", {
103 |       sessionId,
104 |     });
105 |     sessionClient.query = mockClient.query;
106 |     sessionClient.mutation = mockClient.mutation;
107 |     sessionClient.action = mockClient.action;
108 |   });
109 | 
110 |   it("should inject sessionId into query args", async () => {
111 |     const query = {} as FunctionReference<
112 |       "query",
113 |       "public",
114 |       { arg: string; sessionId: SessionId | null },
115 |       any
116 |     >;
117 |     const args = { arg: " foo" };
118 | 
119 |     const result = await sessionClient.sessionQuery(query, args);
120 | 
121 |     expect(mockClient.query).toHaveBeenCalledWith(query, {
122 |       arg: " foo",
123 |       sessionId,
124 |     });
125 |     expect(result).toBe("query-result");
126 |   });
127 | 
128 |   it("should inject sessionId into mutation args", async () => {
129 |     const mutation = {} as FunctionReference<
130 |       "mutation",
131 |       "public",
132 |       { arg: string; sessionId: SessionId },
133 |       any
134 |     >;
135 |     const args = { arg: "foo" };
136 | 
137 |     const result = await sessionClient.sessionMutation(mutation, args);
138 | 
139 |     expect(mockClient.mutation).toHaveBeenCalledWith(
140 |       mutation,
141 |       { ...args, sessionId },
142 |       // options, e.g. for optimistic updates
143 |       undefined,
144 |     );
145 |     expect(result).toBe("mutation-result");
146 |   });
147 | 
148 |   it("should inject sessionId into action args", async () => {
149 |     const action = {} as FunctionReference<
150 |       "action",
151 |       "public",
152 |       { arg: string; sessionId: SessionId },
153 |       any
154 |     >;
155 |     const args = { arg: "foo" };
156 | 
157 |     const result = await sessionClient.sessionAction(action, args);
158 | 
159 |     expect(mockClient.action).toHaveBeenCalledWith(action, {
160 |       ...args,
161 |       sessionId,
162 |     });
163 |     expect(result).toBe("action-result");
164 |   });
165 | 
166 |   it("should allow changing the sessionId", async () => {
167 |     const newSessionId = "new-session-id" as SessionId;
168 |     const query = {} as FunctionReference<
169 |       "query",
170 |       "public",
171 |       { arg: string; sessionId: SessionId },
172 |       any
173 |     >;
174 | 
175 |     sessionClient.setSessionId(newSessionId);
176 | 
177 |     await sessionClient.sessionQuery(query, { arg: "foo" });
178 | 
179 |     expect(mockClient.query).toHaveBeenCalledWith(query, {
180 |       arg: "foo",
181 |       sessionId: newSessionId,
182 |     });
183 |     expect(sessionClient.getSessionId()).toBe(newSessionId);
184 |   });
185 | 
186 |   it("should allow omitting args if the only arg is sessionId", async () => {
187 |     const query = {} as FunctionReference<
188 |       "query",
189 |       "public",
190 |       { sessionId: SessionId },
191 |       any
192 |     >;
193 | 
194 |     expect(await sessionClient.sessionQuery(query)).toBe("query-result");
195 |     expect(mockClient.query).toHaveBeenCalledWith(query, {
196 |       sessionId,
197 |     });
198 | 
199 |     const mutation = {} as FunctionReference<
200 |       "mutation",
201 |       "public",
202 |       { sessionId: SessionId },
203 |       any
204 |     >;
205 | 
206 |     expect(await sessionClient.sessionMutation(mutation)).toBe(
207 |       "mutation-result",
208 |     );
209 |     expect(mockClient.mutation).toHaveBeenCalledWith(
210 |       mutation,
211 |       { sessionId },
212 |       undefined,
213 |     );
214 | 
215 |     const action = {} as FunctionReference<
216 |       "action",
217 |       "public",
218 |       { sessionId: SessionId },
219 |       any
220 |     >;
221 | 
222 |     expect(await sessionClient.sessionAction(action)).toBe("action-result");
223 |     expect(mockClient.action).toHaveBeenCalledWith(action, {
224 |       sessionId,
225 |     });
226 |   });
227 | });
228 | 


--------------------------------------------------------------------------------
/packages/convex-helpers/server/filter.ts:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * Defines a function `filter` that wraps a query, attaching a
  3 |  * JavaScript/TypeScript function that filters results just like
  4 |  * `db.query(...).filter(...)` but with more generality.
  5 |  *
  6 |  */
  7 | 
  8 | import type {
  9 |   DocumentByInfo,
 10 |   GenericTableInfo,
 11 |   PaginationOptions,
 12 |   QueryInitializer,
 13 |   PaginationResult,
 14 |   FilterBuilder,
 15 |   Expression,
 16 |   OrderedQuery,
 17 |   IndexRange,
 18 |   IndexRangeBuilder,
 19 |   Indexes,
 20 |   NamedIndex,
 21 |   NamedSearchIndex,
 22 |   Query,
 23 |   SearchFilterBuilder,
 24 |   SearchIndexes,
 25 | } from "convex/server";
 26 | 
 27 | import { SearchFilter } from "convex/server";
 28 | 
 29 | async function asyncFilter<T>(
 30 |   arr: T[],
 31 |   predicate: (d: T) => Promise<boolean> | boolean,
 32 | ): Promise<T[]> {
 33 |   const results = await Promise.all(arr.map(predicate));
 34 |   return arr.filter((_v, index) => results[index]);
 35 | }
 36 | 
 37 | class QueryWithFilter<T extends GenericTableInfo>
 38 |   implements QueryInitializer<T>
 39 | {
 40 |   // q actually is only guaranteed to implement OrderedQuery<T>,
 41 |   // but we forward all QueryInitializer methods to it and if they fail they fail.
 42 |   q: QueryInitializer<T>;
 43 |   p: Predicate<T>;
 44 |   iterator?: AsyncIterator<any>;
 45 | 
 46 |   constructor(q: OrderedQuery<T>, p: Predicate<T>) {
 47 |     this.q = q as QueryInitializer<T>;
 48 |     this.p = p;
 49 |   }
 50 |   filter(predicate: (q: FilterBuilder<T>) => Expression<boolean>): this {
 51 |     return new QueryWithFilter(this.q.filter(predicate), this.p) as this;
 52 |   }
 53 |   order(order: "asc" | "desc"): QueryWithFilter<T> {
 54 |     return new QueryWithFilter(this.q.order(order), this.p);
 55 |   }
 56 |   async paginate(
 57 |     paginationOpts: PaginationOptions,
 58 |   ): Promise<PaginationResult<DocumentByInfo<T>>> {
 59 |     const result = await this.q.paginate(paginationOpts);
 60 |     return { ...result, page: await asyncFilter(result.page, this.p) };
 61 |   }
 62 |   async collect(): Promise<DocumentByInfo<T>[]> {
 63 |     const results = await this.q.collect();
 64 |     return await asyncFilter(results, this.p);
 65 |   }
 66 |   async take(n: number): Promise<DocumentByInfo<T>[]> {
 67 |     const results: DocumentByInfo<T>[] = [];
 68 |     for await (const result of this) {
 69 |       results.push(result);
 70 |       if (results.length >= n) {
 71 |         break;
 72 |       }
 73 |     }
 74 |     return results;
 75 |   }
 76 |   async first(): Promise<DocumentByInfo<T> | null> {
 77 |     for await (const result of this) {
 78 |       return result;
 79 |     }
 80 |     return null;
 81 |   }
 82 |   async unique(): Promise<DocumentByInfo<T> | null> {
 83 |     let uniqueResult: DocumentByInfo<T> | null = null;
 84 |     for await (const result of this) {
 85 |       if (uniqueResult === null) {
 86 |         uniqueResult = result;
 87 |       } else {
 88 |         throw new Error(
 89 |           `unique() query returned more than one result:
 90 |   [${uniqueResult._id}, ${result._id}, ...]`,
 91 |         );
 92 |       }
 93 |     }
 94 |     return uniqueResult;
 95 |   }
 96 |   [Symbol.asyncIterator](): AsyncIterator<DocumentByInfo<T>, any, undefined> {
 97 |     this.iterator = this.q[Symbol.asyncIterator]();
 98 |     return this;
 99 |   }
100 |   async next(): Promise<IteratorResult<any>> {
101 |     for (;;) {
102 |       const { value, done } = await this.iterator!.next();
103 |       if (value && (await this.p(value))) {
104 |         return { value, done };
105 |       }
106 |       if (done) {
107 |         return { value: null, done: true };
108 |       }
109 |     }
110 |   }
111 |   return() {
112 |     return this.iterator!.return!();
113 |   }
114 | 
115 |   // Implement the remainder of QueryInitializer.
116 |   fullTableScan(): QueryWithFilter<T> {
117 |     return new QueryWithFilter(this.q.fullTableScan(), this.p);
118 |   }
119 |   withIndex<IndexName extends keyof Indexes<T>>(
120 |     indexName: IndexName,
121 |     indexRange?:
122 |       | ((
123 |           q: IndexRangeBuilder<DocumentByInfo<T>, NamedIndex<T, IndexName>, 0>,
124 |         ) => IndexRange)
125 |       | undefined,
126 |   ): Query<T> {
127 |     return new QueryWithFilter(this.q.withIndex(indexName, indexRange), this.p);
128 |   }
129 |   withSearchIndex<IndexName extends keyof SearchIndexes<T>>(
130 |     indexName: IndexName,
131 |     searchFilter: (
132 |       q: SearchFilterBuilder<DocumentByInfo<T>, NamedSearchIndex<T, IndexName>>,
133 |     ) => SearchFilter,
134 |   ): OrderedQuery<T> {
135 |     return new QueryWithFilter(
136 |       this.q.withSearchIndex(indexName, searchFilter),
137 |       this.p,
138 |     );
139 |   }
140 | }
141 | 
142 | export type Predicate<T extends GenericTableInfo> = (
143 |   doc: DocumentByInfo<T>,
144 | ) => Promise<boolean> | boolean;
145 | 
146 | type QueryTableInfo<Q> = Q extends OrderedQuery<infer T> ? T : never;
147 | 
148 | /**
149 |  * Applies a filter to a database query, just like `.filter((q) => ...)` but
150 |  * supporting arbitrary JavaScript/TypeScript.
151 |  * Performance is roughly the same as `.filter((q) => ...)`. If you want better
152 |  * performance, use an index to narrow down the results before filtering.
153 |  *
154 |  * Examples:
155 |  *
156 |  * // Full table scan, filtered to short messages.
157 |  * return await filter(
158 |  *  ctx.db.query("messages"),
159 |  *  async (message) => message.body.length < 10,
160 |  * ).collect();
161 |  *
162 |  * // Short messages by author, paginated.
163 |  * return await filter(
164 |  *  ctx.db.query("messages").withIndex("by_author", q=>q.eq("author", args.author)),
165 |  *  async (message) => message.body.length < 10,
166 |  * ).paginate(args.paginationOpts);
167 |  *
168 |  * // Same behavior as above: Short messages by author, paginated.
169 |  * // Note the filter can wrap any part of the query pipeline, and it is applied
170 |  * // at the end. This is how RowLevelSecurity works.
171 |  * const shortMessages = await filter(
172 |  *  ctx.db.query("messages"),
173 |  *  async (message) => message.body.length < 10,
174 |  * );
175 |  * return await shortMessages
176 |  *  .withIndex("by_author", q=>q.eq("author", args.author))
177 |  *  .paginate(args.paginationOpts);
178 |  *
179 |  * // Also works with `order()`, `take()`, `unique()`, and `first()`.
180 |  * return await filter(
181 |  *  ctx.db.query("messages").order("desc"),
182 |  *  async (message) => message.body.length < 10,
183 |  * ).first();
184 |  *
185 |  * @param query The query to filter.
186 |  * @param predicate Async function to run on each document before it is yielded
187 |  *  from the query pipeline.
188 |  * @returns A new query with the filter applied.
189 |  */
190 | export function filter<Q extends OrderedQuery<GenericTableInfo>>(
191 |   query: Q,
192 |   predicate: Predicate<QueryTableInfo<Q>>,
193 | ): Q {
194 |   return new QueryWithFilter<QueryTableInfo<Q>>(
195 |     query as unknown as OrderedQuery<QueryTableInfo<Q>>,
196 |     predicate,
197 |   ) as any as Q;
198 | }
199 | 


--------------------------------------------------------------------------------