![\"cfa\"](\"https://cloud.githubusercontent.com/assets/8052307/5210657/c5ae0f28-7585-11e4-97d8-86169ef2a160.gif\")
This overview page is a summary contains a shorter version of all the release notes for TypeScript.
\nThis feature is something most users may never have to think about; however, if you’ve hit issues under --isolatedModules, TypeScript’s transpileModule API, or Babel, this feature might be relevant.
TypeScript 3.8 adds a new syntax for type-only imports and exports.
\n\ntsimport type { SomeThing } from \"./some-module.js\";\n\nexport type { SomeThing };
import type only imports declarations to be used for type annotations and declarations.\nIt always gets fully erased, so there’s no remnant of it at runtime.\nSimilarly, export type only provides an export that can be used for type contexts, and is also erased from TypeScript’s output.
It’s important to note that classes have a value at runtime and a type at design-time, and the use is context-sensitive.\nWhen using import type to import a class, you can’t do things like extend from it.
\ntsimport type { Component } from \"react\";\n\ninterface ButtonProps {\n // ...\n}\n\nclass Button extends Component<ButtonProps> {\n // ~~~~~~~~~\n // error! 'Component' only refers to a type, but is being used as a value here.\n\n // ...\n}
If you’ve used Flow before, the syntax is fairly similar.\nOne difference is that we’ve added a few restrictions to avoid code that might appear ambiguous.
\n\nts// Is only 'Foo' a type? Or every declaration in the import?\n// We just give an error because it's not clear.\n\nimport type Foo, { Bar, Baz } from \"some-module\";\n// ~~~~~~~~~~~~~~~~~~~~~~\n// error! A type-only import can specify a default import or named bindings, but not both.
In conjunction with import type, TypeScript 3.8 also adds a new compiler flag to control what happens with imports that won’t be utilized at runtime: importsNotUsedAsValues.\nThis flag takes 3 different values:
remove: this is today’s behavior of dropping these imports. It’s going to continue to be the default, and is a non-breaking change.preserve: this preserves all imports whose values are never used. This can cause imports/side-effects to be preserved.error: this preserves all imports (the same as the preserve option), but will error when a value import is only used as a type. This might be useful if you want to ensure no values are being accidentally imported, but still make side-effect imports explicit.For more information about the feature, you can take a look at the pull request, and relevant changes around broadening where imports from an import type declaration can be used.
TypeScript 3.8 brings support for ECMAScript’s private fields, part of the stage-3 class fields proposal.
\n\ntsclass Person {\n #name: string\n\n constructor(name: string) {\n this.#name = name;\n }\n\n greet() {\n console.log(`Hello, my name is ${this.#name}!`);\n }\n}\n\nlet jeremy = new Person(\"Jeremy Bearimy\");\n\njeremy.#name\n// ~~~~~\n// Property '#name' is not accessible outside class 'Person'\n// because it has a private identifier.
Unlike regular properties (even ones declared with the private modifier), private fields have a few rules to keep in mind.\nSome of them are:
# character. Sometimes we call these private names.public or private can’t be used on private fields.Apart from “hard” privacy, another benefit of private fields is that uniqueness we just mentioned.\nFor example, regular property declarations are prone to being overwritten in subclasses.
\n\ntsclass C {\n foo = 10;\n\n cHelper() {\n return this.foo;\n }\n}\n\nclass D extends C {\n foo = 20;\n\n dHelper() {\n return this.foo;\n }\n}\n\nlet instance = new D();\n// 'this.foo' refers to the same property on each instance.\nconsole.log(instance.cHelper()); // prints '20'\nconsole.log(instance.dHelper()); // prints '20'
With private fields, you’ll never have to worry about this, since each field name is unique to the containing class.
\n\ntsclass C {\n #foo = 10;\n\n cHelper() {\n return this.#foo;\n }\n}\n\nclass D extends C {\n #foo = 20;\n\n dHelper() {\n return this.#foo;\n }\n}\n\nlet instance = new D();\n// 'this.#foo' refers to a different field within each class.\nconsole.log(instance.cHelper()); // prints '10'\nconsole.log(instance.dHelper()); // prints '20'
Another thing worth noting is that accessing a private field on any other type will result in a TypeError!
\ntsclass Square {\n #sideLength: number;\n\n constructor(sideLength: number) {\n this.#sideLength = sideLength;\n }\n\n equals(other: any) {\n return this.#sideLength === other.#sideLength;\n }\n}\n\nconst a = new Square(100);\nconst b = { sideLength: 100 };\n\n// Boom!\n// TypeError: attempted to get private field on non-instance\n// This fails because 'b' is not an instance of 'Square'.\nconsole.log(a.equals(b));
Finally, for any plain .js file users, private fields always have to be declared before they’re assigned to.
\njsclass C {\n // No declaration for '#foo'\n // :(\n\n constructor(foo: number) {\n // SyntaxError!\n // '#foo' needs to be declared before writing to it.\n this.#foo = foo;\n }\n}
JavaScript has always allowed users to access undeclared properties, whereas TypeScript has always required declarations for class properties.\nWith private fields, declarations are always needed regardless of whether we’re working in .js or .ts files.
\njsclass C {\n /** @type {number} */\n #foo;\n\n constructor(foo: number) {\n // This works.\n this.#foo = foo;\n }\n}
For more information about the implementation, you can check out the original pull request
\nWe’ve already received many questions on which type of privates you should use as a TypeScript user: most commonly, “should I use the private keyword, or ECMAScript’s hash/pound (#) private fields?”\nIt depends!
When it comes to properties, TypeScript’s private modifiers are fully erased - that means that at runtime, it acts entirely like a normal property and there’s no way to tell that it was declared with a private modifier. When using theprivate` keyword, privacy is only enforced at compile-time/design-time, and for JavaScript consumers it’s entirely intent-based.
\ntsclass C {\n private foo = 10;\n}\n\n// This is an error at compile time,\n// but when TypeScript outputs .js files,\n// it'll run fine and print '10'.\nconsole.log(new C().foo); // prints '10'\n// ~~~\n// error! Property 'foo' is private and only accessible within class 'C'.\n\n// TypeScript allows this at compile-time\n// as a \"work-around\" to avoid the error.\nconsole.log(new C()[\"foo\"]); // prints '10'
The upside is that this sort of “soft privacy” can help your consumers temporarily work around not having access to some API, and also works in any runtime.
\nOn the other hand, ECMAScript’s # privates are completely inaccessible outside of the class.
\ntsclass C {\n #foo = 10;\n}\n\nconsole.log(new C().#foo); // SyntaxError\n// ~~~~\n// TypeScript reports an error *and*\n// this won't work at runtime!\n\nconsole.log(new C()[\"#foo\"]); // prints undefined\n// ~~~~~~~~~~~~~~~\n// TypeScript reports an error under 'noImplicitAny',\n// and this prints 'undefined'.
This hard privacy is really useful for strictly ensuring that nobody can take use of any of your internals.\nIf you’re a library author, removing or renaming a private field should never cause a breaking change.
\nAs we mentioned, another benefit is that subclassing can be easier with ECMAScript’s # privates because they really are private.\nWhen using ECMAScript # private fields, no subclass ever has to worry about collisions in field naming.\nWhen it comes to TypeScript’s private property declarations, users still have to be careful not to trample over properties declared in superclasses.
One more thing to think about is where you intend for your code to run.\nTypeScript currently can’t support this feature unless targeting ECMAScript 2015 (ES6) targets or higher.\nThis is because our downleveled implementation uses WeakMaps to enforce privacy, and WeakMaps can’t be polyfilled in a way that doesn’t cause memory leaks.\nIn contrast, TypeScript’s private-declared properties work with all targets - even ECMAScript 3!
A final consideration might be speed: private properties are no different from any other property, so accessing them is as fast as any other property access no matter which runtime you target.\nIn contrast, because # private fields are downleveled using WeakMaps, they may be slower to use.\nWhile some runtimes might optimize their actual implementations of # private fields, and even have speedy WeakMap implementations, that might not be the case in all runtimes.
export * as ns SyntaxIt’s often common to have a single entry-point that exposes all the members of another module as a single member.
\n\ntsimport * as utilities from \"./utilities.js\";\nexport { utilities };
This is so common that ECMAScript 2020 recently added a new syntax to support this pattern!
\n\ntsexport * as utilities from \"./utilities.js\";
This is a nice quality-of-life improvement to JavaScript, and TypeScript 3.8 implements this syntax.\nWhen your module target is earlier than es2020, TypeScript will output something along the lines of the first code snippet.
awaitTypeScript 3.8 provides support for a handy upcoming ECMAScript feature called “top-level await“.
JavaScript users often introduce an async function in order to use await, and then immediately called the function after defining it.
\njsasync function main() {\n const response = await fetch(\"...\");\n const greeting = await response.text();\n console.log(greeting);\n}\n\nmain().catch(e => console.error(e));
This is because previously in JavaScript (along with most other languages with a similar feature), await was only allowed within the body of an async function.\nHowever, with top-level await, we can use await at the top level of a module.
\ntsconst response = await fetch(\"...\");\nconst greeting = await response.text();\nconsole.log(greeting);\n\n// Make sure we're a module\nexport {};
Note there’s a subtlety: top-level await only works at the top level of a module, and files are only considered modules when TypeScript finds an import or an export.\nIn some basic cases, you might need to write out export {} as some boilerplate to make sure of this.
Top level await may not work in all environments where you might expect at this point.\nCurrently, you can only use top level await when the target compiler option is es2017 or above, and module is esnext or system.\nSupport within several environments and bundlers may be limited or may require enabling experimental support.
For more information on our implementation, you can check out the original pull request.
\nes2020 for target and moduleTypeScript 3.8 supports es2020 as an option for module and target.\nThis will preserve newer ECMAScript 2020 features like optional chaining, nullish coalescing, export * as ns, and dynamic import(...) syntax.\nIt also means bigint literals now have a stable target below esnext.
TypeScript 3.8 supports JavaScript files by turning on the allowJs flag, and also supports type-checking those JavaScript files via the checkJs option or by adding a // @ts-check comment to the top of your .js files.
Because JavaScript files don’t have dedicated syntax for type-checking, TypeScript leverages JSDoc.\nTypeScript 3.8 understands a few new JSDoc tags for properties.
\nFirst are the accessibility modifiers: @public, @private, and @protected.\nThese tags work exactly like public, private, and protected respectively work in TypeScript.
\njs// @ts-check\n\nclass Foo {\n constructor() {\n /** @private */\n this.stuff = 100;\n }\n\n printStuff() {\n console.log(this.stuff);\n }\n}\n\nnew Foo().stuff;\n// ~~~~~\n// error! Property 'stuff' is private and only accessible within class 'Foo'.
@public is always implied and can be left off, but means that a property can be reached from anywhere.@private means that a property can only be used within the containing class.@protected means that a property can only be used within the containing class, and all derived subclasses, but not on dissimilar instances of the containing class.Next, we’ve also added the @readonly modifier to ensure that a property is only ever written to during initialization.
\njs// @ts-check\n\nclass Foo {\n constructor() {\n /** @readonly */\n this.stuff = 100;\n }\n\n writeToStuff() {\n this.stuff = 200;\n // ~~~~~\n // Cannot assign to 'stuff' because it is a read-only property.\n }\n}\n\nnew Foo().stuff++;\n// ~~~~~\n// Cannot assign to 'stuff' because it is a read-only property.
watchOptionsTypeScript 3.8 ships a new strategy for watching directories, which is crucial for efficiently picking up changes to node_modules.
For some context, on operating systems like Linux, TypeScript installs directory watchers (as opposed to file watchers) on node_modules and many of its subdirectories to detect changes in dependencies.\nThis is because the number of available file watchers is often eclipsed by the of files in node_modules, whereas there are way fewer directories to track.
Older versions of TypeScript would immediately install directory watchers on folders, and at startup that would be fine; however, during an npm install, a lot of activity will take place within node_modules and that can overwhelm TypeScript, often slowing editor sessions to a crawl.\nTo prevent this, TypeScript 3.8 waits slightly before installing directory watchers to give these highly volatile directories some time to stabilize.
Because every project might work better under different strategies, and this new approach might not work well for your workflows, TypeScript 3.8 introduces a new watchOptions field in tsconfig.json and jsconfig.json which allows users to tell the compiler/language service which watching strategies should be used to keep track of files and directories.
\njson{\n // Some typical compiler options\n compilerOptions: {\n target: \"es2020\",\n moduleResolution: \"node\"\n // ...\n },\n\n // NEW: Options for file/directory watching\n watchOptions: {\n // Use native file system events for files and directories\n watchFile: \"useFsEvents\",\n watchDirectory: \"useFsEvents\",\n\n // Poll files for updates more frequently\n // when they're updated a lot.\n fallbackPolling: \"dynamicPriority\"\n }\n}
watchOptions contains 4 new options that can be configured to handle how TypeScript keeps track of changes.
For more information on these changes, head over to GitHub to see the pull request to read more.
\nTypeScript 3.8 introduces a new compiler option called assumeChangesOnlyAffectDirectDependencies.\nWhen this option is enabled, TypeScript will avoid rechecking/rebuilding all truly possibly-affected files, and only recheck/rebuild files that have changed as well as files that directly import them.
In a codebase like Visual Studio Code, this reduced rebuild times for changes in certain files from about 14 seconds to about 1 second.\nWhile we don’t necessarily recommend this option for all codebases, you might be interested if you have an extremely large codebase and are willing to defer full project errors until later (e.g. a dedicated build via a tsconfig.fullbuild.json or in CI).
For more details, you can see the original pull request.
\nOptional chaining is issue #16 on our issue tracker. For context, there have been over 23,000 issues on the TypeScript issue tracker since then.
\nAt its core, optional chaining lets us write code where TypeScript can immediately stop running some expressions if we run into a null or undefined.\nThe star of the show in optional chaining is the new ?. operator for optional property accesses.\nWhen we write code like
\ntslet x = foo?.bar.baz();
this is a way of saying that when foo is defined, foo.bar.baz() will be computed; but when foo is null or undefined, stop what we’re doing and just return undefined.”
More plainly, that code snippet is the same as writing the following.
\n\ntslet x = foo === null || foo === undefined ? undefined : foo.bar.baz();
Note that if bar is null or undefined, our code will still hit an error accessing baz.\nLikewise, if baz is null or undefined, we’ll hit an error at the call site.\n?. only checks for whether the value on the left of it is null or undefined - not any of the subsequent properties.
You might find yourself using ?. to replace a lot of code that performs repetitive nullish checks using the && operator.
\nts// Before\nif (foo && foo.bar && foo.bar.baz) {\n // ...\n}\n\n// After-ish\nif (foo?.bar?.baz) {\n // ...\n}
Keep in mind that ?. acts differently than those && operations since && will act specially on “falsy” values (e.g. the empty string, 0, NaN, and, well, false), but this is an intentional feature of the construct.\nIt doesn’t short-circuit on valid data like 0 or empty strings.
Optional chaining also includes two other operations.\nFirst there’s the optional element access which acts similarly to optional property accesses, but allows us to access non-identifier properties (e.g. arbitrary strings, numbers, and symbols):
\n\nts/**\n * Get the first element of the array if we have an array.\n * Otherwise return undefined.\n */\nfunction tryGetFirstElement<T>(arr?: T[]) {\n return arr?.[0];\n // equivalent to\n // return (arr === null || arr === undefined) ?\n // undefined :\n // arr[0];\n}
There’s also optional call, which allows us to conditionally call expressions if they’re not null or undefined.
\ntsasync function makeRequest(url: string, log?: (msg: string) => void) {\n log?.(`Request started at ${new Date().toISOString()}`);\n // roughly equivalent to\n // if (log != null) {\n // log(`Request started at ${new Date().toISOString()}`);\n // }\n\n const result = (await fetch(url)).json();\n\n log?.(`Request finished at at ${new Date().toISOString()}`);\n\n return result;\n}
The “short-circuiting” behavior that optional chains have is limited property accesses, calls, element accesses - it doesn’t expand any further out from these expressions.\nIn other words,
\n\ntslet result = foo?.bar / someComputation();
doesn’t stop the division or someComputation() call from occurring.\nIt’s equivalent to
\ntslet temp = foo === null || foo === undefined ? undefined : foo.bar;\n\nlet result = temp / someComputation();
That might result in dividing undefined, which is why in strictNullChecks, the following is an error.
\ntsfunction barPercentage(foo?: { bar: number }) {\n return foo?.bar / 100;\n // ~~~~~~~~\n // Error: Object is possibly undefined.\n}
More more details, you can read up on the proposal and view the original pull request.
\nThe nullish coalescing operator is another upcoming ECMAScript feature that goes hand-in-hand with optional chaining, and which our team has been involved with championing in TC39.
\nYou can think of this feature - the ?? operator - as a way to “fall back” to a default value when dealing with null or undefined.\nWhen we write code like
\ntslet x = foo ?? bar();
this is a new way to say that the value foo will be used when it’s “present”;\nbut when it’s null or undefined, calculate bar() in its place.
Again, the above code is equivalent to the following.
\n\ntslet x = foo !== null && foo !== undefined ? foo : bar();
The ?? operator can replace uses of || when trying to use a default value.\nFor example, the following code snippet tries to fetch the volume that was last saved in localStorage (if it ever was);\nhowever, it has a bug because it uses ||.
\ntsfunction initializeAudio() {\n let volume = localStorage.volume || 0.5;\n\n // ...\n}
When localStorage.volume is set to 0, the page will set the volume to 0.5 which is unintended.\n?? avoids some unintended behavior from 0, NaN and \"\" being treated as falsy values.
We owe a large thanks to community members Wenlu Wang and Titian Cernicova Dragomir for implementing this feature!\nFor more details, check out their pull request and the nullish coalescing proposal repository.
\nThere’s a specific set of functions that throw an error if something unexpected happened.\nThey’re called “assertion” functions.\nAs an example, Node.js has a dedicated function for this called assert.
\njsassert(someValue === 42);
In this example if someValue isn’t equal to 42, then assert will throw an AssertionError.
Assertions in JavaScript are often used to guard against improper types being passed in.\nFor example,
\n\njsfunction multiply(x, y) {\n assert(typeof x === \"number\");\n assert(typeof y === \"number\");\n\n return x * y;\n}
Unfortunately in TypeScript these checks could never be properly encoded.\nFor loosely-typed code this meant TypeScript was checking less, and for slightly conservative code it often forced users to use type assertions.
\n\ntsfunction yell(str) {\n assert(typeof str === \"string\");\n\n return str.toUppercase();\n // Oops! We misspelled 'toUpperCase'.\n // Would be great if TypeScript still caught this!\n}
The alternative was to instead rewrite the code so that the language could analyze it, but this isn’t convenient.
\n\ntsfunction yell(str) {\n if (typeof str !== \"string\") {\n throw new TypeError(\"str should have been a string.\");\n }\n // Error caught!\n return str.toUppercase();\n}
Ultimately the goal of TypeScript is to type existing JavaScript constructs in the least disruptive way.\nFor that reason, TypeScript 3.7 introduces a new concept called “assertion signatures” which model these assertion functions.
\nThe first type of assertion signature models the way that Node’s assert function works.\nIt ensures that whatever condition is being checked must be true for the remainder of the containing scope.
\ntsfunction assert(condition: any, msg?: string): asserts condition {\n if (!condition) {\n throw new AssertionError(msg);\n }\n}
asserts condition says that whatever gets passed into the condition parameter must be true if the assert returns (because otherwise it would throw an error).\nThat means that for the rest of the scope, that condition must be truthy.\nAs an example, using this assertion function means we do catch our original yell example.
\ntsfunction yell(str) {\n assert(typeof str === \"string\");\n\n return str.toUppercase();\n // ~~~~~~~~~~~\n // error: Property 'toUppercase' does not exist on type 'string'.\n // Did you mean 'toUpperCase'?\n}\n\nfunction assert(condition: any, msg?: string): asserts condition {\n if (!condition) {\n throw new AssertionError(msg);\n }\n}
The other type of assertion signature doesn’t check for a condition, but instead tells TypeScript that a specific variable or property has a different type.
\n\ntsfunction assertIsString(val: any): asserts val is string {\n if (typeof val !== \"string\") {\n throw new AssertionError(\"Not a string!\");\n }\n}
Here asserts val is string ensures that after any call to assertIsString, any variable passed in will be known to be a string.
\ntsfunction yell(str: any) {\n assertIsString(str);\n\n // Now TypeScript knows that 'str' is a 'string'.\n\n return str.toUppercase();\n // ~~~~~~~~~~~\n // error: Property 'toUppercase' does not exist on type 'string'.\n // Did you mean 'toUpperCase'?\n}
These assertion signatures are very similar to writing type predicate signatures:
\n\ntsfunction isString(val: any): val is string {\n return typeof val === \"string\";\n}\n\nfunction yell(str: any) {\n if (isString(str)) {\n return str.toUppercase();\n }\n throw \"Oops!\";\n}
And just like type predicate signatures, these assertion signatures are incredibly expressive.\nWe can express some fairly sophisticated ideas with these.
\n\ntsfunction assertIsDefined<T>(val: T): asserts val is NonNullable<T> {\n if (val === undefined || val === null) {\n throw new AssertionError(\n `Expected 'val' to be defined, but received ${val}`\n );\n }\n}
To read up more about assertion signatures, check out the original pull request.
\nnever-Returning FunctionsAs part of the work for assertion signatures, TypeScript needed to encode more about where and which functions were being called.\nThis gave us the opportunity to expand support for another class of functions: functions that return never.
The intent of any function that returns never is that it never returns.\nIt indicates that an exception was thrown, a halting error condition occurred, or that the program exited.\nFor example, process.exit(...) in @types/node is specified to return never.
In order to ensure that a function never potentially returned undefined or effectively returned from all code paths, TypeScript needed some syntactic signal - either a return or throw at the end of a function.\nSo users found themselves return-ing their failure functions.
\ntsfunction dispatch(x: string | number): SomeType {\n if (typeof x === \"string\") {\n return doThingWithString(x);\n } else if (typeof x === \"number\") {\n return doThingWithNumber(x);\n }\n return process.exit(1);\n}
Now when these never-returning functions are called, TypeScript recognizes that they affect the control flow graph and accounts for them.
\ntsfunction dispatch(x: string | number): SomeType {\n if (typeof x === \"string\") {\n return doThingWithString(x);\n } else if (typeof x === \"number\") {\n return doThingWithNumber(x);\n }\n process.exit(1);\n}
As with assertion functions, you can read up more at the same pull request.
\nType aliases have always had a limitation in how they could be “recursively” referenced.\nThe reason is that any use of a type alias needs to be able to substitute itself with whatever it aliases.\nIn some cases, that’s not possible, so the compiler rejects certain recursive aliases like the following:
\n\ntstype Foo = Foo;
This is a reasonable restriction because any use of Foo would need to be replaced with Foo which would need to be replaced with Foo which would need to be replaced with Foo which… well, hopefully you get the idea!\nIn the end, there isn’t a type that makes sense in place of Foo.
This is fairly consistent with how other languages treat type aliases, but it does give rise to some slightly surprising scenarios for how users leverage the feature.\nFor example, in TypeScript 3.6 and prior, the following causes an error.
\n\ntstype ValueOrArray<T> = T | Array<ValueOrArray<T>>;\n// ~~~~~~~~~~~~\n// error: Type alias 'ValueOrArray' circularly references itself.
This is strange because there is technically nothing wrong with any use users could always write what was effectively the same code by introducing an interface.
\n\ntstype ValueOrArray<T> = T | ArrayOfValueOrArray<T>;\n\ninterface ArrayOfValueOrArray<T> extends Array<ValueOrArray<T>> {}
Because interfaces (and other object types) introduce a level of indirection and their full structure doesn’t need to be eagerly built out, TypeScript has no problem working with this structure.
\nBut workaround of introducing the interface wasn’t intuitive for users.\nAnd in principle there really wasn’t anything wrong with the original version of ValueOrArray that used Array directly.\nIf the compiler was a little bit “lazier” and only calculated the type arguments to Array when necessary, then TypeScript could express these correctly.
That’s exactly what TypeScript 3.7 introduces.\nAt the “top level” of a type alias, TypeScript will defer resolving type arguments to permit these patterns.
\nThis means that code like the following that was trying to represent JSON…
\n\ntstype Json = string | number | boolean | null | JsonObject | JsonArray;\n\ninterface JsonObject {\n [property: string]: Json;\n}\n\ninterface JsonArray extends Array<Json> {}
can finally be rewritten without helper interfaces.
\n\ntstype Json =\n | string\n | number\n | boolean\n | null\n | { [property: string]: Json }\n | Json[];
This new relaxation also lets us recursively reference type aliases in tuples as well.\nThe following code which used to error is now valid TypeScript code.
\n\ntstype VirtualNode = string | [string, { [key: string]: any }, ...VirtualNode[]];\n\nconst myNode: VirtualNode = [\n \"div\",\n { id: \"parent\" },\n [\"div\", { id: \"first-child\" }, \"I'm the first child\"],\n [\"div\", { id: \"second-child\" }, \"I'm the second child\"]\n];
For more information, you can read up on the original pull request.
\n--declaration and --allowJsThe --declaration flag in TypeScript allows us to generate .d.ts files (declaration files) from TypeScript source files (i.e. .ts and .tsx files).\nThese .d.ts files are important for a couple of reasons.
First of all, they’re important because they allow TypeScript to type-check against other projects without re-checking the original source code.\nThey’re also important because they allow TypeScript to interoperate with existing JavaScript libraries that weren’t built with TypeScript in mind.\nFinally, a benefit that is often underappreciated: both TypeScript and JavaScript users can benefit from these files when using editors powered by TypeScript to get things like better auto-completion.
\nUnfortunately, --declaration didn’t work with the --allowJs flag which allows mixing TypeScript and JavaScript input files.\nThis was a frustrating limitation because it meant users couldn’t use the --declaration flag when migrating codebases, even if they were JSDoc-annotated.\nTypeScript 3.7 changes that, and allows the two options to be used together!
The most impactful outcome of this feature might a bit subtle: with TypeScript 3.7, users can write libraries in JSDoc annotated JavaScript and support TypeScript users.
\nThe way that this works is that when using allowJs, TypeScript has some best-effort analyses to understand common JavaScript patterns; however, the way that some patterns are expressed in JavaScript don’t necessarily look like their equivalents in TypeScript.\nWhen declaration emit is turned on, TypeScript figures out the best way to transform JSDoc comments and CommonJS exports into valid type declarations and the like in the output .d.ts files.
As an example, the following code snippet
\n\njsconst assert = require(\"assert\");\n\nmodule.exports.blurImage = blurImage;\n\n/**\n * Produces a blurred image from an input buffer.\n *\n * @param input {Uint8Array}\n * @param width {number}\n * @param height {number}\n */\nfunction blurImage(input, width, height) {\n const numPixels = width * height * 4;\n assert(input.length === numPixels);\n const result = new Uint8Array(numPixels);\n\n // TODO\n\n return result;\n}
Will produce a .d.ts file like
\nts/**\n * Produces a blurred image from an input buffer.\n *\n * @param input {Uint8Array}\n * @param width {number}\n * @param height {number}\n */\nexport function blurImage(\n input: Uint8Array,\n width: number,\n height: number\n): Uint8Array;
This can go beyond basic functions with @param tags too, where the following example:
\njs/**\n * @callback Job\n * @returns {void}\n */\n\n/** Queues work */\nexport class Worker {\n constructor(maxDepth = 10) {\n this.started = false;\n this.depthLimit = maxDepth;\n /**\n * NOTE: queued jobs may add more items to queue\n * @type {Job[]}\n */\n this.queue = [];\n }\n /**\n * Adds a work item to the queue\n * @param {Job} work\n */\n push(work) {\n if (this.queue.length + 1 > this.depthLimit) throw new Error(\"Queue full!\");\n this.queue.push(work);\n }\n /**\n * Starts the queue if it has not yet started\n */\n start() {\n if (this.started) return false;\n this.started = true;\n while (this.queue.length) {\n /** @type {Job} */ (this.queue.shift())();\n }\n return true;\n }\n}
will be transformed into the following .d.ts file:
\nts/**\n * @callback Job\n * @returns {void}\n */\n/** Queues work */\nexport class Worker {\n constructor(maxDepth?: number);\n started: boolean;\n depthLimit: number;\n /**\n * NOTE: queued jobs may add more items to queue\n * @type {Job[]}\n */\n queue: Job[];\n /**\n * Adds a work item to the queue\n * @param {Job} work\n */\n push(work: Job): void;\n /**\n * Starts the queue if it has not yet started\n */\n start(): boolean;\n}\nexport type Job = () => void;
Note that when using these flags together, TypeScript doesn’t necessarily have to downlevel .js files.\nIf you simply want TypeScript to create .d.ts files, you can use the --emitDeclarationOnly compiler option.
For more details, you can check out the original pull request.
\nuseDefineForClassFields Flag and The declare Property ModifierBack when TypeScript implemented public class fields, we assumed to the best of our abilities that the following code
\n\ntsclass C {\n foo = 100;\n bar: string;\n}
would be equivalent to a similar assignment within a constructor body.
\n\ntsclass C {\n constructor() {\n this.foo = 100;\n }\n}
Unfortunately, while this seemed to be the direction that the proposal moved towards in its earlier days, there is an extremely strong chance that public class fields will be standardized differently.\nInstead, the original code sample might need to de-sugar to something closer to the following:
\n\ntsclass C {\n constructor() {\n Object.defineProperty(this, \"foo\", {\n enumerable: true,\n configurable: true,\n writable: true,\n value: 100\n });\n Object.defineProperty(this, \"bar\", {\n enumerable: true,\n configurable: true,\n writable: true,\n value: void 0\n });\n }\n}
While TypeScript 3.7 isn’t changing any existing emit by default, we’ve been rolling out changes incrementally to help users mitigate potential future breakage.\nWe’ve provided a new flag called useDefineForClassFields to enable this emit mode with some new checking logic.
The two biggest changes are the following:
\nObject.defineProperty.undefined, even if they have no initializer.This can cause quite a bit of fallout for existing code that use inheritance. First of all, set accessors from base classes won’t get triggered - they’ll be completely overwritten.
\ntsclass Base {\n set data(value: string) {\n console.log(\"data changed to \" + value);\n }\n}\n\nclass Derived extends Base {\n // No longer triggers a 'console.log'\n // when using 'useDefineForClassFields'.\n data = 10;\n}
Secondly, using class fields to specialize properties from base classes also won’t work.
\n\ntsinterface Animal {\n animalStuff: any;\n}\ninterface Dog extends Animal {\n dogStuff: any;\n}\n\nclass AnimalHouse {\n resident: Animal;\n constructor(animal: Animal) {\n this.resident = animal;\n }\n}\n\nclass DogHouse extends AnimalHouse {\n // Initializes 'resident' to 'undefined'\n // after the call to 'super()' when\n // using 'useDefineForClassFields'!\n resident: Dog;\n\n constructor(dog: Dog) {\n super(dog);\n }\n}
What these two boil down to is that mixing properties with accessors is going to cause issues, and so will re-declaring properties with no initializers.
\nTo detect the issue around accessors, TypeScript 3.7 will now emit get/set accessors in .d.ts files so that in TypeScript can check for overridden accessors.
Code that’s impacted by the class fields change can get around the issue by converting field initializers to assignments in constructor bodies.
\n\ntsclass Base {\n set data(value: string) {\n console.log(\"data changed to \" + value);\n }\n}\n\nclass Derived extends Base {\n constructor() {\n data = 10;\n }\n}
To help mitigate the second issue, you can either add an explicit initializer or add a declare modifier to indicate that a property should have no emit.
\ntsinterface Animal {\n animalStuff: any;\n}\ninterface Dog extends Animal {\n dogStuff: any;\n}\n\nclass AnimalHouse {\n resident: Animal;\n constructor(animal: Animal) {\n this.resident = animal;\n }\n}\n\nclass DogHouse extends AnimalHouse {\n declare resident: Dog;\n // ^^^^^^^\n // 'resident' now has a 'declare' modifier,\n // and won't produce any output code.\n\n constructor(dog: Dog) {\n super(dog);\n }\n}
Currently useDefineForClassFields is only available when targeting ES5 and upwards, since Object.defineProperty doesn’t exist in ES3.\nTo achieve similar checking for issues, you can create a seperate project that targets ES5 and uses --noEmit to avoid a full build.
For more information, you can take a look at the original pull request for these changes.
\nWe strongly encourage users to try the useDefineForClassFields flag and report back on our issue tracker or in the comments below.\nThis includes feedback on difficulty of adopting the flag so we can understand how we can make migration easier.
TypeScript’s project references provide us with an easy way to break codebases up to give us faster compiles.\nUnfortunately, editing a project whose dependencies hadn’t been built (or whose output was out of date) meant that the editing experience wouldn’t work well.
\nIn TypeScript 3.7, when opening a project with dependencies, TypeScript will automatically use the source .ts/.tsx files instead.\nThis means projects using project references will now see an improved editing experience where semantic operations are up-to-date and “just work”.\nYou can disable this behavior with the compiler option disableSourceOfProjectReferenceRedirect which may be appropriate when working in very large projects where this change may impact editing performance.
You can read up more about this change by reading up on its pull request.
\nA common and dangerous error is to forget to invoke a function, especially if the function has zero arguments or is named in a way that implies it might be a property rather than a function.
\n\ntsinterface User {\n isAdministrator(): boolean;\n notify(): void;\n doNotDisturb?(): boolean;\n}\n\n// later...\n\n// Broken code, do not use!\nfunction doAdminThing(user: User) {\n // oops!\n if (user.isAdministrator) {\n sudo();\n editTheConfiguration();\n } else {\n throw new AccessDeniedError(\"User is not an admin\");\n }\n}
Here, we forgot to call isAdministrator, and the code incorrectly allows non-adminstrator users to edit the configuration!
In TypeScript 3.7, this is identified as a likely error:
\n\ntsfunction doAdminThing(user: User) {\n if (user.isAdministrator) {\n // ~~~~~~~~~~~~~~~~~~~~\n // error! This condition will always return true since the function is always defined.\n // Did you mean to call it instead?
This check is a breaking change, but for that reason the checks are very conservative.\nThis error is only issued in if conditions, and it is not issued on optional properties, if strictNullChecks is off, or if the function is later called within the body of the if:
\ntsinterface User {\n isAdministrator(): boolean;\n notify(): void;\n doNotDisturb?(): boolean;\n}\n\nfunction issueNotification(user: User) {\n if (user.doNotDisturb) {\n // OK, property is optional\n }\n if (user.notify) {\n // OK, called the function\n user.notify();\n }\n}
If you intended to test the function without calling it, you can correct the definition of it to include undefined/null, or use !! to write something like if (!!user.isAdministrator) to indicate that the coercion is intentional.
We owe a big thanks to GitHub user @jwbay who took the initiative to create a proof-of-concept and iterated to provide us with with the current version.
\n// @ts-nocheck in TypeScript FilesTypeScript 3.7 allows us to add // @ts-nocheck comments to the top of TypeScript files to disable semantic checks.\nHistorically this comment was only respected in JavaScript source files in the presence of checkJs, but we’ve expanded support to TypeScript files to make migrations easier for all users.
TypeScript’s built-in formatter now supports semicolon insertion and removal at locations where a trailing semicolon is optional due to JavaScript’s automatic semicolon insertion (ASI) rules. The setting is available now in Visual Studio Code Insiders, and will be available in Visual Studio 16.4 Preview 2 in the Tools Options menu.
\n![\"New](\"https://user-images.githubusercontent.com/3277153/65913194-10066e80-e395-11e9-8a3a-4f7305c397d5.png\")
\nChoosing a value of “insert” or “remove” also affects the format of auto-imports, extracted types, and other generated code provided by TypeScript services. Leaving the setting on its default value of “ignore” makes generated code match the semicolon preference detected in the current file.
\nTypes in lib.dom.d.ts have been updated.\nThese changes are largely correctness changes related to nullability, but impact will ultimately depend on your codebase.
As mentioned above, TypeScript 3.7 emits get/set accessors in .d.ts files which can cause breaking changes for consumers on older versions of TypeScript like 3.5 and prior.\nTypeScript 3.6 users will not be impacted, since that version was future-proofed for this feature.
While not a breakage per se, opting in to the useDefineForClassFields flag can cause breakage when:
To understand the full impact, read the section above on the useDefineForClassFields flag.
As mentioned above, TypeScript now errors when functions appear to be uncalled within if statement conditions.\nAn error is issued when a function type is checked in if conditions unless any of the following apply:
strictNullChecks is disabledifDue to a bug, the following construct was previously allowed in TypeScript:
\n\nts// ./someOtherModule.ts\ninterface SomeType {\n y: string;\n}\n\n// ./myModule.ts\nimport { SomeType } from \"./someOtherModule\";\nexport interface SomeType {\n x: number;\n}\n\nfunction fn(arg: SomeType) {\n console.log(arg.x); // Error! 'x' doesn't exist on 'SomeType'\n}
Here, SomeType appears to originate in both the import declaration and the local interface declaration.\nPerhaps surprisingly, inside the module, SomeType refers exclusively to the imported definition, and the local declaration SomeType is only usable when imported from another file.\nThis is very confusing and our review of the very small number of cases of code like this in the wild showed that developers usually thought something different was happening.
In TypeScript 3.7, this is now correctly identified as a duplicate identifier error.\nThe correct fix depends on the original intent of the author and should be addressed on a case-by-case basis.\nUsually, the naming conflict is unintentional and the best fix is to rename the imported type.\nIf the intent was to augment the imported type, a proper module augmentation should be written instead.
\nTo enable the recursive type alias patterns described above, the typeArguments property has been removed from the TypeReference interface. Users should instead use the getTypeArguments function on TypeChecker instances.
TypeScript 3.6 introduces stricter checking for iterators and generator functions.\nIn earlier versions, users of generators had no way to differentiate whether a value was yielded or returned from a generator.
\n\ntsfunction* foo() {\n if (Math.random() < 0.5) yield 100;\n return \"Finished!\";\n}\n\nlet iter = foo();\nlet curr = iter.next();\nif (curr.done) {\n // TypeScript 3.5 and prior thought this was a 'string | number'.\n // It should know it's 'string' since 'done' was 'true'!\n curr.value;\n}
Additionally, generators just assumed the type of yield was always any.
\ntsfunction* bar() {\n let x: { hello(): void } = yield;\n x.hello();\n}\n\nlet iter = bar();\niter.next();\niter.next(123); // oops! runtime error!
In TypeScript 3.6, the checker now knows that the correct type for curr.value should be string in our first example, and will correctly error on our call to next() in our last example.\nThis is thanks to some changes in the Iterator and IteratorResult type declarations to include a few new type parameters, and to a new type that TypeScript uses to represent generators called the Generator type.
The Iterator type now allows users to specify the yielded type, the returned type, and the type that next can accept.
\ntsinterface Iterator<T, TReturn = any, TNext = undefined> {\n // Takes either 0 or 1 arguments - doesn't accept 'undefined'\n next(...args: [] | [TNext]): IteratorResult<T, TReturn>;\n return?(value?: TReturn): IteratorResult<T, TReturn>;\n throw?(e?: any): IteratorResult<T, TReturn>;\n}
Building on that work, the new Generator type is an Iterator that always has both the return and throw methods present, and is also iterable.
\ntsinterface Generator<T = unknown, TReturn = any, TNext = unknown>\n extends Iterator<T, TReturn, TNext> {\n next(...args: [] | [TNext]): IteratorResult<T, TReturn>;\n return(value: TReturn): IteratorResult<T, TReturn>;\n throw(e: any): IteratorResult<T, TReturn>;\n [Symbol.iterator](): Generator<T, TReturn, TNext>;\n}
To allow differentiation between returned values and yielded values, TypeScript 3.6 converts the IteratorResult type to a discriminated union type:
\ntstype IteratorResult<T, TReturn = any> =\n | IteratorYieldResult<T>\n | IteratorReturnResult<TReturn>;\n\ninterface IteratorYieldResult<TYield> {\n done?: false;\n value: TYield;\n}\n\ninterface IteratorReturnResult<TReturn> {\n done: true;\n value: TReturn;\n}
In short, what this means is that you’ll be able to appropriately narrow down values from iterators when dealing with them directly.
\nTo correctly represent the types that can be passed in to a generator from calls to next(), TypeScript 3.6 also infers certain uses of yield within the body of a generator function.
\ntsfunction* foo() {\n let x: string = yield;\n console.log(x.toUpperCase());\n}\n\nlet x = foo();\nx.next(); // first call to 'next' is always ignored\nx.next(42); // error! 'number' is not assignable to 'string'
If you’d prefer to be explicit, you can also enforce the type of values that can be returned, yielded, and evaluated from yield expressions using an explicit return type.\nBelow, next() can only be called with booleans, and depending on the value of done, value is either a string or a number.
\nts/**\n * - yields numbers\n * - returns strings\n * - can be passed in booleans\n */\nfunction* counter(): Generator<number, string, boolean> {\n let i = 0;\n while (true) {\n if (yield i++) {\n break;\n }\n }\n return \"done!\";\n}\n\nvar iter = counter();\nvar curr = iter.next();\nwhile (!curr.done) {\n console.log(curr.value);\n curr = iter.next(curr.value === 5);\n}\nconsole.log(curr.value.toUpperCase());\n\n// prints:\n//\n// 0\n// 1\n// 2\n// 3\n// 4\n// 5\n// DONE!
For more details on the change, see the pull request here.
\nIn pre-ES2015 targets, the most faithful emit for constructs like for/of loops and array spreads can be a bit heavy.\nFor this reason, TypeScript uses a simpler emit by default that only supports array types, and supports iterating on other types using the --downlevelIteration flag.\nThe looser default without --downlevelIteration works fairly well; however, there were some common cases where the transformation of array spreads had observable differences.\nFor example, the following array containing a spread
\nts[...Array(5)];
can be rewritten as the following array literal
\n\njs[undefined, undefined, undefined, undefined, undefined];
However, TypeScript would instead transform the original code into this code:
\n\ntsArray(5).slice();
which is slightly different.\nArray(5) produces an array with a length of 5, but with no defined property slots.
TypeScript 3.6 introduces a new __spreadArrays helper to accurately model what happens in ECMAScript 2015 in older targets outside of --downlevelIteration.\n__spreadArrays is also available in tslib.
For more information, see the relevant pull request.
\nTypeScript 3.6 introduces some improvements for when Promises are mis-handled.
For example, it’s often very common to forget to .then() or await the contents of a Promise before passing it to another function.\nTypeScript’s error messages are now specialized, and inform the user that perhaps they should consider using the await keyword.
\ntsinterface User {\n name: string;\n age: number;\n location: string;\n}\n\ndeclare function getUserData(): Promise<User>;\ndeclare function displayUser(user: User): void;\n\nasync function f() {\n displayUser(getUserData());\n // ~~~~~~~~~~~~~\n // Argument of type 'Promise<User>' is not assignable to parameter of type 'User'.\n // ...\n // Did you forget to use 'await'?\n}
It’s also common to try to access a method before await-ing or .then()-ing a Promise.\nThis is another example, among many others, where we’re able to do better.
\ntsasync function getCuteAnimals() {\n fetch(\"https://reddit.com/r/aww.json\").json();\n // ~~~~\n // Property 'json' does not exist on type 'Promise<Response>'.\n //\n // Did you forget to use 'await'?\n}
For more details, see the originating issue, as well as the pull requests that link back to it.
\nTypeScript 3.6 contains better support for Unicode characters in identifiers when emitting to ES2015 and later targets.
\n\ntsconst 𝓱𝓮𝓵𝓵𝓸 = \"world\"; // previously disallowed, now allowed in '--target es2015'
import.meta Support in SystemJSTypeScript 3.6 supports transforming import.meta to context.meta when your module target is set to system.
\nts// This module:\n\nconsole.log(import.meta.url);\n\n// gets turned into the following:\n\nSystem.register([], function(exports, context) {\n return {\n setters: [],\n execute: function() {\n console.log(context.meta.url);\n }\n };\n});
get and set Accessors Are Allowed in Ambient ContextsIn previous versions of TypeScript, the language didn’t allow get and set accessors in ambient contexts (like in declare-d classes, or in .d.ts files in general).\nThe rationale was that accessors weren’t distinct from properties as far as writing and reading to these properties;\nhowever, because ECMAScript’s class fields proposal may have differing behavior from in existing versions of TypeScript, we realized we needed a way to communicate this different behavior to provide appropriate errors in subclasses.
As a result, users can write getters and setters in ambient contexts in TypeScript 3.6.
\n\ntsdeclare class Foo {\n // Allowed in 3.6+.\n get x(): number;\n set x(val: number): void;\n}
In TypeScript 3.7, the compiler itself will take advantage of this feature so that generated .d.ts files will also emit get/set accessors.
In previous versions of TypeScript, it was an error to merge classes and functions under any circumstances.\nNow, ambient classes and functions (classes/functions with the declare modifier, or in .d.ts files) can merge.\nThis means that now you can write the following:
\ntsexport declare function Point2D(x: number, y: number): Point2D;\nexport declare class Point2D {\n x: number;\n y: number;\n constructor(x: number, y: number);\n}
instead of needing to use
\n\ntsexport interface Point2D {\n x: number;\n y: number;\n}\nexport declare var Point2D: {\n (x: number, y: number): Point2D;\n new (x: number, y: number): Point2D;\n};
One advantage of this is that the callable constructor pattern can be easily expressed while also allowing namespaces to merge with these declarations (since var declarations can’t merge with namespaces).
In TypeScript 3.7, the compiler will take advantage of this feature so that .d.ts files generated from .js files can appropriately capture both the callability and constructability of a class-like function.
For more details, see the original PR on GitHub.
\n--build and --incrementalTypeScript 3.0 introduced support for referencing other and building them incrementally using the --build flag.\nAdditionally, TypeScript 3.4 introduced the --incremental flag for saving information about previous compilations to only rebuild certain files.\nThese flags were incredibly useful for structuring projects more flexibly and speeding builds up.\nUnfortunately, using these flags didn’t work with 3rd party build tools like Gulp and Webpack.\nTypeScript 3.6 now exposes two sets of APIs to operate on project references and incremental program building.
For creating --incremental builds, users can leverage the createIncrementalProgram and createIncrementalCompilerHost APIs.\nUsers can also re-hydrate old program instances from .tsbuildinfo files generated by this API using the newly exposed readBuilderProgram function, which is only meant to be used as for creating new programs (i.e. you can’t modify the returned instance - it’s only meant to be used for the oldProgram parameter in other create*Program functions).
For leveraging project references, a new createSolutionBuilder function has been exposed, which returns an instance of the new type SolutionBuilder.
For more details on these APIs, you can see the original pull request.
\nEditors like Visual Studio and Visual Studio Code can automatically apply quick fixes, refactorings, and other transformations like automatically importing values from other modules.\nThese transformations are powered by TypeScript, and older versions of TypeScript unconditionally added semicolons to the end of every statement; unfortunately, this disagreed with many users’ style guidelines, and many users were displeased with the editor inserting semicolons.
\nTypeScript is now smart enough to detect whether your file uses semicolons when applying these sorts of edits.\nIf your file generally lacks semicolons, TypeScript won’t add one.
\nFor more details, see the corresponding pull request.
\nJavaScript has a lot of different module syntaxes or conventions: the one in the ECMAScript standard, the one Node already supports (CommonJS), AMD, System.js, and more!\nFor the most part, TypeScript would default to auto-importing using ECMAScript module syntax, which was often inappropriate in certain TypeScript projects with different compiler settings, or in Node projects with plain JavaScript and require calls.
TypeScript 3.6 is now a bit smarter about looking at your existing imports before deciding on how to auto-import other modules.\nYou can see more details in the original pull request here.
\nawait Completions on PromisesThe TypeScript playground has received a much-needed refresh with handy new functionality!\nThe new playground is largely a fork of Artem Tyurin’s TypeScript playground which community members have been using more and more.\nWe owe Artem a big thanks for helping out here!
\nThe new playground now supports many new options including:
\ntarget option (allowing users to switch out of es5 to es3, es2015, esnext, etc.)strict)allowJS and optionally checkJs)These options also persist when sharing links to playground samples, allowing users to more reliably share examples without having to tell the recipient “oh, don’t forget to turn on the noImplicitAny option!“.
In the near future, we’re going to be refreshing the playground samples, adding JSX support, and polishing automatic type acquisition, meaning that you’ll be able to see the same experience on the playground as you’d get in your personal editor.
\nAs we improve the playground and the website, we welcome feedback and pull requests on GitHub!
\nTypeScript 3.5 introduces several optimizations around type-checking and incremental builds.
\nTypeScript 3.5 contains certain optimizations over TypeScript 3.4 for type-checking more efficiently.\nThese improvements are significantly more pronounced in editor scenarios where type-checking drives operations like code completion lists.
\n--incremental improvementsTypeScript 3.5 improves on 3.4’s --incremental build mode, by saving information about how the state of the world was calculated - compiler settings, why files were looked up, where files were found, etc.\nIn scenarios involving hundreds of projects using TypeScript’s project references in --build mode, we’ve found that the amount of time rebuilding can be reduced by as much as 68% compared to TypeScript 3.4!
For more details, you can see the pull requests to
\n\nOmit helper typeTypeScript 3.5 introduces the new Omit helper type, which creates a new type with some properties dropped from the original.
\ntstype Person = {\n name: string;\n age: number;\n location: string;\n};\n\ntype QuantumPerson = Omit<Person, \"location\">;\n\n// equivalent to\ntype QuantumPerson = {\n name: string;\n age: number;\n};
Here we were able to copy over all the properties of Person except for location using the Omit helper.
For more details, see the pull request on GitHub to add Omit, as well as the change to use Omit for object rest.
In TypeScript 3.4 and earlier, certain excess properties were allowed in situations where they really shouldn’t have been.\nFor instance, TypeScript 3.4 permitted the incorrect name property in the object literal even though its types don’t match between Point and Label.
\ntstype Point = {\n x: number;\n y: number;\n};\n\ntype Label = {\n name: string;\n};\n\nconst thing: Point | Label = {\n x: 0,\n y: 0,\n name: true // uh-oh!\n};
Previously, a non-disciminated union wouldn’t have any excess property checking done on its members, and as a result, the incorrectly typed name property slipped by.
In TypeScript 3.5, the type-checker at least verifies that all the provided properties belong to some union member and have the appropriate type, meaning that the sample above correctly issues an error.
\nNote that partial overlap is still permitted as long as the property types are valid.
\n\ntsconst pl: Point | Label = {\n x: 0,\n y: 0,\n name: \"origin\" // okay\n};
--allowUmdGlobalAccess flagIn TypeScript 3.5, you can now reference UMD global declarations like
\nexport as namespace foo;\nfrom anywhere - even modules - using the new --allowUmdGlobalAccess flag.
This mode adds flexibility for mixing and matching the way 3rd party libraries, where globals that libraries declare can always be consumed, even from within modules.
\nFor more details, see the pull request on GitHub.
\nIn TypeScript 3.4 and prior, the following example would fail:
\n\ntstype S = { done: boolean; value: number };\ntype T = { done: false; value: number } | { done: true; value: number };\n\ndeclare let source: S;\ndeclare let target: T;\n\ntarget = source;
That’s because S isn’t assignable to { done: false, value: number } nor { done: true, value: number }.\nWhy?\nBecause the done property in S isn’t specific enough - it’s boolean whereas each constituent of T has a done property that’s specifically true or false.\nThat’s what we meant by each constituent type being checked in isolation: TypeScript doesn’t just union each property together and see if S is assignable to that.\nIf it did, some bad code could get through like the following:
\ntsinterface Foo {\n kind: \"foo\";\n value: string;\n}\n\ninterface Bar {\n kind: \"bar\";\n value: number;\n}\n\nfunction doSomething(x: Foo | Bar) {\n if (x.kind === \"foo\") {\n x.value.toLowerCase();\n }\n}\n\n// uh-oh - luckily TypeScript errors here!\ndoSomething({\n kind: \"foo\",\n value: 123\n});
However, this was a bit overly strict for the original example.\nIf you figure out the precise type of any possible value of S, you can actually see that it matches the types in T exactly.
In TypeScript 3.5, when assigning to types with discriminant properties like in T, the language actually will go further and decompose types like S into a union of every possible inhabitant type.\nIn this case, since boolean is a union of true and false, S will be viewed as a union of { done: false, value: number } and { done: true, value: number }.
For more details, you can see the original pull request on GitHub.
\nIn TypeScript 3.4, we improved inference for when generic functions that return functions like so:
\n\ntsfunction compose<T, U, V>(f: (x: T) => U, g: (y: U) => V): (x: T) => V {\n return x => g(f(x));\n}
took other generic functions as arguments, like so:
\n\ntsfunction arrayify<T>(x: T): T[] {\n return [x];\n}\n\ntype Box<U> = { value: U };\nfunction boxify<U>(y: U): Box<U> {\n return { value: y };\n}\n\nlet newFn = compose(arrayify, boxify);
Instead of a relatively useless type like (x: {}) => Box<{}[]>, which older versions of the language would infer, TypeScript 3.4’s inference allows newFn to be generic.\nIts new type is <T>(x: T) => Box<T[]>.
TypeScript 3.5 generalizes this behavior to work on constructor functions as well.
\n\ntsclass Box<T> {\n kind: \"box\";\n value: T;\n constructor(value: T) {\n this.value = value;\n }\n}\n\nclass Bag<U> {\n kind: \"bag\";\n value: U;\n constructor(value: U) {\n this.value = value;\n }\n}\n\nfunction composeCtor<T, U, V>(\n F: new (x: T) => U,\n G: new (y: U) => V\n): (x: T) => V {\n return x => new G(new F(x));\n}\n\nlet f = composeCtor(Box, Bag); // has type '<T>(x: T) => Bag<Box<T>>'\nlet a = f(1024); // has type 'Bag<Box<number>>'
In addition to compositional patterns like the above, this new inference on generic constructors means that functions that operate on class components in certain UI libraries like React can more correctly operate on generic class components.
\n\ntstype ComponentClass<P> = new (props: P) => Component<P>;\ndeclare class Component<P> {\n props: P;\n constructor(props: P);\n}\n\ndeclare function myHoc<P>(C: ComponentClass<P>): ComponentClass<P>;\n\ntype NestedProps<T> = { foo: number; stuff: T };\n\ndeclare class GenericComponent<T> extends Component<NestedProps<T>> {}\n\n// type is 'new <T>(props: NestedProps<T>) => Component<NestedProps<T>>'\nconst GenericComponent2 = myHoc(GenericComponent);
To learn more, check out the original pull request on GitHub.
\n--incremental flagTypeScript 3.4 introduces a new flag called --incremental which tells TypeScript to save information about the project graph from the last compilation.\nThe next time TypeScript is invoked with --incremental, it will use that information to detect the least costly way to type-check and emit changes to your project.
\njson// tsconfig.json\n{\n compilerOptions: {\n incremental: true,\n outDir: \"./lib\"\n },\n include: [\"./src\"]\n}
By default with these settings, when we run tsc, TypeScript will look for a file called .tsbuildinfo in the output directory (./lib).\nIf ./lib/.tsbuildinfo doesn’t exist, it’ll be generated.\nBut if it does, tsc will try to use that file to incrementally type-check and update our output files.
These .tsbuildinfo files can be safely deleted and don’t have any impact on our code at runtime - they’re purely used to make compilations faster.\nWe can also name them anything that we want, and place them anywhere we want using the --tsBuildInfoFile flag.
\njson// front-end.tsconfig.json\n{\n compilerOptions: {\n incremental: true,\n tsBuildInfoFile: \"./buildcache/front-end\",\n outDir: \"./lib\"\n },\n include: [\"./src\"]\n}
Part of the intent with composite projects (tsconfig.jsons with composite set to true) is that references between different projects can be built incrementally.\nAs such, composite projects will always produce .tsbuildinfo files.
outFileWhen outFile is used, the build information file’s name will be based on the output file’s name.\nAs an example, if our output JavaScript file is ./output/foo.js, then under the --incremental flag, TypeScript will generate the file ./output/foo.tsbuildinfo.\nAs above, this can be controlled with the --tsBuildInfoFile flag.
TypeScript 3.4 can now produce generic function types when inference from other generic functions produces free type variables for inferences.\nThis means many function composition patterns now work better in 3.4.
\nTo get more specific, let’s build up some motivation and consider the following compose function:
\ntsfunction compose<A, B, C>(f: (arg: A) => B, g: (arg: B) => C): (arg: A) => C {\n return x => g(f(x));\n}
compose takes two other functions:
f which takes some argument (of type A) and returns a value of type Bg which takes an argument of type B (the type f returned), and returns a value of type Ccompose then returns a function which feeds its argument through f and then g.
When calling this function, TypeScript will try to figure out the types of A, B, and C through a process called type argument inference.\nThis inference process usually works pretty well:
\ntsinterface Person {\n name: string;\n age: number;\n}\n\nfunction getDisplayName(p: Person) {\n return p.name.toLowerCase();\n}\n\nfunction getLength(s: string) {\n return s.length;\n}\n\n// has type '(p: Person) => number'\nconst getDisplayNameLength = compose(getDisplayName, getLength);\n\n// works and returns the type 'number'\ngetDisplayNameLength({ name: \"Person McPersonface\", age: 42 });
The inference process is fairly straightforward here because getDisplayName and getLength use types that can easily be referenced.\nHowever, in TypeScript 3.3 and earlier, generic functions like compose didn’t work so well when passed other generic functions.
\ntsinterface Box<T> {\n value: T;\n}\n\nfunction makeArray<T>(x: T): T[] {\n return [x];\n}\n\nfunction makeBox<U>(value: U): Box<U> {\n return { value };\n}\n\n// has type '(arg: {}) => Box<{}[]>'\nconst makeBoxedArray = compose(makeArray, makeBox);\n\nmakeBoxedArray(\"hello!\").value[0].toUpperCase();\n// ~~~~~~~~~~~\n// error: Property 'toUpperCase' does not exist on type '{}'.
In older versions, TypeScript would infer the empty object type ({}) when inferring from other type variables like T and U.
During type argument inference in TypeScript 3.4, for a call to a generic function that returns a function type, TypeScript will, as appropriate, propagate type parameters from generic function arguments onto the resulting function type.
\nIn other words, instead of producing the type
\n(arg: {}) => Box<{}[]>\nTypeScript 3.4 produces the type
\n\nts<T>(arg: T) => Box<T[]>
Notice that T has been propagated from makeArray into the resulting type’s type parameter list.\nThis means that genericity from compose’s arguments has been preserved and our makeBoxedArray sample will just work!
\ntsinterface Box<T> {\n value: T;\n}\n\nfunction makeArray<T>(x: T): T[] {\n return [x];\n}\n\nfunction makeBox<U>(value: U): Box<U> {\n return { value };\n}\n\n// has type '<T>(arg: T) => Box<T[]>'\nconst makeBoxedArray = compose(makeArray, makeBox);\n\n// works with no problem!\nmakeBoxedArray(\"hello!\").value[0].toUpperCase();
For more details, you can read more at the original change.
\nReadonlyArray and readonly tuplesTypeScript 3.4 makes it a little bit easier to use read-only array-like types.
\nReadonlyArrayThe ReadonlyArray type describes Arrays that can only be read from.\nAny variable with a reference to a ReadonlyArray can’t add, remove, or replace any elements of the array.
\ntsfunction foo(arr: ReadonlyArray<string>) {\n arr.slice(); // okay\n arr.push(\"hello!\"); // error!\n}
While it’s good practice to use ReadonlyArray over Array when no mutation is intended, it’s often been a pain given that arrays have a nicer syntax.\nSpecifically, number[] is a shorthand version of Array<number>, just as Date[] is a shorthand for Array<Date>.
TypeScript 3.4 introduces a new syntax for ReadonlyArray using a new readonly modifier for array types.
\ntsfunction foo(arr: readonly string[]) {\n arr.slice(); // okay\n arr.push(\"hello!\"); // error!\n}
readonly tuplesTypeScript 3.4 also introduces new support for readonly tuples.\nWe can prefix any tuple type with the readonly keyword to make it a readonly tuple, much like we now can with array shorthand syntax.\nAs you might expect, unlike ordinary tuples whose slots could be written to, readonly tuples only permit reading from those positions.
\ntsfunction foo(pair: readonly [string, string]) {\n console.log(pair[0]); // okay\n pair[1] = \"hello!\"; // error\n}
The same way that ordinary tuples are types that extend from Array - a tuple with elements of type T1, T2, … Tn extends from Array< T1 | T2 | … Tn > - readonly tuples are types that extend from ReadonlyArray. So a readonly tuple with elements T1, T2, … Tn extends from ReadonlyArray< T1 | T2 | … Tn >.
readonly mapped type modifiers and readonly arraysIn earlier versions of TypeScript, we generalized mapped types to operate differently on array-like types.\nThis meant that a mapped type like Boxify could work on arrays and tuples alike.
\ntsinterface Box<T> {\n value: T;\n}\n\ntype Boxify<T> = {\n [K in keyof T]: Box<T[K]>;\n};\n\n// { a: Box<string>, b: Box<number> }\ntype A = Boxify<{ a: string; b: number }>;\n\n// Array<Box<number>>\ntype B = Boxify<number[]>;\n\n// [Box<string>, Box<number>]\ntype C = Boxify<[string, boolean]>;
Unfortunately, mapped types like the Readonly utility type were effectively no-ops on array and tuple types.
\nts// lib.d.ts\ntype Readonly<T> = {\n readonly [K in keyof T]: T[K];\n};\n\n// How code acted *before* TypeScript 3.4\n\n// { readonly a: string, readonly b: number }\ntype A = Readonly<{ a: string; b: number }>;\n\n// number[]\ntype B = Readonly<number[]>;\n\n// [string, boolean]\ntype C = Readonly<[string, boolean]>;
In TypeScript 3.4, the readonly modifier in a mapped type will automatically convert array-like types to their corresponding readonly counterparts.
\nts// How code acts now *with* TypeScript 3.4\n\n// { readonly a: string, readonly b: number }\ntype A = Readonly<{ a: string; b: number }>;\n\n// readonly number[]\ntype B = Readonly<number[]>;\n\n// readonly [string, boolean]\ntype C = Readonly<[string, boolean]>;
Similarly, you could write a utility type like Writable mapped type that strips away readonly-ness, and that would convert readonly array containers back to their mutable equivalents.
\ntstype Writable<T> = {\n -readonly [K in keyof T]: T[K];\n};\n\n// { a: string, b: number }\ntype A = Writable<{\n readonly a: string;\n readonly b: number;\n}>;\n\n// number[]\ntype B = Writable<readonly number[]>;\n\n// [string, boolean]\ntype C = Writable<readonly [string, boolean]>;
Despite its appearance, the readonly type modifier can only be used for syntax on array types and tuple types.\nIt is not a general-purpose type operator.
\ntslet err1: readonly Set<number>; // error!\nlet err2: readonly Array<boolean>; // error!\n\nlet okay: readonly boolean[]; // works fine
You can see more details in the pull request.
\nconst assertionsTypeScript 3.4 introduces a new construct for literal values called const assertions.\nIts syntax is a type assertion with const in place of the type name (e.g. 123 as const).\nWhen we construct new literal expressions with const assertions, we can signal to the language that
\"hello\" to string)readonly propertiesreadonly tuples\nts// Type '\"hello\"'\nlet x = \"hello\" as const;\n\n// Type 'readonly [10, 20]'\nlet y = [10, 20] as const;\n\n// Type '{ readonly text: \"hello\" }'\nlet z = { text: \"hello\" } as const;
Outside of .tsx files, the angle bracket assertion syntax can also be used.
\nts// Type '\"hello\"'\nlet x = <const>\"hello\";\n\n// Type 'readonly [10, 20]'\nlet y = <const>[10, 20];\n\n// Type '{ readonly text: \"hello\" }'\nlet z = <const>{ text: \"hello\" };
This feature means that types that would otherwise be used just to hint immutability to the compiler can often be omitted.
\n\nts// Works with no types referenced or declared.\n// We only needed a single const assertion.\nfunction getShapes() {\n let result = [\n { kind: \"circle\", radius: 100 },\n { kind: \"square\", sideLength: 50 }\n ] as const;\n\n return result;\n}\n\nfor (const shape of getShapes()) {\n // Narrows perfectly!\n if (shape.kind === \"circle\") {\n console.log(\"Circle radius\", shape.radius);\n } else {\n console.log(\"Square side length\", shape.sideLength);\n }\n}
Notice the above needed no type annotations.\nThe const assertion allowed TypeScript to take the most specific type of the expression.
This can even be used to enable enum-like patterns in plain JavaScript code if you choose not to use TypeScript’s enum construct.
\ntsexport const Colors = {\n red: \"RED\",\n blue: \"BLUE\",\n green: \"GREEN\"\n} as const;\n\n// or use an 'export default'\n\nexport default {\n red: \"RED\",\n blue: \"BLUE\",\n green: \"GREEN\"\n} as const;
One thing to note is that const assertions can only be applied immediately on simple literal expressions.
\nts// Error! A 'const' assertion can only be applied to a\n// to a string, number, boolean, array, or object literal.\nlet a = (Math.random() < 0.5 ? 0 : 1) as const;\n\n// Works!\nlet b = Math.random() < 0.5 ? (0 as const) : (1 as const);
Another thing to keep in mind is that const contexts don’t immediately convert an expression to be fully immutable.
\ntslet arr = [1, 2, 3, 4];\n\nlet foo = {\n name: \"foo\",\n contents: arr\n} as const;\n\nfoo.name = \"bar\"; // error!\nfoo.contents = []; // error!\n\nfoo.contents.push(5); // ...works!
For more details, you can check out the respective pull request.
\nglobalThisTypeScript 3.4 introduces support for type-checking ECMAScript’s new globalThis - a global variable that, well, refers to the global scope.\nUnlike the above solutions, globalThis provides a standard way for accessing the global scope which can be used across different environments.
\nts// in a global file:\n\nvar abc = 100;\n\n// Refers to 'abc' from above.\nglobalThis.abc = 200;
Note that global variables declared with let and const don’t show up on globalThis.
\ntslet answer = 42;\n\n// error! Property 'answer' does not exist on 'typeof globalThis'.\nglobalThis.answer = 333333;
It’s also important to note that TypeScript doesn’t transform references to globalThis when compiling to older versions of ECMAScript.\nAs such, unless you’re targeting evergreen browsers (which already support globalThis), you may want to use an appropriate polyfill instead.
For more details on the implementation, see the feature’s pull request.
\nIn prior versions of TypeScript, unions of callable types could only be invoked if they had identical parameter lists.
\n\ntstype Fruit = \"apple\" | \"orange\";\ntype Color = \"red\" | \"orange\";\n\ntype FruitEater = (fruit: Fruit) => number; // eats and ranks the fruit\ntype ColorConsumer = (color: Color) => string; // consumes and describes the colors\n\ndeclare let f: FruitEater | ColorConsumer;\n\n// Cannot invoke an expression whose type lacks a call signature.\n// Type 'FruitEater | ColorConsumer' has no compatible call signatures.ts(2349)\nf(\"orange\");
However, in the above example, both FruitEaters and ColorConsumers should be able to take the string \"orange\", and return either a number or a string.
In TypeScript 3.3, this is no longer an error.
\n\ntstype Fruit = \"apple\" | \"orange\";\ntype Color = \"red\" | \"orange\";\n\ntype FruitEater = (fruit: Fruit) => number; // eats and ranks the fruit\ntype ColorConsumer = (color: Color) => string; // consumes and describes the colors\n\ndeclare let f: FruitEater | ColorConsumer;\n\nf(\"orange\"); // It works! Returns a 'number | string'.\n\nf(\"apple\"); // error - Argument of type '\"red\"' is not assignable to parameter of type '\"orange\"'.\n\nf(\"red\"); // error - Argument of type '\"red\"' is not assignable to parameter of type '\"orange\"'.
In TypeScript 3.3, the parameters of these signatures are intersected together to create a new signature.
\nIn the example above, the parameters fruit and color are intersected together to a new parameter of type Fruit & Color.\nFruit & Color is really the same as (\"apple\" | \"orange\") & (\"red\" | \"orange\") which is equivalent to (\"apple\" & \"red\") | (\"apple\" & \"orange\") | (\"orange\" & \"red\") | (\"orange\" & \"orange\").\nEach of those impossible intersections reduces to never, and we’re left with \"orange\" & \"orange\" which is just \"orange\".
This new behavior only kicks in when at most one type in the union has multiple overloads, and at most one type in the union has a generic signature.\nThat means methods on number[] | string[] like map (which is generic) still won’t be callable.
On the other hand, methods like forEach will now be callable, but under noImplicitAny there may be some issues.
\ntsinterface Dog {\n kind: \"dog\";\n dogProp: any;\n}\ninterface Cat {\n kind: \"cat\";\n catProp: any;\n}\n\nconst catOrDogArray: Dog[] | Cat[] = [];\n\ncatOrDogArray.forEach(animal => {\n // ~~~~~~ error!\n // Parameter 'animal' implicitly has an 'any' type.\n});
This is still strictly more capable in TypeScript 3.3, and adding an explicit type annotation will work.
\n\ntsinterface Dog {\n kind: \"dog\";\n dogProp: any;\n}\ninterface Cat {\n kind: \"cat\";\n catProp: any;\n}\n\nconst catOrDogArray: Dog[] | Cat[] = [];\ncatOrDogArray.forEach((animal: Dog | Cat) => {\n if (animal.kind === \"dog\") {\n animal.dogProp;\n // ...\n } else if (animal.kind === \"cat\") {\n animal.catProp;\n // ...\n }\n});
--build --watchTypeScript 3.0 introduced a new feature for structuring builds called “composite projects”.\nPart of the goal here was to ensure users could break up large projects into smaller parts that build quickly and preserve project structure, without compromising the existing TypeScript experience.\nThanks to composite projects, TypeScript can use --build mode to recompile only the set of projects and dependencies.\nYou can think of this as optimizing inter-project builds.
TypeScript 2.7 also introduced --watch mode builds via a new incremental “builder” API.\nIn a similar vein, the entire idea is that this mode only re-checks and re-emits changed files or files whose dependencies might impact type-checking.\nYou can think of this as optimizing intra-project builds.
Prior to 3.3, building composite projects using --build --watch actually didn’t use this incremental file watching infrastructure.\nAn update in one project under --build --watch mode would force a full build of that project, rather than determining which files within that project were affected.
In TypeScript 3.3, --build mode’s --watch flag does leverage incremental file watching as well.\nThat can mean signficantly faster builds under --build --watch.\nIn our testing, this functionality has resulted in a reduction of 50% to 75% in build times of the original --build --watch times.\nYou can read more on the original pull request for the change to see specific numbers, but we believe most composite project users will see significant wins here.
strictBindCallApplyTypeScript 3.2 introduces a new --strictBindCallApply compiler option (in the --strict family of options) with which the bind, call, and apply methods on function objects are strongly typed and strictly checked.
\ntsfunction foo(a: number, b: string): string {\n return a + b;\n}\n\nlet a = foo.apply(undefined, [10]); // error: too few argumnts\nlet b = foo.apply(undefined, [10, 20]); // error: 2nd argument is a number\nlet c = foo.apply(undefined, [10, \"hello\", 30]); // error: too many arguments\nlet d = foo.apply(undefined, [10, \"hello\"]); // okay! returns a string
This is achieved by introducing two new types, CallableFunction and NewableFunction, in lib.d.ts. These types contain specialized generic method declarations for bind, call, and apply for regular functions and constructor functions, respectively. The declarations use generic rest parameters (see #24897) to capture and reflect parameter lists in a strongly typed manner. In --strictBindCallApply mode these declarations are used in place of the (very permissive) declarations provided by type Function.
Since the stricter checks may uncover previously unreported errors, this is a breaking change in --strict mode.
Additionally, another caveat of this new functionality is that due to certain limitations, bind, call, and apply can’t yet fully model generic functions or functions that have overloads.\nWhen using these methods on a generic function, type parameters will be substituted with the empty object type ({}), and when used on a function with overloads, only the last overload will ever be modeled.
In TypeScript 3.2, object literals now allow generic spread expressions which now produce intersection types, similar to the Object.assign function and JSX literals. For example:
\ntsfunction taggedObject<T, U extends string>(obj: T, tag: U) {\n return { ...obj, tag }; // T & { tag: U }\n}\n\nlet x = taggedObject({ x: 10, y: 20 }, \"point\"); // { x: number, y: number } & { tag: \"point\" }
Property assignments and non-generic spread expressions are merged to the greatest extent possible on either side of a generic spread expression. For example:
\n\ntsfunction foo1<T>(t: T, obj1: { a: string }, obj2: { b: string }) {\n return { ...obj1, x: 1, ...t, ...obj2, y: 2 }; // { a: string, x: number } & T & { b: string, y: number }\n}
Non-generic spread expressions continue to be processed as before: Call and construct signatures are stripped, only non-method properties are preserved, and for properties with the same name, the type of the rightmost property is used. This contrasts with intersection types which concatenate call and construct signatures, preserve all properties, and intersect the types of properties with the same name. Thus, spreads of the same types may produce different results when they are created through instantiation of generic types:
\n\ntsfunction spread<T, U>(t: T, u: U) {\n return { ...t, ...u }; // T & U\n}\n\ndeclare let x: { a: string; b: number };\ndeclare let y: { b: string; c: boolean };\n\nlet s1 = { ...x, ...y }; // { a: string, b: string, c: boolean }\nlet s2 = spread(x, y); // { a: string, b: number } & { b: string, c: boolean }\nlet b1 = s1.b; // string\nlet b2 = s2.b; // number & string
TypeScript 3.2 also allows destructuring a rest binding from a generic variable. This is achieved by using the predefined Pick and Exclude helper types from lib.d.ts, and using the generic type in question as well as the names of the other bindings in the destructuring pattern.
\ntsfunction excludeTag<T extends { tag: string }>(obj: T) {\n let { tag, ...rest } = obj;\n return rest; // Pick<T, Exclude<keyof T, \"tag\">>\n}\n\nconst taggedPoint = { x: 10, y: 20, tag: \"point\" };\nconst point = excludeTag(taggedPoint); // { x: number, y: number }
BigInts are part of an upcoming proposal in ECMAScript that allow us to model theoretically arbitrarily large integers.\nTypeScript 3.2 brings type-checking for BigInts, as well as support for emitting BigInt literals when targeting esnext.
BigInt support in TypeScript introduces a new primitive type called the bigint (all lowercase).\nYou can get a bigint by calling the BigInt() function or by writing out a BigInt literal by adding an n to the end of any integer numeric literal:
\ntslet foo: bigint = BigInt(100); // the BigInt function\nlet bar: bigint = 100n; // a BigInt literal\n\n// *Slaps roof of fibonacci function*\n// This bad boy returns ints that can get *so* big!\nfunction fibonacci(n: bigint) {\n let result = 1n;\n for (let last = 0n, i = 0n; i < n; i++) {\n const current = result;\n result += last;\n last = current;\n }\n return result;\n}\n\nfibonacci(10000n);
While you might imagine close interaction between number and bigint, the two are separate domains.
\ntsdeclare let foo: number;\ndeclare let bar: bigint;\n\nfoo = bar; // error: Type 'bigint' is not assignable to type 'number'.\nbar = foo; // error: Type 'number' is not assignable to type 'bigint'.
As specified in ECMAScript, mixing numbers and bigints in arithmetic operations is an error.\nYou’ll have to explicitly convert values to BigInts.
\ntsconsole.log(3.141592 * 10000n); // error\nconsole.log(3145 * 10n); // error\nconsole.log(BigInt(3145) * 10n); // okay!
Also important to note is that bigints produce a new string when using the typeof operator: the string \"bigint\".\nThus, TypeScript correctly narrows using typeof as you’d expect.
\ntsfunction whatKindOfNumberIsIt(x: number | bigint) {\n if (typeof x === \"bigint\") {\n console.log(\"'x' is a bigint!\");\n } else {\n console.log(\"'x' is a floating-point number\");\n }\n}
We’d like to extend a huge thanks to Caleb Sander for all the work on this feature.\nWe’re grateful for the contribution, and we’re sure our users are too!
\nAs we mentioned, BigInt support is only available for the esnext target.\nIt may not be obvious, but because BigInts have different behavior for mathematical operators like +, -, *, etc., providing functionality for older targets where the feature doesn’t exist (like es2017 and below) would involve rewriting each of these operations.\nTypeScript would need to dispatch to the correct behavior depending on the type, and so every addition, string concatenation, multiplication, etc. would involve a function call.
For that reason, we have no immediate plans to provide downleveling support.\nOn the bright side, Node 11 and newer versions of Chrome already support this feature, so you’ll be able to use BigInts there when targeting esnext.
Certain targets may include a polyfill or BigInt-like runtime object.\nFor those purposes you may want to add esnext.bigint to the lib setting in your compiler options.
TypeScript 3.2 makes narrowing easier by relaxing rules for what it considers a discriminant property.\nCommon properties of unions are now considered discriminants as long as they contain some singleton type (e.g. a string literal, null, or undefined), and they contain no generics.
As a result, TypeScript 3.2 considers the error property in the following example to be a discriminant, whereas before it wouldn’t since Error isn’t a singleton type.\nThanks to this, narrowing works correctly in the body of the unwrap function.
\ntstype Result<T> = { error: Error; data: null } | { error: null; data: T };\n\nfunction unwrap<T>(result: Result<T>) {\n if (result.error) {\n // Here 'error' is non-null\n throw result.error;\n }\n\n // Now 'data' is non-null\n return result.data;\n}
tsconfig.json inheritance via Node.js packagesTypeScript 3.2 now resolves tsconfig.jsons from node_modules. When using a bare path for the \"extends\" field in tsconfig.json, TypeScript will dive into node_modules packages for us.
\njson{\n \"extends\": \"@my-team/tsconfig-base\",\n \"include\": [\"./**/*\"]\n \"compilerOptions\": {\n // Override certain options on a project-by-project basis.\n \"strictBindCallApply\": false,\n }\n}
Here, TypeScript will climb up node_modules folders looking for a @my-team/tsconfig-base package. For each of those packages, TypeScript will first check whether package.json contains a \"tsconfig\" field, and if it does, TypeScript will try to load a configuration file from that field. If neither exists, TypeScript will try to read from a tsconfig.json at the root. This is similar to the lookup process for .js files in packages that Node uses, and the .d.ts lookup process that TypeScript already uses.
This feature can be extremely useful for bigger organizations, or projects with lots of distributed dependencies.
\n--showConfig flagtsc, the TypeScript compiler, supports a new flag called --showConfig.\nWhen running tsc --showConfig, TypeScript will calculate the effective tsconfig.json (after calculating options inherited from the extends field) and print that out.\nThis can be useful for diagnosing configuration issues in general.
Object.defineProperty declarations in JavaScriptWhen writing in JavaScript files (using allowJs), TypeScript now recognizes declarations that use Object.defineProperty.\nThis means you’ll get better completions, and stronger type-checking when enabling type-checking in JavaScript files (by turning on the checkJs option or adding a // @ts-check comment to the top of your file).
\njs// @ts-check\n\nlet obj = {};\nObject.defineProperty(obj, \"x\", { value: \"hello\", writable: false });\n\nobj.x.toLowercase();\n// ~~~~~~~~~~~\n// error:\n// Property 'toLowercase' does not exist on type 'string'.\n// Did you mean 'toLowerCase'?\n\nobj.x = \"world\";\n// ~\n// error:\n// Cannot assign to 'x' because it is a read-only property.
In TypeScript 3.1, mapped object types[1] over tuples and arrays now produce new tuples/arrays, rather than creating a new type where members like push(), pop(), and length are converted.\nFor example:
\ntstype MapToPromise<T> = { [K in keyof T]: Promise<T[K]> };\n\ntype Coordinate = [number, number];\n\ntype PromiseCoordinate = MapToPromise<Coordinate>; // [Promise<number>, Promise<number>]
MapToPromise takes a type T, and when that type is a tuple like Coordinate, only the numeric properties are converted.\nIn [number, number], there are two numerically named properties: 0 and 1.\nWhen given a tuple like that, MapToPromise will create a new tuple where the 0 and 1 properties are Promises of the original type.\nSo the resulting type PromiseCoordinate ends up with the type [Promise<number>, Promise<number>].
TypeScript 3.1 brings the ability to define properties on function declarations and const-declared functons, simply by assigning to properties on these functions in the same scope.\nThis allows us to write canonical JavaScript code without resorting to namespace hacks.\nFor example:
\ntsfunction readImage(path: string, callback: (err: any, image: Image) => void) {\n // ...\n}\n\nreadImage.sync = (path: string) => {\n const contents = fs.readFileSync(path);\n return decodeImageSync(contents);\n};
Here, we have a function readImage which reads an image in a non-blocking asynchronous way.\nIn addition to readImage, we’ve provided a convenience function on readImage itself called readImage.sync.
While ECMAScript exports are often a better way of providing this functionality, this new support allows code written in this style to “just work” TypeScript.\nAdditionaly, this approach for property declarations allows us to express common patterns like defaultProps and propTypes on React stateless function components (SFCs).
\n\ntsexport const FooComponent = ({ name }) => <div>Hello! I am {name}</div>;\n\nFooComponent.defaultProps = {\n name: \"(anonymous)\"\n};
[1] More specifically, homomorphic mapped types like in the above form.
\ntypesVersionsFeedback from our community, as well as our own experience, has shown us that leveraging the newest TypeScript features while also accomodating users on the older versions are difficult.\nTypeScript introduces a new feature called typesVersions to help accomodate these scenarios.
When using Node module resolution in TypeScript 3.1, when TypeScript cracks open a package.json file to figure out which files it needs to read, it first looks at a new field called typesVersions.\nA package.json with a typesVersions field might look like this:
\njson{\n \"name\": \"package-name\",\n \"version\": \"1.0\",\n \"types\": \"./index.d.ts\",\n \"typesVersions\": {\n \">=3.1\": { \"*\": [\"ts3.1/*\"] }\n }\n}
This package.json tells TypeScript to check whether the current version of TypeScript is running.\nIf it’s 3.1 or later, it figures out the path you’ve imported relative to the package, and reads from the package’s ts3.1 folder.\nThat’s what that { \"*\": [\"ts3.1/*\"] } means - if you’re familiar with path mapping today, it works exactly like that.
So in the above example, if we’re importing from \"package-name\", we’ll try to resolve from [...]/node_modules/package-name/ts3.1/index.d.ts (and other relevant paths) when running in TypeScript 3.1.\nIf we import from package-name/foo, we’ll try to look for [...]/node_modules/package-name/ts3.1/foo.d.ts and [...]/node_modules/package-name/ts3.1/foo/index.d.ts.
What if we’re not running in TypeScript 3.1 in this example?\nWell, if none of the fields in typesVersions get matched, TypeScript falls back to the types field, so here TypeScript 3.0 and earlier will be redirected to [...]/node_modules/package-name/index.d.ts.
The way that TypeScript decides on whether a version of the compiler & language matches is by using Node’s semver ranges.
\ntypesVersions can support multiple fields where each field name is specified by the range to match on.
\njson{\n \"name\": \"package-name\",\n \"version\": \"1.0\",\n \"types\": \"./index.d.ts\",\n \"typesVersions\": {\n \">=3.2\": { \"*\": [\"ts3.2/*\"] },\n \">=3.1\": { \"*\": [\"ts3.1/*\"] }\n }\n}
Since ranges have the potential to overlap, determining which redirect applies is order-specific.\nThat means in the above example, even though both the >=3.2 and the >=3.1 matchers support TypeScript 3.2 and above, reversing the order could have different behavior, so the above sample would not be equivalent to the following.
\njson{\n name: \"package-name\",\n version: \"1.0\",\n types: \"./index.d.ts\",\n typesVersions: {\n // NOTE: this doesn't work!\n \">=3.1\": { \"*\": [\"ts3.1/*\"] },\n \">=3.2\": { \"*\": [\"ts3.2/*\"] }\n }\n}
TypeScript 3.0 adds support to multiple new capabilities to interact with function parameter lists as tuple types.\nTypeScript 3.0 adds support for:
\nWith these features it becomes possible to strongly type a number of higher-order functions that transform functions and their parameter lists.
\nWhen a rest parameter has a tuple type, the tuple type is expanded into a sequence of discrete parameters.\nFor example the following two declarations are equivalent:
\n\ntsdeclare function foo(...args: [number, string, boolean]): void;
\ntsdeclare function foo(args_0: number, args_1: string, args_2: boolean): void;
When a function call includes a spread expression of a tuple type as the last argument, the spread expression corresponds to a sequence of discrete arguments of the tuple element types.
\nThus, the following calls are equivalent:
\n\ntsconst args: [number, string, boolean] = [42, \"hello\", true];\nfoo(42, \"hello\", true);\nfoo(args[0], args[1], args[2]);\nfoo(...args);
A rest parameter is permitted to have a generic type that is constrained to an array type, and type inference can infer tuple types for such generic rest parameters. This enables higher-order capturing and spreading of partial parameter lists:
\n\ntsdeclare function bind<T, U extends any[], V>(\n f: (x: T, ...args: U) => V,\n x: T\n): (...args: U) => V;\n\ndeclare function f3(x: number, y: string, z: boolean): void;\n\nconst f2 = bind(f3, 42); // (y: string, z: boolean) => void\nconst f1 = bind(f2, \"hello\"); // (z: boolean) => void\nconst f0 = bind(f1, true); // () => void\n\nf3(42, \"hello\", true);\nf2(\"hello\", true);\nf1(true);\nf0();
In the declaration of f2 above, type inference infers types number, [string, boolean] and void for T, U and V respectively.
Note that when a tuple type is inferred from a sequence of parameters and later expanded into a parameter list, as is the case for U, the original parameter names are used in the expansion (however, the names have no semantic meaning and are not otherwise observable).
Tuple types now permit a ? postfix on element types to indicate that the element is optional:
\ntslet t: [number, string?, boolean?];\nt = [42, \"hello\", true];\nt = [42, \"hello\"];\nt = [42];
In --strictNullChecks mode, a ? modifier automatically includes undefined in the element type, similar to optional parameters.
A tuple type permits an element to be omitted if it has a postfix ? modifier on its type and all elements to the right of it also have ? modifiers.
When tuple types are inferred for rest parameters, optional parameters in the source become optional tuple elements in the inferred type.
\nThe length property of a tuple type with optional elements is a union of numeric literal types representing the possible lengths.\nFor example, the type of the length property in the tuple type [number, string?, boolean?] is 1 | 2 | 3.
The last element of a tuple type can be a rest element of the form ...X, where X is an array type.\nA rest element indicates that the tuple type is open-ended and may have zero or more additional elements of the array element type.\nFor example, [number, ...string[]] means tuples with a number element followed by any number of string elements.
\ntsfunction tuple<T extends any[]>(...args: T): T {\n return args;\n}\n\nconst numbers: number[] = getArrayOfNumbers();\nconst t1 = tuple(\"foo\", 1, true); // [string, number, boolean]\nconst t2 = tuple(\"bar\", ...numbers); // [string, ...number[]]
The type of the length property of a tuple type with a rest element is number.
unknown top typeTypeScript 3.0 introduces a new top type unknown.\nunknown is the type-safe counterpart of any.\nAnything is assignable to unknown, but unknown isn’t assignable to anything but itself and any without a type assertion or a control flow based narrowing.\nLikewise, no operations are permitted on an unknown without first asserting or narrowing to a more specific type.
\nts// In an intersection everything absorbs unknown\n\ntype T00 = unknown & null; // null\ntype T01 = unknown & undefined; // undefined\ntype T02 = unknown & null & undefined; // null & undefined (which becomes never)\ntype T03 = unknown & string; // string\ntype T04 = unknown & string[]; // string[]\ntype T05 = unknown & unknown; // unknown\ntype T06 = unknown & any; // any\n\n// In a union an unknown absorbs everything\n\ntype T10 = unknown | null; // unknown\ntype T11 = unknown | undefined; // unknown\ntype T12 = unknown | null | undefined; // unknown\ntype T13 = unknown | string; // unknown\ntype T14 = unknown | string[]; // unknown\ntype T15 = unknown | unknown; // unknown\ntype T16 = unknown | any; // any\n\n// Type variable and unknown in union and intersection\n\ntype T20<T> = T & {}; // T & {}\ntype T21<T> = T | {}; // T | {}\ntype T22<T> = T & unknown; // T\ntype T23<T> = T | unknown; // unknown\n\n// unknown in conditional types\n\ntype T30<T> = unknown extends T ? true : false; // Deferred\ntype T31<T> = T extends unknown ? true : false; // Deferred (so it distributes)\ntype T32<T> = never extends T ? true : false; // true\ntype T33<T> = T extends never ? true : false; // Deferred\n\n// keyof unknown\n\ntype T40 = keyof any; // string | number | symbol\ntype T41 = keyof unknown; // never\n\n// Only equality operators are allowed with unknown\n\nfunction f10(x: unknown) {\n x == 5;\n x !== 10;\n x >= 0; // Error\n x + 1; // Error\n x * 2; // Error\n -x; // Error\n +x; // Error\n}\n\n// No property accesses, element accesses, or function calls\n\nfunction f11(x: unknown) {\n x.foo; // Error\n x[5]; // Error\n x(); // Error\n new x(); // Error\n}\n\n// typeof, instanceof, and user defined type predicates\n\ndeclare function isFunction(x: unknown): x is Function;\n\nfunction f20(x: unknown) {\n if (typeof x === \"string\" || typeof x === \"number\") {\n x; // string | number\n }\n if (x instanceof Error) {\n x; // Error\n }\n if (isFunction(x)) {\n x; // Function\n }\n}\n\n// Homomorphic mapped type over unknown\n\ntype T50<T> = { [P in keyof T]: number };\ntype T51 = T50<any>; // { [x: string]: number }\ntype T52 = T50<unknown>; // {}\n\n// Anything is assignable to unknown\n\nfunction f21<T>(pAny: any, pNever: never, pT: T) {\n let x: unknown;\n x = 123;\n x = \"hello\";\n x = [1, 2, 3];\n x = new Error();\n x = x;\n x = pAny;\n x = pNever;\n x = pT;\n}\n\n// unknown assignable only to itself and any\n\nfunction f22(x: unknown) {\n let v1: any = x;\n let v2: unknown = x;\n let v3: object = x; // Error\n let v4: string = x; // Error\n let v5: string[] = x; // Error\n let v6: {} = x; // Error\n let v7: {} | null | undefined = x; // Error\n}\n\n// Type parameter 'T extends unknown' not related to object\n\nfunction f23<T extends unknown>(x: T) {\n let y: object = x; // Error\n}\n\n// Anything but primitive assignable to { [x: string]: unknown }\n\nfunction f24(x: { [x: string]: unknown }) {\n x = {};\n x = { a: 5 };\n x = [1, 2, 3];\n x = 123; // Error\n}\n\n// Locals of type unknown always considered initialized\n\nfunction f25() {\n let x: unknown;\n let y = x;\n}\n\n// Spread of unknown causes result to be unknown\n\nfunction f26(x: {}, y: unknown, z: any) {\n let o1 = { a: 42, ...x }; // { a: number }\n let o2 = { a: 42, ...x, ...y }; // unknown\n let o3 = { a: 42, ...x, ...y, ...z }; // any\n}\n\n// Functions with unknown return type don't need return expressions\n\nfunction f27(): unknown {}\n\n// Rest type cannot be created from unknown\n\nfunction f28(x: unknown) {\n let { ...a } = x; // Error\n}\n\n// Class properties of type unknown don't need definite assignment\n\nclass C1 {\n a: string; // Error\n b: unknown;\n c: any;\n}
defaultProps in JSXTypeScript 2.9 and earlier didn’t leverage React defaultProps declarations inside JSX components.\nUsers would often have to declare properties optional and use non-null assertions inside of render, or they’d use type-assertions to fix up the type of the component before exporting it.
TypeScript 3.0 adds supports a new type alias in the JSX namespace called LibraryManagedAttributes.\nThis helper type defines a transformation on the component’s Props type, before using to check a JSX expression targeting it; thus allowing customization like: how conflicts between provided props and inferred props are handled, how inferences are mapped, how optionality is handled, and how inferences from differing places should be combined.
In short using this general type, we can model React’s specific behavior for things like defaultProps and, to some extent, propTypes.
\ntsxexport interface Props {\n name: string;\n}\n\nexport class Greet extends React.Component<Props> {\n render() {\n const { name } = this.props;\n return <div>Hello ${name.toUpperCase()}!</div>;\n }\n static defaultProps = { name: \"world\" };\n}\n\n// Type-checks! No type assertions needed!\nlet el = <Greet />;
defaultPropsThe default-ed properties are inferred from the defaultProps property type. If an explicit type annotation is added, e.g. static defaultProps: Partial<Props>; the compiler will not be able to identify which properties have defaults (since the type of defaultProps include all properties of Props).
Use static defaultProps: Pick<Props, \"name\">; as an explicit type annotation instead, or do not add a type annotation as done in the example above.
For stateless function components (SFCs) use ES2015 default initializers for SFCs:
\n\ntsxfunction Greet({ name = \"world\" }: Props) {\n return <div>Hello ${name.toUpperCase()}!</div>;\n}
@types/ReactCorresponding changes to add LibraryManagedAttributes definition to the JSX namespace in @types/React are still needed.\nKeep in mind that there are some limitations.
/// <reference lib=\"...\" /> reference directivesTypeScript adds a new triple-slash-reference directive (/// <reference lib=\"name\" />), allowing a file to explicitly include an existing built-in lib file.
Built-in lib files are referenced in the same fashion as the \"lib\" compiler option in tsconfig.json (e.g. use lib=\"es2015\" and not lib=\"lib.es2015.d.ts\", etc.).
For declaration file authors who rely on built-in types, e.g. DOM APIs or built-in JS run-time constructors like Symbol or Iterable, triple-slash-reference lib directives are the recommended. Previously these .d.ts files had to add forward/duplicate declarations of such types.
Using /// <reference lib=\"es2017.string\" /> to one of the files in a compilation is equivalent to compiling with --lib es2017.string.
\nts/// <reference lib=\"es2017.string\" />\n\n\"foo\".padStart(4);
number and symbol named properties with keyof and mapped typesTypeScript 2.9 adds support for number and symbol named properties in index types and mapped types.\nPreviously, the keyof operator and mapped types only supported string named properties.
Changes include:
\nkeyof T for some type T is a subtype of string | number | symbol.{ [P in K]: XXX } permits any K assignable to string | number | symbol.for...in statement for an object of a generic type T, the inferred type of the iteration variable was previously keyof T but is now Extract<keyof T, string>. (In other words, the subset of keyof T that includes only string-like values.)Given an object type X, keyof X is resolved as follows:
X contains a string index signature, keyof X is a union of string, number, and the literal types representing symbol-like properties, otherwiseX contains a numeric index signature, keyof X is a union of number and the literal types representing string-like and symbol-like properties, otherwisekeyof X is a union of the literal types representing string-like, number-like, and symbol-like properties.Where:
\nIn a mapped type { [P in K]: XXX }, each string literal type in K introduces a property with a string name, each numeric literal type in K introduces a property with a numeric name, and each unique symbol type in K introduces a property with a unique symbol name.\nFurthermore, if K includes type string, a string index signature is introduced, and if K includes type number, a numeric index signature is introduced.
\ntsconst c = \"c\";\nconst d = 10;\nconst e = Symbol();\n\nconst enum E1 {\n A,\n B,\n C\n}\nconst enum E2 {\n A = \"A\",\n B = \"B\",\n C = \"C\"\n}\n\ntype Foo = {\n a: string; // String-like name\n 5: string; // Number-like name\n [c]: string; // String-like name\n [d]: string; // Number-like name\n [e]: string; // Symbol-like name\n [E1.A]: string; // Number-like name\n [E2.A]: string; // String-like name\n};\n\ntype K1 = keyof Foo; // \"a\" | 5 | \"c\" | 10 | typeof e | E1.A | E2.A\ntype K2 = Extract<keyof Foo, string>; // \"a\" | \"c\" | E2.A\ntype K3 = Extract<keyof Foo, number>; // 5 | 10 | E1.A\ntype K4 = Extract<keyof Foo, symbol>; // typeof e
Since keyof now reflects the presence of a numeric index signature by including type number in the key type, mapped types such as Partial<T> and Readonly<T> work correctly when applied to object types with numeric index signatures:
\ntstype Arrayish<T> = {\n length: number;\n [x: number]: T;\n};\n\ntype ReadonlyArrayish<T> = Readonly<Arrayish<T>>;\n\ndeclare const map: ReadonlyArrayish<string>;\nlet n = map.length;\nlet x = map[123]; // Previously of type any (or an error with --noImplicitAny)
Furthermore, with the keyof operator’s support for number and symbol named keys, it is now possible to abstract over access to properties of objects that are indexed by numeric literals (such as numeric enum types) and unique symbols.
\ntsconst enum Enum {\n A,\n B,\n C\n}\n\nconst enumToStringMap = {\n [Enum.A]: \"Name A\",\n [Enum.B]: \"Name B\",\n [Enum.C]: \"Name C\"\n};\n\nconst sym1 = Symbol();\nconst sym2 = Symbol();\nconst sym3 = Symbol();\n\nconst symbolToNumberMap = {\n [sym1]: 1,\n [sym2]: 2,\n [sym3]: 3\n};\n\ntype KE = keyof typeof enumToStringMap; // Enum (i.e. Enum.A | Enum.B | Enum.C)\ntype KS = keyof typeof symbolToNumberMap; // typeof sym1 | typeof sym2 | typeof sym3\n\nfunction getValue<T, K extends keyof T>(obj: T, key: K): T[K] {\n return obj[key];\n}\n\nlet x1 = getValue(enumToStringMap, Enum.C); // Returns \"Name C\"\nlet x2 = getValue(symbolToNumberMap, sym3); // Returns 3
This is a breaking change; previously, the keyof operator and mapped types only supported string named properties.\nCode that assumed values typed with keyof T were always strings, will now be flagged as error.
\ntsfunction useKey<T, K extends keyof T>(o: T, k: K) {\n var name: string = k; // Error: keyof T is not assignable to string\n}
If your functions are only able to handle string named property keys, use Extract<keyof T, string> in the declaration:
\ntsfunction useKey<T, K extends Extract<keyof T, string>>(o: T, k: K) {\nvar name: string = k; // OK\n}
If your functions are open to handling all property keys, then the changes should be done down-stream:
\n\ntsfunction useKey<T, K extends keyof T>(o: T, k: K) {\nvar name: string | number | symbol = k;\n}
--keyofStringsOnly compiler option to disable the new behavior.JSX elements now allow passing type arguments to generic components.
\n\ntsclass GenericComponent<P> extends React.Component<P> {\n internalProp: P;\n}\n\ntype Props = { a: number; b: string };\n\nconst x = <GenericComponent<Props> a={10} b=\"hi\" />; // OK\n\nconst y = <GenericComponent<Props> a={10} b={20} />; // Error
Tagged templates are a form of invocation introduced in ECMAScript 2015.\nLike call expressions, generic functions may be used in a tagged template and TypeScript will infer the type arguments utilized.
\nTypeScript 2.9 allows passing generic type arguments to tagged template strings.
\n\ntsdeclare function styledComponent<Props>(\n strs: TemplateStringsArray\n): Component<Props>;\n\ninterface MyProps {\n name: string;\n age: number;\n}\n\nstyledComponent<MyProps>`\n font-size: 1.5em;\n text-align: center;\n color: palevioletred;\n`;\n\ndeclare function tag<T>(strs: TemplateStringsArray, ...args: T[]): T;\n\n// inference fails because 'number' and 'string' are both candidates that conflict\nlet a = tag<string | number>`${100} ${\"hello\"}`;
import typesModules can import types declared in other modules. But non-module global scripts cannot access types declared in modules. Enter import types.
Using import(\"mod\") in a type annotation allows for reaching in a module and accessing its exported declaration without importing it.
Given a declaration of a class Pet in a module file:
\nts// module.d.ts\n\nexport declare class Pet {\n name: string;\n}
Can be used in a non-module file global-script.ts:
\nts// global-script.ts\n\nfunction adopt(p: import(\"./module\").Pet) {\n console.log(`Adopting ${p.name}...`);\n}
This also works in JSDoc comments to refer to types from other modules in .js:
\njs// a.js\n\n/**\n * @param p { import(\"./module\").Pet }\n */\nfunction walk(p) {\n console.log(`Walking ${p.name}...`);\n}
With import types available, many of the visibility errors reported during declaration file generation can be handled by the compiler without the need to change the input.
For instance:
\n\ntsimport { createHash } from \"crypto\";\n\nexport const hash = createHash(\"sha256\");\n// ^^^^\n// Exported variable 'hash' has or is using name 'Hash' from external module \"crypto\" but cannot be named.
With TypeScript 2.9, no errors are reported, and now the generated file looks like:
\n\ntsexport declare const hash: import(\"crypto\").Hash;
import.metaTypeScript 2.9 introduces support for import.meta, a new meta-property as described by the current TC39 proposal.
The type of import.meta is the global ImportMeta type which is defined in lib.es5.d.ts.\nThis interface is extremely limited.\nAdding well-known properties for Node or browsers requires interface merging and possibly a global augmentation depending on the context.
Assuming that __dirname is always available on import.meta, the declaration would be done through reopening ImportMeta interface:
\nts// node.d.ts\ninterface ImportMeta {\n __dirname: string;\n}
And usage would be:
\n\ntsimport.meta.__dirname; // Has type 'string'
import.meta is only allowed when targeting ESNext modules and ECMAScript targets.
--resolveJsonModuleOften in Node.js applications a .json is needed. With TypeScript 2.9, --resolveJsonModule allows for importing, extracting types from and generating .json files.
\nts// settings.json\n\n{\n \"repo\": \"TypeScript\",\n \"dry\": false,\n \"debug\": false\n}
\nts// a.ts\n\nimport settings from \"./settings.json\";\n\nsettings.debug === true; // OK\nsettings.dry === 2; // Error: Operator '===' cannot be applied boolean and number
\nts// tsconfig.json\n\n{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"resolveJsonModule\": true,\n \"esModuleInterop\": true\n }\n}
--pretty output by defaultStarting TypeScript 2.9 errors are displayed under --pretty by default if the output device is applicable for colorful text.\nTypeScript will check if the output steam has isTty property set.
Use --pretty false on the command line or set \"pretty\": false in your tsconfig.json to disable --pretty output.
--declarationMapEnabling --declarationMap alongside --declaration causes the compiler to emit .d.ts.map files alongside the output .d.ts files.\nLanguage Services can also now understand these map files, and uses them to map declaration-file based definition locations to their original source, when available.
In other words, hitting go-to-definition on a declaration from a .d.ts file generated with --declarationMap will take you to the source file (.ts) location where that declaration was defined, and not to the .d.ts.
TypeScript 2.8 introduces conditional types which add the ability to express non-uniform type mappings.\nA conditional type selects one of two possible types based on a condition expressed as a type relationship test:
\n\ntsT extends U ? X : Y
The type above means when T is assignable to U the type is X, otherwise the type is Y.
A conditional type T extends U ? X : Y is either resolved to X or Y, or deferred because the condition depends on one or more type variables.\nWhether to resolve or defer is determined as follows:
T' and U' that are instantiations of T and U where all occurrences of type parameters are replaced with any, if T' is not assignable to U', the conditional type is resolved to Y. Intuitively, if the most permissive instantiation of T is not assignable to the most permissive instantiation of U, we know that no instantiation will be and we can just resolve to Y.infer (more later) declaration within U collect a set of candidate types by inferring from T to U (using the same inference algorithm as type inference for generic functions). For a given infer type variable V, if any candidates were inferred from co-variant positions, the type inferred for V is a union of those candidates. Otherwise, if any candidates were inferred from contra-variant positions, the type inferred for V is an intersection of those candidates. Otherwise, the type inferred for V is never.T'' that is an instantiation of T where all infer type variables are replaced with the types inferred in the previous step, if T'' is definitely assignable to U, the conditional type is resolved to X. The definitely assignable relation is the same as the regular assignable relation, except that type variable constraints are not considered. Intuitively, when a type is definitely assignable to another type, we know that it will be assignable for all instantiations of those types.\ntstype TypeName<T> = T extends string\n ? \"string\"\n : T extends number\n ? \"number\"\n : T extends boolean\n ? \"boolean\"\n : T extends undefined\n ? \"undefined\"\n : T extends Function\n ? \"function\"\n : \"object\";\n\ntype T0 = TypeName<string>; // \"string\"\ntype T1 = TypeName<\"a\">; // \"string\"\ntype T2 = TypeName<true>; // \"boolean\"\ntype T3 = TypeName<() => void>; // \"function\"\ntype T4 = TypeName<string[]>; // \"object\"
Conditional types in which the checked type is a naked type parameter are called distributive conditional types.\nDistributive conditional types are automatically distributed over union types during instantiation.\nFor example, an instantiation of T extends U ? X : Y with the type argument A | B | C for T is resolved as (A extends U ? X : Y) | (B extends U ? X : Y) | (C extends U ? X : Y).
\ntstype T10 = TypeName<string | (() => void)>; // \"string\" | \"function\"\ntype T12 = TypeName<string | string[] | undefined>; // \"string\" | \"object\" | \"undefined\"\ntype T11 = TypeName<string[] | number[]>; // \"object\"
In instantiations of a distributive conditional type T extends U ? X : Y, references to T within the conditional type are resolved to individual constituents of the union type (i.e. T refers to the individual constituents after the conditional type is distributed over the union type).\nFurthermore, references to T within X have an additional type parameter constraint U (i.e. T is considered assignable to U within X).
\ntstype BoxedValue<T> = { value: T };\ntype BoxedArray<T> = { array: T[] };\ntype Boxed<T> = T extends any[] ? BoxedArray<T[number]> : BoxedValue<T>;\n\ntype T20 = Boxed<string>; // BoxedValue<string>;\ntype T21 = Boxed<number[]>; // BoxedArray<number>;\ntype T22 = Boxed<string | number[]>; // BoxedValue<string> | BoxedArray<number>;
Notice that T has the additional constraint any[] within the true branch of Boxed<T> and it is therefore possible to refer to the element type of the array as T[number]. Also, notice how the conditional type is distributed over the union type in the last example.
The distributive property of conditional types can conveniently be used to filter union types:
\n\ntstype Diff<T, U> = T extends U ? never : T; // Remove types from T that are assignable to U\ntype Filter<T, U> = T extends U ? T : never; // Remove types from T that are not assignable to U\n\ntype T30 = Diff<\"a\" | \"b\" | \"c\" | \"d\", \"a\" | \"c\" | \"f\">; // \"b\" | \"d\"\ntype T31 = Filter<\"a\" | \"b\" | \"c\" | \"d\", \"a\" | \"c\" | \"f\">; // \"a\" | \"c\"\ntype T32 = Diff<string | number | (() => void), Function>; // string | number\ntype T33 = Filter<string | number | (() => void), Function>; // () => void\n\ntype NonNullable<T> = Diff<T, null | undefined>; // Remove null and undefined from T\n\ntype T34 = NonNullable<string | number | undefined>; // string | number\ntype T35 = NonNullable<string | string[] | null | undefined>; // string | string[]\n\nfunction f1<T>(x: T, y: NonNullable<T>) {\n x = y; // Ok\n y = x; // Error\n}\n\nfunction f2<T extends string | undefined>(x: T, y: NonNullable<T>) {\n x = y; // Ok\n y = x; // Error\n let s1: string = x; // Error\n let s2: string = y; // Ok\n}
Conditional types are particularly useful when combined with mapped types:
\n\ntstype FunctionPropertyNames<T> = {\n [K in keyof T]: T[K] extends Function ? K : never;\n}[keyof T];\ntype FunctionProperties<T> = Pick<T, FunctionPropertyNames<T>>;\n\ntype NonFunctionPropertyNames<T> = {\n [K in keyof T]: T[K] extends Function ? never : K;\n}[keyof T];\ntype NonFunctionProperties<T> = Pick<T, NonFunctionPropertyNames<T>>;\n\ninterface Part {\n id: number;\n name: string;\n subparts: Part[];\n updatePart(newName: string): void;\n}\n\ntype T40 = FunctionPropertyNames<Part>; // \"updatePart\"\ntype T41 = NonFunctionPropertyNames<Part>; // \"id\" | \"name\" | \"subparts\"\ntype T42 = FunctionProperties<Part>; // { updatePart(newName: string): void }\ntype T43 = NonFunctionProperties<Part>; // { id: number, name: string, subparts: Part[] }
Similar to union and intersection types, conditional types are not permitted to reference themselves recursively. For example the following is an error.
\n\ntstype ElementType<T> = T extends any[] ? ElementType<T[number]> : T; // Error
Within the extends clause of a conditional type, it is now possible to have infer declarations that introduce a type variable to be inferred.\nSuch inferred type variables may be referenced in the true branch of the conditional type.\nIt is possible to have multiple infer locations for the same type variable.
For example, the following extracts the return type of a function type:
\n\ntstype ReturnType<T> = T extends (...args: any[]) => infer R ? R : any;
Conditional types can be nested to form a sequence of pattern matches that are evaluated in order:
\n\ntstype Unpacked<T> = T extends (infer U)[]\n ? U\n : T extends (...args: any[]) => infer U\n ? U\n : T extends Promise<infer U>\n ? U\n : T;\n\ntype T0 = Unpacked<string>; // string\ntype T1 = Unpacked<string[]>; // string\ntype T2 = Unpacked<() => string>; // string\ntype T3 = Unpacked<Promise<string>>; // string\ntype T4 = Unpacked<Promise<string>[]>; // Promise<string>\ntype T5 = Unpacked<Unpacked<Promise<string>[]>>; // string
The following example demonstrates how multiple candidates for the same type variable in co-variant positions causes a union type to be inferred:
\n\ntstype Foo<T> = T extends { a: infer U; b: infer U } ? U : never;\ntype T10 = Foo<{ a: string; b: string }>; // string\ntype T11 = Foo<{ a: string; b: number }>; // string | number
Likewise, multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred:
\n\ntstype Bar<T> = T extends { a: (x: infer U) => void; b: (x: infer U) => void }\n ? U\n : never;\ntype T20 = Bar<{ a: (x: string) => void; b: (x: string) => void }>; // string\ntype T21 = Bar<{ a: (x: string) => void; b: (x: number) => void }>; // string & number
When inferring from a type with multiple call signatures (such as the type of an overloaded function), inferences are made from the last signature (which, presumably, is the most permissive catch-all case).\nIt is not possible to perform overload resolution based on a list of argument types.
\n\ntsdeclare function foo(x: string): number;\ndeclare function foo(x: number): string;\ndeclare function foo(x: string | number): string | number;\ntype T30 = ReturnType<typeof foo>; // string | number
It is not possible to use infer declarations in constraint clauses for regular type parameters:
\ntstype ReturnType<T extends (...args: any[]) => infer R> = R; // Error, not supported
However, much the same effect can be obtained by erasing the type variables in the constraint and instead specifying a conditional type:
\n\ntstype AnyFunction = (...args: any[]) => any;\ntype ReturnType<T extends AnyFunction> = T extends (...args: any[]) => infer R\n ? R\n : any;
TypeScript 2.8 adds several predefined conditional types to lib.d.ts:
Exclude<T, U> — Exclude from T those types that are assignable to U.Extract<T, U> — Extract from T those types that are assignable to U.NonNullable<T> — Exclude null and undefined from T.ReturnType<T> — Obtain the return type of a function type.InstanceType<T> — Obtain the instance type of a constructor function type.\ntstype T00 = Exclude<\"a\" | \"b\" | \"c\" | \"d\", \"a\" | \"c\" | \"f\">; // \"b\" | \"d\"\ntype T01 = Extract<\"a\" | \"b\" | \"c\" | \"d\", \"a\" | \"c\" | \"f\">; // \"a\" | \"c\"\n\ntype T02 = Exclude<string | number | (() => void), Function>; // string | number\ntype T03 = Extract<string | number | (() => void), Function>; // () => void\n\ntype T04 = NonNullable<string | number | undefined>; // string | number\ntype T05 = NonNullable<(() => string) | string[] | null | undefined>; // (() => string) | string[]\n\nfunction f1(s: string) {\n return { a: 1, b: s };\n}\n\nclass C {\n x = 0;\n y = 0;\n}\n\ntype T10 = ReturnType<() => string>; // string\ntype T11 = ReturnType<(s: string) => void>; // void\ntype T12 = ReturnType<<T>() => T>; // {}\ntype T13 = ReturnType<<T extends U, U extends number[]>() => T>; // number[]\ntype T14 = ReturnType<typeof f1>; // { a: number, b: string }\ntype T15 = ReturnType<any>; // any\ntype T16 = ReturnType<never>; // any\ntype T17 = ReturnType<string>; // Error\ntype T18 = ReturnType<Function>; // Error\n\ntype T20 = InstanceType<typeof C>; // C\ntype T21 = InstanceType<any>; // any\ntype T22 = InstanceType<never>; // any\ntype T23 = InstanceType<string>; // Error\ntype T24 = InstanceType<Function>; // Error
\n\nNote: The
\nExcludetype is a proper implementation of theDifftype suggested here. We’ve used the nameExcludeto avoid breaking existing code that defines aDiff, plus we feel that name better conveys the semantics of the type. We did not include theOmit<T, K>type because it is trivially written asPick<T, Exclude<keyof T, K>>.
Mapped types support adding a readonly or ? modifier to a mapped property, but they did not provide support the ability to remove modifiers.\nThis matters in homomorphic mapped types which by default preserve the modifiers of the underlying type.
TypeScript 2.8 adds the ability for a mapped type to either add or remove a particular modifier.\nSpecifically, a readonly or ? property modifier in a mapped type can now be prefixed with either + or - to indicate that the modifier should be added or removed.
\ntstype MutableRequired<T> = { -readonly [P in keyof T]-?: T[P] }; // Remove readonly and ?\ntype ReadonlyPartial<T> = { +readonly [P in keyof T]+?: T[P] }; // Add readonly and ?
A modifier with no + or - prefix is the same as a modifier with a + prefix. So, the ReadonlyPartial<T> type above corresponds to
\ntstype ReadonlyPartial<T> = { readonly [P in keyof T]?: T[P] }; // Add readonly and ?
Using this ability, lib.d.ts now has a new Required<T> type.\nThis type strips ? modifiers from all properties of T, thus making all properties required.
\ntstype Required<T> = { [P in keyof T]-?: T[P] };
Note that in --strictNullChecks mode, when a homomorphic mapped type removes a ? modifier from a property in the underlying type it also removes undefined from the type of that property:
\ntstype Foo = { a?: string }; // Same as { a?: string | undefined }\ntype Bar = Required<Foo>; // Same as { a: string }
keyof with intersection typesWith TypeScript 2.8 keyof applied to an intersection type is transformed to a union of keyof applied to each intersection constituent.\nIn other words, types of the form keyof (A & B) are transformed to be keyof A | keyof B.\nThis change should address inconsistencies with inference from keyof expressions.
\ntstype A = { a: string };\ntype B = { b: string };\n\ntype T1 = keyof (A & B); // \"a\" | \"b\"\ntype T2<T> = keyof (T & B); // keyof T | \"b\"\ntype T3<U> = keyof (A & U); // \"a\" | keyof U\ntype T4<T, U> = keyof (T & U); // keyof T | keyof U\ntype T5 = T2<A>; // \"a\" | \"b\"\ntype T6 = T3<B>; // \"a\" | \"b\"\ntype T7 = T4<A, B>; // \"a\" | \"b\"
.js filesTypeScript 2.8 adds support for understanding more namespace patterns in .js files.\nEmpty object literals declarations on top level, just like functions and classes, are now recognized as as namespace declarations in JavaScript.
\njsvar ns = {}; // recognized as a declaration for a namespace `ns`\nns.constant = 1; // recognized as a declaration for var `constant`
Assignments at the top-level should behave the same way; in other words, a var or const declaration is not required.
\njsapp = {}; // does NOT need to be `var app = {}`\napp.C = class {};\napp.f = function() {};\napp.prop = 1;
An IIFE returning a function, class or empty object literal, is also recognized as a namespace:
\n\njsvar C = (function() {\n function C(n) {\n this.p = n;\n }\n return C;\n})();\nC.staticProperty = 1;
“Defaulted declarations” allow initializers that reference the declared name in the left side of a logical or:
\n\njsmy = window.my || {};\nmy.app = my.app || {};
You can assign an object literal directly to the prototype property. Individual prototype assignments still work too:
\n\ntsvar C = function(p) {\n this.p = p;\n};\nC.prototype = {\n m() {\n console.log(this.p);\n }\n};\nC.prototype.q = function(r) {\n return this.p === r;\n};
Nesting works to any level now, and merges correctly across files. Previously neither was the case.
\n\njsvar app = window.app || {};\napp.C = class {};
TypeScript 2.8 adds support for a per-file configurable JSX factory name using @jsx dom paragma.\nJSX factory can be configured for a compilation using --jsxFactory (default is React.createElement). With TypeScript 2.8 you can override this on a per-file-basis by adding a comment to the beginning of the file.
\nts/** @jsx dom */\nimport { dom } from \"./renderer\";\n<h></h>;
Generates:
\n\njsvar renderer_1 = require(\"./renderer\");\nrenderer_1.dom(\"h\", null);
JSX type checking is driven by definitions in a JSX namespace, for instance JSX.Element for the type of a JSX element, and JSX.IntrinsicElements for built-in elements.\nBefore TypeScript 2.8 the JSX namespace was expected to be in the global namespace, and thus only allowing one to be defined in a project.\nStarting with TypeScript 2.8 the JSX namespace will be looked under the jsxNamespace (e.g. React) allowing for multiple jsx factories in one compilation.\nFor backward compatibility the global JSX namespace is used as a fallback if none was defined on the factory function.\nCombined with the per-file @jsx pragma, each file can have a different JSX factory.
--emitDeclarationsOnly--emitDeclarationsOnly allows for only generating declaration files; .js/.jsx output generation will be skipped with this flag. The flag is useful when the .js output generation is handled by a different transpiler like Babel.
TypeScript 2.7 adds support for declaring const-named properties on types including ECMAScript symbols.
\n\nts// Lib\nexport const SERIALIZE = Symbol(\"serialize-method-key\");\n\nexport interface Serializable {\n [SERIALIZE](obj: {}): string;\n}
\nts// consumer\n\nimport { SERIALIZE, Serializable } from \"lib\";\n\nclass JSONSerializableItem implements Serializable {\n [SERIALIZE](obj: {}) {\n return JSON.stringify(obj);\n }\n}
This also applies to numeric and string literals.
\n\ntsconst Foo = \"Foo\";\nconst Bar = \"Bar\";\n\nlet x = {\n [Foo]: 100,\n [Bar]: \"hello\"\n};\n\nlet a = x[Foo]; // has type 'number'\nlet b = x[Bar]; // has type 'string'
unique symbolTo enable treating symbols as unique literals a new type unique symbol is available.\nunique symbol is are subtype of symbol, and are produced only from calling Symbol() or Symbol.for(), or from explicit type annotations.\nThe new type is only allowed on const declarations and readonly static properties, and in order to reference a specific unique symbol, you’ll have to use the typeof operator.\nEach reference to a unique symbol implies a completely unique identity that’s tied to a given declaration.
\nts// Works\ndeclare const Foo: unique symbol;\n\n// Error! 'Bar' isn't a constant.\nlet Bar: unique symbol = Symbol();\n\n// Works - refers to a unique symbol, but its identity is tied to 'Foo'.\nlet Baz: typeof Foo = Foo;\n\n// Also works.\nclass C {\n static readonly StaticSymbol: unique symbol = Symbol();\n}
Because each unique symbol has a completely separate identity, no two unique symbol types are assignable or comparable to each other.
\ntsconst Foo = Symbol();\nconst Bar = Symbol();\n\n// Error: can't compare two unique symbols.\nif (Foo === Bar) {\n // ...\n}
TypeScript 2.7 introduces a new flag called --strictPropertyInitialization.\nThis flag performs checks to ensure that each instance property of a class gets initialized in the constructor body, or by a property initializer.\nFor example
\ntsclass C {\n foo: number;\n bar = \"hello\";\n baz: boolean;\n // ~~~\n // Error! Property 'baz' has no initializer and is not definitely assigned in the\n // constructor.\n\n constructor() {\n this.foo = 42;\n }\n}
In the above, if we truly meant for baz to potentially be undefined, we should have declared it with the type boolean | undefined.
There are certain scenarios where properties can be initialized indirectly (perhaps by a helper method or dependency injection library), in which case you can use the new definite assignment assertion modifiers for your properties (discussed below).
\n\ntsclass C {\n foo!: number;\n // ^\n // Notice this '!' modifier.\n // This is the \"definite assignment assertion\"\n\n constructor() {\n this.initialize();\n }\n\n initialize() {\n this.foo = 0;\n }\n}
Keep in mind that --strictPropertyInitialization will be turned on along with other --strict mode flags, which can impact your project.\nYou can set the strictPropertyInitialization setting to false in your tsconfig.json’s compilerOptions, or --strictPropertyInitialization false on the command line to turn off this checking.
The definite assignment assertion is a feature that allows a ! to be placed after instance property and variable declarations to relay to TypeScript that a variable is indeed assigned for all intents and purposes, even if TypeScript’s analyses cannot detect so.
For example:
\n\ntslet x: number;\ninitialize();\nconsole.log(x + x);\n// ~ ~\n// Error! Variable 'x' is used before being assigned.\n\nfunction initialize() {\n x = 10;\n}
With definite assignment assertions, we can assert that x is really assigned by appending an ! to its declaration:
\nts// Notice the '!'\nlet x!: number;\ninitialize();\n\n// No error!\nconsole.log(x + x);\n\nfunction initialize() {\n x = 10;\n}
In a sense, the definite assignment assertion operator is the dual of the non-null assertion operator (in which expressions are post-fixed with a !), which we could also have used in the example.
\ntslet x: number;\ninitialize();\n\n// No error!\nconsole.log(x! + x!);\n\nfunction initialize() {\n x = 10;
In our example, we knew that all uses of x would be initialized so it makes more sense to use definite assignment assertions than non-null assertions.
In TypeScript 2.6 and earlier, [number, string, string] was considered a subtype of [number, string].\nThis was motivated by TypeScript’s structural nature; the first and second elements of a [number, string, string] are respectively subtypes of the first and second elements of [number, string].\nHowever, after examining real world usage of tuples, we noticed that most situations in which this was permitted was typically undesirable.
In TypeScript 2.7, tuples of different arities are no longer assignable to each other.\nThanks to a pull request from Tycho Grouwstra, tuple types now encode their arity into the type of their respective length property.\nThis is accomplished by leveraging numeric literal types, which now allow tuples to be distinct from tuples of different arities.
Conceptually, you might consider the type [number, string] to be equivalent to the following declaration of NumStrTuple:
\ntsinterface NumStrTuple extends Array<number | string> {\n 0: number;\n 1: string;\n length: 2; // using the numeric literal type '2'\n}
Note that this is a breaking change for some code.\nIf you need to resort to the original behavior in which tuples only enforce a minimum length, you can use a similar declaration that does not explicitly define a length property, falling back to number.
\ntsinterface MinimumNumStrTuple extends Array<number | string> {\n 0: number;\n 1: string;\n}
Note that this does not imply tuples represent immutable arrays, but it is an implied convention.
\nTypeScript 2.7 improves type inference for multiple object literals occurring in the same context.\nWhen multiple object literal types contribute to a union type, we now normalize the object literal types such that all properties are present in each constituent of the union type.
\nConsider:
\n\ntsconst obj = test ? { text: \"hello\" } : {}; // { text: string } | { text?: undefined }\nconst s = obj.text; // string | undefined
Previously type {} was inferred for obj and the second line subsequently caused an error because obj would appear to have no properties.\nThat obviously wasn’t ideal.
\nts// let obj: { a: number, b: number } |\n// { a: string, b?: undefined } |\n// { a?: undefined, b?: undefined }\nlet obj = [{ a: 1, b: 2 }, { a: \"abc\" }, {}][0];\nobj.a; // string | number | undefined\nobj.b; // number | undefined
Multiple object literal type inferences for the same type parameter are similarly collapsed into a single normalized union type:
\n\ntsdeclare function f<T>(...items: T[]): T;\n// let obj: { a: number, b: number } |\n// { a: string, b?: undefined } |\n// { a?: undefined, b?: undefined }\nlet obj = f({ a: 1, b: 2 }, { a: \"abc\" }, {});\nobj.a; // string | number | undefined\nobj.b; // number | undefined
instanceof expressionsTypeScript 2.7 improves the handling of structurally identical classes in union types and instanceof expressions:
instanceof operator is now based on whether the type of the left operand derives from the type indicated by the right operand (as opposed to a structural subtype check).This means that union types and instanceof properly distinguish between structurally identical classes.
\ntsclass A {}\nclass B extends A {}\nclass C extends A {}\nclass D extends A {\n c: string;\n}\nclass E extends D {}\n\nlet x1 = !true ? new A() : new B(); // A\nlet x2 = !true ? new B() : new C(); // B | C (previously B)\nlet x3 = !true ? new C() : new D(); // C | D (previously C)\n\nlet a1 = [new A(), new B(), new C(), new D(), new E()]; // A[]\nlet a2 = [new B(), new C(), new D(), new E()]; // (B | C | D)[] (previously B[])\n\nfunction f1(x: B | C | D) {\n if (x instanceof B) {\n x; // B (previously B | D)\n } else if (x instanceof C) {\n x; // C\n } else {\n x; // D (previously never)\n }\n}
in operatorThe in operator now acts as a narrowing expression for types.
For a n in x expression, where n is a string literal or string literal type and x is a union type, the “true” branch narrows to types which have an optional or required property n, and the “false” branch narrows to types which have an optional or missing property n.
\ntsinterface A {\n a: number;\n}\ninterface B {\n b: string;\n}\n\nfunction foo(x: A | B) {\n if (\"a\" in x) {\n return x.a;\n }\n return x.b;\n}
import d from \"cjs\" form CommonJS modules with --esModuleInteropTypeScript 2.7 updates CommonJS/AMD/UMD module emit to synthesize namespace records based on the presence of an __esModule indicator under --esModuleInterop.\nThe change brings the generated output from TypeScript closer to that generated by Babel.
Previously CommonJS/AMD/UMD modules were treated in the same way as ES6 modules, resulting in a couple of problems. Namely:
\nimport * as foo from \"foo\") for a CommonJS/AMD/UMD module as equivalent to const foo = require(\"foo\").\nThings are simple here, but they don’t work out if the primary object being imported is a primitive or a class or a function.\nECMAScript spec stipulates that a namespace record is a plain object, and that a namespace import (foo in the example above) is not callable, though allowed by TypeScriptimport d from \"foo\") for a CommonJS/AMD/UMD module as equivalent to const d = require(\"foo\").default.\nMost of the CommonJS/AMD/UMD modules available today do not have a default export, making this import pattern practically unusable to import non-ES modules (i.e. CommonJS/AMD/UMD). For instance import fs from \"fs\" or import express from \"express\" are not allowed.Under the new --esModuleInterop these two issues should be addressed:
import * as foo from \"foo\") is now correctly flagged as uncallabale. Calling it will result in an error.import fs from \"fs\"), and should work as expected.\n\nNote: The new behavior is added under a flag to avoid unwarranted breaks to existing code bases. We highly recommend applying it both to new and existing projects.\nFor existing projects, namespace imports (
\nimport * as express from \"express\"; express();) will need to be converted to default imports (import express from \"express\"; express();).
With --esModuleInterop two new helpers are generated __importStar and __importDefault for import * and import default respectively.\nFor instance input like:
\ntsimport * as foo from \"foo\";\nimport b from \"bar\";
Will generate:
\n\njs\"use strict\";\nvar __importStar =\n (this && this.__importStar) ||\n function(mod) {\n if (mod && mod.__esModule) return mod;\n var result = {};\n if (mod != null)\n for (var k in mod)\n if (Object.hasOwnProperty.call(mod, k)) result[k] = mod[k];\n result[\"default\"] = mod;\n return result;\n };\nvar __importDefault =\n (this && this.__importDefault) ||\n function(mod) {\n return mod && mod.__esModule ? mod : { default: mod };\n };\nexports.__esModule = true;\nvar foo = __importStar(require(\"foo\"));\nvar bar_1 = __importDefault(require(\"bar\"));
TypeScript 2.7 brings support for ES Numeric Separators.\nNumeric literals can now be separated into segments using _.
\ntsconst milion = 1_000_000;\nconst phone = 555_734_2231;\nconst bytes = 0xff_0c_00_ff;\nconst word = 0b1100_0011_1101_0001;
--watch modeTypeScript’s --watch mode now clears the screen after a re-compilation is requested.
--pretty outputTypeScript’s --pretty flag can make error messages easier to read and manage.\n--pretty now uses colors for file names, diagnostic codes, and line numbers.\nFile names and positions are now also formatted to allow navigation in common terminals (e.g. Visual Studio Code terminal).
TypeScript 2.6 introduces a new strict checking flag, --strictFunctionTypes.\nThe --strictFunctionTypes switch is part of the --strict family of switches, meaning that it defaults to on in --strict mode.\nYou can opt-out by setting --strictFunctionTypes false on your command line or in your tsconfig.json.
Under --strictFunctionTypes function type parameter positions are checked contravariantly instead of bivariantly.\nFor some background on what variance means for function types check out What are covariance and contravariance?.
The stricter checking applies to all function types, except those originating in method or constructor declarations.\nMethods are excluded specifically to ensure generic classes and interfaces (such as Array<T>) continue to mostly relate covariantly.
Consider the following example in which Animal is the supertype of Dog and Cat:
\ntsdeclare let f1: (x: Animal) => void;\ndeclare let f2: (x: Dog) => void;\ndeclare let f3: (x: Cat) => void;\nf1 = f2; // Error with --strictFunctionTypes\nf2 = f1; // Ok\nf2 = f3; // Error
The first assignment is permitted in default type checking mode, but flagged as an error in strict function types mode.\nIntuitively, the default mode permits the assignment because it is possibly sound, whereas strict function types mode makes it an error because it isn’t provably sound.\nIn either mode the third assignment is an error because it is never sound.
\nAnother way to describe the example is that the type (x: T) => void is bivariant (i.e. covariant or contravariant) for T in default type checking mode, but contravariant for T in strict function types mode.
\ntsinterface Comparer<T> {\n compare: (a: T, b: T) => number;\n}\n\ndeclare let animalComparer: Comparer<Animal>;\ndeclare let dogComparer: Comparer<Dog>;\n\nanimalComparer = dogComparer; // Error\ndogComparer = animalComparer; // Ok
The first assignment is now an error. Effectively, T is contravariant in Comparer<T> because it is used only in function type parameter positions.
By the way, note that whereas some languages (e.g. C# and Scala) require variance annotations (out/in or +/-), variance emerges naturally from the actual use of a type parameter within a generic type due to TypeScript’s structural type system.
Under --strictFunctionTypes the first assignment is still permitted if compare was declared as a method.\nEffectively, T is bivariant in Comparer<T> because it is used only in method parameter positions.
\ntsinterface Comparer<T> {\n compare(a: T, b: T): number;\n}\n\ndeclare let animalComparer: Comparer<Animal>;\ndeclare let dogComparer: Comparer<Dog>;\n\nanimalComparer = dogComparer; // Ok because of bivariance\ndogComparer = animalComparer; // Ok
TypeScript 2.6 also improves type inference involving contravariant positions:
\n\ntsfunction combine<T>(...funcs: ((x: T) => void)[]): (x: T) => void {\n return x => {\n for (const f of funcs) f(x);\n };\n}\n\nfunction animalFunc(x: Animal) {}\nfunction dogFunc(x: Dog) {}\n\nlet combined = combine(animalFunc, dogFunc); // (x: Dog) => void
Above, all inferences for T originate in contravariant positions, and we therefore infer the best common subtype for T.\nThis contrasts with inferences from covariant positions, where we infer the best common supertype.
TypeScript 2.6.2 adds support for the new <>...</> syntax for fragments in JSX.\nIt is frequently desirable to return multiple children from a component.\nHowever, this is invalid, so the usual approach has been to wrap the text in an extra element, such as a <div> or <span> as shown below.
\ntsxrender() {\n return (\n <div>\n Some text.\n <h2>A heading</h2>\n More text.\n </div>\n );\n}
To address this pattern, React introduced the React.Fragment component, which provides a dedicated way to wrap such elements without adding an element to the DOM.\nCorrespondingly, the <>...</> syntax was added to JSX to facilitate this new construct. Therefore, the above scenario becomes:
\ntsxrender() {\n return (\n <>\n Some text.\n <h2>A heading</h2>\n More text.\n </>\n );\n}
Under --jsx preserve, the new syntax is left untouched for TypeScript emit. Otherwise, for --jsx react, <>...</> is compiled to React.createElement(React.Fragment, null, ...), where React.createElement respects --jsxFactory.\nNote that it is an error to use <>...</> when --jsx react and --jsxFactory are both enabled.
Please refer to the React blog for more details on fragments and the new syntax.
\nTypeScript 2.6 fixes the tagged string template emit to align better with the ECMAScript spec.\nAs per the ECMAScript spec, every time a template tag is evaluated, the same template strings object (the same TemplateStringsArray) should be passed as the first argument.\nBefore TypeScript 2.6, the generated output was a completely new template object each time.\nThough the string contents are the same, this emit affects libraries that use the identity of the string for cache invalidation purposes, e.g. lit-html.
\ntsexport function id(x: TemplateStringsArray) {\n return x;\n}\n\nexport function templateObjectFactory() {\n return id`hello world`;\n}\n\nlet result = templateObjectFactory() === templateObjectFactory(); // true in TS 2.6
Results in the following generated code:
\n\njs\"use strict\";\nvar __makeTemplateObject =\n (this && this.__makeTemplateObject) ||\n function(cooked, raw) {\n if (Object.defineProperty) {\n Object.defineProperty(cooked, \"raw\", { value: raw });\n } else {\n cooked.raw = raw;\n }\n return cooked;\n };\n\nfunction id(x) {\n return x;\n}\n\nvar _a;\nfunction templateObjectFactory() {\n return id(\n _a || (_a = __makeTemplateObject([\"hello world\"], [\"hello world\"]))\n );\n}\n\nvar result = templateObjectFactory() === templateObjectFactory();
\n\nNote: This change brings a new emit helper,
\n__makeTemplateObject;\nif you are using--importHelperswithtslib, an updated to version 1.8 or later.
TypeScript 2.6 npm package ships with localized versions of diagnostic messages for 13 languages.\nThe localized messages are available when using --locale flag on the command line.
Error messages in Russian:
\n\nshc:\\ts>tsc --v\nVersion 2.6.0-dev.20171003\n\nc:\\ts>tsc --locale ru --pretty c:\\test\\a.ts\n\n../test/a.ts(1,5): error TS2322: Тип \"\"string\"\" не может быть назначен для типа \"number\".\n\n1 var x: number = \"string\";\n ~
And help in Japanese:
\n\nshPS C:\\ts> tsc --v\nVersion 2.6.0-dev.20171003\n\nPS C:\\ts> tsc --locale ja-jp\nバージョン 2.6.0-dev.20171003\n構文: tsc [オプション] [ファイル ...]\n\n例: tsc hello.ts\n tsc --outFile file.js file.ts\n tsc @args.txt\n\nオプション:\n -h, --help このメッセージを表示します。\n --all コンパイラ オプションをすべて表示します。\n -v, --version コンパイラのバージョンを表示します。\n --init TypeScript プロジェクトを初期化して、tsconfig.json ファイルを作成します。\n -p ファイルまたはディレクトリ, --project ファイルまたはディレクトリ 構成ファイルか、'tsconfig.json' を含むフォルダーにパスが指定されたプロジェクトをコ\nンパイルします。\n --pretty 色とコンテキストを使用してエラーとメッセージにスタイルを適用します (試験的)。\n -w, --watch 入力ファイルを監視します。\n -t バージョン, --target バージョン ECMAScript のターゲット バージョンを指定します: 'ES3' (既定)、'ES5'、'ES2015'、'ES2016'、'ES2017'、'ES\nNEXT'。\n -m 種類, --module 種類 モジュール コード生成を指定します: 'none'、'commonjs'、'amd'、'system'、'umd'、'es2015'、'ESNext'。\n --lib コンパイルに含めるライブラリ ファイルを指定します:\n 'es5' 'es6' 'es2015' 'es7' 'es2016' 'es2017' 'esnext' 'dom' 'dom.iterable' 'webworker' 'scripthost' 'es201\n5.core' 'es2015.collection' 'es2015.generator' 'es2015.iterable' 'es2015.promise' 'es2015.proxy' 'es2015.reflect' 'es2015.symbol' 'es2015.symbol.wellkno\nwn' 'es2016.array.include' 'es2017.object' 'es2017.sharedmemory' 'es2017.string' 'es2017.intl' 'esnext.asynciterable'\n --allowJs javascript ファイルのコンパイルを許可します。\n --jsx 種類 JSX コード生成を指定します: 'preserve'、'react-native'、'react'。\n -d, --declaration 対応する '.d.ts' ファイルを生成します。\n --sourceMap 対応する '.map' ファイルを生成します。\n --outFile ファイル 出力を連結して 1 つのファイルを生成します。\n --outDir ディレクトリ ディレクトリへ出力構造をリダイレクトします。\n --removeComments コメントを出力しないでください。\n --noEmit 出力しないでください。\n --strict strict 型チェックのオプションをすべて有効にします。\n --noImplicitAny 暗黙的な 'any' 型を含む式と宣言に関するエラーを発生させます。\n --strictNullChecks 厳格な null チェックを有効にします。\n --noImplicitThis 暗黙的な 'any' 型を持つ 'this' 式でエラーが発生します。\n --alwaysStrict 厳格モードで解析してソース ファイルごとに \"use strict\" を生成します。\n --noUnusedLocals 使用されていないローカルに関するエラーを報告します。\n --noUnusedParameters 使用されていないパラメーターに関するエラーを報告します。\n --noImplicitReturns 関数の一部のコード パスが値を返さない場合にエラーを報告します。\n --noFallthroughCasesInSwitch switch ステートメントに case のフォールスルーがある場合にエラーを報告します。\n --types コンパイルに含む型宣言ファイル。\n @<ファイル>
TypeScript 2.6 support suppressing errors in .js files using // @ts-ignore comments placed above the offending lines.
\ntsif (false) {\n // @ts-ignore: Unreachable code error\n console.log(\"hello\");\n}
A // @ts-ignore comment suppresses all errors that originate on the following line.\nIt is recommended practice to have the remainder of the comment following @ts-ignore explain which error is being suppressed.
Please note that this comment only suppresses the error reporting, and we recommend you use this comments very sparingly.
\ntsc --watchTypeScript 2.6 brings a faster --watch implementation.\nThe new version optimizes code generation and checking for code bases using ES modules.\nChanges detected in a module file will result in only regenerating the changed module, and files that depend on it, instead of the whole project.\nProjects with large number of files should reap the most benefit from this change.
The new implementation also brings performance enhancements to watching in tsserver.\nThe watcher logic has been completely rewritten to respond faster to change events.
\nTypeScript 2.6 adds revised implementation the --noUnusedLocals and --noUnusedParameters compiler options.\nDeclarations are only written to but never read from are now flagged as unused.
Bellow both n and m will be marked as unused, because their values are never read. Previously TypeScript would only check whether their values were referenced.
\ntsfunction f(n: number) {\n n = 0;\n}\n\nclass C {\n private m: number;\n constructor() {\n this.m = 0;\n }\n}
Also functions that are only called within their own bodies are considered unused.
\n\ntsfunction f() {\n f(); // Error: 'f' is declared but its value is never read\n}
catch clause variablesThanks to work done by @tinganho, TypeScript 2.5 implements a new ECMAScript feature that allows users to omit the variable in catch clauses.\nFor example, when using JSON.parse you may need to wrap calls to the function with a try/catch, but you may not end up using the SyntaxError that gets thrown when input is erroneous.
\ntslet input = \"...\";\ntry {\n JSON.parse(input);\n} catch {\n // ^ Notice that our `catch` clause doesn't declare a variable.\n console.log(\"Invalid JSON given\\n\\n\" + input);\n}
checkJs/@ts-check modeTypeScript 2.5 introduces the ability to assert the type of expressions when using plain JavaScript in your projects.\nThe syntax is an /** @type {...} */ annotation comment followed by a parenthesized expression whose type needs to be re-evaluated.\nFor example:
\ntsvar x = /** @type {SomeType} */ AnyParenthesizedExpression;
When importing using the Node module resolution strategy in TypeScript 2.5, the compiler will now check whether files originate from “identical” packages.\nIf a file originates from a package with a package.json containing the same name and version fields as a previously encountered package, then TypeScript will redirect itself to the top-most package.\nThis helps resolve problems where two packages might contain identical declarations of classes, but which contain private members that cause them to be structurally incompatible.
As a nice bonus, this can also reduce the memory and runtime footprint of the compiler and language service by avoiding loading .d.ts files from duplicate packages.
--preserveSymlinks compiler flagTypeScript 2.5 brings the preserveSymlinks flag, which parallels the behavior of the --preserve-symlinks flag in Node.js.\nThis flag also exhibits the opposite behavior to Webpack’s resolve.symlinks option (i.e. setting TypeScript’s preserveSymlinks to true parallels setting Webpack’s resolve.symlinks to false, and vice-versa).
In this mode, references to modules and packages (e.g. imports and /// <reference type=\"...\" /> directives) are all resolved relative to the location of the symbolic link file, rather than relative to the path that the symbolic link resolves to.\nFor a more concrete example, we’ll defer to the documentation on the Node.js website.
Dynamic import expressions are a new feature and part of ECMAScript that allows users to asynchronously request a module at any arbitrary point in your program.
This means that you can conditionally and lazily import other modules and libraries.\nFor example, here’s an async function that only imports a utility library when it’s needed:
\ntsasync function getZipFile(name: string, files: File[]): Promise<File> {\n const zipUtil = await import(\"./utils/create-zip-file\");\n const zipContents = await zipUtil.getContentAsBlob(files);\n return new File(zipContents, name);\n}
Many bundlers have support for automatically splitting output bundles based on these import expressions, so consider using this new feature with the esnext module target.
TypeScript 2.4 now allows enum members to contain string initializers.
\n\ntsenum Colors {\n Red = \"RED\",\n Green = \"GREEN\",\n Blue = \"BLUE\"\n}
The caveat is that string-initialized enums can’t be reverse-mapped to get the original enum member name.\nIn other words, you can’t write Colors[\"RED\"] to get the string \"Red\".
TypeScript 2.4 introduces a few wonderful changes around the way generics are inferred.
\nFor one, TypeScript can now make inferences for the return type of a call.\nThis can improve your experience and catch errors.\nSomething that now works:
\n\ntsfunction arrayMap<T, U>(f: (x: T) => U): (a: T[]) => U[] {\n return a => a.map(f);\n}\n\nconst lengths: (a: string[]) => number[] = arrayMap(s => s.length);
As an example of new errors you might spot as a result:
\n\ntslet x: Promise<string> = new Promise(resolve => {\n resolve(10);\n // ~~ Error!\n});
Prior to TypeScript 2.4, in the following example
\n\ntslet f: <T>(x: T) => T = y => y;
y would have the type any.\nThis meant the program would type-check, but you could technically do anything with y, such as the following:
\ntslet f: <T>(x: T) => T = y => y() + y.foo.bar;
That last example isn’t actually type-safe.
\nIn TypeScript 2.4, the function on the right side implicitly gains type parameters, and y is inferred to have the type of that type-parameter.
If you use y in a way that the type parameter’s constraint doesn’t support, you’ll correctly get an error.\nIn this case, the constraint of T was (implicitly) {}, so the last example will appropriately fail.
TypeScript now tries to unify type parameters when comparing two single-signature types.\nAs a result, you’ll get stricter checks when relating two generic signatures, and may catch some bugs.
\n\ntstype A = <T, U>(x: T, y: U) => [T, U];\ntype B = <S>(x: S, y: S) => [S, S];\n\nfunction f(a: A, b: B) {\n a = b; // Error\n b = a; // Ok\n}
TypeScript has always compared parameters in a bivariant way.\nThere are a number of reasons for this, but by-and-large this was not been a huge issue for our users until we saw some of the adverse effects it had with Promises and Observables.
TypeScript 2.4 introduces tightens this up when relating two callback types. For example:
\n\ntsinterface Mappable<T> {\n map<U>(f: (x: T) => U): Mappable<U>;\n}\n\ndeclare let a: Mappable<number>;\ndeclare let b: Mappable<string | number>;\n\na = b;\nb = a;
Prior to TypeScript 2.4, this example would succeed.\nWhen relating the types of map, TypeScript would bidirectionally relate their parameters (i.e. the type of f).\nWhen relating each f, TypeScript would also bidirectionally relate the type of those parameters.
When relating the type of map in TS 2.4, the language will check whether each parameter is a callback type, and if so, it will ensure that those parameters are checked in a contravariant manner with respect to the current relation.
In other words, TypeScript now catches the above bug, which may be a breaking change for some users, but will largely be helpful.
\nTypeScript 2.4 introduces the concept of “weak types”.\nAny type that contains nothing but a set of all-optional properties is considered to be weak.\nFor example, this Options type is a weak type:
\ntsinterface Options {\n data?: string;\n timeout?: number;\n maxRetries?: number;\n}
In TypeScript 2.4, it’s now an error to assign anything to a weak type when there’s no overlap in properties.\nFor example:
\n\ntsfunction sendMessage(options: Options) {\n // ...\n}\n\nconst opts = {\n payload: \"hello world!\",\n retryOnFail: true\n};\n\n// Error!\nsendMessage(opts);\n// No overlap between the type of 'opts' and 'Options' itself.\n// Maybe we meant to use 'data'/'maxRetries' instead of 'payload'/'retryOnFail'.
You can think of this as TypeScript “toughening up” the weak guarantees of these types to catch what would otherwise be silent bugs.
\nSince this is a breaking change, you may need to know about the workarounds which are the same as those for strict object literal checks:
\n[propName: string]: {}).opts as Options).First some ES2016 terminology:
\nES2015 introduced Iterator, which is an object that exposes three methods, next, return, and throw, as per the following interface:
\ntsinterface Iterator<T> {\n next(value?: any): IteratorResult<T>;\n return?(value?: any): IteratorResult<T>;\n throw?(e?: any): IteratorResult<T>;\n}
This kind of iterator is useful for iterating over synchronously available values, such as the elements of an Array or the keys of a Map.\nAn object that supports iteration is said to be “iterable” if it has a Symbol.iterator method that returns an Iterator object.
The Iterator protocol also defines the target of some of the ES2015 features like for..of and spread operator and the array rest in destructuring assignmnets.
ES2015 also introduced “Generators”, which are functions that can be used to yield partial computation results via the Iterator interface and the yield keyword.\nGenerators can also internally delegate calls to another iterable through yield *. For example:
\ntsfunction* f() {\n yield 1;\n yield* [2, 3];\n}
--downlevelIterationPreviously generators were only supported if the target is ES6/ES2015 or later.\nMoreover, constructs that operate on the Iterator protocol, e.g. for..of were only supported if they operate on arrays for targets below ES6/ES2015.
TypeScript 2.3 adds full support for generators and the Iterator protocol for ES3 and ES5 targets with --downlevelIteration flag.
With --downlevelIteration, the compiler uses new type check and emit behavior that attempts to call a [Symbol.iterator]() method on the iterated object if it is found, and creates a synthetic array iterator over the object if it is not.
\n\nPlease note that this requires a native
\nSymbol.iteratororSymbol.iteratorshim at runtime for any non-array values.
for..of statements, Array Destructuring, and Spread elements in Array, Call, and New expressions support Symbol.iterator in ES5/E3 if available when using --downlevelIteration, but can be used on an Array even if it does not define Symbol.iterator at run time or design time.
TypeScript 2.3 adds support for the async iterators and generators as described by the current TC39 proposal.
\nThe Async Iteration introduces an AsyncIterator, which is similar to Iterator.\nThe difference lies in the fact that the next, return, and throw methods of an AsyncIterator return a Promise for the iteration result, rather than the result itself. This allows the caller to enlist in an asynchronous notification for the time at which the AsyncIterator has advanced to the point of yielding a value.\nAn AsyncIterator has the following shape:
\ntsinterface AsyncIterator<T> {\n next(value?: any): Promise<IteratorResult<T>>;\n return?(value?: any): Promise<IteratorResult<T>>;\n throw?(e?: any): Promise<IteratorResult<T>>;\n}
An object that supports async iteration is said to be “iterable” if it has a Symbol.asyncIterator method that returns an AsyncIterator object.
The Async Iteration proposal introduces “Async Generators”, which are async functions that also can be used to yield partial computation results. Async Generators can also delegate calls via yield* to either an iterable or async iterable:
\ntsasync function* g() {\n yield 1;\n await sleep(100);\n yield* [2, 3];\n yield* (async function*() {\n await sleep(100);\n yield 4;\n })();\n}
As with Generators, Async Generators can only be function declarations, function expressions, or methods of classes or object literals. Arrow functions cannot be Async Generators. Async Generators require a valid, global Promise implementation (either native or an ES2015-compatible polyfill), in addition to a valid Symbol.asyncIterator reference (either a native symbol or a shim).
for-await-of StatementFinally, ES2015 introduced the for..of statement as a means of iterating over an iterable.\nSimilarly, the Async Iteration proposal introduces the for..await..of statement to iterate over an async iterable:
\ntsasync function f() {\n for await (const x of g()) {\n console.log(x);\n }\n}
The for..await..of statement is only legal within an Async Function or Async Generator.
Symbol.asyncIterator to exist at runtime.\nYou may need to polyfill Symbol.asyncIterator, which for simple purposes can be as simple as: (Symbol as any).asyncIterator = Symbol.asyncIterator || Symbol.from(\"Symbol.asyncIterator\");esnext in your --lib option, to get the AsyncIterator declaration if you do not already have it.--downlevelIterators flag.TypeScript 2.3 adds support for declaring defaults for generic type parameters.
\nConsider a function that creates a new HTMLElement, calling it with no arguments generates a Div; you can optionally pass a list of children as well. Previously you would have to define it as:
\ntsdeclare function create(): Container<HTMLDivElement, HTMLDivElement[]>;\ndeclare function create<T extends HTMLElement>(element: T): Container<T, T[]>;\ndeclare function create<T extends HTMLElement, U extends HTMLElement>(\n element: T,\n children: U[]\n): Container<T, U[]>;
With generic parameter defaults we can reduce it to:
\n\ntsdeclare function create<T extends HTMLElement = HTMLDivElement, U = T[]>(\n element?: T,\n children?: U\n): Container<T, U>;
A generic parameter default follows the following rules:
\n--strict master optionNew checks added to TypeScript are often off by default to avoid breaking existing projects. While avoiding breakage is a good thing, this strategy has the drawback of making it increasingly complex to choose the highest level of type safety, and doing so requires explicit opt-in action on every TypeScript release. With the --strict option it becomes possible to choose maximum type safety with the understanding that additional errors might be reported by newer versions of the compiler as improved type checking features are added.
The new --strict compiler option represents the recommended setting of a number of type checking options. Specifically, specifying --strict corresponds to specifying all of the following options (and may in the future include more options):
--strictNullChecks--noImplicitAny--noImplicitThis--alwaysStrictIn exact terms, the --strict option sets the default value for the compiler options listed above. This means it is still possible to individually control the options. For example,
--strict --noImplicitThis false\nhas the effect of turning on all strict options except the --noImplicitThis option. Using this scheme it is possible to express configurations consisting of all strict options except some explicitly listed options. In other words, it is now possible to default to the highest level of type safety but opt out of certain checks.
Starting with TypeScript 2.3, the default tsconfig.json generated by tsc --init includes a \"strict\": true setting in the \"compilerOptions\" section. Thus, new projects started with tsc --init will by default have the highest level of type safety enabled.
--init outputAlong with setting --strict on by default, tsc --init has an enhanced output. Default tsconfig.json files generated by tsc --init now include a set of the common compiler options along with their descriptions commented out. Just un-comment the configuration you like to set to get the desired behavior; we hope the new output simplifies the setting up new projects and keeps configuration files readable as projects grow.
--checkJsBy default the TypeScript compiler does not report any errors in .js files including using --allowJs. With TypeScript 2.3 type-checking errors can also be reported in .js files with --checkJs.
You can skip checking some files by adding // @ts-nocheck comment to them; conversely you can choose to check only a few .js files by adding // @ts-check comment to them without setting --checkJs. You can also ignore errors on specific lines by adding // @ts-ignore on the preceding line.
.js files are still checked to ensure that they only include standard ECMAScript features; type annotations are only allowed in .ts files and are flagged as errors in .js files. JSDoc comments can be used to add some type information to your JavaScript code, see JSDoc Support documentation for more details about the supported JSDoc constructs.
See Type checking JavaScript Files documentation for more details.
\nTypeScript 2.2 adds support for the ECMAScript 2015 mixin class pattern (see MDN Mixin description and “Real” Mixins with JavaScript Classes for more details) as well as rules for combining mixin construct signatures with regular construct signatures in intersection types.
\nany[] and an object-like return type. For example, given an object-like type X, new (...args: any[]) => X is a mixin constructor type with an instance type X.extends an expression of a type parameter type. The following rules apply to mixin class declarations:extends expression must be constrained to a mixin constructor type.any[] and must use the spread operator to pass those parameters as arguments in a super(...args) call.Given an expression Base of a parametric type T with a constraint X, a mixin class class C extends Base {...} is processed as if Base had type X and the resulting type is the intersection typeof C & T. In other words, a mixin class is represented as an intersection between the mixin class constructor type and the parametric base class constructor type.
When obtaining the construct signatures of an intersection type that contains mixin constructor types, the mixin construct signatures are discarded and their instance types are mixed into the return types of the other construct signatures in the intersection type. For example, the intersection type { new(...args: any[]) => A } & { new(s: string) => B } has a single construct signature new(s: string) => A & B.
\ntsclass Point {\n constructor(public x: number, public y: number) {}\n}\n\nclass Person {\n constructor(public name: string) {}\n}\n\ntype Constructor<T> = new (...args: any[]) => T;\n\nfunction Tagged<T extends Constructor<{}>>(Base: T) {\n return class extends Base {\n _tag: string;\n constructor(...args: any[]) {\n super(...args);\n this._tag = \"\";\n }\n };\n}\n\nconst TaggedPoint = Tagged(Point);\n\nlet point = new TaggedPoint(10, 20);\npoint._tag = \"hello\";\n\nclass Customer extends Tagged(Person) {\n accountBalance: number;\n}\n\nlet customer = new Customer(\"Joe\");\ncustomer._tag = \"test\";\ncustomer.accountBalance = 0;
Mixin classes can constrain the types of classes they can mix into by specifying a construct signature return type in the constraint for the type parameter. For example, the following WithLocation function implements a subclass factory that adds a getLocation method to any class that satisfies the Point interface (i.e. that has x and y properties of type number).
\ntsinterface Point {\n x: number;\n y: number;\n}\n\nconst WithLocation = <T extends Constructor<Point>>(Base: T) =>\n class extends Base {\n getLocation(): [number, number] {\n return [this.x, this.y];\n }\n };
object typeTypeScript did not have a type that represents the non-primitive type, i.e. any thing that is not number | string | boolean | symbol | null | undefined. Enter the new object type.
With object type, APIs like Object.create can be better represented. For example:
\ntsdeclare function create(o: object | null): void;\n\ncreate({ prop: 0 }); // OK\ncreate(null); // OK\n\ncreate(42); // Error\ncreate(\"string\"); // Error\ncreate(false); // Error\ncreate(undefined); // Error
new.targetThe new.target meta-property is new syntax introduced in ES2015. When an instance of a constructor is created via new, the value of new.target is set to be a reference to the constructor function initially used to allocate the instance. If a function is called rather than constructed via new, new.target is set to undefined.
new.target comes in handy when Object.setPrototypeOf or __proto__ needs to be set in a class constructor. One such use case is inheriting from Error in NodeJS v4 and higher.
\ntsclass CustomError extends Error {\n constructor(message?: string) {\n super(message); // 'Error' breaks prototype chain here\n Object.setPrototypeOf(this, new.target.prototype); // restore prototype chain\n }\n}
This results in the generated JS
\n\njsvar CustomError = (function(_super) {\n __extends(CustomError, _super);\n function CustomError() {\n var _newTarget = this.constructor;\n var _this = _super.apply(this, arguments); // 'Error' breaks prototype chain here\n _this.__proto__ = _newTarget.prototype; // restore prototype chain\n return _this;\n }\n return CustomError;\n})(Error);
new.target also comes in handy for writing constructable functions, for example:
\ntsfunction f() {\n if (new.target) {\n /* called via 'new' */\n }\n}
Which translates to:
\n\njsfunction f() {\n var _newTarget = this && this instanceof f ? this.constructor : void 0;\n if (_newTarget) {\n /* called via 'new' */\n }\n}
null/undefined in operands of expressionsTypeScript 2.2 improves checking of nullable operands in expressions. Specifically, these are now flagged as errors:
\n+ operator is nullable, and neither operand is of type any or string.-, *, **, /, %, <<, >>, >>>, &, |, or ^ operator is nullable.<, >, <=, >=, or in operator is nullable.instanceof operator is nullable.+, -, ~, ++, or -- unary operator is nullable.An operand is considered nullable if the type of the operand is null or undefined or a union type that includes null or undefined. Note that the union type case only only occurs in --strictNullChecks mode because null and undefined disappear from unions in classic type checking mode.
Types with a string index signature can be indexed using the [] notation, but were not allowed to use the .. Starting with TypeScript 2.2 using either should be allowed.
\ntsinterface StringMap<T> {\n [x: string]: T;\n}\n\nconst map: StringMap<number>;\n\nmap[\"prop1\"] = 1;\nmap.prop2 = 2;
This only apply to types with an explicit string index signature. It is still an error to access unknown properties on a type using . notation.
TypeScript 2.2 adds support for using spread on a JSX element children. Please see facebook/jsx#57 for more details.
\n\ntsfunction Todo(prop: { key: number; todo: string }) {\n return <div>{prop.key.toString() + prop.todo}</div>;\n}\n\nfunction TodoList({ todos }: TodoListProps) {\n return (\n <div>{...todos.map(todo => <Todo key={todo.id} todo={todo.todo} />)}</div>\n );\n}\n\nlet x: TodoListProps;\n\n<TodoList {...x} />;
jsx: react-nativeReact-native build pipeline expects all files to have a .js extensions even if the file contains JSX syntax. The new --jsx value react-native will persevere the JSX syntax in the output file, but give it a .js extension.
keyof and Lookup TypesIn JavaScript it is fairly common to have APIs that expect property names as parameters, but so far it hasn’t been possible to express the type relationships that occur in those APIs.
\nEnter Index Type Query or keyof;\nAn indexed type query keyof T yields the type of permitted property names for T.\nA keyof T type is considered a subtype of string.
\ntsinterface Person {\n name: string;\n age: number;\n location: string;\n}\n\ntype K1 = keyof Person; // \"name\" | \"age\" | \"location\"\ntype K2 = keyof Person[]; // \"length\" | \"push\" | \"pop\" | \"concat\" | ...\ntype K3 = keyof { [x: string]: Person }; // string
The dual of this is indexed access types, also called lookup types.\nSyntactically, they look exactly like an element access, but are written as types:
\n\ntstype P1 = Person[\"name\"]; // string\ntype P2 = Person[\"name\" | \"age\"]; // string | number\ntype P3 = string[\"charAt\"]; // (pos: number) => string\ntype P4 = string[][\"push\"]; // (...items: string[]) => number\ntype P5 = string[][0]; // string
You can use this pattern with other parts of the type system to get type-safe lookups.
\n\ntsfunction getProperty<T, K extends keyof T>(obj: T, key: K) {\n return obj[key]; // Inferred type is T[K]\n}\n\nfunction setProperty<T, K extends keyof T>(obj: T, key: K, value: T[K]) {\n obj[key] = value;\n}\n\nlet x = { foo: 10, bar: \"hello!\" };\n\nlet foo = getProperty(x, \"foo\"); // number\nlet bar = getProperty(x, \"bar\"); // string\n\nlet oops = getProperty(x, \"wargarbl\"); // Error! \"wargarbl\" is not \"foo\" | \"bar\"\n\nsetProperty(x, \"foo\", \"string\"); // Error!, string expected number
One common task is to take an existing type and make each of its properties entirely optional.\nLet’s say we have a `Person:
\n\ntsinterface Person {\n name: string;\n age: number;\n location: string;\n}
A partial version of it would be:
\n\ntsinterface PartialPerson {\n name?: string;\n age?: number;\n location?: string;\n}
with Mapped types, PartialPerson can be written as a generalized transformation on the type Person as:
\ntstype Partial<T> = {\n [P in keyof T]?: T[P];\n};\n\ntype PartialPerson = Partial<Person>;
Mapped types are produced by taking a union of literal types, and computing a set of properties for a new object type.\nThey’re like list comprehensions in Python, but instead of producing new elements in a list, they produce new properties in a type.
\nIn addition to Partial, Mapped Types can express many useful transformations on types:
\nts// Keep types the same, but make each property to be read-only.\ntype Readonly<T> = {\n readonly [P in keyof T]: T[P];\n};\n\n// Same property names, but make the value a promise instead of a concrete one\ntype Deferred<T> = {\n [P in keyof T]: Promise<T[P]>;\n};\n\n// Wrap proxies around properties of T\ntype Proxify<T> = {\n [P in keyof T]: { get(): T[P]; set(v: T[P]): void };\n};
Partial, Readonly, Record, and PickPartial and Readonly, as described earlier, are very useful constructs.\nYou can use them to describe some common JS routines like:
\ntsfunction assign<T>(obj: T, props: Partial<T>): void;\nfunction freeze<T>(obj: T): Readonly<T>;
Because of that, they are now included by default in the standard library.
\nWe’re also including two other utility types as well: Record and Pick.
\nts// From T pick a set of properties K\ndeclare function pick<T, K extends keyof T>(obj: T, ...keys: K[]): Pick<T, K>;\n\nconst nameAndAgeOnly = pick(person, \"name\", \"age\"); // { name: string, age: number }
\nts// For every properties K of type T, transform it to U\nfunction mapObject<K extends string, T, U>(\n obj: Record<K, T>,\n f: (x: T) => U\n): Record<K, U>;\n\nconst names = { foo: \"hello\", bar: \"world\", baz: \"bye\" };\nconst lengths = mapObject(names, s => s.length); // { foo: number, bar: number, baz: number }
TypeScript 2.1 brings support for ES2017 Spread and Rest.
\nSimilar to array spread, spreading an object can be handy to get a shallow copy:
\n\ntslet copy = { ...original };
Similarly, you can merge several different objects.\nIn the following example, merged will have properties from foo, bar, and baz.
\ntslet merged = { ...foo, ...bar, ...baz };
You can also override existing properties and add new ones:
\n\ntslet obj = { x: 1, y: \"string\" };\nvar newObj = { ...obj, z: 3, y: 4 }; // { x: number, y: number, z: number }
The order of specifying spread operations determines what properties end up in the resulting object;\nproperties in later spreads “win out” over previously created properties.
\nObject rests are the dual of object spreads, in that they can extract any extra properties that don’t get picked up when destructuring an element:
\n\ntslet obj = { x: 1, y: 1, z: 1 };\nlet { z, ...obj1 } = obj;\nobj1; // {x: number, y: number};
This feature was supported before TypeScript 2.1, but only when targeting ES6/ES2015.\nTypeScript 2.1 brings the capability to ES3 and ES5 run-times, meaning you’ll be free to take advantage of it no matter what environment you’re using.
\n\n\nNote: first, we need to make sure our run-time has an ECMAScript-compliant
\nPromiseavailable globally.\nThat might involve grabbing a polyfill forPromise, or relying on one that you might have in the run-time that you’re targeting.\nWe also need to make sure that TypeScript knowsPromiseexists by setting yourlibflag to something like\"dom\", \"es2015\"or\"dom\", \"es2015.promise\", \"es5\"
\njson{\n \"compilerOptions\": {\n \"lib\": [\"dom\", \"es2015.promise\", \"es5\"]\n }\n}
\ntsfunction delay(milliseconds: number) {\n return new Promise<void>(resolve => {\n setTimeout(resolve, milliseconds);\n });\n}\n\nasync function dramaticWelcome() {\n console.log(\"Hello\");\n\n for (let i = 0; i < 3; i++) {\n await delay(500);\n console.log(\".\");\n }\n\n console.log(\"World!\");\n}\n\ndramaticWelcome();
Compiling and running the output should result in the correct behavior on an ES3/ES5 engine.
\ntslib)TypeScript injects a handful of helper functions such as __extends for inheritance, __assign for spread operator in object literals and JSX elements, and __awaiter for async functions.
Previously there were two options:
\n--noEmitHelpers.The two options left more to be desired;\nbundling the helpers in every file was a pain point for customers trying to keep their package size small.\nAnd not including helpers, meant customers had to maintain their own helpers library.
\nTypeScript 2.1 allows for including these files in your project once in a separate module, and the compiler will emit imports to them as needed.
\nFirst, install the tslib utility library:
\nshnpm install tslib
Second, compile your files using --importHelpers:
\nshtsc --module commonjs --importHelpers a.ts
So given the following input, the resulting .js file will include an import to tslib and use the __assign helper from it instead of inlining it.
\ntsexport const o = { a: 1, name: \"o\" };\nexport const copy = { ...o };
\njs\"use strict\";\nvar tslib_1 = require(\"tslib\");\nexports.o = { a: 1, name: \"o\" };\nexports.copy = tslib_1.__assign({}, exports.o);
TypeScript has traditionally been overly strict about how you can import modules.\nThis was to avoid typos and prevent users from using modules incorrectly.
\nHowever, a lot of the time, you might just want to import an existing module that may not have its own .d.ts file.\nPreviously this was an error.\nStarting with TypeScript 2.1 this is now much easier.
With TypeScript 2.1, you can import a JavaScript module without needing a type declaration.\nA type declaration (such as declare module \"foo\" { ... } or node_modules/@types/foo) still takes priority if it exists.
An import to a module with no declaration file will still be flagged as an error under --noImplicitAny.
\nts// Succeeds if `node_modules/asdf/index.js` exists, or if `node_modules/asdf/package.json` defines a valid \"main\" entry point\nimport { x } from \"asdf\";
--target ES2016, --target ES2017 and --target ESNextTypeScript 2.1 supports three new target values --target ES2016, --target ES2017 and --target ESNext.
Using target --target ES2016 will instruct the compiler not to transform ES2016-specific features, e.g. ** operator.
Similarly, --target ES2017 will instruct the compiler not to transform ES2017-specific features like async/await.
--target ESNext targets latest supported ES proposed features.
any InferencePreviously, if TypeScript couldn’t figure out the type of a variable, it would choose the any type.
\ntslet x; // implicitly 'any'\nlet y = []; // implicitly 'any[]'\n\nlet z: any; // explicitly 'any'.
With TypeScript 2.1, instead of just choosing any, TypeScript will infer types based on what you end up assigning later on.
This is only enabled if --noImplicitAny is set.
\ntslet x;\n\n// You can still assign anything you want to 'x'.\nx = () => 42;\n\n// After that last assignment, TypeScript 2.1 knows that 'x' has type '() => number'.\nlet y = x();\n\n// Thanks to that, it will now tell you that you can't add a number to a function!\nconsole.log(x + y);\n// ~~~~~\n// Error! Operator '+' cannot be applied to types '() => number' and 'number'.\n\n// TypeScript still allows you to assign anything you want to 'x'.\nx = \"Hello world!\";\n\n// But now it also knows that 'x' is a 'string'!\nx.toLowerCase();
The same sort of tracking is now also done for empty arrays.
\nA variable declared with no type annotation and an initial value of [] is considered an implicit any[] variable.\nHowever, each subsequent x.push(value), x.unshift(value) or x[n] = value operation evolves the type of the variable in accordance with what elements are added to it.
\ntsfunction f1() {\n let x = [];\n x.push(5);\n x[1] = \"hello\";\n x.unshift(true);\n return x; // (string | number | boolean)[]\n}\n\nfunction f2() {\n let x = null;\n if (cond()) {\n x = [];\n while (cond()) {\n x.push(\"hello\");\n }\n }\n return x; // string[] | null\n}
One great benefit of this is that you’ll see way fewer implicit any errors when running with --noImplicitAny.\nImplicit any errors are only reported when the compiler is unable to know the type of a variable without a type annotation.
\ntsfunction f3() {\n let x = []; // Error: Variable 'x' implicitly has type 'any[]' in some locations where its type cannot be determined.\n x.push(5);\n function g() {\n x; // Error: Variable 'x' implicitly has an 'any[]' type.\n }\n}
String, numeric and boolean literal types (e.g. \"abc\", 1, and true) were previously inferred only in the presence of an explicit type annotation.\nStarting with TypeScript 2.1, literal types are always inferred for const variables and readonly properties.
The type inferred for a const variable or readonly property without a type annotation is the type of the literal initializer.\nThe type inferred for a let variable, var variable, parameter, or non-readonly property with an initializer and no type annotation is the widened literal type of the initializer.\nWhere the widened type for a string literal type is string, number for numeric literal types, boolean for true or false and the containing enum for enum literal types.
\ntsconst c1 = 1; // Type 1\nconst c2 = c1; // Type 1\nconst c3 = \"abc\"; // Type \"abc\"\nconst c4 = true; // Type true\nconst c5 = cond ? 1 : \"abc\"; // Type 1 | \"abc\"\n\nlet v1 = 1; // Type number\nlet v2 = c2; // Type number\nlet v3 = c3; // Type string\nlet v4 = c4; // Type boolean\nlet v5 = c5; // Type number | string
Literal type widening can be controlled through explicit type annotations.\nSpecifically, when an expression of a literal type is inferred for a const location without a type annotation, that const variable gets a widening literal type inferred.\nBut when a const location has an explicit literal type annotation, the const variable gets a non-widening literal type.
\ntsconst c1 = \"hello\"; // Widening type \"hello\"\nlet v1 = c1; // Type string\n\nconst c2: \"hello\" = \"hello\"; // Type \"hello\"\nlet v2 = c2; // Type \"hello\"
In ES2015, constructors which return an object implicitly substitute the value of this for any callers of super().\nAs a result, it is necessary to capture any potential return value of super() and replace it with this.\nThis change enables working with Custom Elements, which takes advantage of this to initialize browser-allocated elements with user-written constructors.
\ntsclass Base {\n x: number;\n constructor() {\n // return a new object other than `this`\n return {\n x: 1\n };\n }\n}\n\nclass Derived extends Base {\n constructor() {\n super();\n this.x = 2;\n }\n}
Generates:
\n\njsvar Derived = (function(_super) {\n __extends(Derived, _super);\n function Derived() {\n var _this = _super.call(this) || this;\n _this.x = 2;\n return _this;\n }\n return Derived;\n})(Base);
\n\nThis change entails a break in the behavior of extending built-in classes like
\nError,Array,Map, etc.. Please see the extending built-ins breaking change documentation for more details.
Often a project has multiple output targets, e.g. ES5 and ES2015, debug and production or CommonJS and System;\nJust a few configuration options change between these two targets, and maintaining multiple tsconfig.json files can be a hassle.
TypeScript 2.1 supports inheriting configuration using extends, where:
extends is a new top-level property in tsconfig.json (alongside compilerOptions, files, include, and exclude).extends must be a string containing a path to another configuration file to inherit from.files, include and exclude from the inheriting config file overwrite those from the base config file.configs/base.json:
\njson{\n \"compilerOptions\": {\n \"noImplicitAny\": true,\n \"strictNullChecks\": true\n }\n}
tsconfig.json:
\njson{\n \"extends\": \"./configs/base\",\n \"files\": [\"main.ts\", \"supplemental.ts\"]\n}
tsconfig.nostrictnull.json:
\njson{\n \"extends\": \"./tsconfig\",\n \"compilerOptions\": {\n \"strictNullChecks\": false\n }\n}
--alwaysStrictInvoking the compiler with --alwaysStrict causes:
\"use strict\"; directive atop every generated file.Modules are parsed automatically in strict mode.\nThe new flag is recommended for non-module code.
\nTypeScript has two special types, Null and Undefined, that have the values null and undefined respectively.\nPreviously it was not possible to explicitly name these types, but null and undefined may now be used as type names regardless of type checking mode.
The type checker previously considered null and undefined assignable to anything.\nEffectively, null and undefined were valid values of every type and it wasn’t possible to specifically exclude them (and therefore not possible to detect erroneous use of them).
--strictNullChecks--strictNullChecks switches to a new strict null checking mode.
In strict null checking mode, the null and undefined values are not in the domain of every type and are only assignable to themselves and any (the one exception being that undefined is also assignable to void).\nSo, whereas T and T | undefined are considered synonymous in regular type checking mode (because undefined is considered a subtype of any T), they are different types in strict type checking mode, and only T | undefined permits undefined values. The same is true for the relationship of T to T | null.
\nts// Compiled with --strictNullChecks\nlet x: number;\nlet y: number | undefined;\nlet z: number | null | undefined;\nx = 1; // Ok\ny = 1; // Ok\nz = 1; // Ok\nx = undefined; // Error\ny = undefined; // Ok\nz = undefined; // Ok\nx = null; // Error\ny = null; // Error\nz = null; // Ok\nx = y; // Error\nx = z; // Error\ny = x; // Ok\ny = z; // Error\nz = x; // Ok\nz = y; // Ok
In strict null checking mode the compiler requires every reference to a local variable of a type that doesn’t include undefined to be preceded by an assignment to that variable in every possible preceding code path.
\nts// Compiled with --strictNullChecks\nlet x: number;\nlet y: number | null;\nlet z: number | undefined;\nx; // Error, reference not preceded by assignment\ny; // Error, reference not preceded by assignment\nz; // Ok\nx = 1;\ny = null;\nx; // Ok\ny; // Ok
The compiler checks that variables are definitely assigned by performing control flow based type analysis. See later for further details on this topic.
\nOptional parameters and properties automatically have undefined added to their types, even when their type annotations don’t specifically include undefined.\nFor example, the following two types are identical:
\nts// Compiled with --strictNullChecks\ntype T1 = (x?: number) => string; // x has type number | undefined\ntype T2 = (x?: number | undefined) => string; // x has type number | undefined
A property access or a function call produces a compile-time error if the object or function is of a type that includes null or undefined.\nHowever, type guards are extended to support non-null and non-undefined checks.
\nts// Compiled with --strictNullChecks\ndeclare function f(x: number): string;\nlet x: number | null | undefined;\nif (x) {\n f(x); // Ok, type of x is number here\n} else {\n f(x); // Error, type of x is number? here\n}\nlet a = x != null ? f(x) : \"\"; // Type of a is string\nlet b = x && f(x); // Type of b is string | 0 | null | undefined
Non-null and non-undefined type guards may use the ==, !=, ===, or !== operator to compare to null or undefined, as in x != null or x === undefined.\nThe effects on subject variable types accurately reflect JavaScript semantics (e.g. double-equals operators check for both values no matter which one is specified whereas triple-equals only checks for the specified value).
Type guards previously only supported checking local variables and parameters.\nType guards now support checking “dotted names” consisting of a variable or parameter name followed one or more property accesses.
\n\ntsinterface Options {\n location?: {\n x?: number;\n y?: number;\n };\n}\n\nfunction foo(options?: Options) {\n if (options && options.location && options.location.x) {\n const x = options.location.x; // Type of x is number\n }\n}
Type guards for dotted names also work with user defined type guard functions and the typeof and instanceof operators and do not depend on the --strictNullChecks compiler option.
A type guard for a dotted name has no effect following an assignment to any part of the dotted name.\nFor example, a type guard for x.y.z will have no effect following an assignment to x, x.y, or x.y.z.
Expression operators permit operand types to include null and/or undefined but always produce values of non-null and non-undefined types.
\nts// Compiled with --strictNullChecks\nfunction sum(a: number | null, b: number | null) {\n return a + b; // Produces value of type number\n}
The && operator adds null and/or undefined to the type of the right operand depending on which are present in the type of the left operand, and the || operator removes both null and undefined from the type of the left operand in the resulting union type.
\nts// Compiled with --strictNullChecks\ninterface Entity {\n name: string;\n}\nlet x: Entity | null;\nlet s = x && x.name; // s is of type string | null\nlet y = x || { name: \"test\" }; // y is of type Entity
The null and undefined types are not widened to any in strict null checking mode.
\ntslet z = null; // Type of z is null
In regular type checking mode the inferred type of z is any because of widening, but in strict null checking mode the inferred type of z is null (and therefore, absent a type annotation, null is the only possible value for z).
A new ! post-fix expression operator may be used to assert that its operand is non-null and non-undefined in contexts where the type checker is unable to conclude that fact.\nSpecifically, the operation x! produces a value of the type of x with null and undefined excluded.\nSimilar to type assertions of the forms <T>x and x as T, the ! non-null assertion operator is simply removed in the emitted JavaScript code.
\nts// Compiled with --strictNullChecks\nfunction validateEntity(e?: Entity) {\n // Throw exception if e is null or invalid entity\n}\n\nfunction processEntity(e?: Entity) {\n validateEntity(e);\n let s = e!.name; // Assert that e is non-null and access name\n}
The new features are designed such that they can be used in both strict null checking mode and regular type checking mode.\nIn particular, the null and undefined types are automatically erased from union types in regular type checking mode (because they are subtypes of all other types), and the ! non-null assertion expression operator is permitted but has no effect in regular type checking mode. Thus, declaration files that are updated to use null- and undefined-aware types can still be used in regular type checking mode for backwards compatibility.
In practical terms, strict null checking mode requires that all files in a compilation are null- and undefined-aware.
\nTypeScript 2.0 implements a control flow-based type analysis for local variables and parameters.\nPreviously, the type analysis performed for type guards was limited to if statements and ?: conditional expressions and didn’t include effects of assignments and control flow constructs such as return and break statements.\nWith TypeScript 2.0, the type checker analyses all possible flows of control in statements and expressions to produce the most specific type possible (the narrowed type) at any given location for a local variable or parameter that is declared to have a union type.
\ntsfunction foo(x: string | number | boolean) {\n if (typeof x === \"string\") {\n x; // type of x is string here\n x = 1;\n x; // type of x is number here\n }\n x; // type of x is number | boolean here\n}\n\nfunction bar(x: string | number) {\n if (typeof x === \"number\") {\n return;\n }\n x; // type of x is string here\n}
Control flow based type analysis is particuarly relevant in --strictNullChecks mode because nullable types are represented using union types:
\ntsfunction test(x: string | null) {\n if (x === null) {\n return;\n }\n x; // type of x is string in remainder of function\n}
Furthermore, in --strictNullChecks mode, control flow based type analysis includes definite assignment analysis for local variables of types that don’t permit the value undefined.
\ntsfunction mumble(check: boolean) {\n let x: number; // Type doesn't permit undefined\n x; // Error, x is undefined\n if (check) {\n x = 1;\n x; // Ok\n }\n x; // Error, x is possibly undefined\n x = 2;\n x; // Ok\n}
TypeScript 2.0 implements support for tagged (or discriminated) union types.\nSpecifically, the TS compiler now support type guards that narrow union types based on tests of a discriminant property and furthermore extend that capability to switch statements.
\ntsinterface Square {\n kind: \"square\";\n size: number;\n}\n\ninterface Rectangle {\n kind: \"rectangle\";\n width: number;\n height: number;\n}\n\ninterface Circle {\n kind: \"circle\";\n radius: number;\n}\n\ntype Shape = Square | Rectangle | Circle;\n\nfunction area(s: Shape) {\n // In the following switch statement, the type of s is narrowed in each case clause\n // according to the value of the discriminant property, thus allowing the other properties\n // of that variant to be accessed without a type assertion.\n switch (s.kind) {\n case \"square\":\n return s.size * s.size;\n case \"rectangle\":\n return s.width * s.height;\n case \"circle\":\n return Math.PI * s.radius * s.radius;\n }\n}\n\nfunction test1(s: Shape) {\n if (s.kind === \"square\") {\n s; // Square\n } else {\n s; // Rectangle | Circle\n }\n}\n\nfunction test2(s: Shape) {\n if (s.kind === \"square\" || s.kind === \"rectangle\") {\n return;\n }\n s; // Circle\n}
A discriminant property type guard is an expression of the form x.p == v, x.p === v, x.p != v, or x.p !== v, where p and v are a property and an expression of a string literal type or a union of string literal types.\nThe discriminant property type guard narrows the type of x to those constituent types of x that have a discriminant property p with one of the possible values of v.
Note that we currently only support discriminant properties of string literal types.\nWe intend to later add support for boolean and numeric literal types.
\nnever typeTypeScript 2.0 introduces a new primitive type never.\nThe never type represents the type of values that never occur.\nSpecifically, never is the return type for functions that never return and never is the type of variables under type guards that are never true.
The never type has the following characteristics:
never is a subtype of and assignable to every type.never (except never itself).return statements, or only return statements with expressions of type never, and if the end point of the function is not reachable (as determined by control flow analysis), the inferred return type for the function is never.never return type annotation, all return statements (if any) must have expressions of type never and the end point of the function must not be reachable.Because never is a subtype of every type, it is always omitted from union types and it is ignored in function return type inference as long as there are other types being returned.
Some examples of functions returning never:
\nts// Function returning never must have unreachable end point\nfunction error(message: string): never {\n throw new Error(message);\n}\n\n// Inferred return type is never\nfunction fail() {\n return error(\"Something failed\");\n}\n\n// Function returning never must have unreachable end point\nfunction infiniteLoop(): never {\n while (true) {}\n}
Some examples of use of functions returning never:
\nts// Inferred return type is number\nfunction move1(direction: \"up\" | \"down\") {\n switch (direction) {\n case \"up\":\n return 1;\n case \"down\":\n return -1;\n }\n return error(\"Should never get here\");\n}\n\n// Inferred return type is number\nfunction move2(direction: \"up\" | \"down\") {\n return direction === \"up\"\n ? 1\n : direction === \"down\"\n ? -1\n : error(\"Should never get here\");\n}\n\n// Inferred return type is T\nfunction check<T>(x: T | undefined) {\n return x || error(\"Undefined value\");\n}
Because never is assignable to every type, a function returning never can be used when a callback returning a more specific type is required:
\ntsfunction test(cb: () => string) {\n let s = cb();\n return s;\n}\n\ntest(() => \"hello\");\ntest(() => fail());\ntest(() => {\n throw new Error();\n});
A property or index signature can now be declared with the readonly modifier is considered read-only.
Read-only properties may have initializers and may be assigned to in constructors within the same class declaration, but otherwise assignments to read-only properties are disallowed.
\nIn addition, entities are implicitly read-only in several situations:
\nget accessor and no set accessor is considered read-only.const variables are considered read-only properties.import statement is considered read-only.foo.x is read-only when foo is declared as import * as foo from \"foo\").\ntsinterface Point {\n readonly x: number;\n readonly y: number;\n}\n\nvar p1: Point = { x: 10, y: 20 };\np1.x = 5; // Error, p1.x is read-only\n\nvar p2 = { x: 1, y: 1 };\nvar p3: Point = p2; // Ok, read-only alias for p2\np3.x = 5; // Error, p3.x is read-only\np2.x = 5; // Ok, but also changes p3.x because of aliasing
\ntsclass Foo {\n readonly a = 1;\n readonly b: string;\n constructor() {\n this.b = \"hello\"; // Assignment permitted in constructor\n }\n}
\ntslet a: Array<number> = [0, 1, 2, 3, 4];\nlet b: ReadonlyArray<number> = a;\nb[5] = 5; // Error, elements are read-only\nb.push(5); // Error, no push method (because it mutates array)\nb.length = 3; // Error, length is read-only\na = b; // Error, mutating methods are missing
this for functionsFollowing up on specifying the type of this in a class or an interface, functions and methods can now declare the type of this they expect.
By default the type of this inside a function is any.\nStarting with TypeScript 2.0, you can provide an explicit this parameter.\nthis parameters are fake parameters that come first in the parameter list of a function:
\ntsfunction f(this: void) {\n // make sure `this` is unusable in this standalone function\n}
this parameters in callbacksLibraries can also use this parameters to declare how callbacks will be invoked.
\ntsinterface UIElement {\n addClickListener(onclick: (this: void, e: Event) => void): void;\n}
this: void means that addClickListener expects onclick to be a function that does not require a this type.
Now if you annotate calling code with this:
\ntsclass Handler {\n info: string;\n onClickBad(this: Handler, e: Event) {\n // oops, used this here. using this callback would crash at runtime\n this.info = e.message;\n }\n}\nlet h = new Handler();\nuiElement.addClickListener(h.onClickBad); // error!
--noImplicitThisA new flag is also added in TypeScript 2.0 to flag all uses of this in functions without an explicit type annotation.
tsconfig.jsonGlob support is here!! Glob support has been one of the most requested features.
\nGlob-like file patterns are supported two properties \"include\" and \"exclude\".
\njson{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"noImplicitAny\": true,\n \"removeComments\": true,\n \"preserveConstEnums\": true,\n \"outFile\": \"../../built/local/tsc.js\",\n \"sourceMap\": true\n },\n \"include\": [\"src/**/*\"],\n \"exclude\": [\"node_modules\", \"**/*.spec.ts\"]\n}
The supported glob wildcards are:
\n* matches zero or more characters (excluding directory separators)? matches any one character (excluding directory separators)**/ recursively matches any subdirectoryIf a segment of a glob pattern includes only * or .*, then only files with supported extensions are included (e.g. .ts, .tsx, and .d.ts by default with .js and .jsx if allowJs is set to true).
If the \"files\" and \"include\" are both left unspecified, the compiler defaults to including all TypeScript (.ts, .d.ts and .tsx) files in the containing directory and subdirectories except those excluded using the \"exclude\" property. JS files (.js and .jsx) are also included if allowJs is set to true.
If the \"files\" or \"include\" properties are specified, the compiler will instead include the union of the files included by those two properties.\nFiles in the directory specified using the \"outDir\" compiler option are always excluded unless explicitly included via the \"files\" property (even when the ”exclude” property is specified).
Files included using \"include\" can be filtered using the \"exclude\" property.\nHowever, files included explicitly using the \"files\" property are always included regardless of \"exclude\".\nThe \"exclude\" property defaults to excluding the node_modules, bower_components, and jspm_packages directories when not specified.
TypeScript 2.0 provides a set of additional module resolution knops to inform the compiler where to find declarations for a given module.
\nSee Module Resolution documentation for more details.
\nUsing a baseUrl is a common practice in applications using AMD module loaders where modules are “deployed” to a single folder at run-time.\nAll module imports with non-relative names are assumed to be relative to the baseUrl.
\njson{\n \"compilerOptions\": {\n \"baseUrl\": \"./modules\"\n }\n}
Now imports to \"moduleA\" would be looked up in ./modules/moduleA
\ntsimport A from \"moduleA\";
Sometimes modules are not directly located under baseUrl.\nLoaders use a mapping configuration to map module names to files at run-time, see RequireJs documentation and SystemJS documentation.
\nThe TypeScript compiler supports the declaration of such mappings using \"paths\" property in tsconfig.json files.
For instance, an import to a module \"jquery\" would be translated at runtime to \"node_modules/jquery/dist/jquery.slim.min.js\".
\njson{\n \"compilerOptions\": {\n \"baseUrl\": \"./node_modules\",\n \"paths\": {\n \"jquery\": [\"jquery/dist/jquery.slim.min\"]\n }\n}
Using \"paths\" also allow for more sophisticated mappings including multiple fall back locations.\nConsider a project configuration where only some modules are available in one location, and the rest are in another.
rootDirsUsing ‘rootDirs’, you can inform the compiler of the roots making up this “virtual” directory;\nand thus the compiler can resolve relative modules imports within these “virtual” directories as if were merged together in one directory.
\nGiven this project structure:
\n src\n └── views\n └── view1.ts (imports './template1')\n └── view2.ts\n\n generated\n └── templates\n └── views\n └── template1.ts (imports './view2')\nA build step will copy the files in /src/views and /generated/templates/views to the same directory in the output.\nAt run-time, a view can expect its template to exist next to it, and thus should import it using a relative name as \"./template\".
\"rootDirs\" specify a list of roots whose contents are expected to merge at run-time.\nSo following our example, the tsconfig.json file should look like:
\njson{\n \"compilerOptions\": {\n \"rootDirs\": [\"src/views\", \"generated/templates/views\"]\n }\n}
--traceResolution offers a handy way to understand how modules have been resolved by the compiler.
\nshelltsc --traceResolution
If you don’t want to take the time to write out declarations before using a new module, you can now just use a shorthand declaration to get started quickly.
\n\ntsdeclare module \"hot-new-module\";
All imports from a shorthand module will have the any type.
\n\ntsimport x, { y } from \"hot-new-module\";\nx(y);
Importing none-code resources using module loaders extension (e.g. AMD or SystemJS) has not been easy before;\npreviously an ambient module declaration had to be defined for each resource.
\nTypeScript 2.0 supports the use of the wildcard character (*) to declare a “family” of module names;\nthis way, a declaration is only required once for an extension, and not for every resource.
\ntsdeclare module \"*!text\" {\n const content: string;\n export default content;\n}\n// Some do it the other way around.\ndeclare module \"json!*\" {\n const value: any;\n export default value;\n}
Now you can import things that match \"*!text\" or \"json!*\".
\ntsimport fileContent from \"./xyz.txt!text\";\nimport data from \"json!http://example.com/data.json\";\nconsole.log(data, fileContent);
Wildcard module names can be even more useful when migrating from an un-typed code base.\nCombined with Shorthand ambient module declarations, a set of modules can be easily declared as any.
\ntsdeclare module \"myLibrary/*\";
All imports to any module under myLibrary would be considered to have the type any by the compiler;\nthus, shutting down any checking on the shapes or types of these modules.
\ntsimport { readFile } from \"myLibrary/fileSystem/readFile\";\n\nreadFile(); // readFile is 'any'
Some libraries are designed to be used in many module loaders, or with no module loading (global variables).\nThese are known as UMD or Isomorphic modules.\nThese libraries can be accessed through either an import or a global variable.
\nFor example:
\n\ntsexport const isPrime(x: number): boolean;\nexport as namespace mathLib;
The library can then be used as an import within modules:
\n\ntsimport { isPrime } from \"math-lib\";\nisPrime(2);\nmathLib.isPrime(2); // ERROR: can't use the global definition from inside a module
It can also be used as a global variable, but only inside of a script.\n(A script is a file with no imports or exports.)
\n\ntsmathLib.isPrime(2);
Optional properties and methods can now be declared in classes, similar to what is already permitted in interfaces.
\n\ntsclass Bar {\n a: number;\n b?: number;\n f() {\n return 1;\n }\n g?(): number; // Body of optional method can be omitted\n h?() {\n return 2;\n }\n}
When compiled in --strictNullChecks mode, optional properties and methods automatically have undefined included in their type. Thus, the b property above is of type number | undefined and the g method above is of type (() => number) | undefined.\nType guards can be used to strip away the undefined part of the type:
\ntsfunction test(x: Bar) {\n x.a; // number\n x.b; // number | undefined\n x.f; // () => number\n x.g; // (() => number) | undefined\n let f1 = x.f(); // number\n let g1 = x.g && x.g(); // number | undefined\n let g2 = x.g ? x.g() : 0; // number\n}
A class constructor may be marked private or protected.\nA class with private constructor cannot be instantiated outside the class body, and cannot be extended.\nA class with protected constructor cannot be instantiated outside the class body, but can be extended.
\ntsclass Singleton {\n private static instance: Singleton;\n\n private constructor() {}\n\n static getInstance() {\n if (!Singleton.instance) {\n Singleton.instance = new Singleton();\n }\n return Singleton.instance;\n }\n}\n\nlet e = new Singleton(); // Error: constructor of 'Singleton' is private.\nlet v = Singleton.getInstance();
An abstract class can declare abstract properties and/or accessors.\nAny sub class will need to declare the abstract properties or be marked as abstract.\nAbstract properties cannot have an initializer.\nAbstract accessors cannot have bodies.
\n\ntsabstract class Base {\n abstract name: string;\n abstract get value();\n abstract set value(v: number);\n}\n\nclass Derived extends Base {\n name = \"derived\";\n\n value = 1;\n}
An object literal type is now assignable to a type with an index signature if all known properties in the object literal are assignable to that index signature. This makes it possible to pass a variable that was initialized with an object literal as parameter to a function that expects a map or dictionary:
\n\ntsfunction httpService(path: string, headers: { [x: string]: string }) {}\n\nconst headers = {\n \"Content-Type\": \"application/x-www-form-urlencoded\"\n};\n\nhttpService(\"\", { \"Content-Type\": \"application/x-www-form-urlencoded\" }); // Ok\nhttpService(\"\", headers); // Now ok, previously wasn't
--libGetting to ES6/ES2015 built-in API declarations were only limited to target: ES6.\nEnter --lib; with --lib you can specify a list of built-in API declaration groups that you can chose to include in your project.\nFor instance, if you expect your runtime to have support for Map, Set and Promise (e.g. most evergreen browsers today), just include --lib es2015.collection,es2015.promise.\nSimilarly you can exclude declarations you do not want to include in your project, e.g. DOM if you are working on a node project using --lib es5,es6.
Here is a list of available API groups:
\n\nbashtsc --target es5 --lib es5,es2015.promise
\njson\"compilerOptions\": {\n \"lib\": [\"es5\", \"es2015.promise\"]\n}
--noUnusedParameters and --noUnusedLocalsTypeScript 2.0 has two new flags to help you maintain a clean code base.\n--noUnusedParameters flags any unused function or method parameters errors.\n--noUnusedLocals flags any unused local (un-exported) declaration like variables, functions, classes, imports, etc…\nAlso, unused private members of a class would be flagged as errors under --noUnusedLocals.
\ntsimport B, { readFile } from \"./b\";\n// ^ Error: `B` declared but never used\nreadFile();\n\nexport function write(message: string, args: string[]) {\n // ^^^^ Error: 'arg' declared but never used.\n console.log(message);\n}
Parameters declaration with names starting with _ are exempt from the unused parameter checking.\ne.g.:
\ntsfunction returnNull(_a) {\n // OK\n return null;\n}
.js extensionBefore TypeScript 2.0, a module identifier was always assumed to be extension-less;\nfor instance, given an import as import d from \"./moduleA.js\", the compiler looked up the definition of \"moduleA.js\" in ./moduleA.js.ts or ./moduleA.js.d.ts.\nThis made it hard to use bundling/loading tools like SystemJS that expect URI’s in their module identifier.
With TypeScript 2.0, the compiler will look up definition of \"moduleA.js\" in ./moduleA.ts or ./moduleA.d.ts.
Previously flagged as an invalid flag combination, target: es5 and ‘module: es6’ is now supported.\nThis should facilitate using ES2015-based tree shakers like rollup.
Trailing comma in function parameter and argument lists are now allowed.\nThis is an implementation for a Stage-3 ECMAScript proposal that emits down to valid ES3/ES5/ES6.
\n\ntsfunction foo(\n bar: Bar,\n baz: Baz // trailing commas are OK in parameter lists\n) {\n // Implementation...\n}\n\nfoo(\n bar,\n baz // and in argument lists\n);
--skipLibCheckTypeScript 2.0 adds a new --skipLibCheck compiler option that causes type checking of declaration files (files with extension .d.ts) to be skipped.\nWhen a program includes large declaration files, the compiler spends a lot of time type checking declarations that are already known to not contain errors, and compile times may be significantly shortened by skipping declaration file type checks.
Since declarations in one file can affect type checking in other files, some errors may not be detected when --skipLibCheck is specified.\nFor example, if a non-declaration file augments a type declared in a declaration file, errors may result that are only reported when the declaration file is checked.\nHowever, in practice such situations are rare.
This has been one common source of duplicate definition errors.\nMultiple declaration files defining the same members on interfaces.
\nTypeScript 2.0 relaxes this constraint and allows duplicate identifiers across blocks, as long as they have identical types.
\nWithin the same block duplicate definitions are still disallowed.
\n\ntsinterface Error {\n stack?: string;\n}\n\ninterface Error {\n code?: string;\n path?: string;\n stack?: string; // OK\n}
--declarationDir--declarationDir allows for generating declaration files in a different location than JavaScript files.
With TypeScript 1.8 it becomes possible for a type parameter constraint to reference type parameters from the same type parameter list. Previously this was an error. This capability is usually referred to as F-Bounded Polymorphism.
\n\ntsfunction assign<T extends U, U>(target: T, source: U): T {\n for (let id in source) {\n target[id] = source[id];\n }\n return target;\n}\n\nlet x = { a: 1, b: 2, c: 3, d: 4 };\nassign(x, { b: 10, d: 20 });\nassign(x, { e: 0 }); // Error
TypeScript 1.8 introduces control flow analysis to help catch common errors that users tend to run into.\nRead on to get more details, and check out these errors in action:
\n
Statements guaranteed to not be executed at run time are now correctly flagged as unreachable code errors. For instance, statements following unconditional return, throw, break or continue statements are considered unreachable. Use --allowUnreachableCode to disable unreachable code detection and reporting.
Here’s a simple example of an unreachable code error:
\n\ntsfunction f(x) {\n if (x) {\n return true;\n } else {\n return false;\n }\n\n x = 0; // Error: Unreachable code detected.\n}
A more common error that this feature catches is adding a newline after a return statement:
\ntsfunction f() {\n return; // Automatic Semicolon Insertion triggered at newline\n {\n x: \"string\"; // Error: Unreachable code detected.\n }\n}
Since JavaScript automatically terminates the return statement at the end of the line, the object literal becomes a block.
Unused labels are also flagged. Just like unreachable code checks, these are turned on by default; use --allowUnusedLabels to stop reporting these errors.
\ntsloop: while (x > 0) {\n // Error: Unused label.\n x++;\n}
Functions with code paths that do not return a value in JS implicitly return undefined. These can now be flagged by the compiler as implicit returns. The check is turned off by default; use --noImplicitReturns to turn it on.
\ntsfunction f(x) {\n // Error: Not all code paths return a value.\n if (x) {\n return false;\n }\n\n // implicitly returns `undefined`\n}
TypeScript can reports errors for fall-through cases in switch statement where the case clause is non-empty.\nThis check is turned off by default, and can be enabled using --noFallthroughCasesInSwitch.
With --noFallthroughCasesInSwitch, this example will trigger an error:
\ntsswitch (x % 2) {\n case 0: // Error: Fallthrough case in switch.\n console.log(\"even\");\n\n case 1:\n console.log(\"odd\");\n break;\n}
However, in the following example, no error will be reported because the fall-through case is empty:
\n\ntsswitch (x % 3) {\n case 0:\n case 1:\n console.log(\"Acceptable\");\n break;\n\n case 2:\n console.log(\"This is *two much*!\");\n break;\n}
TypeScript now supports Stateless Function components.\nThese are lightweight components that easily compose other components:
\n\nts// Use parameter destructuring and defaults for easy definition of 'props' type\nconst Greeter = ({ name = \"world\" }) => <div>Hello, {name}!</div>;\n\n// Properties get validated\nlet example = <Greeter name=\"TypeScript 1.8\" />;
For this feature and simplified props, be sure to be use the latest version of react.d.ts.
\nprops type management in ReactIn TypeScript 1.8 with the latest version of react.d.ts (see above), we’ve also greatly simplified the declaration of props types.
Specifically:
\nref and key or extend React.Propsref and key properties will appear with correct types on all componentsref property is correctly disallowed on instances of Stateless Function componentsUsers can now declare any augmentations that they want to make, or that any other consumers already have made, to an existing module.\nModule augmentations look like plain old ambient module declarations (i.e. the declare module \"foo\" { } syntax), and are directly nested either your own modules, or in another top level ambient external module.
Furthermore, TypeScript also has the notion of global augmentations of the form declare global { }.\nThis allows modules to augment global types such as Array if necessary.
The name of a module augmentation is resolved using the same set of rules as module specifiers in import and export declarations.\nThe declarations in a module augmentation are merged with any existing declarations the same way they would if they were declared in the same file.
Neither module augmentations nor global augmentations can add new items to the top level scope - they can only “patch” existing declarations.
\nHere map.ts can declare that it will internally patch the Observable type from observable.ts and add the map method to it.
\nts// observable.ts\nexport class Observable<T> {\n // ...\n}
\nts// map.ts\nimport { Observable } from \"./observable\";\n\n// Create an augmentation for \"./observable\"\ndeclare module \"./observable\" {\n\n // Augment the 'Observable' class definition with interface merging\n interface Observable<T> {\n map<U>(proj: (el: T) => U): Observable<U>;\n }\n\n}\n\nObservable.prototype.map = /*...*/;
\nts// consumer.ts\nimport { Observable } from \"./observable\";\nimport \"./map\";\n\nlet o: Observable<number>;\no.map(x => x.toFixed());
Similarly, the global scope can be augmented from modules using a declare global declarations:
\nts// Ensure this is treated as a module.\nexport {};\n\ndeclare global {\n interface Array<T> {\n mapToNumbers(): number[];\n }\n}\n\nArray.prototype.mapToNumbers = function() {\n /* ... */\n};
It’s not uncommon for an API to expect a specific set of strings for certain values.\nFor instance, consider a UI library that can move elements across the screen while controlling the “easing” of the animation.
\n\ntsdeclare class UIElement {\n animate(options: AnimationOptions): void;\n}\n\ninterface AnimationOptions {\n deltaX: number;\n deltaY: number;\n easing: string; // Can be \"ease-in\", \"ease-out\", \"ease-in-out\"\n}
However, this is error prone - there is nothing stopping a user from accidentally misspelling one of the valid easing values:
\n\nts// No errors\nnew UIElement().animate({ deltaX: 100, deltaY: 100, easing: \"ease-inout\" });
With TypeScript 1.8, we’ve introduced string literal types.\nThese types are written the same way string literals are, but in type positions.
\nUsers can now ensure that the type system will catch such errors.\nHere’s our new AnimationOptions using string literal types:
\ntsinterface AnimationOptions {\n deltaX: number;\n deltaY: number;\n easing: \"ease-in\" | \"ease-out\" | \"ease-in-out\";\n}\n\n// Error: Type '\"ease-inout\"' is not assignable to type '\"ease-in\" | \"ease-out\" | \"ease-in-out\"'\nnew UIElement().animate({ deltaX: 100, deltaY: 100, easing: \"ease-inout\" });
TypeScript 1.8 improves type inference involving source and target sides that are both union or intersection types.\nFor example, when inferring from string | string[] to string | T, we reduce the types to string[] and T, thus inferring string[] for T.
\ntstype Maybe<T> = T | void;\n\nfunction isDefined<T>(x: Maybe<T>): x is T {\n return x !== undefined && x !== null;\n}\n\nfunction isUndefined<T>(x: Maybe<T>): x is void {\n return x === undefined || x === null;\n}\n\nfunction getOrElse<T>(x: Maybe<T>, defaultValue: T): T {\n return isDefined(x) ? x : defaultValue;\n}\n\nfunction test1(x: Maybe<string>) {\n let x1 = getOrElse(x, \"Undefined\"); // string\n let x2 = isDefined(x) ? x : \"Undefined\"; // string\n let x3 = isUndefined(x) ? \"Undefined\" : x; // string\n}\n\nfunction test2(x: Maybe<number>) {\n let x1 = getOrElse(x, -1); // number\n let x2 = isDefined(x) ? x : -1; // number\n let x3 = isUndefined(x) ? -1 : x; // number\n}
AMD and System modules with --outFileSpecifying --outFile in conjunction with --module amd or --module system will concatenate all modules in the compilation into a single output file containing multiple module closures.
A module name will be computed for each module based on its relative location to rootDir.
\nts// file src/a.ts\nimport * as B from \"./lib/b\";\nexport function createA() {\n return B.createB();\n}
\nts// file src/lib/b.ts\nexport function createB() {\n return {};\n}
Results in:
\n\njsdefine(\"lib/b\", [\"require\", \"exports\"], function(require, exports) {\n \"use strict\";\n function createB() {\n return {};\n }\n exports.createB = createB;\n});\ndefine(\"a\", [\"require\", \"exports\", \"lib/b\"], function(require, exports, B) {\n \"use strict\";\n function createA() {\n return B.createB();\n }\n exports.createA = createA;\n});
default import interop with SystemJSModule loaders like SystemJS wrap CommonJS modules and expose then as a default ES6 import. This makes it impossible to share the definition files between the SystemJS and CommonJS implementation of the module as the module shape looks different based on the loader.
Setting the new compiler flag --allowSyntheticDefaultImports indicates that the module loader performs some kind of synthetic default import member creation not indicated in the imported .ts or .d.ts. The compiler will infer the existence of a default export that has the shape of the entire module itself.
System modules have this flag on by default.
\nlet/const in loopsPreviously an error, now supported in TypeScript 1.8.\nlet/const declarations within loops and captured in functions are now emitted to correctly match let/const freshness semantics.
\ntslet list = [];\nfor (let i = 0; i < 5; i++) {\n list.push(() => i);\n}\n\nlist.forEach(f => console.log(f()));
is compiled to:
\n\njsvar list = [];\nvar _loop_1 = function(i) {\n list.push(function() {\n return i;\n });\n};\nfor (var i = 0; i < 5; i++) {\n _loop_1(i);\n}\nlist.forEach(function(f) {\n return console.log(f());\n});
And results in
\n\ncmd0\n1\n2\n3\n4
for..in statementsPreviously the type of a for..in variable is inferred to any; that allowed the compiler to ignore invalid uses within the for..in body.
Starting with TypeScript 1.8,:
\nfor..in statement is implicitly string.T (such as an array) is indexed by a for..in variable of a containing for..in statement for an object with a numeric index signature and without a string index signature (again such as an array), the value produced is of type T.\ntsvar a: MyObject[];\nfor (var x in a) {\n // Type of x is implicitly string\n var obj = a[x]; // Type of obj is MyObject\n}
\"use strict\"; prologueModules were always parsed in strict mode as per ES6, but for non-ES6 targets this was not respected in the generated code. Starting with TypeScript 1.8, emitted modules are always in strict mode. This shouldn’t have any visible changes in most code as TS considers most strict mode errors as errors at compile time, but it means that some things which used to silently fail at runtime in your TS code, like assigning to NaN, will now loudly fail. You can reference the MDN Article on strict mode for a detailed list of the differences between strict mode and non-strict mode.
.js files with --allowJsOften there are external source files in your project that may not be authored in TypeScript.\nAlternatively, you might be in the middle of converting a JS code base into TS, but still want to bundle all your JS code into a single file with the output of your new TS code.
\n.js files are now allowed as input to tsc.\nThe TypeScript compiler checks the input .js files for syntax errors, and emits valid output based on the --target and --module flags.\nThe output can be combined with other .ts files as well.\nSource maps are still generated for .js files just like with .ts files.
--reactNamespacePassing --reactNamespace <JSX factory Name> along with --jsx react allows for using a different JSX factory from the default React.
The new factory name will be used to call createElement and __spread functions.
\ntsimport { jsxFactory } from \"jsxFactory\";\n\nvar div = <div>Hello JSX!</div>;
Compiled with:
\n\nshelltsc --jsx react --reactNamespace jsxFactory --m commonJS
Results in:
\n\njs\"use strict\";\nvar jsxFactory_1 = require(\"jsxFactory\");\nvar div = jsxFactory_1.jsxFactory.createElement(\"div\", null, \"Hello JSX!\");
this-based type guardsTypeScript 1.8 extends user-defined type guard functions to class and interface methods.
\nthis is T is now valid return type annotation for methods in classes and interfaces.\nWhen used in a type narrowing position (e.g. if statement), the type of the call expression target object would be narrowed to T.
\ntsclass FileSystemObject {\n isFile(): this is File {\n return this instanceof File;\n }\n isDirectory(): this is Directory {\n return this instanceof Directory;\n }\n isNetworked(): this is Networked & this {\n return this.networked;\n }\n constructor(public path: string, private networked: boolean) {}\n}\n\nclass File extends FileSystemObject {\n constructor(path: string, public content: string) {\n super(path, false);\n }\n}\nclass Directory extends FileSystemObject {\n children: FileSystemObject[];\n}\ninterface Networked {\n host: string;\n}\n\nlet fso: FileSystemObject = new File(\"foo/bar.txt\", \"foo\");\nif (fso.isFile()) {\n fso.content; // fso is File\n} else if (fso.isDirectory()) {\n fso.children; // fso is Directory\n} else if (fso.isNetworked()) {\n fso.host; // fso is networked\n}
Starting with TypeScript 1.8, official NuGet packages are available for the Typescript Compiler (tsc.exe) as well as the MSBuild integration (Microsoft.TypeScript.targets and Microsoft.TypeScript.Tasks.dll).
Stable packages are available here:
\n\nAlso, a nightly NuGet package to match the nightly npm package is available on https://myget.org:
\n\ntscWe understand that a ton of monochrome output can be a little difficult on the eyes.\nColors can help discern where a message starts and ends, and these visual clues are important when error output gets overwhelming.
\nBy just passing the --pretty command line option, TypeScript gives more colorful output with context about where things are going wrong.
![\"Showing](\"https://raw.githubusercontent.com/wiki/Microsoft/TypeScript/images/new-in-typescript/pretty01.png\")
With TypeScript 1.8, JSX tags are now classified and colorized in Visual Studio 2015.
\n![\"jsx\"](\"https://cloud.githubusercontent.com/assets/8052307/12271404/b875c502-b90f-11e5-93d8-c6740be354d1.png\")
The classification can be further customized by changing the font and color settings for the VB XML color and font settings through Tools->Options->Environment->Fonts and Colors page.
--project (-p) flag can now take any file pathThe --project command line option originally could only take paths to a folder containing a tsconfig.json.\nGiven the different scenarios for build configurations, it made sense to allow --project to point to any other compatible JSON file.\nFor instance, a user might want to target ES2015 with CommonJS modules for Node 5, but ES5 with AMD modules for the browser.\nWith this new work, users can easily manage two separate build targets using tsc alone without having to perform hacky workarounds like placing tsconfig.json files in separate directories.
The old behavior still remains the same if given a directory - the compiler will try to find a file in the directory named tsconfig.json.
It’s always nice to be able to document your configuration!\ntsconfig.json now accepts single and multi-line comments.
\nts{\n \"compilerOptions\": {\n \"target\": \"ES2015\", // running on node v5, yaay!\n \"sourceMap\": true // makes debugging easier\n },\n /*\n * Excluded files\n */\n \"exclude\": [\n \"file.d.ts\"\n ]\n}
TypeScript 1.8 allows users to use the --outFile argument with special file system entities like named pipes, devices, etc.
As an example, on many Unix-like systems, the standard output stream is accessible by the file /dev/stdout.
\nshelltsc foo.ts --outFile /dev/stdout
This can be used to pipe output between commands as well.
\nAs an example, we can pipe our emitted JavaScript into a pretty printer like pretty-js:
\n\nshelltsc foo.ts --outFile /dev/stdout | pretty-js
tsconfig.json in Visual Studio 2015TypeScript 1.8 allows tsconfig.json files in all project types.\nThis includes ASP.NET v4 projects, Console Application, and the Html Application with TypeScript project types.\nFurther, you are no longer limited to a single tsconfig.json file but can add multiple, and each will be built as part of the project.\nThis allows you to separate the configuration for different parts of your application without having to use multiple different projects.
![\"Showing](\"https://raw.githubusercontent.com/wiki/Microsoft/TypeScript/images/new-in-typescript/tsconfig-in-vs.png\")
We also disable the project properties page when you add a tsconfig.json file.\nThis means that all configuration changes have to be made in the tsconfig.json file itself.
tsconfig.json file, TypeScript files that are not considered part of that context are not compiled.tsconfig.json file, which must be in either the root or the scripts folder.tsconfig.json in most project types.async/await support in ES6 targets (Node v4+)TypeScript now supports asynchronous functions for engines that have native support for ES6 generators, e.g. Node v4 and above.\nAsynchronous functions are prefixed with the async keyword; await suspends the execution until an asynchronous function return promise is fulfilled and unwraps the value from the Promise returned.
In the following example, each input element will be printed out one at a time with a 200ms delay:
\n\nts\"use strict\";\n\n// printDelayed is a 'Promise<void>'\nasync function printDelayed(elements: string[]) {\n for (const element of elements) {\n await delay(200);\n console.log(element);\n }\n}\n\nasync function delay(milliseconds: number) {\n return new Promise<void>(resolve => {\n setTimeout(resolve, milliseconds);\n });\n}\n\nprintDelayed([\"Hello\", \"beautiful\", \"asynchronous\", \"world\"]).then(() => {\n console.log();\n console.log(\"Printed every element!\");\n});
For more information see Async Functions blog post.
\n--target ES6 with --moduleTypeScript 1.7 adds ES6 to the list of options available for the --module flag and allows you to specify the module output when targeting ES6. This provides more flexibility to target exactly the features you want in specific runtimes.
\njson{\n \"compilerOptions\": {\n \"module\": \"amd\",\n \"target\": \"es6\"\n }\n}
this-typingIt is a common pattern to return the current object (i.e. this) from a method to create fluent-style APIs.\nFor instance, consider the following BasicCalculator module:
\ntsexport default class BasicCalculator {\n public constructor(protected value: number = 0) {}\n\n public currentValue(): number {\n return this.value;\n }\n\n public add(operand: number) {\n this.value += operand;\n return this;\n }\n\n public subtract(operand: number) {\n this.value -= operand;\n return this;\n }\n\n public multiply(operand: number) {\n this.value *= operand;\n return this;\n }\n\n public divide(operand: number) {\n this.value /= operand;\n return this;\n }\n}
A user could express 2 * 5 + 1 as
\ntsimport calc from \"./BasicCalculator\";\n\nlet v = new calc(2)\n .multiply(5)\n .add(1)\n .currentValue();
This often opens up very elegant ways of writing code; however, there was a problem for classes that wanted to extend from BasicCalculator.\nImagine a user wanted to start writing a ScientificCalculator:
\ntsimport BasicCalculator from \"./BasicCalculator\";\n\nexport default class ScientificCalculator extends BasicCalculator {\n public constructor(value = 0) {\n super(value);\n }\n\n public square() {\n this.value = this.value ** 2;\n return this;\n }\n\n public sin() {\n this.value = Math.sin(this.value);\n return this;\n }\n}
Because TypeScript used to infer the type BasicCalculator for each method in BasicCalculator that returned this, the type system would forget that it had ScientificCalculator whenever using a BasicCalculator method.
For instance:
\n\ntsimport calc from \"./ScientificCalculator\";\n\nlet v = new calc(0.5)\n .square()\n .divide(2)\n .sin() // Error: 'BasicCalculator' has no 'sin' method.\n .currentValue();
This is no longer the case - TypeScript now infers this to have a special type called this whenever inside an instance method of a class.\nThe this type is written as so, and basically means “the type of the left side of the dot in a method call”.
The this type is also useful with intersection types in describing libraries (e.g. Ember.js) that use mixin-style patterns to describe inheritance:
\ntsinterface MyType {\n extend<T>(other: T): this & T;\n}
TypeScript 1.7 supports upcoming ES7/ES2016 exponentiation operators: ** and **=. The operators will be transformed in the output to ES3/ES5 using Math.pow.
\ntsvar x = 2 ** 3;\nvar y = 10;\ny **= 2;\nvar z = -(4 ** 3);
Will generate the following JavaScript output:
\n\njsvar x = Math.pow(2, 3);\nvar y = 10;\ny = Math.pow(y, 2);\nvar z = -Math.pow(4, 3);
TypeScript 1.7 makes checking of destructuring patterns with an object literal or array literal initializers less rigid and more intuitive.
\nWhen an object literal is contextually typed by the implied type of an object binding pattern:
\nWhen an array literal is contextually typed by the implied type of an array binding pattern:
\n\nts// Type of f1 is (arg?: { x?: number, y?: number }) => void\nfunction f1({ x = 0, y = 0 } = {}) {}\n\n// And can be called as:\nf1();\nf1({});\nf1({ x: 1 });\nf1({ y: 1 });\nf1({ x: 1, y: 1 });\n\n// Type of f2 is (arg?: (x: number, y?: number) => void\nfunction f2({ x, y = 0 } = { x: 0 }) {}\n\nf2();\nf2({}); // Error, x not optional\nf2({ x: 1 });\nf2({ y: 1 }); // Error, x not optional\nf2({ x: 1, y: 1 });
Decorators are now allowed when targeting ES3. TypeScript 1.7 removes the ES5-specific use of reduceRight from the __decorate helper. The changes also inline calls to Object.getOwnPropertyDescriptor and Object.defineProperty in a backwards-compatible fashion that allows for clean up of the emit for ES5 and later by removing various repetitive calls to the aforementioned Object methods.
JSX is an embeddable XML-like syntax. It is meant to be transformed into valid JavaScript, but the semantics of that transformation are implementation-specific. JSX came to popularity with the React library but has since seen other applications. TypeScript 1.6 supports embedding, type checking, and optionally compiling JSX directly into JavaScript.
\n.tsx file extension and as operatorTypeScript 1.6 introduces a new .tsx file extension. This extension does two things: it enables JSX inside of TypeScript files, and it makes the new as operator the default way to cast (removing any ambiguity between JSX expressions and the TypeScript prefix cast operator). For example:
\ntsvar x = <any>foo;\n// is equivalent to:\nvar x = foo as any;
To use JSX-support with React you should use the React typings. These typings define the JSX namespace so that TypeScript can correctly check JSX expressions for React. For example:
\nts/// <reference path=\"react.d.ts\" />\n\ninterface Props {\n name: string;\n}\n\nclass MyComponent extends React.Component<Props, {}> {\n render() {\n return <span>{this.props.foo}</span>;\n }\n}\n\n<MyComponent name=\"bar\" />; // OK\n<MyComponent name={0} />; // error, `name` is not a number
JSX element names and properties are validated against the JSX namespace. Please see the [[JSX]] wiki page for defining the JSX namespace for your framework.
TypeScript ships with two JSX modes: preserve and react.
preserve mode will keep JSX expressions as part of the output to be further consumed by another transform step. Additionally the output will have a .jsx file extension.react mode will emit React.createElement, does not need to go through a JSX transformation before use, and the output will have a .js file extension.See the [[JSX]] wiki page for more information on using JSX in TypeScript.
\nTypeScript 1.6 introduces intersection types, the logical complement of union types. A union type A | B represents an entity that is either of type A or type B, whereas an intersection type A & B represents an entity that is both of type A and type B.
\ntsfunction extend<T, U>(first: T, second: U): T & U {\n let result = <T & U>{};\n for (let id in first) {\n result[id] = first[id];\n }\n for (let id in second) {\n if (!result.hasOwnProperty(id)) {\n result[id] = second[id];\n }\n }\n return result;\n}\n\nvar x = extend({ a: \"hello\" }, { b: 42 });\nvar s = x.a;\nvar n = x.b;
\ntstype LinkedList<T> = T & { next: LinkedList<T> };\n\ninterface Person {\n name: string;\n}\n\nvar people: LinkedList<Person>;\nvar s = people.name;\nvar s = people.next.name;\nvar s = people.next.next.name;\nvar s = people.next.next.next.name;
\ntsinterface A {\n a: string;\n}\ninterface B {\n b: string;\n}\ninterface C {\n c: string;\n}\n\nvar abc: A & B & C;\nabc.a = \"hello\";\nabc.b = \"hello\";\nabc.c = \"hello\";
See issue #1256 for more information.
\nLocal class, interface, enum, and type alias declarations can now appear inside function declarations. Local types are block scoped, similar to variables declared with let and const. For example:
\ntsfunction f() {\n if (true) {\n interface T {\n x: number;\n }\n let v: T;\n v.x = 5;\n } else {\n interface T {\n x: string;\n }\n let v: T;\n v.x = \"hello\";\n }\n}
The inferred return type of a function may be a type declared locally within the function. It is not possible for callers of the function to reference such a local type, but it can of course be matched structurally. For example:
\n\ntsinterface Point {\n x: number;\n y: number;\n}\n\nfunction getPointFactory(x: number, y: number) {\n class P {\n x = x;\n y = y;\n }\n return P;\n}\n\nvar PointZero = getPointFactory(0, 0);\nvar PointOne = getPointFactory(1, 1);\nvar p1 = new PointZero();\nvar p2 = new PointZero();\nvar p3 = new PointOne();
Local types may reference enclosing type parameters and local class and interfaces may themselves be generic. For example:
\n\ntsfunction f3() {\n function f<X, Y>(x: X, y: Y) {\n class C {\n public x = x;\n public y = y;\n }\n return C;\n }\n let C = f(10, \"hello\");\n let v = new C();\n let x = v.x; // number\n let y = v.y; // string\n}
TypeScript 1.6 adds support for ES6 class expressions. In a class expression, the class name is optional and, if specified, is only in scope in the class expression itself. This is similar to the optional name of a function expression. It is not possible to refer to the class instance type of a class expression outside the class expression, but the type can of course be matched structurally. For example:
\n\ntslet Point = class {\n constructor(public x: number, public y: number) {}\n public length() {\n return Math.sqrt(this.x * this.x + this.y * this.y);\n }\n};\nvar p = new Point(3, 4); // p has anonymous class type\nconsole.log(p.length());
TypeScript 1.6 adds support for classes extending arbitrary expression that computes a constructor function. This means that built-in types can now be extended in class declarations.
\nThe extends clause of a class previously required a type reference to be specified. It now accepts an expression optionally followed by a type argument list. The type of the expression must be a constructor function type with at least one construct signature that has the same number of type parameters as the number of type arguments specified in the extends clause. The return type of the matching construct signature(s) is the base type from which the class instance type inherits. Effectively, this allows both real classes and “class-like” expressions to be specified in the extends clause.
Some examples:
\n\nts// Extend built-in types\n\nclass MyArray extends Array<number> {}\nclass MyError extends Error {}\n\n// Extend computed base class\n\nclass ThingA {\n getGreeting() {\n return \"Hello from A\";\n }\n}\n\nclass ThingB {\n getGreeting() {\n return \"Hello from B\";\n }\n}\n\ninterface Greeter {\n getGreeting(): string;\n}\n\ninterface GreeterConstructor {\n new (): Greeter;\n}\n\nfunction getGreeterBase(): GreeterConstructor {\n return Math.random() >= 0.5 ? ThingA : ThingB;\n}\n\nclass Test extends getGreeterBase() {\n sayHello() {\n console.log(this.getGreeting());\n }\n}
abstract classes and methodsTypeScript 1.6 adds support for abstract keyword for classes and their methods. An abstract class is allowed to have methods with no implementation, and cannot be constructed.
\ntsabstract class Base {\n abstract getThing(): string;\n getOtherThing() {\n return \"hello\";\n }\n}\n\nlet x = new Base(); // Error, 'Base' is abstract\n\n// Error, must either be 'abstract' or implement concrete 'getThing'\nclass Derived1 extends Base {}\n\nclass Derived2 extends Base {\n getThing() {\n return \"hello\";\n }\n foo() {\n super.getThing(); // Error: cannot invoke abstract members through 'super'\n }\n}\n\nvar x = new Derived2(); // OK\nvar y: Base = new Derived2(); // Also OK\ny.getThing(); // OK\ny.getOtherThing(); // OK
With TypeScript 1.6, type aliases can be generic. For example:
\n\ntstype Lazy<T> = T | (() => T);\n\nvar s: Lazy<string>;\ns = \"eager\";\ns = () => \"lazy\";\n\ninterface Tuple<A, B> {\n a: A;\n b: B;\n}\n\ntype Pair<T> = Tuple<T, T>;
TypeScript 1.6 enforces stricter object literal assignment checks for the purpose of catching excess or misspelled properties. Specifically, when a fresh object literal is assigned to a variable or passed as an argument for a non-empty target type, it is an error for the object literal to specify properties that don’t exist in the target type.
\n\ntsvar x: { foo: number };\nx = { foo: 1, baz: 2 }; // Error, excess property `baz`\n\nvar y: { foo: number; bar?: number };\ny = { foo: 1, baz: 2 }; // Error, excess or misspelled property `baz`
A type can include an index signature to explicitly indicate that excess properties are permitted:
\n\ntsvar x: { foo: number; [x: string]: any };\nx = { foo: 1, baz: 2 }; // Ok, `baz` matched by index signature
TypeScript 1.6 adds support for generators when targeting ES6.
\nA generator function can have a return type annotation, just like a function. The annotation represents the type of the generator returned by the function. Here is an example:
\n\ntsfunction* g(): Iterable<string> {\n for (var i = 0; i < 100; i++) {\n yield \"\"; // string is assignable to string\n }\n yield* otherStringGenerator(); // otherStringGenerator must be iterable and element type assignable to string\n}
A generator function with no type annotation can have the type annotation inferred. So in the following case, the type will be inferred from the yield statements:
\n\ntsfunction* g() {\n for (var i = 0; i < 100; i++) {\n yield \"\"; // infer string\n }\n yield* otherStringGenerator(); // infer element type of otherStringGenerator\n}
async functionsTypeScript 1.6 introduces experimental support of async functions when targeting ES6. Async functions are expected to invoke an asynchronous operation and await its result without blocking normal execution of the program. This accomplished through the use of an ES6-compatible Promise implementation, and transposition of the function body into a compatible form to resume execution when the awaited asynchronous operation completes.
An async function is a function or method that has been prefixed with the async modifier. This modifier informs the compiler that function body transposition is required, and that the keyword await should be treated as a unary expression instead of an identifier. An Async Function must provide a return type annotation that points to a compatible Promise type. Return type inference can only be used if there is a globally defined, compatible Promise type.
\ntsvar p: Promise<number> = /* ... */;\nasync function fn(): Promise<number> {\n var i = await p; // suspend execution until 'p' is settled. 'i' has type \"number\"\n return 1 + i;\n}\n\nvar a = async (): Promise<number> => 1 + await p; // suspends execution.\nvar a = async () => 1 + await p; // suspends execution. return type is inferred as \"Promise<number>\" when compiling with --target ES6\nvar fe = async function(): Promise<number> {\n var i = await p; // suspend execution until 'p' is settled. 'i' has type \"number\"\n return 1 + i;\n}\n\nclass C {\n async m(): Promise<number> {\n var i = await p; // suspend execution until 'p' is settled. 'i' has type \"number\"\n return 1 + i;\n }\n\n async get p(): Promise<number> {\n var i = await p; // suspend execution until 'p' is settled. 'i' has type \"number\"\n return 1 + i;\n }\n}
While not strictly a language change, nightly builds are now available by installing with the following command:
\nnpm install -g typescript@next\nStarting from release 1.6 TypeScript compiler will use different set of rules to resolve module names when targeting ‘commonjs’. These rules attempted to model module lookup procedure used by Node. This effectively mean that node modules can include information about its typings and TypeScript compiler will be able to find it. User however can override module resolution rules picked by the compiler by using --moduleResolution command line option. Possible values are:
The instance side of an ambient class declaration can be extended using an interface declaration The class constructor object is unmodified. For example:
\n\ntsdeclare class Foo {\n public x: number;\n}\n\ninterface Foo {\n y: string;\n}\n\nfunction bar(foo: Foo) {\n foo.x = 1; // OK, declared in the class Foo\n foo.y = \"1\"; // OK, declared in the interface Foo\n}
TypeScript 1.6 adds a new way to narrow a variable type inside an if block, in addition to typeof and instanceof. A user-defined type guard functions is one with a return type annotation of the form x is T, where x is a declared parameter in the signature, and T is any type. When a user-defined type guard function is invoked on a variable in an if block, the type of the variable will be narrowed to T.
\ntsfunction isCat(a: any): a is Cat {\n return a.name === \"kitty\";\n}\n\nvar x: Cat | Dog;\nif (isCat(x)) {\n x.meow(); // OK, x is Cat in this block\n}
exclude property support in tsconfig.jsonA tsconfig.json file that doesn’t specify a files property (and therefore implicitly references all *.ts files in all subdirectories) can now contain an exclude property that specifies a list of files and/or directories to exclude from the compilation. The exclude property must be an array of strings that each specify a file or folder name relative to the location of the tsconfig.json file. For example:
\n\njson{\n \"compilerOptions\": {\n \"out\": \"test.js\"\n },\n \"exclude\": [\"node_modules\", \"test.ts\", \"utils/t2.ts\"]\n}
The exclude list does not support wilcards. It must simply be a list of files and/or directories.
--init command line optionRun tsc --init in a directory to create an initial tsconfig.json in this directory with preset defaults. Optionally pass command line arguments along with --init to be stored in your initial tsconfig.json on creation.
TypeScript 1.5 supports ECMAScript 6 (ES6) modules. ES6 modules are effectively TypeScript external modules with a new syntax: ES6 modules are separately loaded source files that possibly import other modules and provide a number of externally accessible exports. ES6 modules feature several new export and import declarations. It is recommended that TypeScript libraries and applications be updated to use the new syntax, but this is not a requirement. The new ES6 module syntax coexists with TypeScript’s original internal and external module constructs and the constructs can be mixed and matched at will.
\nIn addition to the existing TypeScript support for decorating declarations with export, module members can also be exported using separate export declarations, optionally specifying different names for exports using as clauses.
\ntsinterface Stream { ... }\nfunction writeToStream(stream: Stream, data: string) { ... }\nexport { Stream, writeToStream as write }; // writeToStream exported as write
Import declarations, as well, can optionally use as clauses to specify different local names for the imports. For example:
\ntsimport { read, write, standardOutput as stdout } from \"./inout\";\nvar s = read(stdout);\nwrite(stdout, s);
As an alternative to individual imports, a namespace import can be used to import an entire module:
\n\ntsimport * as io from \"./inout\";\nvar s = io.read(io.standardOutput);\nio.write(io.standardOutput, s);
Using from clause a module can copy the exports of a given module to the current module without introducing local names.
\ntsexport { read, write, standardOutput as stdout } from \"./inout\";
export * can be used to re-export all exports of another module. This is useful for creating modules that aggregate the exports of several other modules.
\ntsexport function transform(s: string): string { ... }\nexport * from \"./mod1\";\nexport * from \"./mod2\";
An export default declaration specifies an expression that becomes the default export of a module:
\n\ntsexport default class Greeter {\n sayHello() {\n console.log(\"Greetings!\");\n }\n}
Which in turn can be imported using default imports:
\n\ntsimport Greeter from \"./greeter\";\nvar g = new Greeter();\ng.sayHello();
A “bare import” can be used to import a module only for its side-effects.
\n\ntsimport \"./polyfills\";
For more information about module, please see the ES6 module support spec.
\nTypeScript 1.5 adds support to ES6 destructuring declarations and assignments.
\nA destructuring declaration introduces one or more named variables and initializes them with values extracted from properties of an object or elements of an array.
\nFor example, the following sample declares variables x, y, and z, and initializes them to getSomeObject().x, getSomeObject().y and getSomeObject().z respectively:
\ntsvar { x, y, z } = getSomeObject();
Destructuring declarations also works for extracting values from arrays:
\n\ntsvar [x, y, z = 10] = getSomeArray();
Similarly, destructuring can be used in function parameter declarations:
\n\ntsfunction drawText({ text = \"\", location: [x, y] = [0, 0], bold = false }) {\n // Draw text\n}\n\n// Call drawText with an object literal\nvar item = { text: \"someText\", location: [1, 2, 3], style: \"italics\" };\ndrawText(item);
Destructuring patterns can also be used in regular assignment expressions. For instance, swapping two variables can be written as a single destructuring assignment:
\n\ntsvar x = 1;\nvar y = 2;\n[x, y] = [y, x];
namespace keywordTypeScript used the module keyword to define both “internal modules” and “external modules”; this has been a bit of confusion for developers new to TypeScript. “Internal modules” are closer to what most people would call a namespace; likewise, “external modules” in JS speak really just are modules now.
\n\nNote: Previous syntax defining internal modules are still supported.
\n
Before:
\n\ntsmodule Math {\n export function add(x, y) { ... }\n}
After:
\n\ntsnamespace Math {\n export function add(x, y) { ... }\n}
let and const supportES6 let and const declarations are now supported when targeting ES3 and ES5.
\ntsconst MAX = 100;\n\n++MAX; // Error: The operand of an increment or decrement\n// operator cannot be a constant.
\ntsif (true) {\n let a = 4;\n // use a\n} else {\n let a = \"string\";\n // use a\n}\n\nalert(a); // Error: a is not defined in this scope
TypeScript 1.5 adds support to ES6 for..of loops on arrays for ES3/ES5 as well as full support for Iterator interfaces when targetting ES6.
\nThe TypeScript compiler will transpile for..of arrays to idiomatic ES3/ES5 JavaScript when targeting those versions:
\n\ntsfor (var v of expr) {\n}
will be emitted as:
\n\njsfor (var _i = 0, _a = expr; _i < _a.length; _i++) {\n var v = _a[_i];\n}
\n\nTypeScript decorators are based on the ES7 decorator proposal.
\n
A decorator is:
\n\n\nFor more information, please see the Decorators proposal.
\n
Decorators readonly and enumerable(false) will be applied to the property method before it is installed on class C. This allows the decorator to change the implementation, and in this case, augment the descriptor to be writable: false and enumerable: false.
\ntsclass C {\n @readonly\n @enumerable(false)\n method() {}\n}\n\nfunction readonly(target, key, descriptor) {\n descriptor.writable = false;\n}\n\nfunction enumerable(value) {\n return function(target, key, descriptor) {\n descriptor.enumerable = value;\n };\n}
Initializing an object with dynamic properties can be a bit of a burden. Take the following example:
\n\ntstype NeighborMap = { [name: string]: Node };\ntype Node = { name: string; neighbors: NeighborMap };\n\nfunction makeNode(name: string, initialNeighbor: Node): Node {\n var neighbors: NeighborMap = {};\n neighbors[initialNeighbor.name] = initialNeighbor;\n return { name: name, neighbors: neighbors };\n}
Here we need to create a variable to hold on to the neighbor-map so that we can initialize it. With TypeScript 1.5, we can let the compiler do the heavy lifting:
\n\ntsfunction makeNode(name: string, initialNeighbor: Node): Node {\n return {\n name: name,\n neighbors: {\n [initialNeighbor.name]: initialNeighbor\n }\n };\n}
UMD and System module outputIn addition to AMD and CommonJS module loaders, TypeScript now supports emitting modules UMD (Universal Module Definition) and System module formats.
Usage:
\n\n\ntsc —module umd
\n
and
\n\n\ntsc —module system
\n
ES6 introduces escapes that allow users to represent a Unicode codepoint using just a single escape.
\nAs an example, consider the need to escape a string that contains the character ’𠮷‘. In UTF-16/UCS2, ’𠮷’ is represented as a surrogate pair, meaning that it’s encoded using a pair of 16-bit code units of values, specifically 0xD842 and 0xDFB7. Previously this meant that you’d have to escape the codepoint as \"\\uD842\\uDFB7\". This has the major downside that it’s difficult to discern two independent characters from a surrogate pair.
With ES6’s codepoint escapes, you can cleanly represent that exact character in strings and template strings with a single escape: \"\\u{20bb7}\". TypeScript will emit the string in ES3/ES5 as \"\\uD842\\uDFB7\".
In TypeScript 1.4, we added support for template strings for all targets, and tagged templates for just ES6. Thanks to some considerable work done by @ivogabe, we bridged the gap for for tagged templates in ES3 and ES5.
\nWhen targeting ES3/ES5, the following code
\n\ntsfunction oddRawStrings(strs: TemplateStringsArray, n1, n2) {\n return strs.raw.filter((raw, index) => index % 2 === 1);\n}\n\noddRawStrings`Hello \\n${123} \\t ${456}\\n world`;
will be emitted as
\n\njsfunction oddRawStrings(strs, n1, n2) {\n return strs.raw.filter(function(raw, index) {\n return index % 2 === 1;\n });\n}\n(_a = [\"Hello \\n\", \" \\t \", \"\\n world\"]),\n (_a.raw = [\"Hello \\\\n\", \" \\\\t \", \"\\\\n world\"]),\n oddRawStrings(_a, 123, 456);\nvar _a;
/// <amd-dependency path=\"x\" /> informs the compiler about a non-TS module dependency that needs to be injected in the resulting module’s require call; however, there was no way to consume this module in the TS code.
The new amd-dependency name property allows passing an optional name for an amd-dependency:
\nts/// <amd-dependency path=\"legacy/moduleA\" name=\"moduleA\"/>\ndeclare var moduleA: MyType;\nmoduleA.callStuff();
Generated JS code:
\n\njsdefine([\"require\", \"exports\", \"legacy/moduleA\"], function(\n require,\n exports,\n moduleA\n) {\n moduleA.callStuff();\n});
tsconfig.jsonAdding a tsconfig.json file in a directory indicates that the directory is the root of a TypeScript project. The tsconfig.json file specifies the root files and the compiler options required to compile the project. A project is compiled in one of the following ways:
\njson{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"noImplicitAny\": true,\n \"sourceMap\": true\n }\n}
See the tsconfig.json wiki page for more details.
\n--rootDir command line optionOption --outDir duplicates the input hierarchy in the output. The compiler computes the root of the input files as the longest common path of all input files; and then uses that to replicate all its substructure in the output.
Sometimes this is not desirable, for instance inputs FolderA/FolderB/1.ts and FolderA/FolderB/2.ts would result in output structure mirroring FolderA/FolderB/. Now if a new file FolderA/3.ts is added to the input, the output structure will pop out to mirror FolderA/.
--rootDir specifies the input directory to be mirrored in output instead of computing it.
--noEmitHelpers command line optionThe TypeScript compiler emits a few helpers like __extends when needed. The helpers are emitted in every file they are referenced in. If you want to consolidate all helpers in one place, or override the default behavior, use --noEmitHelpers to instructs the compiler not to emit them.
--newLine command line optionBy default the output new line character is \\r\\n on Windows based systems and \\n on *nix based systems. --newLine command line flag allows overriding this behavior and specifying the new line character to be used in generated output files.
--inlineSourceMap and inlineSources command line options--inlineSourceMap causes source map files to be written inline in the generated .js files instead of in a independent .js.map file. --inlineSources allows for additionally inlining the source .ts file into the
Union types are a powerful way to express a value that can be one of several types. For example, you might have an API for running a program that takes a commandline as either a string, a string[] or a function that returns a string. You can now write:
\ntsinterface RunOptions {\n program: string;\n commandline: string[] | string | (() => string);\n}
Assignment to union types works very intuitively — anything you could assign to one of the union type’s members is assignable to the union:
\n\ntsvar opts: RunOptions = /* ... */;\nopts.commandline = '-hello world'; // OK\nopts.commandline = ['-hello', 'world']; // OK\nopts.commandline = [42]; // Error, number is not string or string[]
When reading from a union type, you can see any properties that are shared by them:
\n\ntsif (opts.length === 0) {\n // OK, string and string[] both have 'length' property\n console.log(\"it's empty\");\n}
Using Type Guards, you can easily work with a variable of a union type:
\n\ntsfunction formatCommandline(c: string | string[]) {\n if (typeof c === \"string\") {\n return c.trim();\n } else {\n return c.join(\" \");\n }\n}
With union types able to represent a wide range of type scenarios, we’ve decided to improve the strictness of certain generic calls. Previously, code like this would (surprisingly) compile without error:
\n\ntsfunction equal<T>(lhs: T, rhs: T): boolean {\n return lhs === rhs;\n}\n\n// Previously: No error\n// New behavior: Error, no best common type between 'string' and 'number'\nvar e = equal(42, \"hello\");
With union types, you can now specify the desired behavior at both the function declaration site and the call site:
\n\nts// 'choose' function where types must match\nfunction choose1<T>(a: T, b: T): T {\n return Math.random() > 0.5 ? a : b;\n}\nvar a = choose1(\"hello\", 42); // Error\nvar b = choose1<string | number>(\"hello\", 42); // OK\n\n// 'choose' function where types need not match\nfunction choose2<T, U>(a: T, b: U): T | U {\n return Math.random() > 0.5 ? a : b;\n}\nvar c = choose2(\"bar\", \"foo\"); // OK, c: string\nvar d = choose2(\"hello\", 42); // OK, d: string|number
Union types also allow for better type inference in arrays and other places where you might have multiple kinds of values in a collection:
\n\ntsvar x = [1, \"hello\"]; // x: Array<string|number>\nx[0] = \"world\"; // OK\nx[0] = false; // Error, boolean is not string or number
let declarationsIn JavaScript, var declarations are “hoisted” to the top of their enclosing scope. This can result in confusing bugs:
\ntsconsole.log(x); // meant to write 'y' here\n/* later in the same block */\nvar x = \"hello\";
The new ES6 keyword let, now supported in TypeScript, declares a variable with more intuitive “block” semantics. A let variable can only be referred to after its declaration, and is scoped to the syntactic block where it is defined:
\ntsif (foo) {\n console.log(x); // Error, cannot refer to x before its declaration\n let x = \"hello\";\n} else {\n console.log(x); // Error, x is not declared in this block\n}
let is only available when targeting ECMAScript 6 (--target ES6).
const declarationsThe other new ES6 declaration type supported in TypeScript is const. A const variable may not be assigned to, and must be initialized where it is declared. This is useful for declarations where you don’t want to change the value after its initialization:
\ntsconst halfPi = Math.PI / 2;\nhalfPi = 2; // Error, can't assign to a `const`
const is only available when targeting ECMAScript 6 (--target ES6).
TypeScript now supports ES6 template strings. These are an easy way to embed arbitrary expressions in strings:
\n\ntsvar name = \"TypeScript\";\nvar greeting = `Hello, ${name}! Your name has ${name.length} characters`;
When compiling to pre-ES6 targets, the string is decomposed:
\n\njsvar name = \"TypeScript!\";\nvar greeting =\n \"Hello, \" + name + \"! Your name has \" + name.length + \" characters\";
A common pattern in JavaScript is to use typeof or instanceof to examine the type of an expression at runtime. TypeScript now understands these conditions and will change type inference accordingly when used in an if block.
Using typeof to test a variable:
\ntsvar x: any = /* ... */;\nif(typeof x === 'string') {\n console.log(x.subtr(1)); // Error, 'subtr' does not exist on 'string'\n}\n// x is still any here\nx.unknown(); // OK
Using typeof with union types and else:
\ntsvar x: string | HTMLElement = /* ... */;\nif(typeof x === 'string') {\n // x is string here, as shown above\n}\nelse {\n // x is HTMLElement here\n console.log(x.innerHTML);\n}
Using instanceof with classes and union types:
\ntsclass Dog { woof() { } }\nclass Cat { meow() { } }\nvar pet: Dog|Cat = /* ... */;\nif (pet instanceof Dog) {\n pet.woof(); // OK\n}\nelse {\n pet.woof(); // Error\n}
You can now define an alias for a type using the type keyword:
\ntstype PrimitiveArray = Array<string | number | boolean>;\ntype MyNumber = number;\ntype NgScope = ng.IScope;\ntype Callback = () => void;
Type aliases are exactly the same as their original types; they are simply alternative names.
\nconst enum (completely inlined enums)Enums are very useful, but some programs don’t actually need the generated code and would benefit from simply inlining all instances of enum members with their numeric equivalents. The new const enum declaration works just like a regular enum for type safety, but erases completely at compile time.
\ntsconst enum Suit {\n Clubs,\n Diamonds,\n Hearts,\n Spades\n}\nvar d = Suit.Diamonds;
Compiles to exactly:
\n\njsvar d = 1;
TypeScript will also now compute enum values when possible:
\n\ntsenum MyFlags {\n None = 0,\n Neat = 1,\n Cool = 2,\n Awesome = 4,\n Best = Neat | Cool | Awesome\n}\nvar b = MyFlags.Best; // emits var b = 7;
-noEmitOnError commandline optionThe default behavior for the TypeScript compiler is to still emit .js files if there were type errors (for example, an attempt to assign a string to a number). This can be undesirable on build servers or other scenarios where only output from a “clean” build is desired. The new flag noEmitOnError prevents the compiler from emitting .js code if there were any errors.
This is now the default for MSBuild projects; this allows MSBuild incremental build to work as expected, as outputs are only generated on clean builds.
\nBy default AMD modules are generated anonymous. This can lead to problems when other tools are used to process the resulting modules like a bundler (e.g. r.js).
The new amd-module name tag allows passing an optional module name to the compiler:
\nts//// [amdModule.ts]\n///<amd-module name='NamedModule'/>\nexport class C {}
Will result in assigning the name NamedModule to the module as part of calling the AMD define:
\njs//// [amdModule.js]\ndefine(\"NamedModule\", [\"require\", \"exports\"], function(require, exports) {\n var C = (function() {\n function C() {}\n return C;\n })();\n exports.C = C;\n});
The new protected modifier in classes works like it does in familiar languages like C++, C#, and Java. A protected member of a class is visible only inside subclasses of the class in which it is declared:
\ntsclass Thing {\n protected doSomething() {\n /* ... */\n }\n}\n\nclass MyThing extends Thing {\n public myMethod() {\n // OK, can access protected member from subclass\n this.doSomething();\n }\n}\nvar t = new MyThing();\nt.doSomething(); // Error, cannot call protected member from outside class
Tuple types express an array where the type of certain elements is known, but need not be the same. For example, you may want to represent an array with a string at position 0 and a number at position 1:
\nts// Declare a tuple type\nvar x: [string, number];\n// Initialize it\nx = [\"hello\", 10]; // OK\n// Initialize it incorrectly\nx = [10, \"hello\"]; // Error
When accessing an element with a known index, the correct type is retrieved:
\n\ntsconsole.log(x[0].substr(1)); // OK\nconsole.log(x[1].substr(1)); // Error, 'number' does not have 'substr'
Note that in TypeScript 1.4, when accessing an element outside the set of known indices, a union type is used instead:
\n\ntsx[3] = \"world\"; // OK\nconsole.log(x[5].toString()); // OK, 'string' and 'number' both have toString\nx[6] = true; // Error, boolean isn't number or string
The 1.1 compiler is typically around 4x faster than any previous release. See this blog post for some impressive charts.
\nTypeScript now only strictly enforces the visibility of types in modules if the --declaration flag is provided. This is very useful for Angular scenarios, for example:
","headings":[{"value":"TypeScript 3.8","depth":1},{"value":"Type-Only Imports and Export","depth":2},{"value":"ECMAScript Private Fields","depth":2},{"value":"Which should I use?","depth":3},{"value":"export * as ns Syntax","depth":2},{"value":" Top-Level await","depth":2},{"value":"es2020 for target and module","depth":2},{"value":"JSDoc Property Modifiers","depth":2},{"value":"Better Directory Watching on Linux and watchOptions","depth":2},{"value":"“Fast and Loose” Incremental Checking","depth":2},{"value":"TypeScript 3.7","depth":1},{"value":"Optional Chaining","depth":2},{"value":"Nullish Coalescing","depth":2},{"value":"Assertion Functions","depth":2},{"value":"Better Support for never-Returning Functions","depth":2},{"value":"(More) Recursive Type Aliases","depth":2},{"value":"--declaration and --allowJs","depth":2},{"value":"The useDefineForClassFields Flag and The declare Property Modifier","depth":2},{"value":"Build-Free Editing with Project References","depth":2},{"value":"Uncalled Function Checks","depth":2},{"value":"// @ts-nocheck in TypeScript Files","depth":2},{"value":"Semicolon Formatter Option","depth":2},{"value":"3.7 Breaking Changes","depth":2},{"value":"DOM Changes","depth":3},{"value":"Class Field Mitigations","depth":3},{"value":"Function Truthy Checks","depth":3},{"value":"Local and Imported Type Declarations Now Conflict","depth":3},{"value":"3.7 API Changes","depth":3},{"value":"TypeScript 3.6","depth":2},{"value":"Stricter Generators","depth":2},{"value":"More Accurate Array Spread","depth":2},{"value":"Improved UX Around Promises","depth":2},{"value":"Better Unicode Support for Identifiers","depth":2},{"value":"import.meta Support in SystemJS","depth":2},{"value":"get and set Accessors Are Allowed in Ambient Contexts","depth":2},{"value":"Ambient Classes and Functions Can Merge","depth":2},{"value":"APIs to Support --build and --incremental","depth":2},{"value":"Semicolon-Aware Code Edits","depth":2},{"value":"Smarter Auto-Import Syntax","depth":2},{"value":"await Completions on Promises","depth":2},{"value":"New TypeScript Playground","depth":2},{"value":"TypeScript 3.5","depth":2},{"value":"Speed improvements","depth":2},{"value":"Type-checking speed-ups","depth":3},{"value":"--incremental improvements","depth":3},{"value":"The Omit helper type","depth":2},{"value":"Improved excess property checks in union types","depth":3},{"value":"The --allowUmdGlobalAccess flag","depth":2},{"value":"Smarter union type checking","depth":2},{"value":"Higher order type inference from generic constructors","depth":2},{"value":"TypeScript 3.4","depth":2},{"value":"Faster subsequent builds with the --incremental flag","depth":2},{"value":"Composite projects","depth":3},{"value":"outFile","depth":3},{"value":"Higher order type inference from generic functions","depth":2},{"value":"Improvements for ReadonlyArray and readonly tuples","depth":2},{"value":"A new syntax for ReadonlyArray","depth":3},{"value":"readonly tuples","depth":3},{"value":"readonly mapped type modifiers and readonly arrays","depth":3},{"value":"Caveats","depth":3},{"value":"const assertions","depth":2},{"value":"Caveats","depth":3},{"value":"Type-checking for globalThis","depth":2},{"value":"TypeScript 3.3","depth":2},{"value":"Improved behavior for calling union types","depth":2},{"value":"Caveats","depth":3},{"value":"Incremental file watching for composite projects in --build --watch","depth":2},{"value":"TypeScript 3.2","depth":2},{"value":"strictBindCallApply","depth":2},{"value":"Caveats","depth":3},{"value":"Generic spread expressions in object literals","depth":2},{"value":"Generic object rest variables and parameters","depth":2},{"value":"BigInt","depth":2},{"value":"Caveats","depth":3},{"value":"Non-unit types as union discriminants","depth":2},{"value":"tsconfig.json inheritance via Node.js packages","depth":2},{"value":"The new --showConfig flag","depth":2},{"value":"Object.defineProperty declarations in JavaScript","depth":2},{"value":"TypeScript 3.1","depth":2},{"value":"Mapped types on tuples and arrays","depth":2},{"value":"Properties declarations on functions","depth":2},{"value":"Version selection with typesVersions","depth":2},{"value":"Matching behavior","depth":3},{"value":"Multiple fields","depth":3},{"value":"TypeScript 3.0","depth":2},{"value":"Tuples in rest parameters and spread expressions","depth":2},{"value":"Rest parameters with tuple types","depth":3},{"value":"Spread expressions with tuple types","depth":3},{"value":"Generic rest parameters","depth":3},{"value":"Example","depth":5},{"value":"Optional elements in tuple types","depth":3},{"value":"Example","depth":5},{"value":"Rest elements in tuple types","depth":3},{"value":"Example","depth":5},{"value":"New unknown top type","depth":2},{"value":"Example","depth":5},{"value":"Support for defaultProps in JSX","depth":2},{"value":"Caveats","depth":3},{"value":"Explicit types on defaultProps","depth":4},{"value":"Changes to @types/React","depth":5},{"value":"///tsmodule MyControllers {\n interface ZooScope extends ng.IScope {\n animals: Animal[];\n }\n export class ZooController {\n // Used to be an error (cannot expose ZooScope), but now is only\n // an error when trying to generate .d.ts files\n constructor(public $scope: ZooScope) {}\n /* more code */\n }\n}