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