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