TypeScript union types - error only on function invocation

Question

I've stumbled upon a weird behavior when using union types in TypeScript. When passing a reference of a function, without invoking it, there is no type error:

type A = boolean;
type B = string;
type C = number; 
type BC = B | C; 

interface Props { onChange(expr: A | BC): void } 

const SomeFunction = (_props: Props) => {}
const handler = (el: A | B) => { console.log(el) } 
 
SomeFunction({onChange: handler}) // no error here 
 
SomeFunction({onChange: e => handler(e)}) // <- TS Error: Argument of type 'boolean | BC' is not assignable to parameter of type 'string | boolean'.

The only explanation I could find is improved behavior for calling union types in TypeScript 3.3.

I'm curious about the reasons why there is no error when calling SomeFunction({onChange: handler}) - Is it because there is an overlap between union types?

link to typescript playground

I don't see any union types being called here: in the call `f(x)`, `x` is a union, but `f` is not. Instead this is the difference between contravariant function arguments (safe, when `--strictFunctionTypes` is turned on) and bivariant *method* arguments (unsafe no matter what compiler option you use). If you write the `onChange` definition with function syntax instead of method syntax you will [see the error in both places](https://tsplay.dev/mLlaAm), for good reason as shown. Does that answer your question? If so I can write up a post; if not, what am I missing? — jcalz, Apr 01 '22 at 15:01
Yes, perhaps my terminology wasn't the best when formulating the question. That's a good catch with onChange definition, thank you! I still try understand why there is no error with a method definition — Jan Cziżikow, Apr 01 '22 at 15:06
Method parameters are treated as *bivariant*, see [this q/a](//stackoverflow.com/q/66410115/2887218) for explanation of what that means. There's [this FAQ entry](//github.com/Microsoft/TypeScript/wiki/FAQ#why-are-function-parameters-bivariant) explaining why they allow it. With `--strictFunctionTypes` this is made safe for non-method functions, but they left it in place for methods because otherwise a bunch of built-in things like `Array` would become nearly unusable. I can go into more detail if I write up an answer, which I can do unless I'm missing something about your question. — jcalz, Apr 01 '22 at 15:22
No, I think that's it - just trying to understand why there is no error when using method definition in the above snippet. If you could write up a detail answer I think it could be also helpful for other people and I certainly would appreciate it as well :) — Jan Cziżikow, Apr 01 '22 at 15:27

score 3 · Accepted Answer · answered Apr 01 '22 at 15:55

The difference is that handler is a non-method function, while onChange was declared in Props to be a method. And when you have the --strictFunctionTypes compiler option enabled (which is part of the --strict suite of compiler functionality), parameters of non-method functions are checked more strictly.

In order to be type safe, a function's parameters should be checked contravariantly, which is described in this q/a, but briefly, a function parameter can be safely narrowed but not widened. Since Expr | Primitive is wider than Expr | StringOrBool, it is not safe to treat handler as an onChange, as shown here when you add some functionality:

const SomeFunction = (_props: Props) => { _props.onChange(3) }

const handler = (el: Expr | StringOrBool) => {
    if ((typeof el !== "boolean") && (typeof el !== "object")) {
        console.log(el.toUpperCase()); // has to be a string, right?
    }
    console.log(el)
}

SomeFunction({ onChange: handler }) // runtime error: el.toUpperCase is not a function

The handler function assumes that a non-boolean non-object parameter must be a string, but SomeFunction calls _props.onChange() with a number. Oops!

So at this point it should be clear that, if all we care about is type safety, there should be an error in both invocations of SomeFunction. Indeed, if we rewrite Props to use non-method syntax for onChange:

interface Props {
    onChange: (expr: Expr | Primitive) => void // call expression, not method
}

then we do see both errors:

SomeFunction({ onChange: handler }) // error! 
SomeFunction({ onChange: e => handler(e) }) // error!

But methods (and indeed all functions without --strictFunctionTypes enabled) allow both the safe narrowing (contravariance) and the unsafe widening (covariance). That is, method parameters are checked bivariantly. Why? Well, it turns out that even though this is unsafe, it's quite useful. You can read this FAQ entry or this doc for details, but in short, it enables some common coding practices (like event handling). People like treating a Dog[] as if it were an Animal[], even though it is technically unsafe. If methods were treated safely, then the existence of the push() method of Animal[] would prevent anyone from using a Dog[] as an Animal[]. See this Q/A for more information.

Because we have both method syntax and arrow function syntax available to us, we can sort of have it both ways if we want; anytime you care about type safety of function parameters, stay away from method syntax.

Playground link to code

score 1 · Answer 2 · answered Apr 01 '22 at 15:22

one solution for this would be to use strict unions:

type UnionKeys<T> = T extends T ? keyof T : never;
type StrictUnionHelper<T, TAll> = T extends any
  ? T & Partial<Record<Exclude<UnionKeys<TAll>, keyof T>, never>>
  : never;

type StrictUnion<T> = StrictUnionHelper<T, T>;

Then if you declare the Primitive type as type Primitive = StrictUnion<StringOrBool | Num> you would get the correct error for both of them. I think this is one workaround for the problem that @jcalz mentioned in the comments that the method syntax declaration is not supported this way. StrictUnion also understands the method syntax. This implementation is mentioned here.

TypeScript union types - error only on function invocation

2 Answers2

Related