Proposal: Export multiple, runtime-specific declaration files

Chưa có ai nhận issue này.

### 🔍 Search Terms

export "multiple declaration file" "node bun deno" "custom conditions"

### ✅ 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 isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
- [x] This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

### ⭐ Suggestion

The feature request is to, as a library publisher, have capabilities to export multiple declaration files for each supported runtime/platform.

Consumers also need capabilities to choose which declaration file should be used by their compilation process.

With the proliferation of JavaScript Runtimes other than Node.js such as Bun, Deno, Bare and Cloudflare Workers, libraries will tend to be more and more agnostic or “multi-runtime”.

Each platform has slightly different Type dependencies, they may have different names, is also possible that they may have different ways to be imported.

**Suggestions for exporting multiple versions:**

Using the package.json's `exports`:

```json
{
"name": "my-package",
"version": "1.0.0",
"exports": {
".": {
"types": {
"bun": "./index.bun.d.ts",
"deno": "./index.deno.d.ts",
"default": "./index.d.ts" // node.js typings
},
"default": "./index.js"
}
}
}
```

Similar alternative using `imports` as in https://nodejs.org/api/packages.html#subpath-imports:

```json
{
"name": "my-package",
"version": "1.0.0",
"exports": {
".": {
"types": "./index.d.ts" // which would import '#types'
"default": "./index.js"
}
},
"imports": {
"#types": {
"bun": "./index.bun.d.ts",
"deno": "./index.deno.d.ts",
"node": "./index.node.d.ts"
}
}
}
```

Alternative that reuses `typesVersions`, but using custom conditions as keys:

```json
{
"name": "package-name",
"version": "1.0.0",
"types": "./index.d.ts",
"typesVersions": {
"bun": { "index.d.ts": ["index.bun.d.ts"] },
"deno": { "index.d.ts": ["index.deno.d.ts"] },
}
}
```

---

**Suggestions for consuming a specific version:**

My first suggestion is to reuse the `types` option feature to also trigger the proposed conditional mechanism defined at `package.json`.

```json
{
"compilerOptions": {
"types": ["deno"]
}
}
```

Another alternative is to use reuse the `custom conditions` feature to also trigger the proposed conditional mechanism:

```json
{
"compilerOptions": {
"customConditions": ["deno"]
}
}
```

### 📃 Motivating Example

A practical example is: https://github.com/mafintosh/streamx/pull/123, `streamx` supports Node.js and [Bare Runtime](https://github.com/holepunchto/bare), and here are two versions of the same library that I'd like to expose both:

https://github.com/yassernasc/streamx/blob/17526106a3bd11fd177f9ce62250c19577f4ab64/index.bare.d.ts

https://github.com/yassernasc/streamx/blob/17526106a3bd11fd177f9ce62250c19577f4ab64/index.node.d.ts

### 💻 Use Cases

1. What do you want to use this for?

As a library publisher, I want consumers to have realistic typings whenever is the supported runtime consuming the library.

2. What shortcomings exist with current approaches?

I have not found a direct solution to the problem.

3. What workarounds are you using in the meantime?

I've been writing a minimal `runtime.d.ts` declaration file that defines a minimal subset that all covered runtimes implement. This approach duplicates preexisting typings from the runtimes typings, however, the `runtime.d.ts` file tends to be unmaintained and outdated in the long run, plus, adds unwanted noise to the repositories.

Bắt đầu bằng việc xem xét các ví dụ về exports, imports và typesVersions trong package.json, cùng với các tùy chọn compilerOptions và customConditions được nêu trong issue. So sánh các đường dẫn được đề xuất để lựa chọn tệp khai báo và ví dụ động lực streamx. Công việc được xem là hoàn tất khi đã thống nhất thiết kế và kế hoạch triển khai cho việc phát hành và sử dụng các khai báo dành riêng cho runtime.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.