`as enum` assertion for object literals

[acutmore]

🔍 Search Terms

enum, object literal, type-stripping

✅ Viability Checklist

• 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. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

Context

While TypeScript already allows declaring runtime enums values:

export enum Compass {
  N = "N",
  S = "S",
  E = "E",
  W = "W",
}

This is not standard JavaScript, and does not work in Node.js unless --experimental-transform-types is passed.

An alternative "pure JS" pattern from the TypeScript handbook is:

export const Compass = {
  N: "N",
  S: "S",
  E: "E",
  W: "W",
} as const;
export type Compass = typeof Compass[keyof typeof Compass];

https://www.typescriptlang.org/docs/handbook/enums.html#objects-vs-enums

There are two downsides to this pattern:

• typeof X[keyof typeof X] is both verbose and not beginner friendly.
• The type aliases are not nominal, they are a plain union type.

⭐ Suggestion

Introduce some new syntax to TypeScript to help with the object-literal-as-enum pattern.

For example would be allowing as enum:

export const Compass = {
  N: "N",
  S: "S",
  E: "E",
  W: "W",
} as enum;

(from #59658)

An alternative design could be allowing an enum type annotation on const variable declarations export const Compass: enum = {...}.

This annotation would effectively be the same as writing:

/** secret internal type - here to get nominal typing */
declare const enum __Compass__ {
    N = "N",
    S = "S",
    E = "E",
    W = "W",
}
export const Compass = {
  N: "N" as __Compass__.N,
  S: "S" as __Compass__.S,
  E: "E" as __Compass__.E,
  W: "W" as __Compass__.W,
} as const;
export type Compass = __Compass__;

Rules

The enum annotation would only be permitted for object literals that are

• in a declarative position
• have compile-time constant key+values
• all values are either strings, numbers, or references to constant strings/numbers.

i.e. the object literal would follow very similar rules that are applied to const enum C {} syntax

// @ts-expect-error
foo({ a: "a" } as enum);

class C {
   // @ts-expect-error
   f: enum = {}
}

const o = {
   // @ts-expect-error
   p: Math.random()
} as enum;

Benefits

• The standard JS of an object lieral with the type-checking of an enum
• An explicit marker for tools such as linters to provide extra checks (e.g. enum naming conventions)

Downsides

While this object literal as enum pattern is popular in codebases that avoid non-standard runtime syntax it does not have all the features available with enum syntax such as self-reference during construction.

__proto__: null is currently not supported #38385 making it difficult to avoid object literals from inheriting non-enum properties resulting in false positives with key in MyEnum.

📃 Motivating Example

export const Compass = {
  N: "N",
  S: "S",
  E: "E",
  W: "W",
} as enum;
Object.freeze(Compass);

export function reverse(c: Compass): Compass {
   if (c === Compass.N) return Compass.S;
   if (c === Compass.S) return Compass.N;
   if (c === Compass.E) return Compass.W;
   if (c === Compass.W) return Compass.E;
   throw new Error("unreachable code was run");
}

The above module will work out-of-the-box in Node.js (assuming nodejs/typescript#17).

💻 Use Cases

1. What do you want to use this for?

Creating an enum like value using standard Object literal syntax with some of the type system benefits that enum syntax has.

2. What shortcomings exist with current approaches?

• typeof Foo[keyof typeof Foo] is not beginner friendly and is not a nominal type

3. What workarounds are you using in the meantime?

One workaround is to have a small utility for emulating an enum like nominal type from an object literal (playground). The "literal" & { __key__: val } trick works but results in noisey types when displayed to the developer (e.g. in an error message)

[rauschma]

This is a great idea!

Symbol enums without as enum

all values are either strings, numbers, or references to constant strings/numbers.

For unique enum values, symbols are often used in JavaScript, so I’d want them to be supported. With a utility type, we’d have the following OK-ish code:

const Compass = Object.freeze({
  __proto__: null,
  N: Symbol("N"),
  S: Symbol("S"),
  E: Symbol("E"),
  W: Symbol("W"),
} as const); // (A)
type Compass = EnumValues<Obj>; // (B)

// Utility type:
type EnumValues<Obj> = Obj[Exclude<keyof Obj, '__proto__'>]; // (C)

Sadly this code only almost works – see (1):

1. Major problem (line A): Even with as const, symbols as property values are not unique (you have to use externally declared constants): Symbols in as const objects should be unique symbols #54100

2. At the type level, Object.freeze() has the same effect as as const. So the latter can be omitted here (I’m using it to clarify the previous point).

3. Workaround (line C): __proto__ in object literals is not supported (as you mentioned): RFC: Support __proto__ literal in object initializers #38385

4. Minor problem (line B): You can’t rename both value Compass and type Compass at the same time. So you have to rename first one of them, then the other one. However, the last time I did that in VS Code, that didn’t work well with imports. That’s why, for now, I’d use a different name for the type – e.g. CompassType (which shows up in type completions for Compass).

Symbol enums with as enum

It’d be great if as enum worked with & without freezing and with & without __proto__:null:

const FrozenProtoCompass = Object.freeze({
  __proto__: null,
  N: Symbol("N"),
  S: Symbol("S"),
  E: Symbol("E"),
  W: Symbol("W"),
}) as enum;

const ProtoCompass = {
  __proto__: null,
  N: Symbol("N"),
  S: Symbol("S"),
  E: Symbol("E"),
  W: Symbol("W"),
} as enum;

const Compass = {
  N: Symbol("N"),
  S: Symbol("S"),
  E: Symbol("E"),
  W: Symbol("W"),
} as enum;

[demurgos]

I worked on migrating my code using TS enums to be compatible with the --erasableSyntaxOnly flag today. I posted the solution I landed on here.

In short, here is the code:

const Foo: unique symbol = Symbol("Foo");
const Bar: unique symbol = Symbol("Bar");

const MyEnum = {
  Foo,
  Bar,
} as const;

type MyEnum = typeof MyEnum[keyof typeof MyEnum];

declare namespace MyEnum {
  type Foo = typeof MyEnum.Foo;
  type Bar = typeof MyEnum.Bar;
}

export {MyEnum};

This is very close to the symbol enums discussed above, and would benefit a lot from an as enum assertion to cut down on type-level boilerplate. With as enum, the following code could be equivalent:

export const MyEnum = Object.freeze({
  __proto__: null,
  Foo: Symbol("Foo"),
  Bar: Symbol("Bar"),
}) as enum;

Or if R/T lands, the simpler:

export const MyEnum = #{
  Foo: Symbol("Foo"),
  Bar: Symbol("Bar"),
} as enum;

The reason why I use the particular expansion from my first code fragment is to keep nominal typing and have lightweight syntax in the type namespace.

It’d be great if as enum worked with & without freezing and with & without __proto__:null:

I'm not sure if it would work. An important use case of enums is to act as tags for discriminated unions. For this, you don't need symbol but unique symbol. And for unique symbol, the path should be immutable. Since a goal of this issue is to be compatible with erasable syntax, the immutability has to be in the code. Requiring freezing and a null proto makes sense, until R/T lands.

The way value and type namespaces interact in TS is a relatively advanced topic, so having MyEnum.Foo (or Compass.N provided out of the box in the type namespace when using as enum would be great.

[rauschma]

Personally, I actually prefer enum-as-value and enum-as-type not diverging as much as they do with current enums. I never found that very intuitive. If you need MyEnum.Foo at the type level (e.g. for discriminated unions), you can always use typeof.

It’d be great if as enum worked with & without freezing and with & without __proto__:null

I'm not sure if it would work. An important use case of enums is to act as tags for discriminated unions. For this, you don't need symbol but unique symbol. And for unique symbol, the path should be immutable. Since a goal of this issue is to be compatible with erasable syntax, the immutability has to be in the code. Requiring freezing and a null proto makes sense, until R/T lands.

Given that as enum only affects the type level and given that as const doesn’t require freezing either, I don’t see why it would not work(?)

As an aside, IINM, the following two lines should be equivalent:

const Foo: unique symbol = Symbol("Foo");
const Foo = Symbol("Foo");

[shicks]

Should we be concerned about syntax that encourages/requires {__proto__: null} when this usage is specifically discouraged? Not that I have any better suggestions.

[rauschma]

Should we be concerned about syntax that encourages/requires {__proto__: null} when this usage is specifically discouraged?

Using the accessor Object.prototype.__proto__ is indeed discouraged. However, using the pseudo property key __proto__ in object literals is not: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer#prototype_setter

[demurgos]

Given that as enum only affects the type level and given that as const doesn’t require freezing either, I don’t see why it would not work(?)

The problem that I see is that as const does not work with symbols in objects currently:

const foo = {
  bar: Symbol("bar"),
} as const;

In this snippet, typeof foo.bar is symbol; not unique symbol. I think that as enum should be consistent with as const, so for symbol enums it may require updating how symbols are handled in as const.

This is why I proposed requiring Object.freeze; but you're right that as const is already not super strict.