@srpc.org/react-query 0.20.3

package/dist/context.js

@@ -0,0 +1,344 @@
+'use client';
+import { jsx } from 'react/jsx-runtime';
+import { createContext, useContext, useMemo } from 'react';
+import { createRecursiveProxy } from '@srpc/core/shared';
+import { queryOptions, mutationOptions } from '@tanstack/react-query';
+
+/**
+ * Transforms an SRPC client into React Query-compatible query and mutation options.
+ *
+ * This function takes an SRPC client and returns a proxy object where each procedure
+ * has `.queryOptions()` and `.mutationOptions()` methods that generate options for
+ * React Query's `useQuery` and `useMutation` hooks.
+ *
+ * The proxy automatically:
+ * - Generates query keys based on the procedure path and arguments
+ * - Wraps procedure calls in query/mutation functions
+ * - Preserves type safety throughout the chain
+ *
+ * @template TRouter - The SRPC router type
+ * @template TRoutes - The routes type (inferred automatically)
+ *
+ * @param options - Configuration object
+ * @param options.client - The SRPC client created with `createSRPCClient`
+ *
+ * @returns Decorated procedures with `.queryOptions()` and `.mutationOptions()` methods
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createSRPCClient } from "@srpc/core/client";
+ * import { createSRPCQueryOptions } from "@srpc.org/react-query";
+ * import { useQuery, useMutation } from "@tanstack/react-query";
+ * import type { AppRouter } from "./server";
+ *
+ * const client = createSRPCClient<AppRouter>({ endpoint: "/api" });
+ * const srpc = createSRPCQueryOptions({ client });
+ *
+ * function UserProfile({ userId }: { userId: number }) {
+ *   // Use with useQuery
+ *   const { data, isLoading } = useQuery(
+ *     srpc.users.getUser.queryOptions(userId)
+ *   );
+ *
+ *   return <div>{data?.name}</div>;
+ * }
+ * ```
+ *
+ * @example With mutations
+ * ```typescript
+ * function CreateUserForm() {
+ *   const createUser = useMutation(srpc.users.createUser.mutationOptions());
+ *
+ *   const handleSubmit = (data: UserData) => {
+ *     createUser.mutate(data);
+ *   };
+ *
+ *   return <form onSubmit={handleSubmit}>...</form>;
+ * }
+ * ```
+ *
+ * @example With query options
+ * ```typescript
+ * function UserList() {
+ *   const { data } = useQuery({
+ *     ...srpc.users.list.queryOptions(),
+ *     staleTime: 5000,
+ *     refetchInterval: 10000,
+ *   });
+ *
+ *   return <ul>{data?.map(user => <li key={user.id}>{user.name}</li>)}</ul>;
+ * }
+ * ```
+ *
+ * @example Nested routers
+ * ```typescript
+ * // Works with deeply nested routers
+ * const userQuery = useQuery(srpc.users.getUser.queryOptions(1));
+ * const adminQuery = useQuery(srpc.users.admin.getStats.queryOptions());
+ * const draftQuery = useQuery(srpc.posts.drafts.list.queryOptions());
+ * ```
+ */ function createSRPCQueryOptions({ client }) {
+    return createRecursiveProxy(({ path, args })=>{
+        const lastPath = path[path.length - 1];
+        const pathWithoutTarget = path.slice(0, -1);
+        const procedure = pathWithoutTarget.reduce((acc, key)=>acc[key], client);
+        if (typeof procedure !== "function") {
+            throw new Error(`Procedure at path ${pathWithoutTarget.join(".")} is not a function`);
+        }
+        if (lastPath === "queryOptions") {
+            return queryOptions({
+                queryKey: [
+                    ...pathWithoutTarget,
+                    args
+                ],
+                queryFn: ()=>procedure(...args)
+            });
+        }
+        if (lastPath === "mutationOptions") {
+            return mutationOptions({
+                mutationKey: [
+                    ...pathWithoutTarget,
+                    args
+                ],
+                mutationFn: (variables)=>procedure(...variables)
+            });
+        }
+        throw new Error(`Unknown target path at: ${path.join(".")}`);
+    });
+}
+
+/**
+ * @module
+ *
+ * React Context integration for SRPC with React Query.
+ *
+ * This module provides React Context-based access to SRPC procedures with React Query
+ * integration. It creates a Provider component and hooks for accessing RPC functionality
+ * throughout your React application.
+ *
+ * @example Complete setup
+ * ```typescript
+ * import { createSRPCClient } from "@srpc/core/client";
+ * import { createSRPCContext } from "@srpc/react-query/context";
+ * import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+ * import type { AppRouter } from "./server";
+ *
+ * // Create client
+ * const client = createSRPCClient<AppRouter>({ endpoint: "/api" });
+ *
+ * // Create context and hooks
+ * export const { SRPCProvider, useSRPC, useSRPCClient } =
+ *   createSRPCContext<AppRouter>();
+ *
+ * // Setup in app
+ * function App() {
+ *   const [queryClient] = useState(() => new QueryClient());
+ *
+ *   return (
+ *     <QueryClientProvider client={queryClient}>
+ *       <SRPCProvider client={client}>
+ *         <YourApp />
+ *       </SRPCProvider>
+ *     </QueryClientProvider>
+ *   );
+ * }
+ *
+ * // Use in components
+ * function UserProfile() {
+ *   const srpc = useSRPC();
+ *   const { data } = useQuery(srpc.users.getUser.queryOptions(1));
+ *   return <div>{data?.name}</div>;
+ * }
+ * ```
+ */ 
+/**
+ * Factory function to create SRPC React Context, Provider, and hooks.
+ *
+ * Creates a type-safe React Context system for accessing SRPC procedures throughout
+ * your React application. The returned hooks provide access to both React Query
+ * integrated procedures and the raw RPC client.
+ *
+ * @template TRouter - The SRPC router type from your server
+ *
+ * @returns Object containing:
+ * - `SRPCContext` - React Context (rarely needed directly)
+ * - `SRPCProvider` - Provider component that accepts `client` prop
+ * - `useSRPC()` - Hook returning decorated procedures with `.queryOptions()` and `.mutationOptions()`
+ * - `useSRPCClient()` - Hook returning the raw SRPC client for direct calls
+ *
+ * @example Basic setup
+ * ```typescript
+ * import { createSRPCClient } from "@srpc/core/client";
+ * import { createSRPCContext } from "@srpc.org/react-query";
+ * import type { AppRouter } from "./server";
+ *
+ * // Create client
+ * const rpcClient = createSRPCClient<AppRouter>({ endpoint: "/api" });
+ *
+ * // Create context utilities
+ * export const { SRPCProvider, useSRPC, useSRPCClient } =
+ *   createSRPCContext<AppRouter>();
+ *
+ * // In root component
+ * function App() {
+ *   return (
+ *     <QueryClientProvider client={queryClient}>
+ *       <SRPCProvider client={rpcClient}>
+ *         <YourApp />
+ *       </SRPCProvider>
+ *     </QueryClientProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example Using in components with queries
+ * ```typescript
+ * import { useSRPC } from "./rpc";
+ * import { useQuery } from "@tanstack/react-query";
+ *
+ * function UserProfile({ userId }: { userId: number }) {
+ *   const srpc = useSRPC();
+ *
+ *   const { data, isLoading, error } = useQuery(
+ *     srpc.users.getUser.queryOptions(userId)
+ *   );
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       <h2>{data.name}</h2>
+ *       <p>{data.email}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Using in components with mutations
+ * ```typescript
+ * import { useSRPC } from "./rpc";
+ * import { useMutation, useQueryClient } from "@tanstack/react-query";
+ *
+ * function CreateUserForm() {
+ *   const srpc = useSRPC();
+ *   const queryClient = useQueryClient();
+ *
+ *   const createUser = useMutation({
+ *     ...srpc.users.createUser.mutationOptions(),
+ *     onSuccess: () => {
+ *       queryClient.invalidateQueries({ queryKey: ["users"] });
+ *     },
+ *   });
+ *
+ *   return (
+ *     <form onSubmit={(e) => {
+ *       e.preventDefault();
+ *       const formData = new FormData(e.currentTarget);
+ *       createUser.mutate({
+ *         name: formData.get("name") as string,
+ *         email: formData.get("email") as string,
+ *       });
+ *     }}>
+ *       <input name="name" required />
+ *       <input name="email" type="email" required />
+ *       <button disabled={createUser.isPending}>Create User</button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @example Using raw client for direct calls
+ * ```typescript
+ * import { useSRPCClient } from "./rpc";
+ *
+ * function DirectCallExample() {
+ *   const client = useSRPCClient();
+ *
+ *   const handleClick = async () => {
+ *     // Direct RPC call without React Query
+ *     const result = await client.sayHello("World");
+ *     console.log(result); // "Hello World!"
+ *   };
+ *
+ *   return <button onClick={handleClick}>Call RPC</button>;
+ * }
+ * ```
+ *
+ * @example Nested routers
+ * ```typescript
+ * function NestedRouterExample() {
+ *   const srpc = useSRPC();
+ *
+ *   // All nested paths are fully typed
+ *   const userQuery = useQuery(srpc.users.getUser.queryOptions(1));
+ *   const adminQuery = useQuery(srpc.users.admin.getStats.queryOptions());
+ *   const postQuery = useQuery(srpc.posts.drafts.list.queryOptions());
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ *
+ * @example With Next.js App Router
+ * ```typescript
+ * // app/providers.tsx
+ * "use client";
+ *
+ * import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+ * import { rpcClient, SRPCProvider } from "@/lib/rpc";
+ * import { useState } from "react";
+ *
+ * export function Providers({ children }: { children: React.ReactNode }) {
+ *   const [queryClient] = useState(() => new QueryClient());
+ *
+ *   return (
+ *     <QueryClientProvider client={queryClient}>
+ *       <SRPCProvider client={rpcClient}>
+ *         {children}
+ *       </SRPCProvider>
+ *     </QueryClientProvider>
+ *   );
+ * }
+ * ```
+ */ function createSRPCContext() {
+    // biome-ignore lint/style/noNonNullAssertion: <Asserting non null for context>
+    const SRPCContext = /*#__PURE__*/ createContext(null);
+    function SRPCProvider({ children, client }) {
+        const srpc = useMemo(()=>{
+            return createSRPCQueryOptions({
+                client: client
+            });
+        }, [
+            client
+        ]);
+        return /*#__PURE__*/ jsx(SRPCContext.Provider, {
+            value: {
+                client: client,
+                srpc
+            },
+            children: children
+        });
+    }
+    function useSRPC() {
+        const ctx = useContext(SRPCContext);
+        if (!ctx) {
+            throw new Error("useSRPC must be used within a SRPCProvider");
+        }
+        return ctx.srpc;
+    }
+    function useSRPCClient() {
+        const ctx = useContext(SRPCContext);
+        if (!ctx) {
+            throw new Error("useSRPCClient must be used within a SRPCProvider");
+        }
+        return ctx.client;
+    }
+    return {
+        SRPCContext,
+        SRPCProvider,
+        useSRPC,
+        useSRPCClient
+    };
+}
+
+export { createSRPCContext };

package/dist/index.d.ts

@@ -0,0 +1,205 @@
+import { SRPC, AnySRPC } from '@srpc/core/server';
+import { ClientProcedure, AnyRoutes, AnyProcedure, DecoratedProcedureRecord } from '@srpc/core/shared';
+import { UseQueryOptions, UseMutationOptions } from '@tanstack/react-query';
+export { SRPCContextFactory, SRPCContextValue, createSRPCContext } from './context.js';
+
+/**
+ * @module
+ *
+ * React Query integration for SRPC - Type-safe RPC with automatic query and mutation options.
+ *
+ * This module provides the core functionality for integrating SRPC with TanStack React Query.
+ * It transforms SRPC client procedures into React Query-compatible options objects that can
+ * be used with `useQuery` and `useMutation` hooks.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createSRPCClient } from "@srpc/core/client";
+ * import { createSRPCQueryOptions } from "@srpc.org/react-query";
+ * import { useQuery } from "@tanstack/react-query";
+ * import type { AppRouter } from "./server";
+ *
+ * // Create client
+ * const client = createSRPCClient<AppRouter>({ endpoint: "/api" });
+ *
+ * // Transform to React Query options
+ * const srpc = createSRPCQueryOptions({ client });
+ *
+ * // Use in components
+ * function MyComponent() {
+ *   const { data } = useQuery(srpc.users.getUser.queryOptions(1));
+ *   return <div>{data?.name}</div>;
+ * }
+ * ```
+ *
+ * @example With React Context
+ * ```typescript
+ * import { createSRPCContext } from "@srpc.org/react-query";
+ *
+ * // Create context and hooks
+ * const { SRPCProvider, useSRPC } = createSRPCContext<AppRouter>();
+ *
+ * // Setup provider
+ * function App() {
+ *   return (
+ *     <QueryClientProvider client={queryClient}>
+ *       <SRPCProvider client={rpcClient}>
+ *         <MyComponent />
+ *       </SRPCProvider>
+ *     </QueryClientProvider>
+ *   );
+ * }
+ *
+ * // Use in components
+ * function MyComponent() {
+ *   const srpc = useSRPC();
+ *   const { data } = useQuery(srpc.users.getUser.queryOptions(1));
+ * }
+ * ```
+ */
+/** biome-ignore-all lint/suspicious/noExplicitAny: <Allow any type cast> */
+
+/**
+ * Type representing the query and mutation options factory for a single procedure.
+ *
+ * Each procedure in the SRPC router is transformed to have two methods:
+ * - `queryOptions(...args)` - Returns React Query options for `useQuery`
+ * - `mutationOptions()` - Returns React Query options for `useMutation`
+ *
+ * @template Procedure - The client procedure type
+ * @template TInput - Input parameters type (inferred from procedure)
+ * @template TOutput - Output/return type (inferred from procedure)
+ *
+ * @example
+ * ```typescript
+ * // For a procedure: getUser(id: number) => Promise<User>
+ * type GetUserOptions = OptionsFactory<typeof getUser>;
+ *
+ * // Has methods:
+ * const options: GetUserOptions = {
+ *   queryOptions: (id: number) => UseQueryOptions<Promise<User>>,
+ *   mutationOptions: () => UseMutationOptions<Promise<User>, Error, [number]>
+ * };
+ * ```
+ */
+type OptionsFactory<Procedure extends ClientProcedure<any>, TInput = Parameters<Procedure>, TOutput = ReturnType<Procedure>> = {
+    queryOptions: (...args: Parameters<Procedure>) => UseQueryOptions<TOutput>;
+    mutationOptions: () => UseMutationOptions<TOutput, Error, TInput>;
+};
+/**
+ * Type that recursively transforms an SRPC router into a structure with React Query options.
+ *
+ * For each procedure in the router, adds `.queryOptions()` and `.mutationOptions()` methods.
+ * Handles nested routers recursively, preserving the router structure.
+ *
+ * @template TRouter - The SRPC router routes type
+ *
+ * @example
+ * ```typescript
+ * // Server router
+ * const appRouter = s.router({
+ *   getUser: async (_, id: number) => ({ id, name: "John" }),
+ *   users: s.router({
+ *     createUser: async (_, data: UserData) => ({ id: 1, ...data })
+ *   })
+ * });
+ *
+ * // Client with query options
+ * type QueryRouter = DecoratedQueryProcedureRecord<typeof appRouter["ipc"]>;
+ * // {
+ * //   getUser: {
+ * //     queryOptions: (id: number) => UseQueryOptions<User>,
+ * //     mutationOptions: () => UseMutationOptions<User, Error, [number]>
+ * //   },
+ * //   users: {
+ * //     createUser: {
+ * //       queryOptions: (data: UserData) => UseQueryOptions<UserResult>,
+ * //       mutationOptions: () => UseMutationOptions<UserResult, Error, [UserData]>
+ * //     }
+ * //   }
+ * // }
+ * ```
+ */
+type DecoratedQueryProcedureRecord<TRouter extends AnyRoutes> = {
+    [TKey in keyof TRouter]: TRouter[TKey] extends AnyProcedure ? OptionsFactory<ClientProcedure<TRouter[TKey]>> : TRouter[TKey] extends SRPC<any> ? DecoratedQueryProcedureRecord<TRouter[TKey]["ipc"]> : never;
+};
+/**
+ * Transforms an SRPC client into React Query-compatible query and mutation options.
+ *
+ * This function takes an SRPC client and returns a proxy object where each procedure
+ * has `.queryOptions()` and `.mutationOptions()` methods that generate options for
+ * React Query's `useQuery` and `useMutation` hooks.
+ *
+ * The proxy automatically:
+ * - Generates query keys based on the procedure path and arguments
+ * - Wraps procedure calls in query/mutation functions
+ * - Preserves type safety throughout the chain
+ *
+ * @template TRouter - The SRPC router type
+ * @template TRoutes - The routes type (inferred automatically)
+ *
+ * @param options - Configuration object
+ * @param options.client - The SRPC client created with `createSRPCClient`
+ *
+ * @returns Decorated procedures with `.queryOptions()` and `.mutationOptions()` methods
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createSRPCClient } from "@srpc/core/client";
+ * import { createSRPCQueryOptions } from "@srpc.org/react-query";
+ * import { useQuery, useMutation } from "@tanstack/react-query";
+ * import type { AppRouter } from "./server";
+ *
+ * const client = createSRPCClient<AppRouter>({ endpoint: "/api" });
+ * const srpc = createSRPCQueryOptions({ client });
+ *
+ * function UserProfile({ userId }: { userId: number }) {
+ *   // Use with useQuery
+ *   const { data, isLoading } = useQuery(
+ *     srpc.users.getUser.queryOptions(userId)
+ *   );
+ *
+ *   return <div>{data?.name}</div>;
+ * }
+ * ```
+ *
+ * @example With mutations
+ * ```typescript
+ * function CreateUserForm() {
+ *   const createUser = useMutation(srpc.users.createUser.mutationOptions());
+ *
+ *   const handleSubmit = (data: UserData) => {
+ *     createUser.mutate(data);
+ *   };
+ *
+ *   return <form onSubmit={handleSubmit}>...</form>;
+ * }
+ * ```
+ *
+ * @example With query options
+ * ```typescript
+ * function UserList() {
+ *   const { data } = useQuery({
+ *     ...srpc.users.list.queryOptions(),
+ *     staleTime: 5000,
+ *     refetchInterval: 10000,
+ *   });
+ *
+ *   return <ul>{data?.map(user => <li key={user.id}>{user.name}</li>)}</ul>;
+ * }
+ * ```
+ *
+ * @example Nested routers
+ * ```typescript
+ * // Works with deeply nested routers
+ * const userQuery = useQuery(srpc.users.getUser.queryOptions(1));
+ * const adminQuery = useQuery(srpc.users.admin.getStats.queryOptions());
+ * const draftQuery = useQuery(srpc.posts.drafts.list.queryOptions());
+ * ```
+ */
+declare function createSRPCQueryOptions<TRouter extends AnySRPC, TRoutes extends AnyRoutes = TRouter["ipc"]>({ client, }: {
+    client: DecoratedProcedureRecord<TRoutes>;
+}): DecoratedQueryProcedureRecord<TRoutes>;
+
+export { createSRPCQueryOptions };
+export type { DecoratedQueryProcedureRecord, OptionsFactory };

package/dist/index.js

@@ -0,0 +1,108 @@
+import { createRecursiveProxy } from '@srpc/core/shared';
+import { queryOptions, mutationOptions } from '@tanstack/react-query';
+export { createSRPCContext } from './context.js';
+
+/**
+ * Transforms an SRPC client into React Query-compatible query and mutation options.
+ *
+ * This function takes an SRPC client and returns a proxy object where each procedure
+ * has `.queryOptions()` and `.mutationOptions()` methods that generate options for
+ * React Query's `useQuery` and `useMutation` hooks.
+ *
+ * The proxy automatically:
+ * - Generates query keys based on the procedure path and arguments
+ * - Wraps procedure calls in query/mutation functions
+ * - Preserves type safety throughout the chain
+ *
+ * @template TRouter - The SRPC router type
+ * @template TRoutes - The routes type (inferred automatically)
+ *
+ * @param options - Configuration object
+ * @param options.client - The SRPC client created with `createSRPCClient`
+ *
+ * @returns Decorated procedures with `.queryOptions()` and `.mutationOptions()` methods
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createSRPCClient } from "@srpc/core/client";
+ * import { createSRPCQueryOptions } from "@srpc.org/react-query";
+ * import { useQuery, useMutation } from "@tanstack/react-query";
+ * import type { AppRouter } from "./server";
+ *
+ * const client = createSRPCClient<AppRouter>({ endpoint: "/api" });
+ * const srpc = createSRPCQueryOptions({ client });
+ *
+ * function UserProfile({ userId }: { userId: number }) {
+ *   // Use with useQuery
+ *   const { data, isLoading } = useQuery(
+ *     srpc.users.getUser.queryOptions(userId)
+ *   );
+ *
+ *   return <div>{data?.name}</div>;
+ * }
+ * ```
+ *
+ * @example With mutations
+ * ```typescript
+ * function CreateUserForm() {
+ *   const createUser = useMutation(srpc.users.createUser.mutationOptions());
+ *
+ *   const handleSubmit = (data: UserData) => {
+ *     createUser.mutate(data);
+ *   };
+ *
+ *   return <form onSubmit={handleSubmit}>...</form>;
+ * }
+ * ```
+ *
+ * @example With query options
+ * ```typescript
+ * function UserList() {
+ *   const { data } = useQuery({
+ *     ...srpc.users.list.queryOptions(),
+ *     staleTime: 5000,
+ *     refetchInterval: 10000,
+ *   });
+ *
+ *   return <ul>{data?.map(user => <li key={user.id}>{user.name}</li>)}</ul>;
+ * }
+ * ```
+ *
+ * @example Nested routers
+ * ```typescript
+ * // Works with deeply nested routers
+ * const userQuery = useQuery(srpc.users.getUser.queryOptions(1));
+ * const adminQuery = useQuery(srpc.users.admin.getStats.queryOptions());
+ * const draftQuery = useQuery(srpc.posts.drafts.list.queryOptions());
+ * ```
+ */ function createSRPCQueryOptions({ client }) {
+    return createRecursiveProxy(({ path, args })=>{
+        const lastPath = path[path.length - 1];
+        const pathWithoutTarget = path.slice(0, -1);
+        const procedure = pathWithoutTarget.reduce((acc, key)=>acc[key], client);
+        if (typeof procedure !== "function") {
+            throw new Error(`Procedure at path ${pathWithoutTarget.join(".")} is not a function`);
+        }
+        if (lastPath === "queryOptions") {
+            return queryOptions({
+                queryKey: [
+                    ...pathWithoutTarget,
+                    args
+                ],
+                queryFn: ()=>procedure(...args)
+            });
+        }
+        if (lastPath === "mutationOptions") {
+            return mutationOptions({
+                mutationKey: [
+                    ...pathWithoutTarget,
+                    args
+                ],
+                mutationFn: (variables)=>procedure(...variables)
+            });
+        }
+        throw new Error(`Unknown target path at: ${path.join(".")}`);
+    });
+}
+
+export { createSRPCQueryOptions };