npm install -D typescript@beta\r\n<\/code><\/pre>\nHere’s a quick list of what’s new in TypeScript 5.3!<\/p>\n
\n- Import Attributes<\/a><\/li>\n
- Stable Support
resolution-mode<\/code> in Import Types<\/a><\/li>\nswitch (true)<\/code> Narrowing<\/a><\/li>\n- Narrowing On Comparisons to Booleans<\/a><\/li>\n
instanceof<\/code> Narrowing Through Symbol.hasInstance<\/code><\/a><\/li>\n- Checks for
super<\/code> Property Accesses on Instance Fields<\/a><\/li>\n- Interactive Inlay Hints for Types<\/a><\/li>\n
- Optimizations by Skipping JSDoc Parsing<\/a><\/li>\n
- Optimizations by Comparing Non-Normalized Intersections<\/a><\/li>\n
- Consolidation Between
tsserverlibrary.js<\/code> and typescript.js<\/code><\/a><\/li>\n- Breaking Changes and Correctness Improvements<\/a><\/li>\n<\/ul>\n
Import Attributes<\/h2>\n
TypeScript 5.3 supports the latest updates to the import attributes<\/a> proposal.<\/p>\nOne use-case of import attributes is to provide information about the expected format of a module to the runtime.<\/p>\n
\/\/ We only want this to be interpreted as JSON,\r\n\/\/ not a runnable\/malicious JavaScript file with a `.json` extension.\r\nimport obj from ".\/something.json" with { type: "json" };\r\n<\/code><\/pre>\nThe contents of these attributes are not checked by TypeScript since they’re host-specific, and are simply left alone so that browsers and runtimes can handle them (and possibly error).<\/p>\n
\/\/ TypeScript is fine with this.\r\n\/\/ But your browser? Probably not.\r\nimport * as foo from ".\/foo.js" with { type: "fluffy bunny" };\r\n<\/code><\/pre>\nDynamic import()<\/code> calls can also use import attributes through a second argument.<\/p>\nconst obj = await import(".\/something.json", {\r\n with: { type: "json" }\r\n});\r\n<\/code><\/pre>\nThe expected type of that second argument is defined by a type called ImportCallOptions<\/code>, which by default just expects a property called with<\/code>.<\/p>\nNote that import attributes are an evolution of an earlier proposal called "import assertions", which were implemented in TypeScript 4.5<\/a>.\nThe most obvious difference is the use of the with<\/code> keyword over the assert<\/code> keyword.\nBut the less-visible difference is that runtimes are now free to use attributes to guide the resolution and interpretation of import paths, whereas import assertions could only assert some characteristics after loading a module.<\/p>\nOver time, TypeScript will be deprecating the old syntax for import assertions in favor of the proposed syntax for import attributes.\nExisting code using assert<\/code> should migrate towards the with<\/code> keyword.\nNew code that needs an import attribute should use with<\/code> exclusively.<\/p>\nWe’d like to thank Oleksandr Tarasiuk<\/a> for implementing this proposal<\/a>!\nAnd we’d also like to call out Wenlu Wang<\/a> for their implementation of import assertions<\/a>!<\/p>\nStable Support resolution-mode<\/code> in Import Types<\/h2>\nIn TypeScript 4.7, TypeScript added support for a resolution-mode<\/code> attribute in \/\/\/ <reference types="..." \/><\/code> to control whether a specifier should be resolved via import<\/code> or require<\/code> semantics.<\/p>\n\/\/\/ <reference types="pkg" resolution-mode="require" \/>\r\n\r\n\/\/ or\r\n\r\n\/\/\/ <reference types="pkg" resolution-mode="import" \/>\r\n<\/code><\/pre>\nA corresponding field was added to import assertions on type-only imports as well;\nhowever, it was only supported in nightly versions of TypeScript.\nThe rationale was that in spirit, import assertions<\/em> were not intended to guide module resolution.\nSo this feature was shipped experimentally in a nightly-only mode to get more feedback.<\/p>\nBut given that import attributes<\/a><\/em> can guide resolution, and that we’ve seen reasonable use-cases, TypeScript 5.3 now supports the resolution-mode<\/code> attribute for import type<\/code>.<\/p>\n\/\/ Resolve `pkg` as if we were importing with a `require()`\r\nimport type { TypeFromRequire } from "pkg" with {\r\n "resolution-mode": "require"\r\n};\r\n\r\n\/\/ Resolve `pkg` as if we were importing with an `import`\r\nimport type { TypeFromImport } from "pkg" with {\r\n "resolution-mode": "import"\r\n};\r\n\r\nexport interface MergedType extends TypeFromRequire, TypeFromImport {}\r\n<\/code><\/pre>\nThese import attributes can also be used on import()<\/code> types.<\/p>\nexport type TypeFromRequire =\r\n import("pkg", { with: { "resolution-mode": "require" } }).TypeFromRequire;\r\n\r\nexport type TypeFromImport =\r\n import("pkg", { with: { "resolution-mode": "import" } }).TypeFromImport;\r\n\r\nexport interface MergedType extends TypeFromRequire, TypeFromImport {}\r\n<\/code><\/pre>\nFor more information, check out the change here<\/a><\/p>\nswitch (true)<\/code> Narrowing<\/h2>\nTypeScript 5.3 now can perform narrowing based on conditions in each case<\/code> clause within a switch (true)<\/code>.<\/p>\nfunction f(x: unknown) {\r\n switch (true) {\r\n case typeof x === "string":\r\n \/\/ 'x' is a 'string' here\r\n console.log(x.toUpperCase());\r\n \/\/ falls through...\r\n\r\n case Array.isArray(x):\r\n \/\/ 'x' is a 'string | any[]' here.\r\n console.log(x.length);\r\n \/\/ falls through...\r\n\r\n default:\r\n \/\/ 'x' is 'unknown' here.\r\n \/\/ ...\r\n }\r\n}\r\n<\/code><\/pre>\nThis work<\/a> was contributed courtesy of Mateusz Burzy\u0144ski<\/a>.\nWe’d like to extend a "thank you!" for this contribution.<\/p>\nNarrowing On Comparisons to Booleans<\/h2>\n
Occasionally you may find yourself performing a direct comparison with true<\/code> or false<\/code> in a condition.\nUsually these are unnecessary comparisons, but you might prefer it as a point of style, or to avoid certain issues around JavaScript truthiness.\nRegardless, previously TypeScript just didn’t recognize such forms when performing narrowing.<\/p>\nTypeScript 5.3 now keeps up and understands these expressions when narrowing variables.<\/p>\n
interface A {\r\n a: string;\r\n}\r\n\r\ninterface B {\r\n b: string;\r\n}\r\n\r\ntype MyType = A | B;\r\n\r\nfunction isA(x: MyType): x is A {\r\n return "a" in x;\r\n}\r\n\r\nfunction someFn(x: MyType) {\r\n if (isA(x) === true) {\r\n console.log(x.a); \/\/ works!\r\n }\r\n}\r\n<\/code><\/pre>\nWe’d like to thank Mateusz Burzy\u0144ski<\/a> for the pull request<\/a> that implemented this.<\/p>\ninstanceof<\/code> Narrowing Through Symbol.hasInstance<\/code><\/h2>\nA slightly esoteric feature of JavaScript is that it is possible to override the behavior of the instanceof<\/code> operator.\nTo do so, the value on the right side of the instanceof<\/code> operator needs to have a specific method named by Symbol.hasInstance<\/code>.<\/p>\nclass Weirdo {\r\n static [Symbol.hasInstance](testedValue) {\r\n \/\/ wait, what?\r\n return testedValue === undefined;\r\n }\r\n}\r\n\r\n\/\/ false\r\nconsole.log(new Thing() instanceof Weirdo);\r\n\r\n\/\/ true\r\nconsole.log(undefined instanceof Weirdo);\r\n<\/code><\/pre>\nTo better model this behavior in instanceof<\/code>, TypeScript now checks if such a [Symbol.hasInstance]<\/code> method exists and is declared as a type predicate function.\nIf it does, the tested value on the left side of the instanceof<\/code> operator will be narrowed appropriately by that type predicate.<\/p>\ninterface PointLike {\r\n x: number;\r\n y: number;\r\n}\r\n\r\nclass Point implements PointLike {\r\n x: number;\r\n y: number;\r\n\r\n constructor(x: number, y: number) {\r\n this.x = x;\r\n this.y = y;\r\n }\r\n\r\n distanceFromOrigin() {\r\n return Math.sqrt(this.x ** 2 + this.y ** 2);\r\n }\r\n\r\n static [Symbol.hasInstance](val: unknown): val is PointLike {\r\n return !!val && typeof val === "object" &&\r\n "x" in val && "y" in val &&\r\n typeof val.x === "number" &&\r\n typeof val.y === "number";\r\n }\r\n}\r\n\r\n\r\nfunction f(value: unknown) {\r\n if (value instanceof Point) {\r\n \/\/ Can access both of these - correct!\r\n value.x;\r\n value.y;\r\n\r\n \/\/ Can't access this - we have a 'PointLike',\r\n \/\/ but we don't *actually* have a 'Point'.\r\n value.distanceFromOrigin();\r\n }\r\n}\r\n<\/code><\/pre>\nAs you can see in this example, Point<\/code> defines its own [Symbol.hasInstance]<\/code> method.\nIt actually acts as a custom type guard over a separate type called PointLike<\/code>.\nIn the function f<\/code>, we were able to narrow value<\/code> down to a PointLike<\/code> with instanceof<\/code>, but not<\/em> a Point<\/code>.\nThat means that we can access the properties x<\/code> and y<\/code>, but not the method distanceFromOrigin<\/code>.<\/p>\nFor more information, you can read up on this change here<\/a>.<\/p>\nChecks for super<\/code> Property Accesses on Instance Fields<\/h2>\nIn JavaScript, it’s possible to access a declaration in a base class through the super<\/code> keyword.<\/p>\nclass Base {\r\n someMethod() {\r\n console.log("Base method called!");\r\n }\r\n}\r\n\r\nclass Derived extends Base {\r\n someMethod() {\r\n console.log("Derived method called!");\r\n super.someMethod();\r\n }\r\n}\r\n\r\nnew Derived().someMethod();\r\n\/\/ Prints:\r\n\/\/ Derived method called!\r\n\/\/ Base method called!\r\n<\/code><\/pre>\nThis is different from writing something like this.someMethod()<\/code>, since that could invoke an overridden method.\nThis is a subtle distinction, made more subtle by the fact that often the two can be interchangeable if a declaration is never overridden at all.<\/p>\nclass Base {\r\n someMethod() {\r\n console.log("someMethod called!");\r\n }\r\n}\r\n\r\nclass Derived extends Base {\r\n someOtherMethod() {\r\n \/\/ These act identically.\r\n this.someMethod();\r\n super.someMethod();\r\n }\r\n}\r\n\r\nnew Derived().someOtherMethod();\r\n\/\/ Prints:\r\n\/\/ someMethod called!\r\n\/\/ someMethod called!\r\n<\/code><\/pre>\nThe problem is using them interchangeably is that super<\/code> only works on members declared on the prototype \u2014 not<\/em> instance properties.\nThat means that if you wrote super.someMethod()<\/code>, but someMethod<\/code> was defined as a field, you’d get a runtime error!<\/p>\nclass Base {\r\n someMethod = () => {\r\n console.log("someMethod called!");\r\n }\r\n}\r\n\r\nclass Derived extends Base {\r\n someOtherMethod() {\r\n super.someMethod();\r\n }\r\n}\r\n\r\nnew Derived().someOtherMethod();\r\n\/\/ \ud83d\udca5\r\n\/\/ Doesn't work because 'super.someMethod' is 'undefined'.\r\n<\/code><\/pre>\nTypeScript 5.3 now more-closely inspects super<\/code> property accesses\/method calls to see if they correspond to class fields.\nIf they do, we’ll now get a type-checking error.<\/p>\nThis check<\/a> was contributed thanks to Jack Works<\/a>!<\/p>\nInteractive Inlay Hints for Types<\/h2>\n
TypeScript’s inlay hints now support jumping to the definition of types!\nThis makes it easier to casually navigate your code.<\/p>\n
![\"Ctrl-clicking](\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2023\/10\/clickable-inlay-hints-for-types-5-3-beta.gif\")
<\/p>\n
See more at the implementation here<\/a>.<\/p>\n<\/p>\n
Optimizations by Skipping JSDoc Parsing<\/h2>\n
When running TypeScript via tsc<\/code>, the compiler will now avoid parsing JSDoc.\nThis drops parsing time on its own, but also reduces memory usage to store comments along with time spent in garbage collection.\nAll-in-all, you should see slightly faster compiles and quicker feedback in --watch<\/code> mode.<\/p>\nThe specific changes can be viewed here<\/a>.<\/p>\nBecause not every tool using TypeScript will need to store JSDoc (e.g. typescript-eslint and Prettier), this parsing strategy has been surfaced as part of the API itself.\nThis can enable these tools to gain the same memory and speed improvements we’ve brought to the TypeScript compiler.\nThe new options for comment parsing strategy are described in JSDocParsingMode<\/code>.\nMore information is available on this pull request<\/a>.<\/p>\nOptimizations by Comparing Non-Normalized Intersections<\/h2>\n
In TypeScript, unions and intersections always follow a specific form, where intersections can’t contain union types.\nThat means that when we create an intersection over a union like A & (B | C)<\/code>, that intersection will be normalized into (A & B) | (A & C)<\/code>.\nStill, in some cases the type system will maintain the original form for display purposes.<\/p>\nIt turns out that the original form can be used for some clever fast-path comparisons between types.<\/p>\n
For example, let’s say we have SomeType & (Type1 | Type2 | ... | Type99999NINE)<\/code> and we want to see if that’s assignable to SomeType<\/code>.\nRecall that we don’t really have an intersection as our source type \u2014 we have a union that looks like (SomeType & Type1) | (SomeType & Type2) | ... |(SomeType & Type99999NINE)<\/code>.\nWhen checking if a union is assignable to some target type, we have to check if every<\/em> member of the union is assignable to the target type, and that can be very slow.<\/p>\nIn TypeScript 5.3, we peek at the original intersection form that we were able to tuck away.\nWhen we compare the types, we do a quick check to see if the target exists in any constituent of the source intersection.<\/p>\n
For more information, see this pull request<\/a>.<\/p>\nConsolidation Between tsserverlibrary.js<\/code> and typescript.js<\/code><\/h2>\nTypeScript itself ships two library files: tsserverlibrary.js<\/code> and typescript.js<\/code>.\nThere are certain APIs available only in tsserverlibrary.js<\/code> (like the ProjectService<\/code> API), which may be useful to some importers.\nStill, the two are distinct bundles with have a lot of overlap, duplicating code in the package.\nWhat’s more, it can be challenging to consistently use one over the other due to auto-imports or muscle memory.\nAccidentally loading both modules is far too easy, and code may not work properly on a different instance of the API.\nEven if it does work, loading a second bundle increases resource usage.<\/p>\nGiven this, we’ve decided to consolidate the two.\ntypescript.js<\/code> now contains what tsserverlibrary.js<\/code> used to contain, and tsserverlibrary.js<\/code> now simply re-exports typescript.js<\/code>.\nComparing the before\/after of this consolidation, we saw the following reduction in package size:<\/p>\n