assert-fine

    1.2.2 • Public • Published

    assert-fine

    Build Status Code coverage

    A tiny utility for finding a cause of seemingly random failures in your code.

    The lightweight assert-fine provides a substitute for Node.js native assert API package's strict assert() or ok() , with added benefits:

    1. lazy formatting - informative messages without execution speed penalty;
    2. optional callback is executed before the assertion will throw.
    3. front-end support - yes.

    For a front-end app, the assert npm package or one provided by module bundler, is used when available; otherwise, a simple fallback for just assert.ok() and AssertionError is loaded.

    This package is super useful, when assertions fail in seemingly random manner - in this case the call stack from assertion error may not tell you, which combination of state values actually led to the failure condition - but having debugger stopped at the breakpoint (see above), certainly will.

    Running a special code (a callback) was actually a proposed but rejected Node.js feature request #5312.

    Install

    npm install -S assert-fine
    or
    yarn add assert-fine

    Usage

    const assert = require('assert-fine')
    const getDetails = (...args) => ({ args, foo: 'bar' }) // Or whatever...
    let expectedValue = 'good', value, currentOperation
     
    assert.hook(() => {                         //  This call is optional.
      appendToLogs('good-bye, cruel world!')    //  The breakpoint place.
    })
     
    currentOpertion = 'expected'
     
    assert(value === expected, "%s('%s'): %o", 
      currentOperation, expectedValue, getDetails, 7, 8)
    //  --> "AssertionError: expected('good'): { args: [7, 8], foo: 'bar' }"
     
    //  Some other place - type check has failed, so:
    assert.fail(TypeError, 'expected candy, but got %o instead', typeof someVar)

    API

    The package has named exports AssertionError, ok, fail and hook.

    ok( value, ...args ) : {*}

    Similar to Node.js native assert.ok(), except that:

    • if the value is truey, it returns the value;
    • if the value is falsy, it:
      • calls hook callback;
      • composes diagnostic message;
      • throws an AssertionError with composed message.

    Composing the message:

    1. if one of the optional arguments is a function, it will be replaced with its returned value after applying the rest or arguments to it.
    2. resulting arguments will be applied to Node.js format() function.

    This function is package's default export as well.

    fail( error, ...args )

    Throws an error with message composed of args in the same way the ok() does, but if error argument:

    • is a constructor of Error or any of its child classes, then constructs a new instance and throws it.
    • is an Error instance, then copies its message property to originalMessage, sets new message and throws the instance.
    • is anything else, then throws an Error instance with message and originalMessage composed of args.

    The exceptions from here also invoke the hook callback, when set..

    hook( [ callback ] ) : {function() | undefined}

    Sets new callback function if provided and returns the previous one. Falsy argument results callback set to undefined; otherwise the argument has to be a function or assertion will be thrown. Calling with undefined value will not change the callback.

    When called, the callback receives original args of assertOk call as an array and if it returns an array itself, this will replace the args array for message composition.

    AssertionError class

    For use with instanceof operator. It has the same properties as it's Node.js counterpart.

    In front-end code, the message and stack values may be slightly different from what they might be in case of Node.js assert.

    When error occurs in hook callback or during formatting, the .message and .stack property values of AssertionError instance will indicate this. If this happens, the .message will be multi-line string similar to:

    Assertion callback failed too!
      Error: Intentional
        at apply (/Users/me/dev/_components/assert-fine/test/main.spec.js:15:11)
        at ok (/Users/me/dev/_components/assert-fine/index.js:37:24)
        ...
        at processTicksAndRejections (internal/process/task_queues.js:97:5)
      assertion:
    

    In both cases the .stack will have the original assertion stack dump available after the 'assertion:' line.

    Install

    npm i assert-fine

    DownloadsWeekly Downloads

    5

    Version

    1.2.2

    License

    MIT

    Unpacked Size

    12 kB

    Total Files

    6

    Last publish

    Collaborators

    • valango