RFC: 3.0 API & Ideas

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.

#343 - Middleware use case

@thebigredgeek

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

@kilianc

@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()
  });

@thebigredgeek

@thebigredgeek that's fair. Not that far from what I do today:

const createDebug = require('debug')

module.exports = (label) => {
  const debug = createDebug(label)
  debug.error = createDebug(label)
  debug.error.log = console.error.bind(console)
  return debug
}

This seems a generic enough use case to consider adding a method to all debug instances by default.

For example, I like the .child method but it is not that different from:

const debug = require('debug')
const NAME = process.env.DEBUG_NAMESPACE || 'app'

module.exports = (name) => debug(`${NAME}:${name}`)

It would be nice if we could gather together the most common use cases and add these in the default implementation, even in the form of middleware for consistency. It's just cumbersome for me to carry around a setup file for debug (require('../lib/debug')) that looks always the same :D.

@talkingtab

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

@tehsenaus

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

I just mean they take the same arguments:

@StreetStrider

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

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 ?

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.

@Qix-

@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).

@Qix-

@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

@thebigredgeek

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

@yamikuronue

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

@qix

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

@yamikuronue

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.

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

Navigation Menu

Repository navigation

RFC: 3.0 API & Ideas #370

78 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

RFC: 3.0 API & Ideas #370

Description

Activity

thebigredgeek commented on Dec 14, 2016

kilianc commented on Dec 14, 2016

thebigredgeek commented on Dec 14, 2016

kilianc commented on Dec 14, 2016

78 remaining items

tehsenaus commented on May 30, 2017

StreetStrider commented on May 30, 2017

talkingtab commented on May 30, 2017

stefcameron commented on May 30, 2017

131 commented on Jun 10, 2017

Qix- commented on Aug 8, 2017

yamikuronue commented on Aug 8, 2017

thebigredgeek commented on Aug 8, 2017

yamikuronue commented on Aug 8, 2017

Qix- commented on Aug 8, 2017

yamikuronue commented on Aug 8, 2017

Qix- commented on Aug 8, 2017

paulrobello commented on Sep 24, 2017

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions