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 (https://github.com/visionmedia/debug/issues/280)

• (No) Ability to enable/disable debug instances

• (Maybe) API to overwrite/set environment variables by key (https://github.com/visionmedia/debug/issues/277)

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

[yamikuronue]

I think the most important thing to keep in mind is simplicity. This module is incredibly simple to use; you’ll want to make sure it remains dead simple to use, and is as simple as possible to extend and configure.

[adoyle-h]

I think it will be a great feature to achieve the “Ability to enable/disable specific debugging namespaces at runtime”. Sometimes I want to debug a http server step by step. For examples,

debug.enable('connect:*');
// check out the logs
debug.disable('connect:*');
debug.enable('http:body-parser');
// send request and check out the logs
debug.disable('http:body-parser');
debug.enable('http:response');
// send another request and check out the logs
// ...

Changing environment variables could also work. Stopping the server, setting different environment variables, restarting server again, and it maybe cost much time for waiting server to start. So it is complicated for the scenario. I desire to debug without shutting down the process.

middleware is a way to transform data in a pipeline. But how to extend the debug instance itself? To implement debug.enable(namespace) and debug.disable(namespace) methods. Could you provide any appropriate cases? @thebigredgeek