Declaration emit should not inline type definitions

[mheiber]

TypeScript Version: 3.8.3, 3.8.1, probably others

Search Terms:

declaration inlining, dts inlining, declaration inline, inline literal, declaration literal

Code

// parent.ts
import { num, obj } from "./child"
export const reExportNum = num;
export const reExportObj = obj;

// child.d.ts
export declare const num: number;
export declare const obj: { a: 1 };

tsc index.ts --declaration

Expected behavior:

Declaration emit for parent.ts should not inline types.

// parent.d.ts
import { num, obj } from "./child"
export declare const reExportNum: typeof num;
export declare const reExportObj: typeof obj;

Actual behavior:

Today, declaration emit for parent.ts inlines the types and eliminates the import of the child.d.ts type definition.

// parent.d.ts
export declare const reExportNum: number;
export declare const reExportObj: {
    a: 1;
};

This is a correctness issue, because consumers of parent.d.ts will not get the correct types if the types in child.d.ts change.

In practice, this is most likely to happen when parent and child are in separate packages, because they are published independently, i.e. an application uses parent-package which uses types from child-package. This is exacerbated by the current practice on npm of parent-package depending on an unpinned version, using package.json dependency syntax "child-package": "*".

This issue was co-authored with @robpalme

[DanielRosenwasser]

What would you have TypeScript emit in the case of the following?

export const exportNumNum = num + num;

export const exportExtendedObj = {
  ...obj,
  someOtherProp: 200,
};

[mheiber]

Thanks for looking into this, @DanielRosenwasser . As your examples illustrate, there is a long tail of correctness issues in this area.

If examples like the one in the issue description are the common case, maybe it would be possible to solve them independently of the uncommon cases.

We have some ideas for how to deal with the less common cases and can open a separate issue for them if you think it's a good idea. Perhaps related: #29043.

[RyanCavanaugh]

There's a fairly fundamental tension here about what declaration emit means: Should declaration files represent the types as they existed when you compiled your program, or should they represent the types that a consuming library would have seen had your original program been compiled "in the context of" the consumer's setup?

This gets really mind-bending if you think about conditional types or overloads, e.g.

declare var x: SomeType;
export const c = func(x);

Is the intent here that c should have the type that you saw when you invoked func? Or if a consuming library augments SomeType in a way that changes the resulting type of func(x), should c have some other new type? What if that causes some other use of c to break a contract?

I think one of these behaviors is much easier to reason about than the other, as you can probably tell from my descriptions of them.

Anyway the example in the OP is also in tension with people who want their end-result .d.ts file to be a single-ish artifact that doesn't expose their entire program's internal structure. This is a good goal anyway for performance - it'd be much better if we load 1 file per library instead of 12, and better if we handle some inline anonymous types instead of resolving typeof queries everywhere.

[mheiber]

reply to #37151 (comment)

@RyanCavanaugh thanks for your response, I find your description of the two mental models really helpful: the "types are conceptually inlined" model vs. the "types always flow through" model.

I'm not sure the inlining is easier to reason about, given that "types flow through" is how .ts files work and is also similar to how the runtime works:

export { foo } from "./foo"; // re-exposes whatever is in ./foo

It also seems like the inlining model doesn't work for nominal types: it would lead to spurious type incompatibility errors. That's probably why TS currently does not inline nominal types.

So if the choices are:

• two mental models, one of which leads to runtime errors
• a single mental model in which types are correct

I'd choose the latter. Please let me know if this is a misleading way of stating the choices!

[mheiber]

I'm curious about this issue: is there a way to help progress this?

I could open a separate issue for @RyanCavanaugh 's more fundamental topic re the point of a declaration file.

[mheiber]

Following up on this issue: it's causing us some pain, so it would be good to have some guidance.

[RyanCavanaugh]

@mheiber have you tried with @next lately? We recently had some PRs go through that might improve the emit to more closely match your expecations.

[weswigham]

If you're thinking of #37444, that's still out for review.

[mheiber]

Thanks Ryan and Wes! I'll check out Wes' PR.

[mheiber]

Thanks for the recommendation. I tried #37444 and am not seeing a difference in the output for the example above.

[weswigham]

Yeah, didn't think it would - you're looking for everything to be represented with typeof queries and indexed accesses where possible, essentially. Which is just plain not something we even track the information to do right now.

Naturally, you can always just write the type annotations yourself if preserving that last bit of origin information is important (eg, because you expect augmentations somehow).

[mheiber]

@weswigham thanks for explaining. After looking at your related PR, I think I can see how the information is not currently tracked.

Regarding design (rather than implementation), the fundamental issue seems to me to be that declaration files are neither:

• fully dynamic: types always "flow through" from transitive dependencies, just like values flow through at runtime
• fully static: types are always fully inlined

I gave some reasons above why I see advantages to the dynamic model (#37151 (comment)). One of the most compelling reasons, in my opinion, is that it's the only way I can see that will work well with nominal types.

Am I understanding the design issue correctly?