feat: Introduce an optional escape hatch for listAllObjects

There are cases where we might want to page through the list of objects available
on S3 but we don't need to keep going once we've found what we are looking for.
This commit updates `listAllObjects` to accept an `until` argument - if this
is provided then when a new page of results is loaded we check if `some` of them
match the `until` - if so we don't bother loading another page.

A concrete use-case for this is in #120 - sometimes we just want to
find the currently active revision so we only need to loop through the "pages"
on S3 until we do.

Author: Kelvin Luck

lib/s3.js

@@ -174,7 +174,7 @@ module.exports = CoreObject.extend({
     });
   },
 
-  listAllObjects: function(options) {
+  listAllObjects: function(options, until) {
     var client         = this._client;
     var listObjects    = RSVP.denodeify(client.listObjects.bind(client));
     var allRevisions   = [];
@@ -183,13 +183,14 @@ module.exports = CoreObject.extend({
       return listObjects(options).then(function(response) {
         [].push.apply(allRevisions, response.Contents);
 
-        if (response.IsTruncated) {
-          var nextMarker = response.Contents[response.Contents.length - 1].Key;
-          options.Marker = nextMarker;
-          return listObjectRecursively(options);
-        } else {
+        var isComplete = !response.IsTruncated || (until && response.Contents.some(until));
+
+        if (isComplete) {
           return allRevisions;
         }
+        var nextMarker = response.Contents[response.Contents.length - 1].Key;
+        options.Marker = nextMarker;
+        return listObjectRecursively(options);
       });
     }