@eribrary/zlog v1.0.4

Logging and Error notification functions to smoothen your workflow. Also includes customization options (in case you're crazy and don't like our default flair)!

NEW

Added TypeScript support!

Installation

import * as superLongNameYouWillRegret from '@eribrary/zlog'

OR

import {zlog, notifyOnError /* etc. */} from '@eribrary/zlog'

We'd recommend the second method (or a combination of the two), especially for zlog(), simply because it's faster to type zlog() than superLongNameYouWillRegret.zlog() (and you're totally going to be tired by the 100th time you try to test another section of code to figure out wtf went wrong!)

Key Functions:

zlog

Write colorful logs that include the names (+ links to) functions lower in the call stack (can freely decide how many), making navigation back through the call history quick and painless!

NOTE: calls console.log() to post the final log to the terminal.

notifyOnError

Special notification that can include emails, zlog(), throw new Error, etc. based on the debugger settings (explained below).

setDebugHandlerDefaults

debugHandler (not directly exposed) is an Object with several useful Debug settings. It will be evaluated on notifyOnError() and can be implemented in your own code however you like. This setDebugHandlerDefaults() function lets you change the default values for debugHandler to fit your coding needs! Currently includes the following "flags":

"LogError": true
"EmailDev": false
"NotifyUser": false
"CallDebugger": false
"ThrowError": false
"PreferSendingNotifications": false

Explanation for Each:

LogError Calls zlog() and uses the Error Style (also customizable - see below).

EmailDev Allows for a User-created function to be set up and automatically utilized on notifyOnError(), which will pass the error log to the User-created function.

NOTE: the User is responsible for setting up emailing services etc. Not handled here to avoid dependencies and also to let Users use their preferred packages / setups.

NOTE: don't worry about creating a function for this if you don't plan to use it! If no User-created function is provided, this is skipped.

NotifyUser Essentially the same as for EmailDev above. We don't expect a production-ready service to use this for end-user visibility, as it will just be sending an error log as-is. But it may be helpful during testing to have an on-screen notification (or some other notification method easier than the standard terminal log) rather than having an email sent. But it's up to you anyway, so do whatever!

CallDebugger Sometimes you just need to pause, take a breath, and take a look at wtf is happening! We've added the debugger, which will be thrown when this flag is on.

ThrowError Exactly like it sounds, this throws an error to stop the program from going any further. Do not pass go, do not collect $200, you're going straight to code jail for your heinous failure!

NOTE: ThrowError is evaluated last so that, if it's called, it doesn't prevent the other debugging functions from completing.

PreferSendingNotifications true = prefer sending notifications. false = prefer NOT sending notifications.

• When notifyOnError() is called, one of its parameters is debugHandler, which defaults to the project-wide debug settings. But by using getNewDebugHandler() (see below), you can change the behavior of an individual notifyOnError() call.

• Considering the above, what happens when LogError is true for the default but false for an individual call, but now you want to double-check everything and can't be bothered to go back and find all the special notifyOnError() calls you adjusted? That's where this flag comes in!

• true basically means that if any other flag (e.g. NotifyUser, ThrowError, etc.) is true EITHER in the debugHandler defaults OR as an input for notifyOnError(), then true prevails.

• false means that BOTH would need to be true for true to prevail.

getNewDebugHandler

When using notifyOnError(), the default debugger settings are used. But this allows for unique debugger settings for individual notifyOnError() calls. A deep cloned Object of debugHandler is returned so that you can make changes as desired, then feed the debugHandlerClone into notifyOnError() (or anywhere you want to use this feature).

setEmailDevFunction

setNotifyUserFunction

Both of these functions are essentially the same but used to set up different (optional) User-created functions to be called on notifyOnError() where the debugHandler.EmailDev or debugHandler.NotifyUser (respectively) values === true.

NOTE: each will pass the error log in as the first param, so if you use these, make sure your first param expects a String!

Customization Options

getLogHeaderStyleDefaults

Retrieve the 🌈super-awesome✨ defaults we've set up for the Headers section of the log. Returned as an Object with the following keys:

• TagStyle
• HeaderEnclosures
• FunctionName
• StackLink

NOTE: each value is a String of CSS styles (e.g. "color: orange; background-color: white").

setLogHeaderStyle

Set the Header Style for the log. First argument parameters are the same as the Object values that can be retrieved from getLogHeaderStyleDefaults(), and the last parameter is bResetToDefaults, which will reset all values to their 🔥dope🔥 defaults!

getLogBodyStyleDefaults

Similar to getLogHeaderStyleDefaults() above, except this is for the text body of the log. However, this has 3 unique categories, each with its own variations!

• Normal - defaults have 10 style variations (text color only)

• Special - defaults have 10 style variations (background color only)

• Error - only 1 style used (default uses a red background color with black text, a combination not used in either Normal or Special in order to keep this easily recognizable)

setLogBodyStyle

Wait, what? You don't want to use our freaking awesome defaults?! Well why the hell not??? No, no, it's cool...whatever...😭 If you do want to adjust the look / feel of the text, you can do that here in the same way described above for setLogHeaderStyle() but by using getLogBodyStyleDefaults() instead (also comes with a handy bResetToDefaults param!)

getHeaderTagsDefaults

In the Header we add a Tag. Because we're so dang terrific, we've made the defaults some really cool emoji 🎉! In total there are 4 different Tag types, as explained below:

• First Normal - for the highest call in the Stack (where the log call originated) for normal zlog() calls.

• Others Normal - for all calls lower in the Stack (optional setting that can be changed in the zlog() param numStackCalls, which defaults to 1).

• First Error - for the highest call in the Stack on a notifyOnError() call.

• Others Error - for all calls lower in the Stack on a notifyOnError() call (also has the optional numStackCalls param).

setHeaderTags

Again, why would you ever change the defaults when they're already a work of art?! Just as with all other customization functions above, these can be changed or reset to defaults (values are a simple String).

Pro Note: On Windows, press "Windows Key + ." to open up the emoji selector. For Mac, press "Command + Control + Space". If you're on Linux, either right-click and select "Insert Emoji" or press "Control + ."

SORRY!

We spent waaaaay too much time on this README! Also, it's probably larger than the actual code's file size...so please feel free to delete it!