node_modules/depd/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 ![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 [npm-version-image]: https://img.shields.io/npm/v/depd.svg
 271 [npm-downloads-image]: https://img.shields.io/npm/dm/depd.svg
 272 [npm-url]: https://npmjs.org/package/depd
 273 [travis-image]: https://img.shields.io/travis/dougwilson/nodejs-depd/master.svg?label=linux
 274 [travis-url]: https://travis-ci.org/dougwilson/nodejs-depd
 275 [appveyor-image]: https://img.shields.io/appveyor/ci/dougwilson/nodejs-depd/master.svg?label=windows
 276 [appveyor-url]: https://ci.appveyor.com/project/dougwilson/nodejs-depd
 277 [coveralls-image]: https://img.shields.io/coveralls/dougwilson/nodejs-depd/master.svg
 278 [coveralls-url]: https://coveralls.io/r/dougwilson/nodejs-depd?branch=master
 279 [node-image]: https://img.shields.io/node/v/depd.svg
 280 [node-url]: https://nodejs.org/en/download/