Export API to provide lib.d.ts listing/mapping

[jakebailey]

See:

• Updates vfs to be more future safe when running on node + 2021 dts files for playground TypeScript-Website#2802 (comment)
• microsoft/monaco-editor@main...jakebailey:monaco-editor:reduce-monaco-change#diff-dbd48261b3

[jakebailey]

Checked, and this variable has been defined (with type Map) since 3.0, which predates TS in the playground, so this is a really good option for a backwards compatible playground and so on.

[orta]

Nice, thanks! Will update the vfs side to use the private implementation and can have it prefer whatever implementation ends up happening here

[fatcerberus]

This leads to people duplicating the list externally

you mean like this?
https://github.com/fatcerberus/ts-sphere/blob/master/cell/ts-tool.js#L71-L87

also having to do all this is kind of annoying too
https://github.com/fatcerberus/ts-sphere/blob/master/cell/ts-tool.js#L102-L116

[jakebailey]

Er, why not call ts.getDefaultLibFileName for the former? Not sure what's going on in the second example, sorry.

[fatcerberus]

@jakebailey I assumed that would end up just calling my custom callback here.

Second example is getting a directory listing while handling includes, excludes, ignoring node_modules, etc. In particular if I don’t do that last thing then it ends up pulling in .js and .ts files from within node_modules as if they were part of my project. I really would like to be able to just give TS an unfiltered directory listing and have it handle all that busywork for me. Especially since tsc uses a slightly different globbing algorithm than what most APIs provide.

[fatcerberus]

Addendum: The node_modules exclusion is particularly fun because in order to mimic tsc you seem to have to ignore node_modules but not node_modules/@types, which I only figured out by trial and error.

[jakebailey]

That feels really unrelated to this PR.

[fatcerberus]

It is; I only brought it up as an aside since it’s another case where it’s easy for the logic to fall out of sync with tsc proper. I didn’t mean to imply that should be addressed here, so I apologize.

My concern w.r.t. this PR was my first snippet, but apparently that’s unrelated too (there already being an API that handles that case), so now I’m confused about exactly what this PR does.

[jakebailey]

Per meeting, it seems like this list might not be exhaustive, and that we should just export a function instead of the map itself (which is what I suspected). I'll update the PR with those changes.

In Monaco/VFS we probably will have to still access this or an equivalent for the file list but we could just export and immediately deprecate it, or, just leave it as an unsafe access because those builds aren't going to change.

[jakebailey]

Hah, yeah, it's totally not the right thing. There's a major difference between the two lists. Oops.

[jakebailey]

The PR has been overhauled to take a completely different approach. I've added a new generated.ts file that pulls the info out of libs.json like we do diagnosticMessage.json, then added new APIs that use that data.

Happy to take feedback on this!

[orta]

I'd like to throw open the idea that this PR should probably also add some sort of "compiler options to lib list" function?

If you think about how this is would be used in a real-world project, you currently need to pre-download all necessary dts files ( which is what a big chunk of monaco typescript is doing in its build steps ) this PR would allow you to know what those files are in future TS versions.

However, if you wanted to be a bit more elegant, you might not need to download all the necessary files ahead of time, an API letting you know the necessary lib files to predownload would be useful there.

Right now in the playground for example, an ordered array of "all libs" is effectively chopped down from the highest target or lib member, which is OK, but a hack - it'd be nice to be able to ask TypeScript for the exact libs needed

[andrewbranch]

I have wanted something similar before, but TypeScript doesn’t actually know what that list is going to be since lib files just reference others. The solution I had in mind when I was thinking about this problem was to make a project with automated builds and publishes that track TypeScript versions (like ts-expose-internals), so non-arbitrary work can be done at build time to determine common bundles. I also wanted to expose literal bundles, not just lists of filenames, both minified and unminified, to further make web-based TS tools easier. I didn’t get around to it because I realized I didn’t need any lib files in the end for arethetypeswrong.github.io, but I still think it would be a nice project. And unfortunately I don’t think TypeScript can provide that as a first-class API.

[andrewbranch]

I don’t think TypeScript can provide that as a first-class API

Well, I guess what this PR is already doing is build-time processing in service of a first-class API. But the processing would have to get significantly more complicated to accomplish what @orta suggested.

[orta]

That's very reasonable IMO

[jakebailey]

My main reservations about this PR right now are:

• The added build step and generated file creates a new speedbump in bisecting.
• I haven't yet figured out what we're going to do across the board to properly get a file list for older packages. This makes me wonder if I should even bother with this API at all... in favor of instead doing something like assuming a CDN with file list support. Or, even just not having this API at all and instead including a JSON file in the package with this info rather than a programmatic interface. After all, the only reason I want this is for VFSs.

[andrewbranch]

If someone were to implement my idea of doing something like this in a sidecar project, it could build the list for historical versions.

[jakebailey]

If someone were to implement my idea of doing something like this in a sidecar project, it could build the list for historical versions.

I should also say that I want to have this same info available for pack this, but hopefully without any extra build steps past npm publish (since I would like the playground to be just "point at a CDN that hosts the TypeScript package" and it's done), but maybe a service could handle that. But, I also don't really want to actually set up such a project either or make monaco rely on it...

[typescript-bot]

Looks like you're introducing a change to the public API surface area. If this includes breaking changes, please document them on our wiki's API Breaking Changes page.

Also, please make sure @DanielRosenwasser and @RyanCavanaugh are aware of the changes, just as a heads up.

[sheetalkamat]

Should this lowercase libName eg. ES5 should also get lib.es5.d.ts.. Eg. look at getLibFileNameFromLibReference

[jakebailey]

I think my intent here was that you only ever give this function strings you get from the other APIs, though I just haven't had time to deal with this PR (besides updating it post-dprint) so I can't remember anymore 😅

[sandersn]

@jakebailey This PR has an approval, but is also still a draft. Is it ready to merge? Does it still need work?

[jakebailey]

No, this will require me to get back into the headspace to work on Monaco and the playground. I plan to come back to it.