microsoft / microsoft/TypeScript
Support the `@private` JSDoc directive to exclude private APIs from emitted type declarations
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 111k
- Forks
- 14.3k
- Avg merge
- 2d 4h
- Merged PRs (30d)
- 132
Description
### 🔍 Search Terms
"private jsdoc"
### ✅ Viability Checklist
- [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
- [x] This wouldn't change the runtime behavior of existing JavaScript code
- [x] This could be implemented without emitting different JS based on the types of the expressions
- [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
- [x] This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
- [x] 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`](https://jsdoc.app/tags-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`](https://jsdoc.app/tags-access) as well.
> Private members are not shown in the generated output…
>
> — https://jsdoc.app/tags-access
### 📃 Motivating Example
I maintain a [svgo](https://github.com/svg/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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the motivating JavaScript/JSDoc case from svgo with TypeScript declaration emission. Define how @private and possibly @access private affect emitted declarations, including errors for exported or signature-referenced symbols, and determine whether an opt-in option is needed for compatibility.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, typescript
- Domain
- compilers
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 28/100