feat(fio): add FIO.node

FIO.node is a simpler API to handle callback based async APIs in node.js

src/main/FIO.ts

@@ -40,6 +40,15 @@ export type TaskR<A, R> = FIO<Error, A, R>
  */
 export type UIO<A> = IO<never, A>
 
+/**
+ * Callback function used in node.js to handle async operations.
+ * @ignore
+ */
+export type NodeJSCallback<A> = (
+  err: NodeJS.ErrnoException | null,
+  result?: A
+) => void
+
 /**
  * @typeparam E1 Possible errors that could be thrown by the program.
  * @typeparam A1 The output of the running the program successfully.
@@ -243,6 +252,29 @@ export class FIO<E1 = unknown, A1 = unknown, R1 = NoEnv> {
     return new FIO(Tag.Never, undefined)
   }
 
+  /**
+   * Simple API to create IOs from a node.js based callback.
+   *
+   * **Example:**
+   * ```ts
+   * // FIO<NodeJS.ErrnoException, number, unknown>
+   * const fsOpen = FIO.node(cb => fs.open('./data.txt', cb))
+   * ```
+   */
+  public static node<A = never>(
+    fn: (cb: NodeJSCallback<A>, sh: IScheduler) => void
+  ): IO<NodeJS.ErrnoException, A | undefined> {
+    return FIO.asyncIO<NodeJS.ErrnoException, A>((rej, res, sh) =>
+      sh.asap(() => {
+        try {
+          fn((err, result) => (err === null ? res(result as A) : rej(err)), sh)
+        } catch (e) {
+          rej(e as NodeJS.ErrnoException)
+        }
+      })
+    )
+  }
+
   /**
    * Represents a constant value
    */

test/FIO.test.ts

@@ -559,4 +559,36 @@ describe('FIO', () => {
       assert.deepStrictEqual(actual, expected)
     })
   })
+
+  describe('node', () => {
+    it('should capture exceptions from Node API', () => {
+      const actual = testRuntime().executeSync(
+        FIO.node(cb => cb(new Error('Failed')))
+      )
+      const expected = new Error('Failed')
+
+      assert.deepStrictEqual('' + actual, '' + expected)
+    })
+
+    it('should capture sync exceptions', () => {
+      const actual = testRuntime().executeSync(
+        FIO.node(cb => {
+          throw new Error('Failed')
+        })
+      )
+      const expected = new Error('Failed')
+
+      assert.deepStrictEqual('' + actual, '' + expected)
+    })
+
+    it('should capture success results', () => {
+      const actual = testRuntime().executeSync(
+        // tslint:disable-next-line: no-null-keyword
+        FIO.node<number>(cb => cb(null, 1000))
+      )
+      const expected = 1000
+
+      assert.strictEqual(actual, expected)
+    })
+  })
 })