Flattening types in generated .d.ts files for libraries

🔍 Search Terms

"delcaration readable" "declaration pretty"

✅ 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

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

// 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, however, when building the declaration files, the compiler will generate the flattened version like this

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

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.

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.

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

💻 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

Start by reviewing the proposed inline modifier, its alternative type-level form, and the Prettify workaround described in the issue. Define the semantics for flattening computed types in generated .d.ts files, including how intersections, unions, and Omit behave. Done means a complete proposal with clear behavior and an implementation path.