"Using type predicates" documentation promotes lying to the type system

[ilyash-b]

Acknowledgement

• I acknowledge that issues using this template may be closed without further explanation at the maintainer's discretion.

Comment

Using type predicates documentation provides this example:

function isFish(pet: Fish | Bird): pet is Fish {
  return (pet as Fish).swim !== undefined;
}

This promotes lying to the type system. At the point of as, we don't know the type. Still, we tell the compiler "trust me, it's a Fish". This is semantically incorrect.

Why is this a problem? During code reviews, I was wondering about the usage of as before we know the type. Sometimes, it takes more elaborate forms of "lie now, check for the type later". Like the following:

type ExtendedFoo = {
  __a?: (...args: unknown[]) => void;
  __b?: (...args: unknown[]) => void;
  __c?: (...args: unknown[]) => void;
} & Foo;

const isExtendedFoo = (input: unknown): input is ExtendedFoo => {
  if (typeof input !== "object" || input === null) {
    return false;
  }
  const candidate = input as ExtendedFoo;
  return (
    typeof candidate.a === "function" &&
    typeof candidate.b === "function" &&
    typeof candidate.c === "function" &&
    (candidate.__a === undefined || typeof candidate.__a === "function") &&
    (candidate.__b === undefined || typeof candidate.__b === "function") &&
    (candidate.__c === undefined || typeof candidate.__c === "function")
  );
};

Unlike in the handbook, the above example has a potential for disaster. In future, one can insert a line between const ... and return ..., where candidate is potentially of the wrong type.

Despite the difference, it's hard to argue as a code review feedback "do not lie to the type system" when the official documentation does exactly that.

I propose to use as for the cases where "we really know" and update the example to the following:

function isFish(pet: Fish | Bird): pet is Fish {
  return 'swim' in pet;
}

[MartinJohns]

The entire point of type assertions is to work around the type checks of the compiler. You're telling the compiler "trust me, it matches, or will match later one, so shaddap."

"Lying" to the compiler is a necessity in assertion methods.

[jcalz]

I kind of see the point of this request, but it does feel like you're talking about using an umbrella in a hurricane. In general you wouldn't want to use

function foo(pet: Fish | Bird) {
    const x = (pet as Fish).swim;
}

because now TS thinks x is definitely a function even though it is just as likely to be undefined (and less likely but still possible to be something else entirely). That's all you're saying here, right? If so, agreed.

But, um, in the context of a type predicate function, it feels silly, because you can effortlessly lie to the type system:

function isFish(pet: Fish | Bird): pet is Fish {
    return (pet as Fish).swim === undefined; // oops, reversed it
}

function isFish(pet: Fish | Bird): pet is Fish {
  return Math.random() < 0.5;  // 🎲
}

And indeed even the "truth"

function isFish(pet: Fish | Bird): pet is Fish {
  return "swim" in pet;
}

is seen as a lie in

function act(pet: Fish | Bird) {
  if (isFish(pet)) {
    pet.swim();
  } else {
    pet.fly();
  }
}
const duck = {
  fly() { },
  swim: true // 💩
}
act(duck); // RUNTIME ERROR!

If I were going to start worrying about situations where lying was dangerous, I'd probably change things to

type Fish = { swim: () => void, fly?: never };
type Bird = { fly: () => void, swim?: never };
function isFish(pet: Fish | Bird): pet is Fish {
  return pet.swim !== undefined;
}

but then the whole handbook probably needs to be rewritten to be maximally pedantic? TypeScript is sort of fractally unsound so if you want to get anything done you tend to just pick a place to stop worrying and say it's good enough. For this particular piece of the handbook I feel like it's good enough already.

Playground link

[RyanCavanaugh]

🤖 Thank you for your issue! I've done some analysis to help get you started. This response is automatically generated; feel free to 👍 or 👎 this comment according to its usefulness.

Possible Relevant FAQs

How do I check at run-time if an object implements some interface?

The snippet in the handbook shows one possible way to implement a user-defined type guard. At run time there is no Fish or Bird type metadata to query—everything has been erased—so the only option is to inspect the value’s shape and return a boolean. Whether those property checks are written with a cast or with the in operator does not change the safety guarantees TypeScript can offer: correctness depends entirely on the logic inside the guard.

The cast in

(pet as Fish).swim !== undefined

exists only so the compiler accepts the property access on swim. No value is coerced and no runtime assumption is introduced; it is still just an ordinary property lookup. If the guard later returns true, the compiler narrows the original union to Fish for the caller. If additional code is inserted before the return and that code treats candidate as an ExtendedFoo without first proving it, that is a bug in the guard’s implementation—exactly the same bug that would exist if the guard skipped the typeof checks entirely.

If the cast feels too permissive during code review, rewriting the guard to avoid it is straightforward:

function isFish(pet: Fish | Bird): pet is Fish {
  return "swim" in pet;
}

or, for the more involved example:

const isExtendedFoo = (input: unknown): input is ExtendedFoo => {
  if (typeof input !== "object" || input === null) {
    return false;
  }
  const obj = input as Record<string, unknown>; // only to silence index errors
  return (
    typeof obj["a"] === "function" &&
    typeof obj["b"] === "function" &&
    typeof obj["c"] === "function" &&
    (obj["__a"] === undefined || typeof obj["__a"] === "function") &&
    (obj["__b"] === undefined || typeof obj["__b"] === "function") &&
    (obj["__c"] === undefined || typeof obj["__c"] === "function")
  );
};

Either style is acceptable. The important part is that every path to true actually proves the required properties exist. If that discipline is followed, the type guard remains sound whether or not it includes an as cast.

Similar Issues

Here are the most similar issues I found

• (72%) microsoft/typescript#44450: Type narrowing as documented is broken
• (67%) microsoft/typescript#54467: possible bug with is predicate?
• (66%) microsoft/typescript#57436: Type assertions & type predicates can have incorrect narrowing logic
• (66%) microsoft/typescript#58855: Type guards do not flow when used as callbacks
• (65%) microsoft/typescript#51326: Type predicate assertion does not carry over when used in another function

If your issue is a duplicate of one of these, feel free to close this issue. Otherwise, no action is needed.

[RyanCavanaugh]

I would argue that there's usually no perfect way to write a type predicate function, because if you did have a perfect way to test the type (e.g. a discriminant property), you generally wouldn't have written a type predicate in the first place, since TS's built-in narrowing handles these on its own. This puts the documentation in an impossible position: If the body of the predicate function is true and sound, there's no reason to be writing one.

The proposed alternative trades one problem for another. If you use in, you lose type safety on the key, which isn't true of as:

type Bird = { fly: boolean };
type Fish = { swim: boolean };

function isFish(pet: Fish | Bird): pet is Fish {
  return 'swm' in pet; // Typo missed
}

[ilyash-b]

you lose type safety on the key, which isn't true of as:

in is not a clear winner then. Wanna comment on this in the handbook or just close this issue?

[jendrikw]

Type guard are always circumventing the type system. I don't use them at all and just test for the properties that I actually need.