5.x Roadmap

[Qix-]

5.x Roadmap

It's about time for another step in bringing debug up to date - the 5.x major release.

I know it hasn't been a long time since 4.x was released, and I'm aware that its release kind of forced.. pushed.. nudged users to update their best practices.

Here's what to expect from the 5.x release:

• Custom output format (Customizing output format #582, Custom output formatting #645)
• Pluggable logging handlers ([RFC] Pluggable log handler #556)
• Timed sections (Add timed sections #485)
• No more transpiling (smaller package size) (Remove build step / bundling / babelifying #652, Remove build system #655)
• Patching of old debug versions for formatting and pluggability upgrades ([RFC] Compatibility layer #644)
• Overhaul of .enable() (debug.enable() flushes enabled namespaces #425, Wildcard in name doesn't auto enable on web #636, Regex injection in enable(namespaces) #737)
• Use console.debug() in the browser where available (Use console.debug() instead of console.log() where available (e.g. browsers) #600)
• Simpler documentation (Clean up README #649)
• Passing a function to avoid execution if namespace is disabled (Allow function to be passed & executed if enabled #497)
• Simplified codebase (lots dead code/dotfile removal; [RFC] Remove examples/ folder in lieu of proper README documentation? #650)
• Specify namespace in URL (Specify namespace with url in ESM #948)
• Several bugfixes

[OllieJennings]

Any chance we can get the issue fixed where you have

.env

DEBUG=*

And you run babel-node -r dotenv/config ./index.js

As right now this won't work

[Qix-]

@OllieJennings #705 please search next time.

[botond-veress]

@OllieJennings, that issue was closed prematurely, but it is not fixed. I switched back to debug@3 until the issue will get some attention and will be fixed. I suggest you to do the same thing.

[Qix-]

Please, there's no reason to post in two separate places about a closed ticket. Keep all discussion about that there - posting on the roadmap issue isn't going to get my attention any faster, I look at all issues regardless of urgency.

[getsnoopy]

Just to confirm, the 5.x roadmap stipulates that the module will use console.debug for Node.js environments as well, correct? The description in the OP here is different than that of the linked issue.

[Qix-]

@getsnoopy It'll be configurable. If you want to use something other than console.debug you would make your own log handler. That's defined in #556.

[suiyun39]

If remove build system, How to also supports esm and cjs module?
When used in nodejs, in most cases no bundle tools, requires the library to provide two versions of the export.

like this:

"exports": {
  ".": {
    "import": "./dist/my-lib.mjs",
    "require": "./dist/my-lib.umd.js"
  }
}

[FossPrime]

I ended up doing a complete rewrite and adding Deno support by accident while trying to add ESM support.

• Sandbox: https://dash.deno.com/playground/dude-get-a-framework
• source

I think it would be a good jumping off point for a necessary refactor for node ESM/Unpkg's ?module mode/Vite/TS etc.

Issues that code addresses to some degree:

1. removing require packages within the code
2. Remove all module.export as a global hashmap use.
3. Sharing globals as both runtime configuration and user-land API surface
4. Reduce reliance on optional globals and use globalThis to check for them
5. Reduced Node API surface area, including stderr.fd, writing to process.ENV, and other non JavaScript stuff.
6. Avoid swallowing errors
7. Avoid hoisting, use better structures like Class, singletons and modules instead
8. Rename single word internal functions to multi-word names, specially when they conflict

I propose the following restructure:

1. DebugCore.class.mjs (common.js)
2. DebugFactory.class.mjs

Then for actual front facing code, we would use conditional exports to set the default entry point. You can do

{
  ".": {
    "node": "NodeDebug.class.mjs",
    "deno": "DenoDebug.class.mjs", 
    "browser": "BrowserDebug.class.mjs", // I think this is deprecated in favor of module
    "default": "Debug.class.mjs"
  }
}

Other things that would help:

• Move away from Istanbul (deprecated) / Klarna, to the built-in new test runner for unit testing
• We do not need a whole DOM browser for E2E... jsdom, might enough
• Have way more sandboxes and examples for people to use this library... not just use it begrudgingly when they are stuck
• Welcome experiments in some way... like a labs folder. ESM makes providing experimental exports, free to user-land.

Great api BTW!

[bryanjtc]

What is the status of v5? How long until a release that supports esm?

[Qix-]

Debug already supports ESM, and we're still kind of blocked on some Node things.

[bryanjtc]

Debug already supports ESM, and we're still kind of blocked on some Node things.

When reading the readme I assumed it didn't supported it because of all the requires.
Have you thought of simplifying the release and push those blocking changes to v6?

[Qix-]

There's not much to release at the moment. Plus it doesn't make sense to do much now until Node reaches feature parity with the requires() system.

Node ESM is inherently compatible with old require() packages by the way. Just because we have require() in the readme doesn't stop you from importing it.

[adominguezepiuse]

I hope all is well. I've been keeping an eye on the discussions regarding the ReDoS vulnerability. I was wondering if there's any general sense or rough estimate on when we might expect the release of version 5.x with the necessary security updates. I understand that these things take time, and I appreciate the team's efforts to ensure a thorough fix.

[Qix-]

There's very little security risk in pre-5.x. Just don't feed user input into the main debug constructor.

[OleksandrKucherenko]

Will be great to have a conditional debug messages:

const showMessageToUser = /* some complex condition */
debug.if(showMessageToUser)(/* ... */)

Another great feature to have is a multiplexer, output of the same debug log-message to multiple namespaces:

debug.to('namespace1', ... , 'namespaceN')('something strange: %o', object)

this is useful when we have several namespaces that are attached to logs tracker systems (elk, datadog, etc) and we need that message be delivered to multiple "channels"

[OleksandrKucherenko]

One more feature: Escalate/DeEscalate

for example we have some complex logic that may raise the exception... so idea is: when we caught the exception escalate the logs verbosity and when for example we do not have exceptions for some defined time, automatically de-escalate verbosity.

try {
  /* some logic */

  debug.deescalate('2m', { /*options*/}) // normal execution, recover normal state of logs in 2 minutes
} catch (e) {
  /* that should never happens */

 // if it happens escalate verbosity for all namespaces for next 15mins
 debug.escalate('15m', {cause: e, namespaces: '*', /* options */}) 
}

and will be great to provide some kind of human readable time periods: 'now', '1m', '1h', '90m', '1h30m'

p.s. and it will be great to have some buffer of prev messages that were not published/printed, but in the moment of escalation they can be reviewed and published.

p.p.s. escalate/deescalate logic can be base on timer or "score" logic. "Score" logic means that we increase the priority score to some level, that corresponding specific levels of logs enabling (info, warning, debug, verbose, all). Escalate will increase the score, de-escalate will reduce the score.

ref: https://medium.com/@olku/logging-its-hard-to-make-it-right-part-1-caa066c0e6b

[Qix-]

Both of those things are entirely out of scope for thie package, sorry.

[OleksandrKucherenko]

Can we have an debug lib extension API, so it will be possible to implement those features as additional library?