@questpie/tanstack-query 1.0.0

package/README.md

@@ -0,0 +1,303 @@
+# @questpie/tanstack-query
+
+Type-safe TanStack React Query integration for QUESTPIE.
+
+## 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
+
+## Installation
+
+```bash
+bun add @questpie/tanstack-query questpie @tanstack/react-query
+```
+
+## Quick Start
+
+### 1. Create Query Options
+
+```typescript
+// src/lib/queries.ts
+import { createClient } from "questpie/client";
+import { createQuestpieQueryOptions } from "@questpie/tanstack-query";
+import type { AppCMS } from "@/cms";
+
+const cmsClient = createClient<AppCMS>({
+  baseURL: "http://localhost:3000",
+  basePath: "/api/cms",
+});
+
+export const q = createQuestpieQueryOptions(cmsClient, {
+  keyPrefix: ["cms"], // Optional: prefix for all query keys
+});
+```
+
+### 2. Use in Components
+
+```typescript
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"
+import { q } 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>
+  )
+}
+```
+
+## Query Options API
+
+### Collections
+
+```typescript
+// Find many
+q.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 },
+});
+
+// Create
+q.collections.posts.create();
+// Usage: mutation.mutate({ title: "...", content: "..." })
+
+// Update
+q.collections.posts.update();
+// Usage: mutation.mutate({ id: "...", data: { title: "..." } })
+
+// Delete
+q.collections.posts.delete();
+// Usage: mutation.mutate({ id: "..." })
+
+// Restore (soft delete)
+q.collections.posts.restore();
+// Usage: mutation.mutate({ id: "..." })
+```
+
+### Globals
+
+```typescript
+// Get
+q.globals.siteSettings.get();
+
+// Update
+q.globals.siteSettings.update();
+// Usage: mutation.mutate({ data: { siteName: "..." } })
+```
+
+### Custom Queries
+
+```typescript
+const searchQuery = q.custom.query({
+  key: ["search", query],
+  queryFn: () => fetch(`/api/search?q=${query}`).then((r) => r.json()),
+});
+
+useQuery(searchQuery);
+```
+
+## 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"
+
+export const Route = createFileRoute("/posts")({
+  loader: async ({ context }) => {
+    await context.queryClient.ensureQueryData(
+      q.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>
+  )
+}
+```
+
+### 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"
+
+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>
+  )
+}
+```
+
+## Query Key Structure
+
+All query keys follow this structure:
+
+```typescript
+// Collections
+[...keyPrefix, "collections", collectionName, "find", options]
+[...keyPrefix, "collections", collectionName, "findOne", 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"]>;
+
+// Query result types are automatically inferred
+const { data } = useQuery(q.collections.posts.find({ limit: 10 }));
+//    ^? { docs: Post[], totalDocs: number, ... }
+```
+
+## Related Packages
+
+- [`questpie`](../questpie) - Core CMS engine
+- [`@questpie/hono`](../hono) - Hono adapter
+- [`@questpie/elysia`](../elysia) - Elysia adapter
+- [`@questpie/next`](../next) - Next.js adapter
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,93 @@
+import { DefaultError, QueryKey, UseMutationOptions, UseQueryOptions } from "@tanstack/react-query";
+import { Questpie } from "questpie";
+import { QuestpieClient } from "questpie/client";
+
+//#region src/index.d.ts
+type QuestpieQueryErrorMap = (error: unknown) => unknown;
+type QuestpieQueryOptionsConfig = {
+  keyPrefix?: QueryKey;
+  errorMap?: QuestpieQueryErrorMap;
+  locale?: 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 MutationBuilder<TVariables, TData> = () => UseMutationOptions<TData, DefaultError, TVariables>;
+/** Extract collection keys from QuestpieClient */
+type CollectionKeys<T extends Questpie<any>> = Extract<keyof QuestpieClient<T>["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 {
+  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 {
+  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 GlobalQueryOptionsAPI<T extends Questpie<any>, K$1 extends GlobalKeys<T>> = {
+  get: QueryBuilder<GlobalGet<T, K$1>>;
+  update: MutationBuilder<{
+    data: Parameters<GlobalUpdate<T, K$1>>[0];
+    options?: Parameters<GlobalUpdate<T, K$1>>[1];
+  }, QueryData<GlobalUpdate<T, K$1>>>;
+};
+type QuestpieQueryOptionsProxy<T extends Questpie<any>> = {
+  collections: { [K in CollectionKeys<T>]: CollectionQueryOptionsAPI<T, K> };
+  globals: { [K in GlobalKeys<T>]: GlobalQueryOptionsAPI<T, K> };
+  custom: {
+    query: <TData>(config: {
+      key: QueryKey;
+      queryFn: () => Promise<TData>;
+    }) => UseQueryOptions<TData>;
+    mutation: <TVariables, TData>(config: {
+      key: QueryKey;
+      mutationFn: (variables: TVariables) => Promise<TData>;
+    }) => UseMutationOptions<TData, DefaultError, TVariables>;
+  };
+  key: (parts: QueryKey) => QueryKey;
+};
+/**
+ * Create type-safe query options proxy for TanStack Query
+ *
+ * @example
+ * ```ts
+ * import { createQuestpieQueryOptions } from "@questpie/tanstack-query"
+ * import { createClient } from "questpie/client"
+ *
+ * const client = createClient<typeof cms>({ baseURL: "http://localhost:3000" })
+ * const qpo = createQuestpieQueryOptions(client)
+ *
+ * // Use with useQuery
+ * const { data } = useQuery(qpo.collections.posts.find({ limit: 10 }))
+ *
+ * // Use with useMutation
+ * const mutation = useMutation(qpo.collections.posts.create())
+ * ```
+ */
+declare function createQuestpieQueryOptions<T extends Questpie<any>>(client: QuestpieClient<T>, config?: QuestpieQueryOptionsConfig): QuestpieQueryOptionsProxy<T>;
+//#endregion
+export { type DefaultError, type QueryKey, QuestpieQueryErrorMap, QuestpieQueryOptionsConfig, QuestpieQueryOptionsProxy, type UseMutationOptions, type UseQueryOptions, createQuestpieQueryOptions };

package/dist/index.mjs

@@ -0,0 +1,171 @@
+import { mutationOptions, queryOptions } from "@tanstack/react-query";
+
+//#region src/index.ts
+const defaultErrorMap = (error) => error instanceof Error ? error : new Error(typeof error === "string" ? error : "Unknown error");
+const buildKey = (prefix, parts) => prefix.length ? [...prefix, ...parts] : parts;
+const sanitizeKeyPart = (value) => {
+	if (value === null || value === void 0) return value;
+	if (typeof value === "function") return void 0;
+	if (Array.isArray(value)) return value.map((item) => sanitizeKeyPart(item));
+	if (typeof value === "object") {
+		const sanitized = {};
+		for (const [key, entry] of Object.entries(value)) {
+			if (typeof entry === "function") continue;
+			const nextValue = sanitizeKeyPart(entry);
+			if (nextValue !== void 0) sanitized[key] = nextValue;
+		}
+		return sanitized;
+	}
+	return value;
+};
+const normalizeQueryKeyOptions = (options) => sanitizeKeyPart(options ?? {});
+const wrapQueryFn = (queryFn, errorMap) => {
+	return async () => {
+		try {
+			return await queryFn();
+		} catch (error) {
+			throw errorMap(error);
+		}
+	};
+};
+const wrapMutationFn = (mutationFn, errorMap) => {
+	return async (variables) => {
+		try {
+			return await mutationFn(variables);
+		} catch (error) {
+			throw errorMap(error);
+		}
+	};
+};
+/**
+* Create type-safe query options proxy for TanStack Query
+*
+* @example
+* ```ts
+* import { createQuestpieQueryOptions } from "@questpie/tanstack-query"
+* import { createClient } from "questpie/client"
+*
+* const client = createClient<typeof cms>({ baseURL: "http://localhost:3000" })
+* const qpo = createQuestpieQueryOptions(client)
+*
+* // Use with useQuery
+* const { data } = useQuery(qpo.collections.posts.find({ limit: 10 }))
+*
+* // Use with useMutation
+* const mutation = useMutation(qpo.collections.posts.create())
+* ```
+*/
+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)
+					]),
+					queryFn: wrapQueryFn(() => collection.find(options), errorMap)
+				}),
+				count: (options) => queryOptions({
+					queryKey: buildKey(keyPrefix, [
+						...baseKey,
+						"count",
+						locale,
+						normalizeQueryKeyOptions(options)
+					]),
+					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)
+					]),
+					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)
+				})
+			};
+		} }),
+		custom: {
+			query: (customConfig) => queryOptions({
+				queryKey: buildKey(keyPrefix, customConfig.key),
+				queryFn: wrapQueryFn(customConfig.queryFn, errorMap)
+			}),
+			mutation: (customConfig) => mutationOptions({
+				mutationKey: buildKey(keyPrefix, customConfig.key),
+				mutationFn: wrapMutationFn(customConfig.mutationFn, errorMap)
+			})
+		},
+		key: (parts) => buildKey(keyPrefix, parts)
+	};
+}
+
+//#endregion
+export { createQuestpieQueryOptions };

package/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "@questpie/tanstack-query",
+	"version": "1.0.0",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/questpie/questpie-cms.git",
+		"directory": "packages/tanstack-query"
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsdown",
+		"check-types": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@questpie/typescript-config": "workspace:*",
+		"bun-types": "latest",
+		"tsdown": "^0.18.3"
+	},
+	"peerDependencies": {
+		"questpie": "workspace:*",
+		"@tanstack/react-query": "^5.0.0"
+	},
+	"exports": {
+		".": {
+			"import": "./dist/index.mjs",
+			"types": "./dist/index.d.mts"
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}