Refactor response() handling to enable returning arbitrary data

Fix tests borken by previous changes
Update readme

.github/workflows/build.yml

@@ -41,6 +41,14 @@ jobs:
     - name: Install
       run: npm install
 
+    - name: Link (npm < 7)
+      if: matrix.node-version == '14.x'
+      run: |
+        cd plugins/s3
+        npm link
+        cd ../../
+        npm link @aws-lite/s3
+
     - name: Test
       run: npm test
       env:

readme.md

@@ -174,7 +174,7 @@ The following parameters may be passed with individual client requests; only `se
   - By default, all headers are included in [authentication via AWS signature v4](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html)
 - **`payload` (object, buffer, readable stream, string)**
   - Aliases: `body`, `data`, `json`
-  - As a convenience, any passed objects are automatically JSON-encoded (with the appropriate `content-type` header set, if not already present); buffers and strings simply pass through as is
+  - As a convenience, any passed objects are automatically JSON-encoded (with the appropriate `content-type` header set, if not already present); buffers and strings simply pass through as-is
   - Passing a Node.js readable stream is currently experimental; this initiates an HTTP data stream to the API endpoint instead of writing a normal HTTP body payload
 - **`query` (object)**
   - Serialize the passed object and append it to your `endpoint` as a query string in your request
@@ -343,7 +343,7 @@ The `response()` lifecycle hook is an async function that enables mutation of se
 
 `response()` is executed with two positional arguments:
 
-- **`params` (object)**
+- **`response` (object)**
   - An object containing three properties from the API response:
     - **`statusCode` (number)**
       - HTTP response status code
@@ -354,7 +354,11 @@ The `response()` lifecycle hook is an async function that enables mutation of se
 - **`utils` (object)**
   - [Plugin helper utilities](#plugin-utils)
 
-The `response()` method may return nothing, or it may return an object containing the following optional properties: `statusCode` (number), `headers` (object), `payload` (object or string), and `awsjson` (that behaves the same as in [client requests](#client-requests)). An example:
+The `response()` method may return: nothing (which will pass through the `response` object as-is), a mutated version of the `response` object, or any other data type (most commonly an object or string).
+
+Should you return an object, you may also include an `awsjson` property (that behaves the same as in [client requests](#client-requests)). The `awsjson` property will be stripped from any returned response.
+
+An example:
 
 ```js
 // Automatically deserialize AWS-flavored JSON

src/client-factory.js

@@ -152,16 +152,16 @@ module.exports = async function clientFactory (config, creds, region) {
                 catch (methodError) {
                   errorHandler({ error: methodError, metadata })
                 }
-                if (pluginRes) {
-                  let { statusCode, headers, payload } = pluginRes
-                  if (pluginRes.awsjson) {
-                    payload = awsjson.unmarshall(payload, pluginRes.awsjson)
-                  }
-                  response = {
-                    statusCode: statusCode || response.statusCode,
-                    headers: headers || response.headers,
-                    payload: payload || response.payload,
+                if (pluginRes !== undefined) {
+                  let unmarshalling = pluginRes.awsjson
+                  if (unmarshalling) {
+                    delete pluginRes.awsjson
+                    // If a payload property isn't included, it _is_ the payload
+                    let payload = pluginRes.payload || pluginRes
+                    let unmarshalled = awsjson.unmarshall(payload, unmarshalling)
+                    response = { ...pluginRes, ...unmarshalled }
                   }
+                  else response = pluginRes
                 }
               }
               return response

test/live/_iam.mjs

@@ -12,6 +12,7 @@ export default {
           }
         }
       },
+      response: async ({ payload }) => payload,
     },
     CreateRole: {
       request: async function ({ name, policyDoc, desc, path }) {
@@ -26,6 +27,7 @@ export default {
           }
         }
       },
+      response: async ({ payload }) => payload,
     }
   }
 }

test/live/_lambda.js

@@ -22,6 +22,7 @@ module.exports = {
           endpoint: `/2015-03-31/functions/${name}/configuration`
         }
       },
+      response: async ({ payload }) => payload,
     },
 
     // https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html
@@ -35,6 +36,7 @@ module.exports = {
           endpoint: `/2015-03-31/functions/${name}/invocations`
         }
       },
+      response: async ({ payload }) => payload,
     },
   }
 }