@richie-rpc/react-query 1.0.0

package/README.md

@@ -0,0 +1,360 @@
+# @richie-rpc/react-query
+
+React hooks integration for Richie RPC using TanStack Query (React Query). Provides type-safe hooks with automatic caching, background refetching, and React Suspense support.
+
+## Installation
+
+```bash
+bun add @richie-rpc/react-query @richie-rpc/client @richie-rpc/core @tanstack/react-query zod@^4
+```
+
+## Features
+
+- 🎯 **Fully Type-Safe**: Complete TypeScript inference from contract to hooks
+- 🔄 **Automatic Method Detection**: GET/HEAD → queries, POST/PUT/PATCH/DELETE → mutations
+- ⚡ **React Suspense**: Built-in support with `useSuspenseQuery`
+- 💾 **Smart Caching**: Powered by TanStack Query
+- 🔥 **Zero Config**: Works out of the box with sensible defaults
+- 🎨 **Customizable**: Pass through all TanStack Query options
+
+## Quick Start
+
+### 1. Setup Provider
+
+Wrap your app with `QueryClientProvider`:
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { createClient } from '@richie-rpc/client';
+import { createHooks } from '@richie-rpc/react-query';
+import { contract } from './contract';
+
+// Create client and hooks
+const client = createClient(contract, {
+  baseUrl: 'http://localhost:3000',
+});
+
+const hooks = createHooks(client, contract);
+
+// Create query client
+const queryClient = new QueryClient();
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <YourApp />
+    </QueryClientProvider>
+  );
+}
+```
+
+### 2. Use Query Hooks (GET requests)
+
+Query hooks automatically fetch data when the component mounts:
+
+```tsx
+function UserList() {
+  const { data, isLoading, error, refetch } = hooks.listUsers.useQuery({
+    query: { limit: "10", offset: "0" }
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      {data.data.users.map(user => (
+        <div key={user.id}>{user.name}</div>
+      ))}
+      <button onClick={() => refetch()}>Refresh</button>
+    </div>
+  );
+}
+```
+
+### 3. Use Suspense Queries
+
+For React Suspense integration:
+
+```tsx
+function UserListSuspense() {
+  // This will suspend the component until data is loaded
+  const { data } = hooks.listUsers.useSuspenseQuery({
+    query: { limit: "10" }
+  });
+
+  return (
+    <div>
+      {data.data.users.map(user => (
+        <div key={user.id}>{user.name}</div>
+      ))}
+    </div>
+  );
+}
+
+// Wrap with Suspense boundary
+function App() {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <UserListSuspense />
+    </Suspense>
+  );
+}
+```
+
+### 4. Use Mutation Hooks (POST/PUT/PATCH/DELETE)
+
+Mutation hooks don't auto-fetch; they return a function to trigger the request:
+
+```tsx
+function CreateUserForm() {
+  const mutation = hooks.createUser.useMutation({
+    onSuccess: (data) => {
+      console.log('User created:', data);
+      // Invalidate and refetch
+      queryClient.invalidateQueries({ queryKey: ['listUsers'] });
+    },
+    onError: (error) => {
+      console.error('Failed to create user:', error);
+    },
+  });
+
+  const handleSubmit = (e: FormEvent) => {
+    e.preventDefault();
+    mutation.mutate({
+      body: {
+        name: "Alice",
+        email: "alice@example.com",
+        age: 25,
+      }
+    });
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <button 
+        type="submit" 
+        disabled={mutation.isPending}
+      >
+        {mutation.isPending ? 'Creating...' : 'Create User'}
+      </button>
+      {mutation.error && <div>Error: {mutation.error.message}</div>}
+    </form>
+  );
+}
+```
+
+## API Reference
+
+### `createHooks(client, contract)`
+
+Creates a typed hooks object from a client and contract.
+
+**Parameters:**
+- `client`: Client created with `createClient()`
+- `contract`: Your API contract definition
+
+**Returns:** Hooks object with methods for each endpoint
+
+### Query Hooks (GET/HEAD methods)
+
+#### `hooks.endpointName.useQuery(options, queryOptions?)`
+
+Standard query hook for read operations.
+
+**Parameters:**
+- `options`: Request options (params, query, headers, body)
+- `queryOptions`: Optional TanStack Query options (staleTime, cacheTime, etc.)
+
+**Returns:** `UseQueryResult` with data, isLoading, error, refetch, etc.
+
+#### `hooks.endpointName.useSuspenseQuery(options, queryOptions?)`
+
+Suspense-enabled query hook.
+
+**Parameters:**
+- `options`: Request options (params, query, headers, body)
+- `queryOptions`: Optional TanStack Query options
+
+**Returns:** `UseSuspenseQueryResult` with data (always defined when rendered)
+
+### Mutation Hooks (POST/PUT/PATCH/DELETE methods)
+
+#### `hooks.endpointName.useMutation(mutationOptions?)`
+
+Mutation hook for write operations.
+
+**Parameters:**
+- `mutationOptions`: Optional TanStack Query mutation options (onSuccess, onError, etc.)
+
+**Returns:** `UseMutationResult` with mutate, isPending, error, data, etc.
+
+## Advanced Usage
+
+### Custom Query Options
+
+Pass TanStack Query options for fine-grained control:
+
+```tsx
+const { data } = hooks.listUsers.useQuery(
+  { query: { limit: "10" } },
+  {
+    staleTime: 5 * 60 * 1000, // 5 minutes
+    cacheTime: 10 * 60 * 1000, // 10 minutes
+    refetchInterval: 30000, // Refetch every 30 seconds
+    refetchOnWindowFocus: false,
+  }
+);
+```
+
+### Invalidating Queries
+
+After a mutation, invalidate related queries to trigger refetch:
+
+```tsx
+import { useQueryClient } from '@tanstack/react-query';
+
+function DeleteUserButton({ userId }: { userId: string }) {
+  const queryClient = useQueryClient();
+  
+  const mutation = hooks.deleteUser.useMutation({
+    onSuccess: () => {
+      // Invalidate all queries that start with 'listUsers'
+      queryClient.invalidateQueries({ queryKey: ['listUsers'] });
+      
+      // Or invalidate specific query
+      queryClient.invalidateQueries({ 
+        queryKey: ['getUser', { params: { id: userId } }] 
+      });
+    },
+  });
+
+  return (
+    <button onClick={() => mutation.mutate({ params: { id: userId } })}>
+      Delete User
+    </button>
+  );
+}
+```
+
+### Optimistic Updates
+
+Update the UI immediately before the server responds:
+
+```tsx
+const mutation = hooks.updateUser.useMutation({
+  onMutate: async (variables) => {
+    // Cancel outgoing refetches
+    await queryClient.cancelQueries({ queryKey: ['getUser'] });
+
+    // Snapshot previous value
+    const previousUser = queryClient.getQueryData(['getUser', { params: { id: userId } }]);
+
+    // Optimistically update
+    queryClient.setQueryData(['getUser', { params: { id: userId } }], (old) => ({
+      ...old,
+      data: { ...old.data, ...variables.body }
+    }));
+
+    return { previousUser };
+  },
+  onError: (err, variables, context) => {
+    // Rollback on error
+    if (context?.previousUser) {
+      queryClient.setQueryData(
+        ['getUser', { params: { id: userId } }],
+        context.previousUser
+      );
+    }
+  },
+  onSettled: () => {
+    queryClient.invalidateQueries({ queryKey: ['getUser'] });
+  },
+});
+```
+
+### Dependent Queries
+
+Enable queries only when conditions are met:
+
+```tsx
+function UserPosts({ userId }: { userId: string | null }) {
+  const { data } = hooks.getUserPosts.useQuery(
+    { params: { userId: userId! } },
+    {
+      enabled: !!userId, // Only fetch when userId is available
+    }
+  );
+
+  // ...
+}
+```
+
+### Parallel Queries
+
+Fetch multiple queries at once:
+
+```tsx
+function Dashboard() {
+  const users = hooks.listUsers.useQuery({ query: {} });
+  const stats = hooks.getStats.useQuery({});
+  const settings = hooks.getSettings.useQuery({});
+
+  if (users.isLoading || stats.isLoading || settings.isLoading) {
+    return <div>Loading...</div>;
+  }
+
+  // All queries are fetched in parallel
+  return <div>Dashboard with {users.data.data.total} users</div>;
+}
+```
+
+## TypeScript Tips
+
+### Inferring Types
+
+Extract types from your hooks:
+
+```tsx
+import type { EndpointResponse } from '@richie-rpc/client';
+import type { contract } from './contract';
+
+// Get the response type for an endpoint
+type UserListResponse = EndpointResponse<typeof contract.listUsers>;
+
+// Or extract from hook result
+type UserData = Awaited<ReturnType<typeof hooks.listUsers.useQuery>>['data'];
+```
+
+### Type-Safe Query Keys
+
+Create a helper for consistent query keys:
+
+```tsx
+const queryKeys = {
+  listUsers: (query: { limit?: string; offset?: string }) => 
+    ['listUsers', { query }] as const,
+  getUser: (id: string) => 
+    ['getUser', { params: { id } }] as const,
+};
+
+// Use in invalidation
+queryClient.invalidateQueries({ queryKey: queryKeys.listUsers({}) });
+```
+
+## Best Practices
+
+1. **Create hooks once**: Create the hooks object at the module level, not inside components
+2. **Use Suspense for loading states**: Cleaner than manual loading state management
+3. **Invalidate related queries**: After mutations, invalidate queries that may be affected
+4. **Set appropriate staleTime**: Reduce unnecessary refetches by setting staleTime
+5. **Handle errors with Error Boundaries**: Use React Error Boundaries with Suspense queries
+
+## Examples
+
+See the `packages/demo` directory for complete working examples.
+
+## License
+
+MIT
+

package/dist/cjs/index.cjs

@@ -0,0 +1,74 @@
+// @bun @bun-cjs
+(function(exports, require, module, __filename, __dirname) {var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
+// packages/react-query/index.ts
+var exports_react_query = {};
+__export(exports_react_query, {
+  createHooks: () => createHooks
+});
+module.exports = __toCommonJS(exports_react_query);
+var import_react_query = require("@tanstack/react-query");
+function createHooks(client, contract) {
+  const hooks = {};
+  for (const [name, endpoint] of Object.entries(contract)) {
+    const method = endpoint.method;
+    const clientMethod = client[name];
+    if (method === "GET" || method === "HEAD") {
+      hooks[name] = {
+        useQuery: (options, queryOptions) => {
+          return import_react_query.useQuery({
+            queryKey: [name, options],
+            queryFn: () => clientMethod(options),
+            ...queryOptions
+          });
+        },
+        useSuspenseQuery: (options, queryOptions) => {
+          return import_react_query.useSuspenseQuery({
+            queryKey: [name, options],
+            queryFn: () => clientMethod(options),
+            ...queryOptions
+          });
+        }
+      };
+    } else {
+      hooks[name] = {
+        useMutation: (mutationOptions) => {
+          return import_react_query.useMutation({
+            mutationFn: (options) => clientMethod(options),
+            ...mutationOptions
+          });
+        }
+      };
+    }
+  }
+  return hooks;
+}
+})
+
+//# debugId=CC8C1467648847F064756E2164756E21

package/dist/cjs/index.cjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../index.ts"],
+  "sourcesContent": [
+    "import type {\n  Client,\n  ClientMethod,\n  EndpointRequestOptions,\n  EndpointResponse,\n} from '@richie-rpc/client';\nimport type { Contract, EndpointDefinition } from '@richie-rpc/core';\nimport {\n  type UseMutationOptions,\n  type UseMutationResult,\n  type UseQueryOptions,\n  type UseQueryResult,\n  type UseSuspenseQueryOptions,\n  type UseSuspenseQueryResult,\n  useMutation,\n  useQuery,\n  useSuspenseQuery,\n} from '@tanstack/react-query';\n\n// HTTP methods that should use query hooks (read operations)\ntype QueryMethods = 'GET' | 'HEAD';\n\n// HTTP methods that should use mutation hooks (write operations)\ntype MutationMethods = 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';\n\n/**\n * Hook wrapper for query endpoints (GET, HEAD)\n * Provides useQuery and useSuspenseQuery methods\n */\nexport type QueryHook<T extends EndpointDefinition> = {\n  /**\n   * Standard query hook that returns loading states\n   */\n  useQuery: (\n    options: EndpointRequestOptions<T>,\n    queryOptions?: Omit<UseQueryOptions<EndpointResponse<T>, Error>, 'queryKey' | 'queryFn'>,\n  ) => UseQueryResult<EndpointResponse<T>, Error>;\n\n  /**\n   * Suspense-enabled query hook that throws promises for React Suspense\n   */\n  useSuspenseQuery: (\n    options: EndpointRequestOptions<T>,\n    queryOptions?: Omit<\n      UseSuspenseQueryOptions<EndpointResponse<T>, Error>,\n      'queryKey' | 'queryFn'\n    >,\n  ) => UseSuspenseQueryResult<EndpointResponse<T>, Error>;\n};\n\n/**\n * Hook wrapper for mutation endpoints (POST, PUT, PATCH, DELETE)\n * Provides useMutation method\n */\nexport type MutationHook<T extends EndpointDefinition> = {\n  /**\n   * Mutation hook for write operations\n   */\n  useMutation: (\n    mutationOptions?: Omit<\n      UseMutationOptions<EndpointResponse<T>, Error, EndpointRequestOptions<T>>,\n      'mutationFn'\n    >,\n  ) => UseMutationResult<EndpointResponse<T>, Error, EndpointRequestOptions<T>>;\n};\n\n/**\n * Conditionally apply hook type based on HTTP method\n */\nexport type EndpointHook<T extends EndpointDefinition> = T['method'] extends QueryMethods\n  ? QueryHook<T>\n  : T['method'] extends MutationMethods\n    ? MutationHook<T>\n    : never;\n\n/**\n * Complete hooks object for a contract\n * Each endpoint gets appropriate hooks based on its HTTP method\n */\nexport type Hooks<T extends Contract> = {\n  [K in keyof T]: EndpointHook<T[K]>;\n};\n\n/**\n * Create typed React hooks for all endpoints in a contract\n *\n * Query endpoints (GET, HEAD) get useQuery and useSuspenseQuery methods\n * Mutation endpoints (POST, PUT, PATCH, DELETE) get useMutation method\n *\n * @param client - The typed client created with createClient()\n * @param contract - The contract definition\n * @returns Hooks object with methods for each endpoint\n *\n * @example\n * ```tsx\n * const client = createClient(contract, { baseUrl: 'http://localhost:3000' });\n * const hooks = createHooks(client, contract);\n *\n * // In a component - Query\n * function UserList() {\n *   const { data, isLoading } = hooks.listUsers.useQuery({\n *     query: { limit: \"10\" }\n *   });\n *   // ...\n * }\n *\n * // In a component - Mutation\n * function CreateUser() {\n *   const mutation = hooks.createUser.useMutation();\n *   return (\n *     <button onClick={() => mutation.mutate({\n *       body: { name: \"Alice\", email: \"alice@example.com\" }\n *     })}>\n *       Create User\n *     </button>\n *   );\n * }\n * ```\n */\nexport function createHooks<T extends Contract>(client: Client<T>, contract: T): Hooks<T> {\n  const hooks: Record<string, unknown> = {};\n\n  for (const [name, endpoint] of Object.entries(contract)) {\n    const method = endpoint.method;\n    const clientMethod = client[name as keyof T] as unknown as ClientMethod<EndpointDefinition>;\n\n    if (method === 'GET' || method === 'HEAD') {\n      // Create query hooks for read operations\n      hooks[name] = {\n        useQuery: (\n          options: EndpointRequestOptions<EndpointDefinition>,\n          queryOptions?: Omit<\n            UseQueryOptions<EndpointResponse<EndpointDefinition>, Error>,\n            'queryKey' | 'queryFn'\n          >,\n        ) => {\n          return useQuery({\n            queryKey: [name, options],\n            queryFn: () => clientMethod(options),\n            ...queryOptions,\n          });\n        },\n        useSuspenseQuery: (\n          options: EndpointRequestOptions<EndpointDefinition>,\n          queryOptions?: Omit<\n            UseSuspenseQueryOptions<EndpointResponse<EndpointDefinition>, Error>,\n            'queryKey' | 'queryFn'\n          >,\n        ) => {\n          return useSuspenseQuery({\n            queryKey: [name, options],\n            queryFn: () => clientMethod(options),\n            ...queryOptions,\n          });\n        },\n      };\n    } else {\n      // Create mutation hooks for write operations\n      hooks[name] = {\n        useMutation: (\n          mutationOptions?: Omit<\n            UseMutationOptions<\n              EndpointResponse<EndpointDefinition>,\n              Error,\n              EndpointRequestOptions<EndpointDefinition>\n            >,\n            'mutationFn'\n          >,\n        ) => {\n          return useMutation({\n            mutationFn: (options: EndpointRequestOptions<EndpointDefinition>) =>\n              clientMethod(options),\n            ...mutationOptions,\n          });\n        },\n      };\n    }\n  }\n\n  return hooks as Hooks<T>;\n}\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiBO,IAVP;AAgHO,SAAS,WAA+B,CAAC,QAAmB,UAAuB;AAAA,EACxF,MAAM,QAAiC,CAAC;AAAA,EAExC,YAAY,MAAM,aAAa,OAAO,QAAQ,QAAQ,GAAG;AAAA,IACvD,MAAM,SAAS,SAAS;AAAA,IACxB,MAAM,eAAe,OAAO;AAAA,IAE5B,IAAI,WAAW,SAAS,WAAW,QAAQ;AAAA,MAEzC,MAAM,QAAQ;AAAA,QACZ,UAAU,CACR,SACA,iBAIG;AAAA,UACH,OAAO,4BAAS;AAAA,YACd,UAAU,CAAC,MAAM,OAAO;AAAA,YACxB,SAAS,MAAM,aAAa,OAAO;AAAA,eAChC;AAAA,UACL,CAAC;AAAA;AAAA,QAEH,kBAAkB,CAChB,SACA,iBAIG;AAAA,UACH,OAAO,oCAAiB;AAAA,YACtB,UAAU,CAAC,MAAM,OAAO;AAAA,YACxB,SAAS,MAAM,aAAa,OAAO;AAAA,eAChC;AAAA,UACL,CAAC;AAAA;AAAA,MAEL;AAAA,IACF,EAAO;AAAA,MAEL,MAAM,QAAQ;AAAA,QACZ,aAAa,CACX,oBAQG;AAAA,UACH,OAAO,+BAAY;AAAA,YACjB,YAAY,CAAC,YACX,aAAa,OAAO;AAAA,eACnB;AAAA,UACL,CAAC;AAAA;AAAA,MAEL;AAAA;AAAA,EAEJ;AAAA,EAEA,OAAO;AAAA;",
+  "debugId": "CC8C1467648847F064756E2164756E21",
+  "names": []
+}

package/dist/cjs/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@richie-rpc/react-query",
+  "version": "1.0.0",
+  "type": "commonjs"
+}

package/dist/mjs/index.mjs

@@ -0,0 +1,47 @@
+// @bun
+// packages/react-query/index.ts
+import {
+  useMutation,
+  useQuery,
+  useSuspenseQuery
+} from "@tanstack/react-query";
+function createHooks(client, contract) {
+  const hooks = {};
+  for (const [name, endpoint] of Object.entries(contract)) {
+    const method = endpoint.method;
+    const clientMethod = client[name];
+    if (method === "GET" || method === "HEAD") {
+      hooks[name] = {
+        useQuery: (options, queryOptions) => {
+          return useQuery({
+            queryKey: [name, options],
+            queryFn: () => clientMethod(options),
+            ...queryOptions
+          });
+        },
+        useSuspenseQuery: (options, queryOptions) => {
+          return useSuspenseQuery({
+            queryKey: [name, options],
+            queryFn: () => clientMethod(options),
+            ...queryOptions
+          });
+        }
+      };
+    } else {
+      hooks[name] = {
+        useMutation: (mutationOptions) => {
+          return useMutation({
+            mutationFn: (options) => clientMethod(options),
+            ...mutationOptions
+          });
+        }
+      };
+    }
+  }
+  return hooks;
+}
+export {
+  createHooks
+};
+
+//# debugId=579950B8ADA2DE1A64756E2164756E21

package/dist/mjs/index.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../index.ts"],
+  "sourcesContent": [
+    "import type {\n  Client,\n  ClientMethod,\n  EndpointRequestOptions,\n  EndpointResponse,\n} from '@richie-rpc/client';\nimport type { Contract, EndpointDefinition } from '@richie-rpc/core';\nimport {\n  type UseMutationOptions,\n  type UseMutationResult,\n  type UseQueryOptions,\n  type UseQueryResult,\n  type UseSuspenseQueryOptions,\n  type UseSuspenseQueryResult,\n  useMutation,\n  useQuery,\n  useSuspenseQuery,\n} from '@tanstack/react-query';\n\n// HTTP methods that should use query hooks (read operations)\ntype QueryMethods = 'GET' | 'HEAD';\n\n// HTTP methods that should use mutation hooks (write operations)\ntype MutationMethods = 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';\n\n/**\n * Hook wrapper for query endpoints (GET, HEAD)\n * Provides useQuery and useSuspenseQuery methods\n */\nexport type QueryHook<T extends EndpointDefinition> = {\n  /**\n   * Standard query hook that returns loading states\n   */\n  useQuery: (\n    options: EndpointRequestOptions<T>,\n    queryOptions?: Omit<UseQueryOptions<EndpointResponse<T>, Error>, 'queryKey' | 'queryFn'>,\n  ) => UseQueryResult<EndpointResponse<T>, Error>;\n\n  /**\n   * Suspense-enabled query hook that throws promises for React Suspense\n   */\n  useSuspenseQuery: (\n    options: EndpointRequestOptions<T>,\n    queryOptions?: Omit<\n      UseSuspenseQueryOptions<EndpointResponse<T>, Error>,\n      'queryKey' | 'queryFn'\n    >,\n  ) => UseSuspenseQueryResult<EndpointResponse<T>, Error>;\n};\n\n/**\n * Hook wrapper for mutation endpoints (POST, PUT, PATCH, DELETE)\n * Provides useMutation method\n */\nexport type MutationHook<T extends EndpointDefinition> = {\n  /**\n   * Mutation hook for write operations\n   */\n  useMutation: (\n    mutationOptions?: Omit<\n      UseMutationOptions<EndpointResponse<T>, Error, EndpointRequestOptions<T>>,\n      'mutationFn'\n    >,\n  ) => UseMutationResult<EndpointResponse<T>, Error, EndpointRequestOptions<T>>;\n};\n\n/**\n * Conditionally apply hook type based on HTTP method\n */\nexport type EndpointHook<T extends EndpointDefinition> = T['method'] extends QueryMethods\n  ? QueryHook<T>\n  : T['method'] extends MutationMethods\n    ? MutationHook<T>\n    : never;\n\n/**\n * Complete hooks object for a contract\n * Each endpoint gets appropriate hooks based on its HTTP method\n */\nexport type Hooks<T extends Contract> = {\n  [K in keyof T]: EndpointHook<T[K]>;\n};\n\n/**\n * Create typed React hooks for all endpoints in a contract\n *\n * Query endpoints (GET, HEAD) get useQuery and useSuspenseQuery methods\n * Mutation endpoints (POST, PUT, PATCH, DELETE) get useMutation method\n *\n * @param client - The typed client created with createClient()\n * @param contract - The contract definition\n * @returns Hooks object with methods for each endpoint\n *\n * @example\n * ```tsx\n * const client = createClient(contract, { baseUrl: 'http://localhost:3000' });\n * const hooks = createHooks(client, contract);\n *\n * // In a component - Query\n * function UserList() {\n *   const { data, isLoading } = hooks.listUsers.useQuery({\n *     query: { limit: \"10\" }\n *   });\n *   // ...\n * }\n *\n * // In a component - Mutation\n * function CreateUser() {\n *   const mutation = hooks.createUser.useMutation();\n *   return (\n *     <button onClick={() => mutation.mutate({\n *       body: { name: \"Alice\", email: \"alice@example.com\" }\n *     })}>\n *       Create User\n *     </button>\n *   );\n * }\n * ```\n */\nexport function createHooks<T extends Contract>(client: Client<T>, contract: T): Hooks<T> {\n  const hooks: Record<string, unknown> = {};\n\n  for (const [name, endpoint] of Object.entries(contract)) {\n    const method = endpoint.method;\n    const clientMethod = client[name as keyof T] as unknown as ClientMethod<EndpointDefinition>;\n\n    if (method === 'GET' || method === 'HEAD') {\n      // Create query hooks for read operations\n      hooks[name] = {\n        useQuery: (\n          options: EndpointRequestOptions<EndpointDefinition>,\n          queryOptions?: Omit<\n            UseQueryOptions<EndpointResponse<EndpointDefinition>, Error>,\n            'queryKey' | 'queryFn'\n          >,\n        ) => {\n          return useQuery({\n            queryKey: [name, options],\n            queryFn: () => clientMethod(options),\n            ...queryOptions,\n          });\n        },\n        useSuspenseQuery: (\n          options: EndpointRequestOptions<EndpointDefinition>,\n          queryOptions?: Omit<\n            UseSuspenseQueryOptions<EndpointResponse<EndpointDefinition>, Error>,\n            'queryKey' | 'queryFn'\n          >,\n        ) => {\n          return useSuspenseQuery({\n            queryKey: [name, options],\n            queryFn: () => clientMethod(options),\n            ...queryOptions,\n          });\n        },\n      };\n    } else {\n      // Create mutation hooks for write operations\n      hooks[name] = {\n        useMutation: (\n          mutationOptions?: Omit<\n            UseMutationOptions<\n              EndpointResponse<EndpointDefinition>,\n              Error,\n              EndpointRequestOptions<EndpointDefinition>\n            >,\n            'mutationFn'\n          >,\n        ) => {\n          return useMutation({\n            mutationFn: (options: EndpointRequestOptions<EndpointDefinition>) =>\n              clientMethod(options),\n            ...mutationOptions,\n          });\n        },\n      };\n    }\n  }\n\n  return hooks as Hooks<T>;\n}\n"
+  ],
+  "mappings": ";;AAOA;AAAA;AAAA;AAAA;AAAA;AAgHO,SAAS,WAA+B,CAAC,QAAmB,UAAuB;AAAA,EACxF,MAAM,QAAiC,CAAC;AAAA,EAExC,YAAY,MAAM,aAAa,OAAO,QAAQ,QAAQ,GAAG;AAAA,IACvD,MAAM,SAAS,SAAS;AAAA,IACxB,MAAM,eAAe,OAAO;AAAA,IAE5B,IAAI,WAAW,SAAS,WAAW,QAAQ;AAAA,MAEzC,MAAM,QAAQ;AAAA,QACZ,UAAU,CACR,SACA,iBAIG;AAAA,UACH,OAAO,SAAS;AAAA,YACd,UAAU,CAAC,MAAM,OAAO;AAAA,YACxB,SAAS,MAAM,aAAa,OAAO;AAAA,eAChC;AAAA,UACL,CAAC;AAAA;AAAA,QAEH,kBAAkB,CAChB,SACA,iBAIG;AAAA,UACH,OAAO,iBAAiB;AAAA,YACtB,UAAU,CAAC,MAAM,OAAO;AAAA,YACxB,SAAS,MAAM,aAAa,OAAO;AAAA,eAChC;AAAA,UACL,CAAC;AAAA;AAAA,MAEL;AAAA,IACF,EAAO;AAAA,MAEL,MAAM,QAAQ;AAAA,QACZ,aAAa,CACX,oBAQG;AAAA,UACH,OAAO,YAAY;AAAA,YACjB,YAAY,CAAC,YACX,aAAa,OAAO;AAAA,eACnB;AAAA,UACL,CAAC;AAAA;AAAA,MAEL;AAAA;AAAA,EAEJ;AAAA,EAEA,OAAO;AAAA;",
+  "debugId": "579950B8ADA2DE1A64756E2164756E21",
+  "names": []
+}

package/dist/mjs/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@richie-rpc/react-query",
+  "version": "1.0.0",
+  "type": "module"
+}

package/dist/types/index.d.ts

@@ -0,0 +1,78 @@
+import type { Client, EndpointRequestOptions, EndpointResponse } from '@richie-rpc/client';
+import type { Contract, EndpointDefinition } from '@richie-rpc/core';
+import { type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseQueryResult, type UseSuspenseQueryOptions, type UseSuspenseQueryResult } from '@tanstack/react-query';
+type QueryMethods = 'GET' | 'HEAD';
+type MutationMethods = 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
+/**
+ * Hook wrapper for query endpoints (GET, HEAD)
+ * Provides useQuery and useSuspenseQuery methods
+ */
+export type QueryHook<T extends EndpointDefinition> = {
+    /**
+     * Standard query hook that returns loading states
+     */
+    useQuery: (options: EndpointRequestOptions<T>, queryOptions?: Omit<UseQueryOptions<EndpointResponse<T>, Error>, 'queryKey' | 'queryFn'>) => UseQueryResult<EndpointResponse<T>, Error>;
+    /**
+     * Suspense-enabled query hook that throws promises for React Suspense
+     */
+    useSuspenseQuery: (options: EndpointRequestOptions<T>, queryOptions?: Omit<UseSuspenseQueryOptions<EndpointResponse<T>, Error>, 'queryKey' | 'queryFn'>) => UseSuspenseQueryResult<EndpointResponse<T>, Error>;
+};
+/**
+ * Hook wrapper for mutation endpoints (POST, PUT, PATCH, DELETE)
+ * Provides useMutation method
+ */
+export type MutationHook<T extends EndpointDefinition> = {
+    /**
+     * Mutation hook for write operations
+     */
+    useMutation: (mutationOptions?: Omit<UseMutationOptions<EndpointResponse<T>, Error, EndpointRequestOptions<T>>, 'mutationFn'>) => UseMutationResult<EndpointResponse<T>, Error, EndpointRequestOptions<T>>;
+};
+/**
+ * Conditionally apply hook type based on HTTP method
+ */
+export type EndpointHook<T extends EndpointDefinition> = T['method'] extends QueryMethods ? QueryHook<T> : T['method'] extends MutationMethods ? MutationHook<T> : never;
+/**
+ * Complete hooks object for a contract
+ * Each endpoint gets appropriate hooks based on its HTTP method
+ */
+export type Hooks<T extends Contract> = {
+    [K in keyof T]: EndpointHook<T[K]>;
+};
+/**
+ * Create typed React hooks for all endpoints in a contract
+ *
+ * Query endpoints (GET, HEAD) get useQuery and useSuspenseQuery methods
+ * Mutation endpoints (POST, PUT, PATCH, DELETE) get useMutation method
+ *
+ * @param client - The typed client created with createClient()
+ * @param contract - The contract definition
+ * @returns Hooks object with methods for each endpoint
+ *
+ * @example
+ * ```tsx
+ * const client = createClient(contract, { baseUrl: 'http://localhost:3000' });
+ * const hooks = createHooks(client, contract);
+ *
+ * // In a component - Query
+ * function UserList() {
+ *   const { data, isLoading } = hooks.listUsers.useQuery({
+ *     query: { limit: "10" }
+ *   });
+ *   // ...
+ * }
+ *
+ * // In a component - Mutation
+ * function CreateUser() {
+ *   const mutation = hooks.createUser.useMutation();
+ *   return (
+ *     <button onClick={() => mutation.mutate({
+ *       body: { name: "Alice", email: "alice@example.com" }
+ *     })}>
+ *       Create User
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function createHooks<T extends Contract>(client: Client<T>, contract: T): Hooks<T>;
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@richie-rpc/react-query",
+  "version": "1.0.0",
+  "main": "./dist/cjs/index.cjs",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "require": "./dist/cjs/index.cjs",
+      "import": "./dist/mjs/index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "@richie-rpc/client": "^1.2.0",
+    "@richie-rpc/core": "^1.2.0",
+    "@tanstack/react-query": "^5.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "typescript": "^5",
+    "zod": "^4.1.12"
+  },
+  "author": "Richie <oss@ricsam.dev>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ricsam/richie-rpc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ricsam/richie-rpc/issues"
+  },
+  "homepage": "https://github.com/ricsam/richie-rpc#readme",
+  "keywords": [
+    "typescript",
+    "bun",
+    "zod",
+    "api",
+    "contract",
+    "rpc",
+    "rest",
+    "openapi",
+    "type-safe"
+  ],
+  "description": "A TypeScript-first, type-safe API contract library for Bun with Zod validation",
+  "module": "./dist/mjs/index.mjs",
+  "types": "./dist/types/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}