microsoft / microsoft/TypeScript

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

Open
#61,651 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Awaiting More Feedback Suggestion
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.