npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

unbug

v1.0.0

Published

A feature packed debugging tool

Downloads

2

Readme

unbug

Unbug

Unbug is a tiny debugging utility for Node.js.

Installation

~$ npm install unbug

Usage

The default export of unbug is a function, which takes the name of the module you are debugging. It will return a wrapper around console.debug for you to debug things. This will allow you to toggle debugging on and off for different parts of you app and the whole.

import unbug from 'unbug';
import http from 'http';
import worker from './worker.js'; // fake worker of some kind

const debug = unbug('my-app');

debug('Booting up');

http.createServer((req, res) => {
  debug('Request received: %s %s', req.method, req.url);
  res.end('Hello');
}).listen(3000, () => debug('Server started'));

worker.workA();
worker.workB();

worker.js

import unbug from 'unbug';

const worker = unbug('worker');
const a = worker.extend('a');
const b = worker.extend('b');

export function workA() {
  a('Doing some stuff');
  setTimeout(workA, Math.random() * 1000);
}

export function workB() {
  b('Doing some other stuff');
  setTimeout(workB, Math.random() * 1000);
}

We can now use the DEBUG environment variable to toggle debugging on and off

Here are some examples:

unbug http unbug worker unbug with minus

Colors

Every debugging namespace (aka scope) has a color associated with it. This can help visually identify which debugging messages belong to which scope.

The colors can be disabled by setting the DEBUG_COLORS environment variable to something falsy (false, no, 0, nope, etc.)

The colors used can be configured. See Configuration for more

Millisecond diff

When actively working on an application, it may be helpful to see the times between unbug calls. Unbug shows you a +NNNms diff between debug calls. For more advanced timing utilities, check out debug.time

Extending

You can extend unbug instances. If you enable an instance, all it's nested instances will also be enabled, unless you explicitly filter them out.

import unbug from 'unbug';

const node = unbug('node');
const worker = node.extend('worker');
const thread = worker.extend('thread');
const app = thread.extend('app');

app('Doing some stuff'); // => node:worker:thread:app Doing some stuff

Timers

You can use unbug to time things. Every unbug instance has a .time, .timeMark and .timeEnd method:

import unbug from '../index.js';

const time = unbug('time');

time.time('starting loop');
for (let i = 0; i < 1e9; i++) {}
time.markTime('loop one finished')
for (let i = 0; i < 1e9; i++) {}
time.endTime('finished loop');

unbug time

DEBUG variable format

The DEBUG variable is a comma-separated list of scopes.

Each scope can contain a wildcard * to match any number of scope (not greedy). For example, if you have debug:a:worker, debug:b:worker and debug:a:something-else, you can set DEBUG=debug:*:worker to see all worker debugging.

You can also negate scopes by prepending a - to it's name. For example, DEBUG=*,-worker:a will output all debugging except for worker:a.

Formatting

Unbug uses the builtin util.formatWithOptions to format the output. The options sent to util.formatWithOptions can be configured. See Configuration for details.

Events

Every unbug instance has an .events property which is an instance of EventEmitter. It emits the following events:

  • log(scope, text): emitted when a message is logged
  • logskip(scope, text): emitted when unbug is called but the corresponding debugger has been disabled
  • timestart(scope, text, startTime): emitted when a timer starts
  • timestartskip(scope, text, startTime): emitted when a timer starts but the corresponding debugger has been disabled
  • timemark(scope, text, timerCallTime): emitted when a timer marks a time
  • timemarkskip(scope, text, timerCallTime): emitted when a timer marks a time but the corresponding debugger has been disabled
  • timeend(scope, text, endTime): emitted when a timer ends
  • timeendskip(scope, text, endTime): emitted when a timer ends but the corresponding debugger has been disabled

You can use these events to do your own logging

Configuration

Unbug exports a configure function which takes a configuration object. These are the possible configurations:

import {configure} from 'unbug';

configure({
	// The colors to use for scopes. If we run out of colors, we'll reuse them
	colors: [
		'\x1b[38;5;2m',
		'\x1b[38;5;3m',
		'\x1b[38;5;4m',
		'\x1b[38;5;5m',
		'\x1b[38;5;6m',
		'\x1b[38;5;7m',
		'\x1b[38;5;9m',
		'\x1b[38;5;10m',
		'\x1b[38;5;11m',
		'\x1b[38;5;12m',
		'\x1b[38;5;13m',
		'\x1b[38;5;14m',
	],

	// The debug string
	debug: process.env.DEBUG || '',
	// whether to use colors
	useColor: falsyStrings.includes(process.env.DEBUG_COLOR) ? false : true,

	// The options passed to util.formatWithOptions
	// The default options aim to shorten the output as much as possible
	inspectOptions: {
		colors: true,
		maxArrayLength: 5,
		maxStringLength: 20,
		breakLength: process.stdout.columns || 80,
		compact: true,
	}
});

Remember to call configure before using unbug, otherwise some logs may be wrongly configured.