Add bound parameters to Service objects

You can now create service objects with a `params` hash that
contains top level parameters bound to all subsequent operation calls.
For example, to operate on an S3 object, you can use:

    var s3obj = new AWS.S3({Bucket: 'bucket', Key: 'key'});

    // no bound params passed to put or get calls
    s3obj.putObject({Body: 'text'}, function() {
      s3obj.getObject(function(err, data) {
        console.log("Got the data back", data.Body.toString());
      });
    });

Note that only toplevel parameters can be bound. These parameters
will also be automatically ignored for operations that do not use
these parameters. For example, we can still use the `s3obj` variable
to call `listObjects()`, even though that operation does not accept
a `Key` parameter:

    s3obj.listObjects(function(err, data) {
      console.log("Objects in my bucket", data);
    });

README.md

@@ -39,11 +39,11 @@ AWS.config.loadFromPath('./path/to/credentials.json');
 // Set your region for future requests.
 AWS.config.update({region: 'us-east-1'});
 
-// Create a bucket and put something in it.
-var s3 = new AWS.S3();
-s3.createBucket({Bucket: 'myBucket'}, function() {
-  var data = {Bucket: 'myBucket', Key: 'myKey', Body: 'Hello!'};
-  s3.putObject(data, function(err, data) {
+// Create a bucket using bound parameters and put something in it.
+var s3bucket = new AWS.S3({params: {Bucket: 'myBucket'}});
+s3bucket.createBucket(function() {
+  var data = {Key: 'myKey', Body: 'Hello!'};
+  s3bucket.putObject(data, function(err, data) {
     if (err) {
       console.log("Error uploading data: ", err);
     } else {

doc-src/guide/Examples.md

@@ -35,10 +35,9 @@ The following example puts the string 'Hello!' inside the
 object 'myKey' of bucket 'myBucket':
 
 ```js
-var s3 = new AWS.S3();
-s3.createBucket({Bucket: 'myBucket'}, function() {
-  var data = {Bucket: 'myBucket', Key: 'myKey', Body: 'Hello!'};
-  s3.putObject(data, function() {
+var s3 = new AWS.S3({params: {Bucket: 'myBucket', Key: 'myKey'}});
+s3.createBucket(function() {
+  s3.putObject({Body: 'Hello!'}, function() {
     console.log("Successfully uploaded data to myBucket/myKey");
   });
 });

lib/service.js

@@ -93,7 +93,22 @@ AWS.Service = inherit({
   makeRequest: function makeRequest(operation, params, callback) {
     if (typeof params === 'function') {
       callback = params;
-      params = {};
+      params = null;
+    }
+
+    params = params || {};
+    if (this.config.params) { // copy only toplevel bound params
+      var rules = this.api.operations[operation];
+      if (rules) {
+        params = AWS.util.copy(params);
+        AWS.util.each(this.config.params, function(key, value) {
+          if (rules.input.members[key]) {
+            if (params[key] === undefined || params[key] === null) {
+              params[key] = value;
+            }
+          }
+        });
+      }
     }
 
     var request =  new AWS.Request(this, operation, params);

test/service.spec.coffee

@@ -176,6 +176,24 @@ describe 'AWS.Service', ->
       AWS.EventListeners.Core.removeListener 'validate',
         AWS.EventListeners.Core.VALIDATE_PARAMETERS
 
+      describe 'bound parameters', ->
+        it 'accepts toplevel bound parameters on the service', ->
+          service = new AWS.S3(params: {Bucket: 'bucket', Key: 'key'})
+          req = service.makeRequest 'getObject'
+          expect(req.params).toEqual(Bucket: 'bucket', Key: 'key')
+
+        it 'ignores bound parameters not in input members', ->
+          service = new AWS.S3(params: {Bucket: 'bucket', Key: 'key'})
+          req = service.makeRequest 'listObjects'
+          expect(req.params).toEqual(Bucket: 'bucket')
+
+        it 'can override bound parameters', ->
+          service = new AWS.S3(params: {Bucket: 'bucket', Key: 'key'})
+          params = Bucket: 'notBucket'
+
+          req = service.makeRequest('listObjects', params)
+          expect(params).not.toBe(req.params)
+          expect(req.params).toEqual(Bucket: 'notBucket')
 
     describe 'global events', ->
       it 'adds AWS.events listeners to requests', ->