\href{http://promises-aplus.github.com/promises-spec}{\texttt{ }}

\href{https://travis-ci.org/cujojs/when}{\texttt{ }}\hypertarget{md_sfcode_node_modules_when_README_autotoc_md34043}{}\doxysection{when.\+js}\label{md_sfcode_node_modules_when_README_autotoc_md34043}
When.\+js is a rock solid, battle-\/tested \href{http://promises-aplus.github.com/promises-spec}{\texttt{ Promises/\+A+}} and {\ttfamily when()} implementation, including a complete ES6 Promise shim. It\textquotesingle{}s a powerful combination of small size, high performance, debuggability, and rich features\+:


\begin{DoxyItemize}
\item Resolve arrays and hashes of promises, as well as infinite promise sequences
\item Execute tasks in parallel or sequentially
\item Transform Node-\/style and other callback-\/based APIs into promise-\/based APIs
\end{DoxyItemize}

When.\+js is one of the many stand-\/alone components of \href{http://cujojs.com}{\texttt{ cujo\+JS}}, the Java\+Script Architectural Toolkit.

Check it out\+:


\begin{DoxyItemize}
\item What\textquotesingle{}s new
\item \href{docs/api.md\#api}{\texttt{ API docs}}
\item Read more about how \href{http://know.cujojs.com/tutorials/async/simplifying-async-with-promises}{\texttt{ promises simplify async programming}}
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_when_README_autotoc_md34044}{}\doxysubsection{Installation}\label{md_sfcode_node_modules_when_README_autotoc_md34044}
\hypertarget{md_sfcode_node_modules_when_README_autotoc_md34045}{}\doxyparagraph{AMD}\label{md_sfcode_node_modules_when_README_autotoc_md34045}
Availble as {\ttfamily when} through \href{http://bower.io}{\texttt{ bower}}, or just clone the repo and load {\ttfamily when.\+js} from the root.


\begin{DoxyCode}{0}
\DoxyCodeLine{bower install -\/-\/save when }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_when_README_autotoc_md34046}{}\doxyparagraph{Common\+JS/\+Node}\label{md_sfcode_node_modules_when_README_autotoc_md34046}

\begin{DoxyCode}{0}
\DoxyCodeLine{npm install -\/-\/save when }

\end{DoxyCode}


More help \& other environments \guillemotright{}\hypertarget{md_sfcode_node_modules_when_README_autotoc_md34047}{}\doxysubsection{Usage}\label{md_sfcode_node_modules_when_README_autotoc_md34047}
Promises can be used to help manage complex and/or nested callback flows in a simple manner. To get a better handle on how promise flows look and how they can be helpful, there are a couple examples below (using commonjs).

This first example will print {\ttfamily \char`\"{}hello world!!!!\char`\"{}} if all went well, or {\ttfamily \char`\"{}drat!\char`\"{}} if there was a problem. It also uses \href{https://github.com/cujojs/rest}{\texttt{ rest}} to make an ajax request to a (fictional) external service.


\begin{DoxyCode}{0}
\DoxyCodeLine{var rest = require('rest');}
\DoxyCodeLine{}
\DoxyCodeLine{fetchRemoteGreeting()}
\DoxyCodeLine{    .then(addExclamation)}
\DoxyCodeLine{    .catch(handleError)}
\DoxyCodeLine{    .done(function(greeting) \{}
\DoxyCodeLine{        console.log(greeting);}
\DoxyCodeLine{    \});}
\DoxyCodeLine{}
\DoxyCodeLine{function fetchRemoteGreeting() \{}
\DoxyCodeLine{    // returns a when.js promise for 'hello world'}
\DoxyCodeLine{    return rest('http://example.com/greeting');}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{function addExclamation(greeting) \{}
\DoxyCodeLine{    return greeting + '!!!!'}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{function handleError(e) \{}
\DoxyCodeLine{    return 'drat!';}
\DoxyCodeLine{\} }

\end{DoxyCode}


The second example shows off the power that comes with when\textquotesingle{}s promise logic. Here, we get an array of numbers from a remote source and reduce them. The example will print {\ttfamily 150} if all went well, and if there was a problem will print a full stack trace.


\begin{DoxyCode}{0}
\DoxyCodeLine{var when = require('when');}
\DoxyCodeLine{var rest = require('rest');}
\DoxyCodeLine{}
\DoxyCodeLine{when.reduce(when.map(getRemoteNumberList(), times10), sum)}
\DoxyCodeLine{    .done(function(result) \{}
\DoxyCodeLine{        console.log(result);}
\DoxyCodeLine{    \});}
\DoxyCodeLine{}
\DoxyCodeLine{function getRemoteNumberList() \{}
\DoxyCodeLine{    // Get a remote array [1, 2, 3, 4, 5]}
\DoxyCodeLine{    return rest('http://example.com/numbers').then(JSON.parse);}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{function sum(x, y) \{ return x + y; \}}
\DoxyCodeLine{function times10(x) \{return x * 10; \} }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_when_README_autotoc_md34048}{}\doxysubsection{License}\label{md_sfcode_node_modules_when_README_autotoc_md34048}
Licensed under MIT. \href{LICENSE.txt}{\texttt{ Full license here \guillemotright{}}}\hypertarget{md_sfcode_node_modules_when_README_autotoc_md34049}{}\doxysubsection{Contributing}\label{md_sfcode_node_modules_when_README_autotoc_md34049}
Please see the contributing guide for more information on running tests, opening issues, and contributing code to the project.\hypertarget{md_sfcode_node_modules_when_README_autotoc_md34050}{}\doxysubsection{References}\label{md_sfcode_node_modules_when_README_autotoc_md34050}
Much of this code was inspired by the async innards of \href{https://github.com/cujojs/wire}{\texttt{ wire.\+js}}, and has been influenced by the great work in \href{https://github.com/kriskowal/q}{\texttt{ Q}}, \href{https://github.com/dojo/dojo}{\texttt{ Dojo\textquotesingle{}s Deferred}}, and \href{https://github.com/phiggins42/uber.js}{\texttt{ uber.\+js}}. 