@kibinrpc/tanstack-query 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ixexel661
+
+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,177 @@
+# @kibinrpc/tanstack-query
+
+TanStack Query (v5) adapter for [kibinrpc](../../README.md) — type-safe `queryOptions`, `mutationOptions`, and query key factories, fully inferred from your server router.
+
+## Installation
+
+```sh
+npm install @kibinrpc/tanstack-query @kibinrpc/client @tanstack/react-query
+```
+
+## Quick start
+
+```ts
+// src/kibin.ts
+import { createKibinClient } from '@kibinrpc/client'
+import { createKibinQuery } from '@kibinrpc/tanstack-query'
+import { QueryClient } from '@tanstack/react-query'
+import type { AppRouter } from './server/router'
+
+export const queryClient = new QueryClient()
+export const client = createKibinClient<AppRouter>({ baseUrl: '/api/rpc' })
+export const query = createKibinQuery(client)
+```
+
+```tsx
+// In a component
+import { useQuery, useMutation } from '@tanstack/react-query'
+import { query, queryClient } from './kibin'
+
+function UserList() {
+  const users = useQuery(query.user.listUsers.queryOptions([]))
+
+  const createUser = useMutation(
+    query.user.createUser.mutationOptions({
+      onSuccess: () =>
+        queryClient.invalidateQueries({ queryKey: query.user.queryKey() }),
+    }),
+  )
+
+  return (
+    <>
+      <ul>{users.data?.map(u => <li key={u.id}>{u.name}</li>)}</ul>
+      <button onClick={() => createUser.mutate([{ name: 'Alice', email: 'alice@example.com' }])}>
+        Add
+      </button>
+    </>
+  )
+}
+```
+
+## Query keys
+
+Every namespace and method exposes a stable `queryKey()` factory. TanStack Query's prefix-matching means invalidating a broader key covers all narrower ones beneath it.
+
+```ts
+query.user.queryKey()                    // ['@kibinrpc', 'user']
+query.user.getUser.queryKey()            // ['@kibinrpc', 'user', 'getUser']
+query.user.getUser.queryKey(['user-1'])  // ['@kibinrpc', 'user', 'getUser', { args: ['user-1'] }]
+```
+
+```ts
+// Invalidate all user queries
+queryClient.invalidateQueries({ queryKey: query.user.queryKey() })
+
+// Invalidate exactly one call
+queryClient.invalidateQueries({ queryKey: query.user.getUser.queryKey(['user-1']) })
+```
+
+## Queries
+
+`queryOptions` returns a fully-typed options object compatible with `useQuery`, `useSuspenseQuery`, `prefetchQuery`, `fetchQuery`, and `useQueries`.
+
+```ts
+// Basic
+useQuery(query.post.listPosts.queryOptions([]))
+
+// With overrides
+useSuspenseQuery(query.user.getUser.queryOptions([id], { staleTime: 60_000 }))
+
+// Parallel — auto-batched by kibinrpc into one HTTP request
+useQueries({
+  queries: [
+    query.user.getUser.queryOptions(['1']),
+    query.user.getUser.queryOptions(['2']),
+  ],
+})
+
+// Prefetch in a route loader or server component
+await queryClient.prefetchQuery(query.post.listPosts.queryOptions([]))
+```
+
+## Mutations
+
+`mutationOptions` returns a fully-typed options object for `useMutation`. Arguments are passed as a tuple matching the server method's parameter list.
+
+```ts
+const createPost = useMutation(
+  query.post.createPost.mutationOptions({
+    onSuccess: () =>
+      queryClient.invalidateQueries({ queryKey: query.post.queryKey() }),
+  }),
+)
+
+// args tuple — same order as the server method signature
+createPost.mutate([{ title: 'Hello', body: 'World', authorId: '1' }])
+```
+
+## Configuration
+
+```ts
+// Change the query key prefix (default: '@kibinrpc')
+const query = createKibinQuery(client, { queryKeyPrefix: 'myapp' })
+
+query.user.queryKey() // ['myapp', 'user']
+```
+
+## Error handling
+
+All query and mutation errors are typed as `KibinError`. Use `isKibinError` to narrow the type:
+
+```ts
+import { isKibinError } from '@kibinrpc/client'
+
+if (isKibinError(error)) {
+  console.log(error.code)    // e.g. 'NOT_FOUND', 'TIMEOUT'
+  console.log(error.message)
+}
+```
+
+## API
+
+### `createKibinQuery(client, config?)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `client` | `KibinClient<Router>` | The kibinrpc client to wrap |
+| `config.queryKeyPrefix` | `string` | Prefix for all generated keys. Default: `'@kibinrpc'` |
+
+### `KibinQueryProxy<Router>`
+
+For every namespace `NS` and method `M`:
+
+| Property | Description |
+|---|---|
+| `query[NS][M].queryOptions(args, options?)` | Options for `useQuery`, `useSuspenseQuery`, `prefetchQuery`, … |
+| `query[NS][M].queryKey(args?)` | Call-level key (with args) or method-level key (without) |
+| `query[NS][M].mutationOptions(options?)` | Options for `useMutation` |
+| `query[NS][M].mutationKey()` | Stable key for devtools filtering |
+| `query[NS].queryKey()` | Namespace-level key for broad invalidation |
+
+### Exported types
+
+```ts
+import type {
+  KibinQueryProxy,
+  KibinQueryConfig,
+  MethodUtils,
+} from '@kibinrpc/tanstack-query'
+```
+
+## Known limitations
+
+**TanStack Query's `signal` is not forwarded.** When a component unmounts, TQ passes an `AbortSignal` to `queryFn` to cancel the request — kibinrpc does not support per-call signals yet, so the underlying HTTP request will complete even if TQ discards the result. As a workaround, override `queryFn` manually:
+
+```ts
+query.user.listUsers.queryOptions([], {
+  queryFn: ({ signal }) =>
+    createKibinClient<AppRouter>({ baseUrl: '/api/rpc', signal }).user.listUsers(),
+})
+```
+
+## Related packages
+
+| Package | Description |
+|---|---|
+| [`@kibinrpc/server`](../server/README.md) | Server-side router and action decorators |
+| [`@kibinrpc/client`](../client/README.md) | Type-safe fetch client with automatic batching and retry |

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { MutationObserverOptions, QueryObserverOptions } from "@tanstack/react-query";
+import { KibinClient, KibinError } from "@kibinrpc/client";
+
+//#region src/types.d.ts
+type AnyAsyncFn = (...args: never[]) => Promise<unknown>;
+type MethodUtils<F extends AnyAsyncFn> = {
+  /**
+   * Returns query options compatible with useQuery, useSuspenseQuery,
+   * prefetchQuery, queryClient.fetchQuery, and more.
+   *
+   * @param args Method arguments as a tuple
+   * @param options Additional QueryObserverOptions to merge
+   */
+  queryOptions(args: Parameters<F>, options?: Omit<QueryObserverOptions<Awaited<ReturnType<F>>, KibinError>, 'queryKey' | 'queryFn'>): QueryObserverOptions<Awaited<ReturnType<F>>, KibinError>;
+  /**
+   * Returns a stable query key for this method.
+   * Omit `args` to get a broader key that matches all calls to this method.
+   *
+   * @example
+   * query.user.getUser.queryKey(['id-1']) // exact call
+   * query.user.getUser.queryKey()         // all getUser calls
+   */
+  queryKey(args?: Parameters<F>): readonly unknown[];
+  /**
+   * Returns mutation options for use with useMutation.
+   * Variables passed to `mutate()` must be the argument tuple.
+   *
+   * @example
+   * const { mutate } = useMutation(query.user.createUser.mutationOptions())
+   * mutate(['Alice', 'alice@example.com'])
+   */
+  mutationOptions(options?: Omit<MutationObserverOptions<Awaited<ReturnType<F>>, KibinError, Parameters<F>>, 'mutationFn' | 'mutationKey'>): MutationObserverOptions<Awaited<ReturnType<F>>, KibinError, Parameters<F>>; /** Stable mutation key for devtools filtering and tracking */
+  mutationKey(): readonly unknown[];
+};
+type NamespaceUtils<NS extends Record<string, AnyAsyncFn>> = { [M in keyof NS]: MethodUtils<NS[M]> } & {
+  /** Broad query key covering all methods in this namespace — useful for invalidation */queryKey(): readonly unknown[];
+};
+type KibinQueryProxy<Router> = { [NS in Exclude<keyof KibinClient<Router>, '$unbatched'>]: KibinClient<Router>[NS] extends Record<string, AnyAsyncFn> ? NamespaceUtils<KibinClient<Router>[NS]> : never };
+interface KibinQueryConfig {
+  /** Prefix for all generated query keys. Default: '@kibinrpc' */
+  queryKeyPrefix?: string;
+}
+//#endregion
+//#region src/query.d.ts
+declare function createKibinQuery<Router>(client: KibinClient<Router>, config?: KibinQueryConfig): KibinQueryProxy<Router>;
+//#endregion
+export { type KibinQueryConfig, type KibinQueryProxy, type MethodUtils, createKibinQuery };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/query.ts"],"mappings":";;;;KAGK,UAAA,OAAiB,IAAA,cAAkB,OAAO;AAAA,KAEnC,WAAA,WAAsB,UAAA;EAF7B;;;;AAA0C;AAE/C;;EAQC,YAAA,CACC,IAAA,EAAM,UAAA,CAAW,CAAA,GACjB,OAAA,GAAU,IAAA,CACT,oBAAA,CAAqB,OAAA,CAAQ,UAAA,CAAW,CAAA,IAAK,UAAA,6BAG5C,oBAAA,CAAqB,OAAA,CAAQ,UAAA,CAAW,CAAA,IAAK,UAAA;EAdf;;;;;;;;EAwBjC,QAAA,CAAS,IAAA,GAAO,UAAA,CAAW,CAAA;EAVgB;;;;;;;;EAoB3C,eAAA,CACC,OAAA,GAAU,IAAA,CACT,uBAAA,CAAwB,OAAA,CAAQ,UAAA,CAAW,CAAA,IAAK,UAAA,EAAY,UAAA,CAAW,CAAA,oCAGtE,uBAAA,CAAwB,OAAA,CAAQ,UAAA,CAAW,CAAA,IAAK,UAAA,EAAY,UAAA,CAAW,CAAA,IAHhD;EAM1B,WAAA;AAAA;AAAA,KAGI,cAAA,YAA0B,MAAA,SAAe,UAAA,mBACjC,EAAA,GAAK,WAAA,CAAY,EAAA,CAAG,CAAA;EAPc,uFAU9C,QAAA;AAAA;AAAA,KAGW,eAAA,oBACJ,OAAA,OAAc,WAAA,CAAY,MAAA,mBAAyB,WAAA,CAAY,MAAA,EAAQ,EAAA,UAAY,MAAA,SAEzF,UAAA,IAEE,cAAA,CAAe,WAAA,CAAY,MAAA,EAAQ,EAAA;AAAA,UAItB,gBAAA;EAtBU;EAwB1B,cAAc;AAAA;;;iBC3DC,gBAAA,QAAA,CACf,MAAA,EAAQ,WAAA,CAAY,MAAA,GACpB,MAAA,GAAQ,gBAAA,GACN,eAAA,CAAgB,MAAA"}

package/dist/index.js

@@ -0,0 +1,62 @@
+import { mutationOptions, queryOptions } from "@tanstack/react-query";
+//#region src/query.ts
+const DEFAULT_PREFIX = "@kibinrpc";
+function createKibinQuery(client, config = {}) {
+	const prefix = config.queryKeyPrefix ?? DEFAULT_PREFIX;
+	function nsKey(namespace) {
+		return [prefix, namespace];
+	}
+	function methodKey(namespace, method, args) {
+		if (args !== void 0) return [
+			prefix,
+			namespace,
+			method,
+			{ args }
+		];
+		return [
+			prefix,
+			namespace,
+			method
+		];
+	}
+	function makeMethodUtils(namespace, method) {
+		const fn = client[namespace][method];
+		return {
+			queryOptions(args, options = {}) {
+				return queryOptions({
+					queryKey: methodKey(namespace, method, args),
+					queryFn: () => fn(...args),
+					...options
+				});
+			},
+			queryKey(args) {
+				return methodKey(namespace, method, args);
+			},
+			mutationOptions(options = {}) {
+				return mutationOptions({
+					mutationKey: methodKey(namespace, method),
+					mutationFn: (args) => fn(...args),
+					...options
+				});
+			},
+			mutationKey() {
+				return methodKey(namespace, method);
+			}
+		};
+	}
+	function makeNamespaceProxy(namespace) {
+		return new Proxy({}, { get(_, prop) {
+			if (prop === "queryKey") return () => nsKey(namespace);
+			if (typeof prop !== "string") return void 0;
+			return makeMethodUtils(namespace, prop);
+		} });
+	}
+	return new Proxy({}, { get(_, namespace) {
+		if (typeof namespace !== "string") return void 0;
+		return makeNamespaceProxy(namespace);
+	} });
+}
+//#endregion
+export { createKibinQuery };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/query.ts"],"sourcesContent":["import type { KibinClient } from '@kibinrpc/client';\nimport { mutationOptions, queryOptions } from '@tanstack/react-query';\nimport type { KibinQueryConfig, KibinQueryProxy } from './types.js';\n\nconst DEFAULT_PREFIX = '@kibinrpc';\n\ntype AnyFn = (...args: unknown[]) => Promise<unknown>;\ntype AnyRecord = Record<string, AnyFn>;\n\nexport function createKibinQuery<Router>(\n\tclient: KibinClient<Router>,\n\tconfig: KibinQueryConfig = {},\n): KibinQueryProxy<Router> {\n\tconst prefix = config.queryKeyPrefix ?? DEFAULT_PREFIX;\n\n\tfunction nsKey(namespace: string): readonly unknown[] {\n\t\treturn [prefix, namespace];\n\t}\n\n\tfunction methodKey(namespace: string, method: string, args?: unknown[]): readonly unknown[] {\n\t\tif (args !== undefined) return [prefix, namespace, method, { args }];\n\t\treturn [prefix, namespace, method];\n\t}\n\n\tfunction makeMethodUtils(namespace: string, method: string) {\n\t\tconst fn = (client as Record<string, AnyRecord>)[namespace][method];\n\n\t\treturn {\n\t\t\tqueryOptions(args: unknown[], options = {}) {\n\t\t\t\treturn queryOptions({\n\t\t\t\t\tqueryKey: methodKey(namespace, method, args),\n\t\t\t\t\tqueryFn: () => fn(...args),\n\t\t\t\t\t...options,\n\t\t\t\t});\n\t\t\t},\n\n\t\t\tqueryKey(args?: unknown[]) {\n\t\t\t\treturn methodKey(namespace, method, args);\n\t\t\t},\n\n\t\t\tmutationOptions(options = {}) {\n\t\t\t\treturn mutationOptions({\n\t\t\t\t\tmutationKey: methodKey(namespace, method),\n\t\t\t\t\tmutationFn: (args: unknown[]) => fn(...args),\n\t\t\t\t\t...options,\n\t\t\t\t});\n\t\t\t},\n\n\t\t\tmutationKey() {\n\t\t\t\treturn methodKey(namespace, method);\n\t\t\t},\n\t\t};\n\t}\n\n\tfunction makeNamespaceProxy(namespace: string) {\n\t\treturn new Proxy(\n\t\t\t{},\n\t\t\t{\n\t\t\t\tget(_, prop: string | symbol) {\n\t\t\t\t\tif (prop === 'queryKey') return () => nsKey(namespace);\n\t\t\t\t\tif (typeof prop !== 'string') return undefined;\n\t\t\t\t\treturn makeMethodUtils(namespace, prop);\n\t\t\t\t},\n\t\t\t},\n\t\t);\n\t}\n\n\treturn new Proxy(\n\t\t{},\n\t\t{\n\t\t\tget(_, namespace: string | symbol) {\n\t\t\t\tif (typeof namespace !== 'string') return undefined;\n\t\t\t\treturn makeNamespaceProxy(namespace);\n\t\t\t},\n\t\t},\n\t) as unknown as KibinQueryProxy<Router>;\n}\n"],"mappings":";;AAIA,MAAM,iBAAiB;AAKvB,SAAgB,iBACf,QACA,SAA2B,CAAC,GACF;CAC1B,MAAM,SAAS,OAAO,kBAAkB;CAExC,SAAS,MAAM,WAAuC;EACrD,OAAO,CAAC,QAAQ,SAAS;CAC1B;CAEA,SAAS,UAAU,WAAmB,QAAgB,MAAsC;EAC3F,IAAI,SAAS,KAAA,GAAW,OAAO;GAAC;GAAQ;GAAW;GAAQ,EAAE,KAAK;EAAC;EACnE,OAAO;GAAC;GAAQ;GAAW;EAAM;CAClC;CAEA,SAAS,gBAAgB,WAAmB,QAAgB;EAC3D,MAAM,KAAM,OAAqC,WAAW;EAE5D,OAAO;GACN,aAAa,MAAiB,UAAU,CAAC,GAAG;IAC3C,OAAO,aAAa;KACnB,UAAU,UAAU,WAAW,QAAQ,IAAI;KAC3C,eAAe,GAAG,GAAG,IAAI;KACzB,GAAG;IACJ,CAAC;GACF;GAEA,SAAS,MAAkB;IAC1B,OAAO,UAAU,WAAW,QAAQ,IAAI;GACzC;GAEA,gBAAgB,UAAU,CAAC,GAAG;IAC7B,OAAO,gBAAgB;KACtB,aAAa,UAAU,WAAW,MAAM;KACxC,aAAa,SAAoB,GAAG,GAAG,IAAI;KAC3C,GAAG;IACJ,CAAC;GACF;GAEA,cAAc;IACb,OAAO,UAAU,WAAW,MAAM;GACnC;EACD;CACD;CAEA,SAAS,mBAAmB,WAAmB;EAC9C,OAAO,IAAI,MACV,CAAC,GACD,EACC,IAAI,GAAG,MAAuB;GAC7B,IAAI,SAAS,YAAY,aAAa,MAAM,SAAS;GACrD,IAAI,OAAO,SAAS,UAAU,OAAO,KAAA;GACrC,OAAO,gBAAgB,WAAW,IAAI;EACvC,EACD,CACD;CACD;CAEA,OAAO,IAAI,MACV,CAAC,GACD,EACC,IAAI,GAAG,WAA4B;EAClC,IAAI,OAAO,cAAc,UAAU,OAAO,KAAA;EAC1C,OAAO,mBAAmB,SAAS;CACpC,EACD,CACD;AACD"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@kibinrpc/tanstack-query",
+  "version": "0.3.0",
+  "description": "TanStack Query adapter for @kibinrpc/client",
+  "license": "MIT",
+  "author": "ixexel661",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ixexel661/kibin",
+    "directory": "packages/tanstack-query"
+  },
+  "keywords": [
+    "rpc",
+    "tanstack-query",
+    "react-query",
+    "typescript"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "@kibinrpc/client": "0.3.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "tsdown": "^0.22.0",
+    "vitest": "^4.1.7",
+    "@kibinrpc/client": "0.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run"
+  }
+}