jQuery+: Create $.wait():Promise feature

Create a $.wait(delay, function(){...}) that returns a promise. While jQuery has jQuery.delay() that is used in UI and queues, this is very different in that any Function can be delayed! Promises then allow .done() and .pipe() features to be used.

by Thomas Burleson

HTML

<body>
<!--
    SyntaxHighlighter code prettify
-->
<script type="text/javascript" src="http://alexgorbatchev.com/pub/sh/current/scripts/shCore.js"></script>
<script type="text/javascript" src="http://alexgorbatchev.com/pub/sh/current/scripts/shBrushJScript.js"></script>
<script type="text/javascript" src="http://alexgorbatchev.com/pub/sh/current/scripts/shBrushAS3.js"></script>     
<link type="text/css" rel="stylesheet" href="http://alexgorbatchev.com/pub/sh/current/styles/shCoreDefault.css"/>
<link type="text/css" rel="stylesheet" href="http://alexgorbatchev.com/pub/sh/current/styles/shThemeRDark.css" />    
<script type="text/javascript">SyntaxHighlighter.all();</script>

<div id="body">
    <div id="header"></div>
    <div id="contents">
        <div id="intro">
            <p>
                Create a <span class='jquery'>$.wait()</span> function that uses <strong><a href="http://api.jquery.com/delay/" target="_blank">jQuery Deferred/Promise</a></strong> features.
            </p>
        </div>
        <h2 id="getting-started">
            <span class='code'>$.wait</span>( delay, &lt;function&gt;, ... ) : Promise
        </h2><br>
        <div class="contents">
            <div class="bullet">
                <div class="description">
                    jQuery has a function <span class='jquery'>jQuery.delay()</span> that is used to delay the execution of functions that follow it in the queue. It can be used with the standard effects queue or with a custom queue. In contrast, <code><span class='code'>$.wait()</span></code> is very different. Any function call can be delayed, even if it is not in a jQuery queue!<br>
                    <br>
                    Best of all... since the <code><span class='code'>$.wait()</span></code> function returns a Promise, developers can easily use the <span class='jquery'>Promise::pipe()</span> and <span class='jquery'>Promise::done()</span> features to chain actions and easily defer custom processing to a future...

CSS

code {
  border: 1px solid rgba(0, 0, 0, 0.1);
  border-radius: 3px 3px 3px 3px;
  font-family: monospace;
  font-size: 120%;
  padding: 0 3px;
}
.intro {
  width: 100%;
}
#body {
  -moz-box-align: center;
  -moz-box-orient: vertical;
  display: -moz-box;
  width: 100%;
}
#contents {
  -moz-box-orient: vertical;
  background-color: #fef3e9;
  border-radius: 10px 10px 10px 10px;
  box-shadow: 0 0 10px #723600;
  display: -moz-box;
  padding: 20px;
  position: relative;
  top: -20px;
  width: 60%;
  height: 100%;
  z-index: 2;
}
#contents h1 {
  color: #3F1E00;
  margin-bottom: 0;
}
#intro {
  background: none repeat scroll 0 0 rgba(0, 0, 0, 0.1);
  border-radius: 5px 5px 5px 5px;
  color: #723600;
  font-size: 18px;
  line-height: 24px;
  padding: 10px;
}
#intro p {
  margin: 0;
}
#intro p + p {
  margin-top: 10px;
}
#intro strong {
  color: #582A00;
}

.contents {
  width: 725px;
}
h2 {
  -moz-box-sizing: border-box;
  border-bottom: 3px solid #8B4200;
  color: #582A00;
  font-size: 20px;
  margin-top: 24px;
  padding: 5px;
  width: 100%;
}
ul.bullet {
  -moz-box-align: center;
  -moz-box-orient: horizontal;
  -moz-box-pack: justify;
  display: -moz-box;
}
ul.bullet a {
  -moz-box-flex: 1;
  margin-left: 0;
  margin-right: 10px;
}
ul.bullet a:last-child {
  margin-right: 0;
}
.bullet {
  -moz-box-orient: vertical;
  -moz-box-sizing: border-box;
  display: -moz-box;
  padding: 8px 15px;
  width: 100%;
}
.bullet .description {
  color: #3F1E00;
  line-height: 24px;
  margin-bottom: 8px;
  margin-right: 16px;
  width: 100%;
}
.bullet a {
  background-image: -moz-linear-gradient(center top , #F38709, #C26C07);
  border-radius: 5px 5px 5px 5px;
  color: white;
  display: block;
  margin: 10px 0 0 450px;
  padding-bottom: 8px;
  padding-top: 8px;
  padding-left: 5px;
  padding-right: 5px;
  text-align: center;
  text-decoration: none;
  text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.3);
}
.bullet a:hover {
  background-image: -moz-linear-gradient(center top , #C26C07,...

JavaScript

( function($) {
    
    /**
     * Similar to the jQuery.delay() function but this one supports any arbitrary delay 
     * and allows optional, additional parameters to passed [later] to the 
     * resolved handler [assigned via .done() or .then()].
     *  
     * A special configuration allows the 1st optional parameter to be a function
     * reference so the wait(delay,function(){...}) syntax can be easily used.
     * 
     * Here are the possible call options:
     * 
     *   wait( delay )
     *   wait( delay, ...params )
     *   wait( delay, func2Call )
     *   wait( delay, func2Call, ...func2Params )
     * 
     * @param delay Number of milliseconds to wait before resolving/projecting the promise; 
     *              Default value === 30 msecs
     *
     * @param args  Optional listing of parameters 
     */
     $.wait = function() {
        
        var args  = [].slice.call( arguments, 1 ),
            delay = arguments[0];
                     
        /**
         * If the first variable param is a Function reference, then auto-call
         * that function with/without any subsequent optional params 
         */
        var doInlineCallback = function () {
            var func   = args.length ? args[0] : null,
                result = null;
            
            if ( $.isFunction(func) ) {
                // 1) Remove function element,
                // 2) Call function, save response, and
                // 3) Clear arguments
                
                args.shift();
                
                result = func.apply(null, args);
                args   = [ ];
            }
            
            return result;
        };
        
        return new $.Deferred( function(dfd) {
            var timer = setTimeout( function(){
                clearInterval(timer);
                
                // Call the specified function (if any)
                
                var response = doInlineCallback();
                
          ...