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:
\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>(obj: Record<K, T>, f: (x: T) => U): 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 ESnext 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\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\": [\n \"main.ts\",\n \"supplemental.ts\"\n ]\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.
","headings":[{"value":"keyof and Lookup Types","depth":2},{"value":"Example","depth":5},{"value":"Example","depth":5},{"value":"Mapped Types","depth":2},{"value":"Partial, Readonly, Record, and Pick","depth":2},{"value":"Object Spread and Rest","depth":2},{"value":"Downlevel Async Functions","depth":2},{"value":"Example","depth":5},{"value":"tsconfig.json","depth":5},{"value":"dramaticWelcome.ts","depth":5},{"value":"Support for external helpers library (tslib)","depth":2},{"value":"Untyped imports","depth":2},{"value":"Example","depth":5},{"value":"Support for --target ES2016, --target ES2017 and --target ESNext","depth":2},{"value":"Improved any Inference","depth":2},{"value":"Example","depth":5},{"value":"Implicit any errors","depth":2},{"value":"Example","depth":5},{"value":"Better inference for literal types","depth":2},{"value":"Example","depth":5},{"value":"Example","depth":5},{"value":"Use returned values from super calls as ‘this’","depth":2},{"value":"Example","depth":5},{"value":"Configuration inheritance","depth":2},{"value":"Example","depth":5},{"value":"New --alwaysStrict","depth":2}],"frontmatter":{"permalink":"/docs/handbook/release-notes/typescript-2-1.html","title":"TypeScript 2.1"}}},"pageContext":{"slug":"/docs/handbook/release-notes/typescript-2-1.html","isOldHandbook":true}}}