Docs: "Type assertion" vs "asserts" keyword

[bcherny]

Hey there!

I’m updating Programming TypeScript to include assertions in control flow analysis, and was looking for guidance about naming.

Type assertions (x as T) and assertions in control flow analysis (asserts x is T) are similarly named. What’s a good way to call these these features, in a way that doesn’t confuse people and aligns with the way the TS team is communicating it?

A couple of ideas:

1. Rename x as T to “type coercion” or “type casting" (even though it’s not a runtime behavior), and call asserts x is T a “type assertion”
2. Keep x as T as-is (“type assertion”), and call asserts x is T a “user-defined type assertion”, similar to a “user-defined type guard”

Thanks!

[AnyhowStep]

I like to call the as T operator the make-this-expression-of-type-T-trust-me-i-know-what-type-this-is-and-i-know-what-i-am-doing-but-can-you-please-check-if-both-types-sufficiently-overlap-anyway-just-in-case operator.

I never liked the word "cast" for it because it implies something else in other programming languages.

[jcalz]

Hmm, maybe x as T is an assertion expression, while calling a function returning asserts x is T is an assertion statement:

function as<T>(x: any): asserts x is T { }

// proper use
let exprAssertGood = Math.random() < 3 ? "hello" : 123;
(exprAssertGood as string).toUpperCase();

// proper use
let stmtAssertGood = Math.random() < 3 ? "hello" : 123;
as<string>(stmtAssertGood);
stmtAssertGood.toUpperCase(); // okay

// improper use
let exprAssertBad = Math.random() < 3 ? "hello" : 123;
exprAssertBad as string;
exprAssertBad.toUpperCase(); // error, prior assertion only existed in the immediate expression

// improper use
let stmtAssertBad = Math.random() < 3 ? "hello" : 123;
as<string>(stmtAssertBad).toUpperCase(); // error, assertion is a void expression

Playground link

[orta]

Disclaimer: my opinion

"assertion" in these cases means that you're telling the compiler what a type is, and the compiler will trust you know what you're doing e.g.

• x as T is a type assertion because it's a demand on the compiler and could be wrong (vs x: T)

• asserts x is T is an assertion signature (in that it's always at the end of an existing function) which could be referred to as a function with an signature. The compiler doesn't validate it either.

[bcherny]

I like both @orta and @jcalz's ideas! The book revision is ready to go, pending this decision.

One other thing that may be worth indicating in the name is that asserts is a bit unique, in that it's a lot like a side effect, but at the type level. "Assertion effect" or "Refinement effect" might be a bit too nerdy, but maybe there's a more obvious name that makes this clear.

[isimmons]

Is "assertion signature" or "asserts" in the docs somewhere? I searched and couldn't find it. I'm new to Typescript and have had more than one tutorial refer to "x as T" as casting. Then in a more advanced tutorial I learned about "asserts x is T" and assumed it was "type assertion" because the instructor didn't call it by name. I'm here now because another tutorial going over the use of "x as T" has just referred to it as type assertion instead of casting so I went googling because I thought they were wrong. Also confusing because of how I think of assert in testing and other languages as a test or check that returns true or false depending on a condition or the result of an expression.