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