www.aleph1.co.uk Git - yaffs-website/blob - 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 [![Gratipay][gratipay-image]][gratipay-url]
  10
  11 Deprecate all the things
  12
  13 > With great modules comes great responsibility; mark things deprecated!
  14
  15 ## Install
  16
  17 This module is installed directly using `npm`:
  18
  19 ```sh
  20 $ npm install depd
  21 ```
  22
  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
  26 track deprecations.
  27
  28 ## API
  29
  30 ```js
  31 var deprecate = require('depd')('my-module')
  32 ```
  33
  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
  37 in).
  38
  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.
  44
  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
  47 in.
  48
  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.
  53
  54 ### depd(namespace)
  55
  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.
  60
  61 ### deprecate(message)
  62
  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
  66 function.
  67
  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.
  71
  72 ### deprecate.function(fn, message)
  73
  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
  76 message.
  77
  78 ### deprecate.property(obj, prop, message)
  79
  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.
  83
  84 The method must be called on the object where the property belongs (not
  85 inherited from the prototype).
  86
  87 If the property is a data descriptor, it will be converted to an accessor
  88 descriptor in order to display the deprecation message.
  89
  90 ### process.on('deprecation', fn)
  91
  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
  97 logging source.
  98
  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:
 101
 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
 106
 107 Example `error.stack` output:
 108
 109 ```
 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)
 115     at node.js:902:3
 116 ```
 117
 118 ### process.env.NO_DEPRECATION
 119
 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`:
 123
 124 ```sh
 125 $ NO_DEPRECATION=my-module,othermod node app.js
 126 ```
 127
 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.
 131
 132 Providing the argument `--no-deprecation` to the `node` executable will suppress
 133 all deprecations (only available in Node.js 0.8 or higher).
 134
 135 **NOTE** This will not suppress the deperecations given to any "deprecation"
 136 event listeners, just the output to STDERR.
 137
 138 ### process.env.TRACE_DEPRECATION
 139
 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
 143 `NO_DEPRECATION`:
 144
 145 ```sh
 146 $ TRACE_DEPRECATION=my-module,othermod node app.js
 147 ```
 148
 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.
 152
 153 Providing the argument `--trace-deprecation` to the `node` executable will trace
 154 all deprecations (only available in Node.js 0.8 or higher).
 155
 156 **NOTE** This will not trace the deperecations silenced by `NO_DEPRECATION`.
 157
 158 ## Display
 159
 160 ![message](files/message.png)
 161
 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):
 165
 166 ```
 167 bright cyan    bright yellow
 168 |              |          reset       cyan
 169 |              |          |           |
 170 ▼              ▼          ▼           ▼
 171 my-cool-module deprecated oldfunction [eval]-wrapper:6:22
 172 ▲              ▲          ▲           ▲
 173 |              |          |           |
 174 namespace      |          |           location of mycoolmod.oldfunction() call
 175                |          deprecation message
 176                the word "deprecated"
 177 ```
 178
 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):
 181
 182 ```
 183 Sun, 15 Jun 2014 05:21:37 GMT my-cool-module deprecated oldfunction at [eval]-wrapper:6:22
 184 ▲                             ▲              ▲          ▲              ▲
 185 |                             |              |          |              |
 186 timestamp of message          namespace      |          |             location of mycoolmod.oldfunction() call
 187                                              |          deprecation message
 188                                              the word "deprecated"
 189 ```
 190
 191 ## Examples
 192
 193 ### Deprecating all calls to a function
 194
 195 This will display a deprecated message about "oldfunction" being deprecated
 196 from "my-module" on STDERR.
 197
 198 ```js
 199 var deprecate = require('depd')('my-cool-module')
 200
 201 // message automatically derived from function name
 202 // Object.oldfunction
 203 exports.oldfunction = deprecate.function(function oldfunction() {
 204   // all calls to function are deprecated
 205 })
 206
 207 // specific message
 208 exports.oldfunction = deprecate.function(function () {
 209   // all calls to function are deprecated
 210 }, 'oldfunction')
 211 ```
 212
 213 ### Conditionally deprecating a function call
 214
 215 This will display a deprecated message about "weirdfunction" being deprecated
 216 from "my-module" on STDERR when called with less than 2 arguments.
 217
 218 ```js
 219 var deprecate = require('depd')('my-cool-module')
 220
 221 exports.weirdfunction = function () {
 222   if (arguments.length < 2) {
 223     // calls with 0 or 1 args are deprecated
 224     deprecate('weirdfunction args < 2')
 225   }
 226 }
 227 ```
 228
 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:
 232
 233 ```js
 234 var deprecate = require('depd')('my-cool-module')
 235
 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')
 243   }
 244 }
 245 ```
 246
 247 ### Deprecating property access
 248
 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.
 252
 253 ```js
 254 var deprecate = require('depd')('my-cool-module')
 255
 256 exports.oldprop = 'something'
 257
 258 // message automatically derives from property name
 259 deprecate.property(exports, 'oldprop')
 260
 261 // explicit message
 262 deprecate.property(exports, 'oldprop', 'oldprop >= 0.10')
 263 ```
 264
 265 ## License
 266
 267 [MIT](LICENSE)
 268
 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/