microsoft / microsoft/TypeScript

JSDoc tag for getting around "Object literals are open-ended"

Open
#63,691 0 comments 0 reactions 0 assignees View on GitHub
Awaiting More Feedback Suggestion
Dominant language
Go
Stars
111k
Forks
14.3k
PR merge metrics
PR metrics pending

Description

### 🔍 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.

Contributor guide

Open the contributing guide

Research direction

Start with the handbook section on “Object literals are open-ended” and the linked Exact Types issue (#12936), then investigate the checked-JavaScript JSDoc behavior described in the examples. Done should provide a documented JSDoc opt-in for fixed-shape inferred object literals, including the agreed scope for nested objects, with the shown extra-property assignments rejected.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
compilers
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.