Export `node-utils` from package.json

[typhonrt]

Before you lock down TypeDoc for the TSGO7 upgrade...

I have a small request for a custom deployment of TypeDoc where I have some advanced use cases that benefit from access to the runtime node utilities. I need to access discoverAllReferenceTypes. For programmatic deployments it may be useful to simply expose node-utils similar to how the browser-utils has an export of typedoc/browser. This can be accomplished simply by adding the proper sub-path export condition to package.json

{
   "exports": {
      "./node": {
         "typedoc-ts": "./src/lib/node-utils.ts",
         "types": "./dist/types/node-utils.d.ts",
         "default": "./dist/node-utils.js"
      }
   }
}

This allows:

import { discoverAllReferenceTypes } from 'typedoc/node';

At the end of the day... I can simply modify the package.json after TypeDoc installation into my specific project to add the above, but I think this is generally useful for more advanced programmatic use cases in general.

---

Also just a quick thing I noticed when looking at this enhancement request.. It appears the browser export condition for typedoc-ts is not pointing to the source. IE "typedoc-ts": "./src/lib/browser-utils/index.ts" likely should be "typedoc-ts": "./src/lib/browser-utils.ts", as there is no ./src/lib/browser-utils folder in the latest repo update that I see.

[Gerrit0]

I definitely do not want to export all of node-utils. There is a ridiculous amount of API surface area there which is not intended to be public, and has had no thought towards whether it is appropriate to expose. Several exports in that module are only exported for ease of testing, and aren't even intended for use outside of their module (e.g. splitGlobToPathAndSpecial)

That said, for specific functions that are useful, I'm open to exporting them after consideration of their API. discoverAllReferenceTypes in particular having a forExportValidation boolean parameter is not very friendly for external use, I'd rather export something with the signature (project: ProjectReflection, options: { includeHeritageClauses?: boolean }) => ...

Good catch on the typedoc-ts export! That export is never used in testing apparently, which is the only place where it is intended for use, so it's not a major issue, but would be good to fix.

[typhonrt]

Yeah.. It is a very particular use case on my side for needing discoverAllReferenceTypes. Certainly understood that a barrel / export of all of that node side code is not the best solution. I haven't updated TypeDoc on my larger custom doc generation project and / or kept it locked to 0.28.14; which isn't great in the long term. Whenever you added the tighter package.json exports conditions this bare import is prevented... It's a custom resolver plugin well doing custom things; it works great, but using private API.

[Gerrit0]

The package.json exports have been like that for years at this point, I added export conditions in 2021. Your import with a relative path didn't treat typedoc as a package, so happened to still work. Your workaround could change to work around the bundling that TypeDoc now does to improve startup performance:

-import { discoverAllReferenceTypes }   from '../../../node_modules/typedoc/dist/lib/utils/reflections.js';
+import { discoverAllReferenceTypes }   from '../../../node_modules/typedoc/dist/node-utils.js';

I'd be fine with exporting the discoverAllReferenceTypes function, potentially as a method on ProjectReflection? The time I have for TypeDoc is already going towards the native support, I'm hoping to begin working on burning down deltas after this weekend, 330 compiler errors left... TypeDoc will also likely end up needing some architecture work to try to reduce the number of round trips done over IPC for performance, I can't run anything yet, but I'm concerned with the number of calls it looks like it will make

[typhonrt]

Oops.. Indeed, just a change in path. Just moving a bit too quick on the edge of all of my current efforts to keep track of some of the internal shuffling inside TypeDoc / path changes; found it, but also assumed the exports conditions triggered it at the same time. ;) discoverAllReferenceTypes is helpful in my use case, so it and maybe a few other Node side util methods could eventually be exposed for custom TypeDoc plugin use cases.

Good luck on the TSGo7 efforts. My understanding is that 7.1 is supposed to have a stable programmatic API. Not sure if it is worth trying to rush that aspect of compatibility until it arrives. ~October for the generally scheduled stable and I know that is a pretty big gap with folks clamoring for support. I too have a bunch of TSGo7 upgrade work to do on esm-d-ts, but waiting for 7.1 before even considering it.

Too bad that discussion thread for the DMT doesn't post pings in GitHub. I'm still keeping the the DMT up to date with TypeDoc. Still working on the Svelte 4 -> 5 transition on my side pending completion of my larger framework. Once things stabilize post TSGo7 update for TypeDoc perhaps we can start investigating that angle again. I should be ready post TS 7.1 / TypeDoc support.

Good luck!