\href{https://npmjs.org/package/depd}{\texttt{ }} \href{https://npmjs.org/package/depd}{\texttt{ }} \href{https://nodejs.org/en/download/}{\texttt{ }} \href{https://travis-ci.org/dougwilson/nodejs-depd}{\texttt{ }} \href{https://ci.appveyor.com/project/dougwilson/nodejs-depd}{\texttt{ }} \href{https://coveralls.io/r/dougwilson/nodejs-depd?branch=master}{\texttt{ }}

Deprecate all the things

\begin{quote}
With great modules comes great responsibility; mark things deprecated! \end{quote}
\hypertarget{md_sfcode_node_modules_depd_Readme_autotoc_md8097}{}\doxysection{Install}\label{md_sfcode_node_modules_depd_Readme_autotoc_md8097}
This module is installed directly using {\ttfamily npm}\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\$ npm install depd }

\end{DoxyCode}


This module can also be bundled with systems like \href{http://browserify.org/}{\texttt{ Browserify}} or \href{https://webpack.github.io/}{\texttt{ webpack}}, though by default this module will alter it\textquotesingle{}s API to no longer display or track deprecations.\hypertarget{md_sfcode_node_modules_depd_Readme_autotoc_md8098}{}\doxysection{API}\label{md_sfcode_node_modules_depd_Readme_autotoc_md8098}

\begin{DoxyCode}{0}
\DoxyCodeLine{var deprecate = require('depd')('my-\/module') }

\end{DoxyCode}


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.

{\bfseries{NOTE}} this library has a similar interface to the {\ttfamily debug} module, and this module uses the calling file to get the boundary for the call stacks, so you should always create a new {\ttfamily deprecate} object in each file and not within some central file.\hypertarget{md_sfcode_node_modules_depd_Readme_autotoc_md8099}{}\doxysubsection{depd(namespace)}\label{md_sfcode_node_modules_depd_Readme_autotoc_md8099}
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.\hypertarget{md_sfcode_node_modules_depd_Readme_autotoc_md8100}{}\doxysubsection{deprecate(message)}\label{md_sfcode_node_modules_depd_Readme_autotoc_md8100}
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 {\ttfamily deprecate()} call and will display the name of the function called, similar to the name displayed in a stack trace.\hypertarget{md_sfcode_node_modules_depd_Readme_autotoc_md8101}{}\doxysubsection{deprecate.\+function(fn, message)}\label{md_sfcode_node_modules_depd_Readme_autotoc_md8101}
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.\hypertarget{md_sfcode_node_modules_depd_Readme_autotoc_md8102}{}\doxysubsection{deprecate.\+property(obj, prop, message)}\label{md_sfcode_node_modules_depd_Readme_autotoc_md8102}
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.\hypertarget{md_sfcode_node_modules_depd_Readme_autotoc_md8103}{}\doxysubsection{process.\+on(\textquotesingle{}deprecation\textquotesingle{}, fn)}\label{md_sfcode_node_modules_depd_Readme_autotoc_md8103}
This module will allow easy capturing of deprecation errors by emitting the errors as the type \char`\"{}deprecation\char`\"{} on the global {\ttfamily 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\+:


\begin{DoxyItemize}
\item {\ttfamily message} -\/ This is the message given by the library
\item {\ttfamily name} -\/ This is always `\textquotesingle{}Deprecation\+Error'{\ttfamily  -\/}namespace{\ttfamily -\/ This is the namespace the deprecation came from -\/}stack\`{} -\/ This is the stack of the call to the deprecated thing
\end{DoxyItemize}

Example {\ttfamily error.\+stack} output\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{DeprecationError: my-\/cool-\/module deprecated oldfunction}
\DoxyCodeLine{    at Object.<anonymous> ([eval]-\/wrapper:6:22)}
\DoxyCodeLine{    at Module.\_compile (module.js:456:26)}
\DoxyCodeLine{    at evalScript (node.js:532:25)}
\DoxyCodeLine{    at startup (node.js:80:7)}
\DoxyCodeLine{    at node.js:902:3 }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_depd_Readme_autotoc_md8104}{}\doxysubsection{process.\+env.\+NO\+\_\+\+DEPRECATION}\label{md_sfcode_node_modules_depd_Readme_autotoc_md8104}
As a user of modules that are deprecated, the environment variable {\ttfamily NO\+\_\+\+DEPRECATION} is provided as a quick solution to silencing deprecation warnings from being output. The format of this is similar to that of {\ttfamily DEBUG}\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\$ NO\_DEPRECATION=my-\/module,othermod node app.js }

\end{DoxyCode}


This will suppress deprecations from being output for \char`\"{}my-\/module\char`\"{} and \char`\"{}othermod\char`\"{}. The value is a list of comma-\/separated namespaces. To suppress every warning across all namespaces, use the value {\ttfamily $\ast$} for a namespace.

Providing the argument {\ttfamily -\/-\/no-\/deprecation} to the {\ttfamily node} executable will suppress all deprecations (only available in Node.\+js 0.\+8 or higher).

{\bfseries{NOTE}} This will not suppress the deperecations given to any \char`\"{}deprecation\char`\"{} event listeners, just the output to STDERR.\hypertarget{md_sfcode_node_modules_depd_Readme_autotoc_md8105}{}\doxysubsection{process.\+env.\+TRACE\+\_\+\+DEPRECATION}\label{md_sfcode_node_modules_depd_Readme_autotoc_md8105}
As a user of modules that are deprecated, the environment variable {\ttfamily 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 {\ttfamily NO\+\_\+\+DEPRECATION}\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\$ TRACE\_DEPRECATION=my-\/module,othermod node app.js }

\end{DoxyCode}


This will include stack traces for deprecations being output for \char`\"{}my-\/module\char`\"{} and \char`\"{}othermod\char`\"{}. The value is a list of comma-\/separated namespaces. To trace every warning across all namespaces, use the value {\ttfamily $\ast$} for a namespace.

Providing the argument {\ttfamily -\/-\/trace-\/deprecation} to the {\ttfamily node} executable will trace all deprecations (only available in Node.\+js 0.\+8 or higher).

{\bfseries{NOTE}} This will not trace the deperecations silenced by {\ttfamily NO\+\_\+\+DEPRECATION}.\hypertarget{md_sfcode_node_modules_depd_Readme_autotoc_md8106}{}\doxysection{Display}\label{md_sfcode_node_modules_depd_Readme_autotoc_md8106}


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 {\ttfamily debug} module)\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{bright cyan    bright yellow}
\DoxyCodeLine{|              |          reset       cyan}
\DoxyCodeLine{|              |          |           |}
\DoxyCodeLine{▼              ▼          ▼           ▼}
\DoxyCodeLine{my-\/cool-\/module deprecated oldfunction [eval]-\/wrapper:6:22}
\DoxyCodeLine{▲              ▲          ▲           ▲}
\DoxyCodeLine{|              |          |           |}
\DoxyCodeLine{namespace      |          |           location of mycoolmod.oldfunction() call}
\DoxyCodeLine{               |          deprecation message}
\DoxyCodeLine{               the word "{}deprecated"{} }

\end{DoxyCode}


If the user redirects their STDERR to a file or somewhere that does not support colors, they see (similar layout to the {\ttfamily debug} module)\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{Sun, 15 Jun 2014 05:21:37 GMT my-\/cool-\/module deprecated oldfunction at [eval]-\/wrapper:6:22}
\DoxyCodeLine{▲                             ▲              ▲          ▲              ▲}
\DoxyCodeLine{|                             |              |          |              |}
\DoxyCodeLine{timestamp of message          namespace      |          |             location of mycoolmod.oldfunction() call}
\DoxyCodeLine{                                             |          deprecation message}
\DoxyCodeLine{                                             the word "{}deprecated"{} }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_depd_Readme_autotoc_md8107}{}\doxysection{Examples}\label{md_sfcode_node_modules_depd_Readme_autotoc_md8107}
\hypertarget{md_sfcode_node_modules_depd_Readme_autotoc_md8108}{}\doxysubsection{Deprecating all calls to a function}\label{md_sfcode_node_modules_depd_Readme_autotoc_md8108}
This will display a deprecated message about \char`\"{}oldfunction\char`\"{} being deprecated from \char`\"{}my-\/module\char`\"{} on STDERR.


\begin{DoxyCode}{0}
\DoxyCodeLine{var deprecate = require('depd')('my-\/cool-\/module')}
\DoxyCodeLine{}
\DoxyCodeLine{// message automatically derived from function name}
\DoxyCodeLine{// Object.oldfunction}
\DoxyCodeLine{exports.oldfunction = deprecate.function(function oldfunction () \{}
\DoxyCodeLine{  // all calls to function are deprecated}
\DoxyCodeLine{\})}
\DoxyCodeLine{}
\DoxyCodeLine{// specific message}
\DoxyCodeLine{exports.oldfunction = deprecate.function(function () \{}
\DoxyCodeLine{  // all calls to function are deprecated}
\DoxyCodeLine{\}, 'oldfunction') }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_depd_Readme_autotoc_md8109}{}\doxysubsection{Conditionally deprecating a function call}\label{md_sfcode_node_modules_depd_Readme_autotoc_md8109}
This will display a deprecated message about \char`\"{}weirdfunction\char`\"{} being deprecated from \char`\"{}my-\/module\char`\"{} on STDERR when called with less than 2 arguments.


\begin{DoxyCode}{0}
\DoxyCodeLine{var deprecate = require('depd')('my-\/cool-\/module')}
\DoxyCodeLine{}
\DoxyCodeLine{exports.weirdfunction = function () \{}
\DoxyCodeLine{  if (arguments.length < 2) \{}
\DoxyCodeLine{    // calls with 0 or 1 args are deprecated}
\DoxyCodeLine{    deprecate('weirdfunction args < 2')}
\DoxyCodeLine{  \}}
\DoxyCodeLine{\} }

\end{DoxyCode}


When calling {\ttfamily 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\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var deprecate = require('depd')('my-\/cool-\/module')}
\DoxyCodeLine{}
\DoxyCodeLine{exports.weirdfunction = function () \{}
\DoxyCodeLine{  if (arguments.length < 2) \{}
\DoxyCodeLine{    // calls with 0 or 1 args are deprecated}
\DoxyCodeLine{    deprecate('weirdfunction args < 2')}
\DoxyCodeLine{  \} else if (typeof arguments[0] !== 'string') \{}
\DoxyCodeLine{    // calls with non-\/string first argument are deprecated}
\DoxyCodeLine{    deprecate('weirdfunction non-\/string first arg')}
\DoxyCodeLine{  \}}
\DoxyCodeLine{\} }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_depd_Readme_autotoc_md8110}{}\doxysubsection{Deprecating property access}\label{md_sfcode_node_modules_depd_Readme_autotoc_md8110}
This will display a deprecated message about \char`\"{}oldprop\char`\"{} being deprecated from \char`\"{}my-\/module\char`\"{} on STDERR when accessed. A deprecation will be displayed when setting the value and when getting the value.


\begin{DoxyCode}{0}
\DoxyCodeLine{var deprecate = require('depd')('my-\/cool-\/module')}
\DoxyCodeLine{}
\DoxyCodeLine{exports.oldprop = 'something'}
\DoxyCodeLine{}
\DoxyCodeLine{// message automatically derives from property name}
\DoxyCodeLine{deprecate.property(exports, 'oldprop')}
\DoxyCodeLine{}
\DoxyCodeLine{// explicit message}
\DoxyCodeLine{deprecate.property(exports, 'oldprop', 'oldprop >= 0.10') }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_depd_Readme_autotoc_md8111}{}\doxysection{License}\label{md_sfcode_node_modules_depd_Readme_autotoc_md8111}
\mbox{[}MIT\mbox{]}(LICENSE) 