feat($defer): add $defer.cancel

This functionality was previously available only as obscure $browser.defer.cancel.

I also added docs and tests and fixed an issue in .defer.cancel mock.

src/Browser.js

@@ -390,12 +390,13 @@ function Browser(window, document, body, XHR, $log, $sniffer) {
    *
    * @name angular.service.$browser#defer.cancel
    * @methodOf angular.service.$browser.defer
-   * @returns {boolean} Returns `true` if the task hasn't executed yet and was successfuly canceled.
    *
    * @description
    * Cancels a defered task identified with `deferId`.
+   *
+   * @param {*} deferId Token returned by the `$browser.defer` function.
+   * @returns {boolean} Returns `true` if the task hasn't executed yet and was successfuly canceled.
    */
-
   self.defer.cancel = function(deferId) {
     if (pendingDeferIds[deferId]) {
       delete pendingDeferIds[deferId];

src/angular-mocks.js

@@ -283,6 +283,7 @@ function MockBrowser() {
 
     if (fnIndex !== undefined) {
       self.deferredFns.splice(fnIndex, 1);
+      return true;
     }
   };
 

src/service/defer.js

@@ -14,12 +14,32 @@
  *
  * @param {function()} fn A function, who's execution should be deferred.
  * @param {number=} [delay=0] of milliseconds to defer the function execution.
+ * @returns {*} DeferId that can be used to cancel the task via `$defer.cancel()`.
+ */
+
+/**
+ * @ngdoc function
+ * @name angular.service.$defer#cancel
+ * @methodOf angular.service.$defer
+ *
+ * @description
+ * Cancels a defered task identified with `deferId`.
+ *
+ * @param {*} deferId Token returned by the `$defer` function.
+ * @returns {boolean} Returns `true` if the task hasn't executed yet and was successfuly canceled.
  */
 angularServiceInject('$defer', function($browser) {
   var scope = this;
-  return function(fn, delay) {
-    $browser.defer(function() {
+
+  function defer(fn, delay) {
+    return $browser.defer(function() {
       scope.$apply(fn);
     }, delay);
+  }
+
+  defer.cancel = function(deferId) {
+    return $browser.defer.cancel(deferId);
   };
+
+  return defer;
 }, ['$browser']);

test/service/deferSpec.js

@@ -69,10 +69,53 @@ describe('$defer', function() {
     expect(applySpy).toHaveBeenCalled();
   });
 
+
   it('should allow you to specify the delay time', function() {
     var defer = this.spyOn($browser, 'defer');
     $defer(noop, 123);
     expect(defer.callCount).toEqual(1);
     expect(defer.mostRecentCall.args[1]).toEqual(123);
   });
+
+
+  it('should return a cancelation token', function() {
+    var defer = this.spyOn($browser, 'defer').andReturn('xxx');
+    expect($defer(noop)).toEqual('xxx');
+  });
+
+
+  describe('cancel', function() {
+    it('should cancel tasks', function() {
+      var task1 = jasmine.createSpy('task1'),
+          task2 = jasmine.createSpy('task2'),
+          task3 = jasmine.createSpy('task3'),
+          token1, token3;
+
+      token1 = $defer(task1);
+      $defer(task2);
+      token3 = $defer(task3, 333);
+
+      $defer.cancel(token3);
+      $defer.cancel(token1);
+      $browser.defer.flush();
+
+      expect(task1).not.toHaveBeenCalled();
+      expect(task2).toHaveBeenCalledOnce();
+      expect(task3).not.toHaveBeenCalled();
+    });
+
+
+    it('should return true if a task was succesffuly canceled', function() {
+      var task1 = jasmine.createSpy('task1'),
+          task2 = jasmine.createSpy('task2'),
+          token1, token2;
+
+      token1 = $defer(task1);
+      $browser.defer.flush();
+      token2 = $defer(task2);
+
+      expect($defer.cancel(token1)).toBeFalsy();
+      expect($defer.cancel(token2)).toBe(true);
+    });
+  });
 });