Skip to content

docs: create supplemental doc for typescript remarks #5998

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 15, 2024
Merged

docs: create supplemental doc for typescript remarks #5998

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions supplemental-docs/TYPESCRIPT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# TypeScript

The AWS SDK for JavaScript v3 is written in TypeScript. This allows easier generation of [API documentation](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/), and provides type hints and autocompletion to code editors, whether you are
using JavaScript or TypeScript.

### Minimum supported TypeScript version

The SDK does not have an official minimum supported TypeScript version. We recommend using a recent version of TypeScript.
The current version of TypeScript used in development of the AWS SDK can be seen in the root `package.json` file.

## Common TypeScript-related questions in the AWS SDK for JavaScript (v3)

#### Why are operation request and response structures unions with `| undefined`?

This allows more flexibility when it comes to AWS service APIs changing over time without needing to update your SDK client version, and encourages defensive checking of API responses.
If you acknowledge the risks of not runtime-checking response object structures and would like to skip that, there is a `@smithy/types` type transform that can be applied to AWS SDK clients.

For usage, see https://github.com/smithy-lang/smithy-typescript/tree/main/packages/types#scenario-removing--undefined-from-input-and-output-structures.

#### Why are streaming output values a union type?

The AWS SDK clients accept an optional runtime-provided value for `requestHandler` (see [requestHandler](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/CLIENTS.md#request-handler-requesthandler)).
Because the implementation of the requestHandler varies both by platform (`node:https`-based for Node.js and `fetch`-based for browsers) and by service, and
due to constraints from historical design decisions, the streaming response implementation is not precisely known at compile time.

The type union describes why each member of the union exists ([source code](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/CLIENTS.md#request-handler-requesthandler) comments).

If you would like to narrow the type of streaming responses, for example for AWS S3 getObject, there is another type transform that can be applied to clients, with instructions at
`@smithy/types` https://github.com/smithy-lang/smithy-typescript/tree/main/packages/types#scenario-narrowing-a-smithy-typescript-generated-clients-output-payload-blob-types.