Improve tagging for a (maybe) null error (#12)

* Document a way of handling an error that might be null

* Make typecheck strict

* Test some edge cases

Co-authored-by: Jakob Ackermann <jakob.ackermann@overleaf.com>

libraries/o-error/test/o-error-util.test.js

@@ -149,9 +149,44 @@ describe('OError.tag', function () {
       expect.fail('should have yielded an error')
     })
   })
+
+  it('is not included in the stack trace if using capture', function () {
+    if (!Error.captureStackTrace) return this.skip()
+    const err = new Error('test error')
+    OError.tag(err, 'test message')
+    const stack = OError.getFullStack(err)
+    expect(stack).to.match(/TaggedError: test message\n\s+at/)
+    expect(stack).to.not.match(/TaggedError: test message\n\s+at [\w.]*tag/)
+  })
+
+  describe('without Error.captureStackTrace', function () {
+    /* eslint-disable mocha/no-hooks-for-single-case */
+    before(function () {
+      this.originalCaptureStackTrace = Error.captureStackTrace
+      Error.captureStackTrace = null
+    })
+    after(function () {
+      Error.captureStackTrace = this.originalCaptureStackTrace
+    })
+
+    it('still captures a stack trace, albeit including itself', function () {
+      const err = new Error('test error')
+      OError.tag(err, 'test message')
+      expectFullStackWithoutStackFramesToEqual(err, [
+        'Error: test error',
+        'TaggedError: test message',
+      ])
+      const stack = OError.getFullStack(err)
+      expect(stack).to.match(/TaggedError: test message\n\s+at [\w.]*tag/)
+    })
+  })
 })
 
 describe('OError.getFullInfo', function () {
+  it('works when given null', function () {
+    expect(OError.getFullInfo(null)).to.deep.equal({})
+  })
+
   it('works on a normal error', function () {
     const err = new Error('foo')
     expect(OError.getFullInfo(err)).to.deep.equal({})
@@ -193,6 +228,10 @@ describe('OError.getFullInfo', function () {
 })
 
 describe('OError.getFullStack', function () {
+  it('works when given null', function () {
+    expect(OError.getFullStack(null)).to.equal('')
+  })
+
   it('works on a normal error', function () {
     const err = new Error('foo')
     const fullStack = OError.getFullStack(err)

libraries/o-error/test/support/index.js

@@ -2,6 +2,10 @@ const { expect } = require('chai')
 
 const OError = require('../..')
 
+/**
+ * @param {Error} e
+ * @param {any} expected
+ */
 exports.expectError = function OErrorExpectError(e, expected) {
   expect(
     e.name,
@@ -23,24 +27,28 @@ exports.expectError = function OErrorExpectError(e, expected) {
     'error should be recognised by util.types.isNativeError'
   ).to.be.true
 
-  expect(e.stack, 'error should have a stack trace').to.be.truthy
-
   expect(
     e.toString(),
     'toString should return the default error message formatting'
   ).to.equal(expected.message)
 
+  expect(e.stack, 'error should have a stack trace').to.not.be.empty
+
   expect(
-    e.stack.split('\n')[0],
+    /** @type {string} */ (e.stack).split('\n')[0],
     'stack should start with the default error message formatting'
   ).to.match(new RegExp(`^${expected.name}:`))
 
   expect(
-    e.stack.split('\n')[1],
+    /** @type {string} */ (e.stack).split('\n')[1],
     'first stack frame should be the function where the error was thrown'
   ).to.match(expected.firstFrameRx)
 }
 
+/**
+ * @param {Error} error
+ * @param {String[]} expected
+ */
 exports.expectFullStackWithoutStackFramesToEqual = function (error, expected) {
   const fullStack = OError.getFullStack(error)
   const fullStackWithoutFrames = fullStack