Sincere

Sincere is a lightweight ES6 base class providing intuitive interface for debugging and diagnostics of Node.js applications.

NB: v2.0 has breaking changes:

1. former static methods sincereHook() and sincereReset() are renamed to hook() and reset() respectively;
2. both static methods behavior has slightly changed - see description below.

With Node.js earlier than v8.6.0, something like babel is needed.

Usage

Install with npm

npm i sincere

Example

const Sincere = require('sincere')

class MyClass extends Sincere {
    ...
}

...

//  Before the execution starts...
Sincere.hook(() => {
  return 0     //  Set debugger breakpoint here.
}

const myInstance = new MyClass(...)

let goodValue = myInstance.assert({good: true}, 'try')
let badValue = myInstance.assert(0, 'try', 'this failed, but %O - you see', goodValue)

So, where's the beef? The above code results in AssertionError being thrown and the error message is something like 'MyClass#1.try: this failed, but {good: true} - you see'.

The instance identifier shows exactly which instance of which class failed the assertion. Also, if your debugger breakpoint was set, you'd see the whole picture as it was just before throw. How cool is that?

API

In 99% likelihood, assert(), hook() and className is all the API you need.

Both assert() and sincereMessage() use Node.js native util.format(); see Node.js documentation for details.

Static methods

hook(callback=) Sets a before-the-assertion-will-throw callback. Falsy value inhibits previously set callback; undefined argument value has no effect. Truthy non-function type argument will result in TypeError thrown. Returns callback function or false. NB: In production environment, this method does nothing.

reset() Resets internal seed variable for sincereId property. NB: available only if NODE_ENV was set to 'test' before loading the module; calling it in non-test environment will throw exception.

Instance properties

The instance properties are non-enumerable read-only and can not be overridden in derived classes.

className : string - actual class name, like 'MyClass'.

sincereId : string - unique id, something like 'MyClass#42'.

Instance methods

assert(value, locus, …args) A wrapper method around the native assert.ok(). Returns the value, if it is truthy - e.g. assertion does not fire. If assertion fails, then args are processed by native util.format and util.inspect functions, so the first arg may be format string.

sincereMessage(locus, args) Compose a diagnostic message string prefixed with sincereId

• locus : string usually a method name;
• args : Array<*> arguments to be passed to Node.js util.format().