From df2fc78ccb3e98c33c040f2969c0b00b88bc9b2f Mon Sep 17 00:00:00 2001 From: George Fu Date: Wed, 12 Oct 2022 19:28:38 +0000 Subject: [PATCH 1/5] docs(streams): add readme section about stream mixins --- README.md | 35 ++++++++++++++++++++++++++++++++++- packages/types/src/serde.ts | 9 ++++----- 2 files changed, 38 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 1f9a1b09f2d2..e39d5b7dc08d 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,39 @@ 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 NodeJS and browsers. For convenience, a set of stream handling methods will be merged (`Object.assign`) to the output stream object, as defined in [SdkStreamMixin](https://github.com/aws/aws-sdk-js-v3/blob/ad99b66944b6fe1ce83082c1a33193dff033cfaf/packages/types/src/serde.ts#L77-L81). + +Output types having this feature will be indicated by the `WithSdkStreamMixin` [wrapper type](https://github.com/aws/aws-sdk-js-v3/blob/ad99b66944b6fe1ce83082c1a33193dff033cfaf/packages/types/src/serde.ts#L89-L96), where `T` is the original output type and `BaseStream` is +the stream type specific to the runtime environment. + +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 & 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 = { - [key in keyof T]: T[key] extends BaseStream ? SdkStream : T[key] -} +export type WithSdkStreamMixin = { + [key in keyof T]: T[key] extends T[StreamKey] ? SdkStream : T[key]; +}; /** * Interface for internal function to inject stream utility functions @@ -111,4 +111,3 @@ export interface SdkStreamMixinInjector { export interface SdkStreamSerdeContext { sdkStreamMixin: SdkStreamMixinInjector; } - From eff1b55cf10dc6349ffcac1ecaa748c97a99e7ed Mon Sep 17 00:00:00 2001 From: George Fu Date: Wed, 12 Oct 2022 16:44:14 -0400 Subject: [PATCH 2/5] Update README.md Co-authored-by: Trivikram Kamat <16024985+trivikr@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e39d5b7dc08d..1000359669f6 100644 --- a/README.md +++ b/README.md @@ -284,7 +284,7 @@ Lastly we have higher level libraries in `/lib`. These are javascript specific l ### Streams -Certain command outputs include streams, which have different implementations in NodeJS and browsers. For convenience, a set of stream handling methods will be merged (`Object.assign`) to the output stream object, as defined in [SdkStreamMixin](https://github.com/aws/aws-sdk-js-v3/blob/ad99b66944b6fe1ce83082c1a33193dff033cfaf/packages/types/src/serde.ts#L77-L81). +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](https://github.com/aws/aws-sdk-js-v3/blob/ad99b66944b6fe1ce83082c1a33193dff033cfaf/packages/types/src/serde.ts#L77-L81). Output types having this feature will be indicated by the `WithSdkStreamMixin` [wrapper type](https://github.com/aws/aws-sdk-js-v3/blob/ad99b66944b6fe1ce83082c1a33193dff033cfaf/packages/types/src/serde.ts#L89-L96), where `T` is the original output type and `BaseStream` is the stream type specific to the runtime environment. From c4bd29692a0ed9386b3faa1b44937184d03bfa66 Mon Sep 17 00:00:00 2001 From: George Fu Date: Wed, 12 Oct 2022 16:44:45 -0400 Subject: [PATCH 3/5] Update README.md Co-authored-by: Trivikram Kamat <16024985+trivikr@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1000359669f6..17df9bcc0bb3 100644 --- a/README.md +++ b/README.md @@ -297,7 +297,7 @@ import { S3 } from "@aws-sdk/client-s3"; const client = new S3({}); const getObjectResult = await client.getObject({ - Bucket: '...', + Bucket: "...", Key: "...", }); From 38e81dd9b018c721b9e304385496dc790a9fdc33 Mon Sep 17 00:00:00 2001 From: George Fu Date: Wed, 12 Oct 2022 20:47:07 +0000 Subject: [PATCH 4/5] docs(streams): add newlines --- README.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 17df9bcc0bb3..798eb07811ec 100644 --- a/README.md +++ b/README.md @@ -284,10 +284,15 @@ Lastly we have higher level libraries in `/lib`. These are javascript specific l ### 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](https://github.com/aws/aws-sdk-js-v3/blob/ad99b66944b6fe1ce83082c1a33193dff033cfaf/packages/types/src/serde.ts#L77-L81). - -Output types having this feature will be indicated by the `WithSdkStreamMixin` [wrapper type](https://github.com/aws/aws-sdk-js-v3/blob/ad99b66944b6fe1ce83082c1a33193dff033cfaf/packages/types/src/serde.ts#L89-L96), where `T` is the original output type and `BaseStream` is -the stream type specific to the runtime environment. +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](https://github.com/aws/aws-sdk-js-v3/blob/ad99b66944b6fe1ce83082c1a33193dff033cfaf/packages/types/src/serde.ts#L77-L81). + +Output types having this feature will be indicated by the `WithSdkStreamMixin` +[wrapper type](https://github.com/aws/aws-sdk-js-v3/blob/ad99b66944b6fe1ce83082c1a33193dff033cfaf/packages/types/src/serde.ts#L89-L96), +where `T` is the original output type and `BaseStream` isthe stream type +specific to the runtime environment. Here is an example using `S3::GetObject`. From fa5f81de8de08ca4a1dce9fa20377dfd02879779 Mon Sep 17 00:00:00 2001 From: George Fu Date: Thu, 13 Oct 2022 02:57:22 +0000 Subject: [PATCH 5/5] docs(streams): update streaming mixin docs --- README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 798eb07811ec..123ef10104c8 100644 --- a/README.md +++ b/README.md @@ -287,12 +287,14 @@ Lastly we have higher level libraries in `/lib`. These are javascript specific l 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](https://github.com/aws/aws-sdk-js-v3/blob/ad99b66944b6fe1ce83082c1a33193dff033cfaf/packages/types/src/serde.ts#L77-L81). +[SdkStreamMixin](serde-code-url). -Output types having this feature will be indicated by the `WithSdkStreamMixin` -[wrapper type](https://github.com/aws/aws-sdk-js-v3/blob/ad99b66944b6fe1ce83082c1a33193dff033cfaf/packages/types/src/serde.ts#L89-L96), -where `T` is the original output type and `BaseStream` isthe stream type -specific to the runtime environment. +Output types having this feature will be indicated by the `WithSdkStreamMixin` +[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`.