Assert-debug NPM

assert-debug

assert-debug helps to trace down the actual cause behind seemingly random assertion failures.

When might you need it?

Your code may interact with different databases and even with some resources you can't control.

You think you're ready to deploy, and suddenly there is a weird assertion error. Sure you'll get the stack trace and even what exactly went wrong - in a style like:

// + expected - actual
//   {
// -   a: 1
// +   a: 2
//   }

That's great, but... the cause still remains unclear. And dynamic context is all gone - you can't inspect the local variables. You have no idea of how to repeat this failure. You can expect a long night full of relentless experimenting ahead of you... or not.

What it does?

assert-debug module exports all the stuff from original Node.js assert built-in package, with all assertion methods wrapped into try-catch blocks. A global event will fire, before any assertion actually throws.

An event handler will receive AssertionError instance before it is actually thrown. You can even prevent it from being thrown. But most importantly, by having a debugger breakpoint set inside handler function, you will get access to all dynamic context that led to this assertion!

Usage

Installation

npm i -D assert-debug

yarn add -D assert-debug

Example

//  In the beginning of application code.
const assert = require('assert-debug')

process.on(assert.eventType, (error) => {
  //  Set up debugger breakpoint inside the code here and 
  //  inspect the dynamic context of any assertion failure!
  return 0  //  Has no effect - just for breakpoint.
})
  ...
// Anywhere else in application code.
assert.fail('Will see u at the breakpoint') //  Or any other assertion function.

To get better idea, see example/ directory.

API

assert-debug module exports exactly the same API as original assert, plus:

nodeMajor: number - Node.js semver major number as integer.
eventType: string - originally set to "BeforeAssertionIsThrown". You can assign a different value to change the event to be used. Setting it to falsey value disables the whole trapping altogether. The change affects all assertions happening after it.

Such a super-smart fiddling is hardly ever needed and if you really want a different event type, you can set it by NODE_ASSERTION_EVENT environment variable.

There is an upwards-compatibility bonus: current Node.js documentation promotes using assert.strict, which was still missing in Node.js v8 - but assert-debug always exports strict, so your v10 code won't crash on v8 because of the strict thing.

Code pattern

Instead of directly require('assert-debug') in your application, it may be better to do something like this:

//  File: lib/assert.js
exports = module.exports = require('assert-debug')

if (exports.eventType) {  //  Not present in production mode.
  exports.preventThrows = false

  process.on(exports.eventType, (error, cancel) => {
    //  A nice place for debugger breakpoint!
    if (exports.preventThrows) cancel()
  })
}

//  In application main module, before anything else.
if (process.env.NODE_ENV !== 'production') {
  global.$assert = require('./lib/assert')
}
...

//  In any other module.
const assert = global.$assert || require('assert')  // Will run OK w/o this package too.
...

This is just an example - use of global namespaces is a matter beyond our scope here.

Changes

v1.2

Fixes to issues #2 and #3 (fundamental enough).

v1.1

In production mode, assert-debug does not change native assert behavior, but it still adds nodeMajor and strict (if needed).
eventType is not exported in production mode.
eventType default is changed from "TrappedAssertion" to "BeforeAssertionIsThrown".
Test are refactored to work correctly with Node.js v8.