Repository: TypeScript
Issue: Suggestion: type narrowing based on user-defined type guards against properties
Labels: Suggestion,In Discussion

<!-- 🚨 STOP 🚨 𝗦𝗧𝗢𝗣 🚨 𝑺𝑻𝑶𝑷 🚨

Half of all issues filed here are duplicates, answered in the FAQ, or not appropriate for the bug tracker.

Please help us by doing the following steps before logging an issue:
  * Search: https://github.com/Microsoft/TypeScript/search?type=Issues
  * Read the FAQ, especially the "Common Feature Requests" section: https://github.com/Microsoft/TypeScript/wiki/FAQ

-->

## Search Terms

user-defined type guards, type predicates, type narrowing, object properties

<!-- List of keywords you searched for before creating this issue. Write them down here so that others can find this suggestion more easily -->

## Suggestion

TS can narrow object types in `if` statements and other conditional control flows by various means. Particularly, if the object's type is a union type distinguishable by a "tag" (like `Option<T>` in the below example), we can narrow the type by checking the value of the tag. However, if the check for the tag is done by user-defined type guards against the property (but not the object itself), the object's type is not narrowed.

The suggestion is to make it work even if user-defined type guards are applied to object properties

## Use Cases

The "tagged union" pattern is widely used in TS codebases. If tags theirselves are so complicated, we want to utilize user-defined type guards to check them.

## Examples

```ts
type Option<T> = {
  type: "some"
  value: T
} | {
  type: "none"
}

const isSome = (type: "some" | "none"): type is "some" => type === "some"

declare const option: Option<number>

// Good: option is narrowed in the if block
if (option.type === "some") {
  option.value
}

// Bad: option isn't narrowed
if (isSome(option.type)) {
  // Error: Property 'value' does not exist on type 'Option<number>'.
  option.value
}

// Available workaround
const isSomeObject = <T>(option: Option<T>): option is Extract<Option<T>, { type: "some" }> => option.type === "some"

if (isSomeObject(option)) {
  option.value
}
```

[playground](https://www.typescriptlang.org/play/#code/C4TwDgpgBA8mwEsD2A7APAFQHxQLxQG8BYAKCilEgC4oAiAZyQFsJbTyA3AQwBsBXCDQykAvlAA+hdhXCC6KVK1GlSAY1T1gUBPQDKzaPgAUlOQwO0J8xbQCUNU9vp1GLS7hyPc3lxZUkAEwhVHi4AJ2h1FE0oJHhkFBo4RFQ0FD4mACMIMKx-AHp8qABxJCQAmjiUlCcoFHCwpAB3CADtGuAAC2gEADMoTJ4kVQBrUj6oIyqEgDovH3M3WykyWPjUGe5+CGUSUkKoACEuCrXqpxQAci16sMaWgPH+ox19Fin1lDnZW2XiVYOAFE7kgwjQAAqNSBhUBQS5bASXKABJAQZwKLQQAAeOi0qBkkDhyQSaQy2Vylxm0mmGwROxIIgKRQAgtwEKFBtAmqCRuEkHwUI8SFEYq8DDBMgArYJafCYLAfapJT7y+xnBK1QFY4BhLiqYBoYmpbAAGkIBLMrlYUBEOA86o283wiyUexIExeenFUplioSvxW5BpXzpoiAA)

## Checklist

My suggestion meets these guidelines:

* [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
* [x] This wouldn't change the runtime behavior of existing JavaScript code
* [x] This could be implemented without emitting different JS based on the types of the expressions
* [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).