feat: optimize AbortError

Author: aikoven

src/AbortError.test.ts

@@ -33,3 +33,46 @@ test('catchAbortError', () => {
   expect(() => catchAbortError(new AbortError())).not.toThrow();
   expect(() => catchAbortError(new Error())).toThrow();
 });
+
+test('AbortError with custom message', () => {
+  const error = new AbortError('Custom abort message');
+  expect(error.message).toBe('Custom abort message');
+  expect(error.name).toBe('AbortError');
+});
+
+test('AbortError default message', () => {
+  const error = new AbortError();
+  expect(error.message).toBe('The operation has been aborted');
+  expect(error.name).toBe('AbortError');
+});
+
+test('AbortError with captureStackTrace disabled', () => {
+  const error = new AbortError('Test message', false);
+  expect(error.message).toBe('Test message');
+  expect(error.name).toBe('AbortError');
+  expect(error.stack).toBe(undefined);
+
+  expect(isAbortError(error)).toBe(true);
+  expect(error).toBeInstanceOf(Error);
+  expect(error).toBeInstanceOf(AbortError);
+});
+
+test('AbortError with captureStackTrace enabled', () => {
+  const error = new AbortError('Test message', true);
+  expect(error.message).toBe('Test message');
+  expect(error.name).toBe('AbortError');
+  expect(error.stack).toContain('AbortError: Test message');
+  expect(error.stack).toContain('src/AbortError.test.ts');
+
+  expect(isAbortError(error)).toBe(true);
+  expect(error).toBeInstanceOf(Error);
+  expect(error).toBeInstanceOf(AbortError);
+});
+
+test('throwIfAborted with custom reason', () => {
+  const abortController = new AbortController();
+  const customReason = new Error('Custom reason');
+  abortController.abort(customReason);
+
+  expect(() => throwIfAborted(abortController.signal)).toThrow(AbortError);
+});

src/AbortError.ts

@@ -4,17 +4,23 @@
  * **Warning**: do not use `instanceof` with this class. Instead, use
  * `isAbortError` function.
  */
-export class AbortError extends Error {
-  constructor() {
-    super('The operation has been aborted');
+export class AbortError implements Error {
+  name: 'AbortError' = 'AbortError';
+  stack?: string;
 
-    this.message = 'The operation has been aborted';
+  constructor(
+    public message = 'The operation has been aborted',
+    captureStackTrace = true,
+  ) {
+    if (captureStackTrace) {
+      Error.captureStackTrace?.(this, this.constructor);
+    }
 
-    this.name = 'AbortError';
+    Object.setPrototypeOf(this, Error.prototype);
+  }
 
-    if (typeof Error.captureStackTrace === 'function') {
-      Error.captureStackTrace(this, this.constructor);
-    }
+  static [Symbol.hasInstance](instance: unknown) {
+    return isAbortError(instance);
   }
 }
 

src/all.test.ts

@@ -206,3 +206,94 @@ test('empty', async () => {
   expect(signal.addEventListener).toHaveBeenCalledTimes(0);
   expect(signal.removeEventListener).toHaveBeenCalledTimes(0);
 });
+
+test('abort with custom reason', async () => {
+  const abortController = new AbortController();
+  const signal = abortController.signal;
+
+  const customReason = new Error('Custom abort reason');
+
+  const deferred1 = defer<string>();
+  const deferred2 = defer<number>();
+
+  let innerSignal: AbortSignal;
+
+  const promise = all(signal, signal => {
+    innerSignal = signal;
+    return [deferred1.promise, deferred2.promise];
+  });
+
+  abortController.abort(customReason);
+
+  expect(innerSignal!.aborted).toBe(true);
+
+  // When external signal is aborted with custom reason,
+  // promises should reject with AbortError
+  deferred1.reject(new AbortError());
+  deferred2.reject(new AbortError());
+
+  // The result should be AbortError (first rejection), not custom reason
+  await expect(promise).rejects.toMatchObject({
+    name: 'AbortError',
+  });
+});
+
+test('abort before all with custom reason', async () => {
+  const abortController = new AbortController();
+  const signal = abortController.signal;
+
+  const customReason = new Error('Custom abort reason');
+  abortController.abort(customReason);
+
+  const executor = jest.fn((signal: AbortSignal) => [Promise.resolve('test')]);
+
+  await expect(all(signal, executor)).rejects.toBe(customReason);
+
+  expect(executor).not.toHaveBeenCalled();
+});
+
+test('innerSignal receives custom reason on external abort', async () => {
+  const abortController = new AbortController();
+  const signal = abortController.signal;
+
+  const customReason = new Error('Custom abort reason');
+
+  const deferred1 = defer<string>();
+
+  let innerSignal: AbortSignal;
+
+  all(signal, signal => {
+    innerSignal = signal;
+    return [deferred1.promise];
+  });
+
+  abortController.abort(customReason);
+
+  expect(innerSignal!.aborted).toBe(true);
+  expect(innerSignal!.reason).toBe(customReason);
+});
+
+test('innerSignal receives descriptive reason on promise rejection', async () => {
+  const abortController = new AbortController();
+  const signal = abortController.signal;
+
+  const deferred1 = defer<string>();
+  const deferred2 = defer<number>();
+
+  let innerSignal: AbortSignal;
+
+  all(signal, signal => {
+    innerSignal = signal;
+    return [deferred1.promise, deferred2.promise];
+  });
+
+  deferred1.reject(new Error('test'));
+
+  await nextTick();
+
+  expect(innerSignal!.aborted).toBe(true);
+  expect(innerSignal!.reason).toMatchObject({
+    name: 'AbortError',
+    message: 'One of the promises passed to all() rejected',
+  });
+});

src/all.ts

@@ -143,7 +143,7 @@ export function all<T>(
 ): Promise<T[]> {
   return new Promise((resolve, reject) => {
     if (signal.aborted) {
-      reject(new AbortError());
+      reject(signal.reason ?? new AbortError());
       return;
     }
 
@@ -157,7 +157,7 @@ export function all<T>(
     }
 
     const abortListener = () => {
-      innerAbortController.abort();
+      innerAbortController.abort(signal.reason ?? new AbortError());
     };
 
     signal.addEventListener('abort', abortListener);
@@ -189,7 +189,12 @@ export function all<T>(
           settled();
         },
         reason => {
-          innerAbortController.abort();
+          innerAbortController.abort(
+            new AbortError(
+              'One of the promises passed to all() rejected',
+              false,
+            ),
+          );
 
           if (
             rejection == null ||

src/execute.test.ts

@@ -317,3 +317,99 @@ test('async abort callback rejection', async () => {
   expect(signal.addEventListener).toHaveBeenCalledTimes(1);
   expect(signal.removeEventListener).toHaveBeenCalledTimes(1);
 });
+
+test('abort with custom reason', async () => {
+  const abortController = new AbortController();
+  const signal = abortController.signal;
+
+  const customReason = new Error('Custom abort reason');
+  const callback = jest.fn((reason?: unknown) => {
+    expect(reason).toBe(customReason);
+  });
+
+  let result: PromiseSettledResult<string> | undefined;
+
+  execute<string>(signal, (resolve, reject) => {
+    return callback;
+  }).then(
+    value => {
+      result = {status: 'fulfilled', value};
+    },
+    reason => {
+      result = {status: 'rejected', reason};
+    },
+  );
+
+  abortController.abort(customReason);
+
+  await nextTick();
+
+  expect(callback).toHaveBeenCalledTimes(1);
+  expect(result).toMatchObject({
+    status: 'rejected',
+    reason: customReason,
+  });
+});
+
+test('abort before execute with custom reason', async () => {
+  const abortController = new AbortController();
+  const signal = abortController.signal;
+
+  const customReason = new Error('Custom abort reason');
+  abortController.abort(customReason);
+
+  const executor = jest.fn(
+    (
+      resolve: (value: string) => void,
+      reject: (reason?: any) => void,
+    ): (() => void | PromiseLike<void>) => {
+      return () => {};
+    },
+  );
+
+  await expect(execute(signal, executor)).rejects.toBe(customReason);
+
+  expect(executor).not.toHaveBeenCalled();
+});
+
+test('async abort callback with custom reason', async () => {
+  const abortController = new AbortController();
+  const signal = abortController.signal;
+
+  const customReason = new Error('Custom abort reason');
+  const callbackDeferred = defer<void>();
+
+  const callback = jest.fn((reason?: unknown) => {
+    expect(reason).toBe(customReason);
+    return callbackDeferred.promise;
+  });
+
+  let result: PromiseSettledResult<string> | undefined;
+
+  execute<string>(signal, (resolve, reject) => {
+    return callback;
+  }).then(
+    value => {
+      result = {status: 'fulfilled', value};
+    },
+    reason => {
+      result = {status: 'rejected', reason};
+    },
+  );
+
+  abortController.abort(customReason);
+
+  await nextTick();
+
+  expect(result).toBeUndefined();
+
+  callbackDeferred.resolve();
+
+  await nextTick();
+
+  expect(result).toMatchObject({
+    status: 'rejected',
+    reason: customReason,
+  });
+  expect(callback).toHaveBeenCalledTimes(1);
+});

src/execute.ts

@@ -15,11 +15,11 @@ export function execute<T>(
   executor: (
     resolve: (value: T) => void,
     reject: (reason?: any) => void,
-  ) => () => void | PromiseLike<void>,
+  ) => (reason?: unknown) => void | PromiseLike<void>,
 ): Promise<T> {
   return new Promise<T>((resolve, reject) => {
     if (signal.aborted) {
-      reject(new AbortError());
+      reject(signal.reason ?? new AbortError());
       return;
     }
 
@@ -47,15 +47,15 @@ export function execute<T>(
     );
 
     if (!finished) {
-      const listener = () => {
-        const callbackResult = callback();
+      const abortListener = () => {
+        const callbackResult = callback(signal.reason);
 
         if (callbackResult == null) {
-          reject(new AbortError());
+          reject(signal.reason ?? new AbortError());
         } else {
           callbackResult.then(
             () => {
-              reject(new AbortError());
+              reject(signal.reason ?? new AbortError());
             },
             reason => {
               reject(reason);
@@ -66,10 +66,10 @@ export function execute<T>(
         finish();
       };
 
-      signal.addEventListener('abort', listener);
+      signal.addEventListener('abort', abortListener);
 
       removeAbortListener = () => {
-        signal.removeEventListener('abort', listener);
+        signal.removeEventListener('abort', abortListener);
       };
     }
   });

src/proactiveRetry.ts

@@ -1,4 +1,4 @@
-import {isAbortError, catchAbortError} from './AbortError';
+import {isAbortError, catchAbortError, AbortError} from './AbortError';
 import {delay} from './delay';
 import {execute} from './execute';
 
@@ -48,7 +48,9 @@ export function proactiveRetry<T>(
     const promises = new Map</* attempt */ number, Promise<T>>();
 
     function handleFulfilled(value: T) {
-      innerAbortController.abort();
+      innerAbortController.abort(
+        new AbortError('One of the proactiveRetry() attempts fulfilled', false),
+      );
       promises.clear();
 
       resolve(value);
@@ -71,7 +73,12 @@ export function proactiveRetry<T>(
         try {
           onError(err, attempt);
         } catch (err) {
-          innerAbortController.abort();
+          innerAbortController.abort(
+            new AbortError(
+              'Error was thrown from proactiveRetry() onError callback',
+              false,
+            ),
+          );
           promises.clear();
 
           reject(err);
@@ -103,8 +110,8 @@ export function proactiveRetry<T>(
 
     makeAttempts(innerAbortController.signal).catch(catchAbortError);
 
-    return () => {
-      innerAbortController.abort();
+    return reason => {
+      innerAbortController.abort(reason ?? new AbortError());
     };
   });
 }