RFC: 3.0 API & Ideas

[thebigredgeek]

Hey everyone,

I figured it's time to start discussing the API for V3.

A few fundamental ideas to get started:

• (No) Code written in ES2015 (minimal transpilation?, no es6 modules)
• (Yes) Robust test coverage
• (Yes) XO Code Styling
• (Yes) "Replaceable middleware" pattern for formatting, output, etc. Extensible. This allows hooks for stuff like logstash and client-to-server log streaming as desired. Middleware is FIFO and debug comes with a default set for formatting, output, environment adaptation, etc. Ex:

 //Stdout would be default console.log middleware
import debug, { StdoutMiddleware } from 'debug';
// Add some sort of new middleware element
log.use((data, next) => ... )
// replace Stdout (console.log) with console.info at same position in middleware array
log.replace(StdoutMiddleware, (data, next) => {
  console.info.apply(console, data);
  next(); 
});

• (Yes) "Child" debug instances (which inherit middleware from parent debug instances). Ex:

const log1 = debug('foo');
log1.use((data, next) => ... );
const log2 = log.child('bar');
log2('hello world'); // => foo:bar hello world

• (Yes) Formal organized schema for CHANGELOG.md

• (Yes) Dead-simple generated documentation

• (Yes) Time locale configuration

• (Yes) Stdout moved off of APIs that are pending removal (RFC: 3.0 stdout moved off of APIs that are pending removal #280)

• (No) Ability to enable/disable debug instances

• (Maybe) API to overwrite/set environment variables by key (How to use with AWS Lambda (ie. w/o env vars)? #277)

Any other ideas are welcome. I'd love to have a completed first pass draft by the end of next week.

[thebigredgeek]

#343 - Middleware use case

[kilianc]

@thebigredgeek I am not sure if this came up somewhere else of there is already a solution in place but it would be nice to be able to switch between STDERR and STDOUT at the API level.

Example:

import createDebug from 'debug'

const debug = createDebug('app:upload')

Promise.reject(new Error('Something terrible happened O_O'))
  .catch((err) => debug.error(err.message))

Promise.resolve({ status: 'ok' })
  .then((data) => debug(data.status))

[thebigredgeek]

@kilianc Seems like that case could be solved via a combination of child instances and middleware:

import debug, { StdoutMiddleware } from 'debug';

const appUploadLog = debug('app:upload');

const appUploadErrLog = appUploadLog
  .child('error')
  .replace(StdoutMiddleware, (data, next) => {
    console.error.apply(console, data);
    next()
  });

[ibc]

Hi, sorry if I missed something but, does (No) Ability to enable/disable debug instances means that such a feature is not even under consideration?

[thebigredgeek]

@ibc We are still considering (maybe) API to overwrite/set environment variables by key, which should do the exact same thing as (No) Ability to enable/disable debug instances.

[simonhac]

@thebigredgeek, following @ibc's comment, i am a contributor to a plugin for an application. the applications manages all config and hands the plugin a config object at initialisation time.

it is normal practice that users of the application turn logging on/off through the config object.

so i needed to be able to individually enable/disable debug 'channels' at runtime.

i extended @tehsenaus's excellent hot-debug (fork of debug) with this PR -- i'll fork it off into a project one day soon.

basically, i'm hoping that v3 will allow (either directly or via its own plugin middleware layer):

var debug = require('debug')('myPlugin')

...

function myInit(config) {
  debug.enable(config.debugEnabled)
}

[stefcameron]

What @VBAssassin wrote is a very good idea. I've used this to great effect in a logging class I wrote for use in many projects I've worked on. It also helps mitigate the overhead in the case where logging is disabled, or that particular logger is disabled.

[jfseb]

Apologizes or enlighten me if this is already in:

I often face the issue that debug instrumentation bogs down performance.

var debuglog = require('debug')('myfile') 
debuglog(" inspect this > " + JSON.stringify(bitstuff, undefined,2)); // ooh, hefty Stringify

So i end up with
debuglog( debuglog.enabled ? " inspect this > " + JSON.stringify(bitstuff, undefined,2) : "") ;
or similar.

Suggestion is to change the signature to evaluate (lazily) if passed a function

debuglog( () => `Inspect this > " + JSON.stringify(bitstuff, undefined,2) ) ;

Currently it recognizes the arg as a function and outputs:
myfile [Function] +0ms
which is not that much use. So either be incompatible or add a wrapper evalfunc

var debuglog = require('debug')('myfile').evalfunc;
debuglog( () => `Inspect this > " + JSON.stringify(bitstuff, undefined,2) ) ;

[ibc]

var debuglog = require('debug')('myfile').evalfunc;

Couldn't it just internally check typeof arguments[0] === 'function'?

[TooTallNate]

@jfseb Use the %j or %O formatters:

debuglog(" inspect this > %j", bitstuff);

That way you're just passing in an argument to a noop function when debug is not enabled. Then the processing happens under the hood when debug is enabled.

[PixnBits]

@TooTallNate works for this simple JSON case, but not sure about @VBAssassin's example

[jfseb]

My recommendation was actually a duplicate, thanks @PixnBits and @VBAssassin.

[tehsenaus]

@VBAssassin Can you not already do this?

if ( debug.enabled ) {
    debug(mysql.format(sql,values));
}

IMO the above is more readable, and more efficient as you're not creating a closure.

[StreetStrider]

@tehsenaus your code is lack encapsulation, it requires to know about enabled and also write an if every time; while @VBAssassin follows the common idea behind debug that «debug works only in debug» (in that case a function is passed) and pretty encapsulated.

[talkingtab]

I like the simple syntax of the closure- I'm much more likely to use it. And because it uses the same form as console.log() I don't have to remember a special syntax.

…

On 5/30/17 7:06 AM, Sean Micklethwaite wrote: @VBAssassin <https://github.com/vbassassin> Can you not already do this? |if ( debug.enabled ) { debug(mysql.format(sql,values)); } | IMO the above is more readable, and more efficient as you're not creating a closure. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#370 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAC5InJQhkOLTUKoIn-7fGQXk6Qx4Xc4ks5r-_gcgaJpZM4LNeHb>.

[tehsenaus]

@talkingtab how is it the same form as console.log?

@StreetStrider can you comment on readability? As far as encapsulation goes, I think .enabled wouldn't be a surprising or controversial addition to the public API of any logging library.

[StreetStrider]

@tehsenaus, to be honest, I think closure got better readability too. But it depends on person itself (partly). 🤔 It's like for-loops against map/forEach. Some people found for-loop more readable.

[talkingtab]

I just mean they take the same arguments:

[stefcameron]

@StreetStrider @tehsenaus Another way of writing this, given debug.enabled, would be:

debug.enabled && debug(mysql.format(sql, values);

That might be a little more friendly, visually, and it still ensures that whatever code is on the right side of && is only executed if debug is enabled. So you don't need a closure in this case. This form would also enable code optimizations with transpilers that support tree shaking. Telling the transpiler that debug.enabled === false would allow it to stip-out all the debug statements from the resulting code.

[131]

debug simplicity come from the initial, user defined DEBUG env contract "What i care about".
Inthe same design, I suggest to use a simple process.env.DEBUG_FORMAT (from tj/progress inspiration) that might default to :

process.env.DEBUG_FORMAT = ":timestamp :namespace :body :timediff";

with additionnal formaters like
::namespace_colored
:timestamp_iso

Registering additional formaters should be part of debug API, yet, leaving the user choosing, very simply, what he desired (the same way he choose the namespaces he cares about)

Is there anyone sharing this view ?

[Qix-]

Just throwing this out there - since this will be a major release I assume, the LTS schedule for Node should be closely followed. Right now, Node 5 is in LTS, which means es2015 should be safely distributable without the need for transpilation.

[yamikuronue]

@Qix- You mean Node 4?

Also: this is transpiled for the frontend, as well as being available on the backend. It's safest and least problematic to stick to a widely-supported subset of JS when making code available for three platforms (Node, Electron, and front-end).

[thebigredgeek]

@Qix- haha yeah I wish it was that simple. This lib is used in electron, browser, etc as well as Node. So probably not going to work out so well without transpilation :(. That said, because of the number of platforms we are supporting I do think there could be value in using a compiler step to normalize interfaces between environments. @TooTallNate

[yamikuronue]

@thebigredgeek I mean, I did remove the transpilation step by just rewriting the thing in ES5 code ;P

[Qix-]

@yamikuronue Node 4 is in maintenance LTS. Node 5 is currently the active LTS version.

[yamikuronue]

@qix meaning Node 4 still has support. My company is skipping 5 because 4 is still in support and we might as well go to 6 as we upgrade in anticipation of losing that support. So I'm hesitant to recommend the idea that 5 is safe to assume for a widely used utility.

[Qix-]

Oops you're right @yamikuronue - 5.x is skipped, 6.x is now active LTS. 4.x is still maintenance, which means versions of software that still work for 4.x should backport any major bugfixes to it.

[paulrobello]

I think it would nice to be able specify my own color for a namespace or even a single call to log some output