feat(react-query): add jsdoc to react query apis (#1304)

# Overview close: #1264 - The JSDoc for React Hook APIs includes descriptions of the hooks and links to the official documentation. - The JSDoc for Component APIs includes descriptions of the components, links to the official documentation, and simple examples that illustrate the usage concepts. - The examples are designed to be straightforward, allowing users to grasp the usage without significant complexity (ensuring minimal impact in case of future changes). ## PR Checklist - [x] I did below actions if need 1. I read the [Contributing Guide](https://github.com/toss/suspensive/blob/main/CONTRIBUTING.md) 2. I added documents and tests. --------- Co-authored-by: Jonghyeon Ko <[email protected]>
toss · Oct 12, 2024 · 1ac80e7 · 1ac80e7
1 parent e7dd6ba
commit 1ac80e7
Show file tree

Hide file tree

Showing 20 changed files with 168 additions and 14 deletions.
diff --git a/.changeset/famous-donuts-protect.md b/.changeset/famous-donuts-protect.md
@@ -0,0 +1,6 @@
+---
+"@suspensive/react-query-4": patch
+"@suspensive/react-query-5": patch
+---
+
+feat(react-query): add jsdoc react-query apis
diff --git a/packages/react-query-4/src/PrefetchInfiniteQuery.tsx b/packages/react-query-4/src/PrefetchInfiniteQuery.tsx
@@ -1,6 +1,14 @@
 import { type FetchInfiniteQueryOptions, type QueryKey } from '@tanstack/react-query'
 import { usePrefetchInfiniteQuery } from './usePrefetchInfiniteQuery'
 
+/**
+ * A component that allows you to use usePrefetchInfiniteQuery in JSX, avoiding the limitations of React hooks.
+ * @see {@link https://suspensive.org/en/docs/react-query/PrefetchInfiniteQuery Suspensive Docs}
+ * @example
+ * ```tsx
+ * <PrefetchInfiniteQuery queryKey={['queryKey']} queryFn={queryFn} />
+ * ```
+ */
 export function PrefetchInfiniteQuery<
   TQueryFnData = unknown,
   TError = unknown,

diff --git a/packages/react-query-4/src/PrefetchQuery.tsx b/packages/react-query-4/src/PrefetchQuery.tsx
@@ -1,6 +1,14 @@
 import { type FetchQueryOptions, type QueryKey } from '@tanstack/react-query'
 import { usePrefetchQuery } from './usePrefetchQuery'
 
+/**
+ * A component that allows you to use usePrefetchQuery in JSX, avoiding the limitations of React hooks.
+ * @see {@link https://suspensive.org/en/docs/react-query/PrefetchQuery Suspensive Docs}
+ * @example
+ * ```tsx
+ * <PrefetchQuery queryKey={['queryKey']} queryFn={queryFn} />
+ * ```
+ */
 export function PrefetchQuery<
   TQueryFnData = unknown,
   TError = unknown,

diff --git a/packages/react-query-4/src/QueryErrorBoundary.tsx b/packages/react-query-4/src/QueryErrorBoundary.tsx
@@ -4,7 +4,15 @@ import { type ComponentPropsWithoutRef, type ComponentRef, forwardRef } from 're
 
 /**
  * This component wrapping QueryErrorResetBoundary of `@tanstack/react-query` with `@suspensive/react`'s ErrorBoundary. So you must install `@suspensive/react` first, then use it. with this component, You don't have to make unnecessary repetitive implementation to combine ErrorBoundary with QueryErrorResetBoundary
- * @see {@link https://suspensive.org/docs/react-query/QueryErrorBoundary}
+ * @see {@link https://suspensive.org/en/docs/react-query/QueryErrorBoundary Suspensive Docs}
+ * @example
+ * ```tsx
+ * <QueryErrorBoundary
+ *   fallback={({ reset, error }) => <></>)}
+ * >
+ *   <ChildrenComponent />
+ * </QueryErrorBoundary>
+ * ```
  */
 export const QueryErrorBoundary = forwardRef<
   ComponentRef<typeof ErrorBoundary>,

diff --git a/packages/react-query-4/src/SuspenseInfiniteQuery.tsx b/packages/react-query-4/src/SuspenseInfiniteQuery.tsx
@@ -6,6 +6,22 @@ import {
   useSuspenseInfiniteQuery,
 } from './useSuspenseInfiniteQuery'
 
+/**
+ * We provide these components to clearly express what causes suspense at the same depth.
+ * `<SuspenseInfiniteQuery/>` serves to make `useSuspenseInfiniteQuery` easier to use in jsx.
+ * @see {@link https://suspensive.org/en/docs/react-query/SuspenseInfiniteQuery Suspensive Docs}
+ * @example
+ * ```tsx
+ * import { SuspenseInfiniteQuery } from '@suspensive/react-query'
+ *
+ * // You can use infiniteQueryOptions as props.
+ * <SuspenseInfiniteQuery {...infiniteQueryOptions()}>
+ *   {({ data, fetchNextPage }) => {
+ *     return <></>
+ *   }}
+ * </SuspenseInfiniteQuery>
+ * ```
+ */
 export const SuspenseInfiniteQuery = <
   TQueryFnData = unknown,
   TError = unknown,

diff --git a/packages/react-query-4/src/SuspenseQueries.tsx b/packages/react-query-4/src/SuspenseQueries.tsx
@@ -1,6 +1,21 @@
 import type { ReactNode } from 'react'
 import { type SuspenseQueriesOptions, type SuspenseQueriesResults, useSuspenseQueries } from './useSuspenseQueries'
 
+/**
+ * We provide these components to clearly express what causes suspense at the same depth.
+ * `<SuspenseQueries/>` serves to make `useSuspenseQueries` easier to use in jsx.
+ * @see {@link https://suspensive.org/en/docs/react-query/SuspenseQueries Suspensive Docs}
+ * @example
+ * ```tsx
+ * import { SuspenseQueries } from '@suspensive/react-query'
+ *
+ * <SuspenseQueries queries={[firstQueryOptions(), secondQueryOptions()]}>
+ *   {([{ data: firstQueryData }, { data: secondQueryData }]) => {
+ *     return <></>
+ *   }}
+ * </SuspenseQueries>
+ * ```
+ */
 export function SuspenseQueries<T extends any[]>({
   children,
   queries,

diff --git a/packages/react-query-4/src/SuspenseQuery.tsx b/packages/react-query-4/src/SuspenseQuery.tsx
@@ -2,6 +2,22 @@ import type { QueryKey } from '@tanstack/react-query'
 import type { ReactNode } from 'react'
 import { type UseSuspenseQueryOptions, type UseSuspenseQueryResult, useSuspenseQuery } from './useSuspenseQuery'
 
+/**
+ * We provide these components to clearly express what causes suspense at the same depth.
+ * `<SuspenseQuery/>` serves to make `useSuspenseQuery` easier to use in jsx.
+ * @see {@link https://suspensive.org/en/docs/react-query/SuspenseQuery Suspensive Docs}
+ * @example
+ * ```tsx
+ * import { SuspenseQuery } from '@suspensive/react-query'
+ *
+ * // You can use QueryOptions as props.
+ * <SuspenseQuery {...queryOptions()}>
+ *   {({ data, isLoading }) => {
+ *     return <></>
+ *   }
+ * </SuspenseQuery>
+ * ```
+ */
 export const SuspenseQuery = <
   TQueryFnData = unknown,
   TError = unknown,

diff --git a/packages/react-query-4/src/infiniteQueryOptions.ts b/packages/react-query-4/src/infiniteQueryOptions.ts
@@ -59,6 +59,7 @@ export function infiniteQueryOptions<
 >(
   options: SelectedInfiniteOptions<TQueryFnData, TError, TData, TQueryKey>
 ): SelectedInfiniteOptions<TQueryFnData, TError, TData, TQueryKey>
+
 export function infiniteQueryOptions<
   TQueryFnData,
   TError = unknown,
@@ -67,6 +68,7 @@ export function infiniteQueryOptions<
 >(
   options: UnSelectedInfiniteOptions<TQueryFnData, TError, TData, TQueryKey>
 ): UnSelectedInfiniteOptions<TQueryFnData, TError, TData, TQueryKey>
+
 export function infiniteQueryOptions(options: unknown) {
   return options
 }
diff --git a/packages/react-query-4/src/queryOptions.ts b/packages/react-query-4/src/queryOptions.ts
@@ -63,6 +63,7 @@ export function queryOptions<
 >(
   options: SelectedQueryOptions<TQueryFnData, TError, TData, TQueryKey>
 ): SelectedQueryOptions<TQueryFnData, TError, TData, TQueryKey>
+
 export function queryOptions<
   TQueryFnData = unknown,
   TError = unknown,
@@ -71,15 +72,7 @@ export function queryOptions<
 >(
   options: UnSelectedQueryOptions<TQueryFnData, TError, TData, TQueryKey>
 ): UnSelectedQueryOptions<TQueryFnData, TError, TData, TQueryKey>
-export function queryOptions<
-  TQueryFnData = unknown,
-  TError = unknown,
-  TData = TQueryFnData,
-  TQueryKey extends QueryKey = QueryKey,
->(
-  options:
-    | SelectedQueryOptions<TQueryFnData, TError, TData, TQueryKey>
-    | UnSelectedQueryOptions<TQueryFnData, TError, TData, TQueryKey>
-) {
+
+export function queryOptions(options: unknown) {
   return options
 }
diff --git a/packages/react-query-4/src/usePrefetchInfiniteQuery.ts b/packages/react-query-4/src/usePrefetchInfiniteQuery.ts
@@ -1,5 +1,9 @@
 import { type FetchInfiniteQueryOptions, type QueryKey, useQueryClient } from '@tanstack/react-query'
 
+/**
+ * The usePrefetchInfiniteQuery does not return anything, it should be used just to fire a prefetch during render, before a suspense boundary that wraps a component that uses useSuspenseInfiniteQuery.
+ * @see {@link https://suspensive.org/en/docs/react-query/usePrefetchInfiniteQuery Suspensive Docs}
+ */
 export function usePrefetchInfiniteQuery<
   TQueryFnData = unknown,
   TError = unknown,

diff --git a/packages/react-query-4/src/usePrefetchQuery.ts b/packages/react-query-4/src/usePrefetchQuery.ts
@@ -1,5 +1,9 @@
 import { type FetchQueryOptions, type QueryKey, useQueryClient } from '@tanstack/react-query'
 
+/**
+ * The usePrefetchQuery does not return anything, it should be used just to fire a prefetch during render, before a suspense boundary that wraps a component that uses useSuspenseQuery.
+ * @see {@link https://suspensive.org/en/docs/react-query/usePrefetchQuery Suspensive Docs}
+ */
 export function usePrefetchQuery<
   TQueryFnData = unknown,
   TError = unknown,

diff --git a/packages/react-query-4/src/useSuspenseInfiniteQuery.ts b/packages/react-query-4/src/useSuspenseInfiniteQuery.ts
@@ -28,7 +28,7 @@ export type UseSuspenseInfiniteQueryOptions<
 
 /**
  * This hook is wrapping useInfiniteQuery of `@tanstack/react-query` v4 with default suspense option.
- * @see {@link https://suspensive.org/docs/react-query/useSuspenseInfiniteQuery}
+ * @see {@link https://suspensive.org/en/docs/react-query/useSuspenseInfiniteQuery Suspensive Docs}
  */
 export function useSuspenseInfiniteQuery<
   TQueryFnData = unknown,

diff --git a/packages/react-query-4/src/useSuspenseQueries.ts b/packages/react-query-4/src/useSuspenseQueries.ts
@@ -111,7 +111,7 @@ export type SuspenseQueriesResults<
 
 /**
  * This hook is wrapping useQueries of `@tanstack/react-query` v4 with default suspense option.
- * @see {@link https://suspensive.org/docs/react-query/useSuspenseQueries}
+ * @see {@link https://suspensive.org/en/docs/react-query/useSuspenseQueries Suspensive Docs}
  */
 export function useSuspenseQueries<T extends any[]>({
   queries,

diff --git a/packages/react-query-4/src/useSuspenseQuery.ts b/packages/react-query-4/src/useSuspenseQuery.ts
@@ -19,7 +19,7 @@ export type UseSuspenseQueryOptions<
 
 /**
  * This hook is wrapping useQuery of `@tanstack/react-query` v4 with default suspense option.
- * @see {@link https://suspensive.org/docs/react-query/useSuspenseQuery}
+ * @see {@link https://suspensive.org/en/docs/react-query/useSuspenseQuery Suspensive Docs}
  */
 export function useSuspenseQuery<
   TQueryFnData = unknown,

diff --git a/packages/react-query-5/src/PrefetchInfiniteQuery.tsx b/packages/react-query-5/src/PrefetchInfiniteQuery.tsx
@@ -5,6 +5,14 @@ import {
   usePrefetchInfiniteQuery,
 } from '@tanstack/react-query'
 
+/**
+ * A component that allows you to use usePrefetchInfiniteQuery in JSX, avoiding the limitations of React hooks.
+ * @see {@link https://suspensive.org/en/docs/react-query/PrefetchInfiniteQuery Suspensive Docs}
+ * @example
+ * ```tsx
+ * <PrefetchInfiniteQuery queryKey={['queryKey']} queryFn={queryFn} />
+ * ```
+ */
 export function PrefetchInfiniteQuery<
   TQueryFnData = unknown,
   TError = DefaultError,

diff --git a/packages/react-query-5/src/PrefetchQuery.tsx b/packages/react-query-5/src/PrefetchQuery.tsx
@@ -1,5 +1,13 @@
 import { type DefaultError, type FetchQueryOptions, type QueryKey, usePrefetchQuery } from '@tanstack/react-query'
 
+/**
+ * A component that allows you to use usePrefetchQuery in JSX, avoiding the limitations of React hooks.
+ * @see {@link https://suspensive.org/en/docs/react-query/PrefetchQuery Suspensive Docs}
+ * @example
+ * ```tsx
+ * <PrefetchQuery queryKey={['queryKey']} queryFn={queryFn} />
+ * ```
+ */
 export function PrefetchQuery<
   TQueryFnData = unknown,
   TError = DefaultError,

diff --git a/packages/react-query-5/src/QueryErrorBoundary.tsx b/packages/react-query-5/src/QueryErrorBoundary.tsx
@@ -2,6 +2,18 @@ import { ErrorBoundary } from '@suspensive/react'
 import { useQueryErrorResetBoundary } from '@tanstack/react-query'
 import { type ComponentPropsWithoutRef, type ComponentRef, forwardRef } from 'react'
 
+/**
+ * This component wrapping QueryErrorResetBoundary of `@tanstack/react-query` with `@suspensive/react`'s ErrorBoundary. So you must install `@suspensive/react` first, then use it. with this component, You don't have to make unnecessary repetitive implementation to combine ErrorBoundary with QueryErrorResetBoundary
+ * @see {@link https://suspensive.org/en/docs/react-query/QueryErrorBoundary Suspensive Docs}
+ * @example
+ * ```tsx
+ * <QueryErrorBoundary
+ *   fallback={({ reset, error }) => <></>)}
+ * >
+ *   <ChildrenComponent />
+ * </QueryErrorBoundary>
+ * ```
+ */
 export const QueryErrorBoundary = forwardRef<
   ComponentRef<typeof ErrorBoundary>,
   ComponentPropsWithoutRef<typeof ErrorBoundary>

diff --git a/packages/react-query-5/src/SuspenseInfiniteQuery.tsx b/packages/react-query-5/src/SuspenseInfiniteQuery.tsx
@@ -8,6 +8,22 @@ import {
 } from '@tanstack/react-query'
 import type { ReactNode } from 'react'
 
+/**
+ * We provide these components to clearly express what causes suspense at the same depth.
+ * `<SuspenseInfiniteQuery/>` serves to make `useSuspenseInfiniteQuery` easier to use in jsx.
+ * @see {@link https://suspensive.org/en/docs/react-query/SuspenseInfiniteQuery Suspensive Docs}
+ * @example
+ * ```tsx
+ * import { SuspenseInfiniteQuery } from '@suspensive/react-query'
+ *
+ * // You can use infiniteQueryOptions as props.
+ * <SuspenseInfiniteQuery {...infiniteQueryOptions()}>
+ *   {({ data, fetchNextPage }) => {
+ *     return <></>
+ *   }}
+ * </SuspenseInfiniteQuery>
+ * ```
+ */
 export const SuspenseInfiniteQuery = <
   TQueryFnData,
   TError = DefaultError,

diff --git a/packages/react-query-5/src/SuspenseQueries.tsx b/packages/react-query-5/src/SuspenseQueries.tsx
@@ -1,6 +1,21 @@
 import { type SuspenseQueriesOptions, type SuspenseQueriesResults, useSuspenseQueries } from '@tanstack/react-query'
 import type { ReactNode } from 'react'
 
+/**
+ * We provide these components to clearly express what causes suspense at the same depth.
+ * `<SuspenseQueries/>` serves to make `useSuspenseQueries` easier to use in jsx.
+ * @see {@link https://suspensive.org/en/docs/react-query/SuspenseQueries Suspensive Docs}
+ * @example
+ * ```tsx
+ * import { SuspenseQueries } from '@suspensive/react-query'
+ *
+ * <SuspenseQueries queries={[firstQueryOptions(), secondQueryOptions()]}>
+ *   {([{ data: firstQueryData }, { data: secondQueryData }]) => {
+ *     return <></>
+ *   }}
+ * </SuspenseQueries>
+ * ```
+ */
 export function SuspenseQueries<T extends any[], TCombinedResult = SuspenseQueriesResults<T>>({
   children,
   queries,

diff --git a/packages/react-query-5/src/SuspenseQuery.tsx b/packages/react-query-5/src/SuspenseQuery.tsx
@@ -7,6 +7,21 @@ import {
 } from '@tanstack/react-query'
 import type { ReactNode } from 'react'
 
+/**
+ * We provide these components to clearly express what causes suspense at the same depth.
+ * `<SuspenseQuery/>` serves to make `useSuspenseQuery` easier to use in jsx.
+ * @see {@link https://suspensive.org/en/docs/react-query/SuspenseQuery Suspensive Docs}
+ * @example
+ * ```tsx
+ * import { SuspenseQuery } from '@suspensive/react-query'
+ *
+ * // You can use QueryOptions as props.
+ * <SuspenseQuery {...queryOptions()}>
+ *   {({ data, isLoading }) => {
+ *     return <></>
+ *   }
+ * </SuspenseQuery/>
+ */
 export const SuspenseQuery = <
   TQueryFnData = unknown,
   TError = DefaultError,