feat: improve declaration merging resolution

[jorroll]

Search Terms

declaration merging imported interface

Suggestion

this is an extension of #33326 and this S.O. issue

At the moment, declaration merging requires you to specify the original file that an interface was declared 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'

You cannot currently perform declaration merging using the following

// file_a.ts

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

The problem appears to be that @rschedule/core is re-exporting DateAdapterType. Instead you must do

// file_a.ts

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

This is problematic because the original location of the DateAdapterType is private to the @rschedule/core module.

This is a feature request to let developers use declaration merging via

// file_a.ts

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

Use Cases

The ability to better encapsulate modules and only exposing interfaces via a single point. The current API seems to require that module type declarations are flattened in some way and declared directly in @rschedule/core/index.d.ts. This necessitates a special build setup. I'm not immediately clear on how I can satisfy the current API, practically speaking.

Developer happiness. I would assert that this feature request would make typescript more intuitive, as the current design limitation requires knowledge of the typescript implementation (i.e. the current design doesn't seem to make any logical sense, other than, perhaps (?), for performance reasons).

Examples

shown above

Checklist

My suggestion meets these guidelines:

• [?] This wouldn't be a breaking change in existing TypeScript/JavaScript code

  • I'm not sure if this would be a breaking change. Is it possible that a module is relying on the current behavior? I don't think so, but maybe someone from the community can pipe up and say otherwise. I think this is a non-breaking change though, as I view the current behavior as a bug.

• 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.

[RyanCavanaugh]

We can't do this because it would change the semantics of existing programs in very problematic ways. Declaration merging with modules is difficult and I think there's room for improvement in terms of making it easier to augment existing modules, but this isn't a possible path forward.

[jorroll]

I'd be happy with anything that addresses the spirit of the proposal / improves the ergonomics of declaration merging with modules.

Simply improving the documentation in this area (#33326) would be a big help though.

[typescript-bot]

This issue has been marked 'Working as Intended' and has seen no recent activity. It has been automatically closed for house-keeping purposes.