About declaration merging for nodes from different files

[timocov]

The language documentation: https://www.typescriptlang.org/docs/handbook/declaration-merging.html

Generally it seems impossible to provide such support in any tool if symbols are located in a different files (because on the compiler level a different symbol is created for them and 2 different nodes are represented by different (almost) independent symbols). The tool tries its best to provide support where possible, but not all issues it is possible to solve.

⚠⚠⚠ Please don't use it. I'm begging you, do NOT use declaration merging! ⚠⚠⚠

TLDR: It is pailful to support it, and I decided that I'm not going to spend too much time on cases related to declaration merging. If it works for you - brilliant (but please make sure that you have control over what's generated and probably have diff tests to avoid regression). It if doesn't - you can create an issue but be ready that it will be closed as "won't fix".

---

An example of what doesn't work and most like will never work:

// index.ts
// this is also true for any other type of export
import { Foo as FooRenamed } from './types';

const FooRenamed = 2;

export { FooRenamed };

// types.ts
export interface Foo {}

The reason why it is not possible is because symbols FooRenamed (from index.ts) and Foo (from types.ts) might be used in multiple "declaration merging" cases in the same compilation thus the tool just can't rename one of the symbols so the compiler will perform "declaration merging" mechanism.

In the example above you'd probably get something like:

// output.d.ts
interface Foo {}

export declare const FooRenamed = 2;
export {};

which is not correct output. Lets say the tool fixes names and you get the following:

// output.d.ts
interface Foo {}

declare const Foo = 2;

export { Foo as FooRenamed };

export {};

(note that the tool renamed const FooRenamed to const Foo)

But then you change index.ts to this:

// index.ts
import { Foo as FooRenamed, Foo as Bar } from './types';

const FooRenamed = 2;
const Bar = 2;

export { FooRenamed, Bar };

Without adding extra nodes (extra type to rename the interface Foo, or const Foo or const Bar) it is not possible to generate the correct output. Adding extra nodes (especially ones that are "valuable" like constants) means to affect what a user actually have and I don't think that this tool should do that.