Today we’re excited to announce the release of TypeScript 4.5!<\/p>\n
If you’re not yet familiar with TypeScript, it’s a language that builds on JavaScript by adding statically checked types<\/em>.\nWhen you use static types, you can run the TypeScript compiler to check for bugs like typos and mismatches in the shapes of your data, and get handy suggestions.\nThese types don’t change your program, and you can remove them to leave you with clean, readable JavaScript.\nGoing beyond catching bugs in your code, TypeScript also assists you in writing code because types can power useful tooling like auto-complete, go-to-definition, and renaming in your editor!\nYou can read more on our website<\/a>.<\/p>\n To get started using TypeScript 4.5, you can get it through NuGet<\/a>, or use npm with the following command:<\/p>\n You can also get editor support by<\/p>\n If you’ve already read our beta<\/a> or RC<\/a> blog posts, you can read up on what’s changed since<\/a>.<\/p>\n Some major highlights of TypeScript 4.5 are:<\/p>\n Since our beta release post<\/a> and RC release post<\/a>, 4.5 has gone through a few changes.<\/p>\n The biggest change we’ve made since the beta is that ECMAScript module support for Node.js 12 has been deferred<\/a> to a future release, and is now only available as an experimental flag in nightly releases.\nThis was not an easy decision, but our team had a combination of concerns around ecosystem readiness and general guidance for how\/when to use the feature<\/a>.\nWe felt it would be better to smooth out the user experience instead of releasing something that would ultimately be too frustrating for most people.\nIn the meantime though, you can still use the new support for Since our RC post, we’ve added notes about new JSDoc features<\/a>.\nWhile these features actually were included in the RC, they didn’t make it into our previous release notes.<\/p>\n From the language editing side, we’ve introduced more snippet completions since TypeScript 4.5 beta – specifically, for method implementation and overrides<\/a>.<\/p>\n We’ve also addressed a performance regression in TypeScript 4.5 introduces a new utility type called the The Now For more information, you can read about this change on GitHub<\/a>.<\/p>\n To ensure that TypeScript and JavaScript support works well out of the box, TypeScript bundles a series of declaration files ( There are two occasional downsides to including these declaration files with TypeScript though:<\/p>\n TypeScript 4.5 introduces a way to override a specific built-in You can then use your package manager to install a specific package to take over for a given Then from 4.5 onwards, you can update TypeScript and your dependency manager’s lockfile will ensure that it uses the exact same version of the DOM types.\nThat means you get to update your types on your own terms.<\/p>\n We’d like to give a shout-out to saschanaz<\/a> who has been extremely helpful and patient as we’ve been building out and experimenting with this feature.<\/p>\n For more information, you can see the implementation of this change<\/a>.<\/p>\n TypeScript 4.5 now can narrow values that have template string types, and also recognizes template string types as discriminants.<\/p>\n As an example, the following used to fail, but now successfully type-checks in TypeScript 4.5.<\/p>\n For more information, see the change that enables this feature<\/a>.<\/p>\n Thanks to Kagami S. Rosylight<\/a>, TypeScript now supports a new You can read up more on this change here<\/a>.<\/p>\n TypeScript often needs to gracefully fail when it detects possibly infinite recursion, or any type expansions that can take a long time and affect your editor experience.\nAs a result, TypeScript has heuristics to make sure it doesn’t go off the rails when trying to pick apart an infinitely-deep type, or working with types that generate a lot of intermediate results.<\/p>\n The above example is intentionally simple and useless, but there are plenty of types that are actually useful, and unfortunately trigger our heuristics.\nAs an example, the following This type can be useful, but if a string has 50 leading spaces, you’ll get an error.<\/p>\n That’s unfortunate, because these kinds of types tend to be extremely useful in modeling operations on strings – for example, parsers for URL routers.\nTo make matters worse, a more useful type typically creates more type instantiations, and in turn has even more limitations on input length.<\/p>\n But there’s a saving grace: That’s why TypeScript 4.5 performs some tail-recursion elimination on conditional types.\nAs long as one branch of a conditional type is simply another conditional type, TypeScript can avoid intermediate instantiations.\nThere are still heuristics to ensure that these types don’t go off the rails, but they are much more generous.<\/p>\n Keep in mind, the following type won’t<\/em> be optimized, since it uses the result of a conditional type by adding it to a union.<\/p>\n If you would like to make it tail-recursive, you can introduce a helper that takes an "accumulator" type parameter, just like with tail-recursive functions.<\/p>\n You can read up more on the implementation here<\/a>.<\/p>\n There are some cases where TypeScript can’t detect that you’re using an import.\nFor example, take the following code:<\/p>\n By default, TypeScript always removes this import because it appears to be unused.\nIn TypeScript 4.5, you can enable a new flag called along with in Vue.js, using its These frameworks generate some code based on markup outside of their Note that this flag has a special requirement when combined with That makes another TypeScript 4.5 feature, For more information, see the pull request here<\/a>.<\/p>\n As mentioned above, When these options are combined, we need a way to signal when an import can be legitimately dropped.\nTypeScript already has something for this with This works, but it would be nice to avoid two import statements for the same module.\nThat’s part of why TypeScript 4.5 allows a In the above example, For more information, see the changes on GitHub<\/a>.<\/p>\n TypeScript 4.5 supports an ECMAScript proposal for checking whether an object has a private field on it.\nYou can now write a class with a One interesting aspect of this feature is that the check We’d like to extend a big thanks to our friends at Bloomberg who contributed this pull request<\/a>: Ashley Claymore<\/a>, Titian Cernicova-Dragomir<\/a>, Kubilay Kahveci<\/a>, and Rob Palmer<\/a>!<\/p>\n TypeScript 4.5 supports an ECMAScript proposal for import assertions<\/em>.\nThis is a syntax used by runtimes to make sure that an import has an expected format.<\/p>\n The contents of these assertions are not checked by TypeScript since they’re host-specific, and are simply left alone so that browsers and runtimes can handle them (and possibly error).<\/p>\n Dynamic The expected type of that second argument is defined by a new type called npm install typescript\r\n<\/code><\/pre>\n\n
\n
lib<\/code> from node_modules<\/code><\/a><\/li>\nAwaited<\/code> Type and Promise<\/code> Improvements<\/a><\/li>\n--module es2022<\/code><\/a><\/li>\ntype<\/code> Modifiers on Import Names<\/a><\/li>\nrealPathSync.native<\/code><\/a><\/li>\n<\/a> What’s New Since the Beta and RC?<\/h2>\n
--module nodenext<\/code> and --moduleResolution nodenext<\/code> as experimental features in nightly builds of TypeScript<\/a>.\nIf you try to use these settings in TypeScript 4.5, you’ll receive an error message directing you to use a nightly build instead.<\/p>\n--build<\/code> mode<\/a> due to excessive realpath<\/code> calls for package.json<\/code> files.\nThis change was made for TypeScript 4.5, but was also back-ported to TypeScript 4.4.4.\nIf this regression blocked you from trying TypeScript 4.4, you should see comparable or better speed in --build<\/code> mode compared to past versions.<\/p>\n<\/a> The
Awaited<\/code> Type and Promise<\/code> Improvements<\/h2>\nAwaited<\/code> type.\nThis type is meant to model operations like await<\/code> in async<\/code> functions, or the .then()<\/code> method on Promise<\/code>s – specifically, the way that they recursively unwrap Promise<\/code>s.<\/p>\n\/\/ A = string\r\ntype A = Awaited<Promise<string>>;\r\n\r\n\/\/ B = number\r\ntype B = Awaited<Promise<Promise<number>>>;\r\n\r\n\/\/ C = boolean | number\r\ntype C = Awaited<boolean | Promise<number>>;\r\n<\/code><\/pre>\nAwaited<\/code> type can be helpful for modeling existing APIs, including JavaScript built-ins like Promise.all<\/code>, Promise.race<\/code>, etc.\nIn fact, some of the problems around inference with Promise.all<\/code> served as motivations for Awaited<\/code>.\nHere’s an example that fails in TypeScript 4.4 and earlier.<\/p>\ndeclare function MaybePromise<T>(value: T): T | Promise<T> | PromiseLike<T>;\r\n\r\nasync function doSomething(): Promise<[number, number]> {\r\n const result = await Promise.all([\r\n MaybePromise(100),\r\n MaybePromise(200)\r\n ]);\r\n\r\n \/\/ Error!\r\n \/\/\r\n \/\/ [number | Promise<100>, number | Promise<200>]\r\n \/\/\r\n \/\/ is not assignable to type\r\n \/\/\r\n \/\/ [number, number]\r\n return result;\r\n}\r\n<\/code><\/pre>\nPromise.all<\/code> leverages certain features with Awaited<\/code> to give much better inference results, and the above example works.<\/p>\n<\/a> Supporting
lib<\/code> from node_modules<\/code><\/h2>\n.d.ts<\/code> files).\nThese declaration files represent the available APIs in the JavaScript language, and the standard browser DOM APIs.\nWhile there are some reasonable defaults based on your target<\/code><\/a>, you can pick and choose which declaration files your program uses by configuring the lib<\/code><\/a> setting in the tsconfig.json<\/code>.<\/p>\n\n
lib<\/code> in a manner similar to how @types\/<\/code> support works.\nWhen deciding which lib<\/code> files TypeScript should include, it will first look for a scoped @typescript\/lib-*<\/code> package in node_modules<\/code>.\nFor example, when including dom<\/code> as an option in lib<\/code>, TypeScript will use the types in node_modules\/@typescript\/lib-dom<\/code> if available.<\/p>\nlib<\/code>\nFor example, today TypeScript publishes versions of the DOM APIs on @types\/web<\/code>.\nIf you wanted to lock your project to a specific version of the DOM APIs, you could add this to your package.json<\/code>:<\/p>\n{\r\n "dependencies": {\r\n "@typescript\/lib-dom": "npm:@types\/web"\r\n }\r\n}\r\n<\/code><\/pre>\n<\/a> Template String Types as Discriminants<\/h2>\n
export interface Success {\r\n type: `${string}Success`;\r\n body: string;\r\n}\r\n\r\nexport interface Error {\r\n type: `${string}Error`;\r\n message: string\r\n}\r\n\r\nexport function handler(r: Success | Error) {\r\n if (r.type === "HttpSuccess") {\r\n \/\/ 'r' has type 'Success'\r\n let token = r.body;\r\n }\r\n}\r\n<\/code><\/pre>\n<\/a>
--module es2022<\/code><\/h2>\nmodule<\/code> setting: es2022<\/code>.\nThe main feature in --module es2022<\/code> is top-level await<\/code>, meaning you can use await<\/code> outside of async<\/code> functions.\nThis was already supported in --module esnext<\/code> (and now --module nodenext<\/code>), but es2022<\/code> is the first stable target for this feature.<\/p>\n<\/a> Tail-Recursion Elimination on Conditional Types<\/h2>\n
type InfiniteBox<T> = { item: InfiniteBox<T> }\r\n\r\ntype Unpack<T> = T extends { item: infer U } ? Unpack<U> : T;\r\n\r\n\/\/ error: Type instantiation is excessively deep and possibly infinite.\r\ntype Test = Unpack<InfiniteBox<number>>\r\n<\/code><\/pre>\nTrimLeft<\/code> type removes spaces from the beginning of a string-like type.\nIf given a string type that has a space at the beginning, it immediately feeds the remainder of the string back into TrimLeft<\/code>.<\/p>\ntype TrimLeft<T extends string> =\r\n T extends ` ${infer Rest}` ? TrimLeft<Rest> : T;\r\n\r\n\/\/ Test = "hello" | "world"\r\ntype Test = TrimLeft<" hello" | " world">;\r\n<\/code><\/pre>\ntype TrimLeft<T extends string> =\r\n T extends ` ${infer Rest}` ? TrimLeft<Rest> : T;\r\n\r\n\/\/ error: Type instantiation is excessively deep and possibly infinite.\r\ntype Test = TrimLeft<" oops">;\r\n<\/code><\/pre>\nTrimLeft<\/code> is written in a way that is tail-recursive<\/em> in one branch.\nWhen it calls itself again, it immediately returns the result and doesn’t do anything with it.\nBecause these types don’t need to create any intermediate results, they can be implemented more quickly and in a way that avoids triggering many of type recursion heuristics that are built into TypeScript.<\/p>\ntype GetChars<S> =\r\n S extends `${infer Char}${infer Rest}` ? Char | GetChars<Rest> : never;\r\n<\/code><\/pre>\ntype GetChars<S> = GetCharsHelper<S, never>;\r\ntype GetCharsHelper<S, Acc> =\r\n S extends `${infer Char}${infer Rest}` ? GetCharsHelper<Rest, Char | Acc> : Acc;\r\n<\/code><\/pre>\n<\/a> Disabling Import Elision<\/h2>\n
import { Animal } from ".\/animal.js";\r\n\r\neval("console.log(new Animal().isDangerous())");\r\n<\/code><\/pre>\n--preserveValueImports<\/code> to prevent TypeScript from stripping out any imported values from your JavaScript outputs.\nGood reasons to use eval<\/code> are few and far between, but something very similar to this happens in Svelte:<\/p>\n<!-- A .svelte File -->\r\n<script>\r\nimport { someFunc } from ".\/some-module.js";\r\n<\/script>\r\n\r\n<button on:click={someFunc}>Click me!<\/button>\r\n<\/code><\/pre>\n<script setup><\/code> feature:<\/p>\n<!-- A .vue File -->\r\n<script setup>\r\nimport { someFunc } from ".\/some-module.js";\r\n<\/script>\r\n\r\n<button @click="someFunc">Click me!<\/button>\r\n<\/code><\/pre>\n<script><\/code> tags, but TypeScript only<\/em> sees code within the <script><\/code> tags.\nThat means TypeScript will automatically drop the import of someFunc<\/code>, and the above code won’t be runnable!\nWith TypeScript 4.5, you can use --preserveValueImports<\/code> to avoid these situations.<\/p>\n--isolatedModules<\/code>: imported\ntypes must<\/em> be marked as type-only because compilers that process single files at a time have no way of knowing whether imports are values that appear unused, or a type that must be removed in order to avoid a runtime crash.<\/p>\n\/\/ Which of these is a value that should be preserved? tsc knows, but `ts.transpileModule`,\r\n\/\/ ts-loader, esbuild, etc. don't, so `isolatedModules` gives an error.\r\nimport { someFunc, BaseType } from ".\/some-module.js";\r\n\/\/ ^^^^^^^^\r\n\/\/ Error: 'BaseType' is a type and must be imported using a type-only import\r\n\/\/ when 'preserveValueImports' and 'isolatedModules' are both enabled.\r\n<\/code><\/pre>\ntype<\/code> modifiers on import names<\/a>, especially important.<\/p>\n<\/a>
type<\/code> Modifiers on Import Names<\/h2>\n--preserveValueImports<\/code> and --isolatedModules<\/code> have special requirements so that there’s no ambiguity for build tools whether it’s safe to drop type imports.<\/p>\n\/\/ Which of these is a value that should be preserved? tsc knows, but `ts.transpileModule`,\r\n\/\/ ts-loader, esbuild, etc. don't, so `isolatedModules` issues an error.\r\nimport { someFunc, BaseType } from ".\/some-module.js";\r\n\/\/ ^^^^^^^^\r\n\/\/ Error: 'BaseType' is a type and must be imported using a type-only import\r\n\/\/ when 'preserveValueImports' and 'isolatedModules' are both enabled.\r\n<\/code><\/pre>\nimport type<\/code>:<\/p>\nimport type { BaseType } from ".\/some-module.js";\r\nimport { someFunc } from ".\/some-module.js";\r\n\r\nexport class Thing implements BaseType {\r\n \/\/ ...\r\n}\r\n<\/code><\/pre>\ntype<\/code> modifier on individual named imports, so that you can mix and match as needed.<\/p>\nimport { someFunc, type BaseType } from ".\/some-module.js";\r\n\r\nexport class Thing implements BaseType {\r\n someMethod() {\r\n someFunc();\r\n }\r\n}\r\n<\/code><\/pre>\nBaseType<\/code> is always guaranteed to be erased and someFunc<\/code> will be preserved under --preserveValueImports<\/code>, leaving us with the following code:<\/p>\nimport { someFunc } from ".\/some-module.js";\r\n\r\nexport class Thing {\r\n someMethod() {\r\n someFunc();\r\n }\r\n}\r\n<\/code><\/pre>\n<\/a> Private Field Presence Checks<\/h2>\n
#private<\/code> field member and see whether another object has the same field by using the in<\/code> operator.<\/p>\nclass Person {\r\n #name: string;\r\n constructor(name: string) {\r\n this.#name = name;\r\n }\r\n\r\n equals(other: unknown) {\r\n return other &&\r\n typeof other === "object" &&\r\n #name in other && \/\/ <- this is new!\r\n this.#name === other.#name;\r\n }\r\n}\r\n<\/code><\/pre>\n#name in other<\/code> implies that other<\/code> must have been constructed as a Person<\/code>, since there’s no other way that field could be present.\nThis is actually one of the key features of the proposal, and it’s why the proposal is named "ergonomic brand checks" – because private fields often act as a "brand" to guard against objects that aren’t instances of their class.\nAs such, TypeScript is able to appropriately narrow the type of other<\/code> on each check, until it ends up with the type Person<\/code>.<\/p>\n<\/a> Import Assertions<\/h2>\n
import obj from ".\/something.json" assert { type: "json" };\r\n<\/code><\/pre>\n\/\/ TypeScript is fine with this.\r\n\/\/ But your browser? Probably not.\r\nimport obj from ".\/something.json" assert {\r\n type: "fluffy bunny"\r\n};\r\n<\/code><\/pre>\nimport()<\/code> calls can also use import assertions through a second argument.<\/p>\nconst obj = await import(".\/something.json", {\r\n assert: { type: "json" }\r\n})\r\n<\/code><\/pre>\n