fliplog
all-in-one logging tool
usage
npm i fliplog --save
description
fluent logging with verbose insight, colors, tables, emoji, deep cleaning, filtering, spinners, progress bars, timestamps, capturing, stack traces, clearing, boxen, stringifying, code highlighting, notifications, beeping, sparkles, slow-mode, formatting, bar charts, & presets
legend:
- basics
- stringifying
- json
- stringify
- silencing
- capture all
- return formatted values
- return values
- color
- chalk
- shorthands
- xterm
- function
- emoji
- filtering
- level
- matcher
- flags
- filter
- tags
- quick
- table
- cleaner
- diff
- spinner
- multi
- ora
- progress
- notify
- stack traces
- finding logs
- catch errors
- (r) .register
- trace
- [CL] clear
- deep
- verbose vs tosource
- verbose
- tosource
- highlight
- presets
- add your own
- use built ins
- timestamps
- from
- fun
- tree
- bar chart
- box
- beep
- sparkly
- formatting
- space
- formatter
- slow
- timer
- performance (lightweight configurable dependencies)
- resources
basics
.data({anyKindOfData: true}) // .json, .stringify, .tosource, .verbose
.text('text to use, this is what gets colored')
.color('bold') // any cli-color, chalk, available as shorthands
.echo() // outputs the log, .return to return the formatted values
[NEW] NEW!
all of these new ones need more docs
read the wip docs for new stuff on the wiki
+ == .echo
// ^ same as `log.italic('so short!').echo()`
stringifying
json
log.json({eh: 'prettified'})
stringify
log.stringify({data: 'can stringify deep things'})
silencing
- to disable outputting a log,
.silence()(optionaltrue/falsearg) - to disable all logs,
.shush() - to enable all logs,
.unshush()
capture all
capture output of all console logs everywhere
console.log('this will be captured')
log.stopCapturing()
// captured data is available here
const saved = log.savedLog
return
return only echos from fliplogs, useful for getting formatted data.
const {text, data} = log
.data({catchMeIfYouCan: true})
.text('gingerbread man')
.returnVals()
// this returns everything inside, it will call .filter first
const everything = log
.color('blue.underline')
.data({canYouHandleIt: true})
.text('M')
.return()
color
chalk
all chalk colors available with .color
.text('\n========================================\n')
.color('bold')
.echo()
shorthands
.bold('same as calling .color(bold).text(all this text)')
.echo()
xterm
all cli-color are available by calling .xterm
.time(true)
.xterm(202, 236).text(' orange!!! ')
.echo()
function
because it's javascript, the log is an object... but it can be called as a function for convenience
stack
emoji
names using emoji-commits are available with .emoji (currently not all have been ported yet)
.emoji('phone')
.text('et')
.data('phone home')
.echo()
filtering
comma separated strings, or arrays
a function can also be passed in, the argument will be an object containing the entries see flipchain/ChainedMap.entries
level
filter by log level as a number with simple comparison operators
log.level(1).bold('above 1... success').echo()
log.level(0).bold('not above 1...').echo()
matcher
filter using an Array made up of Functions, Strings, and RegExps!
log.tag('canada-eh').white('canadian, pass.').echo()
more advanced
log.tag('eh').underline('eh').echo()
log.tag('warm').red('warm').echo()
log.tag('ez').yellow('ez').echo()
important to note, if only a function is passed in, it will have the entire log instance passed to the argument, rather than the array of tags (for compatibility & simplicity.)
filter & tags
verboseenables everythingsilentsilences everything!means disabled
.filter('!nope, yes')
log
.tag('unrelated,nope')
.cyan('you will never see me :-(')
.echo()
log
.tag('yes')
.underline('yay!')
.echo()
flags
this can also be done using cli flags compat with debug flags
yourprogram --DEBUG=verbose
quick
quickly log data and exit if you want to stop execution at a certain point for debugging
// or
log.data({now: 'die'}).exit(1)
tables
extending cli-table2
.table(['header1', 'header2'], ['row1', 'row2'])
.echo()
log
.table(['header1', 'header2'])
.row({'key1': 'val1'})
.row({'key2': 'val2'})
.echo()
diff
(uses a fork of ava-format which is a fork of jest-diff which is a fork of google's diff-match-patch)
Compare two pieces of data. Data will be cloned so it can be mutated if needed, and then compared.
log.diff(oneOneTwoTwo)
log.diff(oneOneTwoTwo + '... two-two was one, two.')
log.echo()
(previously deep-diff & cli-table was used.)
const lowlyPeasant = {pauper: true}
log.diff(royalty)
const abomination = Object.assign(royalty, lowlyPeasant)
log.diff(abomination)
log.echo()
cleaner
extremely powerful tool built with chain-able using a fork of js-traverse
can take next-to-unusable output such as this
...or you could clean out certain phrases from every log
obj.circularReference = obj
obj[Symbol('foo')] = 'foo'
obj.map = new Map()
obj.map.set('prop', 'value')
obj.array = [1, NaN, Infinity]
log.prettyformat(obj).echo()
const cleaner = log
.cleaner(true)
.keys([/array|circularReference|map|property/])
.data(obj)
.clean()
.echo()
spinner
- extends cli-spinner
- uses cli-spinners
.Spinneris available on fliplog as the instantiated spinner
easy
log.bold().startSpinner('loading...')
setTimeout(() => log.stopSpinner(), 2000)
advanced
log.startSpinner('spinner message', {
// optional spinner args
onTick: () => {},
// where to output the logs, default process.stdout
stream: () => {}
// default 60
delay: 80,
})
console.log('log this, then spinner shows up again - it is sticky.')
log.stopSpinner()
multiple
- uses node-multispinner
log
.addSpinner('key1', 'spinner 1 msg')
.addSpinner('key2', 'spinner 2 msg')
.addSpinner('key3', 'spinner 3 msg')
// arg is optionally a string for frames
// or an object for multi-spinner options
.startSpinners()
// string arg removes by name
setTimeout(() => log.removeSpinner('key1'), 1000)
// empty args removes all
setTimeout(() => log.removeSpinner(), 20000)
ora
.orais available as a method with the same options- adds
.fliplogto theorainstance to allow chaining back to fliplog - returns
orainstance
log.ora('loading...').start()
// or
log.spinner('loading...', {ora: true})
progress
default
interval callback
total, cb(bar, interval), interval time
bar.tick()
if (bar.complete) clearInterval(interval)
}, 1000)
advanced
const bar = log.progress(' downloading [:bar] :percent :etas', {
complete: '=',
incomplete: ' ',
width: 20,
total: contentLength,
}).progressBar
function next() {
if (!contentLength) return
bar.tick(Math.random() * 10 * 1024)
if (!bar.complete) setTimeout(next, Math.random() * 1000)
}
next()
notify
- allows passing in the same options from node-notifier
string title and [description]
or a string for title
.notify('woot!', 'super long and not as important description')
.echo()
shorthand (echo immediate)
stack traces
catch errors
will output the stack trace formatted and inspected deeply with the error preset
.then(() => Promise.reject(''))
.catch(log.catch)
find logs
in your entry point, calling log.track() will output the location all of the next logs output from.
// later on...
log.bold('I cannot be found... oh wait, I was tracked.').echo()
you can also track every console.log anywhere
// becomes `eh 'at your-file#the-line-number'`
console.log('me!')
trace
calling .trace will output a shortened stack trace to the current location.
(r) register
registerConsole
defines properties on the console global and automatically calls echo where applicable, for easier access:
console.time('so easy')
console.bold('hullabaloo')
console.error(new Error('eh-rar'))
console.timeEnd('so easy')
console.quick('toodaloo')
// also available
// verbose, info, error, track, trace, note, warning, spinner, time, timeEnd, timeLap timeLapEcho, box, beep, timer, table, diff, diffs, stringify, stack, json, filter, tags, quick, exit, reset, sleep, slow, red, yellow, cyan, underline, magenta, bold
registerCatch
catches uncaught promises and errors, displays them verbosely.
throw new Error('eh')
Promise.reject('eh')
[CL] clear
this will clear the terminal (at least, move it down so it is clear)
deep
vs
| goal | winner |
|---|---|
| code source | tosource |
| deep inside objects | verbose |
| colors | verbose |
verbose
using inspector-gadget, objects are inspected and colorized as deep as configured
.bold('verbose:')
.data({
numbers: 1000,
booleans: true,
functions: () => {},
strings: 'wacky wavy fun',
})
.verbose(/* optional number for how deep to go */)
.echo()
tosource
see the code source using tosource for nodejs you can look at the source of a variable
.bold('tosource:')
.data({
numbers: 1000,
booleans: true,
functions: () => {},
strings: 'wacky wavy fun',
})
.tosource()
.echo()
highlight
- cli-highlight (but will not output wrapping html tags around the code, other options are disabled, default themes are used)
log
.data(highlitedWithColors)
.tosource()
.highlight()
.echo()
presets
add your own
return chain.text(' warning:').color('bgYellow.black').verbose(10)
})
use built-ins
.preset('warning')
.data('nananenano!')
.echo()
log
.preset('error')
.data(new Error('prettyfull!'))
.echo()
timestamps
.time(true)
.color('cyan')
.text(' so deep, so colorful, so meta ')
.data(log)
.verbose()
.echo()
from
to use logging from a pure js object, .from is available
data: 'data',
text: 'eh',
color: 'bold',
echo: true,
})
^ is the same as
.text('eh')
.data('data')
.color('bold')
.echo()
fun
these will all be silent by default, so you can easily disable them by filtering your logs or setting silent output which can be exceedingly helpful.
tree
.color('green')
.text(' treeify')
.tree({
oranges: {
mandarin: {
clementine: null,
tangerine: 'so cheap and juicy!',
},
},
apples: {
'gala': null,
'pink lady': null,
},
})
.echo()
sparkly
- options from sparkly can be passed in
- will output a random sparkle if it is not set
bar
- will output a random bar chart if not set
- options from babar can be passed in
random
bar
for (var i = 0; i < Math.PI * 2; i += Math.PI / 1000) {
points.push([i, Math.cos(i)]);
}
log.bar(points).echo()
styles and bar
.bar([[0, 1], [1, 5], [2, 5], [3, 1], [4, 6]])
.barStyles({
width: 80,
height: 10,
color: 'yellow',
maxY: 100
})
.echo()
beep
all options from beeper
box
- all boxen options
colors
log.bold().box('fliplog').echo()
// echos right away
log.box('fliplog', true)
// use boxen box styles
log
.boxStyles({borderColor: 'blue'})
.box('fliplog')
.echo()
formatting
// returns the currently formatted text and data
const {text, data} = log.returnVals()
// returns every single setting as an object, resets
const everything = log.return()
space
will output number of spaces after your log
slow
slow mode allows debugging each log step-by-step, and will force a sleep usable across all environments using sleepfor
log.emoji('snail').yellow('slow...').echo()
const start = Date.now()
log.emoji('snail').yellow('...slow').echo()
const end = Date.now() - start
timer
start, stop, lap, and timer instance using fliptime
.startTimer('named')
.sleep(1000)
.stopTimer('named')
.echoTimer('named')
or for more customized usage
sleepfor(1000)
log.stopTimer('named').echoTimer('named')
const fliptime = log.fliptime()
formatter
allows final formatting of the data before echoing
interesting to note, this is how most plugins do their formatting
if (!data || typeof data !== 'object') return data
Object
.keys(data)
.forEach(key => {
if (typeof data[key] === 'string')
data[key] = data[key].replace(/\s{2}/gmi, ' ')
else if (Array.isArray(data[key]))
data[key] = data[key].map(a => cb(a.name))
})
return data
}
const fixture = {
str: 'I have too many spaces',
arr: [{name: 'eh'}, {noname: 'just undefined'}],
}
log
.formatter(cb)
.data(fixture)
.echo()
performance
config
to keep the module lightweight, almost all functionality is added through plugins.
requiring
all non-core dependencies are required when functions are called & the filtering passes. this way, only the used-functionality is loaded.
additionally, almost all of the functions are not formatted until .echo(), so they will not have dependencies loaded when echoing is false which means code does not have to be changed for production.
if echo(false) or filtering disables the output, they are never called.
resources
- for more on the library used for fluent apis, see flipchain
TODO
- to file
- to stream
- middleware alongside .return
- configure which keys are persistent across instances