docs: add a populateCache as a function (#329)

* docs: add a populateCache as a function

* Update pages/docs/mutation.en-US.md

Co-authored-by: Jiachi Liu <inbox@huozhi.im>

* docs: add descriptions of arguments and a return value of the populateCache function

Co-authored-by: Jiachi Liu <inbox@huozhi.im>

Author: koba04

pages/docs/mutation.en-US.md

@@ -74,7 +74,7 @@ function Profile () {
 
 **`revalidate`**: should the cache revalidate once the asynchronous update resolves.
 
-**`populateCache`**: should the result of the remote mutation be written to the cache.
+**`populateCache`**: should the result of the remote mutation be written to the cache, or a function that receives new result and current result as arguments and returns the mutation result.
 
 **`rollbackOnError`**: should the cache rollback if the remote mutation errors.
 
@@ -96,6 +96,28 @@ mutate('/api/todos', async todos => {
   // filter the list, and return it with the updated item
   const filteredTodos = todos.filter(todo => todo.id !== '1')
   return [...filteredTodos, updatedTodo]
+// Since the API already gives us the updated information,
+// we don't need to revalidate here.
+},　{ revalidate: false })
+```
+
+You can also use the `populateCache` option.
+
+```jsx
+const updateTodo = () => fetch('/api/todos/1', {
+  method: 'PATCH',
+  body: JSON.stringify({ completed: true })
+})
+
+mutate('/api/todos', updateTodo, {
+  populateCache: (updatedTodo, todos) => {
+    // filter the list, and return it with the updated item
+    const filteredTodos = todos.filter(todo => todo.id !== '1')
+    return [...filteredTodos, updatedTodo]
+  },
+  // Since the API already gives us the updated information,
+  // we don't need to revalidate here.
+  revalidate: false
 })
 ```
 

pages/docs/mutation.es-ES.md

@@ -72,7 +72,7 @@ function Profile () {
 
 **`revalidate`**: should the cache revalidate once the asynchronous update resolves.
 
-**`populateCache`**: should the result of the remote mutation be written to the cache.
+**`populateCache`**: should the result of the remote mutation be written to the cache, or a function that receives new result and current result as arguments and returns the mutation result.
 
 **`rollbackOnError`**: should the cache rollback if the remote mutation errors.
 
@@ -94,6 +94,28 @@ mutate('/api/todos', async todos => {
   // filtrar la lista y devolverla con el item actualizado
   const filteredTodos = todos.filter(todo => todo.id !== '1')
   return [...filteredTodos, updatedTodo]
+// Since the API already gives us the updated information,
+// we don't need to revalidate here.
+},　{ revalidate: false })
+```
+
+You can also use the `populateCache` option.
+
+```jsx
+const updateTodo = () => fetch('/api/todos/1', {
+  method: 'PATCH',
+  body: JSON.stringify({ completed: true })
+})
+
+mutate('/api/todos', updateTodo, {
+  populateCache: (updatedTodo, todos) => {
+    // filter the list, and return it with the updated item
+    const filteredTodos = todos.filter(todo => todo.id !== '1')
+    return [...filteredTodos, updatedTodo]
+  },
+  // Since the API already gives us the updated information,
+  // we don't need to revalidate here.
+  revalidate: false
 })
 ```
 

pages/docs/mutation.ja.md

@@ -74,7 +74,7 @@ function Profile () {
 
 **`revalidate`**: 非同期更新が解決した後、キャッシュを再検証するかどうか。
 
-**`populateCache`**: リモートミューテーションの結果をキャッシュに書き込むかどうか。
+**`populateCache`**: リモートミューテーションの結果をキャッシュに書き込むかどうか。関数も受け取ります。関数はミューテーションの結果と現在の値を引数として受けとり、ミューテーションの結果を返します。
 
 **`rollbackOnError`**: リモートミューテーションでエラーが発生した場合、キャッシュをロールバックするかどうか。
 
@@ -96,6 +96,28 @@ mutate('/api/todos', async todos => {
   // リストをフィルタリングし、更新されたアイテムを返します
   const filteredTodos = todos.filter(todo => todo.id !== '1')
   return [...filteredTodos, updatedTodo]
+// API からすでに更新後の情報が取得できるため
+// 再検証する必要はありません
+},　{ revalidate: false })
+```
+
+`populateCache` オプションも使用可能です。
+
+```jsx
+const updateTodo = () => fetch('/api/todos/1', {
+  method: 'PATCH',
+  body: JSON.stringify({ completed: true })
+})
+
+mutate('/api/todos', updateTodo, {
+  populateCache: (updatedTodo, todos) => {
+    // リストをフィルタリングし、更新されたアイテムを返します
+    const filteredTodos = todos.filter(todo => todo.id !== '1')
+    return [...filteredTodos, updatedTodo]
+  },
+  // API からすでに更新後の情報が取得できるため
+  // 再検証する必要はありません
+  revalidate: false
 })
 ```
 

pages/docs/mutation.ko.md

@@ -74,7 +74,7 @@ function Profile () {
 
 **`revalidate`**: 비동기 업데이트가 해소되면 캐시를 갱신합니다.
 
-**`populateCache`**: 캐시에 쓰여질 원격 뮤테이션의 결과입니다.
+**`populateCache`**: should the result of the remote mutation be written to the cache, or a function that receives new result and current result as arguments and returns the mutation result.
 
 **`rollbackOnError`**: 원격 뮤테이션 에러 시 캐시를 롤백합니다.
 
@@ -96,6 +96,28 @@ mutate('/api/todos', async todos => {
   // 리스트를 필터링하고 업데이트된 항목을 반환합니다
   const filteredTodos = todos.filter(todo => todo.id !== '1')
   return [...filteredTodos, updatedTodo]
+// Since the API already gives us the updated information,
+// we don't need to revalidate here.
+},　{ revalidate: false })
+```
+
+You can also use the `populateCache` option.
+
+```jsx
+const updateTodo = () => fetch('/api/todos/1', {
+  method: 'PATCH',
+  body: JSON.stringify({ completed: true })
+})
+
+mutate('/api/todos', updateTodo, {
+  populateCache: (updatedTodo, todos) => {
+    // filter the list, and return it with the updated item
+    const filteredTodos = todos.filter(todo => todo.id !== '1')
+    return [...filteredTodos, updatedTodo]
+  },
+  // Since the API already gives us the updated information,
+  // we don't need to revalidate here.
+  revalidate: false
 })
 ```