@jumpcutking/console

console

@jumpcutking/console is a pretty console reporting system created to support event listening and consistent reporting. It modifies the node.js global console to offer a consistent, stunning experience and unlimited object depth.

This module works on server node.js but may not be in the web browser. Future updates may provide a web version. For complete documentation, please visit the docs.

This open-source project was created from a console module I used in @jumpcutking/threads and as part of The Universe platform.

What's New

v1.6.0

Another round of bug fixes. jckConsole.TruncateTopLevel is a way to report object properties that are top level. This is useful for reporting objects that are too large to report. Arrays and attached objects will not be removed when using this option. It's safe and not object destructive.

v1.5.0

jckConsole now provides generateSafeError and will automatically generate a safe communicatable error object. While JCKConsole doesn't override your error objects, it will convert error objects passed into it. I added a string variable to match the original stack trace item for easier debugging. Clicking on the line and column in VSCode's console will go to that line and column, making it easy to debug and develop.

v1.2.0

jckConsole is happy to help developers know where a log entry has occurred. It's a new object, and It identifies the caller, the file, the line, and the column of the call.

This update is a breaking change to entry and log callbacks. A new "from" object will be passed to every one of the log callbacks. It will look very similar to a parsedStackTrace() line item.

This update also includes other bug fixes.

v1.1.0

Minor bug fixes, including a fix for the stacktrace object.

v1.0 - First Release

This release includes fixes for objects passed into the console. To debug your console event handlers, create a private console attachment and use it to debug your code; otherwise, you will receive a maximum call stack error (caused by recursion).

/**
 * A fresh instance of the console object.
 * This keeps a reference to the console without
 * any loopbacks during global replacement.
 * @type {Object} The console object.
 * @see {@link https://nodejs.org/api/console.html} for more information.
 */
var myConsole = Console({ stdout: process.stdout, stderr: process.stderr }); 

Installation

Using NPM, install the module with the following command:

npm install @jumpcutking/console

Usage

Using @jumpcutking/console is easy; add the following code at the top of your script.

var jckConsole = require('@jumpcutking/console');
jckConsole.startup({ ...options });

@jumpcutking/console will not override the console global object until you have called the startup() function using the options below. @jumpcutking/console will throw an error if the startup() function is called more than once.

options

Name	Type	Description
reportToConsole	boolean	Automatically report to the terminal and console.
generateStacktrace	boolean	Automatically generate a stacktrace object for each log message, returning them to the callback function only.
storeLogs	boolean	should I store logs in memory
depth	boolean	The depth to inspect objects. 0 is unlimited.

Adding a callback or Listening to an Event

@jumpcutking/console supports (2) callbacks: one for when the console is called and another for when a specific supported console function is called.

You can add a callback using the module or global console objects.

Adding an entry callback will allow you to listen to all console calls, regardless of type. This is useful for saving the entries into a file or database.

jckConsole.on('entry', function (type, message, args, stack, from) {
    // Your code here...
});

// or

console.on('entry', function (type, message, args, stack, from) {
    // Your code here...
});

jckConsole.on("warn", function (message, args, stack, from) {
});

// or

console.on("warn", function (message, args, stack, from) {
});

Currently supported methods:
Properties

Name	Type	Description
log	function	The log function.
info	function	The info function.
warn	function	The warn function.
error	function	The error function.
debug	function	The debug function.

Logging Entries

@jumpcutking/console can store logs in memory for later use. This is useful if you want to use them later. They are each stamped with a DateTime, and if you have generateStacktrace enabled, they will also include a stacktrace object.

jckConsole.getEntries();
console.getEntries();

//clear entries
jckConsole.clearEntries();
console.clearEntries();

Log Entry object getEntries() will return an array of log entry objects.

Name	Type	Description
entry.type	string	The type of console message.
entry.message	string	The message provided to the console object.
entry.args	*	The additional arguments provided to the console object.
entry.stack	Array.<object>	An array of a stacktrace object.
entry.when	Datetime	The time the entry was created.
entry.from	object	A stacktrace object for only the orginal caller.

Stacktrace Object

The stack trace is an object, not a string, for ease of use.

Name	Type	Description
stack.call	string	The function or object called.
stack.file	string	The file the message originated from.
stack.line	number	The line the message originated from.
stack.column	number	The column the message originated from.

Building Docs

To build the docs, run the following command:

npm run docs

Note: you'll have to install the jsdoc-to-markdown module to build the docs.

npm install jsdoc-to-markdown