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 |
|
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 | ![message](files/message.png)
|
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
|