1. TypeScript Handbook 2. Table of Contents 3. The TypeScript Handbook 4. Basic Types 5. Interfaces 6. Functions 7. Literal Types 8. Unions and Intersection Types 9. Classes 10. Enums 11. Generics This copy of the TypeScript handbook was generated on Friday, June 26, 2020 against commit 10ecd4 with TypeScript 3.9. The TypeScript Handbook About this Handbook Over 20 years after its introduction to the programming community, JavaScript is now one of the most widespread cross-platform languages ever created. Starting as a small scripting language for adding trivial interactivity to webpages, JavaScript has grown to be a language of choice for both frontend and backend applications of every size. While the size, scope, and complexity of programs written in JavaScript has grown exponentially, the ability of the JavaScript language to express the relationships between different units of code has not. Combined with JavaScript's rather peculiar runtime semantics, this mismatch between language and program complexity has made JavaScript development a difficult task to manage at scale. The most common kinds of errors that programmers write can be described as type errors: a certain kind of value was used where a different kind of value was expected. This could be due to simple typos, a failure to understand the API surface of a library, incorrect assumptions about runtime behavior, or other errors. The goal of TypeScript is to be a static typechecker for JavaScript programs - in other words, a tool that runs before your code runs (static) and ensure that the types of the program are correct (typechecked). If you are coming to TypeScript without a JavaScript background, with the intention of TypeScript being your first language, we recommend you first start reading the documentation on JavaScript at the Mozilla Web Docs. If you have experience in other languages, you should be able to pick up JavaScript syntax quite quickly by reading the handbook. How is this Handbook Structured The handbook is split into two sections: The Handbook The TypeScript Handbook is intended to be a comprehensive document that explains TypeScript to everyday programmers. You can read the handbook by going from top to bottom in the left-hand navigation. You should expect each chapter or page to provide you with a strong understanding of the given concepts. The TypeScript Handbook is not a complete language specification, but it is intended to be a comprehensive guide to all of the language's features and behaviors. A reader who completes the walkthrough should be able to: Read and understand commonly-used TypeScript syntax and patterns Explain the effects of important compiler options Correctly predict type system behavior in most cases Write a .d.ts declaration for a simple function, object, or class In the interests of clarity and brevity, the main content of the Handbook will not explore every edge case or minutiae of the features being covered. You can find more details on particular concepts in the reference articles. The Handbook Reference The handbook reference is built to provide a richer understanding of how a particular part of TypeScript works. You can read it top-to-bottom, but each section aims to provide a deeper explanation of a single concept - meaning there is no aim for continuity. Non-Goals Non-Goals The Handbook is also intended to be a concise document that can be comfortably read in a few hours. Certain topics won't be covered in order to keep things short. Specifically, the Handbook does not fully introduce core JavaScript basics like functions, classes, and closures. Where appropriate, we'll include links to background reading that you can use to read up on those concepts. The Handbook also isn't intended to be a replacement for a language specification. In some cases, edge cases or formal descriptions of behavior will be skipped in favor of high-level, easier-to-understand explanations. Instead, there are separate reference pages that more precisely and formally describe many aspects of TypeScript's behavior. The reference pages are not intended for readers unfamiliar with TypeScript, so they may use advanced terminology or reference topics you haven't read about yet. Finally, the Handbook won't cover how TypeScript interacts with other tools, except where necessary. Topics like how to configure TypeScript with webpack, rollup, parcel, react, babel, closure, lerna, rush, bazel, preact, vue, angular, svelte, jquery, yarn, or npm are out of scope - you can find these resources elsewhere on the web. Get Started Before getting started with Basic Types, we recommend reading one of the following introductory pages. These introductions are intended to highlight key similarities and differences between TypeScript and your favored programming language, and clear up common misconceptions specific to those languages. TypeScript for New Programmers TypeScript for JavaScript Programmers TypeScript for OOP Programmers TypeScript for Functional Programmers Basic Types Introduction For programs to be useful, we need to be able to work with some of the simplest units of data: numbers, strings, structures, boolean values, and the like. In TypeScript, we support much the same types as you would expect in JavaScript, with a convenient enumeration type thrown in to help things along. Boolean The most basic datatype is the simple true/false value, which JavaScript and TypeScript call a boolean value. let isDone: boolean = false; Number As in JavaScript, all numbers in TypeScript are either floating point values or BigIntegers. These floating point numbers get the type number, while BigIntegers get the type bigint. In addition to hexadecimal and decimal literals, TypeScript also supports binary and octal literals introduced in ECMAScript 2015. let decimal: number = 6; let hex: number = 0xf00d; let binary: number = 0b1010; let octal: number = 0o744; let big: bigint = 100n; String Another fundamental part of creating programs in JavaScript for webpages and servers alike is working with textual data. As in other languages, we use the type string to refer to these textual datatypes. Just like JavaScript, TypeScript also uses double quotes (") or single quotes (') to surround string data. let color: string = "blue"; color = "red"; You can also use template strings, which can span multiple lines and have embedded expressions. These strings are surrounded by the backtick/backquote (`) character, and embedded expressions are of the form ${ expr }. let fullName: string = `Bob Bobbington`; let age: number = 37; let sentence: string = `Hello, my name is ${fullName}. I'll be ${age + 1} years old next month.`; This is equivalent to declaring sentence like so: let sentence: string = "Hello, my name is " + fullName + ".\n\n" + "I'll be " + (age + 1) + " years old next month."; Array TypeScript, like JavaScript, allows you to work with arrays of values. Array types can be written in one of two ways. In the first, you use the type of the elements followed by [] to denote an array of that element type: let list: number[] = [1, 2, 3]; The second way uses a generic array type, Array<elemType>: let list: Array<number> = [1, 2, 3]; Tuple Tuple types allow you to express an array with a fixed number of elements whose types are known, but need not be the same. For example, you may want to represent a value as a pair of a string and a number: // Declare a tuple type let x: [string, number]; // Initialize it x = ["hello", 10]; // OK // Initialize it incorrectly x = [10, "hello"]; // Error Type 'number' is not assignable to type 'string'. Type 'string' is not assignable to type 'number'. When accessing an element with a known index, the correct type is retrieved: console.log(x[0].substring(1)); // OK console.log(x[1].substring(1)); // Error, 'number' does not have 'substring' Property 'substring' does not exist on type 'number'. Accessing an element outside the set of known indices fails with an error: x[3] = "world"; // Error, Property '3' does not exist on type '[string, number]'. Tuple type '[string, number]' of length '2' has no element at index '3'. console.log(x[5].toString()); // Error, Property '5' does not exist on type '[string, number]'. Object is possibly 'undefined'. Tuple type '[string, number]' of length '2' has no element at index '5'. Enum A helpful addition to the standard set of datatypes from JavaScript is the enum. As in languages like C#, an enum is a way of giving more friendly names to sets of numeric values. enum Color { Red, Green, Blue, } let c: Color = Color.Green; By default, enums begin numbering their members starting at 0. You can change this by manually setting the value of one of its members. For example, we can start the previous example at 1 instead of 0: enum Color { Red = 1, Green, Blue, } let c: Color = Color.Green; Or, even manually set all the values in the enum: enum Color { Red = 1, Green = 2, Blue = 4, } let c: Color = Color.Green; A handy feature of enums is that you can also go from a numeric value to the name of that value in the enum. For example, if we had the value 2 but weren't sure what that mapped to in the Color enum above, we could look up the corresponding name: enum Color { Red = 1, Green, Blue, } let colorName: string = Color[2]; console.log(colorName); // Displays 'Green' as its value is 2 above Any We may need to describe the type of variables that we do not know when we are writing an application. These values may come from dynamic content, e.g. from the user or a 3rd party library. In these cases, we want to opt-out of type checking and let the values pass through compile-time checks. To do so, we label these with the any type: let notSure: any = 4; notSure = "maybe a string instead"; notSure = false; // okay, definitely a boolean The any type is a powerful way to work with existing JavaScript, allowing you to gradually opt-in and opt-out of type checking during compilation.