@azure/abort-controller 1.0.0-preview.1

package/src/AbortController.ts

@@ -0,0 +1,133 @@
+import { AbortSignal, abortSignal, AbortSignalLike } from "./AbortSignal";
+
+/**
+ * This error is thrown when an asynchronous operation has been aborted.
+ * Check for this error by testing the `name` that the name property of the
+ * error matches `"AbortError"`.
+ *
+ * @example
+ * const controller = new AbortController();
+ * controller.abort();
+ * try {
+ *   doAsyncWork(controller.signal)
+ * } catch (e) {
+ *   if (e.name === 'AbortError') {
+ *     // handle abort error here.
+ *   }
+ * }
+ */
+export class AbortError extends Error {
+  constructor(message?: string) {
+    super(message);
+    this.name = "AbortError";
+  }
+}
+
+/**
+ * An AbortController provides an AbortSignal and the associated controls to signal
+ * that an asynchronous operation should be aborted.
+ *
+ * @example
+ * // Abort an operation when another event fires
+ * const controller = new AbortController();
+ * const signal = controller.signal;
+ * doAsyncWork(signal);
+ * button.addEventListener('click', () => controller.abort());
+ *
+ * @example
+ * // Share aborter cross multiple operations in 30s
+ * // Upload the same data to 2 different data centers at the same time,
+ * // abort another when any of them is finished
+ * const controller = AbortController.withTimeout(30 * 1000);
+ * doAsyncWork(controller.signal).then(controller.abort);
+ * doAsyncWork(controller.signal).then(controller.abort);
+ *
+ * @example
+ * // Cascaded aborting
+ * // All operations can't take more than 30 seconds
+ * const aborter = Aborter.timeout(30 * 1000);
+ *
+ * // Following 2 operations can't take more than 25 seconds
+ * await doAsyncWork(aborter.withTimeout(25 * 1000));
+ * await doAsyncWork(aborter.withTimeout(25 * 1000));
+ *
+ * @export
+ * @class AbortController
+ * @implements {AbortSignalLike}
+ */
+export class AbortController {
+  private _signal: AbortSignal;
+
+  /**
+   * @param {AbortSignalLike[]} [parentSignals] The AbortSignals that will signal aborted on the AbortSignal associated with this controller.
+   * @constructor
+   */
+  constructor(parentSignals?: AbortSignalLike[]);
+  /**
+   * @param {...AbortSignalLike} parentSignals The AbortSignals that will signal aborted on the AbortSignal associated with this controller.
+   * @constructor
+   */
+  constructor(...parentSignals: AbortSignalLike[]);
+  constructor(parentSignals?: any) {
+    this._signal = new AbortSignal();
+
+    if (!parentSignals) {
+      return;
+    }
+    // coerce parentSignals into an array
+    if (!Array.isArray(parentSignals)) {
+      parentSignals = arguments;
+    }
+    for (const parentSignal of parentSignals) {
+      // if the parent signal has already had abort() called,
+      // then call abort on this signal as well.
+      if (parentSignal.aborted) {
+        this.abort();
+      } else {
+        // when the parent signal aborts, this signal should as well.
+        parentSignal.addEventListener("abort", () => {
+          this.abort();
+        });
+      }
+    }
+  }
+
+  /**
+   * The AbortSignal associated with this controller that will signal aborted
+   * when the abort method is called on this controller.
+   *
+   * @readonly
+   * @type {AbortSignal}
+   * @memberof AbortController
+   */
+  public get signal() {
+    return this._signal;
+  }
+
+  /**
+   * Signal that any operations passed this controller's associated abort signal
+   * to cancel any remaining work and throw an `AbortError`.
+   *
+   * @memberof AbortController
+   */
+  abort() {
+    abortSignal(this._signal);
+  }
+
+  /**
+   * Creates a new AbortSignal instance that will abort after the provided ms.
+   *
+   * @static
+   * @params {number} ms Elapsed time in milliseconds to trigger an abort.
+   * @returns {AbortSignal}
+   */
+  public static timeout(ms: number): AbortSignal {
+    const signal = new AbortSignal();
+    const timer = setTimeout(abortSignal, ms, signal);
+    // Prevent the active Timer from keeping the Node.js event loop active.
+    if (typeof timer.unref === "function") {
+      timer.unref();
+    }
+    return signal;
+  }
+}

package/src/AbortSignal.ts

@@ -0,0 +1,159 @@
+/// <reference path="./shims-public.d.ts" />
+type AbortEventListener = (this: AbortSignalLike, ev?: any) => any;
+
+const listenersMap = new WeakMap<AbortSignal, AbortEventListener[]>();
+const abortedMap = new WeakMap<AbortSignal, boolean>();
+
+/**
+ * Allows the request to be aborted upon firing of the "abort" event.
+ * Compatible with the browser built-in AbortSignal and common polyfills.
+ */
+export interface AbortSignalLike {
+  /**
+   * Indicates if the signal has already been aborted.
+   */
+  readonly aborted: boolean;
+  /**
+   * Add new "abort" event listener, only support "abort" event.
+   */
+  addEventListener(
+    type: "abort",
+    listener: (this: AbortSignalLike, ev: any) => any,
+    options?: any
+  ): void;
+  /**
+   * Remove "abort" event listener, only support "abort" event.
+   */
+  removeEventListener(
+    type: "abort",
+    listener: (this: AbortSignalLike, ev: any) => any,
+    options?: any
+  ): void;
+}
+
+/**
+ * An aborter instance implements AbortSignal interface, can abort HTTP requests.
+ *
+ * - Call AbortSignal.none to create a new AbortSignal instance that cannot be cancelled.
+ * Use `AbortSignal.none` when you are required to pass a cancellation token but the operation
+ * cannot or will not ever be cancelled.
+ *
+ * @example
+ * // Abort without timeout
+ * await doAsyncWork(AbortSignal.none);
+ *
+ * @export
+ * @class AbortSignal
+ * @implements {AbortSignalLike}
+ */
+export class AbortSignal implements AbortSignalLike {
+  constructor() {
+    listenersMap.set(this, []);
+    abortedMap.set(this, false);
+  }
+
+  /**
+   * Status of whether aborted or not.
+   *
+   * @readonly
+   * @type {boolean}
+   * @memberof AbortSignal
+   */
+  public get aborted(): boolean {
+    if (!abortedMap.has(this)) {
+      throw new TypeError("Expected `this` to be an instance of AbortSignal.");
+    }
+
+    return abortedMap.get(this)!;
+  }
+
+  /**
+   * Creates a new AbortSignal instance that will never be aborted.
+   *
+   * @readonly
+   * @static
+   * @type {AbortSignal}
+   * @memberof AbortSignal
+   */
+  public static get none(): AbortSignal {
+    return new AbortSignal();
+  }
+
+  /**
+   * onabort event listener.
+   *
+   * @memberof AbortSignal
+   */
+  public onabort?: (ev?: Event) => any;
+
+  /**
+   * Added new "abort" event listener, only support "abort" event.
+   *
+   * @param {"abort"} _type Only support "abort" event
+   * @param {(this: AbortSignalLike, ev: any) => any} listener
+   * @memberof AbortSignal
+   */
+  public addEventListener(
+    // tslint:disable-next-line:variable-name
+    _type: "abort",
+    listener: (this: AbortSignalLike, ev: any) => any
+  ): void {
+    if (!listenersMap.has(this)) {
+      throw new TypeError("Expected `this` to be an instance of AbortSignal.");
+    }
+
+    const listeners = listenersMap.get(this)!;
+    listeners.push(listener);
+  }
+
+  /**
+   * Remove "abort" event listener, only support "abort" event.
+   *
+   * @param {"abort"} _type Only support "abort" event
+   * @param {(this: AbortSignalLike, ev: any) => any} listener
+   * @memberof AbortSignal
+   */
+  public removeEventListener(
+    // tslint:disable-next-line:variable-name
+    _type: "abort",
+    listener: (this: AbortSignalLike, ev: any) => any
+  ): void {
+    if (!listenersMap.has(this)) {
+      throw new TypeError("Expected `this` to be an instance of AbortSignal.");
+    }
+
+    const listeners = listenersMap.get(this)!;
+
+    const index = listeners.indexOf(listener);
+    if (index > -1) {
+      listeners.splice(index, 1);
+    }
+  }
+}
+
+/**
+ * Helper to trigger an abort event immediately, the onabort and all abort event listeners will be triggered.
+ * Will try to trigger abort event for all linked AbortSignal nodes.
+ *
+ * - If there is a timeout, the timer will be cancelled.
+ * - If aborted is true, nothing will happen.
+ *
+ * @returns
+ * @internal
+ */
+export function abortSignal(signal: AbortSignal) {
+  if (signal.aborted) {
+    return;
+  }
+
+  if (signal.onabort) {
+    signal.onabort.call(signal);
+  }
+
+  const listeners = listenersMap.get(signal)!;
+  listeners.forEach((listener) => {
+    listener.call(signal);
+  });
+
+  abortedMap.set(signal, true);
+}

package/src/aborter.ts

@@ -0,0 +1,13 @@
+/// <reference lib="es5" />
+
+// Changes to Aborter
+// * Rename Aborter to AbortSignal
+// * Remove withValue and getValue - async context should be solved differently/wholistically, not tied to cancellation
+// * Remove withTimeout, it's moved to the controller
+// * AbortSignal constructor no longer takes a parent. Cancellation graphs are created from the controller.
+
+// Potential changes to align with DOM Spec
+// * dispatchEvent on Signal
+
+export { AbortController, AbortError } from "./AbortController";
+export { AbortSignal, AbortSignalLike } from "./AbortSignal";

package/src/shims-public.d.ts

@@ -0,0 +1,2 @@
+// forward declaration of Event in case DOM libs are not present.
+interface Event {}

package/tsconfig.json

@@ -0,0 +1,32 @@
+{
+  "compilerOptions": {
+    /* Basic Options */
+    "target": "es5" /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017','ES2018' or 'ESNEXT'. */,
+    "module": "es6" /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', or 'ESNext'. */,
+    "lib": [] /* lib dependencies are triple-slash directives in lib/index.ts */,
+    "declaration": true /* Generates corresponding '.d.ts' file. */,
+    "declarationMap": true /* Generates a sourcemap for each corresponding '.d.ts' file. */,
+    "sourceMap": true /* Generates corresponding '.map' file. */,
+    "outDir": "./dist-esm" /* Redirect output structure to the directory. */,
+    "stripInternal": true /* Do not emit declarations for code with @internal annotation*/,
+    "declarationDir": "./types" /* Output directory for generated declaration files.*/,
+    "importHelpers": true /* Import emit helpers from 'tslib'. */,
+    /* Strict Type-Checking Options */
+    "strict": true /* Enable all strict type-checking options. */,
+    "noImplicitReturns": true /* Report error when not all code paths in function return a value. */,
+    /* Additional Checks */
+    "noUnusedLocals": true /* Report errors on unused locals. */,
+    /* Module Resolution Options */
+    "moduleResolution": "node" /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */,
+    "allowSyntheticDefaultImports": true /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */,
+    "esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */,
+    /* Experimental Options */
+    "forceConsistentCasingInFileNames": true,
+    /* Other options */
+    "newLine": "LF" /*	Use the specified end of line sequence to be used when emitting files: "crlf" (windows) or "lf" (unix).”*/,
+    "allowJs": false /* Don't allow JavaScript files to be compiled.*/
+  },
+  "compileOnSave": true,
+  "exclude": ["node_modules", "./types/**/*.d.ts", "./samples/**/*.ts"],
+  "include": ["./src/**/*.ts", "./test/**/*.ts"]
+}

package/types/src/AbortController.d.ts

@@ -0,0 +1,90 @@
+import { AbortSignal, AbortSignalLike } from "./AbortSignal";
+/**
+ * This error is thrown when an asynchronous operation has been aborted.
+ * Check for this error by testing the `name` that the name property of the
+ * error matches `"AbortError"`.
+ *
+ * @example
+ * const controller = new AbortController();
+ * controller.abort();
+ * try {
+ *   doAsyncWork(controller.signal)
+ * } catch (e) {
+ *   if (e.name === 'AbortError') {
+ *     // handle abort error here.
+ *   }
+ * }
+ */
+export declare class AbortError extends Error {
+    constructor(message?: string);
+}
+/**
+ * An AbortController provides an AbortSignal and the associated controls to signal
+ * that an asynchronous operation should be aborted.
+ *
+ * @example
+ * // Abort an operation when another event fires
+ * const controller = new AbortController();
+ * const signal = controller.signal;
+ * doAsyncWork(signal);
+ * button.addEventListener('click', () => controller.abort());
+ *
+ * @example
+ * // Share aborter cross multiple operations in 30s
+ * // Upload the same data to 2 different data centers at the same time,
+ * // abort another when any of them is finished
+ * const controller = AbortController.withTimeout(30 * 1000);
+ * doAsyncWork(controller.signal).then(controller.abort);
+ * doAsyncWork(controller.signal).then(controller.abort);
+ *
+ * @example
+ * // Cascaded aborting
+ * // All operations can't take more than 30 seconds
+ * const aborter = Aborter.timeout(30 * 1000);
+ *
+ * // Following 2 operations can't take more than 25 seconds
+ * await doAsyncWork(aborter.withTimeout(25 * 1000));
+ * await doAsyncWork(aborter.withTimeout(25 * 1000));
+ *
+ * @export
+ * @class AbortController
+ * @implements {AbortSignalLike}
+ */
+export declare class AbortController {
+    private _signal;
+    /**
+     * @param {AbortSignalLike[]} [parentSignals] The AbortSignals that will signal aborted on the AbortSignal associated with this controller.
+     * @constructor
+     */
+    constructor(parentSignals?: AbortSignalLike[]);
+    /**
+     * @param {...AbortSignalLike} parentSignals The AbortSignals that will signal aborted on the AbortSignal associated with this controller.
+     * @constructor
+     */
+    constructor(...parentSignals: AbortSignalLike[]);
+    /**
+     * The AbortSignal associated with this controller that will signal aborted
+     * when the abort method is called on this controller.
+     *
+     * @readonly
+     * @type {AbortSignal}
+     * @memberof AbortController
+     */
+    readonly signal: AbortSignal;
+    /**
+     * Signal that any operations passed this controller's associated abort signal
+     * to cancel any remaining work and throw an `AbortError`.
+     *
+     * @memberof AbortController
+     */
+    abort(): void;
+    /**
+     * Creates a new AbortSignal instance that will abort after the provided ms.
+     *
+     * @static
+     * @params {number} ms Elapsed time in milliseconds to trigger an abort.
+     * @returns {AbortSignal}
+     */
+    static timeout(ms: number): AbortSignal;
+}
+//# sourceMappingURL=AbortController.d.ts.map

package/types/src/AbortController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbortController.d.ts","sourceRoot":"","sources":["../../src/AbortController.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAe,eAAe,EAAE,MAAM,eAAe,CAAC;AAE1E;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,CAAC,EAAE,MAAM;CAI7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAAc;IAE7B;;;OAGG;gBACS,aAAa,CAAC,EAAE,eAAe,EAAE;IAC7C;;;OAGG;gBACS,GAAG,aAAa,EAAE,eAAe,EAAE;IAyB/C;;;;;;;OAOG;aACQ,MAAM;IAIjB;;;;;OAKG;IACH,KAAK;IAIL;;;;;;OAMG;WACW,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW;CAS/C"}

package/types/src/AbortSignal.d.ts

@@ -0,0 +1,77 @@
+/// <reference path="../../src/shims-public.d.ts" />
+/**
+ * Allows the request to be aborted upon firing of the "abort" event.
+ * Compatible with the browser built-in AbortSignal and common polyfills.
+ */
+export interface AbortSignalLike {
+    /**
+     * Indicates if the signal has already been aborted.
+     */
+    readonly aborted: boolean;
+    /**
+     * Add new "abort" event listener, only support "abort" event.
+     */
+    addEventListener(type: "abort", listener: (this: AbortSignalLike, ev: any) => any, options?: any): void;
+    /**
+     * Remove "abort" event listener, only support "abort" event.
+     */
+    removeEventListener(type: "abort", listener: (this: AbortSignalLike, ev: any) => any, options?: any): void;
+}
+/**
+ * An aborter instance implements AbortSignal interface, can abort HTTP requests.
+ *
+ * - Call AbortSignal.none to create a new AbortSignal instance that cannot be cancelled.
+ * Use `AbortSignal.none` when you are required to pass a cancellation token but the operation
+ * cannot or will not ever be cancelled.
+ *
+ * @example
+ * // Abort without timeout
+ * await doAsyncWork(AbortSignal.none);
+ *
+ * @export
+ * @class AbortSignal
+ * @implements {AbortSignalLike}
+ */
+export declare class AbortSignal implements AbortSignalLike {
+    constructor();
+    /**
+     * Status of whether aborted or not.
+     *
+     * @readonly
+     * @type {boolean}
+     * @memberof AbortSignal
+     */
+    readonly aborted: boolean;
+    /**
+     * Creates a new AbortSignal instance that will never be aborted.
+     *
+     * @readonly
+     * @static
+     * @type {AbortSignal}
+     * @memberof AbortSignal
+     */
+    static readonly none: AbortSignal;
+    /**
+     * onabort event listener.
+     *
+     * @memberof AbortSignal
+     */
+    onabort?: (ev?: Event) => any;
+    /**
+     * Added new "abort" event listener, only support "abort" event.
+     *
+     * @param {"abort"} _type Only support "abort" event
+     * @param {(this: AbortSignalLike, ev: any) => any} listener
+     * @memberof AbortSignal
+     */
+    addEventListener(_type: "abort", listener: (this: AbortSignalLike, ev: any) => any): void;
+    /**
+     * Remove "abort" event listener, only support "abort" event.
+     *
+     * @param {"abort"} _type Only support "abort" event
+     * @param {(this: AbortSignalLike, ev: any) => any} listener
+     * @memberof AbortSignal
+     */
+    removeEventListener(_type: "abort", listener: (this: AbortSignalLike, ev: any) => any): void;
+}
+//# sourceMappingURL=AbortSignal.d.ts.map

package/types/src/AbortSignal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbortSignal.d.ts","sourceRoot":"","sources":["../../src/AbortSignal.ts"],"names":[],"mappings":";AAMA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;OAEG;IACH,gBAAgB,CACd,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,GAAG,KAAK,GAAG,EACjD,OAAO,CAAC,EAAE,GAAG,GACZ,IAAI,CAAC;IACR;;OAEG;IACH,mBAAmB,CACjB,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,GAAG,KAAK,GAAG,EACjD,OAAO,CAAC,EAAE,GAAG,GACZ,IAAI,CAAC;CACT;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,WAAY,YAAW,eAAe;;IAMjD;;;;;;OAMG;aACQ,OAAO,EAAI,OAAO;IAQ7B;;;;;;;OAOG;oBACe,IAAI,EAAI,WAAW;IAIrC;;;;OAIG;IACI,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,KAAK,GAAG,CAAC;IAErC;;;;;;OAMG;IACI,gBAAgB,CAErB,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,GAAG,KAAK,GAAG,GAChD,IAAI;IASP;;;;;;OAMG;IACI,mBAAmB,CAExB,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,GAAG,KAAK,GAAG,GAChD,IAAI;CAYR"}

package/types/src/aborter.d.ts

@@ -0,0 +1,4 @@
+/// <reference lib="es5" />
+export { AbortController, AbortError } from "./AbortController";
+export { AbortSignal, AbortSignalLike } from "./AbortSignal";
+//# sourceMappingURL=aborter.d.ts.map

package/types/src/aborter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aborter.d.ts","sourceRoot":"","sources":["../../src/aborter.ts"],"names":[],"mappings":";AAWA,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}