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.

1 files changed, 22 insertions, 2 deletions

diff --git a/src/service/defer.js b/src/service/defer.js
index 7d0fdeb7..42f80d25 100644
--- a/src/service/defer.js
+++ b/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']);