Merge pull request #590 from desktop/abortable-exec

[Breaking] Allow aborting exec, remove execTask

docs/overview.md

@@ -2,14 +2,11 @@
 
 `dugite` is a wrapper on top of the Git command line interface, with some helpers to make it easy to consume in your Node applications. The important parts:
 
- - `GitProcess` - the core of the library - `GitProcess.exec` is how you
-    interact with Git
- - `IGitResult` - the abstraction for a result returned by Git - contains
-    exit code and standard output/error text
- - `IGitExecutionOptions` - additional overrides to change the behaviour
-    of `GitProcess` (see [API extensibility](./api-extensibility.md) for
-    more information)
- - `GitError` - a collection of known error codes that `dugite` can understand
- - `GitNotFoundErrorCode` and `RepositoryDoesNotExistErrorCode` - error codes
-    that `dugite` will raise for exceptional scenarios when invoking Git - you
-    should check for these in your code.
+- `GitProcess` - the core of the library - `GitProcess.exec` is how you
+  interact with Git
+- `IGitResult` - the abstraction for a result returned by Git - contains
+  exit code and standard output/error text
+- `IGitExecutionOptions` - additional overrides to change the behaviour
+  of `GitProcess` (see [API extensibility](./api-extensibility.md) for
+  more information)
+- `GitError` - a collection of known error codes that `dugite` can understand

lib/errors.ts

@@ -169,11 +169,48 @@ export const GitErrorRegexes: { [regexp: string]: GitError } = {
     GitError.PathExistsButNotInRef,
 }
 
-/**
- * The error code for when git cannot be found. This most likely indicates a
- * problem with dugite itself.
- */
-export const GitNotFoundErrorCode = 'git-not-found-error'
+export class ExecError extends Error {
+  /**
+   * The error.code property is a string label that identifies the kind of error
+   *
+   * See https://nodejs.org/api/errors.html#errorcode
+   */
+  public readonly code?: string
 
-/** The error code for when the path to a repository doesn't exist. */
-export const RepositoryDoesNotExistErrorCode = 'repository-does-not-exist-error'
+  /**
+   * The signal that terminated the process
+   */
+  public readonly signal?: string
+
+  /**
+   * Whether the child process successfully received a signal from
+   * subprocess.kill(). The killed property does not indicate that the child
+   * process has been terminated.
+   */
+  public readonly killed?: boolean
+
+  constructor(
+    public readonly message: string,
+    public readonly stdout: Buffer | string,
+    public readonly stderr: Buffer | string,
+    cause?: unknown
+  ) {
+    super(message, { cause })
+
+    if (cause && typeof cause === 'object') {
+      if ('code' in cause) {
+        if (typeof cause.code === 'string') {
+          this.code = cause.code
+        }
+      }
+
+      if ('signal' in cause && typeof cause.signal === 'string') {
+        this.signal = cause.signal
+      }
+
+      if ('killed' in cause && typeof cause.killed === 'boolean') {
+        this.killed = cause.killed
+      }
+    }
+  }
+}