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 { A, B, C }\nconst enum E2 { A = \"A\", B = \"B\", C = \"C\" }\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 { A, B, C }\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>(strs: TemplateStringsArray): 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.