Support the `@private` JSDoc directive to exclude private APIs from emitted type declarations

🔍 Search Terms

"private jsdoc"

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

Could properties, functions, and classes annotated with the @private JSDoc directive be omitted from the emitted declarations?

tsc should throw an error if a symbol is marked as @private, but is actually imported/exported from another declaration file or used in the signature of another symbol like a function parameter or return type. (And therefore isn't actually an internal API.)

I'm wary this may break some projects if implemented without an opt-in, so it may require an option to enable this behavior, to preserve backward compatibility.

Source

The @private tag marks a symbol as private, or not meant for general use. Private members are not shown in the generated output…
…
The @private tag is equivalent to @access private.

— https://jsdoc.app/tags-private

Based on this, it may be worth also doing it for @access private as well.

Private members are not shown in the generated output…

— https://jsdoc.app/tags-access

📃 Motivating Example

I maintain a svgo, a library that is written in JavaScript and typed with JSDoc directives, and uses tsc to emit declaration files.

As a library normally has an intended public API, afaik there's no need to distribute type declarations for the internal API.

💻 Use Cases

This is just to reduce the amount of type declarations served to developers if they aren't needed, reducing the size of the package on npm a little.

No workaround is currently needed, assuming the project is a module that uses exports rather than main, as we can limit the public API ourselves. The extra types do not cause any harm, it just makes the final package a little bigger.

For projects that use main instead of exports in their package.json, this may leak more private APIs that end-users may accidently consume and believe to be part of the public interface.

首先使用 TypeScript 声明生成来复现 svgo 中作为动机的 JavaScript/JSDoc 案例。定义 @private 以及可能的 @access private 如何影响生成的声明，包括对导出符号或在签名中引用的符号报错，并确定是否需要 opt-in 选项来实现兼容性。