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 [![Gratipay][gratipay-image]][gratipay-url]
11 Deprecate all the things
13 > With great modules comes great responsibility; mark things deprecated!
17 This module is installed directly using `npm`:
23 This module can also be bundled with systems like
24 [Browserify](http://browserify.org/) or [webpack](https://webpack.github.io/),
25 though by default this module will alter it's API to no longer display or
31 var deprecate = require('depd')('my-module')
34 This library allows you to display deprecation messages to your users.
35 This library goes above and beyond with deprecation warnings by
36 introspection of the call stack (but only the bits that it is interested
39 Instead of just warning on the first invocation of a deprecated
40 function and never again, this module will warn on the first invocation
41 of a deprecated function per unique call site, making it ideal to alert
42 users of all deprecated uses across the code base, rather than just
43 whatever happens to execute first.
45 The deprecation warnings from this module also include the file and line
46 information for the call into the module that the deprecated function was
49 **NOTE** this library has a similar interface to the `debug` module, and
50 this module uses the calling file to get the boundary for the call stacks,
51 so you should always create a new `deprecate` object in each file and not
52 within some central file.
56 Create a new deprecate function that uses the given namespace name in the
57 messages and will display the call site prior to the stack entering the
58 file this function was called from. It is highly suggested you use the
59 name of your module as the namespace.
61 ### deprecate(message)
63 Call this function from deprecated code to display a deprecation message.
64 This message will appear once per unique caller site. Caller site is the
65 first call site in the stack in a different file from the caller of this
68 If the message is omitted, a message is generated for you based on the site
69 of the `deprecate()` call and will display the name of the function called,
70 similar to the name displayed in a stack trace.
72 ### deprecate.function(fn, message)
74 Call this function to wrap a given function in a deprecation message on any
75 call to the function. An optional message can be supplied to provide a custom
78 ### deprecate.property(obj, prop, message)
80 Call this function to wrap a given property on object in a deprecation message
81 on any accessing or setting of the property. An optional message can be supplied
82 to provide a custom message.
84 The method must be called on the object where the property belongs (not
85 inherited from the prototype).
87 If the property is a data descriptor, it will be converted to an accessor
88 descriptor in order to display the deprecation message.
90 ### process.on('deprecation', fn)
92 This module will allow easy capturing of deprecation errors by emitting the
93 errors as the type "deprecation" on the global `process`. If there are no
94 listeners for this type, the errors are written to STDERR as normal, but if
95 there are any listeners, nothing will be written to STDERR and instead only
96 emitted. From there, you can write the errors in a different format or to a
99 The error represents the deprecation and is emitted only once with the same
100 rules as writing to STDERR. The error has the following properties:
102 - `message` - This is the message given by the library
103 - `name` - This is always `'DeprecationError'`
104 - `namespace` - This is the namespace the deprecation came from
105 - `stack` - This is the stack of the call to the deprecated thing
107 Example `error.stack` output:
110 DeprecationError: my-cool-module deprecated oldfunction
111 at Object.<anonymous> ([eval]-wrapper:6:22)
112 at Module._compile (module.js:456:26)
113 at evalScript (node.js:532:25)
114 at startup (node.js:80:7)
118 ### process.env.NO_DEPRECATION
120 As a user of modules that are deprecated, the environment variable `NO_DEPRECATION`
121 is provided as a quick solution to silencing deprecation warnings from being
122 output. The format of this is similar to that of `DEBUG`:
125 $ NO_DEPRECATION=my-module,othermod node app.js
128 This will suppress deprecations from being output for "my-module" and "othermod".
129 The value is a list of comma-separated namespaces. To suppress every warning
130 across all namespaces, use the value `*` for a namespace.
132 Providing the argument `--no-deprecation` to the `node` executable will suppress
133 all deprecations (only available in Node.js 0.8 or higher).
135 **NOTE** This will not suppress the deperecations given to any "deprecation"
136 event listeners, just the output to STDERR.
138 ### process.env.TRACE_DEPRECATION
140 As a user of modules that are deprecated, the environment variable `TRACE_DEPRECATION`
141 is provided as a solution to getting more detailed location information in deprecation
142 warnings by including the entire stack trace. The format of this is the same as
146 $ TRACE_DEPRECATION=my-module,othermod node app.js
149 This will include stack traces for deprecations being output for "my-module" and
150 "othermod". The value is a list of comma-separated namespaces. To trace every
151 warning across all namespaces, use the value `*` for a namespace.
153 Providing the argument `--trace-deprecation` to the `node` executable will trace
154 all deprecations (only available in Node.js 0.8 or higher).
156 **NOTE** This will not trace the deperecations silenced by `NO_DEPRECATION`.
160 ![message](files/message.png)
162 When a user calls a function in your library that you mark deprecated, they
163 will see the following written to STDERR (in the given colors, similar colors
164 and layout to the `debug` module):
167 bright cyan bright yellow
171 my-cool-module deprecated oldfunction [eval]-wrapper:6:22
174 namespace | | location of mycoolmod.oldfunction() call
175 | deprecation message
176 the word "deprecated"
179 If the user redirects their STDERR to a file or somewhere that does not support
180 colors, they see (similar layout to the `debug` module):
183 Sun, 15 Jun 2014 05:21:37 GMT my-cool-module deprecated oldfunction at [eval]-wrapper:6:22
186 timestamp of message namespace | | location of mycoolmod.oldfunction() call
187 | deprecation message
188 the word "deprecated"
193 ### Deprecating all calls to a function
195 This will display a deprecated message about "oldfunction" being deprecated
196 from "my-module" on STDERR.
199 var deprecate = require('depd')('my-cool-module')
201 // message automatically derived from function name
202 // Object.oldfunction
203 exports.oldfunction = deprecate.function(function oldfunction() {
204 // all calls to function are deprecated
208 exports.oldfunction = deprecate.function(function () {
209 // all calls to function are deprecated
213 ### Conditionally deprecating a function call
215 This will display a deprecated message about "weirdfunction" being deprecated
216 from "my-module" on STDERR when called with less than 2 arguments.
219 var deprecate = require('depd')('my-cool-module')
221 exports.weirdfunction = function () {
222 if (arguments.length < 2) {
223 // calls with 0 or 1 args are deprecated
224 deprecate('weirdfunction args < 2')
229 When calling `deprecate` as a function, the warning is counted per call site
230 within your own module, so you can display different deprecations depending
231 on different situations and the users will still get all the warnings:
234 var deprecate = require('depd')('my-cool-module')
236 exports.weirdfunction = function () {
237 if (arguments.length < 2) {
238 // calls with 0 or 1 args are deprecated
239 deprecate('weirdfunction args < 2')
240 } else if (typeof arguments[0] !== 'string') {
241 // calls with non-string first argument are deprecated
242 deprecate('weirdfunction non-string first arg')
247 ### Deprecating property access
249 This will display a deprecated message about "oldprop" being deprecated
250 from "my-module" on STDERR when accessed. A deprecation will be displayed
251 when setting the value and when getting the value.
254 var deprecate = require('depd')('my-cool-module')
256 exports.oldprop = 'something'
258 // message automatically derives from property name
259 deprecate.property(exports, 'oldprop')
262 deprecate.property(exports, 'oldprop', 'oldprop >= 0.10')
269 [npm-version-image]: https://img.shields.io/npm/v/depd.svg
270 [npm-downloads-image]: https://img.shields.io/npm/dm/depd.svg
271 [npm-url]: https://npmjs.org/package/depd
272 [travis-image]: https://img.shields.io/travis/dougwilson/nodejs-depd/master.svg?label=linux
273 [travis-url]: https://travis-ci.org/dougwilson/nodejs-depd
274 [appveyor-image]: https://img.shields.io/appveyor/ci/dougwilson/nodejs-depd/master.svg?label=windows
275 [appveyor-url]: https://ci.appveyor.com/project/dougwilson/nodejs-depd
276 [coveralls-image]: https://img.shields.io/coveralls/dougwilson/nodejs-depd/master.svg
277 [coveralls-url]: https://coveralls.io/r/dougwilson/nodejs-depd?branch=master
278 [node-image]: https://img.shields.io/node/v/depd.svg
279 [node-url]: http://nodejs.org/download/
280 [gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg
281 [gratipay-url]: https://www.gratipay.com/dougwilson/