sincere v2.1.2
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;
1. 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.jsutil.format()
.