RFC: @internal by default #49077

⭐ 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.