Today we’re announcing our beta release of TypeScript 4.9!<\/p>\n
To get started using the beta, 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 Here’s a quick list of what’s new in TypeScript 4.9!<\/p>\n TypeScript developers are often faced with a dilemma: we want to ensure that some expression matches<\/em> some type, but also want to keep the most specific<\/em> type of that expression for inference purposes.<\/p>\n For example:<\/p>\n Notice that we’ve written The new Maybe we don’t care about if the property names match up somehow, but we do care about the types of each property.\nIn that case, we can also ensure that all of an object’s property values conform to some type.<\/p>\n For more examples, you can see the issue proposing this<\/a> and the implementing pull request<\/a>.\nWe’d like to thank Oleksandr Tarasiuk<\/a> who implemented and iterated on this feature with us.<\/p>\n As developers, we often need to deal with values that aren’t fully known at runtime.\nIn fact, we often don’t know if properties exist, whether we’re getting a response from a server or reading a configuration file.\nJavaScript’s Previously, TypeScript allowed us to narrow away any types that don’t explicitly list a property.<\/p>\n Here, the type But what about examples where no type listed a given property?\nIn those cases, the language didn’t help us much.\nLet’s take the following example in JavaScript:<\/p>\n Rewriting this to canonical TypeScript would just be a matter of defining and using a type for This is because while the type of TypeScript 4.9 makes the So in our example, TypeScript 4.9 also tightens up a few checks around how For more information, read the implementing pull request<\/a><\/p>\n A major gotcha for JavaScript developers is checking against the value For some background, But at least symmetrically everything<\/em> is always not-equal to This technically isn’t a JavaScript-specific problem, since any language that contains IEEE-754 floats has the same behavior;\nbut JavaScript’s primary numeric type is a floating point number, and number parsing in JavaScript can often result in TypeScript now errors on direct comparisons against We believe that this change should strictly help catch beginner errors, similar to how TypeScript currently issues errors on comparisons against object and array literals.<\/p>\n We’d like to extend our thanks to Oleksandr Tarasiuk<\/a> who contributed this check<\/a>.<\/p>\n In earlier versions, TypeScript leaned heavily on polling<\/em> for watching individual files.\nUsing a polling strategy meant checking the state of a file periodically for updates.\nOn Node.js, Generally speaking, a better approach is to use file system events.\nInstead of polling, we can announce that we’re interested in updates of specific files and provide a callback for when those files actually do<\/em> change.\nMost modern platforms in use provide facilities and APIs like As a result, our default was to pick the lowest common denominator: polling.\nNot always, but most of the time.<\/p>\n Over time, we’ve provided the means to choose other file-watching strategies<\/a>.\nThis allowed us to get feedback and harden our file-watching implementation against most of these platform-specific gotchas.\nAs TypeScript has needed to scale to larger codebases, and has improved in this area, we felt swapping to file system events as the default would be a worthwhile investment.<\/p>\n In TypeScript 4.9, file watching is powered by file system events by default, only falling back to polling if we fail to set up event-based watchers.\nFor most developers, this should provide a much less resource-intensive experience when running in The way file-watching works can still be configured<\/a> through environment variables and You can read up more on this change on GitHub<\/a>.<\/p>\n While TypeScript strives to avoid major breaks, even small changes in the built-in libraries can cause issues.\nWe don’t expect major breaks as a result of DOM and When TypeScript first supported type-checking and compilation for JavaScript, it accidentally supported a feature called import elision.\nIn short, if an import is not used as a value, or the compiler can detect that the import doesn’t refer to a value at runtime, the compiler will drop the import during emit.<\/p>\n This behavior was questionable, especially the detection of whether the import doesn’t refer to a value, since it means that TypeScript has to trust sometimes-inaccurate declaration files.\nIn turn, TypeScript now preserves imports in JavaScript files.<\/p>\n More information is available at the implementing change<\/a>.<\/p>\n Previously, TypeScript incorrectly prioritized the For more information, see this pull request<\/a>.<\/p>\n As part of an optimization on substitution types, For more details, read more on the original pull request<\/a>.<\/p>\n Over the next few weeks, we’ll be continuing development on TypeScript 4.9, eventually shipping a release candidate and then a final release.\nThat work will primarily include bug fixes, polish, and low-risk editor-oriented features.\nSo while the TypeScript beta represents a mostly-feature-complete point of the release cycle, the best way to get an idea of the state of TypeScript 4.9 is to try a nightly build<\/a>!<\/p>\nnpm install -D typescript@beta\r\n<\/code><\/pre>\n\n
\n
satisfies<\/code> Operator<\/a><\/li>\nin<\/code> Operator<\/a><\/li>\nNaN<\/code><\/a><\/li>\n<\/a> The
satisfies<\/code> Operator<\/h2>\n\/\/ Each property can be a string or an RGB tuple.\r\nconst palette = {\r\n red: [255, 0, 0],\r\n green: "#00ff00",\r\n bleu: [0, 0, 255]\r\n\/\/ ^^^^ sacr\u00e9 bleu - we've made a typo!\r\n};\r\n\r\n\/\/ We want to be able to use array methods on 'red'...\r\nconst redComponent = palette.red.at(0);\r\n\r\n\/\/ or string methods on 'green'...\r\nconst greenNormalized = palette.green.toUpperCase();\r\n<\/code><\/pre>\nbleu<\/code>, whereas we probably should have written blue<\/code>.\nWe could try to catch that bleu<\/code> typo by using a type annotation on palette<\/code>, but we’d lose the information about each property.<\/p>\ntype Colors = "red" | "green" | "blue";\r\n\r\ntype RGB = [red: number, green: number, blue: number];\r\n\r\nconst palette: Record<Colors, string | RGB> = {\r\n red: [255, 0, 0],\r\n green: "#00ff00",\r\n bleu: [0, 0, 255]\r\n\/\/ ~~~~ The typo is now correctly detected\r\n};\r\n\r\n\/\/ But we now have an undesirable error here - 'palette.red' "could" be a string.\r\nconst redComponent = palette.red.at(0);\r\n<\/code><\/pre>\nsatisfies<\/code> operator lets us validate that the type of an expression matches some type, without changing the resulting type of that expression.\nAs an example, we could use satisfies<\/code> to validate that all the properties of palette<\/code> are compatible with string | number[]<\/code>:<\/p>\ntype Colors = "red" | "green" | "blue";\r\n\r\ntype RGB = [red: number, green: number, blue: number];\r\n\r\nconst palette = {\r\n red: [255, 0, 0],\r\n green: "#00ff00",\r\n bleu: [0, 0, 255]\r\n\/\/ ~~~~ The typo is now caught!\r\n} satisfies Record<Colors, string | RGB>;\r\n\r\n\/\/ Both of these methods are still accessible!\r\nconst redComponent = palette.red.at(0);\r\nconst greenNormalized = palette.green.toUpperCase();\r\n<\/code><\/pre>\nsatisfies<\/code> can be used to catch lots of possible errors.\nFor example, we could ensure that an object has all<\/em> the keys of some type, but no more:<\/p>\ntype Colors = "red" | "green" | "blue";\r\n\r\n\/\/ Ensure that we have exactly the keys from 'Colors'.\r\nconst favoriteColors = {\r\n "red": "yes",\r\n "green": false,\r\n "blue": "kinda",\r\n "platypus": false\r\n\/\/ ~~~~~~~~~~ error - "platypus" was never listed in 'Colors'.\r\n} satisfies Record<Colors, unknown>;\r\n\r\n\/\/ All the information about the 'red', 'green', and 'blue' properties are retained.\r\nconst g: boolean = favoriteColors.green;\r\n<\/code><\/pre>\ntype RGB = [red: number, green: number, blue: number];\r\n\r\nconst palette = {\r\n red: [255, 0, 0],\r\n green: "#00ff00",\r\n blue: [0, 0]\r\n \/\/ ~~~~~~ error!\r\n} satisfies Record<string, string | RGB>;\r\n\r\n\/\/ Information about each property is still maintained.\r\nconst redComponent = palette.red.at(0);\r\nconst greenNormalized = palette.green.toUpperCase();\r\n<\/code><\/pre>\n<\/a> Unlisted Property Narrowing with the
in<\/code> Operator<\/h2>\nin<\/code> operator can check whether a property\nexists on an object.<\/p>\ninterface RGB {\r\n red: number;\r\n green: number;\r\n blue: number;\r\n}\r\n\r\ninterface HSV {\r\n hue: number;\r\n saturation: number;\r\n value: number;\r\n}\r\n\r\nfunction setColor(color: RGB | HSV) {\r\n if ("hue" in color) {\r\n \/\/ 'color' now has the type HSV\r\n }\r\n \/\/ ...\r\n}\r\n<\/code><\/pre>\nRGB<\/code> didn’t list the hue<\/code> and got narrowed away, and leaving us with the type HSV<\/code>.<\/p>\nfunction tryGetPackageName(context) {\r\n const packageJSON = context.packageJSON;\r\n \/\/ Check to see if we have an object.\r\n if (packageJSON && typeof packageJSON === "object") {\r\n \/\/ Check to see if it has a string name property.\r\n if ("name" in packageJSON && typeof packageJSON.name === "string") {\r\n return packageJSON.name;\r\n }\r\n }\r\n\r\n return undefined;\r\n}\r\n<\/code><\/pre>\ncontext<\/code>;\nhowever, picking a safe type like unknown<\/code> for the packageJSON<\/code> property would cause issues in older versions of TypeScript.<\/p>\ninterface Context {\r\n packageJSON: unknown;\r\n}\r\n\r\nfunction tryGetPackageName(context: Context) {\r\n const packageJSON = context.packageJSON;\r\n \/\/ Check to see if we have an object.\r\n if (packageJSON && typeof packageJSON === "object") {\r\n \/\/ Check to see if it has a string name property.\r\n if ("name" in packageJSON && typeof packageJSON.name === "string") {\r\n \/\/ ~~~~\r\n \/\/ error! Property 'name' does not exist on type 'object.\r\n return packageJSON.name;\r\n \/\/ ~~~~\r\n \/\/ error! Property 'name' does not exist on type 'object.\r\n }\r\n }\r\n\r\n return undefined;\r\n}\r\n<\/code><\/pre>\npackageJSON<\/code> was narrowed from unknown<\/code> to object<\/code>, the in<\/code> operator strictly narrowed to types that actually defined the property being checked.\nAs a result, the type of packageJSON<\/code> remained object<\/code>.<\/p>\nin<\/code> operator a little bit more powerful when narrowing types that don’t<\/em> list the property at all.\nInstead of leaving them as-is, the language will intersect their types with Record<"property-key-being-checked", unknown><\/code>.<\/p>\npackageJSON<\/code> will have its type narrowed from unknown<\/code> to object<\/code> to object & Record<"name", unknown><\/code>\nThat allows us to access packageJSON.name<\/code> directly and narrow that independently.<\/p>\ninterface Context {\r\n packageJSON: unknown;\r\n}\r\n\r\nfunction tryGetPackageName(context: Context): string | undefined {\r\n const packageJSON = context.packageJSON;\r\n \/\/ Check to see if we have an object.\r\n if (packageJSON && typeof packageJSON === "object") {\r\n \/\/ Check to see if it has a string name property.\r\n if ("name" in packageJSON && typeof packageJSON.name === "string") {\r\n \/\/ Just works!\r\n return packageJSON.name;\r\n }\r\n }\r\n\r\n return undefined;\r\n}\r\n<\/code><\/pre>\nin<\/code> is used, ensuring that the left side is assignable to the type string | number | symbol<\/code>, and the right side is assignable to object<\/code>.\nThis helps check that we’re using valid property keys, and not accidentally checking primitives.<\/p>\n<\/a> Checks For Equality on
NaN<\/code><\/h2>\nNaN<\/code> using the built-in equality operators.<\/p>\nNaN<\/code> is a special numeric value that stands for "Not a Number".\nNothing is ever equal to NaN<\/code> – even NaN<\/code>!<\/p>\nconsole.log(NaN == 0) \/\/ false\r\nconsole.log(NaN === 0) \/\/ false\r\n\r\nconsole.log(NaN == NaN) \/\/ false\r\nconsole.log(NaN === NaN) \/\/ false\r\n<\/code><\/pre>\nNaN<\/code>.<\/p>\nconsole.log(NaN != 0) \/\/ true\r\nconsole.log(NaN !== 0) \/\/ true\r\n\r\nconsole.log(NaN != NaN) \/\/ true\r\nconsole.log(NaN !== NaN) \/\/ true\r\n<\/code><\/pre>\nNaN<\/code>.\nIn turn, checking against NaN<\/code> ends up being fairly common, and the correct way to do so is to use Number.isNaN<\/code><\/a> – but<\/em> as we mentioned, lots of people accidentally end up checking with someValue === NaN<\/code> instead.<\/p>\nNaN<\/code>, and will suggest using some variation of Number.isNaN<\/code> instead.<\/p>\nfunction validate(someValue: number) {\r\n return someValue !== NaN;\r\n \/\/ ~~~~~~~~~~~~~~~~~\r\n \/\/ error: This condition will always return 'true'.\r\n \/\/ Did you mean '!Number.isNaN(someValue)'?\r\n}\r\n<\/code><\/pre>\n<\/a> File-Watching Now Uses File System Events<\/h2>\n
fs.watchFile<\/code><\/a> is the built-in way to get a polling file-watcher.\nWhile polling tends to be more predictable across platforms and file systems, it means that your CPU has to periodically get interrupted and check for updates to the file, even when nothing’s changed.\nFor a few dozen files, this might not be noticeable;\nbut on a bigger project with lots of files – or lots of files in node_modules<\/code> – this can become a resource hog.<\/p>\nCreateIoCompletionPort<\/code>, kqueue<\/code>, epoll<\/code>, and inotify<\/code>.\nNode.js mostly abstracts these away by providing fs.watch<\/code><\/a>.\nFile system events usually work great, but there are lots of caveats<\/a> to using them, and in turn, to using the fs.watch<\/code> API.\nA watcher needs to be careful to consider inode watching<\/a>, unavailability on certain file systems<\/a> (e.g.networked file systems), whether recursive file watching is available, whether directory renames trigger events, and even file watcher exhaustion!\nIn other words, it’s not quite a free lunch, especially if you’re looking for something cross-platform.<\/p>\n--watch<\/code> mode, or running with a TypeScript-powered editor like Visual Studio or VS Code.<\/p>\nwatchOptions<\/code> – and some editors like VS Code can support watchOptions<\/code> independently<\/a>.\nDevelopers using more exotic set-ups where source code resides on a networked file systems (like NFS and SMB) may need to opt back into the older behavior; though if a server has reasonable processing power, it might just be better to enable SSH and run TypeScript remotely so that it has direct local file access.\nVS Code has plenty of remote extensions<\/a> to make this easier.<\/p>\n<\/a> Correctness Fixes and Breaking Changes<\/h2>\n
lib.d.ts<\/code> Updates<\/h3>\nlib.d.ts<\/code> updates, but there may be some small ones.<\/p>\nBetter Types for
Promise.resolve<\/code><\/h3>\nPromise.resolve<\/code> now uses the Awaited<\/code> type to unwrap Promise-like types passed to it.\nThis means that it more often returns the right Promise<\/code> type, but that improved type can break existing code if it was expecting any<\/code> or unknown<\/code> instead of a Promise<\/code>.\nFor more information, see the original change<\/a>.<\/p>\nJavaScript Emit No Longer Elides Imports<\/h3>\n
\/\/ Input:\r\nimport { someValue, SomeClass } from "some-module";\r\n\r\n\/** @type {SomeClass} *\/\r\nlet val = someValue;\r\n\r\n\/\/ Previous Output:\r\nimport { someValue } from "some-module";\r\n\r\n\/** @type {SomeClass} *\/\r\nlet val = someValue;\r\n\r\n\/\/ Current Output:\r\nimport { someValue, SomeClass } from "some-module";\r\n\r\n\/** @type {SomeClass} *\/\r\nlet val = someValue;\r\n<\/code><\/pre>\nexports<\/code> is Prioritized Over typesVersions<\/code><\/h3>\ntypesVersions<\/code> field over the exports<\/code> field when resolving through a package.json<\/code> under --moduleResolution node16<\/code>.\nIf this change impacts your library, you may need to add types@<\/code> version selectors in your package.json<\/code>‘s exports<\/code> field.<\/p>\n {\r\n "type": "module",\r\n "main": ".\/dist\/main.js"\r\n "typesVersions": {\r\n "<4.8": { ".": ["4.8-types\/main.d.ts"] },\r\n "*": { ".": ["modern-types\/main.d.ts"] }\r\n },\r\n "exports": {\r\n ".": {\r\n+ "types@<4.8": "4.8-types\/main.d.ts",\r\n+ "types": "modern-types\/main.d.ts",\r\n "import": ".\/dist\/main.js"\r\n }\r\n }\r\n }\r\n<\/code><\/pre>\nsubstitute<\/code> Replaced With constraint<\/code> on SubstitutionType<\/code>s<\/h2>\nSubstitutionType<\/code> objects no longer contain the substitute<\/code> property representing the effective substitution (usually an intersection of the base type and the implicit constraint) – instead, they just contain the constraint<\/code> property.<\/p>\nWhat’s Next<\/h2>\n