From 4cbd1838585a33d4924ce5ed40874f8bbe18768b Mon Sep 17 00:00:00 2001
From: Jonghyeon Ko <jonghyeon@toss.im>
Date: Mon, 7 Oct 2024 18:02:13 +0900
Subject: [PATCH] docs(react-query): add docs for usePrefetchQuery (#1296)

related with https://github.com/toss/suspensive/issues/1253

# Overview

<!--
    A clear and concise description of what this pr is about.
 -->

I added docs for usePrefetchQuery of @suspensive/react-query

I added @gwansikk(@suspensive/react-query active maintainer)
@kangju2000(Sandpack maker) as co-author

## 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: Gwansik Kim <39869096+gwansikk@users.noreply.github.com>
Co-authored-by: Juhyeok Kang <23312485+kangju2000@users.noreply.github.com>
Co-authored-by: Gwansik Kim <Seorit98@gmail.com>
---
 .../src/pages/docs/react-query/_meta.en.json  |   1 +
 .../src/pages/docs/react-query/_meta.ko.json  |   1 +
 .../docs/react-query/usePrefetchQuery.en.mdx  | 107 ++++++++++++++++++
 .../docs/react-query/usePrefetchQuery.ko.mdx  | 107 ++++++++++++++++++
 4 files changed, 216 insertions(+)
 create mode 100644 docs/suspensive.org/src/pages/docs/react-query/usePrefetchQuery.en.mdx
 create mode 100644 docs/suspensive.org/src/pages/docs/react-query/usePrefetchQuery.ko.mdx

diff --git a/docs/suspensive.org/src/pages/docs/react-query/_meta.en.json b/docs/suspensive.org/src/pages/docs/react-query/_meta.en.json
index 2c57e4c3c..0e655f096 100644
--- a/docs/suspensive.org/src/pages/docs/react-query/_meta.en.json
+++ b/docs/suspensive.org/src/pages/docs/react-query/_meta.en.json
@@ -10,6 +10,7 @@
   "useSuspenseQuery": { "title": "useSuspenseQuery" },
   "useSuspenseQueries": { "title": "useSuspenseQueries" },
   "useSuspenseInfiniteQuery": { "title": "useSuspenseInfiniteQuery" },
+  "usePrefetchQuery": { "title": "usePrefetchQuery" },
   "queryOptions": { "title": "queryOptions" },
   "infiniteQueryOptions": { "title": "infiniteQueryOptions" },
   "SuspenseQuery": { "title": "<SuspenseQuery/>" },
diff --git a/docs/suspensive.org/src/pages/docs/react-query/_meta.ko.json b/docs/suspensive.org/src/pages/docs/react-query/_meta.ko.json
index b9492e3d6..a62f5c82b 100644
--- a/docs/suspensive.org/src/pages/docs/react-query/_meta.ko.json
+++ b/docs/suspensive.org/src/pages/docs/react-query/_meta.ko.json
@@ -10,6 +10,7 @@
   "useSuspenseQuery": { "title": "useSuspenseQuery" },
   "useSuspenseQueries": { "title": "useSuspenseQueries" },
   "useSuspenseInfiniteQuery": { "title": "useSuspenseInfiniteQuery" },
+  "usePrefetchQuery": { "title": "usePrefetchQuery" },
   "queryOptions": { "title": "queryOptions" },
   "infiniteQueryOptions": { "title": "infiniteQueryOptions" },
   "SuspenseQuery": { "title": "<SuspenseQuery/>" },
diff --git a/docs/suspensive.org/src/pages/docs/react-query/usePrefetchQuery.en.mdx b/docs/suspensive.org/src/pages/docs/react-query/usePrefetchQuery.en.mdx
new file mode 100644
index 000000000..389ba924d
--- /dev/null
+++ b/docs/suspensive.org/src/pages/docs/react-query/usePrefetchQuery.en.mdx
@@ -0,0 +1,107 @@
+import { Callout, Sandpack } from '@/components'
+
+# usePrefetchQuery
+
+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.
+
+```jsx /usePrefetchQuery/
+import { usePrefetchQuery, queryOptions } from '@suspensive/react-query'
+
+const PostPage = ({ postId }) => {
+  usePrefetchQuery(query.post(postId)) // Prefetch query before suspense boundary
+
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <Post postId={postId} />
+    </Suspense>
+  )
+}
+
+export const Post = ({ postId }) => {
+  const { data } = useSuspenseQuery(query.post(postId))
+
+  return (
+    <div>
+      <h1>{data.title}</h1>
+      <p>{data.body}</p>
+    </div>
+  )
+}
+
+const query = {
+  post: (postId) =>
+    queryOptions({
+      queryKey: ['posts', postId],
+      queryFn: () => getPost(postId),
+    }),
+}
+```
+
+<Sandpack>
+
+```tsx Example.tsx active
+import { Suspense } from '@suspensive/react'
+import { usePrefetchQuery } from '@suspensive/react-query'
+import React from 'react'
+import { Post } from './Post'
+import { query } from './query'
+
+export const Example = () => {
+  const [postId, setPostId] = React.useState(1)
+  usePrefetchQuery(query.post(postId))
+
+  return (
+    <div>
+      <button onClick={() => setPostId((prev) => prev - 1)} disabled={postId === 1}>
+        Previous Post
+      </button>
+      <button onClick={() => setPostId((prev) => prev + 1)} disabled={postId === 100}>
+        Next Post
+      </button>
+      <Suspense fallback={<div>Loading...</div>}>
+        <Post postId={postId} />
+      </Suspense>
+    </div>
+  )
+}
+```
+
+```tsx Post.tsx
+import { useSuspenseQuery } from '@suspensive/react-query'
+import { query } from './query'
+
+export const Post = ({ postId }: { postId: number }) => {
+  const { data } = useSuspenseQuery(query.post(postId))
+
+  return (
+    <div>
+      <h1>{data.title}</h1>
+      <p>{data.body}</p>
+    </div>
+  )
+}
+```
+
+```tsx /query.ts
+import { queryOptions } from '@suspensive/react-query'
+
+export const query = {
+  post: (postId: number) =>
+    queryOptions({
+      queryKey: ['posts', postId],
+      queryFn: async (): Promise<{
+        id: number
+        title: string
+        body: string
+      }> => {
+        const response = await fetch(`https://jsonplaceholder.typicode.com/posts/${postId}`)
+        if (!response.ok) {
+          throw new Error('An error occurred')
+        }
+        return await response.json()
+      }
+    })
+}
+```
+
+</Sandpack>
diff --git a/docs/suspensive.org/src/pages/docs/react-query/usePrefetchQuery.ko.mdx b/docs/suspensive.org/src/pages/docs/react-query/usePrefetchQuery.ko.mdx
new file mode 100644
index 000000000..6f81db414
--- /dev/null
+++ b/docs/suspensive.org/src/pages/docs/react-query/usePrefetchQuery.ko.mdx
@@ -0,0 +1,107 @@
+import { Callout, Sandpack } from '@/components'
+
+# usePrefetchQuery
+
+usePrefetchQuery는 아무것도 반환하지 않으며, useSuspenseQuery를 사용하는 컴포넌트를 래핑하는 suspense boundary가 렌더 되기전에 prefetch를 발생시키는 데에 사용합니다.
+
+```jsx /usePrefetchQuery/
+import { usePrefetchQuery, queryOptions } from '@suspensive/react-query'
+
+const PostPage = ({ postId }) => {
+  usePrefetchQuery(query.post(postId)) // suspense경계 전에 prefetch를 발생 시키는 데에 사용합니다
+
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <Post postId={postId} />
+    </Suspense>
+  )
+}
+
+export const Post = ({ postId }) => {
+  const { data } = useSuspenseQuery(query.post(postId))
+
+  return (
+    <div>
+      <h1>{data.title}</h1>
+      <p>{data.body}</p>
+    </div>
+  )
+}
+
+const query = {
+  post: (postId) =>
+    queryOptions({
+      queryKey: ['posts', postId],
+      queryFn: () => getPost(postId),
+    }),
+}
+```
+
+<Sandpack>
+
+```tsx Example.tsx active
+import { Suspense } from '@suspensive/react'
+import { usePrefetchQuery } from '@suspensive/react-query'
+import React from 'react'
+import { Post } from './Post'
+import { query } from './query'
+
+export const Example = () => {
+  const [postId, setPostId] = React.useState(1)
+  usePrefetchQuery(query.post(postId))
+
+  return (
+    <div>
+      <button onClick={() => setPostId((prev) => prev - 1)} disabled={postId === 1}>
+        Previous Post
+      </button>
+      <button onClick={() => setPostId((prev) => prev + 1)} disabled={postId === 100}>
+        Next Post
+      </button>
+      <Suspense fallback={<div>Loading...</div>}>
+        <Post postId={postId} />
+      </Suspense>
+    </div>
+  )
+}
+```
+
+```tsx Post.tsx
+import { useSuspenseQuery } from '@suspensive/react-query'
+import { query } from './query'
+
+export const Post = ({ postId }: { postId: number }) => {
+  const { data } = useSuspenseQuery(query.post(postId))
+
+  return (
+    <div>
+      <h1>{data.title}</h1>
+      <p>{data.body}</p>
+    </div>
+  )
+}
+```
+
+```tsx /query.ts
+import { queryOptions } from '@suspensive/react-query'
+
+export const query = {
+  post: (postId: number) =>
+    queryOptions({
+      queryKey: ['posts', postId],
+      queryFn: async (): Promise<{
+        id: number
+        title: string
+        body: string
+      }> => {
+        const response = await fetch(`https://jsonplaceholder.typicode.com/posts/${postId}`)
+        if (!response.ok) {
+          throw new Error('An error occurred')
+        }
+        return await response.json()
+      }
+    })
+}
+```
+
+</Sandpack>