devision.js

v1.0.2

Published

3 years ago

A dev tool to track your application's state at run-time!

Downloads

0High
0Medium
0Low

ben_izra2

jqw.chang

DEVision is intended as a drop-in replacement for console.log, with the following features:

Fast
Isomorphic
Elegant API
Browser/Platform Independent
... did we mention, Fast?

DEVision.js Overview

Problem

No run-time debug tracking in JavaScript that's browser and platform independent.
Currently all console.log messages will run into one another & overlap
Once done with console.logs, need to comment / uncomment may lead to errors
No “history” of a variable’s value and “tracing” done manually
No “diff’ing” to visually highlight the changes
Tracing (during development) & Testing (post development) usually violate the DRY concept in work flow context

Solution

An improved console.log replacement allowing the developer to decide (at run-time)* what will be logged based on both priority level & user-defined scope with the ability to track/snapshot variable values and test their values.

DEVision.js Setup

Installation:

npm install devision.js --save dev

Setup in Node.js

const dev = require("devision.js");

Setup in Front-End

<head>
    <script src="https://rawgit.com/nnZTA/DEVision.js/master/library/devision.js"></script>
    <script src="https://rawgit.com/nnZTA/DEVision.js/master/library/devisionView.js"></script>
</head>

DEVision.js HowTo

Usage in General

In fullfilling DEVision's primary purpose of being a drop-in replacement for console.log it is easiest to think of it as a Log Butler that takes care of your diagnostic household. As is the Butler, it will be the gatekeeper for access to your logs. There are two primary methods (during runtime) which allow you to control your diagnostic data flow:

    dev.currentPriority = 0;
    dev.currentScope = ['global', 'appRunTime', 'dataIO', 'foo', ];

currentPriority is a threshold for logging without semantic (context) info beyond the severity of the message to be logged. The implicit (automatic) default level for both dev.currentPriority && dev.log(...) is 0 for all logged data. Therefore, should you use only dev.log(...) without specifying a priority (as the second argument) you will be able to turn off all console logs by simply setting:

    dev.currentPriority = 1;

... this value can be changed either at the terminal in your application, or if on the front end, in a dynamically loaded HTML interface. currentScope is similarly a permissive filter for your data... it will allow any data to be displayed that contains the same scope tag(s) as currently within the dev.currentScope[] array to be displayed. Let's look at a very simple example:

dev.log("Developer Debug Message");
dev.log("Database Connection Successful <*important status update*>", 13, 'db');
dev.log("File Write Failure <*critical alert/error*>", 42, ['error', 'devOps']);
dev.log("Database Connection Failure <*critical alert/error*>", 42, ['error', 'db', 'network']);

Given the defaults of currentPriority===0 && currentScope===[] the output would be:

Developer Debug Message
File Write Failure <*critical alert/error*>
Database Connection Successful <*important status update*>
Database Connection Failure <*critical alert/error*>

Given currentPriority===42 && currentScope===[] the output would be:

File Write Failure <*critical alert/error*>
Database Connection Failure <*critical alert/error*>

Given currentPriority===99 && currentScope===['db'] the output would be:

Database Connection Successful <*important status update*>
Database Connection Failure <*critical alert/error*>

... noting that we can achieve the same "goal" of only seeing the "high priority" items in the second & third examples; however, the first shows only by severity (both file && db) whereas the latter only shows based upon the contextual 'db' scope.

DEVision.js API

dev.log(...) → drop-in replacement for console.log(...)

//  exp === ExpressionToBeLogged
//  dev.log(exp);  // example
let x = 13;
dev.log("x === " + x);

//--->   x === 13
----------

//  clcsv === console.log style comma delimited expressions
//  note:  the [] surrounding clcsv are required for this functionality
//  dev.log([clcsv]);  // example
let y = {someNum:13};
dev.log(["y === ", y]);

//--->   y === ▶ Object { someNum: 13 }

----------

//  dev.log(<exp||clcsv>, priority = 0, scope);  // example
let w = 12;
let x = 13;
dev.currentPriority = x;
dev.log("w === " + w, w);
dev.log("x === " + x, x);

//--->   x === 13

dev.peek({...}) → 'wrappers' dev.log(...) output with "varName === varVal" formatting

dev.peek(...);

dev.passThru(...) → an "in-line" log ... it returns what's being logged

dev.passThru(...);

dev.trace(...) → used to track an object's value at a specific point in code

dev.trace(...);

dev.track(..., true|false) → used to track an object's values until turned off (true|false)

dev.track(...);

dev.watch(...) → "full-monty" dev function, same as calling [log && track]

// ... === <exp||clcsv>, object, testCases, priority = 0, scope
```js
dev.watch(...);

Exporting Test Scripts:

dev.test(...) → used to generate Tape Test files (and in the future, possibly code coverage)

dev.end → property used by dev.test(...)

Make sure to include this script inside your package.json to export:

    "export": "node ./node_modules/devision.js/library/exportTests.js"

for multiple test cases for one objectToTest

dev.test(objToTest, [{},{},{}], dev.end);

or for only one test case for one objectToTest

dev.test(objToTest, {}, dev.end);

dev.test currently only supports these tape assertions: equal, notEqual, deepEqual, notDeepEqual, deepLooseEqual, notDeepLooseEqual, ok, notOk, error, comment

----- inside srcFile.js:

function addTwo(num){
    return num + 2; 
}

module.exports = {
    addTwo
}

Assertion types: equal, notEqual, deepEqual, notDeepEqual, deepLooseEqual, notDeepLooseEqual

dev.test(addTwo, 
    {
        input: 2,
        type: 'equal', // assertion type
        expected: 4,
        msg: [optional]
    }, 
    dev.end
);

Assertion types: ok, notOk

ok : Assert that value is truthy notOk : Assert that value is falsy

dev.test(addTwo, 
    {
        input: 2,
        type: 'ok',
        msg: [optional]
    },
    dev.end
);

Assertion type: error

Assert that e is falsy. If e is non-falsy, use its err.message as the description message.

dev.test(addTwo,
    {
        type: 'error',
        e: 3,
        msg: 'uh oh'
    }, 
    dev.end
);

Assertion type: comment

Print a message without breaking the tap output.

dev.test(addTwo,
    {
        type: 'comment',
        msg: 'Just leaving a comment here'
    }, 
    dev.end
);

Using multiple test cases with different assertion types on one objectToTest:

dev.test(addTwo, 
    [
        {
            input: 2,
            type: 'equal',
            expected: 4,
            msg: 'should equal to 4'
        }, 
        {
            input: 2,
            type: 'notEqual',
            expected: 100,
            msg: 'should not equal to 100!'
        }, 
        {
            type: 'error',
            e: 3,
            msg: 'uh oh'
        }, 
        {
            input: 2,
            type: 'notOk',
        }
    ],
    dev.end
);

output in exported test file:

    test('TESTING addTwo', (t) => {
        t.equal(srcFile.addTwo(2), 4, 'should equal to 4');
        t.notEqual(srcFile.addTwo(2), 100, 'should not equal to 100!');
        t.error(srcFile.addTwo(3), 'uh oh');
        t.notOk(srcFile.addTwo(2));
    })

Please follow the format in order for all test scripts to be exported correctly!

dev Utils

dev.JSs(...) → JSON.stringify(..., null, 2)

dev.JSs(...);

dev.JSp(...) → JSON.parse(...)

dev.JSp(...);

dev.vw() → Launch dev Viewer

dev.vw(...);

Multiply your productivity by using DEVision.js! ☺

Authors

Contributing

If you would like to contribute, submit a pull request and update the README.md with details of changes.