From 9bdee820b2cf72f0eb1a0428574037223fde79c8 Mon Sep 17 00:00:00 2001
From: fzaninotto <fzaninotto@gmail.com>
Date: Thu, 21 Nov 2024 17:44:09 +0100
Subject: [PATCH] [Doc] Update `useUpdate` doc to explain `returnPromise`
 option

---
 docs/useUpdate.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/docs/useUpdate.md b/docs/useUpdate.md
index c9066c1ee6..2600ff49d2 100644
--- a/docs/useUpdate.md
+++ b/docs/useUpdate.md
@@ -110,6 +110,7 @@ const IncreaseLikeButton = () => {
 - `onError`,
 - `onSettled`,
 - `onSuccess`,
+- `returnPromise`.
 
 ```jsx
 const notify = useNotify();
@@ -326,6 +327,32 @@ In `optimistic` mutation mode, `onSuccess` executes *before* the `dataProvider.u
 
 In `undoable` mutation mode, `onSuccess` executes *before* the `dataProvider.update()` is called. The actual call to the dataProvider is delayed until the update notification hides. If the user clicks the undo button, the `dataProvider.update()` call is never made. The callback receives no argument.
 
+## `returnPromise`
+
+By default, the `update` callback that `useUpdate` returns is synchronous and returns nothing. To execute a side effect after the mutation has succeeded, you can use the `onSuccess` callback.
+
+If this is not enough, you can use the `returnPromise` option so that the `update` callback returns a promise that resolves when the mutation has succeeded and rejects when the mutation has failed.
+
+This can be useful if the server changes the record, and you need the updated data to update another record. 
+
+```jsx
+const [update] = useUpdate(
+    'posts',
+    { id: record.id, data: { isPublished: true } },
+    { returnPromise: true }
+);
+const [create] = useCreate('auditLogs');
+
+const publishPost = async () => {
+    try {
+        const post = await update();
+        create('auditLogs', { data: { action: 'publish', recordId: post.id, date: post.updatedAt } });
+    } catch (error) {
+        // handle error
+    }
+};
+```
+
 ## TypeScript
 
 The `useUpdate` hook accepts a generic parameter for the record type and another for the error type: