RFC: @internal by default

[Jack-Works]

⭐ Suggestion

Today you can use @internal JSDoc tag and stripeInternals flag to erase private but exported APIs. It will be good to have a reversed option, that all exports are @internal unless they explicitly opt-out.

Option 1: @public JSDoc tag

If an export is commented with @public JSDoc tag, the declaration is emitted. Otherwise, treat it as @internal.

Example:

A/utils/index.ts

/** @public */
export const a = 1
export const b = 2

With stripeInternal: all, it emits the following declaration file:

export const a: number

Option 2: Entry files

Allowing to specify a set of entry files (or infer it from exports field of package.json).

If a type is not viable from one of the entry files, the type of it will not be emitted.

Example:

A/index.ts

export { A, B } from './utils'

With typeEntries: ["./index.ts"], only type referenced by A and B is emitted, all other declarations are treat as private.

🔍 Search Terms

internal by default declaration project reference

✅ Viability Checklist

My suggestion meets these guidelines:

• 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 feature would agree with the rest of TypeScript's Design Goals.

Add a new compiler option: stripeInternal: "all", and use @public JSDoc to allow the emit of declarations.

📃 Motivating Example

It will improve the protection of internal APIs.

[HolgerJeromin]

Is this something for https://api-extractor.com ?

[Jack-Works]

api extractor will benefit from it, but with only tsc there is also benefit (with stripeInternal flag)

[jakebailey]

Something like this might be useful for TS itself when converted into modules; without namespaces, you can't apply @internal to entire sections of code and instead have to explicitly mark everything.

[Knagis]

imo, @public is not a good candidate because it already has different meaning in classes (though in plain jsdoc it would mean exactly this). But the feature would be very nice to have.

[Knagis]

The problematic scenario is:

/** @public */
export class Foo {
    /** does this require @public? or does it require @internal if the class is exported but the field is not? */
    public bar;
}

[HolgerJeromin]

Terser and UglifyJS uses: "@license", "@preserve"