feat(clients): support util functions to consume response streams

[AllanZhengYP]

Issue

Associated to smithy-lang/smithy-typescript#571
Resolves: #1877

Description

Now if the deserialized object has streaming blob member(SSDK's input or SDK's output), customers can tranform the stream into string by

const body = response.Body;
const str = await body.transformToString("utf-8");

Or get the binary data by:

const binaryData: Uint8Array = await resp.Body.transformToByteArray();
// using buffer
const buf: Buffer = Buffer.from(await resp.Body.transformToByteArray());

Or transform to runtime-agnostic WebStream by:

// browsers and Node.js 16.5+
const webstream: ReadableStream = resp.Body.transformToWebStream();
const data = await webstream.json();
const buf = await webstream.arrayBuffer();

The output stream payload's interface is still assignable to the stream payload shape in the input, so this will work:

  new PutObjectCommand({ Body: bucket1Response.Body, Bucket: "Bucket2" });

At the same time, the payload stream is still an instance of the runtime-specific stream implementation, i.e. Stream.Readable in Node.js, ReadableStream in browsers and Blob in React Native. So the code like below will still work:

if (resp.Body instance of ReadableStream) {
  // Handle web stream
}

Note: since the streaming data can only be read once, and simplify the concurrency model, any of the transform methods to the stream can only be called once.

Testing

Unit test;
Integration test(PR to follow up)

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[kuhe]

continued in #3977

[github-actions]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs and link to relevant comments in this thread.