Generics extending unions cannot be narrowed

TypeScript Version: 2.2.0-dev.20170126

Code

declare function takeA(val: 'A'): void;
export function bounceAndTakeIfA<AB extends 'A' | 'B'>(value: AB): AB {
    if (value === 'A') {
        takeA(value);
        return value;
    }
    else {
        return value;
    }
}

Expected behavior:
Compiles without error.

Actual behavior:

Argument of type 'AB' is not assignable to parameter of type '"A"'.

It works correctly if I just use value: 'A' | 'B' as the argument to bounceAndTakeIfA, but since I want the return value to type-match the input, I need to use the generic (overloading could do it, but overloading is brittle and error-prone, since there is no error-checking that the overload signatures are actually correct; my team has banned them for that reason). But (I'm guessing) since AB extends 'A' | 'B', narrowing doesn't happen. In reality, I am just using extends to mean AB ⊂ 'A' | 'B', but extends can mean more than that, which (I suspect) is why TS is refusing to narrow on it.

Some alternative to extends that more specifically means ⊂ (subsets maybe?) would probably be the best solution here?

But extends already does mean subset. If I'm not mistaken, extends is simply TypeScript's implementation of bounded quantification.

Regarding:

but extends can mean more than that

Do you have a specific example of behavior where you'd do T extends U for some T not assignable to U?

Got the same (I think) problem with a more elaborated example:

interface WithNumber {
  foo: number;
}

interface WithString {
  bar: string;
}

type MyType = WithNumber | WithString;

interface Parameter<C extends MyType = MyType> {
  container: C
} 

function isParameterWithNumberContainer(arg: Parameter): arg is Parameter<WithNumber> {
  return typeof (arg.container as WithNumber).foo === "number";
}

function test(arg: Parameter<WithNumber | WithString>) {
  if (isParameterWithNumberContainer(arg)) {
    arg.container.foo;
    return;
  }
  /*
   * Error:
   *   Property 'bar' does not exist on type 'MyType'.
   *     Property 'bar' does not exist on type 'WithNumber'.
   */
  arg.container.bar;
}

In my opinion, it is impossible that arg will be something else than a Parameter<WithString>. Typescript however still thinks that it is a Parameter<WithNumber | WithString> and thus throws an error when trying to access arg.container.bar.

TL;DR from design discussion: It's somewhat obvious what the "right" thing to do is, but would require a large rework of how we treat type parameters, with concordant negative perf impacts, without a corresponding large positive impact on the actual user-facing behavior side.

If new patterns emerge that make this more frequently problematic, we can take another look.

Again appeared in #25039

How should I write such code then?

type NumberType = (() => number) | number;

function double<T extends NumberType>(
    num: T
) : T {
    if (typeof num === "number") return num * 2;
    return () => num() * 2;
}```

Error `Type 'number' is not assignable to type 'T'.`

By using return num * 2 as T; and return () => num() * 2 as T;, unfortunately. There is no better way, because while TS will narrow num it won’t narrow T for you.

tsc version: 3.2.2

I have encountered this problem. It's much odd because it says "'a' does not exist" even if it's inside of if ("a" in t) block.

// Definition
type A = { a: number }
type B = { b: number }
type AorB = A | B

// Try
function f<T extends AorB>(ab: AorB, t: T): void {
    if ("a" in ab) {
        ab.a
    }
    if ("a" in t) {
        t.a // ⚠️ `a` does not exist
    }
}

Playground

same issue, different example:

interface AllowedMapTypings {
    'str': string;
    'lon': number;
}

const obj: AllowedMapTypings = {
    'str': 'foo',
    'lon': 123
};

function foo<T extends keyof AllowedMapTypings>(key: T): AllowedMapTypings[T] {
    return obj[key];
}
let str = foo('str'); // this works fine, str is a string

function fn<T extends keyof AllowedMapTypings>(key: string, kind: T, value: AllowedMapTypings[T]) {
    if (kind === 'str') {
        console.log(value.length); // Property 'length' does not exist on type 'AllowedMapTypings[T]'.
    }
}

This would be great for specializing Props to React components. Contrived example:

type Type = 'a' | 'b';
type AShape = { a: 'a' };
type BShape = { b: 'b' };
type Props<T extends Type> = {
  type: T,
  shape: T extends 'a' ? AShape : BShape,
};

class Test<T extends ID> extends React.Component<Props<T>> {
  render() {
    const { type, shape } = this.props;
    switch (type) {
      case 'a':
        return <>{shape.a}</>; // Ideally would narrow `shape` here, instead of `AShape | BShape`
      default:
        return <>{shape.b}</>;
    }
  }
}

<T type="a" shape={{ a: 'a' }} /> // No error in ideal case
<T type="a" shape={{ b: 'b' }} /> // error in ideal case

Here is an example that demonstrates the difference in behaviour between non-generic and generic functions:

type Common = { id: number };
type A = { tag: 'A' } & Common;
type B = { tag: 'B' } & Common & { foo: number };

type MyUnion = A | B;

const fn = (value: MyUnion) => {
    value.foo; // error, good!
    if ('foo' in value) {
        value.foo; // no error, good!
    }
    if (value.tag === 'B') {
        value.foo; // no error, good!
    }
};

const fn2 = <T extends MyUnion>(value: T) => {
    value.foo; // error, good!
    if ('foo' in value) {
        value.foo; // error, bad!
    }
    if (value.tag === 'B') {
        value.foo; // error, bad!
    }
};

I think this is the same issue, this came from a real use case but I've reduced it to a toy example to better demonstrate:

interface Foo {
  stringVal: string;
  stringArrayVal: string[];
  numberArrayVal: number[];
}

type KeysWithType<T, V> = { [K in keyof T]: T[K] extends V ? K : never }[keyof T];

type ArrayPropertyOf<T> = KeysWithType<T, Array<any>>;

type ArrayTypeOfPropertyOf<T, K extends keyof T> = T[K] extends Array<infer U> ? U : never;



/// type checks

const obj: Foo = {
  stringVal: 'hello',
  stringArrayVal: ['world'],
  numberArrayVal: [1,2,3]
}

let a: ArrayTypeOfPropertyOf<Foo, 'numberArrayVal'>; // as expected, type narrowed to number.

function printArrayKeyWorking(key: ArrayPropertyOf<Foo>) {

  switch (key) {
    case 'stringArrayVal':
    case 'numberArrayVal':
    case 'stringVal': // as expected: Type '"stringVal"' is not comparable to type '"numberArrayVal" | "stringArrayVal"'.
      console.log(key);
  }    

}

function printArrayKeyNotWorking<K extends ArrayPropertyOf<Foo>>(key: K) {

  switch (key) {
    case 'stringArrayVal':
    case 'numberArrayVal':
    case 'stringVal': // no error
      console.log(key);
  }    

}

function transformChildArrayValue<K extends ArrayPropertyOf<Foo>>(key: K, value: ArrayTypeOfPropertyOf<Foo, K>) {

  switch (key) {
    case 'stringArrayVal':
      return value.repeat(2); // not expected: Type '"stringVal"' is not comparable to type '"numberArrayVal" | "stringArrayVal"'.
    case 'numberArrayVal':
      return value ** 2; // not expected: The left-hand side of an arithmetic operation must be of type 'any', 'number', 'bigint' or an enum type.
    case 'stringVal':
      return key;
  }

}

Is there actually a workaround existing for this? The real case I'm having is the same kind of problem as the last function where I am unable to correctly type the key name and value as the two parameters as the type cannot be correctly narrowed. Note this is part of a library that I want to enforce good types for the downstream developer so I'm looking for generic solution not one specific to this particular problem

Any tips for a workaround greatly appreciated!

Another simple example of a problem. With generic extending a union type, automatic type guards don't work. See code in the playground.

function fn1<T extends "a" | "b" | "c">(t: T) {
  if (t === "a") {
    if (t === "b") {
      // Unreachable, error not highlited
    }
  }
}

function fn2(t: "a" | "b" | "c") {
  if (t === "a") {
    if (t === "b") {
      // Unreachable, error highlited
    }
  }
}

Another example. Code

function add(a: string | number, b: number) {
  if (typeof a === "string") {
    return `${a}${b}`
  }
  return a + b // ✔
}

function add2<T extends string | number>(a: T, b: number) {
  if (typeof a === "string") {
    return `${a}${b}`
  }
  return a + b // ⚠ Operator '+' cannot be applied to types 'T' and 'number'
}

Same issue here but user defined type: Code

// Type definitions

enum CarType {
    sedan = 'sedan',
    suv = 'suv',
    truck = 'truck'
}

type CarSedan = {
    type: CarType.sedan;
    randomKey1?: string;
}

type CarSUV = {
    type: CarType.suv;
    randomKey2?: number;
}

type CarTruck = {
    type: CarType.truck;
    randomKey3?: string;
}

//. Type guard using the key "type" to differentiate the union types

const isCarTruck = <
    Truck extends CarTruck,
    Others extends CarSedan | CarSUV,
    All extends Truck | Others
>(
    car: All
): car is Exclude<All, Others> =>
    (car as CarTruck)?.type === CarType.truck;


// Subset
type Union = CarTruck | CarSedan | CarSUV


// Example 1: In a normal usage its working

const func1 = (car: Union) => {
    isCarTruck(car)
        ?
        car // CarTruck
        :
        car // CarSedan | CarSUV
}

// Example 2: With generic extends it doesnt work

const func = <T extends Union>(car: T) => {
    isCarTruck(car)
        ?
        car // "Exclude<T, CarSedan | CarSUV>"" ----> CarTruck
        :
        car; // "T extends Union" ----> ?????
}

Can confirm generic union type guards aren't working

Playground link

type Types = "1" | "2" | "3"

type XYZ<T extends Types> = {
  type: T;
  x: T extends "1"
    ? number
    : T extends "2"
    ? string
    : T extends "3"
    ? boolean
    : never;
};

function y<T extends Types>(x: XYZ<T>) {
  if(x.type === '1') {
    x.x + 1 // fails because it's number or string or boolean
  }
}

From the look of this thread, the issue is NOT really resolved at this point, and we cannot narrow dependent types?

A very high proportion of comments here are misunderstanding a fundamental aspect of how union-constrained generics work.

It is not safe to write code like this

function f<T extends number | string>(x: T, y: T): string {
    if (typeof x === "string") {
        return y; // <- No!
    }
    return "ok";
}

because a caller can legally write

f<number | string>("hello", 42);

Narrowing one variable of a type parameter's type does not give you sound information about another variable of the same type parameter's type.

Ryan Cavanaugh (@RyanCavanaugh)

Ryan Cavanaugh (@RyanCavanaugh) Gotcha, thanks for that explanation! I can see how that's unsafe.

What about this example?

const Actions = {
	Action1: 'Action1',
	Action2: 'Action2',
} as const;
type Action = ValueOf<typeof Actions>;

// Some dynamic parameters
type ParamConstraints = {
	[Actions.Action1]: { name: string, age: number },
	[Actions.Action2]: { company: string }
};

function doSomething<TAction extends Action>(action: TAction, param: ParamConstraints[TAction]) {
	if(action === 'Action1') {
		param.name // Property 'name' does not exist on type '{ name: string; age: number; } | { company: string; }'.
	}
	
	if(action === 'Action2') {
		param.company // same error
	}

	switch(action) {
		case 'Action1':
			param.name // same error
			break;
		case 'Action2':
			param.company // same error
			break;
	}
}

// Expected error about the wrong structure for the 2nd argument
doSomething('Action1', { company: 'test' })

This seems to enforce the contract for callers (ie. I must call doSomething() with the correct arguments as dictated by ParamConstraints) . Shouldn't this be safe for narrowing inside of doSomething()?

Or is this something entirely different?

This seems to enforce the contract for callers

No

// Sound upcast
const p = 'Action1' as 'Action1' | 'Action2';
// Correct call causes unsoundness in function body
doSomething(p, { company: 'test' });

Thank you for the response!

To me that looks like self-sabotage by intentionally casting to something not intended? I'm not sure if I would consider that a case that needs defending against for that example, but I'm very likely wrong 😅

I guess this spawns 2 questions for you:

Is this sort of narrowing even possible/supported in TS?
If it is. Is there further constraint that I need to make this safe? Or how can this be done? (Does it have a name?)

This is the work-around I'm using. The key function in the following is the asUnion function, and its example use in discriminateExample. Explanation below.

type Types = {
  'Num': number
  'Str': string
}
type Names = keyof Types // 'Num' | 'Str'
type Inner<T extends Names> = Types[T]

interface Box<T extends Names> {
  type: T
  value: Inner<T>
}

// Example of generic operation on Box
function unboxExample<T extends Names>(box: Box<T>): Inner<T> {
  // `box.value` is correctly inferred with type `Inner<T>`
  return box.value
}

function asUnion<T extends Names>(box: Box<T>): T extends any ? Box<T> : never {
  return box as any
}

function discriminateExample<T extends Names>(box: Box<T>) {
  const { type, value } = asUnion(box);
  switch (type) {
    case 'Num': return value + 1; // `value` narrowed to `number`
    case 'Str': return value + ' text'; // `value` narrowed to `string`
  }
}

For my use case, I have a generic Box<T> container, where T is a type name (Num or Str in the example, to keep things simple).

I have some operations on boxes that I want to implement generically -- unboxExample is an example. And I have some operations on boxes where I want to discriminate on the different types of boxes and implement each case individually -- discriminateExample is an example. The issue, as raised in this thread, is that it's hard to do both kinds of operations on the same types: if Box<T> is a union then generic operations require casting, and if Box<T> is not a union then you can't discriminate on the individual possibilities.

The solution here is the asUnion function, which internally does a cast from the generic form to the union form, but at least the cast is only in one place. The return type of asUnion uses a conditional type to expand out the discriminated union based on all the possible type names T.

For example, if the argument of asUnion is Box<'Num' | 'Str'> then the return type is Box<'Num'> | Box<'Str'>, which is then compatible with TypeScript's narrowing logic.

The fix seems very incomplete to me. A simple re-assignment of the narrowed variable will break it:

type Type = 'a' | 'b';

let testVariable: 'a'

function testTypeNarrowing<T extends 'a' | 'b'>(t: T): 'a' | null {
  if (t === 'a') {
    // this assignment works, making you believe t has been correctly narrowed
    testVariable = t
    // t has not actually been narrowed here
    const x = t
    return x  //compilation error, but returning t itself woudl work!
  }
  return null
}

This of course causes all sorts of related problems. In light of this, shouldn't this issue be reopened for having a main source of reference on these kind of issues?

This also doesn't work with narrowing conditional types (tested with both enums and unions in TS 5.5):

function getConcreteEnumImpl<TEnum extends MyEnum>(myEnum: TEnum): SpecializedTypeOfEnum<TEnum> {
  switch (myEnum) {
    case MyEnum.bar: {
      return new BarEnumSpecialization(); <-- Typing error because TS does not narrow `TEnum` to `bar`
    }
    case MyEnum.foo: {
      return new FooEnumSpecialization();
    }
    default: throw new Error();
  }
}

Full TS playground link

was also surprised to find out typescript won't infer a more specific type for a generic index access:

    persist<K extends keyof Action>(proj: Project, action: K, data: Action[K]) {
      let result: Project;
      if (action === "ARM") {

inside the if clause above, data is still Action[K] instead of Action["ARM"]

Marcos Pereira (@marcospgp)

Marcos Pereira (@marcospgp) The problem is that you’re expecting K to be one and only exactly one, known, keyof Action. That isn’t necessarily true. Consider persist<"ARM" | "x86"> (either written that way, or because someone has a variable typed as "ARM" | "x86"): Because K is "ARM" | "x86", data can be Action["ARM" | "x86"], which is the same as Action["ARM"] | Action["x86"].

For example,

interface Action {
  foo: number;
  bar: string;
}

persist<"foo" | "bar">(
  "foo", // allowed, "foo" extends "foo" | "bar"
  "text", // allowed, "text" extends string which extends Action["bar"] which extends Action["foo" | "bar"]
}

See this Playground example.

You need to come up with a structure that actually enforces that each action goes only with its own data. You can’t do that with separate function arguments, but you can do it with a single object. To do it, though, you need a union of the specific type-pairings you’re looking at:

type Actionable = [action: "ARM", data: Action["ARM"]] | [action: "x86", data: Action["x86"]] | //…

You can automate the creation of Actionable by using distributive types, though you’ll need a helper type for it because this is one of those weird times where a type alias isn’t just an alias in TS: you need the somewhat arcane distributive property. A type is distributive, i.e. it handles a union argument by applying the type to each member of the union separately and then unioning those results, if its argument isn't constrained.

// distributive type because <K> isn't constrained
type _ActionableOf<K> = [action: K, data: Action[K]];

// distributes, so each keyof Action is handled separately,
// so equivalent to _ActionableOf<"ARM"> | _ActionableOf<"x86"> | …
// which equals ["ARM", Action["ARM"]] | ["x86", Action["x86"]] | …
type Actionable = _ActionableOf<keyof Action>;

With this, you can write a persist function that is actually typesafe.

declare function takeNumber(val: number): void;
declare function takeString(val: string): void;

function persist<A extends Actionable>(...[action, data]: A) {
  if (action === 'foo') {
    takeNumber(data);
  }
  else if (action === 'bar') {
    takeString(data);
  }
}

See this in a Playground. Note that despite destructuring with ..., this function sees the two arguments as a single Actionable object (which is defined as a 2-ple). TS can narrow that 2-ple based on its members (I was honestly surprised to discover this, I thought you’d have to work with the 2-ple as a single object, i.e. actionable[0] instead of action and actionable[1] instead of data, in order to get narrowing).

Also, in this case, currently, there isn’t actually a need for the generic on persist, either. Writing function persist(...[action, data]: Actionable) would work just as well. The generic would be useful if, say, you wanted to return something different depending on A.

Kevin Ryan (@krryan)

Kevin Ryan (@krryan) it seems the underlying issue is there is no way to constrain a type to be a single key

which is #27808

Navigation Menu

Repository navigation

Generics extending unions cannot be narrowed #13995

42 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Generics extending unions cannot be narrowed #13995

Description

Activity

masaeedu commented on Mar 22, 2017

Nimelrian commented on Jan 18, 2018

RyanCavanaugh commented on Feb 6, 2018

lingz commented on Jun 18, 2018

mifopen commented on Nov 16, 2018

krryan commented on Nov 16, 2018

mysticatea commented on Jan 9, 2019

DerGernTod commented on Feb 6, 2019

rsolomon commented on Feb 14, 2019

OliverJAsh commented on Mar 29, 2019

zakhenry commented on Jun 22, 2019

42 remaining items

Cauen commented on Mar 13, 2022

leonchabbey commented on May 20, 2022

alekangelov commented on Jul 7, 2022

douglasg14b commented on Jul 11, 2022

RyanCavanaugh commented on Jul 11, 2022

douglasg14b commented on Jul 12, 2022

RyanCavanaugh commented on Jul 12, 2022

douglasg14b commented on Jul 12, 2022

coder-mike commented on Dec 19, 2022

thierry-stul commented on Jun 5, 2024

Woodz commented on Jun 25, 2024

marcospgp commented on Jun 25, 2025

krryan commented on Jun 25, 2025

marcospgp commented on Jun 26, 2025

jcalz commented on Jun 26, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions