JS type and name resolution #36

sandersn · 2019-12-03T17:39:31Z

This document came out of conversations with Eli, who pointed out that we don't have a good description of how types are resolved. The current handbook just hopes that type references will "just work", so omits any discussion.

Once I got started writing a reference page, the level of detail is right for explaining name resolution JS as well. I didn't finish this, but I wanted to send the type resolution explanation out for review first. I can cut the name resolution sections for later if needed.

elibarzilay · 2019-12-03T18:28:25Z

reference/JSDoc-Type-References.md

@@ -0,0 +1,242 @@
+In Javascript files, the compiler understands Typescript types in
+JSDoc comments like `@type` and `@param`. However, it has additional


Add a link to the page you pointed me to? (With a TODO to switch to the new page when it's in this repo?)

elibarzilay · 2019-12-03T18:59:10Z

reference/JSDoc-Type-References.md

+`Number`    | `number`
+`String`    | `string`
+`Boolean`   | `boolean`


This is good to know, but very confusing... I'm guessing that in jsdoc either they're the same or people don't make a distinction, but then I saw that TS does have Number etc, and I can't figure out the difference or why number is preferable. (Maybe this is the answer, and if so add a link to it, or better, to the thing it points to.)

I'd rather link to another reference page that explains the difference. I didn't use the correct terms here, which probably made googling harder.

elibarzilay · 2019-12-03T19:00:39Z

reference/JSDoc-Type-References.md

+The rewrite `Object -> any` is disabled when `"noImplicitAny": true`,
+which the compiler takes as a signal that the code is being written
+with Typescript in mind. Old versions of Typescript also rewrote
+`object -> any`, but stopped in Typescript 3.7.


(Even more confusing for Object vs object...)

elibarzilay · 2019-12-03T19:17:56Z

reference/JSDoc-Type-References.md

+`Null`                | `null`
+`Undefined`           | `undefined`
+`Void`                | `void`
+`function`            | `Function`


Yet more confusion, especially since this is unlikely to have the same explanation as the above--?

I will write more explanations for all of these.

elibarzilay · 2019-12-03T19:19:32Z

reference/JSDoc-Type-References.md

+`Object<number,Type>` | `{ [x: number]: Type }`
+
+Finally, `Array` and `Promise` both default their type parameters to
+`any` when no type parameters are provided:


Side-question: shouldn't these be using unknown when noImplicitAny is on?

That's not how it works in JS -- JS defaults to any -- although perhaps it should. You are probably thinking of inference's default, but elsewhere in TS you just get an error, and the resulting variable has type any:

var a: Array

Yes, I was thinking that would happen only if you're using noImplicitAny. (And an unknown seems to me a bit better than an error, since it would lead to other errors which will clarify that you need to say what's in it.) In any case, it's a tangent...

elibarzilay · 2019-12-03T20:56:37Z

reference/JSDoc-Type-References.md

+  frabjous: true,
+  beamish: true,
+  callooh: "callay",


(Made me spill some time on google...)

reference/JSDoc-Type-References.md

elibarzilay · 2019-12-03T21:07:05Z

reference/JSDoc-Type-References.md

+Expando declarations are those that start with an initial declaration
+and add properties to it, like so:


(Probably not the right place, but I get the feeling that these expando things deserve their own page?)

Hmmm probably so. Let me write a bit about aliasing here and then I'll think about whether to move it into a new page.

Yep, I started on aliasing and I think Assignment Declarations need their own page, which will cover expandos and various kinds of aliasing.

I'll remove it from this PR.

elibarzilay · 2019-12-03T21:32:26Z

reference/JSDoc-Type-References.md

+Like expando, except that you are often directly making entries in the
+module's symbol table instead.
+
+TODO: Explain aliasing.


I'm not sure whether this TODO is repeated or maybe it is about some other kind of aliasing (since I don't know how commonjs is related here, isn't it just module-level thing?).

The compiler tries even harder to figure out patterns of aliasing for module.exports, which means that this section will expand on the previous one.

elibarzilay · 2019-12-03T21:35:21Z

reference/JSDoc-Type-References.md

+<!--
+## Weird Stuff ##
+
+- `@enum`


From what I've seen (after your "oh boy, @enum" comment, which made me go look), this would probably be a useful addition...

weswigham · 2019-12-03T23:28:02Z

reference/JSDoc-Type-References.md

+
+`getIntendedJSDocTypeReference` in src/compiler/checker.ts.
+
+## Values as Types ##


I'll be honest, I'd prefer to never mention this in any documentation ever so that we don't imply that we think relying on it is a good idea (it's not).

Like maybe we could talk about it in the TypeScript necronomicon or something, but I'd leave it out of the handbook.

Reference pages are the necronomicon, or the closest we'll get in an open-source team.

This is why I've never written it down before, though. I hoped it would "just work" for most people.

But, like, rust has a hard split between "The Rust Book" and "The Rustonomicon" (which is what I was referencing before). While documenting the current state of esoteric edge cases in, say, conditional type resolution or js type lookup is laudable, I don't think it should be adjacent to information that's much more mainstream - it serves mostly to distract. Like, I think the "what simple remappings do we do (String -> string)" is more useful for casual reading and documentation, while "what fallback code exists within the compiler, approximately" is heavyweight "I wanna know how the compiler internals tick" stuff. This article does a bit of both - I'd split it into two pieces, down those viewership lines, with one targeted at each audience, tbh.

I think we're going for the same two categories, but with a softer split. Look at the other documents in reference/ -- they cover the same kinds of things.

I think it is worthwhile to put the first section's information into the handbook under checkJs though.
It's just that that chapter doesn't exist yet.

Does that mean that Compiler Options belongs elsewhere? Because that is just a reference, while the rest are really technical internal discussions.

Probably. Not sure where it should go, though. @RyanCavanaugh opinions?

Yeah, I think this is good case for splitting into two articles - my goal when I get my hands on doing new handbook stuff is to try split the existing doc into three main camps:

Language Learners

Experts looking to debug why something isn't what they expect

People wanting to faff with tooling

And each doc on any topic should ideally only be trying to address one of those three people (e.g. don't try mix the descriptions of config settings deeply in with a language feature)

I expected we'd need a bunch of docs for JSDoc though, so I wouldn't worry too much now about how it splits because once it starts becoming public facing we'll have more info

@orta when you say "faff with tooling", are you thinking of API consumers? This article is mostly people interested in compiler internals, with a touch of "experts' debugging help". That's what I was thinking of for the Assignability page too; realistically knowing the mechanics of assignability isn't going to help debugging much.

For example "TypeScript with webpack" or "TypeScript with eslint" user-level stuff - not this depth 👍

Re-use FOO | BAR example throughout the algorithm explanation.

oh no

elibarzilay · 2019-12-16T23:19:05Z

reference/JSDoc-Type-References.md

+JSDoc authors wanted to use `object` with its Typescript meaning. The
+rewrite `Object -> any` is disabled when `"noImplicitAny": true`,
+which the compiler takes as a signal that the code is being written
+with Typescript in mind.


Maybe drop "which ... mind" since it's mentioned at the top?

sandersn added 8 commits December 2, 2019 11:05

outline + intro + entry points

6c1f5a4

document simple rewrites

2f2cd1c

mostly done with Values as Types

6bd7db4

Finish values-as-types 1st draft

ce031f0

basic info on expandos

5a2db5a

add expando example

b35fc1d

More polish and small expando section

a0049e9

Fix intro text

0d908a5

sandersn requested review from RyanCavanaugh, andrewbranch, elibarzilay and orta December 3, 2019 17:39

elibarzilay approved these changes Dec 3, 2019

View reviewed changes

weswigham reviewed Dec 3, 2019

View reviewed changes

halfway through review comments

48194b3

andrewbranch mentioned this pull request Dec 6, 2019

Provide easier access to object in JavaScript JSDoc microsoft/TypeScript#34980

Closed

5 tasks

sandersn added 3 commits December 9, 2019 09:57

Rewrite value-as-type section

c9edeab

Re-use FOO | BAR example throughout the algorithm explanation.

Document @enum

bca507e

oh no

Small cleanups

8ed9449

elibarzilay reviewed Dec 16, 2019

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

JS type and name resolution #36

JS type and name resolution #36

sandersn commented Dec 3, 2019

elibarzilay Dec 3, 2019

elibarzilay Dec 3, 2019

sandersn Dec 3, 2019

elibarzilay Dec 3, 2019

elibarzilay Dec 3, 2019

sandersn Dec 3, 2019

elibarzilay Dec 3, 2019

sandersn Dec 3, 2019

elibarzilay Dec 3, 2019

elibarzilay Dec 3, 2019

elibarzilay Dec 3, 2019

sandersn Dec 5, 2019

sandersn Dec 9, 2019

elibarzilay Dec 3, 2019

sandersn Dec 5, 2019

elibarzilay Dec 3, 2019

weswigham Dec 3, 2019

weswigham Dec 3, 2019

sandersn Dec 5, 2019

weswigham Dec 5, 2019 •

edited

Loading

sandersn Dec 5, 2019

weswigham Dec 5, 2019

sandersn Dec 5, 2019

orta Dec 6, 2019

sandersn Dec 9, 2019

orta Dec 9, 2019

elibarzilay Dec 16, 2019

		@@ -0,0 +1,242 @@
		In Javascript files, the compiler understands Typescript types in
		JSDoc comments like `@type` and `@param`. However, it has additional

		Expando declarations are those that start with an initial declaration
		and add properties to it, like so:


		`getIntendedJSDocTypeReference` in src/compiler/checker.ts.

		## Values as Types ##

JS type and name resolution #36

Are you sure you want to change the base?

JS type and name resolution #36

Conversation

sandersn commented Dec 3, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

weswigham Dec 5, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

weswigham Dec 5, 2019 •

edited

Loading