Today we are excited to announce the availability of TypeScript 6.0!<\/p>\n
If you are not familiar with TypeScript, it’s a language that builds on JavaScript by adding syntax for types, which enables type-checking to catch errors, and provide rich editor tooling.\nYou can learn more about TypeScript and how to get started on the TypeScript website<\/a>.<\/p>\n But if you’re already familiar with the language, you can get TypeScript 6.0 through npm with the following command:<\/p>\n TypeScript 6.0 is a unique release in that we intend for it to be the last release based on the current JavaScript codebase.\nAs announced last year<\/a> (with recent updates here<\/a>), we are working on a new codebase for the TypeScript compiler and language service written in Go that takes advantage of the speed of native code and shared-memory multi-threading.\nThat new codebase will be the foundation of TypeScript 7.0 and beyond.<\/p>\n TypeScript 6.0 acts as the bridge between TypeScript 5.9 and 7.0.\nAs such, most changes in TypeScript 6.0 are meant to help align and prepare for adopting TypeScript 7.0.\nIt may seem surprising to say, but TypeScript 7.0 is actually extremely close to completion<\/strong>.\nYou can try it out in Visual Studio Code<\/a> or install it from npm<\/a>.\nIn fact, if you’re able to adopt TypeScript 6.0, we encourage you to try out the native previews of TypeScript 7.0.<\/p>\n With that said, there are some new features and improvements in TypeScript 6.0s that are not just about alignment.\nLet’s take a look at some of the highlights of this release, followed by a more detailed look at what’s changing for 7.0 and how to prepare for it.<\/p>\n Since TypeScript 6.0 beta, we have made a few noteworthy changes – mostly to align with the behavior of TypeScript 7.0.<\/p>\n One adjustment is in type-checking for function expressions in generic calls, especially those occurring in generic JSX expressions (see this pull request<\/a>).\nThis will typically catch more bugs in existing code, though you may find that some generic calls may need an explicit type argument.<\/p>\n We have also extended our deprecation of import assertion syntax (i.e. Finally, we have updated the DOM types to reflect the latest web standards, including some adjustments to the Temporal APIs as well.<\/p>\n When parameters don’t have explicit types written out, TypeScript can usually infer them based on an expected type, or even through other arguments in the same function call.<\/p>\n Here, TypeScript can infer the type of Strangely enough, the second call to These functions are called contextually sensitive functions<\/em> – basically, functions that have parameters without explicit types.\nEventually the type system will need to figure out types for these parameters – but this is a bit at odds with how inference works in generic functions because the two "pull" on types in different directions.<\/p>\n To solve this, TypeScript skips over contextually sensitive functions during type argument inference, and instead checks and infers from other arguments first.\nIf skipping over contextually sensitive functions doesn’t work, inference just continues across any unchecked arguments, going left-to-right in the argument list.\nIn the example immediately above, TypeScript will skip over the callback during inference for So what’s going on in our earlier examples?<\/p>\n In both examples, The issue is subtle: most functions (like the ones using method syntax) have an implicit But we’re not using TypeScript 6.0 takes this into account when it decides if a function is contextually sensitive or not.\nIf This change was provided<\/a> thanks to the work of Mateusz Burzy\u0144ski<\/a>.<\/p>\n When Node.js added support for modules, it added a feature called "subpath imports"<\/a>.\nThis is basically a field called This allows modules in instead of using a relative path like the following.<\/p>\n One minor annoyance with this feature has been that developers always had to write something<\/em> after the Developers who have used bundlers are also accustomed to using path-mapping to avoid long relative paths.\nA familiar convention with bundlers has been to use a simple But more recently, Node.js added support for subpath imports starting with This is supported in newer Node.js 20 releases, and so TypeScript now supports it under the options This work was done thanks to magic-akari<\/a>, and the implementing pull request can be found here<\/a>.<\/p>\n TypeScript’s Projects will often want to instead plan out a migration towards either<\/p>\n depending on your project type (e.g. bundled web app, Bun app, or Node.js app).<\/p>\n More information can be found at this implementing pull request<\/a>.<\/p>\n As part of our ongoing work on TypeScript’s native port<\/a>, we’ve introduced a new flag called Today, TypeScript assigns type IDs (internal tracking numbers) to types in the order they are encountered, and uses these IDs to sort union types in a consistent manner.\nA similar process occurs for properties.\nAs a result, the order in which things are declared in a program can have possibly surprising effects on things like declaration emit.<\/p>\n For example, consider the declaration emit from this file:<\/p>\n If we add an unrelated This happens because the literal type One of the major architectural improvements in TypeScript 7 is parallel type checking, which dramatically improves overall check time.\nHowever, parallelism introduces a challenge: when different type-checkers visit nodes, types, and symbols in different orders, the internal IDs assigned to these constructs become non-deterministic.\nThis in turn leads to confusing non-deterministic output, where two files with identical contents in the same program can produce different declaration files, or even calculate different errors when analyzing the same file.\nTo fix this, TypeScript 7.0 sorts its internal objects (e.g. types and symbols) according to a deterministic algorithm based on the content of the object.\nThis ensures that all checkers encounter the same object order regardless of how and when they were created.\nAs a consequence, in the given example, TypeScript 7 will always<\/em> print This means that TypeScript 6 and 7 can and do sometimes display different ordering.\nWhile these ordering changes are almost always benign, if you’re comparing compiler outputs between runs (for example, checking emitted declaration files in 6.0 vs 7.0), these different orderings can produce a lot of noise that makes it difficult to assess correctness.\nOccasionally though, you may witness a change in ordering that causes a type error to appear or disappear, which can be even more confusing.<\/p>\n To help with this situation, in 6.0, you can specify the new If you encounter a type error using or a variable annotation for an argument you intend to pass into a call.<\/p>\n Note that this flag is only intended to help diagnose differences between 6.0 and 7.0 – it is not intended to be used as a long-term feature<\/strong><\/p>\n See more at this pull-request<\/a>.<\/p>\n TypeScript 6.0 adds support for the The long-awaited Temporal proposal<\/a> has reached stage 4 and will be part of a future ECMAScript standard.\nTypeScript 6.0 now includes built-in types for the Temporal API, so you can start using it in your TypeScript code today via Temporal is already usable in several runtimes, and with stage 4 status it is now officially part of the JavaScript language.\nDocumentation on the Temporal APIs is available on MDN<\/a>.<\/p>\n This work<\/a> was contributed thanks to GitHub user Renegade334<\/a>.<\/p>\n A common pattern with This pattern can be tedious.\nECMAScript’s "upsert" proposal<\/a> recently reached stage 4, and introduces 2 new methods on These methods have been added to the With This callback is also given the key as an argument, which can be useful for cases where the default value is based on the key.<\/p>\n This update<\/a> was contributed thanks to GitHub user Renegade334<\/a>.<\/p>\n When constructing some literal string to match within a regular expression, it is important to escape special regular expression characters like This work<\/a> was contributed thanks Kenta Moriuchi<\/a>.<\/p>\n TypeScript’s In TypeScript 6.0, the contents of This is a quality-of-life improvement that eliminates a common point of confusion, since no major modern browser lacks these capabilities.\nIf you were already including both npm install -D typescript\r\n<\/code><\/pre>\nWhat’s New Since the Beta and RC?<\/h2>\n
import ... assert {...}<\/code>) to import()<\/code> calls<\/a> like import(..., { assert: {...}})<\/code><\/p>\nLess Context-Sensitivity on
this<\/code>-less Functions<\/h2>\ndeclare function callIt<T>(obj: {\r\n produce: (x: number) => T,\r\n consume: (y: T) => void,\r\n}): void;\r\n\r\n\/\/ Works, no issues.\r\ncallIt({\r\n produce: (x: number) => x * 2,\r\n consume: y => y.toFixed(),\r\n});\r\n\r\n\/\/ Works, no issues even though the order of the properties is flipped.\r\ncallIt({\r\n consume: y => y.toFixed(),\r\n produce: (x: number) => x * 2,\r\n});\r\n<\/code><\/pre>\ny<\/code> in the consume<\/code> function based on the inferred T<\/code> from the produce<\/code> function, regardless of the order of the properties.\nBut what about if these functions were written using method syntax<\/em> instead of arrow function syntax?<\/p>\ndeclare function callIt<T>(obj: {\r\n produce: (x: number) => T,\r\n consume: (y: T) => void,\r\n}): void;\r\n\r\n\/\/ Works fine, `x` is inferred to be a number.\r\ncallIt({\r\n produce(x: number) { return x * 2; },\r\n consume(y) { return y.toFixed(); },\r\n});\r\n\r\ncallIt({\r\n consume(y) { return y.toFixed(); },\r\n \/\/ ~\r\n \/\/ error: 'y' is of type 'unknown'.\r\n\r\n produce(x: number) { return x * 2; },\r\n});\r\n<\/code><\/pre>\ncallIt<\/code> results in an error because TypeScript is not able to infer the type of y<\/code> in the consume<\/code> method.\nWhat’s happening here is that when TypeScript is trying to find candidates for T<\/code>, it will first skip over functions whose parameters don’t have explicit types.\nIt does this because certain functions may need the inferred type of T<\/code> to be correctly checked – in our case, we need to know the type of T<\/code> to analyze our consume<\/code> function.<\/p>\nfunction callFunc<T>(callback: (x: T) => void, value: T) {\r\n return callback(value);\r\n}\r\n\r\ncallFunc(x => x.toFixed(), 42);\r\n\/\/ ^\r\n\/\/ We need to figure out the type of `x` here,\r\n\/\/ but we also need to figure out the type of `T` to check the callback.\r\n<\/code><\/pre>\nT<\/code>, but will then look at the second argument, 42<\/code>, and infer that T<\/code> is number<\/code>.\nThen, when it comes back to check the callback, it will have a contextual type of (x: number) => void<\/code>, which allows it to infer that x<\/code> is a number<\/code> as well.<\/p>\n\/\/ Arrow syntax - no errors.\r\ncallIt({\r\n consume: y => y.toFixed(),\r\n produce: (x: number) => x * 2,\r\n});\r\n\r\n\/\/ Method syntax - errors!\r\ncallIt({\r\n consume(y) { return y.toFixed(); },\r\n \/\/ ~\r\n \/\/ error: 'y' is of type 'unknown'.\r\n\r\n produce(x: number) { return x * 2; },\r\n});\r\n<\/code><\/pre>\nproduce<\/code> is assigned a function with an explicitly-typed x<\/code> parameter.\nShouldn’t they be checked identically?<\/p>\nthis<\/code> parameter, but arrow functions do not.\nAny usage of this<\/code> could require "pulling" on the type of T<\/code> – for example, knowing the type of the containing object literal could in turn require the type of consume<\/code>, which uses T<\/code>.<\/p>\nthis<\/code>!\nSure, the function might have a this<\/code> value at runtime, but it’s never used!<\/p>\nthis<\/code> is never actually used<\/em> in a function, then it is not considered contextually sensitive.\nThat means these functions will be seen as higher-priority when it comes to type inference, and all of our examples above now work!<\/p>\nSubpath Imports Starting with
#\/<\/code><\/h2>\nimports<\/code><\/a> which allows packages to create internal aliases for modules within their package.<\/p>\n{\r\n "name": "my-package",\r\n "type": "module",\r\n "imports": {\r\n "#root\/*": ".\/dist\/*"\r\n }\r\n}\r\n<\/code><\/pre>\nmy-package<\/code> to import from paths starting with #root\/<\/code><\/p>\nimport * as utils from "#root\/utils.js";\r\n<\/code><\/pre>\nimport * as utils from "..\/..\/utils.js";\r\n<\/code><\/pre>\n#<\/code> when specifying a subpath import.\nHere, we used root<\/code>, but it is a bit useless since there is no directory we’re mapping over other than .\/dist\/<\/code><\/p>\n@\/<\/code> as the prefix.\nUnfortunately, subpath imports could not start with #\/<\/code> at all, leading to a lot of confusion for developers trying to adopt them in their projects.<\/p>\n#\/<\/code><\/a>.\nThis allows packages to use a simple #\/<\/code> prefix for their subpath imports without needing to add an extra segment.<\/p>\n{\r\n "name": "my-package",\r\n "type": "module",\r\n "imports": {\r\n "#\/*": ".\/dist\/*"\r\n }\r\n}\r\n<\/code><\/pre>\nnodenext<\/code> and bundler<\/code> for the --moduleResolution<\/code> setting.<\/p>\nCombining
--moduleResolution bundler<\/code> with --module commonjs<\/code><\/h2>\n--moduleResolution bundler<\/code> setting was previously only allowed to be used with --module esnext<\/code> or --module preserve<\/code>;\nhowever, with the deprecation of --moduleResolution node<\/code> (a.k.a. --moduleResolution node10<\/code>), this new combination is often the most suitable upgrade path for many projects.<\/p>\n\n
--module preserve<\/code> and --moduleResolution bundler<\/code><\/li>\n--module nodenext<\/code><\/li>\n<\/ul>\nThe
--stableTypeOrdering<\/code> Flag<\/h2>\n--stableTypeOrdering<\/code> intended to assist with 6.0-to-7.0 migrations.<\/p>\n\/\/ Input: some-file.ts\r\nexport function foo(condition: boolean) {\r\n return condition ? 100 : 500;\r\n}\r\n\r\n\/\/ Output: some-file.d.ts\r\nexport declare function foo(condition: boolean): 100 | 500;\r\n\/\/ ^^^^^^^^^\r\n\/\/ Note the order of this union: 100, then 500.\r\n<\/code><\/pre>\nconst<\/code> above<\/em> foo<\/code>, the declaration emit changes:<\/p>\n\/\/ Input: some-file.ts\r\nconst x = 500;\r\nexport function foo(condition: boolean) {\r\n return condition ? 100 : 500;\r\n}\r\n\r\n\/\/ Output: some-file.d.ts\r\nexport declare function foo(condition: boolean): 500 | 100;\r\n\/\/ ^^^^^^^^^\r\n\/\/ Note the change in order here.\r\n<\/code><\/pre>\n500<\/code> gets a lower type ID than 100<\/code> because it was processed first when analyzing the const x<\/code> declaration.\nIn very rare cases this change in ordering can even cause errors to appear or disappear based on program processing order, but in general, the main place you might notice this ordering is in the emitted declaration files, or in the way types are displayed in your editor.<\/p>\n100 | 500<\/code>, removing the ordering instability entirely.<\/p>\n--stableTypeOrdering<\/code> flag.\nThis makes 6.0’s type ordering behavior match 7.0’s, reducing the number of differences between the two codebases.\nNote that we don’t necessarily encourage using this flag all the time as it can add a substantial slowdown to type-checking (up to 25% depending on codebase).<\/p>\n--stableTypeOrdering<\/code>, this is typically due to inference differences.\nThe previous inference without --stableTypeOrdering<\/code> happened<\/em> to work based on the current ordering of types in your program.\nTo help with this, you’ll often benefit from providing an explicit type somewhere.\nOften, this will be a type argument<\/p>\n- someFunctionCall(\/*...*\/);\r\n+ someFunctionCall<SomeExplicitType>(\/*...*\/);\r\n<\/code><\/pre>\n- const someVariable = { \/*... some complex object ...*\/ };\r\n+ const someVariable: SomeExplicitType = { \/*... some complex object ...*\/ };\r\n\r\nsomeFunctionCall(someVariable);\r\n<\/code><\/pre>\nes2025<\/code> option for target<\/code> and lib<\/code><\/h2>\nes2025<\/code> option for both target<\/code> and lib<\/code>.\nWhile there are no new JavaScript language features in ES2025, this new target adds new types for built-in APIs (e.g. RegExp.escape<\/code>), and moves a few declarations from esnext<\/code> into es2025<\/code> (e.g. Promise.try<\/code>, Iterator<\/code> methods, and Set<\/code> methods).\nWork to enable the new target<\/a> was contributed thanks to Kenta Moriuchi<\/a>.<\/p>\nNew Types for
Temporal<\/code><\/h2>\n--target esnext<\/code> or "lib": ["esnext"]<\/code> (or the more-granular esnext.temporal<\/code>).<\/p>\nlet yesterday = Temporal.Now.instant().subtract({\r\n hours: 24,\r\n});\r\n\r\nlet tomorrow = Temporal.Now.instant().add({\r\n hours: 24,\r\n});\r\n\r\nconsole.log(`Yesterday: ${yesterday}`);\r\nconsole.log(`Tomorrow: ${tomorrow}`);\r\n<\/code><\/pre>\nNew Types for "upsert" Methods (a.k.a.
getOrInsert<\/code>)<\/h2>\nMap<\/code>s is to check if a key exists, and if not, set and fetch a default value.<\/p>\nfunction processOptions(compilerOptions: Map<string, unknown>) {\r\n let strictValue: unknown;\r\n if (compilerOptions.has("strict")) {\r\n strictValue = compilerOptions.get("strict");\r\n }\r\n else {\r\n strictValue = true;\r\n compilerOptions.set("strict", strictValue);\r\n }\r\n \/\/ ...\r\n}\r\n<\/code><\/pre>\nMap<\/code> and WeakMap<\/code>:<\/p>\n\n
getOrInsert<\/code><\/li>\ngetOrInsertComputed<\/code><\/li>\n<\/ul>\nesnext<\/code> lib so that you can start using them immediately in TypeScript 6.0.<\/p>\ngetOrInsert<\/code>, we can replace our code above with the following:<\/p>\nfunction processOptions(compilerOptions: Map<string, unknown>) {\r\n let strictValue = compilerOptions.getOrInsert("strict", true);\r\n \/\/ ...\r\n}\r\n<\/code><\/pre>\ngetOrInsertComputed<\/code> works similarly, but is for cases where the default value may be expensive to compute (e.g. requires lots of computations, allocations, or does long-running synchronous I\/O).\nInstead, it takes a callback that will only be called if the key is not already present.<\/p>\nsomeMap.getOrInsertComputed("someKey", () => {\r\n return computeSomeExpensiveValue(\/*...*\/);\r\n});\r\n<\/code><\/pre>\nsomeMap.getOrInsertComputed(someKey, computeSomeExpensiveDefaultValue);\r\n\r\nfunction computeSomeExpensiveValue(key: string) {\r\n \/\/ ...\r\n}\r\n<\/code><\/pre>\nRegExp.escape<\/code><\/h2>\n*<\/code>, +<\/code>, ?<\/code>, (<\/code>, )<\/code>, etc.\nThe RegExp Escaping ECMAScript proposal<\/a> has reached stage 4, and introduces a new RegExp.escape<\/code> function that takes care of this for you.<\/p>\nfunction matchWholeWord(word: string, text: string) {\r\n const escapedWord = RegExp.escape(word);\r\n const regex = new RegExp(`\\\\b${escapedWord}\\\\b`, "g");\r\n return text.match(regex);\r\n}\r\n<\/code><\/pre>\nRegExp.escape<\/code> is available in the es2025<\/code> lib, so you can start using it in TypeScript 6.0 today.<\/p>\nThe
dom<\/code> lib Now Contains dom.iterable<\/code> and dom.asynciterable<\/code><\/h2>\nlib<\/code> option allows you to specify which global declarations your target runtime has.\nOne option is dom<\/code> to represent web environments (i.e. browsers, who implement the DOM APIs<\/a>).\nPreviously, the DOM APIs were partially split out into dom.iterable<\/code> and dom.asynciterable<\/code> for environments that didn’t support Iterable<\/code>s and AsyncIterable<\/code>s.\nThis meant that you had to explicitly add dom.iterable<\/code> to use iteration methods on DOM collections like NodeList<\/code> or HTMLCollection<\/code>.<\/p>\nlib.dom.iterable.d.ts<\/code> and lib.dom.asynciterable.d.ts<\/code> are fully included in lib.dom.d.ts<\/code>.\nYou can still reference dom.iterable<\/code> and dom.asynciterable<\/code> in your configuration file’s "lib"<\/code> array, but they are now just empty files.<\/p>\n\/\/ Before TypeScript 6.0, this required "lib": ["dom", "dom.iterable"]\r\n\/\/ Now it works with just "lib": ["dom"]\r\nfor (const element of document.querySelectorAll("div")) {\r\n console.log(element.textContent);\r\n}\r\n<\/code><\/pre>\ndom<\/code> and dom.iterable<\/code>, you can now simplify to just dom<\/code>.<\/p>\n