Add Toolkit.run

README.md

@@ -87,6 +87,19 @@ const tools = new Toolkit({
 })
 ```
 
+### Toolkit.run
+
+Run an asynchronous function that receives an instance of `Toolkit` as its argument. If the function throws an error (or returns a rejected promise), `Toolkit.run` will log the error and exit the action with a failure status code.
+
+The toolkit instance can be configured by passing `Toolkit` options as the second argument to `Toolkit.run`.
+
+```js
+Toolkit.run(async tools => {
+  // Action code
+}, { event: 'push' })
+```
+<br>
+
 ### tools.github
 
 Returns an [Octokit SDK](https://octokit.github.io/rest.js) client authenticated for this repository. See [https://octokit.github.io/rest.js](https://octokit.github.io/rest.js) for the API.

src/index.ts

@@ -16,6 +16,29 @@ export interface ToolkitOptions {
 }
 
 export class Toolkit {
+  /**
+   * Run an asynchronous function that accepts a toolkit as its argument, and fail if
+   * an error occurs.
+   *
+   * @param func - Async function to run
+   * @param [opts] - Options to pass to the toolkit
+   *
+   * @example This is generally used to run a `main` async function:
+   *
+   * ```js
+   * Toolkit.run(async tools => {
+   *   // Action code here.
+   * }, { event: 'push' })
+   * ```
+   */
+  public static async run (func: (tools: Toolkit) => Promise<unknown>, opts?: ToolkitOptions) {
+    const tools = new Toolkit(opts)
+
+    return func(tools).catch(err => {
+      tools.exit.failure(err)
+    })
+  }
+
   public context: Context
 
   /**

tests/index.test.ts

@@ -159,6 +159,31 @@ describe('Toolkit', () => {
     })
   })
 
+  describe('.run', () => {
+    it('runs the async function passed to it', async () => {
+      const spy = jest.fn(() => Promise.resolve('hi'))
+      const actual = await Toolkit.run(spy)
+      // Test that the function was called
+      expect(spy).toHaveBeenCalled()
+      // Make sure it was called with a Toolkit instance
+      expect((spy.mock.calls as any)[0][0]).toBeInstanceOf(Toolkit)
+      // Check that it returned a value as an async function
+      expect(actual).toBe('hi')
+    })
+
+    it('logs and fails when the function throws an error', async () => {
+      const err = new Error('Whoops!')
+      const exitFailure = jest.fn()
+
+      await Toolkit.run(async twolkit => {
+        twolkit.exit.failure = exitFailure
+        throw err
+      })
+
+      expect(exitFailure).toHaveBeenCalledTimes(1)
+    })
+  })
+
   describe('#wrapLogger', () => {
     it('wraps the provided logger and allows for a callable class', () => {
       const logger = new Signale() as jest.Mocked<Signale>