opusdev/vector-similarity-api

1# depd2 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 10Deprecate all the things11 12> With great modules comes great responsibility; mark things deprecated!13 14## Install15 16This module is installed directly using `npm`:17 18```sh19$ npm install depd20```21 22This module can also be bundled with systems like23[Browserify](http://browserify.org/) or [webpack](https://webpack.github.io/),24though by default this module will alter it's API to no longer display or25track deprecations.26 27## API28 29<!-- eslint-disable no-unused-vars -->30 31```js32var deprecate = require('depd')('my-module')33```34 35This library allows you to display deprecation messages to your users.36This library goes above and beyond with deprecation warnings by37introspection of the call stack (but only the bits that it is interested38in).39 40Instead of just warning on the first invocation of a deprecated41function and never again, this module will warn on the first invocation42of a deprecated function per unique call site, making it ideal to alert43users of all deprecated uses across the code base, rather than just44whatever happens to execute first.45 46The deprecation warnings from this module also include the file and line47information for the call into the module that the deprecated function was48in.49 50**NOTE** this library has a similar interface to the `debug` module, and51this module uses the calling file to get the boundary for the call stacks,52so you should always create a new `deprecate` object in each file and not53within some central file.54 55### depd(namespace)56 57Create a new deprecate function that uses the given namespace name in the58messages and will display the call site prior to the stack entering the59file this function was called from. It is highly suggested you use the60name of your module as the namespace.61 62### deprecate(message)63 64Call this function from deprecated code to display a deprecation message.65This message will appear once per unique caller site. Caller site is the66first call site in the stack in a different file from the caller of this67function.68 69If the message is omitted, a message is generated for you based on the site70of the `deprecate()` call and will display the name of the function called,71similar to the name displayed in a stack trace.72 73### deprecate.function(fn, message)74 75Call this function to wrap a given function in a deprecation message on any76call to the function. An optional message can be supplied to provide a custom77message.78 79### deprecate.property(obj, prop, message)80 81Call this function to wrap a given property on object in a deprecation message82on any accessing or setting of the property. An optional message can be supplied83to provide a custom message.84 85The method must be called on the object where the property belongs (not86inherited from the prototype).87 88If the property is a data descriptor, it will be converted to an accessor89descriptor in order to display the deprecation message.90 91### process.on('deprecation', fn)92 93This module will allow easy capturing of deprecation errors by emitting the94errors as the type "deprecation" on the global `process`. If there are no95listeners for this type, the errors are written to STDERR as normal, but if96there are any listeners, nothing will be written to STDERR and instead only97emitted. From there, you can write the errors in a different format or to a98logging source.99 100The error represents the deprecation and is emitted only once with the same101rules as writing to STDERR. The error has the following properties:102 103  - `message` - This is the message given by the library104  - `name` - This is always `'DeprecationError'`105  - `namespace` - This is the namespace the deprecation came from106  - `stack` - This is the stack of the call to the deprecated thing107 108Example `error.stack` output:109 110```111DeprecationError: my-cool-module deprecated oldfunction112    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:3117```118 119### process.env.NO_DEPRECATION120 121As a user of modules that are deprecated, the environment variable `NO_DEPRECATION`122is provided as a quick solution to silencing deprecation warnings from being123output. The format of this is similar to that of `DEBUG`:124 125```sh126$ NO_DEPRECATION=my-module,othermod node app.js127```128 129This will suppress deprecations from being output for "my-module" and "othermod".130The value is a list of comma-separated namespaces. To suppress every warning131across all namespaces, use the value `*` for a namespace.132 133Providing the argument `--no-deprecation` to the `node` executable will suppress134all deprecations (only available in Node.js 0.8 or higher).135 136**NOTE** This will not suppress the deperecations given to any "deprecation"137event listeners, just the output to STDERR.138 139### process.env.TRACE_DEPRECATION140 141As a user of modules that are deprecated, the environment variable `TRACE_DEPRECATION`142is provided as a solution to getting more detailed location information in deprecation143warnings by including the entire stack trace. The format of this is the same as144`NO_DEPRECATION`:145 146```sh147$ TRACE_DEPRECATION=my-module,othermod node app.js148```149 150This will include stack traces for deprecations being output for "my-module" and151"othermod". The value is a list of comma-separated namespaces. To trace every152warning across all namespaces, use the value `*` for a namespace.153 154Providing the argument `--trace-deprecation` to the `node` executable will trace155all 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## Display160 161![message](files/message.png)162 163When a user calls a function in your library that you mark deprecated, they164will see the following written to STDERR (in the given colors, similar colors165and layout to the `debug` module):166 167```168bright cyan    bright yellow169|              |          reset       cyan170|              |          |           |171▼              ▼          ▼           ▼172my-cool-module deprecated oldfunction [eval]-wrapper:6:22173▲              ▲          ▲           ▲174|              |          |           |175namespace      |          |           location of mycoolmod.oldfunction() call176               |          deprecation message177               the word "deprecated"178```179 180If the user redirects their STDERR to a file or somewhere that does not support181colors, they see (similar layout to the `debug` module):182 183```184Sun, 15 Jun 2014 05:21:37 GMT my-cool-module deprecated oldfunction at [eval]-wrapper:6:22185▲                             ▲              ▲          ▲              ▲186|                             |              |          |              |187timestamp of message          namespace      |          |             location of mycoolmod.oldfunction() call188                                             |          deprecation message189                                             the word "deprecated"190```191 192## Examples193 194### Deprecating all calls to a function195 196This will display a deprecated message about "oldfunction" being deprecated197from "my-module" on STDERR.198 199```js200var deprecate = require('depd')('my-cool-module')201 202// message automatically derived from function name203// Object.oldfunction204exports.oldfunction = deprecate.function(function oldfunction () {205  // all calls to function are deprecated206})207 208// specific message209exports.oldfunction = deprecate.function(function () {210  // all calls to function are deprecated211}, 'oldfunction')212```213 214### Conditionally deprecating a function call215 216This will display a deprecated message about "weirdfunction" being deprecated217from "my-module" on STDERR when called with less than 2 arguments.218 219```js220var deprecate = require('depd')('my-cool-module')221 222exports.weirdfunction = function () {223  if (arguments.length < 2) {224    // calls with 0 or 1 args are deprecated225    deprecate('weirdfunction args < 2')226  }227}228```229 230When calling `deprecate` as a function, the warning is counted per call site231within your own module, so you can display different deprecations depending232on different situations and the users will still get all the warnings:233 234```js235var deprecate = require('depd')('my-cool-module')236 237exports.weirdfunction = function () {238  if (arguments.length < 2) {239    // calls with 0 or 1 args are deprecated240    deprecate('weirdfunction args < 2')241  } else if (typeof arguments[0] !== 'string') {242    // calls with non-string first argument are deprecated243    deprecate('weirdfunction non-string first arg')244  }245}246```247 248### Deprecating property access249 250This will display a deprecated message about "oldprop" being deprecated251from "my-module" on STDERR when accessed. A deprecation will be displayed252when setting the value and when getting the value.253 254```js255var deprecate = require('depd')('my-cool-module')256 257exports.oldprop = 'something'258 259// message automatically derives from property name260deprecate.property(exports, 'oldprop')261 262// explicit message263deprecate.property(exports, 'oldprop', 'oldprop >= 0.10')264```265 266## License267 268[MIT](LICENSE)269 270[appveyor-image]: https://badgen.net/appveyor/ci/dougwilson/nodejs-depd/master?label=windows271[appveyor-url]: https://ci.appveyor.com/project/dougwilson/nodejs-depd272[coveralls-image]: https://badgen.net/coveralls/c/github/dougwilson/nodejs-depd/master273[coveralls-url]: https://coveralls.io/r/dougwilson/nodejs-depd?branch=master274[node-image]: https://badgen.net/npm/node/depd275[node-url]: https://nodejs.org/en/download/276[npm-downloads-image]: https://badgen.net/npm/dm/depd277[npm-url]: https://npmjs.org/package/depd278[npm-version-image]: https://badgen.net/npm/v/depd279[travis-image]: https://badgen.net/travis/dougwilson/nodejs-depd/master?label=linux280[travis-url]: https://travis-ci.org/dougwilson/nodejs-depd281