How to get TSC to narrow a union type between a function and a Record with a discriminatory property and retain a proper error message

Edit: Comments on this post might not make sense to new readers because of the vast amount of changes that the post went through over its lifetime. Refer to the history if you are confused.

Here are some types which we will refer to in the question (find on tsplayground):

type AnyAction =
  { type: "INC"; } |
  { type: "DEC"; } |
  { type: "SET_VALUE"; payload: number; } |
  { type: "SOME_OTHER_ACTION"; hasExtra: boolean; }

type ThunkAction = () => Promise<any>

type ActionCreator = () => AnyAction | ThunkAction 

The idea behind ActionCreator is to provide a uniform approach to creating "actions" that will be dispatched to the Redux store (which is implemented to allow for thunks). A user would always "invoke" an action creator and dispatch the result to the store. The result as such can be either AnyAction or ThunkAction.

However, there are weird behaviours when we define ActionCreator in such a way, and they seem to appear due to a union between a AnyAction and ThunkAction as TSC is not able to properly narrow down what is the return type of an ActionCreator (at least to my understanding)

For example:

const good: ActionCreator = () => ({ type: "SET_VALUE", payload: 123 })
const alsoWorks: ActionCreator = () => () => Promise.resolve(123)

This works well, TSC even has good autocomplete, suggests the types, constraints the payload to a number, etc.

To showcase what is an expected (or rather, WANTED) behavior I will also demonstrate what happens once we DO NOT USE a union:

// We get a good error message
const noUnion: () => AnyAction = () => ({ type: "WRONG" })
// Type '"WRONG"' is not assignable to type '"INC" | "DEC" | "SET_VALUE" | "SOME_OTHER_ACTION"'

However once we have a union between AnyAction and ThunkAction as a return type for our ActionCreator the error message gets some weird behaviour:

// TSC recognizes this as an error, but gives a less then ideal message
const oops: ActionCreator = () => ({ type: "WRONG" })
// Type '"WRONG"' is not assignable to type '"SOME_OTHER_ACTION"'.

Question:

How would I define the ActionCreator or (as discussed in comments) change the ThunkAction type in order to allow TSC to give a message as shown in the "showcase" even for a union return type for an ActionCreator?

In your code, AnyAction is a discriminated union type, but AnyAction | ThunkAction is not because ThunkAction doesn't explicitly mention the type discriminant. It's a union, but not a discriminated union.

TypeScript tends to do a reasonably good job of producing a readable error if you have an invalid value of a discriminated union type, but when you have an invalid value of an arbitrary union, then the error is sometimes not what people expect. See microsoft/TypeScript#37488 and microsoft/TypeScript#53258 for examples.

The underlying issue is that, if a value is supposed to be of type A | B | C | ⋯ | Z but fails to be, it's because the value fails to be an A and it fails to be a B and it fails to be a C, et cetera. If you fixed even one of those failures, the error would go away. But the compiler can't possibly write an error message that details all of those (e.g., "your value isn't an A because you put a string where you were supposed to put a number and it isn't a B because you forgot the b property and ... and it isn't a Z because it's not an array, so you should fix one of these.") Instead it just picks one of the union members and gives you the error for that one, usually the last one, (e.g., "your value isn't a Z because it it's not an array"). There's nothing necessarily incorrect about that message; after all, if you fixed that, the error would go away. It's just that it might not be the most relevant piece of information for someone trying to understand what went wrong.

In the absence of language changes to improve error messages, one approach you could take would be to turn AnyAction | ThunkAction into a genuine discriminated union by making sure that ThunkAction's declaration explicitly prohibits having a defined type value. Like this, for example:

type ThunkAction = { (): Promise<any>, type?: never }

(That's the equivalent of (() => Promise<any>) & {type?: never}, but it's packaged in a single type.) Note that you can't really prohibit a property in TypeScript; the closest you can come is to make an optional property whose value is the impossible never type, so the only value that could possibly be there is undefined.

Once we do that, we get a more readable error:

const oops: ActionCreator = () => ({ type: "WRONG" });
// Type '"WRONG"' is not assignable to type 
// '"INC" | "DEC" | "SET_VALUE" | "SOME_OTHER_ACTION" | undefined'.

Since "WRONG" is none of possible discriminant types, which now includes undefined, the compiler can issue an error saying that. And hopefully this doesn't change the semantics of the code elsewhere. Your examples still work correctly, at least:

const alsoWorks: ActionCreator = () => () => Promise.resolve(123) // okay

Playground link to code