Repository: TypeScript
Issue: Flattening types in generated .d.ts files for libraries
Labels: Suggestion,Awaiting More Feedback

### 🔍 Search Terms

"delcaration readable" "declaration pretty"

### ✅ 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

Allow library authors to add the `inline` modifier on a type declaration which makes the compiler flatten the type in generated code.

An `inline` modifier for type declarations
```ts
// Strawman syntax

// Instead of this
type Foo = Bar & Baz | Omit<Bat, "x" | "y">

// The library author can write this
inline type Foo = Bar & Baz | Omit<Bat, "x" | "y">

type Bar = { foo: "b" };
type Baz = { bar: "c" };
type Bat = { x: "x"; y: "y"; z: "z"; a: "a" };

```
The compiler would mostly ignore the `inline` directive (it would behave similarly to the `Prettify` [helper type](https://www.totaltypescript.com/concepts/the-prettify-helper), however, when building the declaration files, the compiler will generate the flattened version like this

```ts
type Foo = {
    foo: "b";
    bar: "c";
} | {
    z: "z";
    a: "a";
}
```

Alternatively, instead of a modifier on a declaration, it can be a modifier we can add on types
```ts
type Foo = Inline<Bar> & Inline<Baz> | Inline<Omit<Bat, "x" | "y">>
```

Honestly, I'm not sure of the full semantics of `inline`. My mental intuition is based on the `Prettify` type helper.
```ts
type Prettify<T> = {
  [K in keyof T]: T[K];
} & unknown;
```

Alternatively, a tsconfig.json setting might also work. Although I'm sure to have the best experience, the compiler might need some feedback from the library author too.

Sorry if this isn't fully fleshed out, but I'm willing to work on a full proposal in case the team is open to the idea.

### 📃 Motivating Example

We have a lot of computed types in our design system library. Most (React) components can receive Theme defined props.

Here's a verbatim example which is our `Box` component, which is a design system aware `div`.

```ts
export type BoxProps = AsChild & ThemeProps & styles.SprinklesProps & React.HTMLAttributes<HTMLDivElement>;
```

This describes the type perfectly, but it leads to very poor DX for the callers. When someone Cmd-Clicks `Box`, they see a type which isn't really helpful when trying to figure out the API of `Box`.

What I'd like to see in the generated declarations would be something like the following
![Image](https://github.com/user-attachments/assets/b7bf04fc-cd9a-46a1-aaa6-f33bfff1ee09)


### 💻 Use Cases

1. What do you want to use this for?
    Improving the UX of our library consumers when there are computed types in the public API.
2. What shortcomings exist with current approaches?
    It's hard to understand the API of our library because cmputed types obscure the actual properties that are accepted by the types
3. What workarounds are you using in the meantime?
     We wrap certain public API types with the `Prettify` helper type so that the users can hover over certain types to received a flattened version of the type