feat(waiter-utils): adding reasons for waiter states and exceptions

Author: alexforsyth

packages/util-waiter/src/createWaiter.ts

@@ -34,5 +34,10 @@ export const createWaiter = async <Client, Input>(
   if (options.abortController) {
     exitConditions.push(abortTimeout(options.abortController.signal));
   }
+
+  if (options.abortSignal) {
+    exitConditions.push(abortTimeout(options.abortSignal));
+  }
+
   return Promise.race(exitConditions);
 };

packages/util-waiter/src/poller.ts

@@ -21,7 +21,7 @@ const randomInRange = (min: number, max: number) => min + Math.random() * (max -
  * @param stateChecker function that checks the acceptor states on each poll.
  */
 export const runPolling = async <Client, Input>(
-  { minDelay, maxDelay, maxWaitTime, abortController, client }: WaiterOptions<Client>,
+  { minDelay, maxDelay, maxWaitTime, abortController, client, abortSignal }: WaiterOptions<Client>,
   input: Input,
   acceptorChecks: (client: Client, input: Input) => Promise<WaiterResult>
 ): Promise<WaiterResult> => {
@@ -36,7 +36,7 @@ export const runPolling = async <Client, Input>(
   // Pre-compute this number to avoid Number type overflow.
   const attemptCeiling = Math.log(maxDelay / minDelay) / Math.log(2) + 1;
   while (true) {
-    if (abortController?.signal?.aborted) {
+    if (abortController?.signal?.aborted || abortSignal?.aborted) {
       return { state: WaiterState.ABORTED };
     }
     const delay = exponentialBackoffWithJitter(minDelay, maxDelay, attemptCeiling, currentAttempt);

packages/util-waiter/src/waiter.ts

@@ -12,10 +12,16 @@ export interface WaiterConfiguration<Client> {
   maxWaitTime: number;
 
   /**
+   * @deprecated Use abortSignal
    * Abort controller. Used for ending the waiter early.
    */
   abortController?: AbortController;
 
+  /**
+   * Abort Signal. Used for ending the waiter early.
+   */
+  abortSignal?: AbortController["signal"];
+
   /**
    * The minimum amount of time to delay between retries in seconds. This is the
    * floor of the exponential backoff. This value defaults to service default
@@ -55,4 +61,28 @@ export enum WaiterState {
 
 export type WaiterResult = {
   state: WaiterState;
+
+  /**
+   * (optional) Indicates a reason for why a waiter has reached its state.
+   */
+  reason?: any;
+};
+
+/**
+ * Handles and throws exceptions resulting from the waiterResult
+ * @param result WaiterResult
+ */
+export const checkExceptions = (result: WaiterResult): WaiterResult => {
+  if (result.state === WaiterState.ABORTED) {
+    throw new Error(
+      `${JSON.stringify({
+        ...result,
+        name: "AbortError",
+        reason: "Request was aborted",
+      })}`
+    );
+  } else if (result.state !== WaiterState.SUCCESS) {
+    throw new Error(`${JSON.stringify({ result })}`);
+  }
+  return result;
 };