Reconsider assignability of number to enum type.

[UselessPickles]

Search Terms

number assignable enum

Suggestion

Remove assignability of number to enum types.

Type number is currently assignable to numeric enum types. I am aware that this was intentionally implemented as a special case for convenience.

With recent improvements to generics (particularly conditional types), I believe that the convenience of number -> enum assignability may now be outweighed by the power of "distinctness" of NOT allowing assignability in that direction.

Removing this special case behavior would also probably have the benefit of simplifying some code in the TypeScript compiler and reducing risk of future bugs. Here's an example of a bug that was caused by the special case behavior of number->enum assignability: #10738

Use Cases

If number is NOT assignable to enum types, then it would enable the use of conditional types to distinguish numeric literal/enum types from plain old number, similar to the difference between
string literal/enum types and plain string.

My particular use case is probably too complex to try to present a full example, but here's a high level description...

I am generating typescript code/interfaces from a Swagger document for making API calls. There are two parts to this:

1. The compile-time static types of interfaces for the API's "models" (data structures). This is obviously used for static compile-time analysis to ensure that API request/response data is used properly. This includes generated enum types (both number and string) for properties that are defined as enums in the Swagger schema.
2. The run-time representation of the schema for the API's "models". This is used to generate forms, grid column configurations, etc., at run time based on the API "model" schemas. At the core of this is a discriminated union of interfaces containing the pertinent schema info for all supported data types for the properties of the API's "models". The interface for each data type is different. For example, "Number" data can have min/max values, indication of whether it's integer or floating point. "NumberEnum" simply contains a list of valid numeric values and generated names for each value (which match the actual names of values in corresponding generated enum type from [1] above). The Swagger JSON document is parsed at run time and converted into appropriate data structures to represent the API's "models" in terms of these data type schema interfaces.

In order to link these two halves together and have strictly typed run-time schema utilities that make use of the compile time types of the "model" interfaces, part of my solution requires a helper type that maps from the type of a property in a "model" interface to the type of that field's schema definition interface.

Currently, I can accurately distinguish between string enum vs plain string types, but I cannot do the same for number enum vs plain number. Numeric enum properties incorrectly have their types mapped to the data schema interface type for plain numeric data.

Examples

Here's an over-simplified example of the type mapping I am attempting, with comments indicating the results I would expect if number is NOT assignable to number enum:

enum StringEnum {
    A = "A",
    B = "B"
}

enum NumberEnum {
    A,
    B
}

type Test<T> = T extends number
    ? (number extends T ? "number" : "number-enum")
    : T extends string
        ? (string extends T ? "string" : "string-enum")
        : never;

let testString: Test<string>; // type: "string"
let testStringEnum: Test<StringEnum>; // type: "string-enum"
let testNumber: Test<number>; // type: "number"
let testNumberEnum: Test<NumberEnum>; // type: "number-enum"

With the current implementation of number->enum assignability, the type of testNumberEnum is "number" instead of "number-enum".

Aside from that, there's all the usual benefits of the stricter typing/assignability: plain numbers will need to be explicitly cast to an enum type before assigning (forces developer to consider whether it is correct).

Then there's the breaking change and inconvenience: plain numbers will need to be explicitly cast to an enum type before assigning (forces developer to consider whether it is correct).

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript / JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. new expression-level syntax)

[RyanCavanaugh]

I don't see this as enough to change our mind here; this would be a very large breaking change and would imply bifurcating flag and nonflag enums. See #17734, #21546, #11559, #15591, #8020, #18409, etc.

You can write this today if your enums have 0 and 1 and get the expected behavior:

type Test<T> = T extends 0 | 1
  ? "number-enum" : "number";

[DanielRosenwasser]

The behavior is motivated by bitwise operations. There are times when SomeFlag.Foo | SomeFlag.Bar is intended to produce another SomeFlag. Instead you end up with number, and you don't want to have to cast back to SomeFlag`.

I think if we did TypeScript over again and still had enums, we'd have made a separate construct for bit flags.

[UselessPickles]

@RyanCavanaugh

You can write this today if your enums have 0 and 1 and get the expected behavior:

That is not a viable solution, because I need to generically detect that a type is more specific than simply number. I suppose I could create a union of all possible distinct number literals (ALL OF THEM) to create a generic test that "works", but that would be impractical.

@DanielRosenwasser
All explanations I've seen so far for when number is assignable to enum (bit flags, enum arithmetic, etc) are situations where I would actually expect to need to be extra careful and use type casting to convince the compiler that I really do know what I'm doing. "Breaking" these use cases actually sounds like a good thing to me.

In the case of bit flag enums, the result of ORing multiple bits together doesn't even produce a value that matches any of the enum values, so it doesn't seem right at all to treat the result as the enum type (implicitly, or explicitly via type casting). Multiple bits ORed together really is just a number.

Based on the duplicate issues linked above, it doesn't seem uncommon that developers would expect/desire more strictness with enum types. My gut feeling is that the current behavior may have helped TypeScript enums be more palatable earlier on when developers transitioning from JavaScript were more skeptical of all this type strictness. The community as a whole seems to be embracing stricter typing and its benefits more as time goes on. How do we determine if/when the community as a whole has reached the point where they would prefer stricter enum behavior while accepting that "bit flags" would be "broken"?

Consider that the breaking change, while widespread, would be very straightforward to deal with. Compiler errors would very clearly indicate the enum type that you must now type cast to in order to migrate the code to deal with the breaking change. It's probably so straightforward that a script could be developed to automatically migrate code to use enum type casting where necessary (if the developer wants a quick/effortless solution without taking the opportunity to review each instance for potential actual incorrect code uncovered by the new strictness). The migrated code would also be backward compatible with the previous version of TypeScript.

A possibly more pragmatic approach: Is it feasible to add this as a compiler option (strictNumericEnums)?

[UselessPickles]

BTW - I did just realize the migration for the breaking change would not be quite as simple as I suggested. If developers are declaring properties/params as bit flag enum types with the intent that they will hold values formed from combining multiple flags, then those would have to be changed to type number,

Also, if a variable/property is initialized to a single bit flag enum value without being explicitly typed, then its type will be inferred as the enum type and may break code that tries to modify that value with |=, &=, etc. Such variables/properties would need to be explicitly type as number, or initialized to an expression like 0 | MyFlags.FOO that evaluates to type number.

This whole bit flag enum concept just feels so foreign and wrong to me: declaring something as an enum type with the intent to store values in it that are intentionally NOT any of the enumerated values.

[RyanCavanaugh]

I'm not sure how to communicate this effectively, but we really have thought about this a large amount and weighed pros and cons of complexity vs usefulness.

We've taken the feedback and will continue to keep this on our radar for possible future changes.

[UselessPickles]

Consider it communicated effectively. Thanks for reading.

One final thought on bit flag enums specifically: Allowing number -> enum assignment effectively neuters the type safety of declaring a property/param as an enum type. The enum type declaration becomes more of a "hint" for documentation purposes to suggest to an observant developer that maybe they should go look at that enum definition to understand what the different bits mean, and use those enums to conveniently build a value out of those bits:

/**
 * Do something with some bit flags.
 * @param flags - Not really a MyBitFlags value, but a number whose bits are interpreted as defined by MyBitFlags.
 */
function foo(flags: MyBitFlags): void;

How is this any more helpful than declaring it as type number and referencing the enum in documentation?

/**
 * Do something with some bit flags.
 * @param flags - See {@link MyBitFlags} for bit definitions.
 */
function foo(flags: number): void;

[RyanCavanaugh]

How is this any more helpful than declaring it as type number and referencing the enum in documentation?

This is actually extremely helpful. In our own codebase, for example, we have 17 different kinds of flag masks that are never interoperable. The existing behavior makes sure we don't use NodeFlags where SymbolFlags are needed. It doesn't catch all errors you can make here, but catches many while still being pragmatic for other cases.

[evmar]

I was surprised by the rule here, so here's a little snippet just in case anyone else was wondering:

enum SymbolFlags {
  A,
  B
}
enum NodeFlags {
  C,
  D
}

function wantsSymbol(s: SymbolFlags) {}

// You might expect all of these should all be rejected, but
wantsSymbol(NodeFlags.C | SymbolFlags.A); // accepted
wantsSymbol(NodeFlags.C | 0);  // accepted
wantsSymbol(NodeFlags.C | NodeFlags.A);  // rejected