convex-route-query 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ludicrous
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# convex-route-query
+
+Type-safe Convex query helpers for TanStack Router loaders and React Query Suspense.
+
+```ts
+import { createConvexRouteQuery } from "convex-route-query";
+import { api } from "../convex/_generated/api";
+
+const listExperiences = createConvexRouteQuery(
+  api.resume.queries.listExperiences,
+);
+
+export const Route = createFileRoute("/experience/")({
+  loader: async ({ context }) => {
+    await listExperiences.prefetchQuery(context.queryClient);
+  },
+  component: ExperiencePage,
+});
+
+function ExperiencePage() {
+  const { data } = listExperiences.useSuspenseQuery();
+
+  return <ExperienceList experiences={data} />;
+}
+```
+
+Queries with arguments infer their argument object from the Convex function reference.
+
+```ts
+const getPost = createConvexRouteQuery(api.blog.queries.getPost);
+
+export const Route = createFileRoute("/blog/$slug")({
+  loader: async ({ context, params }) => {
+    const post = await getPost.fetchQuery(context.queryClient, {
+      slug: params.slug,
+    });
+
+    if (!post) {
+      throw notFound();
+    }
+
+    return { post };
+  },
+  component: BlogPostPage,
+});
+
+function BlogPostPage() {
+  const { slug } = Route.useParams();
+  const { data: post } = getPost.useSuspenseQuery({ slug });
+
+  return <Post post={post} />;
+}
+```
+
+## Install
+
+```sh
+bun add convex-route-query
+```
+
+## API
+
+### `createConvexRouteQuery(query)`
+
+Returns an object with:
+
+- `options(...args)` - the underlying `convexQuery(...)` options.
+- `fetchQuery(queryClient, ...args)` - calls `queryClient.fetchQuery(...)`.
+- `prefetchQuery(queryClient, ...args)` - calls `queryClient.prefetchQuery(...)`.
+- `useSuspenseQuery(...args)` - calls React Query's `useSuspenseQuery(...)`.
+
+The loader helpers need a `QueryClient` because loaders run outside React context. The hook reads the `QueryClient` from React context.

package/dist/index.cjs

@@ -0,0 +1,24 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _convex_dev_react_query = require("@convex-dev/react-query");
+let _tanstack_react_query = require("@tanstack/react-query");
+//#region src/index.ts
+function createConvexRouteQuery(query) {
+	const createOptions = _convex_dev_react_query.convexQuery;
+	const options = (...args) => createOptions(query, ...args);
+	return {
+		options,
+		fetchQuery(queryClient, ...args) {
+			return queryClient.fetchQuery(options(...args));
+		},
+		prefetchQuery(queryClient, ...args) {
+			return queryClient.prefetchQuery(options(...args));
+		},
+		useSuspenseQuery(...args) {
+			return (0, _tanstack_react_query.useSuspenseQuery)(options(...args));
+		}
+	};
+}
+//#endregion
+exports.createConvexRouteQuery = createConvexRouteQuery;
+
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["convexQuery"],"sources":["../src/index.ts"],"sourcesContent":["import { convexQuery } from \"@convex-dev/react-query\";\nimport {\n  useSuspenseQuery as useTanStackSuspenseQuery,\n  type UseSuspenseQueryResult,\n} from \"@tanstack/react-query\";\nimport type {\n  FunctionArgs,\n  FunctionReference,\n  FunctionReturnType,\n  OptionalRestArgs,\n} from \"convex/server\";\n\nexport type ConvexRouteQueryOptions<Query extends FunctionReference<\"query\">> =\n  {\n    queryKey: [\"convexQuery\", Query, FunctionArgs<Query>];\n    staleTime: number;\n  };\n\nexport type ConvexRouteQuery<Query extends FunctionReference<\"query\">> = {\n  options: (...args: OptionalRestArgs<Query>) => ConvexRouteQueryOptions<Query>;\n  fetchQuery: (\n    queryClient: ConvexRouteQueryClient<Query>,\n    ...args: OptionalRestArgs<Query>\n  ) => Promise<FunctionReturnType<Query>>;\n  prefetchQuery: (\n    queryClient: ConvexRouteQueryClient<Query>,\n    ...args: OptionalRestArgs<Query>\n  ) => Promise<void>;\n  useSuspenseQuery: (\n    ...args: OptionalRestArgs<Query>\n  ) => UseSuspenseQueryResult<FunctionReturnType<Query>, Error>;\n};\n\nexport type ConvexRouteQueryClient<Query extends FunctionReference<\"query\">> = {\n  fetchQuery: (options: ConvexRouteQueryOptions<Query>) => Promise<unknown>;\n  prefetchQuery: (options: ConvexRouteQueryOptions<Query>) => Promise<void>;\n};\n\ntype CreateConvexQueryOptions<Query extends FunctionReference<\"query\">> = (\n  query: Query,\n  ...args: OptionalRestArgs<Query>\n) => ConvexRouteQueryOptions<Query>;\n\nexport function createConvexRouteQuery<\n  Query extends FunctionReference<\"query\">,\n>(query: Query): ConvexRouteQuery<Query> {\n  const createOptions =\n    convexQuery as unknown as CreateConvexQueryOptions<Query>;\n  const options = (...args: OptionalRestArgs<Query>) =>\n    createOptions(query, ...args);\n\n  return {\n    options,\n    fetchQuery(queryClient, ...args) {\n      return queryClient.fetchQuery(options(...args)) as Promise<\n        FunctionReturnType<Query>\n      >;\n    },\n    prefetchQuery(queryClient, ...args) {\n      return queryClient.prefetchQuery(options(...args));\n    },\n    useSuspenseQuery(...args) {\n      return useTanStackSuspenseQuery(options(...args));\n    },\n  };\n}\n"],"mappings":";;;;AA2CA,SAAgB,uBAEd,OAAuC;CACvC,MAAM,gBACJA,wBAAAA;CACF,MAAM,WAAW,GAAG,SAClB,cAAc,OAAO,GAAG,IAAI;CAE9B,OAAO;EACL;EACA,WAAW,aAAa,GAAG,MAAM;GAC/B,OAAO,YAAY,WAAW,QAAQ,GAAG,IAAI,CAAC;EAGhD;EACA,cAAc,aAAa,GAAG,MAAM;GAClC,OAAO,YAAY,cAAc,QAAQ,GAAG,IAAI,CAAC;EACnD;EACA,iBAAiB,GAAG,MAAM;GACxB,QAAA,GAAA,sBAAA,iBAAA,CAAgC,QAAQ,GAAG,IAAI,CAAC;EAClD;CACF;AACF"}

package/dist/index.d.cts

@@ -0,0 +1,22 @@
+import { UseSuspenseQueryResult } from "@tanstack/react-query";
+import { FunctionArgs, FunctionReference, FunctionReturnType, OptionalRestArgs } from "convex/server";
+
+//#region src/index.d.ts
+type ConvexRouteQueryOptions<Query extends FunctionReference<"query">> = {
+  queryKey: ["convexQuery", Query, FunctionArgs<Query>];
+  staleTime: number;
+};
+type ConvexRouteQuery<Query extends FunctionReference<"query">> = {
+  options: (...args: OptionalRestArgs<Query>) => ConvexRouteQueryOptions<Query>;
+  fetchQuery: (queryClient: ConvexRouteQueryClient<Query>, ...args: OptionalRestArgs<Query>) => Promise<FunctionReturnType<Query>>;
+  prefetchQuery: (queryClient: ConvexRouteQueryClient<Query>, ...args: OptionalRestArgs<Query>) => Promise<void>;
+  useSuspenseQuery: (...args: OptionalRestArgs<Query>) => UseSuspenseQueryResult<FunctionReturnType<Query>, Error>;
+};
+type ConvexRouteQueryClient<Query extends FunctionReference<"query">> = {
+  fetchQuery: (options: ConvexRouteQueryOptions<Query>) => Promise<unknown>;
+  prefetchQuery: (options: ConvexRouteQueryOptions<Query>) => Promise<void>;
+};
+declare function createConvexRouteQuery<Query extends FunctionReference<"query">>(query: Query): ConvexRouteQuery<Query>;
+//#endregion
+export { ConvexRouteQuery, ConvexRouteQueryClient, ConvexRouteQueryOptions, createConvexRouteQuery };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;;;KAYY,uBAAA,eAAsC,iBAAA;EAE9C,QAAA,kBAA0B,KAAA,EAAO,YAAA,CAAa,KAAA;EAC9C,SAAA;AAAA;AAAA,KAGQ,gBAAA,eAA+B,iBAAA;EACzC,OAAA,MAAa,IAAA,EAAM,gBAAA,CAAiB,KAAA,MAAW,uBAAA,CAAwB,KAAA;EACvE,UAAA,GACE,WAAA,EAAa,sBAAA,CAAuB,KAAA,MACjC,IAAA,EAAM,gBAAA,CAAiB,KAAA,MACvB,OAAA,CAAQ,kBAAA,CAAmB,KAAA;EAChC,aAAA,GACE,WAAA,EAAa,sBAAA,CAAuB,KAAA,MACjC,IAAA,EAAM,gBAAA,CAAiB,KAAA,MACvB,OAAA;EACL,gBAAA,MACK,IAAA,EAAM,gBAAA,CAAiB,KAAA,MACvB,sBAAA,CAAuB,kBAAA,CAAmB,KAAA,GAAQ,KAAA;AAAA;AAAA,KAG7C,sBAAA,eAAqC,iBAAA;EAC/C,UAAA,GAAa,OAAA,EAAS,uBAAA,CAAwB,KAAA,MAAW,OAAA;EACzD,aAAA,GAAgB,OAAA,EAAS,uBAAA,CAAwB,KAAA,MAAW,OAAA;AAAA;AAAA,iBAQ9C,sBAAA,eACA,iBAAA,WACd,KAAA,EAAO,KAAA,GAAQ,gBAAA,CAAiB,KAAA"}

package/dist/index.d.mts

@@ -0,0 +1,22 @@
+import { UseSuspenseQueryResult } from "@tanstack/react-query";
+import { FunctionArgs, FunctionReference, FunctionReturnType, OptionalRestArgs } from "convex/server";
+
+//#region src/index.d.ts
+type ConvexRouteQueryOptions<Query extends FunctionReference<"query">> = {
+  queryKey: ["convexQuery", Query, FunctionArgs<Query>];
+  staleTime: number;
+};
+type ConvexRouteQuery<Query extends FunctionReference<"query">> = {
+  options: (...args: OptionalRestArgs<Query>) => ConvexRouteQueryOptions<Query>;
+  fetchQuery: (queryClient: ConvexRouteQueryClient<Query>, ...args: OptionalRestArgs<Query>) => Promise<FunctionReturnType<Query>>;
+  prefetchQuery: (queryClient: ConvexRouteQueryClient<Query>, ...args: OptionalRestArgs<Query>) => Promise<void>;
+  useSuspenseQuery: (...args: OptionalRestArgs<Query>) => UseSuspenseQueryResult<FunctionReturnType<Query>, Error>;
+};
+type ConvexRouteQueryClient<Query extends FunctionReference<"query">> = {
+  fetchQuery: (options: ConvexRouteQueryOptions<Query>) => Promise<unknown>;
+  prefetchQuery: (options: ConvexRouteQueryOptions<Query>) => Promise<void>;
+};
+declare function createConvexRouteQuery<Query extends FunctionReference<"query">>(query: Query): ConvexRouteQuery<Query>;
+//#endregion
+export { ConvexRouteQuery, ConvexRouteQueryClient, ConvexRouteQueryOptions, createConvexRouteQuery };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;KAYY,uBAAA,eAAsC,iBAAA;EAE9C,QAAA,kBAA0B,KAAA,EAAO,YAAA,CAAa,KAAA;EAC9C,SAAA;AAAA;AAAA,KAGQ,gBAAA,eAA+B,iBAAA;EACzC,OAAA,MAAa,IAAA,EAAM,gBAAA,CAAiB,KAAA,MAAW,uBAAA,CAAwB,KAAA;EACvE,UAAA,GACE,WAAA,EAAa,sBAAA,CAAuB,KAAA,MACjC,IAAA,EAAM,gBAAA,CAAiB,KAAA,MACvB,OAAA,CAAQ,kBAAA,CAAmB,KAAA;EAChC,aAAA,GACE,WAAA,EAAa,sBAAA,CAAuB,KAAA,MACjC,IAAA,EAAM,gBAAA,CAAiB,KAAA,MACvB,OAAA;EACL,gBAAA,MACK,IAAA,EAAM,gBAAA,CAAiB,KAAA,MACvB,sBAAA,CAAuB,kBAAA,CAAmB,KAAA,GAAQ,KAAA;AAAA;AAAA,KAG7C,sBAAA,eAAqC,iBAAA;EAC/C,UAAA,GAAa,OAAA,EAAS,uBAAA,CAAwB,KAAA,MAAW,OAAA;EACzD,aAAA,GAAgB,OAAA,EAAS,uBAAA,CAAwB,KAAA,MAAW,OAAA;AAAA;AAAA,iBAQ9C,sBAAA,eACA,iBAAA,WACd,KAAA,EAAO,KAAA,GAAQ,gBAAA,CAAiB,KAAA"}

package/dist/index.mjs

@@ -0,0 +1,23 @@
+import { convexQuery } from "@convex-dev/react-query";
+import { useSuspenseQuery } from "@tanstack/react-query";
+//#region src/index.ts
+function createConvexRouteQuery(query) {
+	const createOptions = convexQuery;
+	const options = (...args) => createOptions(query, ...args);
+	return {
+		options,
+		fetchQuery(queryClient, ...args) {
+			return queryClient.fetchQuery(options(...args));
+		},
+		prefetchQuery(queryClient, ...args) {
+			return queryClient.prefetchQuery(options(...args));
+		},
+		useSuspenseQuery(...args) {
+			return useSuspenseQuery(options(...args));
+		}
+	};
+}
+//#endregion
+export { createConvexRouteQuery };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["useTanStackSuspenseQuery"],"sources":["../src/index.ts"],"sourcesContent":["import { convexQuery } from \"@convex-dev/react-query\";\nimport {\n  useSuspenseQuery as useTanStackSuspenseQuery,\n  type UseSuspenseQueryResult,\n} from \"@tanstack/react-query\";\nimport type {\n  FunctionArgs,\n  FunctionReference,\n  FunctionReturnType,\n  OptionalRestArgs,\n} from \"convex/server\";\n\nexport type ConvexRouteQueryOptions<Query extends FunctionReference<\"query\">> =\n  {\n    queryKey: [\"convexQuery\", Query, FunctionArgs<Query>];\n    staleTime: number;\n  };\n\nexport type ConvexRouteQuery<Query extends FunctionReference<\"query\">> = {\n  options: (...args: OptionalRestArgs<Query>) => ConvexRouteQueryOptions<Query>;\n  fetchQuery: (\n    queryClient: ConvexRouteQueryClient<Query>,\n    ...args: OptionalRestArgs<Query>\n  ) => Promise<FunctionReturnType<Query>>;\n  prefetchQuery: (\n    queryClient: ConvexRouteQueryClient<Query>,\n    ...args: OptionalRestArgs<Query>\n  ) => Promise<void>;\n  useSuspenseQuery: (\n    ...args: OptionalRestArgs<Query>\n  ) => UseSuspenseQueryResult<FunctionReturnType<Query>, Error>;\n};\n\nexport type ConvexRouteQueryClient<Query extends FunctionReference<\"query\">> = {\n  fetchQuery: (options: ConvexRouteQueryOptions<Query>) => Promise<unknown>;\n  prefetchQuery: (options: ConvexRouteQueryOptions<Query>) => Promise<void>;\n};\n\ntype CreateConvexQueryOptions<Query extends FunctionReference<\"query\">> = (\n  query: Query,\n  ...args: OptionalRestArgs<Query>\n) => ConvexRouteQueryOptions<Query>;\n\nexport function createConvexRouteQuery<\n  Query extends FunctionReference<\"query\">,\n>(query: Query): ConvexRouteQuery<Query> {\n  const createOptions =\n    convexQuery as unknown as CreateConvexQueryOptions<Query>;\n  const options = (...args: OptionalRestArgs<Query>) =>\n    createOptions(query, ...args);\n\n  return {\n    options,\n    fetchQuery(queryClient, ...args) {\n      return queryClient.fetchQuery(options(...args)) as Promise<\n        FunctionReturnType<Query>\n      >;\n    },\n    prefetchQuery(queryClient, ...args) {\n      return queryClient.prefetchQuery(options(...args));\n    },\n    useSuspenseQuery(...args) {\n      return useTanStackSuspenseQuery(options(...args));\n    },\n  };\n}\n"],"mappings":";;;AA2CA,SAAgB,uBAEd,OAAuC;CACvC,MAAM,gBACJ;CACF,MAAM,WAAW,GAAG,SAClB,cAAc,OAAO,GAAG,IAAI;CAE9B,OAAO;EACL;EACA,WAAW,aAAa,GAAG,MAAM;GAC/B,OAAO,YAAY,WAAW,QAAQ,GAAG,IAAI,CAAC;EAGhD;EACA,cAAc,aAAa,GAAG,MAAM;GAClC,OAAO,YAAY,cAAc,QAAQ,GAAG,IAAI,CAAC;EACnD;EACA,iBAAiB,GAAG,MAAM;GACxB,OAAOA,iBAAyB,QAAQ,GAAG,IAAI,CAAC;EAClD;CACF;AACF"}

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "convex-route-query",
+  "version": "0.0.1",
+  "description": "Type-safe Convex query helpers for TanStack Router loaders and React Query Suspense.",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.mts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "concurrently --raw --names tsdown \"bun run build:tsdown\"",
+    "build:tsdown": "tsdown",
+    "ci": "bun run ci:test && bun run build && bun run lint:pkg",
+    "ci:test": "concurrently --raw --names runtime,types,xo \"bun run ci:test:runtime\" \"bun run ci:test:types\" \"bun run ci:test:xo\"",
+    "ci:test:runtime": "vitest run",
+    "ci:test:types": "tsc --noEmit",
+    "ci:test:xo": "xo",
+    "dev": "concurrently --raw --names tsdown \"bun run dev:tsdown\"",
+    "dev:tsdown": "tsdown --watch",
+    "lint:pkg": "concurrently --raw --names publint,attw \"bun run lint:pkg:publint\" \"bun run lint:pkg:attw\"",
+    "lint:pkg:attw": "attw --pack .",
+    "lint:pkg:publint": "publint",
+    "prepublishOnly": "bun run ci",
+    "release": "bun run build && changeset publish",
+    "test": "concurrently --raw --names runtime,types,xo \"bun run test:runtime\" \"bun run test:types\" \"bun run test:xo\"",
+    "test:runtime": "vitest run",
+    "test:types": "tsc --noEmit",
+    "test:xo": "xo",
+    "typecheck": "bun run test:types",
+    "version": "changeset version && bun install --lockfile-only"
+  },
+  "keywords": [
+    "convex",
+    "tanstack",
+    "tanstack-router",
+    "react-query",
+    "suspense",
+    "typescript"
+  ],
+  "author": "ludicrous",
+  "license": "MIT",
+  "homepage": "https://github.com/ludicroushq/convex-route-query#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ludicroushq/convex-route-query.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ludicroushq/convex-route-query/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "packageManager": "bun@1.3.14",
+  "peerDependencies": {
+    "@convex-dev/react-query": ">=0.1.0",
+    "@tanstack/react-query": ">=5.0.0",
+    "convex": ">=1.0.0",
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.3",
+    "@changesets/cli": "^2.31.0",
+    "@convex-dev/react-query": "^0.1.0",
+    "@tanstack/react-query": "^5.101.0",
+    "@types/react": "^19.2.7",
+    "concurrently": "^10.0.3",
+    "convex": "^1.41.0",
+    "expect-type": "^1.3.0",
+    "lefthook": "^2.1.9",
+    "prettier": "^3.8.4",
+    "publint": "^0.3.21",
+    "react": "^19.2.7",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8",
+    "xo": "^2.0.2"
+  }
+}