First-class TypeScript support in modular AWS SDK for JavaScript

As of December 15th, 2020, the AWS SDK for JavaScript, version 3 (v3) is generally available.

On October 19th, 2020, we published the Release Candidate (RC) of the AWS SDK for JavaScript, version 3 (v3). One of the major changes in v3 is first-class TypeScript support. In this blog post we will discuss why we decided to use TypeScript for building version 3 of JavaScript SDK and provide examples of how TypeScript helps development and debugging.

Motivation

The version 2 of the SDK is written in vanilla JavaScript. The type definition files were added in late 2016, when AWS SDK customers requested support after Angular 2 started recommending TypeScript as a primary language for application development. The internal components of the SDK are still written in vanilla JavaScript, and type definitions can go out of date.

TypeScript popularity

Over the years, the TypeScript programming language exploded in popularity. TypeScript extends JavaScript by adding types, and saves you time catching errors and providing fixes before you run your code. The following image shows Google Trends 2012-2020 for TypeScript.

In GitHub’s annual survey Octoverse, TypeScript entered top languages at #10 in 2017, and jumped to #7 in 2018 and #4 in 2020. This is in addition to vanilla JavaScript occupying the top language spot since the survey began in 2014.

TypeScript is also the second most loved programming language behind Rust in StackOverflow survey, and the most popular JavaScript flavor as per the State of JavaScript survey. TypeScript has climbed rankings in other surveys like Redmonk and TIOBE index.

Increased TypeScript adoption in JavaScript projects

Angular is written in TypeScript since version 2.0, and it recommends TypeScript as a primary language for application development. Vue.js is another popular JavaScript frontend framework, and Vue 3 is written in TypeScript. The Create React App tool of React also added TypeScript support in v2.1.0. Yarn is one of the popular package managers for JavaScript, and they switched to TypeScript in yarn 2.

TypeScript is popular among companies owning large JavaScript codebases, including Slack, Airbnb, and Bloomberg. Microsoft’s popular open-source cross-platform code editor Visual Studio Code is written in TypeScript as well.

Benefits of using TypeScript in the SDK

Static type definitions

JavaScript is a dynamically typed language, which means that the types are checked and datatype errors are spotted only at the runtime. TypeScript introduces optional static type definitions. Once declared, a variable can’t change its type and can take only certain values. The compiler alerts developers to type-related mistakes, resulting in less error-prone code in production.

As per the research study on Quantifying Detectable Bugs in JavaScript from 2017, the type definitions detect around 15% of bugs in the code. When Airbnb adopted TypeScript, they found that 38% of bugs could have been prevented by TypeScript in their postmortem analysis.

Static type definitions also give the code more structure, make it self-documenting, and speed up readability, debugging and refactoring. It is not a magic pill though when it comes to reducing bug density. We still need to use other quality control measures – like design review, spec review, code review, using a linter and writing tests – in addition to static types.

IDE Support (Intellisense)

Thanks to the static type definitions, the IDEs are able to provide variety of code editing features like code completion and parameter info. In one of the popular code editors Visual Studio Code, this is known as Intellisense.

In the following screenshot, Intellisense in Visual Studio Code provides details for region configuration parameter while creating DynamoDB client. It specifies that region is optional, its value can be a string or a Provider<string>, and it stores the AWS region to which the client will send requests.

Equivalent example in TypeScript using imports:

Although we highly recommend our customers to use TypeScript in their code, it’s optional. The Intellisense features will work even if you’re writing your code in JavaScript. The code in the screenshot is JavaScript code.

Latest ECMAScript features

As maintainers of the SDK, we get to use the latest and greatest features of the ECMAScript specification supported by TypeScript but still target the published artifacts to use the version supported by runtime.

At the time of writing in December 2020, the SDK is using the latest stable version of TypeScript 4.1.2 and our Node.js artifacts are targeting ES2018. Thanks to TypeScript we’re already using ES2020 features in our codebase like Nullish Coalescing and Optional chaining, and TypeScript compiles them to ES2018 for us.

For example, here is the code to select retryDecider in retry middleware which uses both optional chaining and nullish coalescing:

this.retryDecider = options?.retryDecider ?? defaultRetryDecider;

TypeScript compiles it to the following in ES2018 so that it can run in Node.js 10.x:

this.retryDecider =
  (_a = options === null || options === void 0 ? void 0 : options.retryDecider) !== null && _a !== void 0
    ? _a
    : retryDecider_1.defaultRetryDecider;

When we need to drop support for Node.js 10.x in future, we can just update TypeScript configuration to target ES2019. The code doesn’t need to be updated. Similarly, when ES2021 features will get supported in future versions of TypeScript, we can start using them while still compiling code to ES2018 for supporting Node.js 10.x.

Documentation

In version 2, we use yard documentation tool for generating API reference. Yard was originally written for Ruby Programming Language, but was adopted for JavaScript. In version 3, since we use TSDoc with TypeScript the types in the documentation are tightly coupled with the codebase. When the types change in the code, an independent change of the comment is not required which would have been necessary if JSDoc was used.

We also use TypeDoc documentation generator which is extensible and supports a variety of configurations.

Feedback

We value your feedback, so please tell us what you like and don’t like by opening an issue on GitHub.