Was this page helpful?

TypeScript 5.4

ts
functionuppercaseStrings(x:string |number) {
if (typeofx ==="string") {
// TypeScript knows 'x' is a 'string' here.
returnx.toUpperCase();
    }
}

ts
functiongetUrls(url:string |URL,names:string[]) {
if (typeofurl ==="string") {
url =newURL(url);
    }
returnnames.map(name=> {
url.searchParams.set("name",name)
//  ~~~~~~~~~~~~
// error!
// Property 'searchParams' does not exist on type 'string | URL'.
returnurl.toString();
    });
}

ts
functionprintValueLater(value:string |undefined) {
if (value ===undefined) {
value ="missing!";
    }
setTimeout(()=> {
// Modifying 'value', even in a way that shouldn't affect
// its type, will invalidate type refinements in closures.
value =value;
    },500);
setTimeout(()=> {
console.log(value.toUpperCase());
//          ~~~~~
// error! 'value' is possibly 'undefined'.
    },1000);
}

ts
functiondoSomething<T>(arg:T) {
// ...
}
// We can explicitly say that 'T' should be 'string'.
doSomething<string>("hello!");
// We can also just let the type of 'T' get inferred.
doSomething("hello!");

ts
functioncreateStreetLight<Cextendsstring>(colors:C[],defaultColor?:C) {
// ...
}
createStreetLight(["red","yellow","green"],"red");

ts
// Oops! This is undesirable, but is allowed!
createStreetLight(["red","yellow","green"],"blue");

ts
functioncreateStreetLight<Cextendsstring,DextendsC>(colors:C[],defaultColor?:D) {
}
createStreetLight(["red","yellow","green"],"blue");
//                                            ~~~~~~
// error!
// Argument of type '"blue"' is not assignable to parameter of type '"red" | "yellow" | "green" | undefined'.

ts
functioncreateStreetLight<Cextendsstring>(colors:C[],defaultColor?:NoInfer<C>) {
// ...
}
createStreetLight(["red","yellow","green"],"blue");
//                                            ~~~~~~
// error!
// Argument of type '"blue"' is not assignable to parameter of type '"red" | "yellow" | "green" | undefined'.

is basically equivalent to writing this:

js
constmyObj = {
even: [0,2,4],
odd: [1,3,5],
};

Map.groupBy is similar, but produces aMap instead of a plain object.This might be more desirable if you need the guarantees ofMaps, you’re dealing with APIs that expectMaps, or you need to use any kind of key for grouping - not just keys that can be used as property names in JavaScript.

js
constmyObj =Map.groupBy(array, (num,index)=> {
returnnum %2 ===0 ?"even" :"odd";
});

and just as before, you could have createdmyObj in an equivalent way:

js
constmyObj =newMap();
myObj.set("even", [0,2,4]);
myObj.set("odd", [1,3,5]);

Note that in the above example ofObject.groupBy, the object produced uses all optional properties.

ts
interfaceEvenOdds {
even?:number[];
odd?:number[];
}
constmyObj:EvenOdds =Object.groupBy(...);
myObj.even;
//    ~~~~
// Error to access this under 'strictNullChecks'.

This is because there’s no way to guarantee in a general way thatall the keys were produced bygroupBy.

Note also that these methods are only accessible by configuring yourtarget toesnext or adjusting yourlib settings.We expect they will eventually be available under a stablees2024 target.

We’d like to extend a thanks toKevin Gibbons foradding the declarations to thesegroupBy methods.

Support forrequire() calls in--moduleResolution bundler and--module preserve

TypeScript has amoduleResolution option calledbundler that is meant to model the way modern bundlers figure out which file an import path refers to.One of the limitations of the option is that it had to be paired with--module esnext, making it impossible to use theimport ... = require(...) syntax.

ts
// previously errored
importmyModule =require("module/path");

That might not seem like a big deal if you’re planning on just writing standard ECMAScriptimports, but there’s a difference when using a package withconditional exports.

In TypeScript 5.4,require() can now be used when setting themodule setting to a new option calledpreserve.

Between--module preserve and--moduleResolution bundler, the two more accurately model what bundlers and runtimes like Bun will allow, and how they’ll perform module lookups.In fact, when using--module preserve, thebundler option will be implicitly set for--moduleResolution (along with--esModuleInterop and--resolveJsonModule)

json
{
"compilerOptions": {
"module":"preserve",
// ^ also implies:
// "moduleResolution": "bundler",
// "esModuleInterop": true,
// "resolveJsonModule": true,
// ...
    }
}

Under--module preserve, an ECMAScriptimport will always be emitted as-is, andimport ... = require(...) will be emitted as arequire() 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).This holds true regardless of the file extension of the containing file.So the output of this code:

ts
import*asfoofrom"some-package/foo";
importbar =require("some-package/bar");

should look something like this:

js
import*asfoofrom"some-package/foo";
varbar =require("some-package/bar");

What this also means is that the syntax you choose directs howconditional exports are matched.So in the above example, if thepackage.json ofsome-package looks like this:

json
{
"name":"some-package",
"version":"0.0.1",
"exports": {
"./foo": {
"import":"./esm/foo-from-import.mjs",
"require":"./cjs/foo-from-require.cjs"
    },
"./bar": {
"import":"./esm/bar-from-import.mjs",
"require":"./cjs/bar-from-require.cjs"
    }
  }
}

TypeScript will resolve these paths to[...]/some-package/esm/foo-from-import.mjs and[...]/some-package/cjs/bar-from-require.cjs.

For more information, you canread up on these new settings here.

Checked Import Attributes and Assertions

Import attributes and assertions are now checked against the globalImportAttributes type.This means that runtimes can now more accurately describe the import attributes

ts
// In some global file.
interfaceImportAttributes {
type:"json";
}
// In some other module
import*asnsfrom"foo"with {type: "not-json" };
//                                     ~~~~~~~~~~
// error!
//
// Type '{ type: "not-json"; }' is not assignable to type 'ImportAttributes'.
//  Types of property 'type' are incompatible.
//    Type '"not-json"' is not assignable to type '"json"'.

This change was provided thanks toOleksandr Tarasiuk.

Quick Fix for Adding Missing Parameters

TypeScript now has a quick fix to add a new parameter to functions that are called with too many arguments.

This can be useful when threading a new argument through several existing functions, which can be cumbersome today.

This quick fix was provided courtsey ofOleksandr Tarasiuk.

Upcoming Changes from TypeScript 5.0 Deprecations

TypeScript 5.0 deprecated the following options and behaviors:

• charset
• target: ES3
• importsNotUsedAsValues
• noImplicitUseStrict
• noStrictGenericChecks
• keyofStringsOnly
• suppressExcessPropertyErrors
• suppressImplicitAnyIndexErrors
• out
• preserveValueImports
• prepend in project references
• implicitly OS-specificnewLine

To continue using them, developers using TypeScript 5.0 and other more recent versions have had to specify a new option calledignoreDeprecations with the value"5.0".

However, TypScript 5.4 will be the last version in which these will continue to function as normal.By TypeScript 5.5 (likely June 2024), these will become hard errors, and code using them will need to be migrated away.

For more information, you canread up on this plan on GitHub, which contains suggestions in how to best adapt your codebase.

Notable Behavioral Changes

This section highlights a set of noteworthy changes that should be acknowledged and understood as part of any upgrade.Sometimes it will highlight deprecations, removals, and new restrictions.It can also contain bug fixes that are functionally improvements, but which can also affect an existing build by introducing new errors.

lib.d.ts Changes

Types generated for the DOM may have an impact on type-checking your codebase.For more information,see the DOM updates for TypeScript 5.4.

More Accurate Conditional Type Constraints

The following code no longer allows the second variable declaration in the functionfoo.

ts
typeIsArray<T> =Textendsany[] ?true :false;
functionfoo<Uextendsobject>(x:IsArray<U>) {
letfirst:true =x;// Error
letsecond:false =x;// Error, but previously wasn't
}

Previously, when TypeScript checked the initializer forsecond, it needed to determine whetherIsArray<U> was assignable to the unit typefalse.WhileIsArray<U> isn’t compatible any obvious way, TypeScript looks at theconstraint of that type as well.In a conditional type likeT extends Foo ? TrueBranch : FalseBranch, whereT is generic, the type system would look at the constraint ofT, substitute it in forT itself, and decide on either the true or false branch.

But this behavior was inaccurate because it was overly eager.Even if the constraint ofT isn’t assignable toFoo, that doesn’t mean that it won’t be instantiated with something that is.And so the more correct behavior is to produce a union type for the constraint of the conditional type in cases where it can’t be proven thatTnever oralways extendsFoo.

TypeScript 5.4 adopts this more accurate behavior.What this means in practice is that you may begin to find that some conditional type instances are no longer compatible with their branches.

You can read about the specific changes here.

More Aggressive Reduction of Intersections Between Type Variables and Primitive Types

TypeScript now reduces intersections with type variables and primitives more aggressively, depending on how the type variable’s constraint overlaps with those primitives.

ts
declarefunctionintersect<T,U>(x:T,y:U):T &U;
functionfoo<Textends"abc" |"def">(x:T,str:string,num:number) {
// Was 'T & string', now is just 'T'
leta =intersect(x,str);
// Was 'T & number', now is just 'never'
letb =intersect(x,num)
// Was '(T & "abc") | (T & "def")', now is just 'T'
letc =Math.random() <0.5 ?
intersect(x,"abc") :
intersect(x,"def");
}

For more information,see the change here.

Improved Checking Against Template Strings with Interpolations

TypeScript now more accurately checks whether or not strings are assignable to the placeholder slots of a template string type.

ts
functiona<Textends {id:string}>() {
letx:`-${keyofT&string}`;
// Used to error, now doesn't.
x ="-id";
}

This behavior is more desirable, but may cause breaks in code using constructs like conditional types, where these rule changes are easy to witness.

See this change for more details.

Errors When Type-Only Imports Conflict with Local Values

Previously, TypeScript would permit the following code underisolatedModules if the import toSomething only referred to a type.

ts
import {Something }from"./some/path";
letSomething =123;

However, it’s not safe for single-file compilers to assume whether it’s “safe” to drop theimport, even if the code is guaranteed to fail at runtime.In TypeScript 5.4, this code will trigger an error like the following:

Import 'Something' conflicts with local value, so must be declared with a type-only import when 'isolatedModules' is enabled.

The fix should be to either make a local rename, or, as the error states, add thetype modifier to the import:

ts
importtype {Something }from"./some/path";
// or
import {typeSomething }from"./some/path";

See more information on the change itself.

New Enum Assignability Restrictions

When two enums have the same declared names and enum member names, they were previously always considered compatible;however, when the values were known, TypeScript would silently allow them to have differing values.

TypeScript 5.4 tightens this restriction by requiring the values to be identical when they are known.

ts
namespaceFirst {
exportenumSomeEnum {
A =0,
B =1,
    }
}
namespaceSecond {
exportenumSomeEnum {
A =0,
B =2,
    }
}
functionfoo(x:First.SomeEnum,y:Second.SomeEnum) {
// Both used to be compatible - no longer the case,
// TypeScript errors with something like:
//
//  Each declaration of 'SomeEnum.B' differs in its value, where '1' was expected but '2' was given.
x =y;
y =x;
}

Additionally, there are new restrictions for when one of the enum members does not have a statically known value.In these cases, the other enum must at least be implicitly numeric (e.g. it has no statically resolved initializer), or it is explicitly numeric (meaning TypeScript could resolve the value to something numeric).Practically speaking, what this means is that string enum members are only ever compatible with other string enums of the same value.

ts
namespaceFirst {
exportdeclareenumSomeEnum {
A,
B,
    }
}
namespaceSecond {
exportdeclareenumSomeEnum {
A,
B ="some known string",
    }
}
functionfoo(x:First.SomeEnum,y:Second.SomeEnum) {
// Both used to be compatible - no longer the case,
// TypeScript errors with something like:
//
//  One value of 'SomeEnum.B' is the string '"some known string"', and the other is assumed to be an unknown numeric value.
x =y;
y =x;
}

For more information,see the pull request that introduced this change.

Name Restrictions on Enum Members

TypeScript no longer allows enum members to use the namesInfinity,-Infinity, orNaN.

ts
// Errors on all of these:
//
//  An enum member cannot have a numeric name.
enumE {
Infinity =0,
"-Infinity" =1,
NaN =2,
}

See more details here.

Better Mapped Type Preservation Over Tuples withany Rest Elements

Previously, applying a mapped type withany into a tuple would create anany element type.This is undesirable and is now fixed.

ts
Promise.all(["", ...([]asany)])
    .then((result)=> {
consthead =result[0];// 5.3: any, 5.4: string
consttail =result.slice(1);// 5.3 any, 5.4: any[]
    });

For more information, seethe fix along withthe follow-on discussion around behavioral changes andfurther tweaks.

Emit Changes

While not a breaking change per se, developers may have implicitly taken dependencies on TypeScript’s JavaScript or declaration emit outputs.The following are notable changes.

• Preserve type parameter names more often when shadowed
• Move complex parameter lists of async function into downlevel generator body
• Do not remove binding alias in function declarations
• ImportAttributes should go through the same emit phases when in an ImportTypeNode