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 Visual Studio and VS Code.\nIn fact, if you’ve been writing JavaScript in either of those editors, you’ve been using TypeScript all this time!<\/p>\nTo get started using TypeScript through NuGet<\/a> or through npm with the following command:<\/p>\nnpm install -D typescript\r\n<\/code><\/pre>\nHere’s a quick list of what’s new in TypeScript 5.4!<\/p>\n
\n- Preserved Narrowing in Closures Following Last Assignments<\/a><\/li>\n
- The
NoInfer<\/code> Utility Type<\/a><\/li>\nObject.groupBy<\/code> and Map.groupBy<\/code><\/a><\/li>\n- Support for
require()<\/code> calls in --moduleResolution bundler<\/code> and --module preserve<\/code><\/a><\/li>\n- Checked Import Attributes and Assertions<\/a><\/li>\n
- Quick Fix for Adding Missing Parameters<\/a><\/li>\n
- Auto-Import Support for Subpath Imports<\/a><\/li>\n
- Upcoming 5.5 Deprecations<\/a><\/li>\n
- Notable Behavioral Changes<\/a><\/li>\n<\/ul>\n
What’s New Since the Beta and RC?<\/h2>\n
Since the beta, we’ve updated the release notes to document new notable behavioral changes<\/a>, including restrictions around enum compatibility, restrictions on enum member naming, and improvements in mapped type behavior.<\/p>\nSince the release candidate, we’ve documented our new auto-import support for subpath imports<\/a>.<\/p>\nPreserved Narrowing in Closures Following Last Assignments<\/h2>\n
TypeScript can usually figure out a more specific type for a variable based on checks that you might perform.\nThis process is called narrowing.<\/p>\n
function uppercaseStrings(x: string | number) {\r\n if (typeof x === "string") {\r\n \/\/ TypeScript knows 'x' is a 'string' here.\r\n return x.toUpperCase();\r\n }\r\n}\r\n<\/code><\/pre>\nOne common pain-point was that these narrowed types weren’t always preserved within function closures.<\/p>\n
function getUrls(url: string | URL, names: string[]) {\r\n if (typeof url === "string") {\r\n url = new URL(url);\r\n }\r\n\r\n return names.map(name => {\r\n url.searchParams.set("name", name)\r\n \/\/ ~~~~~~~~~~~~\r\n \/\/ error!\r\n \/\/ Property 'searchParams' does not exist on type 'string | URL'.\r\n\r\n return url.toString();\r\n });\r\n}\r\n<\/code><\/pre>\nHere, TypeScript decided that it wasn’t "safe" to assume that url<\/code> was actually<\/em> a URL<\/code> object in our callback function because it was mutated elsewhere;\nhowever, in this instance, that arrow function is always<\/em> created after that assignment to url<\/code>, and it’s also the last<\/em> assignment to url<\/code>.<\/p>\nTypeScript 5.4 takes advantage of this to make narrowing a little smarter.\nWhen parameters and let<\/code> variables are used in non-hoisted<\/a> functions, the type-checker will look for a last assignment point.\nIf one is found, TypeScript can safely narrow from outside the containing function.\nWhat that means is the above example just works now.<\/p>\nNote that narrowing analysis doesn’t kick in if the variable is assigned anywhere in a nested function.\nThis is because there’s no way to know for sure whether the function will be called later.<\/p>\n
function printValueLater(value: string | undefined) {\r\n if (value === undefined) {\r\n value = "missing!";\r\n }\r\n\r\n setTimeout(() => {\r\n \/\/ Modifying 'value', even in a way that shouldn't affect\r\n \/\/ its type, will invalidate type refinements in closures.\r\n value = value;\r\n }, 500);\r\n\r\n setTimeout(() => {\r\n console.log(value.toUpperCase());\r\n \/\/ ~~~~~\r\n \/\/ error! 'value' is possibly 'undefined'.\r\n }, 1000);\r\n}\r\n<\/code><\/pre>\nThis should make lots of typical JavaScript code easier to express.\nYou can read more about the change on GitHub<\/a>.<\/p>\nThe NoInfer<\/code> Utility Type<\/h2>\nWhen calling generic functions, TypeScript is able to infer type arguments from whatever you pass in.<\/p>\n
function doSomething<T>(arg: T) {\r\n \/\/ ...\r\n}\r\n\r\n\r\n\/\/ We can explicitly say that 'T' should be 'string'.\r\ndoSomething<string>("hello!");\r\n\r\n\/\/ We can also just let the type of 'T' get inferred.\r\ndoSomething("hello!");\r\n<\/code><\/pre>\nOne challenge, however, is that it is not always clear what the "best" type is to infer.\nThis might lead to TypeScript rejecting valid calls, accepting questionable calls, or just reporting worse error messages when it catches a bug.<\/p>\n
For example, let’s imagine a createStreetLight<\/code> function that takes a list of color names, along with an optional default color.<\/p>\nfunction createStreetLight<C extends string>(colors: C[], defaultColor?: C) {\r\n \/\/ ...\r\n}\r\n\r\ncreateStreetLight(["red", "yellow", "green"], "red");\r\n<\/code><\/pre>\nWhat happens when we pass in a defaultColor<\/code> that wasn’t in the original colors<\/code> array?\nIn this function, colors<\/code> is supposed to be the "source of truth" and describe what can be passed to defaultColor<\/code>.<\/p>\n\/\/ Oops! This undesirable, but is allowed!\r\ncreateStreetLight(["red", "yellow", "green"], "blue");\r\n<\/code><\/pre>\nIn this call, type inference decided that "blue"<\/code> was just as valid of a type as "red"<\/code> or "yellow"<\/code> or "green"<\/code>.\nSo instead of rejecting the call, TypeScript infers the type of C<\/code> as "red" | "yellow" | "green" | "blue"<\/code>.\nYou might say that inference just blue up in our faces!<\/p>\nOne way people currently deal with this is to add a separate type parameter that’s bounded by the existing type parameter.<\/p>\n
function createStreetLight<C extends string, D extends C>(colors: C[], defaultColor?: D) {\r\n}\r\n\r\ncreateStreetLight(["red", "yellow", "green"], "blue");\r\n\/\/ ~~~~~~\r\n\/\/ error!\r\n\/\/ Argument of type '"blue"' is not assignable to parameter of type '"red" | "yellow" | "green" | undefined'.\r\n<\/code><\/pre>\nThis works, but is a little bit awkward because D<\/code> probably won’t be used anywhere else in the signature for createStreetLight<\/code>.\nWhile not bad in this case<\/em>, using a type parameter only once in a signature is often a code smell.<\/p>\nThat’s why TypeScript 5.4 introduces a new NoInfer<T><\/code> utility type.\nSurrounding a type in NoInfer<...><\/code> gives a signal to TypeScript not to dig in and match against the inner types to find candidates for type inference.<\/p>\nUsing NoInfer<\/code>, we can rewrite createStreetLight<\/code> as something like this:<\/p>\nfunction createStreetLight<C extends string>(colors: C[], defaultColor?: NoInfer<C>) {\r\n \/\/ ...\r\n}\r\n\r\ncreateStreetLight(["red", "yellow", "green"], "blue");\r\n\/\/ ~~~~~~\r\n\/\/ error!\r\n\/\/ Argument of type '"blue"' is not assignable to parameter of type '"red" | "yellow" | "green" | undefined'.\r\n<\/code><\/pre>\nExcluding the type of defaultColor<\/code> from being explored for inference means that "blue"<\/code> never ends up as an inference candidate, and the type-checker can reject it.<\/p>\nYou can see the specific changes in the implementing pull request<\/a>, along with the initial implementation<\/a> provided thanks to Mateusz Burzy\u0144ski<\/a>!<\/p>\nObject.groupBy<\/code> and Map.groupBy<\/code><\/h2>\nTypeScript 5.4 adds declarations for JavaScript’s new Object.groupBy<\/code> and Map.groupBy<\/code> static methods.<\/p>\nObject.groupBy<\/code> takes an iterable, and a function that decides which "group" each element should be placed in.\nThe function needs to make a "key" for each distinct group, and Object.groupBy<\/code> uses that key to make an object where every key maps to an array with the original element in it.<\/p>\nSo the following JavaScript:<\/p>\n
const array = [0, 1, 2, 3, 4, 5];\r\n\r\nconst myObj = Object.groupBy(array, (num, index) => {\r\n return num % 2 === 0 ? "even": "odd";\r\n});\r\n<\/code><\/pre>\nis basically equivalent to writing this:<\/p>\n
const myObj = {\r\n even: [0, 2, 4],\r\n odd: [1, 3, 5],\r\n};\r\n<\/code><\/pre>\nMap.groupBy<\/code> is similar, but produces a Map<\/code> instead of a plain object.\nThis might be more desirable if you need the guarantees of Map<\/code>s, you’re dealing with APIs that expect Map<\/code>s, or you need to use any kind of key for grouping – not just keys that can be used as property names in JavaScript.<\/p>\nconst myObj = Map.groupBy(array, (num, index) => {\r\n return num % 2 === 0 ? "even" : "odd";\r\n});\r\n<\/code><\/pre>\nand just as before, you could have created myObj<\/code> in an equivalent way:<\/p>\nconst myObj = new Map();\r\n\r\nmyObj.set("even", [0, 2, 4]);\r\nmyObj.set("odd", [1, 3, 5]);\r\n<\/code><\/pre>\nNote that in the above example of Object.groupBy<\/code>, the object produced uses all optional properties.<\/p>\ninterface EvenOdds {\r\n even?: number[];\r\n odd?: number[];\r\n}\r\n\r\nconst myObj: EvenOdds = Object.groupBy(...);\r\n\r\nmyObj.even;\r\n\/\/ ~~~~\r\n\/\/ Error to access this under 'strictNullChecks'.\r\n<\/code><\/pre>\nThis is because there’s no way to guarantee in a general way that all<\/em> the keys were produced by groupBy<\/code>.<\/p>\nNote also that these methods are only accessible by configuring your target<\/code> to esnext<\/code> or adjusting your lib<\/code> settings.\nWe expect they will eventually be available under a stable es2024<\/code> target.<\/p>\nWe’d like to extend a thanks to Kevin Gibbons<\/a> for adding the declarations to these groupBy<\/code> methods<\/a>.<\/p>\nSupport for require()<\/code> calls in --moduleResolution bundler<\/code> and --module preserve<\/code><\/h2>\nTypeScript has a moduleResolution<\/code> option called bundler<\/code> that is meant to model the way modern bundlers figure out which file an import path refers to.\nOne of the limitations of the option is that it had to be paired with --module esnext<\/code>, making it impossible to use the import ... = require(...)<\/code> syntax.<\/p>\n\/\/ previously errored\r\nimport myModule = require("module\/path");\r\n<\/code><\/pre>\nThat might not seem like a big deal if you’re planning on just writing standard ECMAScript import<\/code>s, but there’s a difference when using a package with conditional exports<\/a>.<\/p>\nIn TypeScript 5.4, require()<\/code> can now be used when setting the module<\/code> setting to a new option called preserve<\/code>.<\/p>\nBetween --module preserve<\/code> and --moduleResolution bundler<\/code>, the two more accurately model what bundlers and runtimes like Bun will allow, and how they’ll perform module lookups.\nIn fact, when using --module preserve<\/code>, the bundler<\/code> option will be implicitly set for --moduleResolution<\/code> (along with --esModuleInterop<\/code> and --resolveJsonModule<\/code>)<\/p>\n{\r\n "compilerOptions": {\r\n "module": "preserve",\r\n \/\/ ^ also implies:\r\n \/\/ "moduleResolution": "bundler",\r\n \/\/ "esModuleInterop": true,\r\n \/\/ "resolveJsonModule": true,\r\n\r\n \/\/ ...\r\n }\r\n}\r\n<\/code><\/pre>\nUnder --module preserve<\/code>, an ECMAScript import<\/code> will always be emitted as-is, and import ... = require(...)<\/code> will be emitted as a require()<\/code> call (though in practice you may not even use TypeScript for emit, since it’s likely you’ll be using a bundler for your code).\nThis holds true regardless of the file extension of the containing file.\nSo the output of this code:<\/p>\nimport * as foo from "some-package\/foo";\r\nimport bar = require("some-package\/bar");\r\n<\/code><\/pre>\nshould look something like this:<\/p>\n
import * as foo from "some-package\/foo";\r\nvar bar = require("some-package\/bar");\r\n<\/code><\/pre>\nWhat this also means is that the syntax you choose directs how conditional exports<\/a> are matched.\nSo in the above example, if the package.json<\/code> of some-package<\/code> looks like this:<\/p>\n{\r\n "name": "some-package",\r\n "version": "0.0.1",\r\n "exports": {\r\n ".\/foo": {\r\n "import": ".\/esm\/foo-from-import.mjs",\r\n "require": ".\/cjs\/foo-from-require.cjs"\r\n },\r\n ".\/bar": {\r\n "import": ".\/esm\/bar-from-import.mjs",\r\n "require": ".\/cjs\/bar-from-require.cjs"\r\n }\r\n }\r\n}\r\n<\/code><\/pre>\nTypeScript will resolve these paths to [...]\/some-package\/esm\/foo-from-import.mjs<\/code> and [...]\/some-package\/cjs\/bar-from-require.cjs<\/code>.<\/p>\nFor more information, you can read up on these new settings here<\/a>.<\/p>\nChecked Import Attributes and Assertions<\/h2>\n
Import attributes and assertions are now checked against the global ImportAttributes<\/code> type.\nThis means that runtimes can now more accurately describe the import attributes<\/p>\n\/\/ In some global file.\r\ninterface ImportAttributes {\r\n type: "json";\r\n}\r\n\r\n\/\/ In some other module\r\nimport * as ns from "foo" with { type: "not-json" };\r\n\/\/ ~~~~~~~~~~\r\n\/\/ error!\r\n\/\/\r\n\/\/ Type '{ type: "not-json"; }' is not assignable to type 'ImportAttributes'.\r\n\/\/ Types of property 'type' are incompatible.\r\n\/\/ Type '"not-json"' is not assignable to type '"json"'.\r\n<\/code><\/pre>\nThis change<\/a> was provided thanks to Oleksandr Tarasiuk<\/a>.<\/p>\nQuick Fix for Adding Missing Parameters<\/h2>\n
TypeScript now has a quick fix to add a new parameter to functions that are called with too many arguments.<\/p>\n
![\"A](\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2024\/01\/add-missing-params-5-4-beta-before.png\")
<\/p>\n
![\"The](\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2024\/01\/add-missing-params-5-4-beta-after.png\")
<\/p>\n
This can be useful when threading a new argument through several existing functions, which can be cumbersome today.<\/p>\n
This quick fix<\/a> was provided courtsey of Oleksandr Tarasiuk<\/a>.<\/p>\nAuto-Import Support for Subpath Imports<\/h2>\n
In Node.js, package.json<\/code> supports a feature called "subpath imports" via a field called imports<\/code>s<\/a>.\nIt’s a way to re-mapping paths inside of a package to other module paths.\nConceptually, this is pretty similar to path-mapping, a featue that certain module bundlers and loaders support (and which TypeScript supports via a feature called paths<\/code>).\nThe only difference is that subpath imports always have to start with a #<\/code>.<\/p>\nTypeScript’s auto-imports feature previously did not consider paths in imports<\/code> which could be frustrating.\nInstead, users might have to manually define paths<\/code> in their tsconfig.json<\/code>.\nHowever, thanks to a contribution from Emma Hamilton<\/a>, TypeScript’s auto-imports now support subpath imports<\/a>!<\/p>\nUpcoming Changes from TypeScript 5.0 Deprecations<\/h2>\n
TypeScript 5.0 deprecated the following options and behaviors:<\/p>\n
\ncharset<\/code><\/li>\ntarget: ES3<\/code><\/li>\nimportsNotUsedAsValues<\/code><\/li>\nnoImplicitUseStrict<\/code><\/li>\nnoStrictGenericChecks<\/code><\/li>\nkeyofStringsOnly<\/code><\/li>\nsuppressExcessPropertyErrors<\/code><\/li>\nsuppressImplicitAnyIndexErrors<\/code><\/li>\nout<\/code><\/li>\npreserveValueImports<\/code><\/li>\nprepend<\/code> in project references<\/li>\n- implicitly OS-specific
newLine<\/code><\/li>\n<\/ul>\nTo continue using them, developers using TypeScript 5.0 and other more recent versions have had to specify a new option called ignoreDeprecations<\/code> with the value "5.0"<\/code>.<\/p>\nHowever, TypScript 5.4 will be the last version in which these will continue to function as normal.\nBy TypeScript 5.5 (likely June 2024), these will become hard errors, and code using them will need to be migrated away.<\/p>\n