Today we are excited to announce the availability of TypeScript 5.6 Beta.<\/p>\n
To get started using the beta, you can get it through NuGet<\/a>, or through npm with the following command:<\/p>\n Here’s a quick list of what’s new in TypeScript 5.6!<\/p>\n Maybe you’ve written a regex and forgotten to call or maybe you’ve accidentally written or maybe you’ve tried to use a default value with or maybe you’ve misplaced a parenthesis in a complex expression:<\/p>\n None of these examples do what the author intended, but they’re all valid JavaScript code.\nPreviously TypeScript also quietly accepted these examples.<\/p>\n But with a little bit of experimentation, we found that many many<\/em> bugs could be caught from flagging down suspicious examples like above.\nIn TypeScript 5.6, the compiler now errors when it can syntactically determine a truthy or nullish check will always evaluate in a specific way.\nSo in the above examples, you’ll start to see errors:<\/p>\n Similar results can be achieved by enabling the ESLint Note that certain expressions are still allowed, even if they are always truthy or nullish.\nSpecifically, is still idiomatic and useful, and code like the following:<\/p>\n is useful while iterating\/debugging code.<\/p>\n If you’re curious about the implementation or the sorts of bugs it catches, take a look at the pull request that implemented this feature<\/a>.<\/p>\n JavaScript has a notion of iterables<\/em> (things which we can iterate over by calling a For example, every generator now produces an object that also has a The same is true for methods like You can also extend the new And you can adapt any existing Now, we have to talk about naming.<\/p>\n Earlier we mentioned that TypeScript has types for But there is still a new runtime value<\/strong> called TypeScript 5.6 introduces a new type called Lots of built-in collections and methods produce this type, and both the core JavaScript and DOM types in Similarly, there is a We’d like to thank Kevin Gibbons<\/a> who contributed the changes for these types<\/a>, and who is one of the co-authors of the proposal<\/a>.<\/p>\n When you call the The naming here is inspired by the way a generator function works.\nGenerator functions can With the new It would be hard to fix this on every TypeScript 5.6 introduces a new intrinsic type called By default, For more information, you can read up on the feature here<\/a>.<\/p>\n JavaScript allows modules to export bindings with invalid identifier names as string literals:<\/p>\n Likewise, it allows modules to grab imports with these arbitrary names and bind them to valid identifiers:<\/p>\n This seems like a cute party trick (if you’re as fun as we are at parties), but it has its uses for interoperability with other languages (typically via JavaScript\/WebAssembly boundaries), since other languages may have different rules for what constitutes a valid identifier.\nIt can also be useful for tools that generate code, like esbuild with its TypeScript 5.6 now allows you to use these arbitrary module identifiers in your code!\nWe’d like to thank Evan Wallace<\/a> who contributed this change to TypeScript<\/a>!<\/p>\n In JavaScript it’s possible to These imports are often called side effect imports<\/em> because the only useful behavior they can provide is by executing some side effect (like registering a global variable, or adding a polyfill to a prototype).<\/p>\n In TypeScript, this syntax has had a pretty strange quirk: if the This is surprising behavior, but it partially stems from modeling patterns in the JavaScript ecosystem.\nFor example, this syntax has also been used with special loaders in bundlers to load CSS or other assets.\nYour bundler might be configured in such a way where you can include specific Still, this masks potential typos on side effect imports.\nThat’s why TypeScript 5.6 introduces a new compiler option called When enabling this option, some working code may now receive an error, like in the CSS example above.\nTo work around this, users who want to just write side effect In fact, you might already have a file like this in your project!\nFor example, running something like While this option is currently off by default, we encourage users to give it a try!<\/p>\nnpm install -D typescript@beta\r\n<\/code><\/pre>\n\n
--strictBuiltinIteratorReturn<\/code>)<\/a><\/li>\n--noUncheckedSideEffectImports<\/code> Option<\/a><\/li>\n--noCheck<\/code> Option<\/a><\/li>\n--build<\/code> with Intermediate Errors<\/a><\/li>\n\n
lib.d.ts<\/code><\/a><\/li>\n.tsbuildinfo<\/code> is Always Written<\/a><\/li>\npackage.json<\/code> from within node_modules<\/code><\/a><\/li>\noverride<\/code> Checks on Computed Properties<\/a><\/li>\n<\/ul>\n<\/li>\n<\/ul>\nDisallowed Nullish and Truthy Checks<\/h2>\n
.test(...)<\/code> on it:<\/p>\nif (\/0x[0-9a-f]\/) {\r\n \/\/ Oops! This block always runs.\r\n \/\/ ...\r\n}\r\n<\/code><\/pre>\n=><\/code> (which creates an arrow function) instead of >=<\/code> (the greater-than-or-equal-to operator):<\/p>\nif (x => 0) {\r\n \/\/ Oops! This block always runs.\r\n \/\/ ...\r\n}\r\n<\/code><\/pre>\n??<\/code>, but mixed up the precedence of ??<\/code> and a comparison operator like <<\/code>:<\/p>\nfunction isValid(value: string | number, options: any, strictness: "strict" | "loose") {\r\n if (strictness === "loose") {\r\n value = +value\r\n }\r\n return value < options.max ?? 100;\r\n \/\/ Oops! This is parsed as (value < options.max) ?? 100\r\n}\r\n\r\n<\/code><\/pre>\nif (\r\n isValid(primaryValue, "strict") || isValid(secondaryValue, "strict") ||\r\n isValid(primaryValue, "loose" || isValid(secondaryValue, "loose"))\r\n) {\r\n \/\/ ^^^^ \ud83d\udc40 Did we forget a closing ')'?\r\n}\r\n<\/code><\/pre>\nif (\/0x[0-9a-f]\/) {\r\n\/\/ ~~~~~~~~~~~~\r\n\/\/ error: This kind of expression is always truthy.\r\n}\r\n\r\nif (x => 0) {\r\n\/\/ ~~~~~~\r\n\/\/ error: This kind of expression is always truthy.\r\n}\r\n\r\nfunction isValid(value: string | number, options: any, strictness: "strict" | "loose") {\r\n if (strictness === "loose") {\r\n value = +value\r\n }\r\n return value < options.max ?? 100;\r\n \/\/ ~~~~~~~~~~~~~~~~~~~\r\n \/\/ error: Right operand of ?? is unreachable because the left operand is never nullish.\r\n}\r\n\r\nif (\r\n isValid(primaryValue, "strict") || isValid(secondaryValue, "strict") ||\r\n isValid(primaryValue, "loose" || isValid(secondaryValue, "loose"))\r\n) {\r\n \/\/ ~~~~~~~\r\n \/\/ error: This kind of expression is always truthy.\r\n}\r\n<\/code><\/pre>\nno-constant-binary-expression<\/code> rule, and you can see some of the results they achieved in their blog post<\/a>;\nbut the new checks TypeScript performs does not have perfect overlap with the ESLint rule, and we also believe there is a lot of value in having these checks built into TypeScript itself.<\/p>\ntrue<\/code>, false<\/code>, 0<\/code>, and 1<\/code> are all still allowed despite always being truthy or falsy, since code like the following:<\/p>\nwhile (true) {\r\n doStuff();\r\n\r\n if (something()) {\r\n break;\r\n }\r\n\r\n doOtherStuff();\r\n}\r\n<\/code><\/pre>\nif (true || inDebuggingOrDevelopmentEnvironment()) {\r\n \/\/ ...\r\n}\r\n<\/code><\/pre>\nIterator Helper Methods<\/h2>\n
[Symbol.iterator]()<\/code> and getting an iterator) and iterators<\/em> (things which have a next()<\/code> method which we can call to try to get the next value as we iterate).\nBy and large, you don’t typically have to think about these things when you toss them into a for<\/code>\/of<\/code> loop, or [...spread]<\/code> them into a new array.\nBut TypeScript does model these with the types Iterable<\/code> and Iterator<\/code> (and even IterableIterator<\/code> which acts as both!), and these types describe the minimal set of members you need for constructs like for<\/code>\/of<\/code> to work on them.<\/p>\nIterable<\/code>s (and IterableIterator<\/code>s) are nice because they can be used in all sorts of places in JavaScript – but a lot of people found themselves missing methods on Array<\/code>s like map<\/code>, filter<\/code>, and for some reason reduce<\/code>.\nThat’s why a recent proposal was brought forward in ECMAScript<\/a> to add many methods (and more) from Array<\/code> onto most of the IterableIterator<\/code>s that are produced in JavaScript.<\/p>\nmap<\/code> method and a take<\/code> method.<\/p>\nfunction* positiveIntegers() {\r\n let i = 1;\r\n while (true) {\r\n yield i;\r\n i++;\r\n }\r\n}\r\n\r\nconst evenNumbers = positiveIntegers().map(x => x * 2);\r\n\r\n\/\/ Output:\r\n\/\/ 2\r\n\/\/ 4\r\n\/\/ 6\r\n\/\/ 8\r\n\/\/ 10\r\nfor (const value of evenNumbers.take(5)) {\r\n console.log(value);\r\n}\r\n<\/code><\/pre>\nkeys()<\/code>, values()<\/code>, and entries()<\/code> on Map<\/code>s and Set<\/code>s.<\/p>\nfunction invertKeysAndValues<K, V>(map: Map<K, V>): Map<V, K> {\r\n return new Map(\r\n map.entries().map(([k, v]) => [v, k])\r\n );\r\n}\r\n<\/code><\/pre>\nIterator<\/code> object:<\/p>\n\/**\r\n * Provides an endless stream of `0`s.\r\n *\/\r\nclass Zeroes extends Iterator<number> {\r\n next() {\r\n return { value: 0, done: false } as const;\r\n }\r\n}\r\n\r\nconst zeroes = new Zeroes();\r\n\r\n\/\/ Transform into an endless stream of `1`s.\r\nconst ones = zeroes.map(x => x + 1);\r\n<\/code><\/pre>\nIterable<\/code>s or Iterator<\/code>s into this new type with Iterator.from<\/code>:<\/p>\nIterator.from(...).filter(someFunction);\r\n<\/code><\/pre>\nIterable<\/code> and Iterator<\/code>;\nhowever, like we mentioned, these act sort of like "protocols" to ensure certain operations work.\nThat means that not every value that is declared Iterable<\/code> or Iterator<\/code> in TypeScript will have those methods we mentioned above.<\/em><\/p>\nIterator<\/code>.\nYou can reference Iterator<\/code>, as well as Iterator.prototype<\/code>, as actual values in JavaScript.\nThis is a bit awkward since TypeScript already defines its own thing called Iterator<\/code> purely for type-checking.\nSo due to this unfortunate name clash, TypeScript needs to introduce a separate type to describe these native\/built-in iterable iterators.<\/p>\nBuiltinIterator<\/code>.\nIt is defined as follows:<\/p>\ninterface BuiltinIterator<T, TReturn = any, TNext = any> {\r\n \/\/ ...\r\n}\r\n<\/code><\/pre>\nlib.d.ts<\/code>, along with @types\/node<\/code>, have been updated to use this new type.<\/p>\nBuiltinAsyncIterator<\/code> type for parity.\nAsyncIterator<\/code> does not yet exist as a runtime value in JavaScript that brings the same methods for AsyncIterable<\/code>s, but it is an active proposal<\/a> and this new type prepares for it.<\/p>\nStrict Builtin Iterator Checks (and
--strictBuiltinIteratorReturn<\/code>)<\/h2>\nnext()<\/code> method on an Iterator<T, TReturn><\/code>, it returns an object with a value<\/code> and a done<\/code> property.\nThis is modeled with the type IteratorResult<\/code>.<\/p>\ntype IteratorResult<T, TReturn = any> = IteratorYieldResult<T> | IteratorReturnResult<TReturn>;\r\n\r\ninterface IteratorYieldResult<TYield> {\r\n done?: false;\r\n value: TYield;\r\n}\r\n\r\ninterface IteratorReturnResult<TReturn> {\r\n done: true;\r\n value: TReturn;\r\n}\r\n<\/code><\/pre>\nyield<\/code> values, and then return<\/code> a final value – but the types between the two can be unrelated.<\/p>\nfunction abc123() {\r\n yield "a";\r\n yield "b";\r\n yield "c";\r\n return 123;\r\n}\r\n\r\nconst iter = abc123();\r\n\r\niter.next(); \/\/ { value: "a", done: false }\r\niter.next(); \/\/ { value: "b", done: false }\r\niter.next(); \/\/ { value: "c", done: false }\r\niter.next(); \/\/ { value: 123, done: true }\r\n<\/code><\/pre>\nBuiltinIterator<\/code> type, we discovered some difficulties in allowing safe implementations of BuiltinIterator<\/code>s.\nAt the same time, there’s been a long standing unsafety with IteratorResult<\/code> in cases where TReturn<\/code> was any<\/code> (the default!).\nFor example, let’s say we have an IteratorResult<string, any><\/code>.\nIf we end up reaching for the value<\/code> of this type, we’ll end up with string | any<\/code>, which is just any<\/code>.<\/p>\nfunction* uppercase(iter: Iterator<string, any>) {\r\n while (true) {\r\n const { value, done } = iter.next();\r\n yield value.toUppercase(); \/\/ oops! forgot to check for `done` first and misspelled `toUpperCase`\r\n\r\n if (done) {\r\n return;\r\n }\r\n }\r\n}\r\n<\/code><\/pre>\nIterator<\/code> today without introducing a lot of breaks, but we can at least fix it with most BuiltinIterator<\/code>s that get created.<\/p>\nBuiltinIteratorReturn<\/code> and a new --strict<\/code>-mode flag called --strictBuiltinIteratorReturn<\/code>.\nWhenever BuiltinIterator<\/code>s are used in places like lib.d.ts<\/code>, they are always written with BuiltinIteratorReturn<\/code> type for TReturn<\/code>:<\/p>\ninterface Map<K, V> {\r\n \/\/ ...\r\n\r\n \/**\r\n * Returns an iterable of key, value pairs for every entry in the map.\r\n *\/\r\n entries(): BuiltinIterator<[K, V], BuiltinIteratorReturn>;\r\n\r\n \/**\r\n * Returns an iterable of keys in the map\r\n *\/\r\n keys(): BuiltinIterator<K, BuiltinIteratorReturn>;\r\n\r\n \/**\r\n * Returns an iterable of values in the map\r\n *\/\r\n values(): BuiltinIterator<V, BuiltinIteratorReturn>;\r\n}\r\n<\/code><\/pre>\nBuiltinIteratorReturn<\/code> is any<\/code>, but when --strictBuiltinIteratorReturn<\/code> is enabled (possibly via --strict<\/code>), it is undefined<\/code>.\nUnder this new mode, if we use BuiltinIteratorReturn<\/code>, our earlier example now correctly errors:<\/p>\nfunction* uppercase(iter: Iterator<string, BuiltinIteratorReturn>) {\r\n while (true) {\r\n const { value, done } = iter.next();\r\n yield value.toUppercase();\r\n \/\/ ~~~~~ ~~~~~~~~~~~\r\n \/\/ error! \u2503 \u2503\r\n \/\/ \u2503 \u2517\u2501 Property 'toUppercase' does not exist on type 'string'. Did you mean 'toUpperCase'?\r\n \/\/ \u2503\r\n \/\/ \u2517\u2501 'value' is possibly 'undefined'.\r\n\r\n if (done) {\r\n return;\r\n }\r\n }\r\n}\r\n<\/code><\/pre>\nSupport for Arbitrary Module Identifiers<\/h2>\n
const banana = "\ud83c\udf4c";\r\n\r\nexport { banana as "\ud83c\udf4c" };\r\n<\/code><\/pre>\nimport { "\ud83c\udf4c" as banana } from ".\/foo"\r\n\r\n\/**\r\n * om nom nom\r\n *\/\r\nfunction eat(food: string) {\r\n console.log("Eating", food);\r\n};\r\n\r\neat(banana);\r\n<\/code><\/pre>\ninject<\/code> feature<\/a>.<\/p>\nThe
--noUncheckedSideEffectImports<\/code> Option<\/h2>\nimport<\/code> a module without actually importing any values from it.<\/p>\nimport "some-module";\r\n<\/code><\/pre>\nimport<\/code> could be resolved to a valid source file, then TypeScript would load and check the file.\nOn the other hand, if no source file could be found, TypeScript would silently ignore the import<\/code>!<\/p>\n.css<\/code> files by writing something like the following:<\/p>\nimport ".\/button-component.css";\r\n\r\nexport function Button() {\r\n \/\/ ...\r\n}\r\n<\/code><\/pre>\n--noUncheckedSideEffectImports<\/code>, to catch these cases.\nWhen --noUncheckedSideEffectImports<\/code> is enabled, TypeScript will now error if it can’t find a source file for a side effect import.<\/p>\nimport "oops-this-module-does-not-exist";\r\n\/\/ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r\n\/\/ error: Cannot find module 'oops-this-module-does-not-exist' or its corresponding type declarations.\r\n<\/code><\/pre>\nimport<\/code>s for assets might be better served by writing what’s called an ambient module declaration<\/em> with a wildcard specifier.\nIt would go in a global file and look something like the following:<\/p>\n\/\/ .\/src\/globals.d.ts\r\n\r\n\/\/ Recognize all CSS files as module imports.\r\ndeclare module "*.css" {}\r\n<\/code><\/pre>\nvite init<\/code> might create a similar vite-env.d.ts<\/code>.<\/p>\n