docs(make-cancelable): updated documentation

Author: João Dias

docs/docs/functions/utils/make-cancelable.mdx

@@ -1,7 +1,7 @@
 ---
 title: makeCancelable
 ---
-Wraps a native Promise and allows it to be cancelled using AbortController. This is useful for cancelling long-running operations or preventing memory leaks when a component unmounts before an async operation completes.
+Wraps a native Promise and allows it to be cancelled using AbortController. This is useful for cancelling long-running operations or preventing memory leaks when a component unmounts before an async operation completes. The function also provides access to the underlying AbortSignal, which can be used to coordinate cancellation across multiple promises or network requests.
 
 ## API
 
@@ -11,14 +11,24 @@ interface MakeCancelablePromise<T = unknown> {
    * The wrapped promise that can be aborted
    */
   promise: Promise<T>;
+
   /**
    * Aborts the promise execution. Safe to call multiple times - subsequent calls will be ignored if already cancelled.
+   * @param reason - Optional reason for the cancellation
    */
-  cancel: () => void;
+  cancel: (reason?: any) => void;
+
   /**
    * Checks whether the promise has been cancelled
    */
   isCancelled: () => boolean;
+
+  /**
+   * The AbortSignal object that can be used to check if the promise has been cancelled.
+   * This signal can be used to coordinate cancellation across multiple promises or network requests
+   * by passing it to other abortable operations that should be cancelled together.
+   */
+  signal: AbortSignal;
 }
 
 function makeCancelable<T = unknown>(promise: Promise<T>): MakeCancelablePromise<T>;
@@ -53,6 +63,15 @@ cancelable.cancel();
 if (cancelable.isCancelled()) {
   console.log('Promise was already cancelled');
 }
+
+// Use the signal with other abortable operations
+fetch('/api/data', { signal: cancelable.signal })
+  .then(response => response.json())
+  .catch(error => {
+    if (error instanceof AbortPromiseError) {
+      console.log('Fetch was cancelled');
+    }
+  });
 ```
 
 ### React Example
@@ -65,8 +84,16 @@ function MyComponent() {
   useEffect(() => {
     const cancelable = makeCancelable(fetchData());
 
-    cancelable.promise
-      .then(setData)
+    // Use the signal with multiple operations
+    const fetchUser = fetch('/api/user', { signal: cancelable.signal });
+    const fetchSettings = fetch('/api/settings', { signal: cancelable.signal });
+
+    Promise.all([cancelable.promise, fetchUser, fetchSettings])
+      .then(([data, user, settings]) => {
+        setData(data);
+        setUser(user);
+        setSettings(settings);
+      })
       .catch(error => {
         if (error instanceof AbortPromiseError) {
           // Handle cancellation
@@ -105,3 +132,29 @@ try {
   }
 }
 ```
+
+### Coordinating Multiple Operations
+
+The `signal` property can be used to coordinate cancellation across multiple operations. This is particularly useful when you need to cancel multiple related operations together:
+
+```typescript
+const cancelable = makeCancelable(fetchData());
+
+// Use the same signal for multiple operations
+const operation1 = new Promise((resolve, reject) => {
+  cancelable.signal.addEventListener('abort', () => {
+    reject(new AbortPromiseError());
+  });
+  // ... operation logic
+});
+
+const operation2 = new Promise((resolve, reject) => {
+  cancelable.signal.addEventListener('abort', () => {
+    reject(new AbortPromiseError());
+  });
+  // ... operation logic
+});
+
+// Cancelling the original promise will also cancel all operations using its signal
+cancelable.cancel();
+```