change to debounce TODO: add proper throttle

debounce/README.md

@@ -0,0 +1,32 @@
+Here's the basic usage of the file that you'll be creating:
+
+```js
+var debounce = require('./') // <- this is the file you make;
+
+var sayHi = function() {
+  console.log('hi');
+};
+
+var debounced = debounce(sayHi, 100);
+
+debounced();
+debounced();
+debounced();
+debounced();
+
+// there should only be one 'hi' message on the console
+```
+
+More info: http://underscorejs.org/#debounce
+
+
+### Difference between debounce and throttle
+There's a lot in common between debounce and throttle, people sometimes confuse the two. The general difference between them is that throttle is used to make sure the function doesn't execute more than once per x milliseconds as opposed to debounce which makes sure that the function doesn't execute until x milliseconds passed without it being called.
+
+For example: Let's say that you have a page that darkens the background based on how far down the page the user scrolled and also saves the scroll location on the server. In the case of smooth scrolling this function can end up being called hundreds of times per second. Assuming that checking the page scroll involves some fancy math and DOM touching this can end up causing the function to still be running as the next scroll event happens :( .
+
+Let's assume the user is continuously scrolling the page...
+
+In the case of darkening the background you would use a throttle function because you want to still darken the background even as new scroll events happen, just not as often as they come in.
+
+In the case of saving the scroll position on the server, you wouldn't want it to be saved until after the user is done scrolling, so you would use the debounce function.

throttle/test.js → debounce/test.js

@@ -1,15 +1,25 @@
 var assert = require('assert');
-var throttle = require('./');
+var debounce = require('./');
+
+describe('debounce', function() {
+  it('waits for the threshold to pass before executing', function(done) {
+    var now = new Date();
+    var debounced = debounce(function() {
+      assert.equal(new Date() - now > 10);
+      done();
+      called++;
+    }, 10);
+    debounced();
+  });
 
-describe('throttle', function() {
   it("won't execute more than once within the threshold", function(done) {
     var called = 0;
-    var throttled = throttle(function() {
+    var debounced = debounce(function() {
       called++;
     }, 10);
-    throttled();
-    throttled();
-    throttled();
+    debounced();
+    debounced();
+    debounced();
     setTimeout(function() {
       assert.equal(called, 1);
       done();
@@ -18,12 +28,12 @@ describe('throttle', function() {
 
   it("will execute more than once outside the threshold", function(done) {
     var called = 0;
-    var throttled = throttle(function() {
+    var debounced = debounce(function() {
       called++;
     }, 10);
-    throttled();
-    setTimeout(throttled, 5);
-    setTimeout(throttled, 20);
+    debounced();
+    setTimeout(debounced, 5);
+    setTimeout(debounced, 20);
     setTimeout(function() {
       assert.equal(called, 2);
       done();
@@ -32,26 +42,26 @@ describe('throttle', function() {
 
   it('gets called with context', function(done) {
     var ctx;
-    var throttled = throttle(function() {
+    var debounced = debounce(function() {
       ctx = this;
     }, 10);
-    throttled.call(11);
-    throttled.call(22);
+    debounced.call(11);
+    debounced.call(22);
     setTimeout(function() {
-      assert.equal(ctx, 11);
+      assert.equal(ctx, 22);
       done();
     }, 15)
   });
 
   it('gets called with arguments', function(done) {
     var args;
-    var throttled = throttle(function() {
+    var debounced = debounce(function() {
       args = [].slice.call(arguments);
     }, 10);
-    throttled(11, 22, 33);
-    throttled(22, 33, 44);
+    debounced(11, 22, 33);
+    debounced(22, 33, 44);
     setTimeout(function() {
-      assert.deepEqual(args, [11, 22, 33]);
+      assert.deepEqual(args, [22, 33, 44]);
       done();
     }, 15);
   });