Repository: TypeScript
Issue: request: add accompanying `importsNotUsedAsValues` option for declaration imports
Labels: Suggestion,Awaiting More Feedback

# Suggestion

I'm looking for the ability to instruct the compiler to preserve imports as 'side-effecting' for declaration files. I'm framing this request in terms of the existing `importsNotUsedAsValues` option for sake of clarity but this is for declarations only. 

I suspect it may require a new accompanying option to `importsNotUsedAsValues` called, .e.g., `declarationImportsAsSideEffects`


## 🔍 Search Terms

 - declarations side effect
 - importsNotUsedAsValues declarations
 - import side effect declarations

## ✅ Viability Checklist

* [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
* [x] This wouldn't change the runtime behavior of existing JavaScript code
* [x] This could be implemented without emitting different JS based on the types of the expressions
* [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).


## ⭐ Suggestion

Based on the existing `importsNotUsedAsValues` behaviour, imports are emitted to `.js` to varying degrees. This proposal would ensure that there are accompanying imports within emitted `.d.ts` files to the same degree. For imports that are value-only and preserved, a "side effecting" `import './a-module'` would be emitted; others would remain as is

## 📃 Motivating Example

```
// plugins/my-plugin.ts
declare global {
  export interface AppPlugins {
    myPlugin: {some: 'value'}
  }
}

export default function() { ... }
```

```
// plugin-loader.ts

declare global {
  export interface AppPlugins {
    corePlugin: {some: 'otherValue' }
  }
}

import myPlugin from './plugins/my-plugin'
// import './plugins/my-plugin'.   <---- currently required

const plugins: Plugin[] = ...
export default plugins
```

Compiling yields (tested 4.3.2 with `importsNotUsedAsValues='preserve'`)
```
// plugin-loader.d.ts

declare global {
  export interface AppPlugins {
    corePlugin: {some: 'otherValue' }
  }
}

// import './plugins/my-plugin'  // <---- would be emitted with proposed change

declare const plugins: Plugin[];
export default plugins;
```

Currently, if another module were to import `plugin-loader`:

```
// app.ts
import plugins from './plugin-loader'

type PluginNames = keyof AppPlugins  //  'corePlugin'
```

Note that the augmentation type (global/module) doesn't matter, just that they're included

## 💻 Use Cases

  - What do you want to use this for?
  Enable plugin architectures where augmentations can be reliably expected to have been reached
  
  - What workarounds are you using in the meantime?
  "Shadow" [side-effect imports](https://www.typescriptlang.org/docs/handbook/modules.html#import-a-module-for-side-effects-only) to ensure declarations include `import`
  
  What shortcomings exist with current (workaround) approach?
  - Redundant, confusing to new eyes etc. In my particular use case where such code will be authored by plugin creators, any decreased DX is particularly unappealing. Worth mentioning that any missed shadow import in the chain would lead to the augmentation going unnoticed so this workaround would snowball