Repository: TypeScript
Issue: Nested application of "typesVersions" mappings
Labels: Suggestion,Awaiting More Feedback

# Suggestion / Bug Report

<!--
  Please fill in each section completely. Thank you!
-->

This is a combination bug/FR. I'm not sure if some other TypeScript setting can solve this problem.

## 🔍 Search Terms

<!--
  💡 Did you know? TypeScript has over 2,000 open suggestions!
  🔎 Please search thoroughly before logging new feature requests as most common ideas already have a proposal in progress.
  The "Common Feature Requests" section of the FAQ lists many popular requests: https://github.com/Microsoft/TypeScript/wiki/FAQ#common-feature-requests

  Replace the text below:
-->

- `typesVersions`

## ✅ Viability Checklist

<!--
   Suggestions that don't meet all these criteria are very, very unlikely to be accepted.
   We always recommend reviewing the TypeScript design goals before investing time writing
   a proposal for ideas outside the scope of the project.
-->
My suggestion meets these guidelines:

* [?] This wouldn't be a breaking change in existing TypeScript/JavaScript code
    - (_I'm not sure_, though I think the risk is low.)
* [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/Bug

It seems like `typesVersions` in package.json can only influence the root declarations that are loaded for a package. It would be helpful if it could also map paths deeper within the type module graph. The [TypeScript 3.1 Release Notes introducing `typesVersions`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-1.html#version-selection-with-typesversions) say that "if you’re familiar with path mapping today, it works exactly like that." However, tsconfig.json `paths` can remap import paths anywhere within the project's own module hierarchy. This is why I say it's also a bug, because in my mind the documentation suggests that `typesVersions` is capable of something it isn't.

The [Publishing page](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html#version-selection-with-typesversions) on the TypeScript docs doesn't include that language, but it's also not the first thing that comes up when you search for "typescript typesVersions".

I've put together a quick [repro repository](https://github.com/willmtemple/typesversions-repro) on my GitHub account that illustrates this.

## 📃 Motivating Example

<!--
  If you were announcing this feature in a blog post, what's a short explanation that shows
  a developer why this feature improves the language?
-->

Currently, if your package provides type __declarations__ that export a set of declarations from a nested module, it is troublesome for library authors to provide differing type definitions of nested-module for users of older TypeScript versions without providing completely separate root declaration files:

```typescript
// /my-root-package.d.ts

export declare function doSomething(): void;

// If this file is the root of my declarations, then there's no way to remap just the
// contents of the following import for older TS versions
export * from "./nested-module/latest/index.d.ts";`
```

With nested application of `typesVersions`, an entry in the package.json `typesVersions` field can apply to this import in the declarations and remap it when the compiler loads the types:

```javascript
{
  // ...
  "typesVersions": {
    "<3.6": {
      "nested-module/latest/*": ["nested-module/3.1/*"]
    }
  }
}
```

This nested application of `typesVersions` mappings will be used when the declaration file for a package is a module (contains `import` or `export` statements).

## 💻 Use Cases

<!--
  What do you want to use this for?
  What shortcomings exist with current approaches?
  What workarounds are you using in the meantime?
-->

In the Azure SDK for JavaScript, we're building isomorphic libraries, and we don't want to assume that consumers of our APIs have DOM types loaded in their project, so we use DOM types in our compilation, but only provide empty shims for the DOM types that appear in our public API surface (we may have a method that optionally consumes `RequestInit` for example). We also use the following stack to manage our type declarations:

- api-extractor (for d.ts-rollup, allowing us to ship declarations of only our public API surface area)
- downlevel-dts (to allow us to support older versions of typescript without support for things like getters/setters)

We emit our rolled-up types into `types/latest/<package>.d.ts` for newer versions of TS and `types/3.1/<package>.d.ts` for TS older than 3.6. The best way we've found to tie all of this together with our shims is to create a hand-written declaration module that declares the interface shims we need into the global scope, and then re-exports our actual API types, like the following:

```typescript
// /core-rest-pipeline.shims.d.ts

declare global {
  // These shims can be overridden if a consumer loads lib.dom.d.ts
  interface FormData {}
  interface RequestInit {}
  // etc.
}

export * from "./types/latest/core-rest-pipeline.d.ts";
```

This allows Node consumers to use our libraries without lib.dom.d.ts. However, because `typesVersions` can only influence the selection of the root type declaration file, we have to provide this shim twice and use `typesVersions` to remap the shim file. It's a small nuisance, but a nuisance nonetheless that we can't just remap the import within a single shim file.