microsoft / microsoft/TypeScript

Support `@deprecated` marker on namespace aliases

Ouverte
#62,340 0 commentaires 1 réaction 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

Domain: JSDoc Help Wanted Possible Improvement
Langage dominant
Go
Étoiles
111k
Forks
14.3k
Merge moyen
2 j 4 h
PR mergées (30 j)
132

Description

### 🔍 Search Terms

"@deprecated", "deprecated", "namespace", "namespace alias"

### ✅ 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

Note: Marking this as a feature request, very well might be a bug. It's one of those that are probably up for interpretation?

---

I'd like the ability to annotate namespace aliases with `@deprecated`. At the moment you'd need to mark the referenced type as deprecated, which often isn't viable.

Here's a little example:

```ts
// @filename: example.d.ts
export type Bar = string | number;

/** @deprecated */
export type Baz = string | number;

// @filename: foo.ts
import * as example from './example';

declare namespace JSX {
/** @deprecated */
export type Foo = string | number;

/** @deprecated */
export import Bar = example.Bar;

export import Baz = example.Baz;
}

let x: JSX.Foo; // Marked as deprecated
let y: JSX.Bar; // Not marked as deprecated (but should be)
let z: JSX.Baz; // Marked as deprecated
```

[TypeScript Playground Link](https://www.typescriptlang.org/play/?jsx=0&multiFile=true#code/PTAEAEDMEsBsFMB2BDAtvAXKeAPNAHBAOgBMiAXAZwChd8B7AJ3NHIE995QAhZR0ALyhK5RtEQBzUAB9QiAK6oARvEYBuatWAAqbRBLx8jeAGNk5eCVDbgtHA2asOXXgC9Bw0eKmyFy1RqaIBAwCCjoWJD09BQ00KgOLHrIlNh4CQigkIz0qKAA5ETAuAQI+YEGJrB8XOHwlPjIJlwAUgDKABqgAN7UAJA6euAGRqbmlta2fXRMLOycoABi0R4iYpIycooq6poDuvqGxmYWVjb9M47xiTx8HiUZ8ES8uxf2s6DXH2736YRPbg0AF9NAgWDgsO0OkRlvQNGDQGxIZ1nnx4fAWK5kdDAUA)

### 📃 Motivating Example

Allows developers to mark namespace aliases as deprecated, giving downstream users more warning when those aliases will go away.

### 💻 Use Cases

1. What do you want to use this for?

[preact](https://github.com/preactjs/preact) has long since loaded up the JSX namespace with unrelated types... shouldn't have, but did. We're looking to get rid of this in our next major and to help folks migrate we wanted to extract the types to the `preact` namespace and re-export them as aliases through the `JSX` namespace. This will avoid any breaking changes in the current version and allow folks to keep compatibility with v10 and the upcoming v11.

Unfortunately, however, we can't mark this usage as deprecated which is a shame.

2. What shortcomings exist with current approaches?

Just doesn't work. End users get no warning that the namespace alias is deprecated.

3. What workarounds are you using in the meantime?

Just duplicated all the types. Instead of extracted types that are consumed both as direct exports and namespace aliases, we've had to make copies. Those in the namespace get the deprecation comment, those outside do not.

It's pretty fragile obviously, any change to one now has to be reflected to the same interface in another file.

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Piste de recherche

Commencez par l’exemple TypeScript Playground de l’issue et suivez la manière dont la dépréciation est signalée pour les membres de namespace et les alias de types. Ajoutez une couverture de régression pour `export import Bar = example.Bar` afin que `JSX.Bar` soit marqué comme déprécié, tandis que le comportement existant de `JSX.Baz` reste inchangé. Le travail est terminé lorsque les alias de namespace produisent l’avertissement de dépréciation attendu sans modifier la sortie JavaScript.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
typescript
Domaine
compilers
Type d'issue
Fonctionnalité
Difficulté
5/5
Temps estimé
Plus d'une semaine
Activité
À l'abandon
Clarté
Plutôt claire
Accessibilité débutants
35/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.