Merge pull request #4 from wilsonpage/dev

Implement clear API (closes #1)

6 files changed, 146 insertions, 13 deletions

diff --git a/README.md b/README.md
index 937b685..ff06f17 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,50 @@ dom.write(function() {
 <DOM Write>
 ```
 
+## API
+
+### DomBatch#read(callback)
+
+Schedules a task for the 'read' queue.
+
+```js
+dom.read(function() {
+  var width = element.clientWidth;
+});
+```
+
+### DomBatch#write(callback)
+
+Schedules a task for the 'write' queue.
+
+```js
+dom.write(function() {
+  element.style.width = width + 'px';
+});
+```
+
+### DomBatch#clearRead(callback)
+
+Removes a task from the 'read' queue.
+
+```js
+var fn = function(){};
+
+dom.read(fn);
+dom.clearRead(fn);
+```
+
+### DomBatch#clearWrite(callback)
+
+Removes a task from the 'write' queue.
+
+```js
+var fn = function(){};
+
+dom.write(fn);
+dom.clearWrite(fn);
+```
+
 ## Tests
 
 #### With PhantomJS
diff --git a/lib/dom-batch.js b/lib/dom-batch.js
index f4124ce..1e1bcb4 100644
--- a/lib/dom-batch.js
+++ b/lib/dom-batch.js
@@ -27,12 +27,9 @@
     : new DomBatch();
 
   /**
-   * Creates a new
+   * Creates a fresh
    * DomBatch instance.
    *
-   * (you should only have one
-   * instance per application).
-   *
    * @constructor
    */
   function DomBatch() {
@@ -67,6 +64,28 @@
   };
 
   /**
+   * Removes a job from
+   * the 'reads' queue.
+   *
+   * @param  {Function} fn
+   * @api public
+   */
+  DomBatch.prototype.clearRead = function(fn) {
+    remove(this.reads, fn);
+  };
+
+  /**
+   * Removes a job from
+   * the 'writes' queue.
+   *
+   * @param  {Function} fn
+   * @api public
+   */
+  DomBatch.prototype.clearWrite = function(fn) {
+    remove(this.writes, fn);
+  };
+
+  /**
    * Makes the decision as to
    * whether a the frame needs
    * to be scheduled.
@@ -131,14 +150,13 @@
     // that come in will schedule a new frame
     this.pending = false;
 
-    // Set the mode to 'reading' so
-    // that we know we can add more
-    // reads to the queue instead of
-    // scheduling a new frame.
+    // Set the mode to 'reading',
+    // then empty all read jobs
     this.mode = 'reading';
     this.run(this.reads);
 
-    // Set
+    // Set the mode to 'writing'
+    // then empty all write jobs
     this.mode = 'writing';
     this.run(this.writes);
 
@@ -146,6 +164,15 @@
   };
 
   /**
+   * Util
+   */
+
+  function remove(array, item) {
+    var index = array.indexOf(item);
+    if (~index) array.splice(index, 1);
+  }
+
+  /**
    * Expose 'DomBatch'
    */
 
diff --git a/test/buster.js b/test/buster.js
index 33839c3..e8278f3 100644
--- a/test/buster.js
+++ b/test/buster.js
@@ -4,10 +4,10 @@ config["dom-batch"] = {
   rootPath: '../',
   environment: "browser",
   sources: [
-    'test/setup.js',
-    'lib/dom-batch.js'
+    'lib/dom-batch.js',
+    'test/setup.js'
   ],
   tests: [
-    'test/tests.js'
+    'test/test-*.js'
   ]
 };
diff --git a/test/setup.js b/test/setup.js
index c556d1b..a28247b 100644
--- a/test/setup.js
+++ b/test/setup.js
@@ -3,4 +3,6 @@
 var raf = window.requestAnimationFrame
   || window.webkitRequestAnimationFrame
   || window.mozRequestAnimationFrame
-  || function(cb) { window.setTimeout(cb, 1000 / 60); };
\ No newline at end of file
+  || function(cb) { window.setTimeout(cb, 1000 / 60); };
+
+var DomBatch = dom.constructor;
\ No newline at end of file
diff --git a/test/test-clearing.js b/test/test-clearing.js
new file mode 100644
index 0000000..d5599d5
--- /dev/null
+++ b/test/test-clearing.js
@@ -0,0 +1,60 @@
+
+buster.testCase('DomBatch - Clearing', {
+
+  "Should not run 'read' job if cleared (sync)": function(done) {
+    var dom = new DomBatch();
+    var read = this.spy();
+
+    dom.read(read);
+    dom.clearRead(read);
+
+    raf(function() {
+      refute(read.called);
+      done();
+    });
+  },
+
+  "Should fail silently if job not found in queue": function(done) {
+    var dom = new DomBatch();
+    var read = this.spy();
+    var read2 = this.spy();
+
+    dom.read(read);
+    dom.clearRead(read2);
+
+    raf(function() {
+      refute(read2.called);
+      done();
+    });
+  },
+
+  "Should not run 'write' job if cleared (async)": function(done) {
+    var dom = new DomBatch();
+    var read = this.spy();
+    var write = this.spy();
+
+    dom.write(write);
+    dom.read(function() {
+      dom.clearWrite(write);
+
+      raf(function() {
+        refute(read.called);
+        done();
+      });
+    });
+  },
+
+  "Should not run 'write' job if cleared": function(done) {
+    var dom = new DomBatch();
+    var write = this.spy();
+
+    dom.write(write);
+    dom.clearWrite(write);
+
+    raf(function() {
+      refute(write.called);
+      done();
+    });
+  }
+
+});
\ No newline at end of file
diff --git a/test/tests.js b/test/test-setting.js
index 09f4b25..09f4b25 100644
--- a/test/tests.js
+++ b/test/test-setting.js