Allow for safely accessing properties that arguments to a type guard function could potentially have

Suggestion

🔍 Search Terms

type guard allow unknown

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

It would be helpful if arguments to a type guard function could be treated as having the potential to be anything, while at the same time making no new assumptions about its type.

📃 Motivating Example

Say we had this Foo class, and we wanted to write a custom type guard to detect if something is a Foo.

type Foo = {
  bar: string;
}

function isFoo(value: any): value is Foo {
  return typeof value.bar === 'string';
}

This has the downside of using any, which is often linted against and unsafe. We'd like to be able to use unknown instead, but then it would complain about accessing value.bar. If we go with the same pattern as the example in the documentation, we get something like this:

function isFoo(value: unknown): value is Foo {
  return typeof (value as Foo).bar === 'string';
}

This also isn't great, because we're using as and thus losing whatever type safety we had about value. In both of these cases, we're ignoring that value could be undefined, and thus break this function.

This could be solved with using new syntax for "expanding" the argument, or by always allowing the argument to be expanded to its limit when its being tested by a type guard.

function isFoo(value: unknown): value is Foo {
  return typeof value?.bar === 'string';
}

This complains in the Playground because of value?.bar, even though it's valid for any possible arguments. It could also be written as

function isFoo(value: unknown): value is Foo {
  if (!value) {
    return false;
  }
  return typeof value.bar === 'string';
}

since in the second path it would have decided that value isn't nullish, and thus value.bar is safe.

The idea is that the argument starts off as a blank slate (or with whatever its initial type is if it isn't unknown) and anything can be accessed on it, provided it's been proven to exist.

If this is considered to big of a change in behavior, it could be introduced as a keyword for the argument (and then possibly used outside of type assertions):

function isFoo(expandable value: unknown): value is Foo {
  return typeof value?.bar === 'string';
}

💻 Use Cases

This would be useful for almost any type guard function that has to take in something unknown as an argument. Even for something with a baseline type, it would help prevent errors from liberal use of any and casting.

Start with the narrowing documentation's type-predicate example and reproduce the linked Playground case. Compare the unknown, any, cast, optional-chaining, and null-check variants, then determine the type-system behavior and syntax needed for safe property access. Done means the intended type guard is accepted without unsafe casts while preserving null-safety.