-
Notifications
You must be signed in to change notification settings - Fork 13k
Support the JSDoc @enum tag #26021
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Support the JSDoc @enum tag #26021
Conversation
`@enum` is used on a variable declaration with an object literal initializer. It does a number of things: 1. The object literal has a closed set of properties, unlike other object literals in Javascript. 2. The variable's name is resolvable as a type, but it just has the declared type of the enum tag. 3. Each property's type must be assignable to the enum tag's declared type, which can be any type. For example, ```js /** @enum {string} */ const Target = { START: "START", END: "END", MISTAKE: 0, // error 'number' is not assignable to 'string' -- see (3) } Target.THIS_IS_AN_ERROR; // See (1) /** @type {Target} See (2) */ var target = Target.START; ```
Thanks for adding this @sandersn! Out of curiousity: how would the above |
(disregarding the MISTAKE member) enum Target {
START = "START",
END = "END"
}
Target.ERROR // error here
var target: Target = Target.START
target = "lol whatever" // error here! You can also avoid the enum construct since it's not standard JS. There's more boilerplate in that case. var Target = {
"START": "START" as "START",
"END": "END" as "END"
}
type Target = keyof typeof Target
Target.ERROR
var target: Target = Target.START
target = 'lol whatever' // error here too But you can emulate var target: string = Target.START
target = 'lol whatever' // ok, target is just a string If you don't care about values, you can also get the loose assignability behaviour with number enums, but they still only allow numbers to be assigned: enum Target {
START,
END
}
var target: Target = Target.START
target = 'lol whatever' // error
target = 111 // ok Edit: Unlike |
Thanks! The 2nd snippet above (avoiding the enum construct) is my favorite. |
@sandersn Is it common practice to change the number values of |
@eps1lon Yes, this is common, and it's the reason we use |
@Andy-MS But the value of |
It's in general an error to mix-and-match two different TypeScript installs. |
I keep hearing that but I have yet to find libraries that pin typescript to exact versions. This is also not documented anywhere and I feel like this should be the case because npm and yarn assume by default that packages follow semver. |
Typically TypeScript would be a peer dependency (example: tslint) of a library that needs to |
@enum
is used on a variable declaration with an object literalinitializer. It does a number of things:
Notably, this PR does not implement the fourth feature from #18161, which is to treat the enum's name as a new type that is not assignable to and from any other types. I believe this would require a lot more effort to implement, and I expect this tag to only be used in codebases transitioning from Closure. If I'm wrong, it shouldn't be a problem to make the semantics stricter.
For example,
Fixes #18161