Add option to detect and strip internal exports

🔍 Search Terms

• “detect internal”
• “stripInternal”

✅ 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

I would like TypeScript to be able to detect unused exports and strip them. Most packages define and import and export types that are for internal use only. If package.json has the exports field, TypeScript knows which parts are part of the public interface.

📃 Motivating Example

Let’s say you have the following files:

// package.json
{
  "exports": "./dist/index.js"
}

// tsconfig.json
{
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  }
}

// src/index.ts
import { internalFunction, PublicType } from './internal.js'

export { PublicType }

export function publicFunction(): PublicType {
  return internalFunction({ internal: true })
}

// src/internal.ts
export interface PublicType {
  public: boolean
}

export interface InternalType {
  internal: boolean
}

export function internalFuncion(argument: InternalType): PublicType {
  return { public: true }
}

TypeScript emits the following type definitions:

// dist/index.d.ts
import { PublicType } from './internal.js'

export { PublicType }

export function publicFunction(): PublicType;

// dist/internal.d.ts
export interface PublicType {
  public: boolean
}

export interface InternalType {
  internal: boolean
}

export function internalFuncion(argument: InternalType): PublicType;

With the option detectInternal, TypeScript omits types that aren’t needed for the public interface. Instead of the above, TypeScript would emit:

// dist/index.d.ts
import { PublicType } from './internal.js'

export { PublicType }

export function publicFunction(): PublicType;

// dist/internal.d.ts
export interface PublicType {
  public: boolean
}

💻 Use Cases

I want to use this option for libraries. Libraries often have such internal exports that are not relevant to the user. These often include types that are imported from other libraries. If TypeScript strips unused exports while compiling a library, it has to load fewer files and process fewer types when a user consumes this library.

Currently a library author can use the stripInternal option and @internal JSDoc tags. This means the author has to manually find and tag internals. This is error prone. It can lead to both false positive and false negative internal markings, without TypeScript complaining.

Start by reviewing declaration output for the package.json exports field, the tsconfig.json compilerOptions, and the existing stripInternal behavior described in the issue. Compare the emitted declarations for src/index.ts and src/internal.ts with the proposed output. Done means an option can detect types not needed by the public interface and omit them without changing runtime JavaScript.