{"id":4607,"date":"2025-01-29T10:51:38","date_gmt":"2025-01-29T18:51:38","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/typescript\/?p=4607"},"modified":"2025-01-29T13:35:58","modified_gmt":"2025-01-29T21:35:58","slug":"announcing-typescript-5-8-beta","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/typescript\/announcing-typescript-5-8-beta\/","title":{"rendered":"Announcing TypeScript 5.8 Beta"},"content":{"rendered":"

Today we are excited to announce the availability of TypeScript 5.8 Beta.<\/p>\n

To get started using the beta, you can get it through npm with the following command:<\/p>\n

npm install -D typescript@beta\r\n<\/code><\/pre>\n
Let’s take a look at what’s new in TypeScript 5.8!<\/p>\n
Checked Returns for Conditional and Indexed Access Types<\/h2>\n
Consider an API that presents a set of options to a user:<\/p>\n
\/**\r\n * @param prompt The text to show to a user.\r\n * @param selectionKind Whether a user can select multiple options, or just a single option.\r\n * @param items Each of the options presented to the user.\r\n **\/\r\nasync function showQuickPick(\r\n    prompt: string,\r\n    selectionKind: SelectionKind,\r\n    items: readonly string[],\r\n): Promise<string | string[]> {\r\n    \/\/ ...\r\n}\r\n\r\nenum SelectionKind {\r\n    Single,\r\n    Multiple,\r\n}\r\n<\/code><\/pre>\n
The intent with showQuickPick<\/code> is that it shows a UI element that can allow selecting either a single option or multiple options.\nWhen it does this is determined by the selectionKind<\/code> parameter.\nWhen selectionKind<\/code> is SelectionKind.Single<\/code>, the return type of showQuickPick<\/code> should be string<\/code>, and when it is SelectionKind.Multiple<\/code>, the return type should be string[]<\/code>.<\/p>\n
The problem is that the type signature of showQuickPick<\/code> doesn’t make this clear.\nIt just says that it eventually returns string | string[]<\/code> – it could be a string<\/code> and it could be a string[]<\/code>, but callers have to explicitly check.\nIn our example below, we might expect shoppingList<\/code> to have the type string[]<\/code>, but we end up with the more broad string | string[]<\/code>.<\/p>\n
let shoppingList = await showQuickPick(\r\n    "Which fruits do you want to purchase?",\r\n    SelectionKind.Multiple,\r\n    ["apples", "oranges", "bananas", "durian"],\r\n);\r\n\r\nconsole.log(`Alright, going out to buy some ${shoppingList.join(", ")}`);\r\n\/\/                                                         ~~~~\r\n\/\/ error!\r\n\/\/ Property 'join' does not exist on type 'string | string[]'.\r\n\/\/  Property 'join' does not exist on type 'string'.\r\n<\/code><\/pre>\n
Instead, we can use a conditional type to make the return type of showQuickPick<\/code> more precise:<\/p>\n
type QuickPickReturn<S extends SelectionKind> =\r\n    S extends SelectionKind.Multiple ? string[] : string\r\n\r\nasync function showQuickPick<S extends SelectionKind>(\r\n    prompt: string,\r\n    selectionKind: S,\r\n    items: readonly string[],\r\n): Promise<QuickPickReturn<S>> {\r\n    \/\/ ...\r\n}\r\n<\/code><\/pre>\n
This works well for callers!<\/p>\n
\/\/ `SelectionKind.Multiple` gives a `string[]` - works \u2705\r\nlet shoppingList: string[] = await showQuickPick(\r\n    "Which fruits do you want to purchase?",\r\n    SelectionKind.Multiple,\r\n    ["apples", "oranges", "bananas", "durian"],\r\n);\r\n\r\n\/\/ `SelectionKind.Single` gives a `string` - works \u2705\r\nlet dinner: string = await showQuickPick(\r\n    "What's for dinner tonight?",\r\n    SelectionKind.Single,\r\n    ["sushi", "pasta", "tacos", "ugh I'm too hungry to think, whatever you want"],\r\n);\r\n<\/code><\/pre>\n
But what if we try to actually implement showQuickPick<\/code>?<\/p>\n
async function showQuickPick<S extends SelectionKind>(\r\n    prompt: string,\r\n    selectionKind: S,\r\n    items: readonly string[],\r\n): Promise<QuickPickReturn<S>> {\r\n    if (items.length < 1) {\r\n        throw new Error("At least one item must be provided.");\r\n    }\r\n    \r\n    \/\/ Create buttons for every option.\r\n    let buttons = items.map(item => ({\r\n        selected: false,\r\n        text: item,\r\n    }));\r\n\r\n    \/\/ Default to the first element if necessary.\r\n    if (selectionKind === SelectionKind.Single) {\r\n        buttons[0].selected = true;\r\n    }\r\n\r\n    \/\/ Event handling code goes here...\r\n\r\n    \/\/ Figure out the selected items\r\n    const selectedItems = buttons\r\n        .filter(button => button.selected)\r\n        .map(button => button.text);\r\n\r\n    if (selectionKind === SelectionKind.Single) {\r\n        \/\/ Pick the first (only) selected item.\r\n        return selectedItems[0];\r\n    }\r\n    else {\r\n        \/\/ Return all selected items.\r\n        return selectedItems;\r\n    }\r\n}\r\n<\/code><\/pre>\n
Unfortunately, TypeScript issues an error on each of the return statements.<\/p>\n
Type 'string[]' is not assignable to type 'QuickPickReturn<S>'.\r\nType 'string' is not assignable to type 'QuickPickReturn<S>'.\r\n<\/code><\/pre>\n
Until this point, TypeScript required a type assertion to implement any function returning a higher-order conditional type.<\/p>\n
      if (selectionKind === SelectionKind.Single) {\r\n          \/\/ Pick the first (only) selected item.\r\n-         return selectedItems[0];\r\n+         return selectedItems[0] as QuickPickReturn<S>;\r\n      }\r\n      else {\r\n          \/\/ Return all selected items.\r\n-         return selectedItems;\r\n+         return selectedItems as QuickPickReturn<S>;\r\n      }\r\n<\/code><\/pre>\n
This is not ideal because type assertions defeat legitimate checks that TypeScript would otherwise perform.\nFor example, it would be ideal if TypeScript could catch the following bug where we mixed up each branch of the if<\/code>\/else<\/code>:<\/p>\n
    if (selectionKind === SelectionKind.Single) {\r\n        \/\/ Oops! Returning an array when the caller expects a single item!\r\n        return selectedItems;\r\n    }\r\n    else {\r\n        \/\/ Oops! Returning a single item when the caller expects an array! \r\n        return selectedItems[0];\r\n    }\r\n<\/code><\/pre>\n
To avoid type assertions, TypeScript 5.8 now supports a limited form of checking against conditional types in return statements.\nWhen a function’s return type is a generic conditional type, TypeScript will now use control flow analysis for generic parameters whose types are used in the conditional type, instantiate the conditional type with the narrowed type of each parameter, and relate against that new type.<\/p>\n
What does this mean in practice?\nWell first, let’s look into what kinds of conditional types imply narrowing.\nTo mirror how narrowing operates in expressions, we have to be more explicit and exhaustive about what happens in each branch<\/p>\n
type QuickPickReturn<S extends SelectionKind> =\r\n    S extends SelectionKind.Multiple ? string[] :\r\n    S extends SelectionKind.Single ? string :\r\n    never;\r\n<\/code><\/pre>\n
Once we’ve done this, everything in our example works.\nOur callers have no issue, and our implementation is now type-safe!\nAnd if we try swapping the contents of our if<\/code> branches, TypeScript correctly flags it as an error!<\/p>\n
    if (selectionKind === SelectionKind.Single) {\r\n        \/\/ Oops! Returning an array when the caller expects a single item!\r\n        return selectedItems;\r\n    \/\/  ~~~~~~\r\n    \/\/ error! Type 'string[]' is not assignable to type 'string'.\r\n    }\r\n    else {\r\n        \/\/ Oops! Returning a single item when the caller expects an array! \r\n        return selectedItems[0];\r\n    \/\/  ~~~~~~\r\n    \/\/ error! Type 'string[]' is not assignable to type 'string'.\r\n}\r\n<\/code><\/pre>\n
Note that TypeScript now also does something similar if we’re using indexed access types!
\nInstead of a conditional type, we can use a type that basically acts as a map from SelectionKind<\/code> to the return type we want:<\/p>\n
interface QuickPickReturn {\r\n    [SelectionKind.Single]: string;\r\n    [SelectionKind.Multiple]: string[];\r\n}\r\n\r\nasync function showQuickPick<S extends SelectionKind>(\r\n    prompt: string,\r\n    selectionKind: S,\r\n    items: readonly string[],\r\n): Promise<QuickPickReturn[S]> {\r\n    \/\/ ...\r\n}\r\n<\/code><\/pre>\n
For many users, this will be a more ergonomic way to write the same code.<\/p>\n
For more information about this analysis, see the proposal and implementation here<\/a>!<\/p>\n
A Note on Limitations<\/h3>\n
There are some limitations to this feature.\nThis special checking only kicks in when a single parameter is associated with the type being checked against in a conditional type or used as a key in an indexed access type.\nIf using a conditional type, at least two checks must exist, with a terminal branch including never<\/code>.\nThat parameter’s type must be generic and have a union type as its constraint.\nIn other words, the code analysis kicks in for a pattern like the following:<\/p>\n
function f<T extends A | B>(x: T):\r\n    T extends A ? string :\r\n    T extends B ? number :\r\n    never\r\n<\/code><\/pre>\n
This means these checks will not occur when a specific property is associated with a type parameter.\nFor example, if we rewrote our code above to use an options bag instead of individual parameters, TypeScript would not<\/em> apply this new checking.<\/p>\n
interface QuickPickOptions<S> {\r\n    prompt: string,\r\n    selectionKind: S,\r\n    items: readonly string[]\r\n}\r\n\r\nasync function showQuickPick<S extends SelectionKind>(\r\n    options: QuickPickOptions<S>\r\n): Promise<QuickPickReturn<S>> {\r\n    \/\/ narrowing won't work correctly here...\r\n}\r\n<\/code><\/pre>\n
But workarounds may exist by writing a conditional type that checks against the inner contents.<\/p>\n
type QuickPickReturn<O extends QuickPickOptionsBase> =\r\n    O extends QuickPickOptionsMultiple ? string[] :\r\n    O extends QuickPickOptionsSingle ? string :\r\n    never;\r\n\r\ninterface QuickPickOptionsBase {\r\n    prompt: string,\r\n    items: readonly string[]\r\n}\r\ninterface QuickPickOptionsSingle extends QuickPickOptionsBase {\r\n    selectionKind: SelectionKind.Single;\r\n}\r\ninterface QuickPickOptionsMultiple extends QuickPickOptionsBase {\r\n    selectionKind: SelectionKind.Multiple;\r\n}\r\n\r\nasync function showQuickPick<Opts extends QuickPickOptionsSingle | QuickPickOptionsMultiple>(\r\n    options: Opts\r\n): Promise<QuickPickReturn<Opts>>\r\n<\/code><\/pre>\n
These rules may seem like quite a lot to remember, but in practice, most code will not need to leverage these higher-order types.\nAdditionally, while we prefer implementations use this new checking mechanism over type assertions, we do encourage users to keep their APIs simple when possible in the interest of keeping the types written simpler as well.\nIn the meantime, we will continue to explore ways to relax some of these limitations while making the code easy to author.<\/p>\n
Support for require()<\/code> of ECMAScript Modules in --module nodenext<\/code><\/h2>\n
For years, Node.js supported ECMAScript modules (ESM) alongside CommonJS modules.\nUnfortunately, the interoperability between the two had some challenges.<\/p>\n