The Wayback Machine - https://web.archive.org/web/20211123093218/https://github.com/microsoft/TypeScript/issues/35653
Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: "Type assertion" vs "asserts" keyword #35653

Open
bcherny opened this issue Dec 12, 2019 · 4 comments
Open

Docs: "Type assertion" vs "asserts" keyword #35653

bcherny opened this issue Dec 12, 2019 · 4 comments

Comments

@bcherny
Copy link

@bcherny bcherny commented Dec 12, 2019

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
Copy link
Contributor

@AnyhowStep AnyhowStep commented Dec 12, 2019

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.

Loading

@jcalz
Copy link
Contributor

@jcalz jcalz commented Dec 13, 2019

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

Loading

@orta
Copy link
Member

@orta orta commented Dec 18, 2019

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.

Loading

@bcherny
Copy link
Author

@bcherny bcherny commented Dec 21, 2019

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.

Loading

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants