From 36c24c4268685ab9e74fe6096ba14b61c07ab7e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?I=C3=B1aki=20Baz=20Castillo?= Date: Sun, 12 Jan 2020 16:04:58 +0100 Subject: [PATCH] README: document debug instance destroy() method --- README.md | 65 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 52 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 88dae35d..ad516c2f 100644 --- a/README.md +++ b/README.md @@ -7,19 +7,21 @@ A tiny JavaScript debugging utility modelled after Node.js core's debugging technique. Works in Node.js and web browsers. + ## Installation ```bash $ npm install debug ``` + ## Usage `debug` exposes a function; simply pass this function the name of your module, and it will return a decorated version of `console.error` for you to pass debug statements to. This will allow you to toggle the debug output for different parts of your module as well as the module as a whole. Example [_app.js_](./examples/node/app.js): -```js +```javascript var debug = require('debug')('http') , http = require('http') , name = 'My App'; @@ -42,7 +44,7 @@ require('./worker'); Example [_worker.js_](./examples/node/worker.js): -```js +```javascript var a = require('debug')('worker:a') , b = require('debug')('worker:b'); @@ -103,10 +105,11 @@ $env:DEBUG='app';node app.js Then, run the program to be debugged as usual. npm script example: -```js +```javascript "windowsDebug": "@powershell -Command $env:DEBUG='*';node app.js", ``` + ## Namespace Colors Every debug instance has a color generated for it based on its namespace name. @@ -146,6 +149,7 @@ When stdout is not a TTY, `Date#toISOString()` is used, making it more useful fo If you're using this in one or more of your libraries, you _should_ use the name of your library so that developers may toggle debugging as desired without guessing names. If you have more than one debuggers you _should_ prefix them with your library name and use ":" to separate features. For example "bodyParser" from Connect would then be "connect:bodyParser". If you append a "*" to the end of your name, it will always be enabled regardless of the setting of the DEBUG environment variable. You can then use it for normal output as well as debug output. + ## Wildcards The `*` character may be used as a wildcard. Suppose for example your library has @@ -158,6 +162,7 @@ You can also exclude specific debuggers by prefixing them with a "-" character. For example, `DEBUG=*,-connect:*` would include all debuggers except those starting with "connect:". + ## Environment Variables When running through Node.js, you can set a few environment variables that will @@ -178,6 +183,7 @@ See the Node.js documentation for [`util.inspect()`](https://nodejs.org/api/util.html#util_util_inspect_object_options) for the complete list. + ## Formatters Debug uses [printf-style](https://wikipedia.org/wiki/Printf_format_string) formatting. @@ -193,13 +199,13 @@ Below are the officially supported formatters: | `%%` | Single percent sign ('%'). This does not consume an argument. | -### Custom formatters +#### Custom formatters You can add custom formatters by extending the `debug.formatters` object. For example, if you wanted to add support for rendering a Buffer as hex with `%h`, you could do something like: -```js +```javascript const createDebug = require('debug') createDebug.formatters.h = (v) => { return v.toString('hex') @@ -222,13 +228,13 @@ Debug's enable state is currently persisted by `localStorage`. Consider the situation shown below where you have `worker:a` and `worker:b`, and wish to debug both. You can enable this using `localStorage.debug`: -```js +```javascript localStorage.debug = 'worker:*' ``` And then refresh the page. -```js +```javascript a = debug('worker:a'); b = debug('worker:b'); @@ -248,7 +254,7 @@ setInterval(function(){ Example [_stdout.js_](./examples/node/stdout.js): -```js +```javascript var debug = require('debug'); var error = debug('app:error'); @@ -268,9 +274,12 @@ error('now goes to stdout via console.info'); log('still goes to stdout, but via console.info now'); ``` + ## Extend -You can simply extend debugger -```js + +You can simply extend debugger: + +```javascript const log = require('debug')('auth'); //creates new debug instance with extended namespace @@ -284,9 +293,9 @@ logLogin('hello'); //auth:login hello ## Set dynamically -You can also enable debug dynamically by calling the `enable()` method : +You can also enable debug dynamically by calling the `enable()` method: -```js +```javascript let debug = require('debug'); console.log(1, debug.enabled('test')); @@ -325,7 +334,7 @@ temporarily without knowing what was enabled to begin with. For example: -```js +```javascript let debug = require('debug'); debug.enable('foo:*,-foo:bar'); let namespaces = debug.disable(); @@ -335,6 +344,7 @@ debug.enable(namespaces); Note: There is no guarantee that the string will be identical to the initial enable string, but semantically they will be identical. + ## Checking whether a debug target is enabled After you've created a debug instance, you can determine whether or not it is @@ -352,12 +362,40 @@ You can also manually toggle this property to force the debug instance to be enabled or disabled. +## Destroying a debug instance + +If debug instances are created dynamically (rather than a static debug instance per file as usual), the application must call `destroy()` on the dynamically created debug instance. Otherwise it would leak memory. + +For example: + +```javascript +const debug = require('debug'); + +class Foo { + constructor(id) { + // Per Foo instance debug instance. + this.debug = debug(`foo:${id}`); + } + + close() { + // Must call destroy() on the debug instance, otherwise it would leak. + this.debug.destroy(); + } +} + +const foo = new Foo(1234);} +``` + +Here the application may create many instances of the `Foo` class. The application should ensure that, when those `Foo` instances are no longer needed, it calls a method on them (i.e. `foo.close()`) that destroys the debug instance. + + ## Authors - TJ Holowaychuk - Nathan Rajlich - Andrew Rhyne + ## Backers Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/debug#backer)] @@ -429,6 +467,7 @@ Become a sponsor and get your logo on our README on Github with a link to your s + ## License (The MIT License)