@questpie/tanstack-query 1.1.1 → 3.0.0

package/README.md

@@ -1,12 +1,15 @@
 # @questpie/tanstack-query
 
-Type-safe TanStack React Query integration for QUESTPIE.
+Type-safe TanStack Query option builders for QUESTPIE — collections, globals, app routes, and realtime streaming.
 
 ## Features
 
-- **Query Options Factory** - Pre-built query/mutation options using `queryOptions()` and `mutationOptions()` from TanStack Query
-- **SSR Ready** - Prefetch data on server, hydrate on client
-- **Type-Safe** - Full TypeScript inference from your CMS schema
+- **Query Options Factory** — Pre-built `queryOptions()` and `mutationOptions()` for all CRUD operations
+- **Route Query Options** — Typed `query()` / `mutation()` builders for app routes with nested path support
+- **Realtime Streaming** — `streamedQuery`-based options for SSE live updates on collections and globals
+- **Batch Operations** — `updateMany` and `deleteMany` mutation builders
+- **SSR Ready** — Prefetch data on the server, hydrate on the client
+- **Full Type Inference** — Types flow from your app schema through to query results
 
 ## Installation
 
@@ -18,285 +21,223 @@ bun add @questpie/tanstack-query questpie @tanstack/react-query
 
 ### 1. Create Query Options
 
-```typescript
-// src/lib/queries.ts
+```ts
 import { createClient } from "questpie/client";
 import { createQuestpieQueryOptions } from "@questpie/tanstack-query";
-import type { AppCMS } from "@/cms";
+import type { AppConfig } from "#questpie";
 
-const cmsClient = createClient<AppCMS>({
-  baseURL: "http://localhost:3000",
-  basePath: "/api/cms",
+const appClient = createClient<AppConfig>({
+	baseURL: "http://localhost:3000",
+	basePath: "/api",
 });
 
-export const q = createQuestpieQueryOptions(cmsClient, {
-  keyPrefix: ["cms"], // Optional: prefix for all query keys
-});
+export const appQueries = createQuestpieQueryOptions(appClient);
 ```
 
 ### 2. Use in Components
 
-```typescript
-import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"
-import { q } from "@/lib/queries"
+```tsx
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { appQueries } from "@/lib/queries";
 
 function PostsList() {
-  // Queries
-  const { data: posts } = useQuery(q.collections.posts.find({ limit: 10 }))
-
-  // Mutations
-  const queryClient = useQueryClient()
-
-  const createPost = useMutation({
-    ...q.collections.posts.create(),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ["cms", "collections", "posts"] })
-    },
-  })
-
-  return (
-    <div>
-      {posts?.docs.map((post) => (
-        <div key={post.id}>{post.title}</div>
-      ))}
-      <button onClick={() => createPost.mutate({ title: "New Post" })}>
-        Create Post
-      </button>
-    </div>
-  )
+	const { data } = useQuery(appQueries.collections.posts.find({ limit: 10 }));
+
+	const queryClient = useQueryClient();
+	const createPost = useMutation({
+		...appQueries.collections.posts.create(),
+		onSuccess: () => {
+			queryClient.invalidateQueries({
+				queryKey: appQueries.collections.posts.key(),
+			});
+		},
+	});
+
+	return (
+		<div>
+			{data?.docs.map((post) => (
+				<div key={post.id}>{post.title}</div>
+			))}
+			<button onClick={() => createPost.mutate({ title: "New Post" })}>
+				Create
+			</button>
+		</div>
+	);
 }
 ```
 
-## Query Options API
-
-### Collections
+## Collections
 
-```typescript
-// Find many
-q.collections.posts.find({
-  where: { published: { eq: true } },
-  orderBy: { createdAt: "desc" },
-  limit: 10,
-  offset: 0,
-  with: { author: true },
+```ts
+// Find many (paginated)
+appQueries.collections.posts.find({
+	where: { published: { eq: true } },
+	orderBy: { createdAt: "desc" },
+	limit: 10,
+	offset: 0,
+	with: { author: true },
 });
 
 // Find one
-q.collections.posts.findOne({
-  where: { id: "post-id" },
-  with: { author: true, comments: true },
+appQueries.collections.posts.findOne({
+	where: { id: "post-id" },
+	with: { author: true },
 });
 
-// Create
-q.collections.posts.create();
-// Usage: mutation.mutate({ title: "...", content: "..." })
+// Count
+appQueries.collections.posts.count({
+	where: { published: { eq: true } },
+});
+
+// Create (mutation)
+appQueries.collections.posts.create();
+
+// Update (mutation)
+appQueries.collections.posts.update();
 
-// Update
-q.collections.posts.update();
-// Usage: mutation.mutate({ id: "...", data: { title: "..." } })
+// Delete (mutation)
+appQueries.collections.posts.delete();
 
-// Delete
-q.collections.posts.delete();
-// Usage: mutation.mutate({ id: "..." })
+// Update many (mutation)
+appQueries.collections.posts.updateMany();
 
-// Restore (soft delete)
-q.collections.posts.restore();
-// Usage: mutation.mutate({ id: "..." })
+// Delete many (mutation)
+appQueries.collections.posts.deleteMany();
+
+// Restore soft-deleted (mutation)
+appQueries.collections.posts.restore();
+
+// Query key for invalidation
+appQueries.collections.posts.key();
 ```
 
-### Globals
+## Globals
 
-```typescript
-// Get
-q.globals.siteSettings.get();
+```ts
+// Get global value
+appQueries.globals.siteSettings.get();
 
-// Update
-q.globals.siteSettings.update();
-// Usage: mutation.mutate({ data: { siteName: "..." } })
+// Update global (mutation)
+appQueries.globals.siteSettings.update();
+
+// Query key
+appQueries.globals.siteSettings.key();
 ```
 
-### Custom Queries
+## Routes
+
+Full type-safe query/mutation options for app routes:
 
-```typescript
-const searchQuery = q.custom.query({
-  key: ["search", query],
-  queryFn: () => fetch(`/api/search?q=${query}`).then((r) => r.json()),
+```ts
+// Query options from route
+const { data } = useQuery(
+	appQueries.routes.dashboard.getStats.query({ period: "week" }),
+);
+
+// Mutation options from route
+const publish = useMutation(appQueries.routes.posts.publish.mutation());
+publish.mutate({ id: "post_123" });
+
+// Query key for invalidation/prefetch
+queryClient.invalidateQueries({
+	queryKey: appQueries.routes.dashboard.getStats.key({ period: "week" }),
 });
+```
+
+## Realtime Streaming
+
+Collection queries support SSE-based live updates via `streamedQuery`:
+
+```ts
+// Enable realtime on a query
+const { data } = useQuery(
+	appQueries.collections.posts.find({ limit: 10 }, { realtime: true }),
+);
+```
+
+Topic helpers for manual subscription:
 
-useQuery(searchQuery);
+```ts
+import {
+	buildCollectionTopic,
+	buildGlobalTopic,
+} from "@questpie/tanstack-query";
+
+const postsTopic = buildCollectionTopic("posts");
+const settingsTopic = buildGlobalTopic("siteSettings");
 ```
 
 ## SSR Prefetching
 
 ### TanStack Start
 
-```typescript
-// src/routes/posts.tsx
-import { createFileRoute } from "@tanstack/react-router"
-import { useSuspenseQuery } from "@tanstack/react-query"
-import { q } from "@/lib/queries"
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { useSuspenseQuery } from "@tanstack/react-query";
+import { appQueries } from "@/lib/queries";
 
 export const Route = createFileRoute("/posts")({
-  loader: async ({ context }) => {
-    await context.queryClient.ensureQueryData(
-      q.collections.posts.find({ limit: 10 })
-    )
-  },
-  component: PostsPage,
-})
+	loader: async ({ context }) => {
+		await context.queryClient.ensureQueryData(
+			appQueries.collections.posts.find({ limit: 10 }),
+		);
+	},
+	component: PostsPage,
+});
 
 function PostsPage() {
-  const { data: posts } = useSuspenseQuery(
-    q.collections.posts.find({ limit: 10 })
-  )
-
-  return (
-    <ul>
-      {posts.docs.map((post) => (
-        <li key={post.id}>{post.title}</li>
-      ))}
-    </ul>
-  )
+	const { data } = useSuspenseQuery(
+		appQueries.collections.posts.find({ limit: 10 }),
+	);
+	return (
+		<ul>
+			{data.docs.map((post) => (
+				<li key={post.id}>{post.title}</li>
+			))}
+		</ul>
+	);
 }
 ```
 
 ### Next.js
 
-```typescript
-// app/posts/page.tsx
-import { HydrationBoundary, dehydrate } from "@tanstack/react-query"
-import { getQueryClient } from "@/lib/query-client"
-import { q } from "@/lib/queries"
-import { PostsList } from "./posts-list"
+```tsx
+import { HydrationBoundary, dehydrate } from "@tanstack/react-query";
+import { getQueryClient } from "@/lib/query-client";
+import { appQueries } from "@/lib/queries";
 
 export default async function PostsPage() {
-  const queryClient = getQueryClient()
-
-  await queryClient.prefetchQuery(
-    q.collections.posts.find({ limit: 10 })
-  )
-
-  return (
-    <HydrationBoundary state={dehydrate(queryClient)}>
-      <PostsList />
-    </HydrationBoundary>
-  )
-}
-```
-
-## Optimistic Updates
-
-```typescript
-const queryClient = useQueryClient();
-
-const updatePost = useMutation({
-  ...q.collections.posts.update(),
-  onMutate: async ({ id, data }) => {
-    await queryClient.cancelQueries({
-      queryKey: ["cms", "collections", "posts"],
-    });
-
-    const previousPosts = queryClient.getQueryData([
-      "cms",
-      "collections",
-      "posts",
-    ]);
-
-    queryClient.setQueryData(["cms", "collections", "posts"], (old) => ({
-      ...old,
-      docs: old.docs.map((post) =>
-        post.id === id ? { ...post, ...data } : post,
-      ),
-    }));
-
-    return { previousPosts };
-  },
-  onError: (err, variables, context) => {
-    queryClient.setQueryData(
-      ["cms", "collections", "posts"],
-      context?.previousPosts,
-    );
-  },
-  onSettled: () => {
-    queryClient.invalidateQueries({
-      queryKey: ["cms", "collections", "posts"],
-    });
-  },
-});
-```
-
-## Infinite Queries
-
-```typescript
-import { useInfiniteQuery } from "@tanstack/react-query"
-import { cmsClient } from "@/lib/cms-client"
-
-function InfinitePosts() {
-  const { data, fetchNextPage, hasNextPage } = useInfiniteQuery({
-    queryKey: ["cms", "collections", "posts", "infinite"],
-    queryFn: ({ pageParam = 0 }) =>
-      cmsClient.collections.posts.find({
-        limit: 10,
-        offset: pageParam,
-      }),
-    getNextPageParam: (lastPage, allPages) => {
-      const totalFetched = allPages.flatMap((p) => p.docs).length
-      return lastPage.docs.length === 10 ? totalFetched : undefined
-    },
-    initialPageParam: 0,
-  })
-
-  return (
-    <div>
-      {data?.pages.flatMap((page) =>
-        page.docs.map((post) => <div key={post.id}>{post.title}</div>)
-      )}
-      {hasNextPage && (
-        <button onClick={() => fetchNextPage()}>Load More</button>
-      )}
-    </div>
-  )
+	const queryClient = getQueryClient();
+	await queryClient.prefetchQuery(
+		appQueries.collections.posts.find({ limit: 10 }),
+	);
+	return (
+		<HydrationBoundary state={dehydrate(queryClient)}>
+			<PostsList />
+		</HydrationBoundary>
+	);
 }
 ```
 
 ## Query Key Structure
 
-All query keys follow this structure:
-
-```typescript
+```ts
 // Collections
-[...keyPrefix, "collections", collectionName, "find", options]
-[...keyPrefix, "collections", collectionName, "findOne", options]
+["collections", collectionName, "find", options]
+["collections", collectionName, "findOne", options]
+["collections", collectionName, "count", options]
 
 // Globals
-[...keyPrefix, "globals", globalName, "get", options]
-
-// Custom
-[...keyPrefix, ...customKey]
-```
-
-## TypeScript
-
-Full type inference from your CMS schema:
-
-```typescript
-import type { CollectionSelect } from "questpie";
-import type { AppCMS } from "@/cms";
-
-// Collection item type
-type Post = CollectionSelect<AppCMS["config"]["collections"]["posts"]>;
+["globals", globalName, "get"]
 
-// Query result types are automatically inferred
-const { data } = useQuery(q.collections.posts.find({ limit: 10 }));
-//    ^? { docs: Post[], totalDocs: number, ... }
+// Routes
+["routes", ...segments, "query", input]
+["routes", ...segments, "mutation"]
 ```
 
-## Related Packages
+## Documentation
 
-- [`questpie`](../questpie) - Core CMS engine
-- [`@questpie/hono`](../hono) - Hono adapter
-- [`@questpie/elysia`](../elysia) - Elysia adapter
-- [`@questpie/next`](../next) - Next.js adapter
+Full documentation: [https://questpie.com/docs/client/tanstack-query](https://questpie.com/docs/client/tanstack-query)
 
 ## License
 

package/dist/index.d.mts

@@ -1,6 +1,5 @@
 import { DefaultError, QueryKey, UseMutationOptions, UseQueryOptions } from "@tanstack/react-query";
-import { Questpie } from "questpie";
-import { QuestpieClient } from "questpie/client";
+import { QuestpieApp, QuestpieClient, RealtimeAPI, TopicConfig, buildCollectionTopic, buildGlobalTopic } from "questpie/client";
 
 //#region src/index.d.ts
 type QuestpieQueryErrorMap = (error: unknown) => unknown;
@@ -8,56 +7,93 @@ type QuestpieQueryOptionsConfig = {
   keyPrefix?: QueryKey;
   errorMap?: QuestpieQueryErrorMap;
   locale?: string;
+  stage?: string;
 };
 type AnyAsyncFn = (...args: any[]) => Promise<any>;
 type QueryData<TFn extends AnyAsyncFn> = Awaited<ReturnType<TFn>>;
 type FirstArg<TFn extends AnyAsyncFn> = Parameters<TFn> extends [infer TFirst, ...any[]] ? TFirst : never;
 type HasArgs<TFn extends AnyAsyncFn> = Parameters<TFn> extends [] ? false : true;
 type QueryBuilder<TFn extends AnyAsyncFn> = HasArgs<TFn> extends false ? () => UseQueryOptions<QueryData<TFn>> : undefined extends FirstArg<TFn> ? (options?: FirstArg<TFn>) => UseQueryOptions<QueryData<TFn>> : (options: FirstArg<TFn>) => UseQueryOptions<QueryData<TFn>>;
+type KeyBuilder<TFn extends AnyAsyncFn> = HasArgs<TFn> extends false ? () => QueryKey : undefined extends FirstArg<TFn> ? (options?: FirstArg<TFn>) => QueryKey : (options: FirstArg<TFn>) => QueryKey;
+type MutationVariables<TFn extends AnyAsyncFn> = HasArgs<TFn> extends false ? void : undefined extends FirstArg<TFn> ? FirstArg<TFn> | void : FirstArg<TFn>;
 type MutationBuilder<TVariables, TData> = () => UseMutationOptions<TData, DefaultError, TVariables>;
 /** Extract collection keys from QuestpieClient */
-type CollectionKeys<T extends Questpie<any>> = Extract<keyof QuestpieClient<T>["collections"], string>;
+type CollectionKeys<TApp extends QuestpieApp> = Extract<keyof QuestpieClient<TApp>["collections"], string>;
 /** Extract global keys from QuestpieClient */
-type GlobalKeys<T extends Questpie<any>> = Extract<keyof QuestpieClient<T>["globals"], string>;
-type CollectionFind<T extends Questpie<any>, K$1 extends CollectionKeys<T>> = QuestpieClient<T>["collections"][K$1]["find"];
-type CollectionCount<T extends Questpie<any>, K$1 extends CollectionKeys<T>> = QuestpieClient<T>["collections"][K$1]["count"];
-type CollectionFindOne<T extends Questpie<any>, K$1 extends CollectionKeys<T>> = QuestpieClient<T>["collections"][K$1]["findOne"];
-type CollectionCreate<T extends Questpie<any>, K$1 extends CollectionKeys<T>> = QuestpieClient<T>["collections"][K$1]["create"];
-type CollectionUpdate<T extends Questpie<any>, K$1 extends CollectionKeys<T>> = QuestpieClient<T>["collections"][K$1]["update"];
-type CollectionDelete<T extends Questpie<any>, K$1 extends CollectionKeys<T>> = QuestpieClient<T>["collections"][K$1]["delete"];
-type CollectionRestore<T extends Questpie<any>, K$1 extends CollectionKeys<T>> = QuestpieClient<T>["collections"][K$1]["restore"];
-type GlobalGet<T extends Questpie<any>, K$1 extends GlobalKeys<T>> = QuestpieClient<T>["globals"][K$1] extends {
+type GlobalKeys<TApp extends QuestpieApp> = Extract<keyof QuestpieClient<TApp>["globals"], string>;
+type CollectionFind<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = QuestpieClient<TApp>["collections"][K$1]["find"];
+type CollectionCount<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = QuestpieClient<TApp>["collections"][K$1]["count"];
+type CollectionFindOne<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = QuestpieClient<TApp>["collections"][K$1]["findOne"];
+type CollectionCreate<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = QuestpieClient<TApp>["collections"][K$1]["create"];
+type CollectionUpdate<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = QuestpieClient<TApp>["collections"][K$1]["update"];
+type CollectionDelete<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = QuestpieClient<TApp>["collections"][K$1]["delete"];
+type CollectionRestore<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = QuestpieClient<TApp>["collections"][K$1]["restore"];
+type CollectionFindVersions<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = QuestpieClient<TApp>["collections"][K$1]["findVersions"];
+type CollectionRevertToVersion<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = QuestpieClient<TApp>["collections"][K$1]["revertToVersion"];
+type CollectionTransitionStage<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = QuestpieClient<TApp>["collections"][K$1]["transitionStage"];
+type GlobalGet<TApp extends QuestpieApp, K$1 extends GlobalKeys<TApp>> = QuestpieClient<TApp>["globals"][K$1] extends {
   get: infer TGet;
 } ? TGet extends AnyAsyncFn ? TGet : never : never;
-type GlobalUpdate<T extends Questpie<any>, K$1 extends GlobalKeys<T>> = QuestpieClient<T>["globals"][K$1] extends {
+type GlobalUpdate<TApp extends QuestpieApp, K$1 extends GlobalKeys<TApp>> = QuestpieClient<TApp>["globals"][K$1] extends {
   update: infer TUpdate;
 } ? TUpdate extends AnyAsyncFn ? TUpdate : never : never;
-type CollectionQueryOptionsAPI<T extends Questpie<any>, K$1 extends CollectionKeys<T>> = {
-  find: QueryBuilder<CollectionFind<T, K$1>>;
-  count: QueryBuilder<CollectionCount<T, K$1>>;
-  findOne: QueryBuilder<CollectionFindOne<T, K$1>>;
-  create: MutationBuilder<FirstArg<CollectionCreate<T, K$1>>, QueryData<CollectionCreate<T, K$1>>>;
-  update: MutationBuilder<{
-    id: Parameters<CollectionUpdate<T, K$1>>[0];
-    data: Parameters<CollectionUpdate<T, K$1>>[1];
-  }, QueryData<CollectionUpdate<T, K$1>>>;
-  delete: MutationBuilder<{
-    id: Parameters<CollectionDelete<T, K$1>>[0];
-  }, QueryData<CollectionDelete<T, K$1>>>;
-  restore: MutationBuilder<{
-    id: Parameters<CollectionRestore<T, K$1>>[0];
-  }, QueryData<CollectionRestore<T, K$1>>>;
+type GlobalFindVersions<TApp extends QuestpieApp, K$1 extends GlobalKeys<TApp>> = QuestpieClient<TApp>["globals"][K$1] extends {
+  findVersions: infer TFindVersions;
+} ? TFindVersions extends AnyAsyncFn ? TFindVersions : never : never;
+type GlobalRevertToVersion<TApp extends QuestpieApp, K$1 extends GlobalKeys<TApp>> = QuestpieClient<TApp>["globals"][K$1] extends {
+  revertToVersion: infer TRevert;
+} ? TRevert extends AnyAsyncFn ? TRevert : never : never;
+type GlobalTransitionStage<TApp extends QuestpieApp, K$1 extends GlobalKeys<TApp>> = QuestpieClient<TApp>["globals"][K$1] extends {
+  transitionStage: infer TTransition;
+} ? TTransition extends AnyAsyncFn ? TTransition : never : never;
+type RouteLeafQueryOptionsAPI<TFn extends AnyAsyncFn> = {
+  query: QueryBuilder<TFn>;
+  mutation: MutationBuilder<MutationVariables<TFn>, QueryData<TFn>>;
+  key: KeyBuilder<TFn>;
+};
+type RoutesQueryOptionsAPI<TNode> = TNode extends AnyAsyncFn ? RouteLeafQueryOptionsAPI<TNode> : TNode extends Record<string, any> ? { [K in keyof TNode]: RoutesQueryOptionsAPI<TNode[K]> } : never;
+type CollectionQueryOptionsAPI<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = {
+  find: QueryBuilder<CollectionFind<TApp, K$1>>;
+  count: QueryBuilder<CollectionCount<TApp, K$1>>;
+  findOne: QueryBuilder<CollectionFindOne<TApp, K$1>>;
+  create: MutationBuilder<FirstArg<CollectionCreate<TApp, K$1>>, QueryData<CollectionCreate<TApp, K$1>>>;
+  update: MutationBuilder<FirstArg<CollectionUpdate<TApp, K$1>>, QueryData<CollectionUpdate<TApp, K$1>>>;
+  delete: MutationBuilder<FirstArg<CollectionDelete<TApp, K$1>>, QueryData<CollectionDelete<TApp, K$1>>>;
+  restore: MutationBuilder<FirstArg<CollectionRestore<TApp, K$1>>, QueryData<CollectionRestore<TApp, K$1>>>;
+  findVersions: QueryBuilder<CollectionFindVersions<TApp, K$1>>;
+  revertToVersion: MutationBuilder<FirstArg<CollectionRevertToVersion<TApp, K$1>>, QueryData<CollectionRevertToVersion<TApp, K$1>>>;
+  transitionStage: MutationBuilder<FirstArg<CollectionTransitionStage<TApp, K$1>>, QueryData<CollectionTransitionStage<TApp, K$1>>>;
+  updateMany: MutationBuilder<{
+    where: any;
+    data: any;
+  }, QueryData<CollectionUpdate<TApp, K$1>>>;
+  deleteMany: MutationBuilder<{
+    where: any;
+  }, {
+    success: boolean;
+    count: number;
+  }>;
 };
-type GlobalQueryOptionsAPI<T extends Questpie<any>, K$1 extends GlobalKeys<T>> = {
-  get: QueryBuilder<GlobalGet<T, K$1>>;
+type GlobalQueryOptionsAPI<TApp extends QuestpieApp, K$1 extends GlobalKeys<TApp>> = {
+  get: QueryBuilder<GlobalGet<TApp, K$1>>;
   update: MutationBuilder<{
-    data: Parameters<GlobalUpdate<T, K$1>>[0];
-    options?: Parameters<GlobalUpdate<T, K$1>>[1];
-  }, QueryData<GlobalUpdate<T, K$1>>>;
+    data: Parameters<GlobalUpdate<TApp, K$1>>[0];
+    options?: Parameters<GlobalUpdate<TApp, K$1>>[1];
+  }, QueryData<GlobalUpdate<TApp, K$1>>>;
+  findVersions: QueryBuilder<GlobalFindVersions<TApp, K$1>>;
+  revertToVersion: MutationBuilder<{
+    params: Parameters<GlobalRevertToVersion<TApp, K$1>>[0];
+    options?: Parameters<GlobalRevertToVersion<TApp, K$1>>[1];
+  }, QueryData<GlobalRevertToVersion<TApp, K$1>>>;
+  transitionStage: MutationBuilder<{
+    params: Parameters<GlobalTransitionStage<TApp, K$1>>[0];
+    options?: Parameters<GlobalTransitionStage<TApp, K$1>>[1];
+  }, QueryData<GlobalTransitionStage<TApp, K$1>>>;
 };
-type QuestpieQueryOptionsProxy<T extends Questpie<any>> = {
-  collections: { [K in CollectionKeys<T>]: CollectionQueryOptionsAPI<T, K> };
-  globals: { [K in GlobalKeys<T>]: GlobalQueryOptionsAPI<T, K> };
+type QuestpieQueryOptionsProxy<TApp extends QuestpieApp = QuestpieApp> = {
+  collections: { [K in CollectionKeys<TApp>]: CollectionQueryOptionsAPI<TApp, K> };
+  globals: { [K in GlobalKeys<TApp>]: GlobalQueryOptionsAPI<TApp, K> };
+  routes: RoutesQueryOptionsAPI<QuestpieClient<TApp>["routes"]>;
   custom: {
     query: <TData>(config: {
       key: QueryKey;
@@ -77,17 +113,21 @@ type QuestpieQueryOptionsProxy<T extends Questpie<any>> = {
  * ```ts
  * import { createQuestpieQueryOptions } from "@questpie/tanstack-query"
  * import { createClient } from "questpie/client"
+ * import type { App, AppRpc } from "@/app"
  *
- * const client = createClient<typeof cms>({ baseURL: "http://localhost:3000" })
- * const qpo = createQuestpieQueryOptions(client)
+ * const client = createClient<App, AppRpc>({ baseURL: "http://localhost:3000" })
+ * const cmsQueries = createQuestpieQueryOptions(client)
  *
  * // Use with useQuery
- * const { data } = useQuery(qpo.collections.posts.find({ limit: 10 }))
+ * const { data } = useQuery(cmsQueries.collections.posts.find({ limit: 10 }))
  *
  * // Use with useMutation
- * const mutation = useMutation(qpo.collections.posts.create())
+ * const mutation = useMutation(cmsQueries.collections.posts.create())
+ *
+ * // Use with routes
+ * const stats = useQuery(cmsQueries.routes.dashboard.getStats.query({ period: "week" }))
  * ```
  */
-declare function createQuestpieQueryOptions<T extends Questpie<any>>(client: QuestpieClient<T>, config?: QuestpieQueryOptionsConfig): QuestpieQueryOptionsProxy<T>;
+declare function createQuestpieQueryOptions<TApp extends QuestpieApp = QuestpieApp>(client: QuestpieClient<TApp>, config?: QuestpieQueryOptionsConfig): QuestpieQueryOptionsProxy<TApp>;
 //#endregion
-export { type DefaultError, type QueryKey, QuestpieQueryErrorMap, QuestpieQueryOptionsConfig, QuestpieQueryOptionsProxy, type UseMutationOptions, type UseQueryOptions, createQuestpieQueryOptions };
+export { type DefaultError, type QueryKey, QuestpieQueryErrorMap, QuestpieQueryOptionsConfig, QuestpieQueryOptionsProxy, type RealtimeAPI, type TopicConfig, type UseMutationOptions, type UseQueryOptions, buildCollectionTopic, buildGlobalTopic, createQuestpieQueryOptions };

package/dist/index.mjs

@@ -1,4 +1,5 @@
-import { mutationOptions, queryOptions } from "@tanstack/react-query";
+import { experimental_streamedQuery, mutationOptions, queryOptions } from "@tanstack/react-query";
+import { buildCollectionTopic, buildCollectionTopic as buildCollectionTopic$1, buildGlobalTopic, buildGlobalTopic as buildGlobalTopic$1 } from "questpie/client";
 
 //#region src/index.ts
 const defaultErrorMap = (error) => error instanceof Error ? error : new Error(typeof error === "string" ? error : "Unknown error");
@@ -44,114 +45,334 @@ const wrapMutationFn = (mutationFn, errorMap) => {
 * ```ts
 * import { createQuestpieQueryOptions } from "@questpie/tanstack-query"
 * import { createClient } from "questpie/client"
+* import type { App, AppRpc } from "@/app"
 *
-* const client = createClient<typeof cms>({ baseURL: "http://localhost:3000" })
-* const qpo = createQuestpieQueryOptions(client)
+* const client = createClient<App, AppRpc>({ baseURL: "http://localhost:3000" })
+* const cmsQueries = createQuestpieQueryOptions(client)
 *
 * // Use with useQuery
-* const { data } = useQuery(qpo.collections.posts.find({ limit: 10 }))
+* const { data } = useQuery(cmsQueries.collections.posts.find({ limit: 10 }))
 *
 * // Use with useMutation
-* const mutation = useMutation(qpo.collections.posts.create())
+* const mutation = useMutation(cmsQueries.collections.posts.create())
+*
+* // Use with routes
+* const stats = useQuery(cmsQueries.routes.dashboard.getStats.query({ period: "week" }))
 * ```
 */
 function createQuestpieQueryOptions(client, config = {}) {
 	const keyPrefix = config.keyPrefix ?? ["questpie"];
 	const errorMap = config.errorMap ?? defaultErrorMap;
 	const locale = config.locale;
-	return {
-		collections: new Proxy({}, { get: (_target, collectionName) => {
-			if (typeof collectionName !== "string") return void 0;
-			const collection = client.collections[collectionName];
-			const baseKey = ["collections", collectionName];
-			return {
-				find: (options) => queryOptions({
-					queryKey: buildKey(keyPrefix, [
-						...baseKey,
-						"find",
-						locale,
-						normalizeQueryKeyOptions(options)
-					]),
+	const stage = config.stage;
+	const collections = new Proxy({}, { get: (_target, collectionName) => {
+		if (typeof collectionName !== "string") return void 0;
+		const collection = client.collections[collectionName];
+		const baseKey = ["collections", collectionName];
+		return {
+			find: (options, queryConfig) => {
+				const qKey = buildKey(keyPrefix, [
+					...baseKey,
+					"find",
+					locale,
+					stage,
+					normalizeQueryKeyOptions(options)
+				]);
+				if (queryConfig?.realtime && client.realtime) {
+					const topic = buildCollectionTopic$1(collectionName, options);
+					return queryOptions({
+						queryKey: qKey,
+						queryFn: experimental_streamedQuery({
+							streamFn: ({ signal }) => client.realtime.stream(topic, signal),
+							reducer: (_, chunk) => chunk,
+							initialValue: void 0,
+							refetchMode: "append"
+						})
+					});
+				}
+				return queryOptions({
+					queryKey: qKey,
 					queryFn: wrapQueryFn(() => collection.find(options), errorMap)
-				}),
-				count: (options) => queryOptions({
-					queryKey: buildKey(keyPrefix, [
-						...baseKey,
-						"count",
-						locale,
-						normalizeQueryKeyOptions(options)
-					]),
+				});
+			},
+			count: (options, queryConfig) => {
+				const qKey = buildKey(keyPrefix, [
+					...baseKey,
+					"count",
+					locale,
+					stage,
+					normalizeQueryKeyOptions(options)
+				]);
+				if (queryConfig?.realtime && client.realtime) {
+					const topic = buildCollectionTopic$1(collectionName, options);
+					return queryOptions({
+						queryKey: qKey,
+						queryFn: experimental_streamedQuery({
+							streamFn: ({ signal }) => client.realtime.stream(topic, signal),
+							reducer: (_, chunk) => typeof chunk?.totalDocs === "number" ? chunk.totalDocs : chunk,
+							initialValue: void 0,
+							refetchMode: "append"
+						})
+					});
+				}
+				return queryOptions({
+					queryKey: qKey,
 					queryFn: wrapQueryFn(() => collection.count(options), errorMap)
-				}),
-				findOne: (options) => queryOptions({
-					queryKey: buildKey(keyPrefix, [
-						...baseKey,
-						"findOne",
-						locale,
-						normalizeQueryKeyOptions(options)
-					]),
-					queryFn: wrapQueryFn(() => collection.findOne(options), errorMap)
-				}),
-				create: () => mutationOptions({
-					mutationKey: buildKey(keyPrefix, [
-						...baseKey,
-						"create",
-						locale
-					]),
-					mutationFn: wrapMutationFn((data) => collection.create(data, locale ? { locale } : void 0), errorMap)
-				}),
-				update: () => mutationOptions({
-					mutationKey: buildKey(keyPrefix, [
-						...baseKey,
-						"update",
-						locale
-					]),
-					mutationFn: wrapMutationFn((variables) => collection.update(variables.id, variables.data, locale ? { locale } : void 0), errorMap)
-				}),
-				delete: () => mutationOptions({
-					mutationKey: buildKey(keyPrefix, [
-						...baseKey,
-						"delete",
-						locale
-					]),
-					mutationFn: wrapMutationFn((variables) => collection.delete(variables.id, locale ? { locale } : void 0), errorMap)
-				}),
-				restore: () => mutationOptions({
-					mutationKey: buildKey(keyPrefix, [
-						...baseKey,
-						"restore",
-						locale
-					]),
-					mutationFn: wrapMutationFn((variables) => collection.restore(variables.id, locale ? { locale } : void 0), errorMap)
-				})
-			};
-		} }),
-		globals: new Proxy({}, { get: (_target, globalName) => {
-			if (typeof globalName !== "string") return void 0;
-			const global = client.globals[globalName];
-			const baseKey = ["globals", globalName];
-			return {
-				get: (options) => queryOptions({
-					queryKey: buildKey(keyPrefix, [
-						...baseKey,
-						"get",
-						locale,
-						normalizeQueryKeyOptions(options)
-					]),
+				});
+			},
+			findOne: (options) => queryOptions({
+				queryKey: buildKey(keyPrefix, [
+					...baseKey,
+					"findOne",
+					locale,
+					stage,
+					normalizeQueryKeyOptions(options)
+				]),
+				queryFn: wrapQueryFn(() => collection.findOne(options), errorMap)
+			}),
+			create: () => mutationOptions({
+				mutationKey: buildKey(keyPrefix, [
+					...baseKey,
+					"create",
+					locale,
+					stage
+				]),
+				mutationFn: wrapMutationFn((data) => collection.create(data, locale || stage ? {
+					...locale ? { locale } : {},
+					...stage ? { stage } : {}
+				} : void 0), errorMap)
+			}),
+			update: () => mutationOptions({
+				mutationKey: buildKey(keyPrefix, [
+					...baseKey,
+					"update",
+					locale,
+					stage
+				]),
+				mutationFn: wrapMutationFn((variables) => collection.update(variables, locale || stage ? {
+					...locale ? { locale } : {},
+					...stage ? { stage } : {}
+				} : void 0), errorMap)
+			}),
+			delete: () => mutationOptions({
+				mutationKey: buildKey(keyPrefix, [
+					...baseKey,
+					"delete",
+					locale,
+					stage
+				]),
+				mutationFn: wrapMutationFn((variables) => collection.delete(variables, locale || stage ? {
+					...locale ? { locale } : {},
+					...stage ? { stage } : {}
+				} : void 0), errorMap)
+			}),
+			restore: () => mutationOptions({
+				mutationKey: buildKey(keyPrefix, [
+					...baseKey,
+					"restore",
+					locale,
+					stage
+				]),
+				mutationFn: wrapMutationFn((variables) => collection.restore(variables, locale || stage ? {
+					...locale ? { locale } : {},
+					...stage ? { stage } : {}
+				} : void 0), errorMap)
+			}),
+			findVersions: (params) => queryOptions({
+				queryKey: buildKey(keyPrefix, [
+					...baseKey,
+					"findVersions",
+					locale,
+					stage,
+					normalizeQueryKeyOptions(params)
+				]),
+				queryFn: wrapQueryFn(() => collection.findVersions(params, locale || stage ? {
+					...locale ? { locale } : {},
+					...stage ? { stage } : {}
+				} : void 0), errorMap)
+			}),
+			revertToVersion: () => mutationOptions({
+				mutationKey: buildKey(keyPrefix, [
+					...baseKey,
+					"revertToVersion",
+					locale,
+					stage
+				]),
+				mutationFn: wrapMutationFn((variables) => collection.revertToVersion(variables, locale || stage ? {
+					...locale ? { locale } : {},
+					...stage ? { stage } : {}
+				} : void 0), errorMap)
+			}),
+			transitionStage: () => mutationOptions({
+				mutationKey: buildKey(keyPrefix, [
+					...baseKey,
+					"transitionStage",
+					locale,
+					stage
+				]),
+				mutationFn: wrapMutationFn((variables) => collection.transitionStage(variables, locale || stage ? {
+					...locale ? { locale } : {},
+					...stage ? { stage } : {}
+				} : void 0), errorMap)
+			}),
+			updateMany: () => mutationOptions({
+				mutationKey: buildKey(keyPrefix, [
+					...baseKey,
+					"updateMany",
+					locale,
+					stage
+				]),
+				mutationFn: wrapMutationFn((variables) => collection.updateMany(variables, locale || stage ? {
+					...locale ? { locale } : {},
+					...stage ? { stage } : {}
+				} : void 0), errorMap)
+			}),
+			deleteMany: () => mutationOptions({
+				mutationKey: buildKey(keyPrefix, [
+					...baseKey,
+					"deleteMany",
+					locale,
+					stage
+				]),
+				mutationFn: wrapMutationFn((variables) => collection.deleteMany(variables, locale || stage ? {
+					...locale ? { locale } : {},
+					...stage ? { stage } : {}
+				} : void 0), errorMap)
+			})
+		};
+	} });
+	const globals = new Proxy({}, { get: (_target, globalName) => {
+		if (typeof globalName !== "string") return void 0;
+		const global = client.globals[globalName];
+		const baseKey = ["globals", globalName];
+		return {
+			get: (options, queryConfig) => {
+				const qKey = buildKey(keyPrefix, [
+					...baseKey,
+					"get",
+					locale,
+					stage,
+					normalizeQueryKeyOptions(options)
+				]);
+				if (queryConfig?.realtime && client.realtime) {
+					const topic = buildGlobalTopic$1(globalName, options);
+					return queryOptions({
+						queryKey: qKey,
+						queryFn: experimental_streamedQuery({
+							streamFn: ({ signal }) => client.realtime.stream(topic, signal),
+							reducer: (_, chunk) => chunk,
+							initialValue: void 0,
+							refetchMode: "append"
+						})
+					});
+				}
+				return queryOptions({
+					queryKey: qKey,
 					queryFn: wrapQueryFn(() => global.get(options), errorMap)
-				}),
-				update: () => mutationOptions({
-					mutationKey: buildKey(keyPrefix, [
-						...baseKey,
-						"update",
-						locale
-					]),
-					mutationFn: wrapMutationFn((variables) => global.update(variables.data, {
-						...variables.options,
-						...locale ? { locale } : void 0
-					}), errorMap)
-				})
-			};
+				});
+			},
+			update: () => mutationOptions({
+				mutationKey: buildKey(keyPrefix, [
+					...baseKey,
+					"update",
+					locale,
+					stage
+				]),
+				mutationFn: wrapMutationFn((variables) => global.update(variables.data, {
+					...variables.options,
+					...locale ? { locale } : void 0,
+					...stage ? { stage } : void 0
+				}), errorMap)
+			}),
+			findVersions: (options) => queryOptions({
+				queryKey: buildKey(keyPrefix, [
+					...baseKey,
+					"findVersions",
+					locale,
+					stage,
+					normalizeQueryKeyOptions(options)
+				]),
+				queryFn: wrapQueryFn(() => global.findVersions({
+					...options,
+					...locale ? { locale } : void 0,
+					...stage ? { stage } : void 0
+				}), errorMap)
+			}),
+			revertToVersion: () => mutationOptions({
+				mutationKey: buildKey(keyPrefix, [
+					...baseKey,
+					"revertToVersion",
+					locale,
+					stage
+				]),
+				mutationFn: wrapMutationFn((variables) => global.revertToVersion(variables.params, {
+					...variables.options,
+					...locale ? { locale } : void 0,
+					...stage ? { stage } : void 0
+				}), errorMap)
+			}),
+			transitionStage: () => mutationOptions({
+				mutationKey: buildKey(keyPrefix, [
+					...baseKey,
+					"transitionStage",
+					locale,
+					stage
+				]),
+				mutationFn: wrapMutationFn((variables) => global.transitionStage(variables.params, {
+					...variables.options,
+					...locale ? { locale } : void 0
+				}), errorMap)
+			})
+		};
+	} });
+	/**
+	* Resolve a nested route caller from the client by traversing dot segments.
+	*/
+	const callRoute = async (segments, input) => {
+		let current = client.routes;
+		for (const segment of segments) current = current?.[segment];
+		if (typeof current !== "function") throw new Error(`Route not found at path: ${segments.join(".") || "<root>"}`);
+		if (input === void 0) return current();
+		return current(input);
+	};
+	const createRouteNodeProxy = (segments) => {
+		return new Proxy({}, { get: (_target, prop) => {
+			if (prop === "query") return (input) => queryOptions({
+				queryKey: buildKey(keyPrefix, [
+					"routes",
+					...segments,
+					"query",
+					locale,
+					normalizeQueryKeyOptions(input)
+				]),
+				queryFn: wrapQueryFn(() => callRoute(segments, input), errorMap)
+			});
+			if (prop === "mutation") return () => mutationOptions({
+				mutationKey: buildKey(keyPrefix, [
+					"routes",
+					...segments,
+					"mutation",
+					locale
+				]),
+				mutationFn: wrapMutationFn((variables) => callRoute(segments, variables), errorMap)
+			});
+			if (prop === "key") return (input) => buildKey(keyPrefix, [
+				"routes",
+				...segments,
+				"query",
+				locale,
+				normalizeQueryKeyOptions(input)
+			]);
+			if (typeof prop !== "string") return void 0;
+			return createRouteNodeProxy([...segments, prop]);
+		} });
+	};
+	return {
+		collections,
+		globals,
+		routes: new Proxy({}, { get: (_target, prop) => {
+			if (typeof prop !== "string") return void 0;
+			return createRouteNodeProxy([prop]);
 		} }),
 		custom: {
 			query: (customConfig) => queryOptions({
@@ -168,4 +389,4 @@ function createQuestpieQueryOptions(client, config = {}) {
 }
 
 //#endregion
-export { createQuestpieQueryOptions };
+export { buildCollectionTopic, buildGlobalTopic, createQuestpieQueryOptions };

package/package.json

@@ -1,15 +1,35 @@
 {
 	"name": "@questpie/tanstack-query",
-	"version": "1.1.1",
-	"type": "module",
+	"version": "3.0.0",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/questpie/questpie-cms.git",
+		"url": "https://github.com/questpie/questpie.git",
 		"directory": "packages/tanstack-query"
 	},
 	"files": [
 		"dist"
 	],
+	"type": "module",
+	"main": "./dist/index.mjs",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.mts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.mts",
+			"default": "./dist/index.mjs"
+		},
+		"./package.json": "./package.json"
+	},
+	"publishConfig": {
+		"access": "public",
+		"exports": {
+			".": {
+				"types": "./dist/index.d.mts",
+				"default": "./dist/index.mjs"
+			},
+			"./package.json": "./package.json"
+		}
+	},
 	"scripts": {
 		"build": "tsdown",
 		"check-types": "tsc --noEmit"
@@ -19,16 +39,7 @@
 		"tsdown": "^0.18.3"
 	},
 	"peerDependencies": {
-		"questpie": "^1.0.0",
-		"@tanstack/react-query": "^5.0.0"
-	},
-	"exports": {
-		".": {
-			"import": "./dist/index.mjs",
-			"types": "./dist/index.d.mts"
-		}
-	},
-	"publishConfig": {
-		"access": "public"
+		"@tanstack/react-query": "^5.0.0",
+		"questpie": "^3.0.0"
 	}
 }