diff options
author | Minteck <contact@minteck.org> | 2023-01-10 14:54:04 +0100 |
---|---|---|
committer | Minteck <contact@minteck.org> | 2023-01-10 14:54:04 +0100 |
commit | 99c1d9af689e5325f3cf535c4007b3aeb8325229 (patch) | |
tree | e663b3c2ebdbd67c818ac0c5147f0ce1d2463cda /alarm/node_modules/depd/Readme.md | |
parent | 9871b03912fc28ad38b4037ebf26a78aa937baba (diff) | |
download | pluralconnect-99c1d9af689e5325f3cf535c4007b3aeb8325229.tar.gz pluralconnect-99c1d9af689e5325f3cf535c4007b3aeb8325229.tar.bz2 pluralconnect-99c1d9af689e5325f3cf535c4007b3aeb8325229.zip |
Update - This is an automated commit
Diffstat (limited to 'alarm/node_modules/depd/Readme.md')
-rw-r--r-- | alarm/node_modules/depd/Readme.md | 280 |
1 files changed, 0 insertions, 280 deletions
diff --git a/alarm/node_modules/depd/Readme.md b/alarm/node_modules/depd/Readme.md deleted file mode 100644 index 043d1ca..0000000 --- a/alarm/node_modules/depd/Readme.md +++ /dev/null @@ -1,280 +0,0 @@ -# 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 - -![message](files/message.png) - -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 |