[Advice] JSDoc types questions from maintainers' perspectives

[chrisrzhou]

Hey unified/mm team!

I have been personally inspired by the maintainers on mindfully when authoring libraries without committing deeply to TS.

I understand the general principles for using JSDoc-based TS typings.

• TS, while being a superset of JS, is not part of the JS standard. Things can and will change, and the cost to rewrite should be considered (history of JS innovations should be a guidance e.g. coffeescript, flow, babel etc). In general, if code is simply JS, then all is good.
• TS should be viewed as a developer tool to aid development. It should not impact how source code is written (and I've caught hints at how the maintainers mindfully considered this since compiled TS code maybe larger or simply change the intended way the code would be expressed).
• JSDoc is an agnostic documentation solution that plays well with TS but provides open paths in the future to either fully adopt or abandon TS. Docs are still retained without source code changes, which is great.

My discussion post is to mainly ask for advice from the team on a few things that JSDoc-based typing does not seem to sit well with the principles above:

1. If our goal is to truly decouple from TS, I think this is either challenging or near-impossible.

• For example, I find myself not being to avoid TS-specific syntax in JSDocs in many occasions due to the limitations of JSDocs authoring more complex types (example).
• Does the team accept such situations in favor of pragmatism over principles?
• Is it at odds with the goal of decoupling from TS in the first place?
• What techniques does the team use to prevent "TS-spill" in JSDoc syntax? Just code reviews?

2. How do the maintainers think about semantic versioning with respect to TS types?

• Does the team consider exported types as part of the public interface?
• If a future version introduced only type changes but no source code changes, does the team consider that as a major or minor/fix?
• My opinions lead me to think type changes should be minor/fixes as the project seems to lean on being exposed primarily as a JS package with TS types as a convenience for the TS community.

3. Both 1. and 2. have led me to a dilemma if I should continue this explicit goal of separating types from JS source code via JSDocs. I like many parts about this explicitness but I find myself struggling to see how this purely creates the separation (see 1.). JSDocs with this approach is still fundamentally TS-driven if 1. is not cleanly enforced.

Thank you so much for your time. Been passively learning from many of you, but figured I'll actively seek some help and get into your mindspace on this topic :)

[ChristianMurphy]

TS, while being a superset of JS, is not part of the JS standard. Things can and will change, and the cost to rewrite should be considered (history of JS innovations should be a guidance e.g. coffeescript, flow, babel etc). In general, if code is simply JS, then all is good.

Exactly.
I'd add that there is complexity, compatibility, and maintenance overhead to compiling/transpiling/bundling code.
If that can be avoided, for example if https://github.com/tc39/proposal-type-annotations becomes standard, we may leverage that syntax.

JSDoc is an agnostic documentation solution that plays well with TS but provides open paths in the future to either fully adopt or abandon TS. Docs are still retained without source code changes, which is great.

Yes, though I'd note the caveat that it is not entirely agnostic.
JSDoc doesn't natively have syntax for higher order type logic (generics) fully fleshed out.
So there can be small areas of TypeScript specific syntax to capture some of those more dynamic areas.

If our goal is to truly decouple from TS, I think this is either challenging or near-impossible.

The goal isn't to entirely decouple, it is mostly to avoid compilation/transpiling/bundling.
It seems that a lot of these build tools and compilers have been optimized for applications, rather than libraries.
In an application context, one doesn't need to worry about:

1. "will this work with other build tools?"
2. "can I use this on node without a build tool?"
3. "can I run off/test a pre-release version not on npm yet?"

Which are three common considerations micromark/unified faces (among many others).
Plain JS offers a path to all three through:

1. Build tools should already support plain JS, if they don't that is a bug in the tool, not the library
2. Plain JS works fine on node without a custom loader
3. Plain JS can be npm/yarn/pnpm installed directly from git to try out features before an official release

For example, I find myself not being to avoid TS-specific syntax in JSDocs in many occasions due to the limitations of JSDocs authoring more complex types

It happens, both with non-standard JSDoc, and there are some things which cannot be represented in JSDoc syntax at all, and a handwritten .d.ts file needs to be included. For example:
https://github.com/unifiedjs/unified/blob/144eec01b0e1faa23655359d61c3749ad2af99e7/index.d.ts#L31

Does the team accept such situations in favor of pragmatism over principles?

Taking a step back, I'd personally articulate the principles as: (* other maintainers may articulate these differently)

1. Code can run directly in node (no custom transpiler/loader)
2. Valid uses of the library shows as valid in TypeScript/LanguageServer
3. Invalid uses of the library should show a type error
4. 100% type coverage
5. Stick as close to JSDoc as possible

When/where there is a conflict between them 1 takes precedence over 2, 2 takes precedence over 3, etc.

So far I'd say that has been pragmatic enough.

What techniques does the team use to prevent "TS-spill" in JSDoc syntax? Just code reviews?

Mostly code review.
Some small areas are also covered by ESLint/XO during the lint checking phase of the test suite.

Does the team consider exported types as part of the public interface?

Type which are exported AND documented in a types section of a readme.md file.
JSDoc/TypeScript can tend to accidentally/incidentally export types which are part of the internal interface.
Which can cause confusion like syntax-tree/unist-util-map#6.
We've been moving towards having a separate lib folder for internals, to make it clearer which interfaces are internal and which aren't https://github.com/search?q=org%3Asyntax-tree+move+core+to+lib&type=commits but that isn't in every project yet.

If a future version introduced only type changes but no source code changes, does the team consider that as a major or minor/fix?

That goes case by case, usually semver patch/fix.
Which would include cases like:

• Supporting a valid usage of the library which is mistakenly throwing a type error
• Fixing messaging around an invalid usage of the library, which is missed by type checking

The only major we've had so far is occasionally dropping support for an older version of TypeScript, to enable accurate type checking.

[chrisrzhou]

Thank you so much @ChristianMurphy for the detailed response. I'll spend time going over it carefully.

This helped me understand the goals of the unified maintainers, and for me to make my appropriate calls on my own projects:

The goal isn't to entirely decouple, it is mostly to avoid compilation/transpiling/bundling.

I'm assuming if compilation became increasingly optimized (i.e. theoretically if the compiler would always outperform the human decisions), the only reason to not use TS natively would likely be a subjective project decisions (e.g. the set of tools needed for the project, considering how multiple developers would maintain the project forward, considering and limiting dev deps).

[chrisrzhou]

On a separate note,

I chanced upon tsdoc and was musing on how this would be more inline with projects that wish to remain JS-first and leverage JSDocish tools for documentation and TS for typings. There are a few gaps that make tsdoc be a good fit for such projects:

• it seems to only support TS source files and not JS files.
• it does not seem to be a superset of JSDoc (a shame given the approach that TS is a superset of JS), which would limit its natural adoption for JS-based projects.

Once those gaps are filled, I think it would make for a more natural use case instead of tweaking/mixing JSDoc and TS support (either domain seems to be lacking full support of the other which makes for some awkward doc/type-gen experience).

[ChristianMurphy]

I'm assuming if compilation became increasingly optimized (i.e. theoretically if the compiler would always outperform the human decisions), the only reason to not use TS natively would likely be a subjective project decisions (e.g. the set of tools needed for the project, considering how multiple developers would maintain the project forward, considering and limiting dev deps).

Sorry, I'm not sure I follow.
TypeScript is not optimizing compiler, nor am I aware of any plans to make it one.
All optimization is done by the JS runtime itself (V8 for Node and Deno, JavaScriptCore for Bun).
The only things TypeScript can do in its current state are: leave the performance the same, or add performance overhead.

I chanced upon tsdoc and was musing on how this would be more inline with projects that wish to remain JS-first and leverage JSDocish tools for documentation and TS for typings. There are a few gaps that make tsdoc be a good fit for such projects:

Do you mean generating markdown documentation from typings?
There are some JSDoc alternatives like: https://github.com/jsdoc2md/jsdoc-to-markdown

Or if you mean generating a documentation site from JSDoc based TypeScript annotations, I believe https://github.com/TypeStrong/typedoc can already do that.

[chrisrzhou]

The only things TypeScript can do in its current state are: leave the performance the same, or add performance overhead.

That helps answer my question, thank you.

Do you mean generating markdown documentation from typings?

My comment was probably not clear. The point was that JSDoc-generated TS typings suffer from a slight conundrum of "decoupling usage and goals of either framework" (e.g. "we can keep JSDocs if we decide to drop TS"). The current state cannot be fully decoupled cleanly as the way JSDoc is used is still influenced by TS. If tsdoc was a strict superset of JSDoc and also aids in the deliberate goal of generating TS types, then I can see that being an attractive alternative to JSDoc as one does not need to deal with non-interoperable (lacking features) on either JSDoc or TS.

But the comment is mostly observational and has no real value as tsdoc is not a strict superset of JSDoc, and you helped confirm the maintainer's mindset towards this problem relates less with "decoupling from TS" and more with avoiding build tools and chain.

[JounQin]

Can we just have a src folder with TS codes but compiles into lib as .js and .d.ts files in git repo at the same time? Jsdoc based TypeScript is really non-intuitive if we want to maintain such large scale of libraries.

[ChristianMurphy]

Your question seems tangential to the original post?
It would likely warrant its own discussion or RFC.

Also be aware, that it's been discussed few times in the past, and the outcome of previous discussions have been: no.
Not until https://github.com/tc39/proposal-type-annotations or another similar proposal to the JavaScript standard becomes official.
Removing the need for compilation, and allowing the code to function without the TypeScript toolchain.