Ja-log NPM | npm.io

ja-log (v3.0.2)

The excruciatingly simple logging tool.

I dislike large logging libraries. They can be inefficient and a pain to work with, so I have been using JS's built in console. console is great and I am satisfied with it, but I wanted to have a bit more information with my output.

So I made ja-log!

ja-log is a drop-in replacement for the console.log() function and variants. ja-log is extremely small (2.65 KB) and works with ECMAScript 3 (1999) to EMCAScript 9 (2018) and beyond! Also, ja-log is extendable using the jaLog.onSend(callback) function, which allows easy output of log commands to any medium.

The ja-log script works on both Node.JS and in the browser at the same time, so using it is easy! Example:

//Node.
var jaLog = require("ja-log");

//Browser. (not recommended for production, use a local copy instead)
//<script src="https://github.com/jackyminer/ja-log/raw/master/ja-log.min.js"></script>

jaLog.log("Hello!");

Should work anywhere, including browsers without console, just use jaLog.onSend(callback)!

Also, when I say small, I mean small. Here is the entire file (minified) with Node.JS and browser comparability in one screenshot:
Very Small!

Features

The feature set of ja-log is small but it contains everything you need to do efficient and pretty logging.

Drop in replacement for console
Runs on pretty much any JS implementation
Nice looking and fast timestamp formatting
Colorful formatting using ANSI color codes(Node) or CSS(Browser)
Simple system for re-directing output
Easy to configure settings
Speed

Example

Input:

var x = 1;
jaLog.onSend(function (message) {
    x++;
});

jaLog.log("This will be cleared.");
jaLog.clear();

jaLog.log("This is info! Log it!");

jaLog.debug(10);
jaLog.log();
jaLog.warn(undefined);
jaLog.error(Math.PI);
jaLog.debug(true);
jaLog.trace("Tracing this!");
jaLog.log([ 10, "32", null, true ]);
jaLog.error({
    object: "time",
    my: "dudes",
    yes: 10
});
jaLog.debug(new Error("Died!"));

var i = ["This would normally break JSON.stringify!"];
i.push(i);

jaLog.warn(i);

jaLog.assert(1 > 0, "Good!");
jaLog.assert(1 < 0, "Bad!");

jaLog.debug(x + " messages logged.");

Output(Node):
Node.JS Output
Output(Chrome):
Chrome Console Output
Output(IE 8 Developer Console w/ IE 7 Mode):
IE 8 Console Output
Some stuff doesn't exactly work because, well, IE. But hey, IE 7 mode with logging and some color!

Installation

ja-log is available via NPM or as a small script for the browser.

NPM:
Install: $ npm install -s ja-log
Use: var jaLog = require("ja-log")

Browser:
Install: Download the latest release here.
Use: <script src="ja-log.min.js"></script>

The browser script is also NPM compatible, so just require("ja-log.min.js") will work too. Really, the "browser" script runs anywhere JS does.

If you are targeting legacy JS implementations, you may want to use the raw script as the minified one takes some shortcuts that only work on newer JS versions.

Usage

I am going to keep this section simple, but there is a lot of stuff packed into this tiny library!

Function List

debug(message); //Send a message at debug level.
log(message); //Send a message at info level.
warn(message); //Send a message at warning level.
error(message); //Send a message at error level.
trace(message); //Send a message followed by a stack trace at error level.

assert(assertion, message); //Send a message at error level if the assertion evaluates to true.
clear(); //Clear the console, identical to console.clear().

settings(newSettings); //Change settings, see usage.

onSend(callback); //Add a send callback, see usage.

Settings

ja-log has a few settings that can be configured by the user.

Default Settings:

{
    consoleOutput: (autodetected), //Should we output to console? This will be set to false if console is not valid or true if it is.
    niceTimestamp: true, //Use nice timestamps (10/26/2018, 6:21:48 PM) instead of UNIX (1540604512.479).
    colorMode: (autodetected), //What color mode to use, 0 = no color, 1 = ANSI, 2 = CSS. Will be set to ANSI in Node or CSS in a browser.
    fastString: false, //Don't do string conversion.
    disabledDebug: false, //Disable output of jaLog.debug(message). Will still call onSend callbacks.
    disabledInfo: false //Disable output of jaLog.info(message). Will still call onSend callbacks.
}

Configuration:

Changing settings is also very easy. Just call jaLog.settings(newSettings) with an object containing what settings you wish to use. If a setting is not present in the call, it will use whatever is already set.

jaLog.settings({
    consoleOutput: true,
    niceTimestamp: true,
    colorMode: 1,
    fastString: false,
    disabledDebug: false,
    disabledInfo: false
}); //Set all settings.

jaLog.settings({ consoleOutput: false }); //Turn off console output and keep everything else from the last call.

onSend Callbacks

Logging to console is great, but what if you want to, say, write to a log file? That is also very easy!

Using jaLog.onSend(callback) you can run a function whenever a message is sent. This includes disabled output using settings.

The only arguments passed to the callback is a copy of the message array, formatted like this:

[ UNIX timestamp (number), Nice timestamp (string), Level number (0:Debug 1:Info 2:Warning 3:Error 4:Trace), Message contents (string) ]

Some examples:

//Count the messages sent.
var x = 0;
jaLog.onSend(function () {
    x++;
});

//Replace the console output with your own.
jaLog.settings({ consoleOutput: false });
jaLog.onSend(function (message) {
    console.log(message[ 3 ]);
});

Building

When I make a new version and need to minify the file, I use the minify.sh file. It minifies the file and adds a source map, it is just one command.

I also paste the copyright notice at the top.