You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
280 lines
9.8 KiB
280 lines
9.8 KiB
# depd |
|
|
|
[![NPM Version][npm-version-image]][npm-url] |
|
[![NPM Downloads][npm-downloads-image]][npm-url] |
|
[![Node.js Version][node-image]][node-url] |
|
[![Linux Build][travis-image]][travis-url] |
|
[![Windows Build][appveyor-image]][appveyor-url] |
|
[![Coverage Status][coveralls-image]][coveralls-url] |
|
|
|
Deprecate all the things |
|
|
|
> With great modules comes great responsibility; mark things deprecated! |
|
|
|
## Install |
|
|
|
This module is installed directly using `npm`: |
|
|
|
```sh |
|
$ npm install depd |
|
``` |
|
|
|
This module can also be bundled with systems like |
|
[Browserify](http://browserify.org/) or [webpack](https://webpack.github.io/), |
|
though by default this module will alter it's API to no longer display or |
|
track deprecations. |
|
|
|
## API |
|
|
|
<!-- eslint-disable no-unused-vars --> |
|
|
|
```js |
|
var deprecate = require('depd')('my-module') |
|
``` |
|
|
|
This library allows you to display deprecation messages to your users. |
|
This library goes above and beyond with deprecation warnings by |
|
introspection of the call stack (but only the bits that it is interested |
|
in). |
|
|
|
Instead of just warning on the first invocation of a deprecated |
|
function and never again, this module will warn on the first invocation |
|
of a deprecated function per unique call site, making it ideal to alert |
|
users of all deprecated uses across the code base, rather than just |
|
whatever happens to execute first. |
|
|
|
The deprecation warnings from this module also include the file and line |
|
information for the call into the module that the deprecated function was |
|
in. |
|
|
|
**NOTE** this library has a similar interface to the `debug` module, and |
|
this module uses the calling file to get the boundary for the call stacks, |
|
so you should always create a new `deprecate` object in each file and not |
|
within some central file. |
|
|
|
### depd(namespace) |
|
|
|
Create a new deprecate function that uses the given namespace name in the |
|
messages and will display the call site prior to the stack entering the |
|
file this function was called from. It is highly suggested you use the |
|
name of your module as the namespace. |
|
|
|
### deprecate(message) |
|
|
|
Call this function from deprecated code to display a deprecation message. |
|
This message will appear once per unique caller site. Caller site is the |
|
first call site in the stack in a different file from the caller of this |
|
function. |
|
|
|
If the message is omitted, a message is generated for you based on the site |
|
of the `deprecate()` call and will display the name of the function called, |
|
similar to the name displayed in a stack trace. |
|
|
|
### deprecate.function(fn, message) |
|
|
|
Call this function to wrap a given function in a deprecation message on any |
|
call to the function. An optional message can be supplied to provide a custom |
|
message. |
|
|
|
### deprecate.property(obj, prop, message) |
|
|
|
Call this function to wrap a given property on object in a deprecation message |
|
on any accessing or setting of the property. An optional message can be supplied |
|
to provide a custom message. |
|
|
|
The method must be called on the object where the property belongs (not |
|
inherited from the prototype). |
|
|
|
If the property is a data descriptor, it will be converted to an accessor |
|
descriptor in order to display the deprecation message. |
|
|
|
### process.on('deprecation', fn) |
|
|
|
This module will allow easy capturing of deprecation errors by emitting the |
|
errors as the type "deprecation" on the global `process`. If there are no |
|
listeners for this type, the errors are written to STDERR as normal, but if |
|
there are any listeners, nothing will be written to STDERR and instead only |
|
emitted. From there, you can write the errors in a different format or to a |
|
logging source. |
|
|
|
The error represents the deprecation and is emitted only once with the same |
|
rules as writing to STDERR. The error has the following properties: |
|
|
|
- `message` - This is the message given by the library |
|
- `name` - This is always `'DeprecationError'` |
|
- `namespace` - This is the namespace the deprecation came from |
|
- `stack` - This is the stack of the call to the deprecated thing |
|
|
|
Example `error.stack` output: |
|
|
|
``` |
|
DeprecationError: my-cool-module deprecated oldfunction |
|
at Object.<anonymous> ([eval]-wrapper:6:22) |
|
at Module._compile (module.js:456:26) |
|
at evalScript (node.js:532:25) |
|
at startup (node.js:80:7) |
|
at node.js:902:3 |
|
``` |
|
|
|
### process.env.NO_DEPRECATION |
|
|
|
As a user of modules that are deprecated, the environment variable `NO_DEPRECATION` |
|
is provided as a quick solution to silencing deprecation warnings from being |
|
output. The format of this is similar to that of `DEBUG`: |
|
|
|
```sh |
|
$ NO_DEPRECATION=my-module,othermod node app.js |
|
``` |
|
|
|
This will suppress deprecations from being output for "my-module" and "othermod". |
|
The value is a list of comma-separated namespaces. To suppress every warning |
|
across all namespaces, use the value `*` for a namespace. |
|
|
|
Providing the argument `--no-deprecation` to the `node` executable will suppress |
|
all deprecations (only available in Node.js 0.8 or higher). |
|
|
|
**NOTE** This will not suppress the deperecations given to any "deprecation" |
|
event listeners, just the output to STDERR. |
|
|
|
### process.env.TRACE_DEPRECATION |
|
|
|
As a user of modules that are deprecated, the environment variable `TRACE_DEPRECATION` |
|
is provided as a solution to getting more detailed location information in deprecation |
|
warnings by including the entire stack trace. The format of this is the same as |
|
`NO_DEPRECATION`: |
|
|
|
```sh |
|
$ TRACE_DEPRECATION=my-module,othermod node app.js |
|
``` |
|
|
|
This will include stack traces for deprecations being output for "my-module" and |
|
"othermod". The value is a list of comma-separated namespaces. To trace every |
|
warning across all namespaces, use the value `*` for a namespace. |
|
|
|
Providing the argument `--trace-deprecation` to the `node` executable will trace |
|
all deprecations (only available in Node.js 0.8 or higher). |
|
|
|
**NOTE** This will not trace the deperecations silenced by `NO_DEPRECATION`. |
|
|
|
## Display |
|
|
|
 |
|
|
|
When a user calls a function in your library that you mark deprecated, they |
|
will see the following written to STDERR (in the given colors, similar colors |
|
and layout to the `debug` module): |
|
|
|
``` |
|
bright cyan bright yellow |
|
| | reset cyan |
|
| | | | |
|
▼ ▼ ▼ ▼ |
|
my-cool-module deprecated oldfunction [eval]-wrapper:6:22 |
|
▲ ▲ ▲ ▲ |
|
| | | | |
|
namespace | | location of mycoolmod.oldfunction() call |
|
| deprecation message |
|
the word "deprecated" |
|
``` |
|
|
|
If the user redirects their STDERR to a file or somewhere that does not support |
|
colors, they see (similar layout to the `debug` module): |
|
|
|
``` |
|
Sun, 15 Jun 2014 05:21:37 GMT my-cool-module deprecated oldfunction at [eval]-wrapper:6:22 |
|
▲ ▲ ▲ ▲ ▲ |
|
| | | | | |
|
timestamp of message namespace | | location of mycoolmod.oldfunction() call |
|
| deprecation message |
|
the word "deprecated" |
|
``` |
|
|
|
## Examples |
|
|
|
### Deprecating all calls to a function |
|
|
|
This will display a deprecated message about "oldfunction" being deprecated |
|
from "my-module" on STDERR. |
|
|
|
```js |
|
var deprecate = require('depd')('my-cool-module') |
|
|
|
// message automatically derived from function name |
|
// Object.oldfunction |
|
exports.oldfunction = deprecate.function(function oldfunction () { |
|
// all calls to function are deprecated |
|
}) |
|
|
|
// specific message |
|
exports.oldfunction = deprecate.function(function () { |
|
// all calls to function are deprecated |
|
}, 'oldfunction') |
|
``` |
|
|
|
### Conditionally deprecating a function call |
|
|
|
This will display a deprecated message about "weirdfunction" being deprecated |
|
from "my-module" on STDERR when called with less than 2 arguments. |
|
|
|
```js |
|
var deprecate = require('depd')('my-cool-module') |
|
|
|
exports.weirdfunction = function () { |
|
if (arguments.length < 2) { |
|
// calls with 0 or 1 args are deprecated |
|
deprecate('weirdfunction args < 2') |
|
} |
|
} |
|
``` |
|
|
|
When calling `deprecate` as a function, the warning is counted per call site |
|
within your own module, so you can display different deprecations depending |
|
on different situations and the users will still get all the warnings: |
|
|
|
```js |
|
var deprecate = require('depd')('my-cool-module') |
|
|
|
exports.weirdfunction = function () { |
|
if (arguments.length < 2) { |
|
// calls with 0 or 1 args are deprecated |
|
deprecate('weirdfunction args < 2') |
|
} else if (typeof arguments[0] !== 'string') { |
|
// calls with non-string first argument are deprecated |
|
deprecate('weirdfunction non-string first arg') |
|
} |
|
} |
|
``` |
|
|
|
### Deprecating property access |
|
|
|
This will display a deprecated message about "oldprop" being deprecated |
|
from "my-module" on STDERR when accessed. A deprecation will be displayed |
|
when setting the value and when getting the value. |
|
|
|
```js |
|
var deprecate = require('depd')('my-cool-module') |
|
|
|
exports.oldprop = 'something' |
|
|
|
// message automatically derives from property name |
|
deprecate.property(exports, 'oldprop') |
|
|
|
// explicit message |
|
deprecate.property(exports, 'oldprop', 'oldprop >= 0.10') |
|
``` |
|
|
|
## License |
|
|
|
[MIT](LICENSE) |
|
|
|
[appveyor-image]: https://badgen.net/appveyor/ci/dougwilson/nodejs-depd/master?label=windows |
|
[appveyor-url]: https://ci.appveyor.com/project/dougwilson/nodejs-depd |
|
[coveralls-image]: https://badgen.net/coveralls/c/github/dougwilson/nodejs-depd/master |
|
[coveralls-url]: https://coveralls.io/r/dougwilson/nodejs-depd?branch=master |
|
[node-image]: https://badgen.net/npm/node/depd |
|
[node-url]: https://nodejs.org/en/download/ |
|
[npm-downloads-image]: https://badgen.net/npm/dm/depd |
|
[npm-url]: https://npmjs.org/package/depd |
|
[npm-version-image]: https://badgen.net/npm/v/depd |
|
[travis-image]: https://badgen.net/travis/dougwilson/nodejs-depd/master?label=linux |
|
[travis-url]: https://travis-ci.org/dougwilson/nodejs-depd
|
|
|