From 7434604a0c7b17d95daf5f4f0cecf9ce666e8422 Mon Sep 17 00:00:00 2001
From: George Fu <kuhe@users.noreply.github.com>
Date: Thu, 13 Oct 2022 11:05:55 -0400
Subject: [PATCH] docs(streams): add readme section about stream mixins (#4036)

Co-authored-by: Trivikram Kamat <16024985+trivikr@users.noreply.github.com>
---
 README.md                   | 42 ++++++++++++++++++++++++++++++++++++-
 packages/types/src/serde.ts |  9 ++++----
 2 files changed, 45 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 1f9a1b09f2d2..123ef10104c8 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,6 @@
 ![Build Status](https://codebuild.us-west-2.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiMmtFajZWQmNUbEhidnBKN1VncjRrNVI3d0JUcFpGWUd3STh4T3N3Rnljc1BMaEIrYm9HU2t4YTV1RlE1YmlnUG9XM3luY0Ftc2tBc0xTeVFJMkVOa24wPSIsIml2UGFyYW1ldGVyU3BlYyI6IlBDMDl6UEROK1dlU1h1OWciLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=main)
 [![codecov](https://codecov.io/gh/aws/aws-sdk-js-v3/branch/main/graph/badge.svg)](https://codecov.io/gh/aws/aws-sdk-js-v3)
 [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
-[![Dependabot Status](https://api.dependabot.com/badges/status?host=github&repo=aws/aws-sdk-js-v3)](https://dependabot.com)
 
 The **AWS SDK for JavaScript v3** is a rewrite of v2 with some great new features.
 As with version 2, it enables you to easily work with [Amazon Web Services](https://aws.amazon.com/),
@@ -37,6 +36,7 @@ visit our [code samples repo](https://github.com/aws-samples/aws-sdk-js-tests).
    1. [How to upgrade](#other-changes)
 1. [High Level Concepts in V3](#high-level-concepts)
    1. [Generated Packages](#generated-code)
+   1. [Streams](#streams)
    1. [Paginators](#paginators)
    1. [Abort Controller](#abort-controller)
    1. [Middleware Stack](#middleware-stack)
@@ -282,6 +282,46 @@ Lastly we have higher level libraries in `/lib`. These are javascript specific l
 1. `/clients`. This sub directory is code generated and depends on code published from `/packages` . It is 1:1 with AWS services and operations. Manual edits should generally not occur here. These are published to NPM under `@aws-sdk/client-XXXX`.
 1. `/lib`. This sub directory depends on generated code published from `/clients`. It wraps existing AWS services and operations to make them easier to work with in Javascript. These are published to NPM under `@aws-sdk/lib-XXXX`
 
+### Streams
+
+Certain command outputs include streams, which have different implementations in
+Node.js and browsers. For convenience, a set of stream handling methods will be
+merged (`Object.assign`) to the output stream object, as defined in 
+[SdkStreamMixin](serde-code-url).
+
+Output types having this feature will be indicated by the `WithSdkStreamMixin<T, StreamKey>`
+[wrapper type](serde-code-url), where `T` is the original output type
+and `StreamKey` is the output property key having a stream type specific to 
+the runtime environment.
+
+[serde-code-url]: https://github.com/aws/aws-sdk-js-v3/blob/main/packages/types/src/serde.ts
+
+Here is an example using `S3::GetObject`. 
+
+```js
+import { S3 } from "@aws-sdk/client-s3";
+
+const client = new S3({});
+
+const getObjectResult = await client.getObject({
+  Bucket: "...",
+  Key: "...",
+});
+
+// env-specific stream with added mixin methods.
+const bodyStream = getObjectResult.Body; 
+
+// one-time transform.
+const bodyAsString = await bodyStream.transformToString();
+
+// throws an error on 2nd call, stream cannot be rewound.
+const __error__ = await bodyStream.transformToString();
+```
+
+Note that these methods will read the stream in order to collect it,
+so **you must save the output**. The methods cannot be called more than once
+on a stream.
+
 ### Paginators
 
 Many AWS operations return paginated results when the response object is too large to return in a single response. In AWS SDK for JavaScript v2, the response contains a token you can use to retrieve the next page of results. You then need to write additional functions to process pages of results.
diff --git a/packages/types/src/serde.ts b/packages/types/src/serde.ts
index 2455739e47ff..a303bd56ab41 100644
--- a/packages/types/src/serde.ts
+++ b/packages/types/src/serde.ts
@@ -88,12 +88,12 @@ export type SdkStream<BaseStream> = BaseStream & SdkStreamMixin;
 
 /**
  * Indicates that any members of type T
- * that were of type BaseStream have been extended
+ * that were of type T[StreamKey] have been extended
  * with the SdkStreamMixin helper methods.
  */
-export type WithSdkStreamMixin<T, BaseStream> = {
-  [key in keyof T]: T[key] extends BaseStream ? SdkStream<BaseStream> : T[key]
-}
+export type WithSdkStreamMixin<T, StreamKey extends keyof T> = {
+  [key in keyof T]: T[key] extends T[StreamKey] ? SdkStream<T[StreamKey]> : T[key];
+};
 
 /**
  * Interface for internal function to inject stream utility functions
@@ -111,4 +111,3 @@ export interface SdkStreamMixinInjector {
 export interface SdkStreamSerdeContext {
   sdkStreamMixin: SdkStreamMixinInjector;
 }
-