René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"`as enum` assertion for object literals","articleBody":"### 🔍 Search Terms\n\nenum, object literal, type-stripping\n\n### ✅ Viability Checklist\n\n- [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code\n- [x] This wouldn't change the runtime behavior of existing JavaScript code\n- [x] This could be implemented without emitting different JS based on the types of the expressions\n- [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)\n- [x] This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types\n- [x] This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals\n\n### Context\n\nWhile TypeScript already allows declaring runtime enums values:\n\n```ts\nexport enum Compass {\n  N = \"N\",\n  S = \"S\",\n  E = \"E\",\n  W = \"W\",\n}\n```\n\nThis is not standard JavaScript, and does not work in Node.js unless [`--experimental-transform-types`](https://nodejs.org/api/cli.html#--experimental-transform-types) is passed.\n\nAn alternative \"pure JS\" pattern from the TypeScript handbook is:\n\n```ts\nexport const Compass = {\n  N: \"N\",\n  S: \"S\",\n  E: \"E\",\n  W: \"W\",\n} as const;\nexport type Compass = typeof Compass[keyof typeof Compass];\n```\n\nhttps://www.typescriptlang.org/docs/handbook/enums.html#objects-vs-enums\n\nThere are two downsides to this pattern:\n\n- `typeof X[keyof typeof X]` is both verbose and not beginner friendly.\n- The type aliases are not nominal, they are a _plain_ union type.\n\n### ⭐ Suggestion\n\nIntroduce some new syntax to TypeScript to help with the object-literal-as-enum pattern.\n\nFor example would be allowing `as enum`:\n\n```ts\nexport const Compass = {\n  N: \"N\",\n  S: \"S\",\n  E: \"E\",\n  W: \"W\",\n} as enum;\n```\n\n(from #59658)\n\nAn alternative design could be allowing an `enum` type annotation on `const` variable declarations `export const Compass: enum = {...}`.\n\nThis annotation would effectively be the same as writing:\n\n```ts\n/** secret internal type - here to get nominal typing */\ndeclare const enum __Compass__ {\n    N = \"N\",\n    S = \"S\",\n    E = \"E\",\n    W = \"W\",\n}\nexport const Compass = {\n  N: \"N\" as __Compass__.N,\n  S: \"S\" as __Compass__.S,\n  E: \"E\" as __Compass__.E,\n  W: \"W\" as __Compass__.W,\n} as const;\nexport type Compass = __Compass__;\n```\n\n### Rules\n\nThe `enum` annotation would only be permitted for object literals that are\n - in a declarative position\n - have compile-time constant key+values\n - all values are either strings, numbers, or references to constant strings/numbers.\n\ni.e. the object literal would follow very similar rules that are applied to `const enum C {}` syntax\n\n```ts\n// @ts-expect-error\nfoo({ a: \"a\" } as enum);\n\nclass C {\n   // @ts-expect-error\n   f: enum = {}\n}\n\nconst o = {\n   // @ts-expect-error\n   p: Math.random()\n} as enum;\n```\n\n### Benefits\n\n- The standard JS of an object lieral with the type-checking of an `enum`\n- An explicit marker for tools such as linters to provide extra checks (e.g. enum naming conventions)\n\n### Downsides\n\nWhile 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.\n\n`__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`.\n\n\n### 📃 Motivating Example\n\n```ts\nexport const Compass = {\n  N: \"N\",\n  S: \"S\",\n  E: \"E\",\n  W: \"W\",\n} as enum;\nObject.freeze(Compass);\n\nexport function reverse(c: Compass): Compass {\n   if (c === Compass.N) return Compass.S;\n   if (c === Compass.S) return Compass.N;\n   if (c === Compass.E) return Compass.W;\n   if (c === Compass.W) return Compass.E;\n   throw new Error(\"unreachable code was run\");\n}\n```\n\nThe above module will work out-of-the-box in Node.js (assuming  https://github.com/nodejs/typescript/issues/17).\n\n\n### 💻 Use Cases\n\n1. What do you want to use this for?\n\nCreating an enum like value using standard Object literal syntax with some of the type system benefits that `enum` syntax has.\n\n2. What shortcomings exist with current approaches?\n\n- `typeof Foo[keyof typeof Foo]` is not beginner friendly and is not a nominal type\n\n3. What workarounds are you using in the meantime?\n\nOne workaround is to have a small utility for emulating an enum like nominal type from an object literal ([playground](https://www.typescriptlang.org/play/?ts=5.7.2#code/FAEwpgxgNghgTmABBA9gOwM4BdEFE0CuAtgMoCeRAXIgWgJYCOBSGFARilANzBZkAOSfMQBicFEQA8AFURgAHljBoQGRAG8AvgD5EAXkSyFSlWvWIA2v3H9q2OHTQBzALrVHAMzBw8iTYgB+X2o0MAA3bx5gD1oILDp0PEIpVEwcI0VlVUQAJUgUOBBJe0cnABpEEudEAB9EZLZvbW0ACgxBCGppAEpqcwQYEHQoMksAa0RHRDGwMhQPQzdDCzGXRAAyDUthUgolmbmF6X9-dWBEC8QELAI4NEqOxBg1GDQyHk1gYAV+ApxU7CIADCEn4zzUBh2LTOFwActQAESwhEVEiIkgovCI3CYgDqiNxCOAmm6PB+f0QfEEwNB4P0SVE4ikVLA8xpRDBGAw2h4QA)). The `\"literal\" \u0026 { __key__: val }` trick _works_ but results in _noisey_ types when displayed to the developer (e.g. in an error message)\n","author":{"url":"https://github.com/acutmore","@type":"Person","name":"acutmore"},"datePublished":"2024-12-17T16:29:54.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":8},"url":"https://github.com/60790/TypeScript/issues/60790"}