Rename CancellationToken to AbortController (and bring into line with WHATWG spec) (#54)

* Rename CancellationToken to AbortController (and bring into line with WHATWG spec)

* Rename abortcontroller types file to abort.ts

Author: jeskew

packages/abort-controller/.gitignore

@@ -0,0 +1,2 @@
+/node_modules/
+/build/

packages/abort-controller/.npmignore

@@ -0,0 +1,15 @@
+/src/
+/coverage/
+tsconfig.test.json
+
+*.spec.js
+*.spec.d.ts
+*.spec.js.map
+
+*.mock.js
+*.mock.d.ts
+*.mock.js.map
+
+*.fixture.js
+*.fixture.d.ts
+*.fixture.js.map

packages/abort-controller/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@aws/abort-controller",
+  "version": "0.0.1",
+  "private": true,
+  "description": "A simple abort controller library",
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "scripts": {
+    "prepublishOnly": "tsc",
+    "pretest": "tsc -p tsconfig.test.json",
+    "test": "jest"
+  },
+  "author": "[email protected]",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@aws/types": "^0.0.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^20.0.2",
+    "jest": "^20.0.4",
+    "typescript": "^2.3"
+  }
+}

packages/abort-controller/src/AbortController.spec.ts

@@ -0,0 +1,16 @@
+import {AbortController} from "./AbortController";
+import {AbortSignal} from "./AbortSignal";
+
+jest.useFakeTimers();
+
+describe('AbortController', () => {
+    it('should communicate cancellation via its signal', () => {
+        const source = new AbortController();
+        const {signal} = source;
+        expect(signal).toBeInstanceOf(AbortSignal);
+        expect(signal.aborted).toBe(false);
+
+        source.abort();
+        expect(signal.aborted).toBe(true);
+    });
+});

packages/abort-controller/src/AbortController.ts

@@ -0,0 +1,10 @@
+import {AbortController as IAbortController} from "@aws/types";
+import {AbortSignal} from "./AbortSignal";
+
+export class AbortController implements IAbortController {
+    public readonly signal: AbortSignal = new AbortSignal();
+
+    abort(): void {
+        this.signal.abort();
+    }
+}

packages/abort-controller/src/AbortSignal.spec.ts

@@ -0,0 +1,35 @@
+import {AbortController} from "./AbortController";
+import {AbortSignal} from "./AbortSignal";
+
+describe('AbortSignal', () => {
+    it('should report aborted to be false until the signal is aborted', () => {
+        const controller = new AbortController();
+        const {signal} = controller;
+        expect(signal.aborted).toBe(false);
+
+        controller.abort();
+        expect(signal.aborted).toBe(true);
+    });
+
+    it('should invoke the onabort handler when the signal is aborted', () => {
+        const controller = new AbortController();
+        const {signal} = controller;
+        const abortHandler = jest.fn();
+        signal.onabort = abortHandler;
+        expect(abortHandler.mock.calls.length).toBe(0);
+        controller.abort();
+        expect(abortHandler.mock.calls.length).toBe(1);
+    });
+
+    it('should not invoke the onabort handler multiple time', () => {
+        const controller = new AbortController();
+        const {signal} = controller;
+        const abortHandler = jest.fn();
+        signal.onabort = abortHandler;
+        expect(abortHandler.mock.calls.length).toBe(0);
+        controller.abort();
+        expect(abortHandler.mock.calls.length).toBe(1);
+        controller.abort();
+        expect(abortHandler.mock.calls.length).toBe(1);
+    });
+});

packages/abort-controller/src/AbortSignal.ts

@@ -0,0 +1,34 @@
+import {
+    AbortSignal as IAbortSignal,
+    AbortHandler,
+} from '@aws/types';
+
+export class AbortSignal implements IAbortSignal {
+    public onabort?: AbortHandler;
+    private _aborted: boolean;
+
+    constructor() {
+        Object.defineProperty(this, '_aborted', {
+            value: false,
+            writable: true,
+        });
+    }
+
+    /**
+     * Whether the associated operation has already been cancelled.
+     */
+    get aborted(): boolean {
+        return this._aborted;
+    }
+
+    /**
+     * @internal
+     */
+    abort(): void {
+        this._aborted = true;
+        if (this.onabort) {
+            this.onabort();
+            this.onabort = undefined;
+        }
+    }
+}

packages/abort-controller/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./AbortController";
+export * from "./AbortSignal";

packages/abort-controller/tsconfig.json

@@ -0,0 +1,16 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "target": "es5",
+        "lib": [
+            "es5",
+            "es2015.collection"
+        ],
+        "strict": true,
+        "sourceMap": true,
+        "declaration": true,
+        "stripInternal": true,
+        "rootDir": "./src",
+        "outDir": "./build"
+    }
+}

packages/abort-controller/tsconfig.test.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "sourceMap": false,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "rootDir": "./src",
+    "outDir": "./build"
+  }
+}

packages/types/package.json

@@ -11,7 +11,7 @@
   "scripts": {
     "prepublishOnly": "tsc",
     "pretest": "tsc",
-    "test": ""
+    "test": "exit 0"
   },
   "author": "[email protected]",
   "license": "UNLICENSED"

packages/types/src/abort.ts

@@ -0,0 +1,46 @@
+export interface AbortHandler {
+    (): void;
+}
+
+/**
+ * Holders of an AbortSignal object may query if the associated operation has
+ * been aborted and register an onabort handler.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
+ */
+export interface AbortSignal {
+    /**
+     * Whether the action represented by this signal has been cancelled.
+     */
+    readonly aborted: boolean;
+
+    /**
+     * A function to be invoked when the action represented by this signal has
+     * been cancelled.
+     */
+    onabort?: AbortHandler;
+}
+
+/**
+ * The AWS SDK uses a Controller/Signal model to allow for cooperative
+ * cancellation of asynchronous operations. When initiating such an operation,
+ * the caller can create an AbortController and then provide linked signal to
+ * subtasks. This allows a single source to communicate to multiple consumers
+ * that an action has been aborted without dictating how that cancellation
+ * should be handled.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortController
+ */
+export interface AbortController {
+    /**
+     * An object that reports whether the action associated with this
+     * {AbortController} has been cancelled.
+     */
+    readonly signal: AbortSignal;
+
+    /**
+     * Declares the operation associated with this AbortController to have been
+     * cancelled.
+     */
+    abort(): void;
+}

packages/types/src/index.ts

@@ -1,3 +1,4 @@
+export * from './abort';
 export * from './credentials';
 export * from './crypto';
 export * from './http';