Make querykey optional and provide a default based on method name and request

Author: dpup

README.md

@@ -78,7 +78,6 @@ const UserProfilePage ({ userID }) => {
   const { isLoading, isError, error, data } = useServiceQuery(
     UserService.ReadUser,
     { id: userID },
-    { queryKey: ['user', userID] },
   );
   if (isLoading) return <LoadingScreen />;
   else if (isError) return <ErrorPage error={error} />;
@@ -112,6 +111,24 @@ mutation.mutate({ id: userID, name: newName });
 use suspenses. It is only marginally more convenient than using the service
 method directly.
 
+```ts
+const reqCtx = useContext(ServiceContext);
+const { data: currentWorkspace } = useSuspenseQuery(
+  queryOptions(UserService.GetUser, { userId }, reqCtx, {
+    staleTime: 60 * 1000,
+  }),
+);
+```
+
+### queryKey
+
+`queryKey` returns a default query key for a service method and request. It is
+provided as a convenience and can be overridden in the options param.
+
+```ts
+await queryClient.invalidateQueries({ queryKey: queryKey(UserService.ListUsers) });
+```
+
 ## Contributing
 
 If you find issues or spot possible improvements, please submit a pull-request.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-query-grpc-gateway",
-  "version": "1.2.6",
+  "version": "1.2.7",
   "description": "React hook for querying gRPC Gateway endpoints using Tanstack Query.",
   "type": "module",
   "main": "dist/index.js",

src/index.ts

@@ -2,3 +2,4 @@ export * from './types';
 export * from './useServiceMutation';
 export * from './useServiceQuery';
 export * from './serviceContext';
+export * from './queryKey';

src/queryKey.ts

@@ -0,0 +1,12 @@
+import { ServiceMethod } from './types';
+
+// Returns a default query key for a service method and request object. The key
+// structure should not be depended on and considered internal. It is subject to
+// change.
+export function queryKey<M extends ServiceMethod<Parameters<M>[0], Awaited<ReturnType<M>>>>(
+  method: M,
+  req?: Parameters<M>[0],
+): [string] | [string, Parameters<M>[0]] {
+  if (req === undefined) return [method.name];
+  return [method.name, req];
+}

src/types.ts

@@ -3,8 +3,9 @@
 // - O represents the output type for the service method, or the response.
 // - M represents the service method itself.
 // - C represents a context.
+// - Q represents a QueryKey.
 
-import { UseMutationOptions, UseQueryOptions } from '@tanstack/react-query';
+import { QueryKey, UseMutationOptions, UseQueryOptions } from '@tanstack/react-query';
 
 // Represents the static methods from the generated service client.
 export type ServiceMethod<I, O> = (req: I, initReq: RequestInitWithPathPrefix) => Promise<O>;
@@ -33,13 +34,16 @@ export interface ErrorResponse {
 
 // Represents the `useServiceQuery` options. This is the same as
 // `UseQueryOptions` except that `queryFn` is handled internally, so must not
-// be provided. Additionally an `onError` handler can be provided to provide
-// customized error handling.
-export type UseServiceQueryOptions<M extends ServiceMethod<Parameters<M>[0], ReturnType<M>>> = Omit<
-  UseQueryOptions<Awaited<ReturnType<M>>, ServiceError>,
-  'queryFn'
-> & {
+// be provided and `queryKey` becomes optional.
+// Additionally an `onError` handler can be provided to provide customized error
+// handling.
+export type UseServiceQueryOptions<
+  M extends ServiceMethod<Parameters<M>[0], ReturnType<M>>,
+  Q extends QueryKey,
+> = Omit<UseQueryOptions<Awaited<ReturnType<M>>, ServiceError>, 'queryFn' | 'queryKey'> & {
   onError?: OnErrorHandler<ReturnType<M>>;
+} & {
+  queryKey?: Q;
 };
 
 // Represents the `useServiceMutation` options. This is the same as

src/useServiceQuery.ts

@@ -1,4 +1,4 @@
-import { UseQueryResult, useQuery, UseQueryOptions } from '@tanstack/react-query';
+import { UseQueryResult, useQuery, UseQueryOptions, QueryKey } from '@tanstack/react-query';
 import { useContext } from 'react';
 import { ServiceContext } from '.';
 import {
@@ -7,28 +7,36 @@ import {
   ServiceMethod,
   UseServiceQueryOptions,
 } from './types';
+import { queryKey } from './queryKey';
 
 // Wraps `useQuery` from react-query, pulling request configuration from context
 // and making it easier to call generated service clients.
-export function useServiceQuery<M extends ServiceMethod<Parameters<M>[0], Awaited<ReturnType<M>>>>(
+export function useServiceQuery<
+  M extends ServiceMethod<Parameters<M>[0], Awaited<ReturnType<M>>>,
+  Q extends QueryKey,
+>(
   method: M,
   req: Parameters<M>[0],
-  options?: UseServiceQueryOptions<M>,
+  options?: UseServiceQueryOptions<M, Q>,
 ): UseQueryResult<Awaited<ReturnType<M>>, ServiceError> {
   const reqCtx = useContext(ServiceContext);
   return useQuery(queryOptions(method, req, reqCtx, options));
 }
 
 // Returns the options object for `useQuery` based on the service method. Can
 // be used with `useSuspenseQuery` for data loading.
-export function queryOptions<M extends ServiceMethod<Parameters<M>[0], Awaited<ReturnType<M>>>>(
+export function queryOptions<
+  M extends ServiceMethod<Parameters<M>[0], Awaited<ReturnType<M>>>,
+  Q extends QueryKey,
+>(
   method: M,
   req: Parameters<M>[0],
   reqInit?: RequestInitWithPathPrefix,
-  options?: UseServiceQueryOptions<M>,
+  options?: UseServiceQueryOptions<M, Q>,
 ): UseQueryOptions<Awaited<ReturnType<M>>, ServiceError> {
   return {
-    ...options!,
+    ...options,
+    queryKey: options?.queryKey ?? queryKey(method, req),
     queryFn: () => {
       const resp = method(req, {
         ...reqInit,

tests/queryKey.test.tsx

@@ -0,0 +1,32 @@
+import { queryKey } from '../src/queryKey';
+import { RequestInitWithPathPrefix } from '../src/types';
+
+interface FakeRequest {
+  id: number;
+  name: string;
+}
+
+interface FakeResponse {
+  req: FakeRequest;
+  initReq?: RequestInitWithPathPrefix;
+}
+
+class FakeService {
+  static FakeMethod(
+    this: void,
+    req: FakeRequest,
+    initReq?: RequestInitWithPathPrefix,
+  ): Promise<FakeResponse> {
+    return Promise.resolve({ req, initReq });
+  }
+}
+
+test('query key with request', () => {
+  const key = queryKey(FakeService.FakeMethod, { id: 1, name: 'Hello' });
+  expect(key).toEqual(['FakeMethod', { id: 1, name: 'Hello' }]);
+});
+
+test('query key with only method', () => {
+  const key = queryKey(FakeService.FakeMethod);
+  expect(key).toEqual(['FakeMethod']);
+});

tests/useServiceQuery.test.tsx

@@ -44,14 +44,39 @@ class FakeService {
   }
 }
 
-test('basic method call should return expected data', async () => {
+test('basic service call', async () => {
   const queryClient = new QueryClient();
   const wrapper: FC<PropsWithChildren> = ({ children }) => (
     <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
   );
 
   const { result } = renderHook(
-    () => useServiceQuery(FakeService.FakeMethod, { id: 1, name: 'Hello' }, { queryKey: ['fake'] }),
+    () => useServiceQuery(FakeService.FakeMethod, { id: 1, name: 'Hello' }),
+    { wrapper },
+  );
+
+  await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+  if (result.current.data) {
+    expect(result.current.data.req.id).toEqual(1);
+    expect(result.current.data.req.name).toEqual('Hello');
+    expect(result.current.data.initReq).toEqual({
+      headers: { 'Content-Type': 'application/json' },
+    });
+  } else {
+    fail('Expected data to be defined');
+  }
+});
+
+test('service call with custom query key', async () => {
+  const queryClient = new QueryClient();
+  const wrapper: FC<PropsWithChildren> = ({ children }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+
+  const { result } = renderHook(
+    () =>
+      useServiceQuery(FakeService.FakeMethod, { id: 1, name: 'Hello' }, { queryKey: ['mykey', 1] }),
     { wrapper },
   );
 
@@ -79,7 +104,7 @@ test('service context should override request options', async () => {
   );
 
   const { result } = renderHook(
-    () => useServiceQuery(FakeService.FakeMethod, { id: 1, name: 'Hello' }, { queryKey: ['fake'] }),
+    () => useServiceQuery(FakeService.FakeMethod, { id: 1, name: 'Hello' }),
     { wrapper },
   );
 
@@ -108,7 +133,6 @@ test('onerror handler should be able to recover from an error', async () => {
         FakeService.ErrorMethod,
         { id: 1, name: 'Hello' },
         {
-          queryKey: ['fake'],
           onError: (e) => {
             if (isErrorResponse(e) && e.code === 16) {
               return null;