docs: clarify declaration merging behavior

Search Terms

declaration merging imported interface module declaration merging

related issue #11406

Suggestion

This is a docs improvement request

As I found via some helpful feedback on Gitter, in response to this S.O. issue, in order for declaration merging to work across multiple files, all subsequent declarations (after the first) need to specify the original file that the declared interface was created in.

For example, given a module @rschedule/core with the following files

// @rschedule/core/es2015/packages/core/core/date-adapter

export interface DateAdapterType {
  base: DateAdapterBase;
}

// @rschedule/core/index.ts

export * from './es2015/packages/core/core/date-adapter'

this does not work work (though I think it is reasonable to expect that it would):

// file_a.ts

declare module '@rschedule/core' {
  interface DateAdapterType {
    one: string;
  }
}

// file_b.ts

import { DateAdapterType } from '@rschedule/core';
import './file_a';

function test(date: DateAdapterType) {
  date.base; // should be type `DateAdapterBase` but instead errors that `.base` doesn't exist
  date.one; // is type `string`
}

This fails because @rschedule/core is re-exporting the DateAdapterType interface. The following works

// file_a.ts

declare module '@rschedule/core/es2015/packages/core/core/date-adapter' {
  interface DateAdapterType {
    one: string;
  }
}

// file_b.ts

import { DateAdapterType } from '@rschedule/core';
import './file_a';

function test(date: DateAdapterType) {
  date.base; // is type `DateAdapterBase`
  date.one; // is type `string`
}

This existing API for declaration merging is problematic because the true location of the DateAdapterType interface within @rschedule/core is private to the module and could theoretically change between releases. Longer term, I'd like to see this implementation issue within typescript fixed (#33327), but in the immediate term a docs update could save future folks some pain.

I'll note that I was only able to eventually figure out what was going on via #11406 from 2016. As @MoonStorm sagely put it in a comment at that time to clarify this documentation.

Could you please update the docs with this example, in the module augmentation section as well as in what's new ? Nobody is going to augment rxjs's Observable straight in the external module's own folder.

Use Cases

Developer understanding and happiness

Examples

Checklist

My suggestion meets these guidelines:

• 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, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

Start with the Declaration Merging handbook page, especially the module augmentation section, and review related issue #11406 for the earlier discussion. Add the reported cross-file and re-exported-interface behavior to the documentation and, as requested, the What's New material. Done means readers can understand which module path to augment and why the public re-export path fails.