added rate limit utilities

Author: Tim Whitlock

examples/rate-limits.js

@@ -0,0 +1,44 @@
+/**
+ * Example spanks API rate limit and shows how to get rate limit data from client
+ */
+
+var client = require('../lib/twitter').createClient();
+
+client.setAuth ( 
+    '4MROlaLN7k2IyzhLrC7bg',
+    'x0HLIFFAvCGq3kse9EZt5asrPTzMhYxTtztp1QidI',
+    '16683251-gRyf6HILdKYrnGYvcYl4ZABS2h7Js9ylJ2h22kD8Q',
+    'V0fmla3bfopj9ApclxcKRfppU8OF9V6iLbHwm9U7I'
+);
+
+
+// Page through followers - this will run out pretty quickly
+var cursor = '-1';
+function nextPage(){
+    client.get( 'followers/ids', { cursor: cursor, screen_name: 'timwhitlock', skip_status: true }, function( page, error, status ){
+        if( error ){
+            if( 429 === status ){
+                var resetTime = client.getRateLimitReset();
+                console.error('Wait until '+ resetTime.toString() );
+            }
+            process.exit();
+        }
+        else {
+            console.log('OK: '+cursor+' -> '+page.ids.length+' followers' );
+            cursor = page.next_cursor_str;
+            
+            var limit = client.getRateLimit();
+            if( limit ){
+                var remaining = client.getRateLimitRemaining();
+                if( remaining ){
+                    console.log( 'No requests left. Next call will throw 429 .. you\'ll see' );
+                }
+                else {
+                    console.log( remaining+' of '+limit+' requests remaining');
+                }
+            }
+        }
+        cursor && nextPage();
+    } );
+}
+nextPage();

lib/twitter.js

@@ -118,6 +118,25 @@ OAuthParams.prototype.getHeader = function(){
  */
 function TwitterClient(){
     this.deAuth();
+    // register rate limits for all REST calls
+    this.lastCall = null;
+    this.lastMeta = {};
+}
+
+TwitterClient.prototype.getLastMeta = function( method ){
+    return this.lastMeta[ method || this.lastCall ] || { limit: 0, remaining: 0, reset: 0 };
+}
+
+TwitterClient.prototype.getRateLimit = function( method ){
+    return this.getLastMeta(method).limit;
+}
+
+TwitterClient.prototype.getRateLimitRemaining = function( method ){
+    return this.getLastMeta(method).remaining;
+}
+
+TwitterClient.prototype.getRateLimitReset = function( method ){
+    return new Date( this.getLastMeta(method).reset * 1000 );
 }
 
 TwitterClient.prototype.setAuth = function( consumerKey, consumerSecret, accessKey, accessSecret ){
@@ -159,6 +178,8 @@ TwitterClient.prototype._rest = function( requestMethod, requestPath, requestArg
             console.error('No callback for '+requestMethod+' '+requestUri);
         }
     }
+    this.lastCall = requestPath;
+    var client = this;
     return this.call( requestMethod, requestUri, requestArgs, TWITTER_API_TIMEOUT, function( res, err ) {
         if( ! res ){
             callback( null, err, 0 );
@@ -191,6 +212,16 @@ TwitterClient.prototype._rest = function( requestMethod, requestPath, requestArg
                 callback( data, error, res.statusCode );
             }
         } );
+        // remember last rest call
+        // pull rate limit data from headers
+        var limit = res.headers['x-rate-limit-limit'];
+        if( limit ){
+            client.lastMeta[ client.lastCall ] = {
+                limit:     Number( limit ),
+                remaining: Number( res.headers['x-rate-limit-remaining'] ),
+                reset:     Number( res.headers['x-rate-limit-reset'] )
+            }
+        }
     } );
 }