[Discussion] esm-d-ts

[typhonrt]

Hi Rich,

Just posting a note as I'm quite active on the Svelte side of things and have built a tool for automatic ESM to DTS support that I use for my expanding library effort that I've been at for the past 1.5+ years. I've been doing the ESM native thing this whole time + TS / JSDoc integration. It does a few things that your effort does not, but I'm certainly curious to take a look at your approach to the problem as it differs from the path I've gone down. Anyway.. My effort is here esm-d-ts. I should be finishing off some pretty advanced features in short order in regard to automatically linking local symbols for import types and ts-morph integration for when more involved AST modification of the generated DTS is useful (I've got one use case for that). From a quick gander at your effort it looks like you might be doing the former re: local symbol linking / import types.

There are some sharp edges to workaround in general w/ the ESM to DTS support via TS. An example there is "static private" variables get tweaked out by TS and remain in the public API via an awkward string substitution in the DTS output (still as of TS 5.0.4). I support TS transformers to handle some of that and also transformers to process JSDoc tags like excluding API that has @internal.

I should have a full beta release of my tooling out very soon w/ full docs; I'm semver conservative. I'm also working on some rather compelling TypeDoc tooling that dynamically uses Svelte and will have a big announcement for that in a couple of weeks. It's more of a TypeDoc default theme augmentation and it cuts down disk space usage by 90% and speeds up doc generation by 80%; pretty insane results there especially for large projects. I use the generated and linked DTS from ESM source to generate cross-linked documentation that supports the TS in JSDoc. I'll have some examples of this for my library soon / next release.

So, just reaching out as we are solving similar problems especially from a library author point of view.

Cheers...

[mryechkin]

@typhonrt I just tried your esm-d-ts library and it worked great. I wasn't having much luck or was 100% clear on how to use dts-buddy, so wanted to give yours a shot. In short - holy crap, thank you! It worked right out of the box and did exactly what I needed.

I'm not a TypeScript user myself, but when I heard about Svelte moving to JSDoc, I wanted to see how I could leverage it in a similar way in my Rollup library starter. Quite honestly I wasn't sure where to even start. A few blog posts later and having been following Rich on GitHub, I ended up here.

Now I had zero expectations for getting this to work over a weekend. My first few tries with dts-buddy landed nowhere, as I mentioned. But when I tried your library everything just worked. I'm going to keep playing around with it, but just wanted to say thank you for sharing it! I'm surprised it has so few stars. Looking forward to the full release 🚀

[typhonrt]

@mryechkin I appreciate the kind words; they inspired me to dig deep and spend all week adding even more fit & finish / polish to esm-d-ts. This is not my forum so to speak, so I won't talk about new features, but it's definitely super streamlined at this point. You can check the README, etc.

But when I tried your library everything just worked.

I put a lot of work into getting it oriented towards zero configuration and being flexible for a variety of approaches including advanced library author use cases too. I also have the benefit of using the tool daily for the last 1.5 years, so a bit certainly was discovered in an iterative manner. I really do have to give appreciation to Guy Bedford for his excellent es-module-lexer package as that is the main underlying tool that allows things to work so smoothly to lexically analyze single file entry points.

I'm surprised it has so few stars.

Certainly a lot to say about that, but not the right forum; the one thing that will be true is that when I receive any sort of critical success it will be the extreme polar opposite of an "overnight success".

---

I do want to sort of bring this up and glad to discuss a technical point of concern on the current direction dts-buddy is implemented. Granted it's early days, but there is a particular edge case that likely won't get caught / seen if Svelte v4 / v5 repo is the test bed for building dts-buddy. I'd be glad to discuss that here or offline if you respond Rich. I also want to make sure any feedback is received as constructive, etc. so no need to bring it up if you're not interested.

---

One last thing I'd like to prime a future conversation with Rich and this is about a new resource and what I think could turn into a very valuable global resource for all JS / TS developers. This is related to creating API documentation from generated TS declarations. The one thing that has always irked me is that there is no definitive API docs for the TS built-in libs. When you link to any symbol from the built in DOM / ES / WebWorker libraries there is no where to go in your generated project API docs. Our IDEs use the built-in libs, but it would be great to have a global resource of 1:1 API docs for the TS built-in libs to link to. Even cooler is that I include the WebGPU / WebCodec / WebXR declarations / APIs in the docs as these are important APIs available now / imminently for the modern web.

I have spent a month building a customized TypeDoc project that creates complete API docs for the TS built in libraries and even cooler I provide a web component that provides buttons that cross-link all symbols to MDN and related TC39 specifications from the @mdn/browser-compat-data. There also is a TypeDoc plugin that associates all symbols from the built-in libs used in JSDoc when generating API documentation for any project.

This is why I spent a lot of time working on a way to reduce the disk space utilization of standard TypeDoc output. I accomplish this through some neat tricks with Svelte. For instance the 2400 page DOM API docs goes from 1.4GB to 140MB putting it in reasonable range for a hosting company to perhaps be willing to host it as a global resource.

I'm not looking for any immediate response as I'll be finishing this off in the coming 1-2 weeks. I will put it up on Github pages and make an overview video, but if it takes off I'll hit the 1GB cap on GH pages quickly. It would be great to have you take a look at this when it goes up as Vercel could be a great organization to host said docs for the global dev community. Outside of your potential contact to take a look at this I'll be cold emailing / calling various orgs.

---

I'll drop you an email early next week to follow up. If there is no further points of discussion to be had on this issue it can be closed.