feat(make-cancelable): add support for cancelling promises using AbortController

Author: João Dias

cypress/test/functions/utlities/make-cancelable.cy.ts

@@ -3,52 +3,139 @@
  *
  * (c) 2024 Feedzai
  */
-import { makeCancelable } from "src/functions";
+import { AbortPromiseError, makeCancelable, wait } from "src/functions";
+
+async function expectAbort(cancelable: ReturnType<typeof makeCancelable>) {
+  try {
+    await cancelable.promise;
+    throw new Error("Promise should have been rejected");
+  } catch (error) {
+    expect(error).to.be.instanceOf(AbortPromiseError);
+    if (error instanceof AbortPromiseError) {
+      expect(error.message).to.equal("Promise was aborted");
+    }
+  }
+}
 
 describe("makeCancelable", () => {
-  it("should return an object with a promise and a cancel function", () => {
-    const promise = new Promise((resolve) => setTimeout(resolve, 100));
+  // Configure Cypress to not fail on unhandled promise rejections
+  before(() => {
+    cy.on("uncaught:exception", (err) => {
+      if (err.name === "AbortError") {
+        return false;
+      }
+    });
+  });
+
+  it("should reject with AbortPromiseError if cancelled just before resolution", async () => {
+    const promise = wait(10);
+    const cancelable = makeCancelable(promise);
+
+    setTimeout(() => cancelable.cancel(), 5);
+
+    await expectAbort(cancelable);
+  });
+
+  it("should return an object with a promise, cancel function, and isCancelled function", () => {
+    const promise = wait(25);
     const cancelable = makeCancelable(promise);
     expect(cancelable).to.be.an("object");
     expect(cancelable.promise).to.be.a("promise");
     expect(cancelable.cancel).to.be.a("function");
+    expect(cancelable.isCancelled).to.be.a("function");
   });
 
   it("should resolve the promise if not cancelled", async () => {
-    const promise = new Promise((resolve) => setTimeout(resolve, 100));
+    const value = "test value";
+    const promise = new Promise((resolve) => setTimeout(() => resolve(value), 25));
     const cancelable = makeCancelable(promise);
     const result = await cancelable.promise;
-    expect(result).to.be.undefined; // Or any other expected resolved value
+    expect(result).to.equal(value);
   });
 
-  it("should reject the promise with { isCanceled: true } if cancelled", async () => {
-    const promise = new Promise((resolve) => setTimeout(resolve, 100));
+  it("should reject with AbortPromiseError when cancelled", async () => {
+    const promise = wait(25);
     const cancelable = makeCancelable(promise);
     cancelable.cancel();
+
     try {
       await cancelable.promise;
-    } catch (error) {
-      expect(error).to.have.property("isCanceled", true);
+      throw new Error("Promise should have been rejected");
+    } catch (error: unknown) {
+      expect(error).to.be.instanceOf(AbortPromiseError);
+      if (error instanceof AbortPromiseError) {
+        expect(error.message).to.equal("Promise was aborted");
+      }
     }
   });
 
-  it("should not resolve or reject the promise after being cancelled", async () => {
-    cy.window().then(async (win) => {
-      const promise = new win.Promise((resolve) => win.setTimeout(resolve, 100));
-      const cancelable = makeCancelable(promise);
-      cancelable.cancel();
-      const racePromise = win.Promise.race([
-        cancelable.promise.then(() => "resolved"),
-        new win.Promise((resolve) => win.setTimeout(() => resolve("not-resolved"), 200)),
-      ]);
+  it("should handle rejection from the original promise", async () => {
+    const error = new Error("Original promise error");
+    const promise = new Promise((_, reject) => setTimeout(() => reject(error), 25));
+    const cancelable = makeCancelable(promise);
+
+    try {
+      await cancelable.promise;
+      throw new Error("Promise should have been rejected");
+    } catch (caughtError: unknown) {
+      expect(caughtError).to.equal(error);
+    }
+  });
 
-      try {
-        const result = await racePromise;
+  it("should not reject with original error if cancelled", async () => {
+    const error = new Error("Original promise error");
+    const promise = new Promise((_, reject) => setTimeout(() => reject(error), 25));
+    const cancelable = makeCancelable(promise);
+    cancelable.cancel();
 
-        expect(result).to.equal("not-resolved");
-      } catch (error) {
-        console.log(error);
+    try {
+      await cancelable.promise;
+      throw new Error("Promise should have been rejected");
+    } catch (caughtError: unknown) {
+      expect(caughtError).to.be.instanceOf(AbortPromiseError);
+      if (caughtError instanceof AbortPromiseError) {
+        expect(caughtError.message).to.equal("Promise was aborted");
       }
-    });
+    }
+  });
+
+  it("should handle multiple cancel calls", async () => {
+    const promise = wait(25);
+    const cancelable = makeCancelable(promise);
+
+    cancelable.cancel();
+    cancelable.cancel(); // Second call should be ignored
+
+    try {
+      await cancelable.promise;
+      throw new Error("Promise should have been rejected");
+    } catch (error: unknown) {
+      expect(error).to.be.instanceOf(AbortPromiseError);
+    }
+  });
+
+  it("should correctly report cancellation state", async () => {
+    const promise = wait(25);
+    const cancelable = makeCancelable(promise);
+
+    expect(cancelable.isCancelled()).to.be.false;
+    cancelable.cancel();
+    expect(cancelable.isCancelled()).to.be.true;
+  });
+
+  it("should handle abort error message", async () => {
+    const promise = wait(25);
+    const cancelable = makeCancelable(promise);
+    cancelable.cancel();
+
+    try {
+      await cancelable.promise;
+      throw new Error("Promise should have been rejected");
+    } catch (error: unknown) {
+      expect(error).to.be.instanceOf(AbortPromiseError);
+      if (error instanceof AbortPromiseError) {
+        expect(error.message).to.equal("Promise was aborted");
+      }
+    }
   });
 });

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

@@ -1,28 +1,107 @@
 ---
 title: makeCancelable
 ---
-Wraps a native Promise and allows it to be cancelled.
+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.
 
 ## API
 
 ```typescript
-function makeCancelable<GenericPromiseValue = unknown>(promise: Promise<GenericPromiseValue>): MakeCancelablePromise<GenericPromiseValue>;
+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.
+   */
+  cancel: () => void;
+  /**
+   * Checks whether the promise has been cancelled
+   */
+  isCancelled: () => boolean;
+}
+
+function makeCancelable<T = unknown>(promise: Promise<T>): MakeCancelablePromise<T>;
 ```
 
 ### Usage
 
 ```tsx
-import { wait } from '@feedzai/js-utilities';
+import { makeCancelable, wait } from '@feedzai/js-utilities';
 
 // A Promise that resolves after 1 second
 const somePromise = wait(1000);
 
-// Can also be made cancellable by wrapping it
+// Make it cancelable
 const cancelable = makeCancelable(somePromise);
 
-// So that when we execute said wrapped promise...
-cancelable.promise.then(console.log).catch(({ isCanceled }) => console.error('isCanceled', isCanceled));
+// Execute the wrapped promise
+cancelable.promise
+  .then(console.log)
+  .catch(error => {
+    if (error instanceof AbortPromiseError) {
+      console.log('Promise was cancelled');
+    } else {
+      console.error('Other error:', error);
+    }
+  });
 
-// We can cancel it on demand
+// Cancel it when needed
 cancelable.cancel();
+
+// Check if already cancelled
+if (cancelable.isCancelled()) {
+  console.log('Promise was already cancelled');
+}
+```
+
+### React Example
+
+```tsx
+import { makeCancelable } from '@feedzai/js-utilities';
+import { useEffect } from 'react';
+
+function MyComponent() {
+  useEffect(() => {
+    const cancelable = makeCancelable(fetchData());
+
+    cancelable.promise
+      .then(setData)
+      .catch(error => {
+        if (error instanceof AbortPromiseError) {
+          // Handle cancellation
+          console.log('Data fetch was cancelled');
+        } else {
+          // Handle other errors
+          console.error('Error fetching data:', error);
+        }
+      });
+
+    // Cleanup on unmount
+    return () => cancelable.cancel();
+  }, []);
+
+  return <div>...</div>;
+}
+```
+
+### Error Handling
+
+When a promise is cancelled, it rejects with an `AbortPromiseError`. This error extends `DOMException` and has the following properties:
+
+- `name`: "AbortError"
+- `message`: "Promise was aborted"
+
+You can check for cancellation by using `instanceof`:
+
+```typescript
+try {
+  await cancelable.promise;
+} catch (error) {
+  if (error instanceof AbortPromiseError) {
+    // Handle cancellation
+  } else {
+    // Handle other errors
+  }
+}
 ```