https://github.com/valango/sincere
A lightweight javascript base class providing intuitive interface for debugging and diagnostics of Node.js applications
https://github.com/valango/sincere
Last synced: about 2 months ago
JSON representation
A lightweight javascript base class providing intuitive interface for debugging and diagnostics of Node.js applications
- Host: GitHub
- URL: https://github.com/valango/sincere
- Owner: valango
- License: isc
- Created: 2020-01-18T19:56:51.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-05T05:18:08.000Z (over 3 years ago)
- Last Synced: 2025-02-25T10:08:49.438Z (over 1 year ago)
- Language: JavaScript
- Size: 731 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Sincere [](https://travis-ci.org/valango/sincere) [](https://codecov.io/gh/valango/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`](https://babeljs.io/) is needed.
## Usage
Install with npm
```
npm i sincere
```
## Example
```javascript
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](https://nodejs.org/dist/latest-v12.x/docs/api/util.html#util_util_format_format_args)
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()`](https://nodejs.org/dist/latest-v12.x/docs/api/util.html#util_util_format_format_args).