āš fliplog
all-in-one logging tool
usage
yarn add fliplog
npm i fliplog --save
const log = require('fliplog')
š 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
log
.data({anyKindOfData: true})
.text('text to use, this is what gets colored')
.color('bold')
.echo()
š NEW!
šš all of these new ones need more docs
š read the wip docs for new stuff on the wiki
+
== .echo
log.italic('so short!')+
š stringifying
json
prettyjson
log.json({eh: 'prettified'})
stringify
javascript-stringify
log.stringify({data: 'can stringify deep things'})
š silencing
- to disable outputting a log,
.silence()
(optional true
/false
arg) - to disable all logs,
.shush()
- to enable all logs,
.unshush()
capture all
capture output of all console logs everywhere
log.startCapturing()
console.log('this will be captured')
log.stopCapturing()
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()
const everything = log
.color('blue.underline')
.data({canYouHandleIt: true})
.text('M')
.return()
šØ color
chalk
all chalk colors available with .color
log
.text('\n========================================\n')
.color('bold')
.echo()
shorthands
log
.bold('same as calling .color(bold).text(all this text)')
.echo()
xterm
all cli-color are available by calling .xterm
log
.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
log({data: true}, 'text', 'color')
stack
š emoji
names using emoji-commits are available with .emoji
(currently š§ not all have been ported yet)
log
.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.filter('>= 1')
log.level(1).bold('above 1... success').echo()
log.level(0).bold('not above 1...').echo()
šÆ matcher
filter using an Array
made up of Function
s, String
s, and RegExp
s!
log.filter(['canada*'])
log.tag('canada-eh').white('canadian, pass.').echo()
more advanced
log.filter(['eh*', '!warm', tag => (/ez/).test(tag)])
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
verbose
enables everythingsilent
silences everything!
means disabled
log
.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="!nope,yes"
yourprogram --DEBUG=verbose
š quick
quickly log data and exit if you want to stop execution at a certain point for
debugging
log.quick({give: 'me'}, 'everything', 'and quit')
log.data({now: 'die'}).exit(1)
ā¬ tables
extending cli-table2
log
.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.
let oneOneTwoTwo = 'one-one was a race horse š '
log.diff(oneOneTwoTwo)
log.diff(oneOneTwoTwo + '... two-two was one, two.')
log.echo()
(previously deep-diff & cli-table was used.)
const royalty = {posh: true}
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
and clean it usable
...or you could clean out certain phrases from every log
var obj = {property: {}}
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
easy
log.bold().startSpinner('loading...')
setTimeout(() => log.stopSpinner(), 2000)
advanced
log.startSpinner('spinner message', {
onTick: () => {},
stream: () => {}
delay: 80,
})
console.log('log this, then spinner shows up again - it is sticky.')
log.stopSpinner()
šš multiple
log
.addSpinner('key1', 'spinner 1 msg')
.addSpinner('key2', 'spinner 2 msg')
.addSpinner('key3', 'spinner 3 msg')
.startSpinners()
setTimeout(() => log.removeSpinner('key1'), 1000)
setTimeout(() => log.removeSpinner(), 20000)
ora
.ora
is available as a method with the same options- adds
.fliplog
to the ora
instance to allow chaining back to fliplog - returns
ora
instance
log.ora('loading...').start()
log.spinner('loading...', {ora: true})
š progress
default
log.progress()
interval callback
total, cb(bar, interval), interval time
log.progress(20, (bar, interval) => {
bar.tick()
if (bar.complete) clearInterval(interval)
}, 1000)
advanced
let contentLength = 128 * 1024
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
string title and [description]
or a string
for title
log
.notify('woot!', 'super long and not as important description')
.echo()
shorthand (echo immediate)
log.notify('woot!', true)
šŗ stack traces
ā¾ catch errors
will output the stack trace formatted and inspected deeply with the error preset
const ForeverAndEver = new Promise(resolve => Promise.resolve())
.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.
log.track()
log.bold('I cannot be found... oh wait, I was tracked.').echo()
you can also track every console.log anywhere
log.trackConsole()
console.log('me!')
trace
calling .trace
will output a shortened stack trace to the current location.
log.data({bigData: 'oh'}).trace().echo()
Ā®ļø register
registerConsole
defines properties on the console
global and automatically calls echo
where applicable, for easier access:
log.registerConsole()
console.time('so easy')
console.bold('hullabaloo')
console.error(new Error('eh-rar'))
console.timeEnd('so easy')
console.quick('toodaloo')
registerCatch
catches uncaught promises and errors, displays them verbosely.
log.registerCatch()
throw new Error('eh')
Promise.reject('eh')
š clear
this will clear the terminal (at least, move it down so it is clear)
log.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
log
.bold('verbose:')
.data({
numbers: 1000,
booleans: true,
functions: () => {},
strings: 'wacky wavy fun',
})
.verbose()
.echo()
tosource
see the code source
using tosource for nodejs you can look at the source of a variable
log
.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)
function highlitedWithColors() { return 'notice me' }
log
.data(highlitedWithColors)
.tosource()
.highlight()
.echo()
š° presets
add your own
log.addPreset('warning', (chain) => {
return chain.text('ā warning:').color('bgYellow.black').verbose(10)
})
use built-ins
log
.preset('warning')
.data('nananenano!')
.echo()
log
.preset('error')
.data(new Error('prettyfull!'))
.echo()
ā timestamps
log
.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
log.from({
data: 'data',
text: 'eh',
color: 'bold',
echo: true,
})
^ is the same as
log
.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
log
.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
log.sparkly().echo()
š bar
- will output a random bar chart if not set
- options from babar can be passed in
random
log.bar().echo()
bar
const points = []
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
log
.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
log.beep(1).echo()
š¦ box
colors
log.bold().box('fliplog').echo()
log.box('fliplog', true)
log
.boxStyles({borderColor: 'blue'})
.box('fliplog')
.echo()
š£ formatting
log.data({}).bold('text')
const {text, data} = log.returnVals()
const everything = log.return()
š° space
will output number
of spaces after your log
log.text('followed by 2 empty lines').space(2).echo()
š slow
slow mode allows debugging each log step-by-step, and will force a sleep
usable across all environments using sleepfor
log.slow(1000)
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
log
.startTimer('named')
.sleep(1000)
.stopTimer('named')
.echoTimer('named')
or for more customized usage
log.startTimer('named')
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
function cb(data) {
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
š TODO
- to file š
- to stream
- middleware alongside .return
- configure which keys are persistent across instances