Enum unification and improvements

[ahejlsberg]

Since #9407 TypeScript has had two kinds of enum types: Numeric enum types and literal enum types (also known as union enum types). Numeric enum types have permitted enum members to have computed values, but not literal types; whereas literal enum types have required members to be declared using simple numeric or string literals only. The distinction between these two kinds of enums is subtle and has been the source of a fair amount of confusion over time.

With this PR we unify the two kinds into a single hybrid that incorporates the best of both worlds. Specifically, enums are always represented as unions of their member types, member values may be computed by constant or non-constant expressions, and members with constant values are given literal types. The PR only affects type checking of enums. There are no changes to the emitted code (except for better inlining of constant expressions in some cases).

An enum declaration now declares a type representing the entire enum and types representing each member (similar to literal enum types). For example,

enum E {
    A = 10 * 10,  // Numeric literal enum member
    B = "foo",    // String literal enum member
    C = bar(42)   // Opaque computed enum member
}

declares a type E and types E.A, E.B, and E.C, where E is the union E.A | E.B | E.C.

An enum member has a literal enum type when it is initialized by a constant expression or when it has no initializer and is given an auto-incremented numeric value. In the example above, E.A and E.B denote enum literal types with values 100 and "foo" respectively.

An enum member has a unique and opaque enum member type when it is initialized by a non-constant expression. Non-constant initializer expressions must be assignable to type number and are not permitted in const enum declarations. In the example above, E.C denotes a unique enum member type representing the value computed by the non-constant initializer expression. This unique type is assignable to type number, but otherwise incompatible with other types.

An expression is considered a constant expression if it is

• a number or string literal,
• a unary +, -, or ~ applied to a numeric constant expression,
• a binary +, -, *, /, %, **, <<, >>, >>>, |, &, ^ applied to two numeric constant expressions,
• a binary + applied to two constant expressions whereof at least one is a string,
• a template expression where each substitution expression is a constant expression,
• a parenthesized constant expression,
• a dotted name (e.g. x.y.z) that references a const variable with a constant expression initializer and no type annotation,
• a dotted name that references an enum member with an enum literal type, or
• a dotted name indexed by a string literal (e.g. x.y["z"]) that references an enum member with an enum literal type.

Note that constant expressions are not permitted to make forward references--any value referenced by a constant expression must have been previously declared.

Some examples:

const BaseValue = 10;
const Prefix = "/data";
const enum Values {
    First = BaseValue,  // 10
    Second,             // 11
    Third               // 12
}
const enum Routes {
    Parts = `${prefix}/parts`,       // "/data/parts"
    Invoices = `${prefix}/invoices`  // "/data/invoices"
}

NOTE: This PR is technically a breaking change because checking of the new unified enum types is stricter than the old numeric enum types.

Fixes #27976.
Fixes #35875.
Fixes #40793.
Fixes #43902.

[RyanCavanaugh]

@typescript-bot pack this

[typescript-bot]

Heya @RyanCavanaugh, I've started to run the tarball bundle task on this PR at 50a952b. You can monitor the build here.

[ahejlsberg]

@typescript-bot test this
@typescript-bot user test this inline
@typescript-bot run dt
@typescript-bot perf test faster

[typescript-bot]

Heya @ahejlsberg, I've started to run the extended test suite on this PR at 50a952b. You can monitor the build here.

[typescript-bot]

Heya @ahejlsberg, I've started to run the abridged perf test suite on this PR at 50a952b. You can monitor the build here.

Update: The results are in!

[typescript-bot]

Heya @ahejlsberg, I've started to run the parallelized Definitely Typed test suite on this PR at 50a952b. You can monitor the build here.

[typescript-bot]

Heya @ahejlsberg, I've started to run the diff-based user code test suite on this PR at 50a952b. You can monitor the build here.

Update: The results are in!

[typescript-bot]

@ahejlsberg
The results of the perf run you requested are in!

Here they are:

Comparison Report - main..50528

Metric	main	50528	Delta	Best	Worst
Angular - node (v14.15.1, x64)
Memory used	338,727k (± 0.00%)	338,717k (± 0.01%)	-9k (- 0.00%)	338,668k	338,757k
Parse Time	2.08s (± 0.70%)	2.09s (± 0.93%)	+0.02s (+ 0.82%)	2.06s	2.15s
Bind Time	0.80s (± 0.62%)	0.80s (± 0.75%)	+0.00s (+ 0.00%)	0.79s	0.81s
Check Time	5.82s (± 0.58%)	5.83s (± 0.27%)	+0.01s (+ 0.14%)	5.79s	5.87s
Emit Time	6.18s (± 0.49%)	6.22s (± 0.72%)	+0.04s (+ 0.58%)	6.16s	6.37s
Total Time	14.87s (± 0.27%)	14.93s (± 0.40%)	+0.06s (+ 0.41%)	14.85s	15.11s
Compiler-Unions - node (v14.15.1, x64)
Memory used	192,654k (± 0.02%)	192,983k (± 0.37%)	+329k (+ 0.17%)	192,631k	195,896k
Parse Time	0.86s (± 0.52%)	0.85s (± 0.87%)	-0.01s (- 0.58%)	0.84s	0.87s
Bind Time	0.49s (± 0.75%)	0.49s (± 0.82%)	+0.00s (+ 0.62%)	0.48s	0.50s
Check Time	6.70s (± 0.55%)	6.73s (± 0.69%)	+0.03s (+ 0.43%)	6.64s	6.85s
Emit Time	2.41s (± 1.02%)	2.40s (± 0.72%)	-0.01s (- 0.54%)	2.35s	2.43s
Total Time	10.46s (± 0.45%)	10.47s (± 0.51%)	+0.02s (+ 0.16%)	10.35s	10.62s
Monaco - node (v14.15.1, x64)
Memory used	326,505k (± 0.01%)	326,536k (± 0.00%)	+31k (+ 0.01%)	326,510k	326,581k
Parse Time	1.57s (± 0.59%)	1.60s (± 1.50%)	+0.03s (+ 1.65%)	1.57s	1.69s
Bind Time	0.73s (± 0.85%)	0.73s (± 0.68%)	-0.00s (- 0.41%)	0.72s	0.74s
Check Time	5.73s (± 0.51%)	5.78s (± 0.51%)	+0.05s (+ 0.86%)	5.73s	5.85s
Emit Time	3.35s (± 0.61%)	3.35s (± 0.67%)	-0.00s (- 0.12%)	3.30s	3.40s
Total Time	11.39s (± 0.42%)	11.45s (± 0.44%)	+0.06s (+ 0.55%)	11.35s	11.55s
TFS - node (v14.15.1, x64)
Memory used	289,645k (± 0.00%)	289,648k (± 0.01%)	+3k (+ 0.00%)	289,614k	289,687k
Parse Time	1.31s (± 0.83%)	1.31s (± 0.80%)	+0.01s (+ 0.38%)	1.30s	1.34s
Bind Time	0.78s (± 2.29%)	0.80s (± 0.75%)	+0.01s (+ 1.40%)	0.78s	0.81s
Check Time	5.36s (± 0.54%)	5.35s (± 0.62%)	-0.01s (- 0.24%)	5.27s	5.44s
Emit Time	3.60s (± 0.77%)	3.57s (± 0.76%)	-0.03s (- 0.75%)	3.51s	3.63s
Total Time	11.05s (± 0.38%)	11.03s (± 0.59%)	-0.03s (- 0.25%)	10.87s	11.20s
material-ui - node (v14.15.1, x64)
Memory used	438,087k (± 0.06%)	438,212k (± 0.00%)	+125k (+ 0.03%)	438,180k	438,251k
Parse Time	1.86s (± 0.59%)	1.87s (± 0.59%)	+0.01s (+ 0.38%)	1.84s	1.89s
Bind Time	0.59s (± 0.62%)	0.59s (± 1.10%)	+0.00s (+ 0.34%)	0.58s	0.61s
Check Time	13.06s (± 0.95%)	12.92s (± 0.81%)	-0.14s (- 1.06%)	12.72s	13.15s
Emit Time	0.00s (± 0.00%)	0.00s (± 0.00%)	0.00s ( NaN%)	0.00s	0.00s
Total Time	15.51s (± 0.81%)	15.38s (± 0.72%)	-0.13s (- 0.83%)	15.16s	15.62s
xstate - node (v14.15.1, x64)
Memory used	547,388k (± 0.00%)	547,403k (± 0.00%)	+15k (+ 0.00%)	547,362k	547,442k
Parse Time	2.60s (± 0.45%)	2.62s (± 0.47%)	+0.02s (+ 0.73%)	2.60s	2.65s
Bind Time	0.97s (± 0.70%)	0.98s (± 0.68%)	+0.01s (+ 0.62%)	0.97s	0.99s
Check Time	1.54s (± 0.62%)	1.54s (± 0.42%)	-0.00s (- 0.13%)	1.53s	1.55s
Emit Time	0.07s (± 4.13%)	0.07s (± 3.14%)	-0.00s (- 1.39%)	0.07s	0.08s
Total Time	5.20s (± 0.42%)	5.22s (± 0.21%)	+0.02s (+ 0.38%)	5.19s	5.24s

System

Machine Name	ts-ci-ubuntu
Platform	linux 4.4.0-210-generic
Architecture	x64
Available Memory	16 GB
Available Memory	15 GB
CPUs	4 × Intel(R) Core(TM) i7-4770 CPU @ 3.40GHz

Hosts

• node (v14.15.1, x64)

Scenarios

• Angular - node (v14.15.1, x64)
• Compiler-Unions - node (v14.15.1, x64)
• Monaco - node (v14.15.1, x64)
• TFS - node (v14.15.1, x64)
• material-ui - node (v14.15.1, x64)
• xstate - node (v14.15.1, x64)

Benchmark	Name	Iterations
Current	50528	10
Baseline	main	10

Developer Information:

Download Benchmark

[typescript-bot]

@ahejlsberg Here are the results of running the user test suite comparing main and refs/pull/50528/merge:

Everything looks good!

[typescript-bot]

Heya @ahejlsberg, I've run the RWC suite on this PR - assuming you're on the TS core team, you can view the resulting diff here.

[typescript-bot]

Hey @RyanCavanaugh, I've packed this into an installable tgz. You can install it for testing by referencing it in your package.json like so:

{
    "devDependencies": {
        "typescript": "https://typescript.visualstudio.com/cf7ac146-d525-443c-b23c-0d58337efebc/_apis/build/builds/133037/artifacts?artifactName=tgz&fileId=3F948668C1BD8758CB1C8E59919B3D6E945DCF3815094A729B98FCE15A366B7E02&fileName=/typescript-4.9.0-insiders.20220829.tgz"
    }
}

and then running npm install.

---

There is also a playground for this build and an npm module you can use via "typescript": "npm:@typescript-deploys/pr-build@4.9.0-pr-50528-10".;

[ahejlsberg]

@typescript-bot test this
@typescript-bot user test this inline
@typescript-bot run dt
@typescript-bot perf test faster
@typescript-bot test top100

[typescript-bot]

Heya @ahejlsberg, I've started to run the diff-based top-repos suite on this PR at 3f66f6c. You can monitor the build here.

Update: The results are in!

[Sweater-Baron]

Is this included in a published version of Typescript yet? Based on the comments in this PR thread, it sounds like it should be in Typescript 5.

I'm on Typescript 5.0.2, but getting the error "const enum member initializers can only contain literal values and other computed enum values.", which I believe shouldn't happen if I'm on a version of typescript that includes this code?

I'm copying the example from the PR:

const prefix = '/data';

const enum Routes {
  Parts = `${prefix}/parts`, // "/data/parts"
  Invoices = `${prefix}/invoices`, // "/data/invoices"
}

[janbiasi]

Is this included in a published version of Typescript yet? Based on the comments in this PR thread, it sounds like it should be in Typescript 5.

@Sweater-Baron Yes it is, your example is working perfectly fine running version 5.0.2 (see playground). If you use VSCode make sure that you use your local TypeScript version and not VSCode's version.

[JordanDC2]

Is there any plan to implement enum extension like in this playground (or some other way to extend enums)?:

[isaackhoo]

Is this included in a published version of Typescript yet? Based on the comments in this PR thread, it sounds like it should be in Typescript 5.

@Sweater-Baron Yes it is, your example is working perfectly fine running version 5.0.2 (see playground). If you use VSCode make sure that you use your local TypeScript version and not VSCode's version.

I have set my vscode to use 5.0.2, but im still getting the error

[WORMSS]

@JordanDC2 Not 100% exactly what you asked for..
But I find they work better than enums

https://www.typescriptlang.org/play?#code/MYewdgzgLgBADgJwKYDMCWAPGBeGByAegBMBDKEvAbgFgAoUSWAJRAFcokIcYBvOmATAAKJBFAgAuGAAMAJD0SpMAXwJxR46QBp+ggJJgAbiDTBOUuQuToMqtEZNmI2uspgkuDaDVp0vzNg4IAFEMDjAiJCJuPlpBGAA6JJZ2Th04wQB5BEiESRl5RRtVEBykPJdaNw8Yfx86KABPOCQYFKDQ8MiiADUSABtWTm4mlpAUNsDOTqQIqIBtAGskRvGYUaQ19umw2e6AXXraFFYwYCg0cBgAcxAoEAAKBCmpbZDdud6BoYgASl5lHQ6Ld7g83jNPgkDMZTJxfj4QY83lCHLC-pQgA

[JordanDC2]

@WORMSS yeah thats kind of what im having to work with currently, i just wish it was a capability of Enums since we can have computed values now but not computed keys

[Seriosus]

@JordanDC2 Not 100% exactly what you asked for.. But I find they work better than enums

https://www.typescriptlang.org/play?#code/MYewdgzgLgBADgJwKYDMCWAPGBeGByAegBMBDKEvAbgFgAoUSWAJRAFcokIcYBvOmATAAKJBFAgAuGAAMAJD0SpMAXwJxR46QBp+ggJJgAbiDTBOUuQuToMqtEZNmI2uspgkuDaDVp0vzNg4IAFEMDjAiJCJuPlpBGAA6JJZ2Th04wQB5BEiESRl5RRtVEBykPJdaNw8Yfx86KABPOCQYFKDQ8MiiADUSABtWTm4mlpAUNsDOTqQIqIBtAGskRvGYUaQ19umw2e6AXXraFFYwYCg0cBgAcxAoEAAKBCmpbZDdud6BoYgASl5lHQ6Ld7g83jNPgkDMZTJxfj4QY83lCHLC-pQgA

Man, you saved me, thank you.
This is indeed better than using enums or at least when not using literals.

[tka85]

Sounds weird, but I'm on Typescript 5.0.2. I'm forcing VSC to use the local installed Typescript version (which it recognizes is 5.0.2 instead of VSC's 4.9.5) and the enum values still get udnerlined with red squiggly line.

export enum TABLES {
    foo = `${config.schema}.foos`,
    bar = `${config.schema}.bars`
}

Any ideas what I'm missing here? I see the playground link posted above by @janbiasi and it should be working for 5.0.2. But it's not.

I confirm that the project has 5.0.2 installed with npm ls typescript; only 5.0.2 and no other version exists in the workspace.

[Regiden]

We just tried to update our code base and we noticed a ton of errors. Turns out this change basically means you cannot treat an enum as basically "just" a number anymore? No way to optionally tell TypeScript to allow "optional" values that are basically null?

This is somewhat weird, because you now can't have a fall back state and HAVE to define a "NONE" type.

enum TEST {
    ONE = 1,
    TWO
}

const foo: TEST = 0;

This now is an error. Was there any reason not to allow for a fallback here?

[gabriel-calin-lazar]

how come
we have strict enum usages when value is number, when using number literal or enum entry
but
we have strict enum usages when value is string, only when using enum entry - not when using string literal ?

would be really useful to not have this not so obvious difference

you can check some examples here

[ahejlsberg]

@gabriel-calin-lazar See my comment here.

[vtarelkin]

@tka85 any ideas about it? Also have TS above 5 and it complains

[tka85]

@vtarelkin Nope. No response.

[jakebailey]

An old PR is really not the best place to ask for help or report bugs. I would really suggest filing an issue if you want it to be seen by the right people.

[vtarelkin]

@jakebailey people are searching over the whole net and hope to find a clue here) maybe you could help us please?)) I have a TS above 5th version and it still complains

[jakebailey]

Please, please, please, file an issue and fill out the template.

[nick4fake]

@jakebailey this issues comes the first google search result. I have typescript 5.1.3 and just noticed the same problem, still trying to find any relevant tickets in this repo.

If there is a solution - it might be helpful to add it here, or at least have a link somewhere in comments

[RyanCavanaugh]

Please file a new issue outlining the problem you're having