microsoft / microsoft/TypeScript
JSDoc tag for getting around "Object literals are open-ended"
- Lingua principale
- Go
- Stelle
- 111k
- Fork
- 14.3k
- Merge medio
- 2g 4h
- PR unite (30g)
- 132
Descrizione
### 🔍 Search Terms
label:"Domain: JSDoc" open-ended
label:"Domain: JSDoc" literal
label:checkJs open-ended
label:checkJs literal
### ✅ 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
According to [the documentation](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#object-literals-are-open-ended), TypeScript treats inferred object literals in checked `.js` files as open-ended by default. This is good and makes sense, but is annoying for the times when it isn't the desired functionality.
I'd like for a new tag to be introduced. I'll be using `@closed` as an example, but I'm fine with whatever wording, really. The new tag would be used on an object definition in order to opt out of this open-ended behavior for that specific object literal declaration.
Ideally, this would be done recursively through the object's definition (i.e. I shouldn't have to define `@closed` for each sub-object), but I understand if that's too broad-reaching. I'd be fine with having that limitation.
This is obviously very similar to [Exact Types (#12936)](https://github.com/microsoft/TypeScript/issues/12936), but it concerns general exact object types and structural compatibility, whereas this request is limited to a JSDoc opt-in for inferred object literals in checked JavaScript. I therefore believe this warrants its own feature request.
### 📃 Motivating Example
I use JSDoc quite extensively in my hobby work. I often run into issues like this:
```js
class CustomFooBarElement extends HTMLElement {
_elements = {
/** @type {HTMLSpanElement|null} */
foo: null,
};
constructor() {
super();
this._elements.bar = document.createElement("span");
// ^ currently doesn't report an error
}
}
```
Now, you can easily work around this by adding a full object typing to the `_elements` object:
```js
class CustomFooBarElement extends HTMLElement {
/** @type {{foo: HTMLSpanElement|null}} */
_elements = {
foo: null,
};
```
which would cause the `.bar` access to fail. However, maintaining such a declaration can quickly grow cumbersome when the `_elements` object grows in size and complexity:
```js
class CustomFooBarElement extends HTMLElement {
/**
* @type {{
* foo: HTMLSpanElement | null,
* buttons: {
* primary: {
* a: HTMLButtonElement | null,
* b: HTMLButtonElement | null,
* },
* },
* images: {
* a: HTMLImageElement | null,
* b: HTMLImageElement | null,
* },
* }}
*/
_elements = {
foo: null,
buttons: {
primary: {
a: null,
b: null,
},
},
images: {
a: null,
b: null,
},
};
```
A silly example, but I think you get the point. Not to mention the fact that you've completely decoupled the type definition from the definition of the variable itself.
Now, if I instead could do something like this:
```js
class CustomFooBarElement extends HTMLElement {
/** @closed */
_elements = {
/** @type {HTMLSpanElement|null} */
foo: null,
buttons: {
primary: {
/** @type {HTMLButtonElement|null} */
a: null,
/** @type {HTMLButtonElement|null} */
b: null,
},
},
images: {
/** @type {HTMLImageElement|null} */
a: null,
/** @type {HTMLImageElement|null} */
b: null,
},
};
```
It's much easier to handle, and would lead to the desired result:
```js
this._elements.bar = document.createElement("span");
// ^^^ error: Property 'bar' does not exist
this._elements.buttons.primary.c = document.createElement("button");
// ^ error: Property 'c' does not exist
```
### 💻 Use Cases
1. What do you want to use this for?
Typing fixed-shape objects. See the examples above.
2. What shortcomings exist with current approaches?
The object-declaration-level `@type` requires essentially repeating the entire structure of the object. It also decouples the type of the actual leaf property from its definition.
3. What workarounds are you using in the meantime?
I started with the object-declaration-level `@type`, but at this point I just use the leaf-level `@type` and hope I don't run into any spelling mistakes or such.
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Inizia dalla sezione dell’handbook “Object literals are open-ended” e dall’Exact Types issue collegata (#12936), quindi analizza il comportamento JSDoc di checked JavaScript descritto negli esempi. Il lavoro sarà completo quando sarà disponibile un opt-in JSDoc documentato per i literal di oggetto inferiti con forma fissa, incluso l’ambito concordato per gli oggetti annidati, e le assegnazioni di proprietà aggiuntive mostrate verranno rifiutate.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- javascript, typescript
- Ambito
- compilers
- Tipo di issue
- Funzionalità
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Stato di attività
- Tranquilla
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 45/100