Merge pull request #17 from wilsonpage/dev

Cleaner FastDom#clear API

7 files changed, 93 insertions, 61 deletions

diff --git a/History.md b/History.md
new file mode 100644
index 0000000..58e4104
--- /dev/null
+++ b/History.md
@@ -0,0 +1,7 @@
+
+0.7.0 / 2013-10-05
+==================
+
+  * add `FastDom#clear` clears read, write and defer jobs by id
+  * remove `FastDom#clearRead`
+  * remove `FastDom#clearWrite`
\ No newline at end of file
diff --git a/README.md b/README.md
index c703c79..c5f6e84 100644
--- a/README.md
+++ b/README.md
@@ -83,32 +83,28 @@ fastdom.write(function() {
 });
 ```
 
-### FastDom#clearRead(id)
-
-Removes a job from the 'read' queue by id.
-
-```js
-var id = fastdom.read(function(){});
-fastdom.clearRead(id);
-```
+### FastDom#defer(frames, callback[, context])
 
-### FastDom#clearWrite(id)
+Defers a job for the number of frames specified. This is useful is you have a particualrly expensive piece of work to do, and don't want it to be done with all the other work.
 
-Removes a job from the 'write' queue by id.
+For example; you are using third party library that doesn't expose an API that allows you split DOM read/write work, `fastdom.defer()` will push this work futher into the future and prevent it from disrupting other carefully batched work.
 
 ```js
-var id = fastdom.write(function(){});
-fastdom.clearWrite(id);
+fastdom.defer(3, expensiveStuff);
 ```
 
-### FastDom#defer(frames, callback[, context])
+### FastDom#clear(id)
 
-Defers a job for the number of frames specified. This is useful is you have a particualrly expensive piece of work to do, and don't want it to be done with all the other work.
-
-For example; you are using third party library that doesn't expose an API that allows you split DOM read/write work, `fastdom.defer()` will push this work futher into the future and prevent it from disrupting other carefully batched work.
+Clears **any** scheduled job by id.
 
 ```js
-fastdom.defer(3, expensiveStuff);
+var read = fastdom.read(function(){});
+var write = fastdom.write(function(){});
+var defer = fastdom.defer(4, function(){});
+
+fastdom.clear(read);
+fastdom.clear(write);
+fastdom.clear(defer);
 ```
 
 ## Tests
diff --git a/bower.json b/bower.json
index 91ef9e9..e184380 100644
--- a/bower.json
+++ b/bower.json
@@ -1,7 +1,7 @@
 {
   "name": "fastdom",
   "description": "Eliminates layout thrashing by batching DOM read/write operations",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "main": "lib/fastdom.js",
   "scripts": [
     "lib/fastdom.js"
diff --git a/component.json b/component.json
index 702f9f1..792072c 100644
--- a/component.json
+++ b/component.json
@@ -1,7 +1,7 @@
 {
   "name": "fastdom",
   "description": "Eliminates layout thrashing by batching DOM read/write operations",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "main": "lib/fastdom.js",
   "scripts": [
     "lib/fastdom.js"
diff --git a/lib/fastdom.js b/lib/fastdom.js
index a5f98ad..677a215 100644
--- a/lib/fastdom.js
+++ b/lib/fastdom.js
@@ -13,12 +13,23 @@
 
   'use strict';
 
-  // RequestAnimationFrame Polyfill
+  // Normalize rAF
   var raf = window.requestAnimationFrame
     || window.webkitRequestAnimationFrame
     || window.mozRequestAnimationFrame
     || function(cb) { window.setTimeout(cb, 1000 / 60); };
 
+  // Normalize cAF
+  var caf = window.cancelAnimationFrame
+    || window.cancelRequestAnimationFrame
+    || window.mozCancelAnimationFrame
+    || window.mozCancelRequestAnimationFrame
+    || window.webkitCancelAnimationFrame
+    || window.webkitCancelRequestAnimationFrame
+    || window.msCancelAnimationFrame
+    || window.msCancelRequestAnimationFrame
+    || function(id) { window.clearTimeout(id); };
+
   // Use existing instance if
   // one already exists in
   // this app, else make one.
@@ -37,8 +48,10 @@
     this.jobs = {};
     this.mode = null;
     this.pending = false;
-    this.reads = [];
-    this.writes = [];
+    this.queue = {
+      read: [],
+      write: []
+    };
   }
 
   /**
@@ -49,9 +62,10 @@
    * @api public
    */
   FastDom.prototype.read = function(fn, ctx) {
-    var id = this._add(this.reads, fn, ctx);
+    var job = this._add('read', fn, ctx);
+    this.queue.read.push(job.id);
     this._request('read');
-    return id;
+    return job.id;
   };
 
   /**
@@ -62,9 +76,10 @@
    * @api public
    */
   FastDom.prototype.write = function(fn, ctx) {
-    var id = this._add(this.writes, fn, ctx);
+    var job = this._add('write', fn, ctx);
+    this.queue.write.push(job.id);
     this._request('write');
-    return id;
+    return job.id;
   };
 
   /**
@@ -74,19 +89,21 @@
    * @param  {Number} id
    * @api public
    */
-  FastDom.prototype.clearRead = function(id) {
-    this._remove(this.reads, id);
-  };
+  FastDom.prototype.clear = function(id) {
+    var job = this.jobs[id];
+    if (!job) return;
+
+    // Defer jobs are cleared differently
+    if (job.type === 'defer') {
+      caf(job.timer);
+      return;
+    }
 
-  /**
-   * Removes a job from
-   * the 'writes' queue.
-   *
-   * @param  {Number} id
-   * @api public
-   */
-  FastDom.prototype.clearWrite = function(id) {
-    this._remove(this.writes, id);
+    var list = this.queue[job.type];
+    var index = list.indexOf(id);
+
+    if (~index) list.splice(index, 1);
+    delete this.jobs[id];
   };
 
   /**
@@ -182,12 +199,12 @@
     // Set the mode to 'reading',
     // then empty all read jobs
     this.mode = 'reading';
-    this._run(this.reads);
+    this._run(this.queue.read);
 
     // Set the mode to 'writing'
     // then empty all write jobs
     this.mode = 'writing';
-    this._run(this.writes);
+    this._run(this.queue.write);
 
     this.mode = null;
   };
@@ -203,16 +220,17 @@
    */
   FastDom.prototype.defer = function(frames, fn, ctx) {
     if (frames < 0) return;
-
+    var job = this._add('defer', fn);
     (function wrapped() {
       if (frames-- === 0) {
-        try { fn.call(ctx); } catch (e) {
+        try { fn.call(ctx); } catch(e) {
           if (this.onError) this.onError(e);
         }
       } else {
-        raf(wrapped);
+        job.timer = raf(wrapped);
       }
     })();
+    return job.id;
   };
 
   /**
@@ -225,22 +243,14 @@
    * @returns {Number} id
    * @api private
    */
-  FastDom.prototype._add = function(list, fn, ctx) {
+  FastDom.prototype._add = function(type, fn, ctx) {
     var id = this._uniqueId();
-
-    // Store this job
-    this.jobs[id] = {
+    return this.jobs[id] = {
+      id: id,
       fn: fn,
-      ctx: ctx
+      ctx: ctx,
+      type: type
     };
-
-    // Push the id of
-    // this job into
-    // the given queue
-    list.push(id);
-
-    // Return the id
-    return id;
   };
 
   /**
diff --git a/package.json b/package.json
index ef5a6b9..e9c77cd 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "fastdom",
   "description": "Eliminates layout thrashing by batching DOM read/write operations",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "main": "lib/fastdom.js",
   "scripts": {
     "test": "./node_modules/.bin/mocha-phantomjs test/index.html"
diff --git a/test/test.clear.js b/test/test.clear.js
index 6b274fe..0e5a0f8 100644
--- a/test/test.clear.js
+++ b/test/test.clear.js
@@ -6,7 +6,7 @@ suite('Clear', function(){
     var read = sinon.spy();
 
     var id = fastdom.read(read);
-    fastdom.clearRead(id);
+    fastdom.clear(id);
 
     raf(function() {
       assert(!read.called);
@@ -20,7 +20,7 @@ suite('Clear', function(){
     var read2 = sinon.spy();
 
     var id = fastdom.read(read);
-    fastdom.clearRead(id);
+    fastdom.clear(id);
 
     raf(function() {
       assert(!read2.called);
@@ -35,7 +35,7 @@ suite('Clear', function(){
 
     var id = fastdom.write(write);
     fastdom.read(function() {
-      fastdom.clearWrite(id);
+      fastdom.clear(id);
 
       raf(function() {
         assert(!read.called);
@@ -49,7 +49,7 @@ suite('Clear', function(){
     var write = sinon.spy();
     var id = fastdom.write(write);
 
-    fastdom.clearWrite(id);
+    fastdom.clear(id);
 
     raf(function() {
       assert(!write.called);
@@ -57,4 +57,23 @@ suite('Clear', function(){
     });
   });
 
+  test("Should not run 'defer' job if cleared", function(done) {
+    var fastdom = new FastDom();
+    var write = sinon.spy();
+    var id = fastdom.defer(3, write);
+
+    fastdom.clear(id);
+
+    raf(function() {
+      raf(function() {
+        raf(function() {
+          raf(function() {
+            assert(!write.called);
+            done();
+          });
+        });
+      });
+    });
+  });
+
 });
\ No newline at end of file