fliplog

all-in-one logging tool

usage

yarn add fliplog
npm i fliplog --save

const log = require('fliplog')

🔠 description

🗝️ legend:

• 👋 basics
• 🎀 stringifying

• 🙊 silencing

• 🎨 color

• function
• 😊 emoji
• ☕ filtering

• 🛑 quick
• ⬛ table
• 🛁 cleaner
• ⚖️ diff
• 🌀 spinner

• 📈 progress
• 🛎 notify
• 🗺 stack traces
• 🔎 finding logs
• ⚾ catch errors
• ®️ .register
• trace
• 🆑 clear
• 🕳 deep

• 💈 highlight
• 🍰 presets

• ⌛ timestamps
• from
• 🎢 fun

- [🛰 space](#-space)
- [💱 formatter](#-formatter)

• resources

👋 basics

log
  .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

📝📚 all of these new ones need more docs

+ == .echo

log.italic('so short!')+

// ^ same as `log.italic('so short!').echo()`

🎀 stringifying

json

// optional second arg for options passed into pretty json
log.json({eh: 'prettified'})

stringify

// args are the same as 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()

// captured data is available here
const saved = log.savedLog

return

// 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

log
.text('\n========================================\n')
.color('bold')
.echo()

shorthands

log
  .bold('same as calling .color(bold).text(all this text)')
  .echo()

xterm

log
  .time(true)
  .xterm(202, 236).text(' orange!!! ')
  .echo()

function

log({data: true}, 'text', 'color')

😊 emoji

log
  .emoji('phone')
  .text('et')
  .data('phone home')
  .echo()

☕ filtering

🔢 level

log.filter('>= 1')
log.level(1).bold('above 1... success').echo()
log.level(0).bold('not above 1...').echo()

🎯 matcher

log.filter(['canada*'])
log.tag('canada-eh').white('canadian, pass.').echo()

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()

filter & tags

• verbose enables everything
• silent 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

yourprogram --DEBUG="!nope,yes"
yourprogram --DEBUG=verbose

🛑 quick

log.quick({give: 'me'}, 'everything', 'and quit')

// or
log.data({now: 'die'}).exit(1)

⬛ tables

log
  .table(['header1', 'header2'], ['row1', 'row2'])
  .echo()

log
  .table(['header1', 'header2'])
  .row({'key1': 'val1'})
  .row({'key2': 'val2'})
  .echo()

⚖️ diff

let oneOneTwoTwo = 'one-one  was a race horse 🐎 '
log.diff(oneOneTwoTwo)
log.diff(oneOneTwoTwo + '... two-two was one, two.')
log.echo()

const royalty = {posh: true}
const lowlyPeasant = {pauper: true}
log.diff(royalty)
const abomination = Object.assign(royalty, lowlyPeasant)
log.diff(abomination)
log.echo()

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

• extends cli-spinner
• uses cli-spinners
• .Spinner is available on fliplog as the instantiated spinner

easy

// easy to color spinners
log.bold().startSpinner('loading...')
setTimeout(() => log.stopSpinner(), 2000)

advanced

// instance available on log.Spinner
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

// instance available on log.spinners
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

• .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

// call .ora
log.ora('loading...').start()

// or
log.spinner('loading...', {ora: true})

📈 progress

• node-progress

default

log.progress()

interval callback

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

• allows passing in the same options from node-notifier

string title and description

log
  .notify('woot!', 'super long and not as important description')
  .echo()

shorthand (echo immediate)

log.notify('woot!', true)

🗺 stack traces

⚾ catch errors

const ForeverAndEver = new Promise(resolve => Promise.resolve())
  .then(() => Promise.reject('💍'))
  .catch(log.catch)

🔎 find logs

log.track()

// later on...

log.bold('I cannot be found... oh wait, I was tracked.').echo()

log.trackConsole()

// becomes `eh 'at your-file#the-line-number'`
console.log('me!')

trace

log.data({bigData: 'oh'}).trace().echo()

®️ register

registerConsole

log.registerConsole()

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

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

verbose

log
  .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

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

log.from({
  data: 'data',
  text: 'eh',
  color: 'bold',
  echo: true,
})

log
  .text('eh')
  .data('data')
  .color('bold')
  .echo()

🎢 fun

🌲 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

log.beep(1).echo()

📦 box

• all boxen options

colors

// with bold 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

log.data({}).bold('text')

// 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

log.text('followed by 2 empty lines').space(2).echo()

🐌 slow

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

log
  .startTimer('named')
  .sleep(1000)
  .stopTimer('named')
  .echoTimer('named')

log.startTimer('named')

sleepfor(1000)

log.stopTimer('named').echoTimer('named')

const fliptime = log.fliptime()

💱 formatter

✍ 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

requiring

🔗 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