feat: Add AbortSignal.any(signals), signal.throwIfAborted() and AbortSignal.timeout(time)

Author: retyui

packages/react-native/src/private/webapis/dom/abort-api/AbortController.js

@@ -27,8 +27,8 @@ export class AbortController {
   /**
    * Abort and signal to any observers that the associated activity is to be aborted.
    */
-  abort(): void {
-    abortSignal(getSignal(this));
+  abort(reason: unknown): void {
+    abortSignal(reason, getSignal(this));
   }
 }
 

packages/react-native/src/private/webapis/dom/abort-api/AbortSignal.js

@@ -2,16 +2,83 @@
  * @flow strict
  * @format
  */
+import DOMException from '../../errors/DOMException'
 import Event from '../events/Event';
 import EventTarget from '../events/EventTarget'
+import {AbortController} from './AbortController';
 
+const reasons = new WeakMap<AbortSignal, unknown>();
 
 
 /**
  * The signal class.
  * @see https://dom.spec.whatwg.org/#abortsignal
  */
 export class AbortSignal extends EventTarget {
+  /**
+   *  AbortSignal.timeout static method
+   *   Docs: https:developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static
+   *   Spec: https://dom.spec.whatwg.org/#dom-abortsignal-timeout
+   */
+  static timeout(timeInMs: number): AbortSignal {
+    if (!(timeInMs >= 0)) {
+      throw new TypeError(
+        "Failed to execute 'timeout' on 'AbortSignal': The provided value have to be a non-negative number.",
+      );
+    }
+    const controller = new AbortController();
+    setTimeout(
+      () =>
+        controller.abort(new DOMException('signal timed out', 'TimeoutError')),
+      timeInMs,
+    );
+    return controller.signal;
+  }
+
+  /**
+   * 3. AbortSignal.any static method
+   *  Docs: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/any_static
+   *  Spec: https://dom.spec.whatwg.org/#dom-abortsignal-any
+   */
+  static any(signals: AbortSignal[]): AbortSignal {
+    if (!Array.isArray(signals)) {
+      throw new Error('The signals value must be an instance of Array');
+    }
+
+    const controller = new AbortController();
+    const listeners = [];
+    const cleanup = () => listeners.forEach(unsubscribe => unsubscribe());
+
+    for (let i = 0; i < signals.length; i++) {
+      const signal = signals[i];
+
+      // Validate that each item is an AbortSignal
+      if (!(signal instanceof AbortSignal)) {
+        cleanup(); // Remove all listeners added so far
+        throw new Error(
+          'The "signals[' +
+            i +
+            ']" argument must be an instance of AbortSignal',
+        );
+      }
+
+      // Abort immediately if one of the signals is already aborted
+      if (signal.aborted) {
+        cleanup(); // Remove all listeners added so far
+        controller.abort(signal.reason);
+        break;
+      }
+
+      const onAbort = () => {
+        controller.abort(signal.reason);
+        cleanup();
+      };
+      signal.addEventListener('abort', onAbort);
+      listeners.push(() => signal.removeEventListener('abort', onAbort));
+    }
+    return controller.signal;
+  }
+
   /**
    * AbortSignal cannot be constructed directly.
    */
@@ -36,6 +103,17 @@ export class AbortSignal extends EventTarget {
     }
     return aborted;
   }
+
+  // $FlowExpectedError[unsafe-getters-setters]
+  get reason(): unknown {
+    return reasons.get(this);
+  }
+
+  throwIfAborted(): void {
+    if (this.aborted) {
+      throw this.reason;
+    }
+  }
 }
 
 const listeners = new WeakMap<AbortSignal, (()=> void)>();
@@ -83,12 +161,16 @@ export function createAbortSignal(): AbortSignal {
 /**
  * Abort a given signal.
  */
-export function abortSignal(signal: AbortSignal): void {
+export function abortSignal(
+  reason: unknown | void = new DOMException('signal is aborted without reason', 'AbortError'),
+  signal: AbortSignal,
+): void {
   if (abortedFlags.get(signal) !== false) {
     return;
   }
 
   abortedFlags.set(signal, true);
+  reasons.set(signal, reason);
   // $FlowExpectedError[incompatible-type]
   signal.dispatchEvent(new Event('abort'));
 }
@@ -102,6 +184,7 @@ const abortedFlags = new WeakMap<AbortSignal, boolean>()
 //$FlowExpectedError[cannot-write]
 Object.defineProperties(AbortSignal.prototype, {
   aborted: {enumerable: true},
+  reason: {enumerable: true},
 });
 
 

packages/react-native/src/private/webapis/dom/abort-api/__tests__/abort-api-test.js

@@ -8,8 +8,7 @@
  * @format
  */
 
-import '@react-native/fantom/src/setUpDefaultReactNativeEnvironment';
-
+import DOMException from '../../../errors/DOMException';
 import {AbortController} from '../AbortController';
 import {AbortSignal} from '../AbortSignal';
 import Event from 'react-native/src/private/webapis/dom/events/Event';
@@ -58,6 +57,7 @@ describe('AbortController', () => {
 
   it('should not be callable', () => {
     expect(() => {
+      // $FlowExpectedError[prop-missing]
       // $FlowExpectedError[constructor-as-function]
       AbortController();
     }).toThrow(TypeError);
@@ -75,6 +75,7 @@ describe('AbortController', () => {
   });
 
   it('should be stringified as [object AbortController]', () => {
+    // $FlowExpectedError[method-unbinding]
     expect(Object.prototype.toString.call(controller)).toBe(
       '[object AbortController]',
     );
@@ -103,11 +104,9 @@ describe('AbortController', () => {
       const keys = new Set([
         'aborted',
         'onabort',
-        // TODO
-        // 'reason',
+        'reason',
+        // TODO: The modern class syntax was specifically designed to prevent this, ensuring methods don't "pollute" standard loops.
         // 'throwIfAborted',
-        // 'when',
-        // TODO: Problem with EventTarget: the modern class syntax was specifically designed to prevent this, ensuring methods don't "pollute" standard loops.
         // 'addEventListener',
         // 'dispatchEvent',
         // 'removeEventListener',
@@ -125,7 +124,12 @@ describe('AbortController', () => {
       expect(signal.aborted).toBe(false);
     });
 
+    it("should have 'reason' property which is undefined by default", () => {
+      expect(signal.reason).toBe(undefined);
+    });
+
     it("should have 'onabort' property which is null by default", () => {
+      // $FlowExpectedError[prop-missing]
       expect(signal.onabort).toBe(null);
     });
 
@@ -144,6 +148,7 @@ describe('AbortController', () => {
     });
 
     it('should be stringified as [object AbortSignal]', () => {
+      // $FlowExpectedError[method-unbinding]
       expect(Object.prototype.toString.call(signal)).toBe(
         '[object AbortSignal]',
       );
@@ -156,6 +161,45 @@ describe('AbortController', () => {
       expect(controller.signal.aborted).toBe(true);
     });
 
+    it("should set default 'reason' when called without an argument", () => {
+      controller.abort();
+
+      expect(controller.signal.reason).toBeInstanceOf(DOMException);
+      expect(controller.signal.reason).toMatchObject({
+        name: 'AbortError',
+        message: 'signal is aborted without reason',
+      });
+    });
+
+    it("should set the provided 'reason' when called with an argument", () => {
+      const reason = new Error('boom');
+
+      controller.abort(reason);
+
+      expect(controller.signal.reason).toBe(reason);
+    });
+
+    it("should make 'throwIfAborted' throw the abort reason", () => {
+      const reason = {message: 'boom'};
+
+      controller.abort(reason);
+
+      let thrown;
+      try {
+        controller.signal.throwIfAborted();
+      } catch (error) {
+        thrown = error;
+      }
+
+      expect(thrown).toBe(reason);
+    });
+
+    it("should not throw from 'throwIfAborted' before aborting", () => {
+      expect(() => {
+        controller.signal.throwIfAborted();
+      }).not.toThrow();
+    });
+
     it("should fire 'abort' event on 'signal' (addEventListener)", () => {
       const listener = createListener();
       controller.signal.addEventListener('abort', listener);
@@ -167,6 +211,7 @@ describe('AbortController', () => {
     it("should fire 'abort' event on 'signal' (onabort)", () => {
       const listener = createListener();
       // $FlowExpectedError[incompatible-type]
+      // $FlowExpectedError[prop-missing]
       controller.signal.onabort = listener;
       controller.abort();
 
@@ -186,15 +231,79 @@ describe('AbortController', () => {
 
     it("should throw a TypeError if 'this' is not an AbortController object", () => {
       expect(() => {
+        // $FlowExpectedError[method-unbinding]
         controller.abort.call({});
       }).toThrow(TypeError);
     });
   });
+
+  describe("'any' static method", () => {
+    it("should abort when one of the provided signals aborts", () => {
+      const first = new AbortController();
+      const second = new AbortController();
+      const reason = new Error('stop');
+
+      const signal = AbortSignal.any([first.signal, second.signal]);
+
+      expect(signal).toBeInstanceOf(AbortSignal);
+      expect(signal.aborted).toBe(false);
+
+      second.abort(reason);
+
+      expect(signal.aborted).toBe(true);
+      expect(signal.reason).toBe(reason);
+    });
+
+    it("should abort immediately if one of the provided signals is already aborted", () => {
+      const first = new AbortController();
+      const second = new AbortController();
+      const reason = new Error('already aborted');
+
+      second.abort(reason);
+
+      const signal = AbortSignal.any([first.signal, second.signal]);
+
+      expect(signal.aborted).toBe(true);
+      expect(signal.reason).toBe(reason);
+    });
+  });
+
+  describe("'timeout' static method", () => {
+    beforeEach(() => {
+      jest.useFakeTimers();
+    });
+
+    afterEach(() => {
+      jest.useRealTimers();
+    });
+
+    it("should abort after the timeout with a TimeoutError reason", () => {
+      const signal = AbortSignal.timeout(10);
+
+      expect(signal.aborted).toBe(false);
+
+      jest.advanceTimersByTime(10);
+
+      expect(signal.aborted).toBe(true);
+      expect(signal.reason).toBeInstanceOf(DOMException);
+      expect(signal.reason).toMatchObject({
+        name: 'TimeoutError',
+        message: 'signal timed out',
+      });
+    });
+
+    it("should throw a TypeError for a negative timeout", () => {
+      expect(() => {
+        AbortSignal.timeout(-1);
+      }).toThrow(TypeError);
+    });
+  });
 });
 
 describe('AbortSignal', () => {
   it('should not be callable', () => {
     expect(() => {
+      // $FlowExpectedError[prop-missing]
       // $FlowExpectedError[constructor-as-function]
       AbortSignal();
     }).toThrow(TypeError);

packages/react-native/src/types/globals.d.ts

@@ -626,6 +626,26 @@ declare global {
             capture?: boolean | undefined;
           },
     ) => void;
+
+    /**
+     * Throws the abort reason if the signal has been aborted.
+     * Otherwise, does nothing.
+     *
+     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/throwIfAborted)
+     */
+    throwIfAborted(): void;
+    /**
+     * The **`AbortSignal.any()`** static method takes an iterable of abort signals and returns an AbortSignal.
+     *
+     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/any_static)
+     */
+    static any(signals: AbortSignal[]): AbortSignal;
+    /**
+     * The **`AbortSignal.timeout()`** static method returns an AbortSignal that will automatically abort after a specified time.
+     *
+     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/timeout_static)
+     */
+    static timeout(milliseconds: number): AbortSignal;
   }
 
   class AbortController {
@@ -640,7 +660,7 @@ declare global {
     /**
      * Abort and signal to any observers that the associated activity is to be aborted.
      */
-    abort(): void;
+    abort(reason?: any): void;
   }
 
   interface FileReaderEventMap {

packages/react-native/types/__typetests__/globals.tsx

@@ -142,11 +142,13 @@ const fetchCopy: WindowOrWorkerGlobalScope['fetch'] = fetch;
 const myHeaders = new Headers();
 myHeaders.append('Content-Type', 'image/jpeg');
 
+const controller = new AbortController();
+
 const myInit: RequestInit = {
     method: 'GET',
     headers: myHeaders,
     mode: 'cors',
-    signal: new AbortSignal(),
+  signal: AbortSignal.any([controller.signal, AbortSignal.timeout(5000)]),
 };
 
 const myRequest = new Request('flowers.jpg');