Debug-MyCoffee (Logging)

Whats New 1.0.0

Major overhaul docs are now outdated

Objective

debug-mycoffee is a lightweight micro package intended as a simple way to replace the infamous console.log debugging statement approach. It is not a testing framework so the package can be bundled in production, but rather debug-mycoffee is a smarter way to print out logging information

Install

To install run npm install debug-mycoffee. The package contains no external dependencies.

Usage

To log a message use one of the several logging functions. There are 5 styles of logs available 'default', 'note', 'error', 'func', 'ok'. These are defined in the MemoStyle type if you are using typescript

export type MemoStyle = "default" | "note" | "error" | "ok" | "func"

Printing A log

import { DebugMemo, DebugNote, DebugError, DebugFunc, DebugOk } from "debug-mycoffee"

// DebugMemo has optional 2nd param defining 'style'
DebugMemo("This is a memo");
DebugMemo("error memo, check logs", "error"); //use of of any 'MemoStyle'

/*You can use the wrapper quick access versions (1 parameter) */
DebugNote("Print in the note style");
DebugError("Some error has occurred");
DebugFunc("Functions: Write(...) being called");
DebugOk("API call was successful");

Turning off logging style

debug-mycoffee allows you to turn off a style when in production or test-mode using DebugOff(style : MemoStyle)

import { DebugOff } from "debug-mycoffee"

DebugOff("note") //turn off 'notes'
DebugOff("func") //turn off 'func style'
DebugOff("default") //turn off 'default'
DebugOff("ok") //turn off 'ok style'

Note: you cannot turn off the 'error' memo since this is considered critical and should not be hidden

Quick off all

use the DebugOffAll to quickly turn off all memo styles in a single call

import { DebugOffAll } from "debug-mycoffee"

DebugOffAll() // turns of all logs excpect 'error'

Debug Assert

DebugAssert(val : T) is a simple way to add assertions to logging without the overhead of a full testing framework.

To check a value call DebugAssert(val : T)

import { DebugAssert } from "debug-mycoffee"

const check = DebugAssert("my string");
check.isVal("should equal this")
check.isDefined();
check.assert(val => {
    //TODO: custom predicate / assert logic
    return true
})
const list = ["my-string", "more-data"]

//checks 'my-string' inside array 'list' using iterator
check.inside(list); 

You can add optional 'msg' at end of assert statement to append to print statement

Assertion Interface Full Definition

export interface DebugChecker<T> {
    assert(predicate : (val : T) => boolean, msg? : string) : void
    isVal(val : T, msg? : string) : void
    isDefined(msg? : string) : void
    inside(list : any, msg? : string) : void 
}

Call Assertions

Interface

export interface DebugCaller {
    call() : void
    isCalled(msg? : string) : void,
    isNotCalled(msg? : string) : void,
    isCalledTimes(count : number, msg? : string) : void
    count() : number
}

Create a caller using the DebugCall()

import { DebugCall }

const caller = DebugCall();
//use .call() to increment the call count and assert
caller.call();

caller.isCalled() //success
caller.isCalledTimes(2) //will dump an assertion fail

Simple to DebugAssert(..) if AssertOff is called, the assertion will be ignored

Turn Off Assertions

you can turn off assertion checks by using the AssertOff() function. This will return a singleton defined EMPTY object with all the functions defined as empty ignoring the assertion. This is to ensure computations with assert(..) don't take up any compute time.

import { AssertOff , DebugAssert} from "debug-mycoffee"

AssertOff();

DebugAssert(83).assert(num => {
    //Will be ignored due to 'AssertOff' being called earlier
})

Capture Assertion Fails with Custom Handler

you can capture all failed assertions with a custom handler using the DebugCaptureDump(handler: (msg : string) => void )

Handler defined as

export type DumpHandler = (msg : string, stack? : string) => void

import { DebugCaptureDump } from "debug-mycoffee"

DebugCaptureDump((msg, stack) => {
    //TODO: send msg to server??
})
DebugCaptureDump(msg => {
    //msg not stack
})
//stack is optional

//will trigger DebugCaptureDump to be called
DebugAssert(9).isVal(3, "9 == 3 ??")

Note: in Above only one DebugCaptureDump allowed, 2nd call will override first

Browser Optimization

The logging colors are designed with node.js in mind primarily. Certain console function colors don't show as intended on the in web so use DebugMode('node' | 'web') to set the color mode for better view-ability on the web

import { DebugMode } from "debug-mycoffee"

//mode to web
DebugMode("web");

//set mode to node
DebugMode("node");

Freeze settings

You can freeze all current setings by calling DebugFreeze() so certain functions will be ignored when called

import {DebugFreeze , DebugOff, DebugOffAll, AssertOff, DebugCaptureDump, DebugMode } from "debug-mycoffee"

DebugFreeze();

//The following functions will be frozen
DebugOff(..)
DebugOffAll();
AssertOff();
DebugCaptureDump(..)
DebugMode(..)