feat($timeout): Add debouncing support to $timeout service

This feature allows resetting the timer on an ongoing `$timeout` promise.

A fourth optional argument is added to `$timeout` which is the
old promise to be reset.

I.e.: `promise = $timeout(fn, 2000, true, promise);`

This will call `fn()` 2 seconds after the last call to the `$timeout()`
function.

Author: lrlopez

src/ng/timeout.js

@@ -29,15 +29,23 @@ function $TimeoutProvider() {
       * @param {number=} [delay=0] Delay in milliseconds.
       * @param {boolean=} [invokeApply=true] If set to `false` skips model dirty checking, otherwise
       *   will invoke `fn` within the {@link ng.$rootScope.Scope#$apply $apply} block.
+      * @param {Promise=} debounce If set to an outgoing promise, it will reject it before creating
+      *   the new one. This allows debouncing the execution of the function.
       * @returns {Promise} Promise that will be resolved when the timeout is reached. The value this
       *   promise will be resolved with is the return value of the `fn` function.
       */
-    function timeout(fn, delay, invokeApply) {
+    function timeout(fn, delay, invokeApply, debounce) {
       var deferred = $q.defer(),
           promise = deferred.promise,
           skipApply = (isDefined(invokeApply) && !invokeApply),
           timeoutId, cleanup;
 
+      // debouncing support
+      if (debounce && debounce.$$timeoutId in deferreds) {
+        deferreds[debounce.$$timeoutId].reject('debounced');
+        $browser.defer.cancel(debounce.$$timeoutId);
+      }
+
       timeoutId = $browser.defer(function() {
         try {
           deferred.resolve(fn());

test/ng/timeoutSpec.js

@@ -199,4 +199,34 @@ describe('$timeout', function() {
       expect(cancelSpy).toHaveBeenCalledOnce();
     }));
   });
+
+
+  describe('debouncing', function() {
+    it('should allow debouncing tasks', inject(function($timeout) {
+      var task = jasmine.createSpy('task'),
+          successtask = jasmine.createSpy('successtask'), 
+          errortask = jasmine.createSpy('errortask'),
+          promise = null;
+
+      promise = $timeout(task, 10000, true, promise);
+      promise.then(successtask, errortask);
+
+      expect(task).not.toHaveBeenCalled();
+      expect(successtask).not.toHaveBeenCalled();
+      expect(errortask).not.toHaveBeenCalled();
+      
+      promise = $timeout(task, 10000, true, promise);
+      expect(task).not.toHaveBeenCalled();
+      expect(successtask).not.toHaveBeenCalled();
+      expect(errortask).not.toHaveBeenCalled();
+
+      $timeout.flush();
+
+      expect(task).toHaveBeenCalled();
+      // it's a different promise, so 'successtask' should not be called but 'errortask' should
+      expect(successtask).not.toHaveBeenCalled();
+      expect(errortask).toHaveBeenCalled();
+    }));
+
+  });
 });