TypeScript 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}\nelse {\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 particularly 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\": return s.size * s.size;\n case \"rectangle\": return s.width * s.height;\n case \"circle\": return Math.PI * s.radius * s.radius;\n }\n}\n\nfunction test1(s: Shape) {\n if (s.kind === \"square\") {\n s; // Square\n }\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 }\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\" ? 1 :\n direction === \"down\" ? -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(() => { throw new Error(); })
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\": [\n \"src/**/*\"\n ],\n \"exclude\": [\n \"node_modules\",\n \"**/*.spec.ts\"\n ]\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\": [\n \"src/views\",\n \"generated/templates/views\"\n ]\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\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) { // 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.t.
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\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.