Array.forEach incorrectly narrows the inferred type when elements are annotated with union type

[shogunsea]

Bug Report

🔎 Search Terms

Array.forEach
union type

🕗 Version & Regression Information

all versions

• This is the behavior in every version I tried, and I reviewed the FAQ for entries about array and foreach

⏯ Playground Link

Playground link with relevant **code**

💻 Code

interface FooValue {
  value: string;
}

interface BarValue {
  value: string;
  name: string;
}

interface Props {
  values: BarValue[] | FooValue[];
}

export function foo({ values }: Props) {
  return values.forEach((value) => value);
}

🙁 Actual behavior

The inferred type of value is simply FooValue:

🙂 Expected behavior

But really it should be FooValue | BarValue, which is correct when using .map:

I suspect this issue happens because forEach isn't annotated with generic return type U while map is:

TypeScript/src/lib/es5.d.ts

Lines 1235 to 1246 in 250065e

	/**
	* Performs the specified action for each element in an array.
	* @param callbackfn A function that accepts up to three arguments. forEach calls the callbackfn function one time for each element in the array.
	* @param thisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
	*/
	forEach(callbackfn: (value: T, index: number, array: readonly T[]) => void, thisArg?: any): void;
	/**
	* Calls a defined callback function on each element of an array, and returns an array that contains the results.
	* @param callbackfn A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.
	* @param thisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
	*/
	map<U>(callbackfn: (value: T, index: number, array: readonly T[]) => U, thisArg?: any): U[];

In fact after changing forEach to forEach<U> fixes this problem locally:

[MartinJohns]

Subtype reduction, working as intended.

[jcalz]

Essentially a duplicate of #46449 and many others: if A extends B then TS will sometimes reduce A | B to B. This is working as intended. In a perfectly sound type system such types A | B and B would be identical and the reduction from the former to the latter would have no observable effect. Unfortunately TS doesn't have a perfectly sound type system, so the operation is indeed observable and sometimes produces surprising or undesired results for users. But it's not considered a bug.

[fatcerberus]

In a perfectly sound type system such types A | B and B would be identical and the reduction from the former to the latter would have no observable effect.

Essentially a restatement of #53425 (comment), fwiw
(and in case that isn't clear: objects are allowed to have extra properties, so writing FooValue | BarValue doesn't add any additional constraints on which values are allowed compared to just FooValue by itself).

[shogunsea]

@jcalz @fatcerberus thanks for the explanation, but why this is not an issue with .map? I'd expect .map and .forEach behave identically except the return value (per the language spec).

But it's not considered a bug

I agree in general based on typescript not being "a perfectly sound system", however this did feel like a bug in our use case: we were using https://typescript-eslint.io/ to lint the data usage based on the type information, and when a piece of data was transformed with Array#forEach it produced wrong result due to this sub type reduction behavior.

[typescript-bot]

This issue has been marked as "Not a Defect" and has seen no recent activity. It has been automatically closed for house-keeping purposes.