Consider adding TypeScript types to packages

[NotWoods]

TypeScript is used by a significant number of projects and adding TypeScript types would make it easier to know the shape of the returned objects.

Since the JSON files are all validated against a JSON Schema, types can be automatically generated using a tool like json-schema-to-typescript. You'd only need a small amount of manual work to add a type definition for the listAll function.

Happy to open a PR for this :)

[tidoust]

Thanks for the offer ;) Isn't that what microsoft/TypeScript-DOM-lib-generator, based on Webref data and distributed in the @types/web NPM package, already provides? If not, what would be difference?

I personally tend to like the idea that, apart from a tiny bit of JavaScript code in the packages that consumers can happily ignore, Webref data does not force the use of any particular programming language. I'm sure I can be persuaded otherwise though ;)

[NotWoods]

@types/web covers most interfaces but doesn't cover CSS data. csstype has historically used MDN data to generate strict CSS types but it would be nice to migrate to webref.

Currently @types/web writes its own types for webref. Other TypeScript-based generators would need to do the same, so this puts some extra work on those using the package. (but since it can be autogenerated, it's admittedly not that much work.)

I don't feel that shipping an index.d.ts file with TypeScript types forces the use of a particular programming language any more than index.js does. JavaScript devs benefit from autocomplete but can ignore it. TypeScript devs benefit from strict types. Other languages are going to use the JSON files and can generate their own wrappers from the JSON schema if desired.

[tidoust]

OK, that seems good indeed.

@dontcallmedom and I are not TypeScript experts. If we can take you up on your offer to craft a pull request, that would help us assess whether we can easily maintain this afterwards :)

Also tagging @saschanaz for perspective and possible overlap with, or usefulness for, @types/web.

[saschanaz]

@types/web implementation also depends on BCD data to make sure things are implemented by two distinct browser engines and also adds several typescript-specific manual modifications e.g. generics. Perhaps webref could provide a way to decide whether to add a type or not.

But I'm not sure it's worth to reimplement all of that here instead of extending @types/web to better support CSS, if that's the main reason. The lack of better CSS support was mainly because CSS syntax is complex enough to limit things based on implementation status, but I guess that's now at least better with foolip/mdn-bcd-collector#1805. (And also because there's no full time worker focusing on that library, I'm just maintaining it in my free time. Which means, PRs welcome.)

Also, webref would need to coordinate with Microsoft or it'll cause a lot of conflict with the existing libraries depending on the current @types/web definitions. (Microsoft wants to put such coordination inside their own repo because of their internal policy, which is why the library is in Microsoft org right now. Maybe we can start some talk to change that...)

[NotWoods]

csstype provides an equivalent to @types/web with more CSS specifics.

I'm not advocating for generating DOM types here, but instead types for the listAll method that just make the shape of the webref JSON clearer. This would make webref easier to use in generators like @types/web and csstype.

[saschanaz]

Hmm, for CSS it sounds reasonable, but for others not sure.

For example @types/web is generating T[] and Iterable<T> for sequence<T> in separate files for ES5 compatibility. What would webref do for sequences?

[saschanaz]

Oh also for CSS, what would it do when there are 7 keywords in the spec but only 5 are ever implemented in browser engines and only 3 are in multiple engines? And what would it do for more complex syntax?

To do it "properly" without defining all the syntax, csstype uses hacky string & {} and I know the TypeScript team is against this hack. microsoft/TypeScript-DOM-lib-generator#1467 (comment)

[saschanaz]

Oh wait, you mean you just want this? https://github.com/microsoft/TypeScript-DOM-lib-generator/blob/main/src/build/webref/webref-idl.d.ts

I was totally misunderstanding then, I'm all for that. And I don't think it'll be any hard to maintain.

[NotWoods]

Yes, I just wanted something like that file with a little more detail based on the existing JSON schema.

I started working on the PR but will hold off on publishing for now, because there's some bugs with reffy's JSON schema I noticed. Will try to resolve those first.