Design Meeting Notes, 8/11/2020

Question

DanielRosenwasser opened this issue 5 years ago · 0 comments

`///` Comments

(10 minutes)

Idea is using single-line 3-slash/triple-slash /// comments instead of /**
We might be the biggest processor of JSDoc
JSDoc also has a /// comment plugin supported since 2011.
Orta submitted an issue, JSDoc team more or less said "won't add it to core because VS Code won't support it" (!!!???)
Community Support
- Deno wanted to add it for itself.
- A couple of votes in TSDoc, team agrees it's a better design.
Why are we leading on this one?
- Not one specific
Need a thing on TSServer to specify preferences
What about /// <reference /> comments?
- Scanner throws out directive comments.
What about directive comments like /** @jsx */?
- But ts-check is single line?
- No, some directives require multiline comments.
  - We're just copying Babel's logic there.
  - Don't change it.
TmLanguage needs updates
Need community updates
- JSDoc
- TSDoc
- WebStorm
- Closure
- Others? (sorry!)
What about XML comments? C# converts might expect XML.
- Probably won't do this.
Multiple ways to do something is not ideal.
- Also, lint rules can help pick up slack here.
Work with other stakeholders in community.

Example with AssemblyScript
- Not showing Rust because their WASM support is super good.
- WasmPack generates foo.wasm.d.ts
What happens with numbers?
- i32, i64, f32, f64
- Proposals for expanded types.
- But all of them are just number to JavaScript, and those numbers get coerced.
Implementation takes the WASM and generates a virtual .d.ts file that gets type-checked against.
How do you report errors on these?
- Unclear.
Go to definition?
- Virtual file is the definition.
- But also, can read DWARF info to get the real source in some cases.
Meta-point: our APIs were hard to work with.
- readFile gets a string. WASM is not a string!
- readFileBuffer 😣
Also problems with incremental updates.
Unclear whether this should just be a standalone tool or an integrated thing.
No reason it can't start out as a build tool.
Definitely want to continue exploring this space.

If you want to write the Awaited type today, you can only do it with indexed access type hacks
But it is ugly.
- But people are writing this in Stack Overflow answers.
We even use the same trick for Array.prototype.flat()
When we started, we intentionally limited recursive conditional type by forcing eager evaluation.
- But could still use indexed access type trick. In the last few years, we've been hardening the compiler against run-away recursion. In a sense, these wacky indexed access types gave us early feedback on how to implement conditional recursive types correctly.
So adding recursive conditional types is trivial - we more or less just stop eager evaluation of any given branch of a conditional type. We now we defer until instantiation time.

Awaited can be written as

type Awaited<T> =
  T extends null | undefined ? T : // for non-strictNullChecks
  T extends PromiseLike<infer U> ? Awaited<U> :
  T

The thing about Awaited is that every method that passes the await-ed value ought to use Awaited - but that breaks a ton of stuff!
Let's get a PR out and get some community feedback!