null<\/code> and undefined<\/code>, and more.\nTypes also power TypeScript’s editor tooling like the auto-completion, code navigation, and refactorings that you might see in editors like Visual Studio and VS Code.\nIn fact, if you write JavaScript in either of those editors, that experience is powered by TypeScript!\nYou can learn more at the TypeScript website<\/a>.<\/p>\nTo get started using TypeScript through npm with the following command:<\/p>\n
npm install -D typescript\r\n<\/code><\/pre>\nor through NuGet<\/a>.<\/p>\nHere’s a quick list of what’s new in TypeScript 5.5!<\/p>\n
\n- Inferred Type Predicates<\/a><\/li>\n
- Control Flow Narrowing for Constant Indexed Accesses<\/a><\/li>\n
- The JSDoc
@import<\/code> Tag<\/a><\/li>\n- Regular Expression Syntax Checking<\/a><\/li>\n
- Support for New ECMAScript
Set<\/code> Methods<\/a><\/li>\n- Isolated Declarations<\/a><\/li>\n
- The
${configDir}<\/code> Template Variable for Configuration Files<\/a><\/li>\n- Consulting
package.json<\/code> Dependencies for Declaration File Generation<\/a><\/li>\n- Editor and Watch-Mode Reliability Improvements<\/a><\/li>\n
- Performance and Size Optimizations<\/a><\/li>\n
- Easier API Consumption from ECMAScript Modules<\/a><\/li>\n
- The
transpileDeclaration<\/code> API<\/a><\/li>\n- Notable Behavioral Changes<\/a>\n
\n- Disabling Features Deprecated in TypeScript 5.0<\/a><\/li>\n
lib.d.ts<\/code> Changes<\/a><\/li>\n- Stricter Parsing for Decorators<\/a><\/li>\n
undefined<\/code> is No Longer a Definable Type Name<\/a><\/li>\n- Simplified Reference Directive Declaration Emit<\/a><\/li>\n<\/ul>\n<\/li>\n<\/ul>\n
What’s New Since the Beta and RC?<\/h2>\n
Since the beta<\/a>, we’ve made a few changes that we wanted to call out.<\/p>\nFor one, we added support for ECMAScript’s new Set<\/code> methods<\/a>. Additionally, we’ve adjusted the behavior of TypeScript’s new regular expression checking<\/a> to be slightly more lenient, while still erroring on questionable escapes that are only allowed per ECMAScript’s Annex B.<\/p>\nWe’ve also added and documented even more performance optimizations<\/a>: notably, skipped checking in transpileModule<\/code> and optimizations in how TypeScript filters contextual types.\nThese optimizations can lead to faster build and iteration time in many common scenarios.<\/p>\nSince the release candidate (RC)<\/a>, we’ve temporarily reverted our newer work around consulting package.json<\/code> to determine a given file’s module format<\/a>. We received some feedback that this change disrupted certain workflows and caused an unexpected amount of file-watching pressure for larger projects. In TypeScript 5.6, we hope to bring back a more nuanced version of this feature<\/a>, while we also look into optimizations how we can watch for non-existent files.<\/p>\nInferred Type Predicates<\/h2>\n
This section was written by Dan Vanderkam<\/a>, who implemented this feature in TypeScript 5.5<\/a>. Thanks Dan!<\/em><\/p>\nTypeScript’s control flow analysis does a great job of tracking how the type of a variable changes as it moves through your code:<\/p>\n
interface Bird {\r\n commonName: string;\r\n scientificName: string;\r\n sing(): void;\r\n}\r\n\r\n\/\/ Maps country names -> national bird.\r\n\/\/ Not all nations have official birds (looking at you, Canada!)\r\ndeclare const nationalBirds: Map<string, Bird>;\r\n\r\nfunction makeNationalBirdCall(country: string) {\r\n const bird = nationalBirds.get(country); \/\/ bird has a declared type of Bird | undefined\r\n if (bird) {\r\n bird.sing(); \/\/ bird has type Bird inside the if statement\r\n } else {\r\n \/\/ bird has type undefined here.\r\n }\r\n}\r\n<\/code><\/pre>\nBy making you handle the undefined<\/code> case, TypeScript pushes you to write more robust code.<\/p>\nIn the past, this sort of type refinement was more difficult to apply to arrays. This would have been an error in all previous versions of TypeScript:<\/p>\n
function makeBirdCalls(countries: string[]) {\r\n \/\/ birds: (Bird | undefined)[]\r\n const birds = countries\r\n .map(country => nationalBirds.get(country))\r\n .filter(bird => bird !== undefined);\r\n\r\n for (const bird of birds) {\r\n bird.sing(); \/\/ error: 'bird' is possibly 'undefined'.\r\n }\r\n}\r\n<\/code><\/pre>\nThis code is perfectly fine: we’ve filtered all the undefined<\/code> values out of the list.\nBut TypeScript hasn’t been able to follow along.<\/p>\nWith TypeScript 5.5, the type checker is fine with this code:<\/p>\n
function makeBirdCalls(countries: string[]) {\r\n \/\/ birds: Bird[]\r\n const birds = countries\r\n .map(country => nationalBirds.get(country))\r\n .filter(bird => bird !== undefined);\r\n\r\n for (const bird of birds) {\r\n bird.sing(); \/\/ ok!\r\n }\r\n}\r\n<\/code><\/pre>\nNote the more precise type for birds<\/code>.<\/p>\nThis works because TypeScript now infers a type predicate<\/a> for the filter<\/code> function.\nYou can see what’s going on more clearly by pulling it out into a standalone function:<\/p>\n\/\/ function isBirdReal(bird: Bird | undefined): bird is Bird\r\nfunction isBirdReal(bird: Bird | undefined) {\r\n return bird !== undefined;\r\n}\r\n<\/code><\/pre>\nbird is Bird<\/code> is the type predicate.\nIt means that, if the function returns true<\/code>, then it’s a Bird<\/code> (if the function returns false<\/code> then it’s undefined<\/code>).\nThe type declarations for Array.prototype.filter<\/code> know about type predicates, so the net result is that you get a more precise type and the code passes the type checker.<\/p>\nTypeScript will infer that a function returns a type predicate if these conditions hold:<\/p>\n
\n- The function does not have an explicit return type or type predicate annotation.<\/li>\n
- The function has a single
return<\/code> statement and no implicit returns.<\/li>\n- The function does not mutate its parameter.<\/li>\n
- The function returns a
boolean<\/code> expression that’s tied to a refinement on the parameter.<\/li>\n<\/ol>\nGenerally this works how you’d expect.\nHere’s a few more examples of inferred type predicates:<\/p>\n
\/\/ const isNumber: (x: unknown) => x is number\r\nconst isNumber = (x: unknown) => typeof x === 'number';\r\n\r\n\/\/ const isNonNullish: <T>(x: T) => x is NonNullable<T>\r\nconst isNonNullish = <T,>(x: T) => x != null;\r\n<\/code><\/pre>\nPreviously, TypeScript would have just inferred that these functions return boolean<\/code>.\nIt now infers signatures with type predicates like x is number<\/code> or x is NonNullable<T><\/code>.<\/p>\nType predicates have "if and only if" semantics.\nIf a function returns x is T<\/code>, then it means that:<\/p>\n\n- If the function returns
true<\/code> then x<\/code> has the type T<\/code>.<\/li>\n- If the function returns
false<\/code> then x<\/code> does not<\/em> have type T<\/code>.<\/li>\n<\/ol>\nIf you’re expecting a type predicate to be inferred but it’s not, then you may be running afoul of the second rule. This often comes up with "truthiness" checks:<\/p>\n
function getClassroomAverage(students: string[], allScores: Map<string, number>) {\r\n const studentScores = students\r\n .map(student => allScores.get(student))\r\n .filter(score => !!score);\r\n\r\n return studentScores.reduce((a, b) => a + b) \/ studentScores.length;\r\n \/\/ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r\n \/\/ error: Object is possibly 'undefined'.\r\n}\r\n<\/code><\/pre>\nTypeScript did not infer a type predicate for score => !!score<\/code>, and rightly so: if this returns true<\/code> then score<\/code> is a number<\/code>.\nBut if it returns false<\/code>, then score<\/code> could be either undefined<\/code> or a number<\/code> (specifically, 0<\/code>).\nThis is a real bug: if any student got a zero on the test, then filtering out their score will skew the average upwards.\nFewer will be above average and more will be sad!<\/p>\nAs with the first example, it’s better to explicitly filter out undefined<\/code> values:<\/p>\nfunction getClassroomAverage(students: string[], allScores: Map<string, number>) {\r\n const studentScores = students\r\n .map(student => allScores.get(student))\r\n .filter(score => score !== undefined);\r\n\r\n return studentScores.reduce((a, b) => a + b) \/ studentScores.length; \/\/ ok!\r\n}\r\n<\/code><\/pre>\nA truthiness check will<\/em> infer a type predicate for object types, where there’s no ambiguity.\nRemember that functions must return a boolean<\/code> to be a candidate for an inferred type predicate: x => !!x<\/code> might infer a type predicate, but x => x<\/code> definitely won’t.<\/p>\nExplicit type predicates continue to work exactly as before.\nTypeScript will not check whether it would infer the same type predicate.\nExplicit type predicates ("is") are no safer than a type assertion ("as").<\/p>\n
It’s possible that this feature will break existing code if TypeScript now infers a more precise type than you want. For example:<\/p>\n
\/\/ Previously, nums: (number | null)[]\r\n\/\/ Now, nums: number[]\r\nconst nums = [1, 2, 3, null, 5].filter(x => x !== null);\r\n\r\nnums.push(null); \/\/ ok in TS 5.4, error in TS 5.5\r\n<\/code><\/pre>\nThe fix is to tell TypeScript the type that you want using an explicit type annotation:<\/p>\n
const nums: (number | null)[] = [1, 2, 3, null, 5].filter(x => x !== null);\r\nnums.push(null); \/\/ ok in all versions\r\n<\/code><\/pre>\nFor more information, check out the implementing pull request<\/a> and Dan’s blog post about implementing this feature<\/a>.<\/p>\nControl Flow Narrowing for Constant Indexed Accesses<\/h2>\n
TypeScript is now able to narrow expressions of the form obj[key]<\/code> when both obj<\/code> and key<\/code> are effectively constant.<\/p>\nfunction f1(obj: Record<string, unknown>, key: string) {\r\n if (typeof obj[key] === "string") {\r\n \/\/ Now okay, previously was error\r\n obj[key].toUpperCase();\r\n }\r\n}\r\n<\/code><\/pre>\nIn the above, neither obj<\/code> nor key<\/code> are ever mutated, so TypeScript can narrow the type of obj[key]<\/code> to string<\/code> after the typeof<\/code> check.\nFor more information, see the implementing pull request here<\/a>.<\/p>\nThe JSDoc @import<\/code> Tag<\/h2>\nToday, if you want to import something only for type-checking in a JavaScript file, it is cumbersome.\nJavaScript developers can’t simply import a type named SomeType<\/code> if it’s not there at runtime.<\/p>\n\/\/ .\/some-module.d.ts\r\nexport interface SomeType {\r\n \/\/ ...\r\n}\r\n\r\n\/\/ .\/index.js\r\nimport { SomeType } from ".\/some-module"; \/\/ \u274c runtime error!\r\n\r\n\/**\r\n * @param {SomeType} myValue\r\n *\/\r\nfunction doSomething(myValue) {\r\n \/\/ ...\r\n}\r\n<\/code><\/pre>\nSomeType<\/code> won’t exist at runtime, so the import will fail.\nDevelopers can instead use a namespace import instead.<\/p>\nimport * as someModule from ".\/some-module";\r\n\r\n\/**\r\n * @param {someModule.SomeType} myValue\r\n *\/\r\nfunction doSomething(myValue) {\r\n \/\/ ...\r\n}\r\n<\/code><\/pre>\nBut .\/some-module<\/code> is still imported at runtime – which might also not be desirable.<\/p>\nTo avoid this, developers typically had to use import(...)<\/code> types in JSDoc comments.<\/p>\n\/**\r\n * @param {import(".\/some-module").SomeType} myValue\r\n *\/\r\nfunction doSomething(myValue) {\r\n \/\/ ...\r\n}\r\n<\/code><\/pre>\nIf you wanted to reuse the same type in multiple places, you could use a typedef<\/code> to avoid repeating the import.<\/p>\n\/**\r\n * @typedef {import(".\/some-module").SomeType} SomeType\r\n *\/\r\n\r\n\/**\r\n * @param {SomeType} myValue\r\n *\/\r\nfunction doSomething(myValue) {\r\n \/\/ ...\r\n}\r\n<\/code><\/pre>\nThis helps with local uses of SomeType<\/code>, but it gets repetitive for many imports and can be a bit verbose.<\/p>\nThat’s why TypeScript now supports a new @import<\/code> comment tag that has the same syntax as ECMAScript imports.<\/p>\n\/** @import { SomeType } from "some-module" *\/\r\n\r\n\/**\r\n * @param {SomeType} myValue\r\n *\/\r\nfunction doSomething(myValue) {\r\n \/\/ ...\r\n}\r\n<\/code><\/pre>\nHere, we used named imports.\nWe could also have written our import as a namespace import.<\/p>\n
\/** @import * as someModule from "some-module" *\/\r\n\r\n\/**\r\n * @param {someModule.SomeType} myValue\r\n *\/\r\nfunction doSomething(myValue) {\r\n \/\/ ...\r\n}\r\n<\/code><\/pre>\nBecause these are just JSDoc comments, they don’t affect runtime behavior at all.<\/p>\n
We would like to extend a big thanks to Oleksandr Tarasiuk<\/a> who contributed this change<\/a>!<\/p>\nRegular Expression Syntax Checking<\/h2>\n
Until now, TypeScript has typically skipped over most regular expressions in code.\nThis is because regular expressions technically have an extensible grammar and TypeScript never made any effort to compile regular expressions to earlier versions of JavaScript.\nStill, this meant that lots of common problems would go undiscovered in regular expressions, and they would either turn into errors at runtime, or silently fail.<\/p>\n
But TypeScript now does basic syntax checking on regular expressions!<\/p>\n
let myRegex = \/@robot(\\s+(please|immediately)))? do some task\/;\r\n\/\/ ~\r\n\/\/ error!\r\n\/\/ Unexpected ')'. Did you mean to escape it with backslash?\r\n<\/code><\/pre>\nThis is a simple example, but this checking can catch a lot of common mistakes.\nIn fact, TypeScript’s checking goes slightly beyond syntactic checks.\nFor instance, TypeScript can now catch issues around backreferences that don’t exist.<\/p>\n
let myRegex = \/@typedef \\{import\\((.+)\\)\\.([a-zA-Z_]+)\\} \\3\/u;\r\n\/\/ ~\r\n\/\/ error!\r\n\/\/ This backreference refers to a group that does not exist.\r\n\/\/ There are only 2 capturing groups in this regular expression.\r\n<\/code><\/pre>\nThe same applies to named capturing groups.<\/p>\n
let myRegex = \/@typedef \\{import\\((?<importPath>.+)\\)\\.(?<importedEntity>[a-zA-Z_]+)\\} \\k<namedImport>\/;\r\n\/\/ ~~~~~~~~~~~\r\n\/\/ error!\r\n\/\/ There is no capturing group named 'namedImport' in this regular expression.\r\n<\/code><\/pre>\nTypeScript’s checking is now also aware of when certain RegExp features are used when newer than your target version of ECMAScript.\nFor example, if we use named capturing groups like the above in an ES5 target, we’ll get an error.<\/p>\n
let myRegex = \/@typedef \\{import\\((?<importPath>.+)\\)\\.(?<importedEntity>[a-zA-Z_]+)\\} \\k<importedEntity>\/;\r\n\/\/ ~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~\r\n\/\/ error!\r\n\/\/ Named capturing groups are only available when targeting 'ES2018' or later.\r\n<\/code><\/pre>\nThe same is true for certain regular expression flags as well.<\/p>\n
Note that TypeScript’s regular expression support is limited to regular expression literals<\/em>.\nIf you try calling new RegExp<\/code> with a string literal, TypeScript will not check the provided string.<\/p>\nWe would like to thank GitHub user graphemecluster<\/a> who iterated a ton with us to get this feature into TypeScript<\/a>.<\/p>\nSupport for New ECMAScript Set<\/code> Methods<\/h2>\nTypeScript 5.5 declares new proposed methods for the ECMAScript Set<\/code> type<\/a>.<\/p>\nSome of these methods, like union<\/code>, intersection<\/code>, difference<\/code>, and symmetricDifference<\/code>, take another Set<\/code> and return a new Set<\/code> as the result.\nThe other methods, isSubsetOf<\/code>, isSupersetOf<\/code>, and isDisjointFrom<\/code>, take another Set<\/code> and return a boolean<\/code>.\nNone of these methods mutate the original Set<\/code>s.<\/p>\nHere’s a quick example of how you might use these methods and how they behave:<\/p>\n
let fruits = new Set(["apples", "bananas", "pears", "oranges"]);\r\nlet applesAndBananas = new Set(["apples", "bananas"]);\r\nlet applesAndOranges = new Set(["apples", "oranges"]);\r\nlet oranges = new Set(["oranges"]);\r\nlet emptySet = new Set();\r\n\r\n\/\/\/\/\r\n\/\/ union\r\n\/\/\/\/\r\n\r\n\/\/ Set(4)\u00a0{'apples', 'bananas', 'pears', 'oranges'}\r\nconsole.log(fruits.union(oranges));\r\n\r\n\/\/ Set(3)\u00a0{'apples', 'bananas', 'oranges'}\r\nconsole.log(applesAndBananas.union(oranges));\r\n\r\n\/\/\/\/\r\n\/\/ intersection\r\n\/\/\/\/\r\n\r\n\/\/ Set(2)\u00a0{'apples', 'bananas'}\r\nconsole.log(fruits.intersection(applesAndBananas));\r\n\r\n\/\/ Set(0)\u00a0{}\r\nconsole.log(applesAndBananas.intersection(oranges));\r\n\r\n\/\/ Set(1)\u00a0{'apples'}\r\nconsole.log(applesAndBananas.intersection(applesAndOranges));\r\n\r\n\/\/\/\/\r\n\/\/ difference\r\n\/\/\/\/\r\n\r\n\/\/ Set(3)\u00a0{'apples', 'bananas', 'pears'}\r\nconsole.log(fruits.difference(oranges));\r\n\r\n\/\/ Set(2)\u00a0{'pears', 'oranges'}\r\nconsole.log(fruits.difference(applesAndBananas));\r\n\r\n\/\/ Set(1) {'bananas'}\r\nconsole.log(applesAndBananas.difference(applesAndOranges));\r\n\r\n\/\/\/\/\r\n\/\/ symmetricDifference\r\n\/\/\/\/\r\n\r\n\/\/ Set(2)\u00a0{'bananas', 'oranges'}\r\nconsole.log(applesAndBananas.symmetricDifference(applesAndOranges)); \/\/ no apples\r\n\r\n\/\/\/\/\r\n\/\/ isDisjointFrom\r\n\/\/\/\/\r\n\r\n\/\/ true\r\nconsole.log(applesAndBananas.isDisjointFrom(oranges));\r\n\r\n\/\/ false\r\nconsole.log(applesAndBananas.isDisjointFrom(applesAndOranges));\r\n\r\n\/\/ true\r\nconsole.log(fruits.isDisjointFrom(emptySet));\r\n\r\n\/\/ true\r\nconsole.log(emptySet.isDisjointFrom(emptySet));\r\n\r\n\/\/\/\/\r\n\/\/ isSubsetOf\r\n\/\/\/\/\r\n\r\n\/\/ true\r\nconsole.log(applesAndBananas.isSubsetOf(fruits));\r\n\r\n\/\/ false\r\nconsole.log(fruits.isSubsetOf(applesAndBananas));\r\n\r\n\/\/ false\r\nconsole.log(applesAndBananas.isSubsetOf(oranges));\r\n\r\n\/\/ true\r\nconsole.log(fruits.isSubsetOf(fruits));\r\n\r\n\/\/ true\r\nconsole.log(emptySet.isSubsetOf(fruits));\r\n\r\n\/\/\/\/\r\n\/\/ isSupersetOf\r\n\/\/\/\/\r\n\r\n\/\/ true\r\nconsole.log(fruits.isSupersetOf(applesAndBananas));\r\n\r\n\/\/ false\r\nconsole.log(applesAndBananas.isSupersetOf(fruits));\r\n\r\n\/\/ false\r\nconsole.log(applesAndBananas.isSupersetOf(oranges));\r\n\r\n\/\/ true\r\nconsole.log(fruits.isSupersetOf(fruits));\r\n\r\n\/\/ false\r\nconsole.log(emptySet.isSupersetOf(fruits));\r\n<\/code><\/pre>\nWe’d like to thank Kevin Gibbons<\/a> who not only co-championed the feature in ECMAScript, but also provided the declarations for Set<\/code>, ReadonlySet<\/code>, and ReadonlySetLike<\/code> in TypeScript<\/a>!<\/p>\nIsolated Declarations<\/h2>\n
![\"frontend](\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2024\/04\/5-5-beta-isolated-declarations-deps.png\")
<\/p>\n