Readme.md
1 # depd 2 3 [![NPM Version][npm-version-image]][npm-url] 4 [![NPM Downloads][npm-downloads-image]][npm-url] 5 [![Node.js Version][node-image]][node-url] 6 [![Linux Build][travis-image]][travis-url] 7 [![Windows Build][appveyor-image]][appveyor-url] 8 [![Coverage Status][coveralls-image]][coveralls-url] 9 10 Deprecate all the things 11 12 > With great modules comes great responsibility; mark things deprecated! 13 14 ## Install 15 16 This module is installed directly using `npm`: 17 18 ```sh 19 $ npm install depd 20 ``` 21 22 This module can also be bundled with systems like 23 [Browserify](http://browserify.org/) or [webpack](https://webpack.github.io/), 24 though by default this module will alter it's API to no longer display or 25 track deprecations. 26 27 ## API 28 29 <!-- eslint-disable no-unused-vars --> 30 31 ```js 32 var deprecate = require('depd')('my-module') 33 ``` 34 35 This library allows you to display deprecation messages to your users. 36 This library goes above and beyond with deprecation warnings by 37 introspection of the call stack (but only the bits that it is interested 38 in). 39 40 Instead of just warning on the first invocation of a deprecated 41 function and never again, this module will warn on the first invocation 42 of a deprecated function per unique call site, making it ideal to alert 43 users of all deprecated uses across the code base, rather than just 44 whatever happens to execute first. 45 46 The deprecation warnings from this module also include the file and line 47 information for the call into the module that the deprecated function was 48 in. 49 50 **NOTE** this library has a similar interface to the `debug` module, and 51 this module uses the calling file to get the boundary for the call stacks, 52 so you should always create a new `deprecate` object in each file and not 53 within some central file. 54 55 ### depd(namespace) 56 57 Create a new deprecate function that uses the given namespace name in the 58 messages and will display the call site prior to the stack entering the 59 file this function was called from. It is highly suggested you use the 60 name of your module as the namespace. 61 62 ### deprecate(message) 63 64 Call this function from deprecated code to display a deprecation message. 65 This message will appear once per unique caller site. Caller site is the 66 first call site in the stack in a different file from the caller of this 67 function. 68 69 If the message is omitted, a message is generated for you based on the site 70 of the `deprecate()` call and will display the name of the function called, 71 similar to the name displayed in a stack trace. 72 73 ### deprecate.function(fn, message) 74 75 Call this function to wrap a given function in a deprecation message on any 76 call to the function. An optional message can be supplied to provide a custom 77 message. 78 79 ### deprecate.property(obj, prop, message) 80 81 Call this function to wrap a given property on object in a deprecation message 82 on any accessing or setting of the property. An optional message can be supplied 83 to provide a custom message. 84 85 The method must be called on the object where the property belongs (not 86 inherited from the prototype). 87 88 If the property is a data descriptor, it will be converted to an accessor 89 descriptor in order to display the deprecation message. 90 91 ### process.on('deprecation', fn) 92 93 This module will allow easy capturing of deprecation errors by emitting the 94 errors as the type "deprecation" on the global `process`. If there are no 95 listeners for this type, the errors are written to STDERR as normal, but if 96 there are any listeners, nothing will be written to STDERR and instead only 97 emitted. From there, you can write the errors in a different format or to a 98 logging source. 99 100 The error represents the deprecation and is emitted only once with the same 101 rules as writing to STDERR. The error has the following properties: 102 103 - `message` - This is the message given by the library 104 - `name` - This is always `'DeprecationError'` 105 - `namespace` - This is the namespace the deprecation came from 106 - `stack` - This is the stack of the call to the deprecated thing 107 108 Example `error.stack` output: 109 110 ``` 111 DeprecationError: my-cool-module deprecated oldfunction 112 at Object.<anonymous> ([eval]-wrapper:6:22) 113 at Module._compile (module.js:456:26) 114 at evalScript (node.js:532:25) 115 at startup (node.js:80:7) 116 at node.js:902:3 117 ``` 118 119 ### process.env.NO_DEPRECATION 120 121 As a user of modules that are deprecated, the environment variable `NO_DEPRECATION` 122 is provided as a quick solution to silencing deprecation warnings from being 123 output. The format of this is similar to that of `DEBUG`: 124 125 ```sh 126 $ NO_DEPRECATION=my-module,othermod node app.js 127 ``` 128 129 This will suppress deprecations from being output for "my-module" and "othermod". 130 The value is a list of comma-separated namespaces. To suppress every warning 131 across all namespaces, use the value `*` for a namespace. 132 133 Providing the argument `--no-deprecation` to the `node` executable will suppress 134 all deprecations (only available in Node.js 0.8 or higher). 135 136 **NOTE** This will not suppress the deperecations given to any "deprecation" 137 event listeners, just the output to STDERR. 138 139 ### process.env.TRACE_DEPRECATION 140 141 As a user of modules that are deprecated, the environment variable `TRACE_DEPRECATION` 142 is provided as a solution to getting more detailed location information in deprecation 143 warnings by including the entire stack trace. The format of this is the same as 144 `NO_DEPRECATION`: 145 146 ```sh 147 $ TRACE_DEPRECATION=my-module,othermod node app.js 148 ``` 149 150 This will include stack traces for deprecations being output for "my-module" and 151 "othermod". The value is a list of comma-separated namespaces. To trace every 152 warning across all namespaces, use the value `*` for a namespace. 153 154 Providing the argument `--trace-deprecation` to the `node` executable will trace 155 all deprecations (only available in Node.js 0.8 or higher). 156 157 **NOTE** This will not trace the deperecations silenced by `NO_DEPRECATION`. 158 159 ## Display 160 161  162 163 When a user calls a function in your library that you mark deprecated, they 164 will see the following written to STDERR (in the given colors, similar colors 165 and layout to the `debug` module): 166 167 ``` 168 bright cyan bright yellow 169 | | reset cyan 170 | | | | 171 ▼ ▼ ▼ ▼ 172 my-cool-module deprecated oldfunction [eval]-wrapper:6:22 173 ▲ ▲ ▲ ▲ 174 | | | | 175 namespace | | location of mycoolmod.oldfunction() call 176 | deprecation message 177 the word "deprecated" 178 ``` 179 180 If the user redirects their STDERR to a file or somewhere that does not support 181 colors, they see (similar layout to the `debug` module): 182 183 ``` 184 Sun, 15 Jun 2014 05:21:37 GMT my-cool-module deprecated oldfunction at [eval]-wrapper:6:22 185 ▲ ▲ ▲ ▲ ▲ 186 | | | | | 187 timestamp of message namespace | | location of mycoolmod.oldfunction() call 188 | deprecation message 189 the word "deprecated" 190 ``` 191 192 ## Examples 193 194 ### Deprecating all calls to a function 195 196 This will display a deprecated message about "oldfunction" being deprecated 197 from "my-module" on STDERR. 198 199 ```js 200 var deprecate = require('depd')('my-cool-module') 201 202 // message automatically derived from function name 203 // Object.oldfunction 204 exports.oldfunction = deprecate.function(function oldfunction () { 205 // all calls to function are deprecated 206 }) 207 208 // specific message 209 exports.oldfunction = deprecate.function(function () { 210 // all calls to function are deprecated 211 }, 'oldfunction') 212 ``` 213 214 ### Conditionally deprecating a function call 215 216 This will display a deprecated message about "weirdfunction" being deprecated 217 from "my-module" on STDERR when called with less than 2 arguments. 218 219 ```js 220 var deprecate = require('depd')('my-cool-module') 221 222 exports.weirdfunction = function () { 223 if (arguments.length < 2) { 224 // calls with 0 or 1 args are deprecated 225 deprecate('weirdfunction args < 2') 226 } 227 } 228 ``` 229 230 When calling `deprecate` as a function, the warning is counted per call site 231 within your own module, so you can display different deprecations depending 232 on different situations and the users will still get all the warnings: 233 234 ```js 235 var deprecate = require('depd')('my-cool-module') 236 237 exports.weirdfunction = function () { 238 if (arguments.length < 2) { 239 // calls with 0 or 1 args are deprecated 240 deprecate('weirdfunction args < 2') 241 } else if (typeof arguments[0] !== 'string') { 242 // calls with non-string first argument are deprecated 243 deprecate('weirdfunction non-string first arg') 244 } 245 } 246 ``` 247 248 ### Deprecating property access 249 250 This will display a deprecated message about "oldprop" being deprecated 251 from "my-module" on STDERR when accessed. A deprecation will be displayed 252 when setting the value and when getting the value. 253 254 ```js 255 var deprecate = require('depd')('my-cool-module') 256 257 exports.oldprop = 'something' 258 259 // message automatically derives from property name 260 deprecate.property(exports, 'oldprop') 261 262 // explicit message 263 deprecate.property(exports, 'oldprop', 'oldprop >= 0.10') 264 ``` 265 266 ## License 267 268 [MIT](LICENSE) 269 270 [appveyor-image]: https://badgen.net/appveyor/ci/dougwilson/nodejs-depd/master?label=windows 271 [appveyor-url]: https://ci.appveyor.com/project/dougwilson/nodejs-depd 272 [coveralls-image]: https://badgen.net/coveralls/c/github/dougwilson/nodejs-depd/master 273 [coveralls-url]: https://coveralls.io/r/dougwilson/nodejs-depd?branch=master 274 [node-image]: https://badgen.net/npm/node/depd 275 [node-url]: https://nodejs.org/en/download/ 276 [npm-downloads-image]: https://badgen.net/npm/dm/depd 277 [npm-url]: https://npmjs.org/package/depd 278 [npm-version-image]: https://badgen.net/npm/v/depd 279 [travis-image]: https://badgen.net/travis/dougwilson/nodejs-depd/master?label=linux 280 [travis-url]: https://travis-ci.org/dougwilson/nodejs-depd