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.

Declaration Merging のハンドブックページ、特に module augmentation のセクションから始め、以前の議論については関連する issue #11406 を確認してください。報告されているファイル間および再エクスポートされたインターフェイスの動作をドキュメントに追加し、要求どおり What's New の内容にも追加してください。読者が、どのモジュールパスを拡張すべきか、そしてなぜ公開された再エクスポートパスが失敗するのかを理解できれば完了です。