From ec563dbd5f4904b9193bea442da9aac857c8ba60 Mon Sep 17 00:00:00 2001 From: Kirk Waiblinger Date: Fri, 20 Sep 2024 13:21:59 -0600 Subject: [PATCH 1/3] docs: [no-unsafe-enum-comparison] clarify motivation and applicability --- .../docs/rules/no-unsafe-enum-comparison.mdx | 122 +++++++++++++++--- .../no-unsafe-enum-comparison.shot | 5 + 2 files changed, 108 insertions(+), 19 deletions(-) diff --git a/packages/eslint-plugin/docs/rules/no-unsafe-enum-comparison.mdx b/packages/eslint-plugin/docs/rules/no-unsafe-enum-comparison.mdx index 7988317b5b6d..3ba2947dedff 100644 --- a/packages/eslint-plugin/docs/rules/no-unsafe-enum-comparison.mdx +++ b/packages/eslint-plugin/docs/rules/no-unsafe-enum-comparison.mdx @@ -9,23 +9,82 @@ import TabItem from '@theme/TabItem'; > > See **https://typescript-eslint.io/rules/no-unsafe-enum-comparison** for documentation. -The TypeScript compiler can be surprisingly lenient when working with enums. String enums are widely considered to be safer than number enums, but even string enums have some pitfalls. For example, it is allowed to compare enum values against literals: - -```ts -enum Vegetable { - Asparagus = 'asparagus', -} - -declare const vegetable: Vegetable; - -vegetable === 'asparagus'; // No error -``` - -The above code snippet should instead be written as `vegetable === Vegetable.Asparagus`. Allowing literals in comparisons subverts the point of using enums in the first place. By enforcing comparisons with properly typed enums: - -- It makes a codebase more resilient to enum members changing values. -- It allows for code IDEs to use the "Rename Symbol" feature to quickly rename an enum. -- It aligns code to the proper enum semantics of referring to them by name and treating their values as implementation details. +The TypeScript compiler can be surprisingly lenient when working with enums. +While overt unsafety problems with enums were [resolved in TypeScript 5.0](https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#all-enums-are-union-enums), some logical pitfalls remain permitted: + +1. Comparing an enum to its literal runtime value: + + ```ts + enum Vegetable { + Arugula = 0, + Spinach = 1, + } + + function makeSalad(vegetable: Vegetable) { + switch (vegetable) { + case 0: + console.log('Making Arugula Salad'); + break; + case 1: + console.log('Making Spinach Salad'); + break; + } + } + ``` + + The above code will break if the enum values change... + + ```ts + enum Vegetable { + Arugula = 1, + Spinach = 0, + } + + makeSalad(Vegetable.Spinach); // Prints 'Making Arugula Salad' + ``` + + ...whereas the code would have continued to work if written without explicit reference to the enum values: + + ```ts + function makeSalad(vegetable: Vegetable) { + switch (vegetable) { + case Vegetable.Arugula: + console.log('Making Arugula Salad'); + break; + case Vegetable.Spinach: + console.log('Making Spinach Salad'); + break; + } + } + ``` + + Note that using this style of comparison also allows for better IDE support, such as the "Rename Symbol" feature. + +2. Comparing an enum to a non-enum type: + + ```ts + enum HandleAction { + Open = 'OPEN', + Close = 'CLOSE', + } + + function handleAction(action: string) { + if (action === HandleAction.Open) { + openFile(); + } else if (action === HandleAction.Close) { + closeFile(); + } + } + ``` + + This pattern is extremely brittle. + It will break without complaints from the compiler if the enum values change, as before, or if the caller makes a typo: + + ```ts + handleAction('open'); // No error, but completely useless. + ``` + +This rule enforces the proper enum semantics of referring to them by name and treating their values as implementation details. ## Examples @@ -50,6 +109,10 @@ enum Vegetable { declare let vegetable: Vegetable; vegetable === 'asparagus'; + +declare let anyString: string; + +anyString === Vegetable.Asparagus; ``` @@ -80,7 +143,28 @@ vegetable === Vegetable.Asparagus; ## When Not To Use It -If you don't mind number and/or literal string constants being compared against enums, you likely don't need this rule. +If you don't mind enums being treated as a namespaced bag of values, rather than opaque identifiers, you likely don't need this rule. + +Sometimes, you may want to ingest a value from an API or user input, then use it as an enum throughout your application. +While validating the input, it may be appropriate to disable the rule; use your judgement as to what makes sense in your application. +For example: + +```ts +/* eslint-disable @typescript-eslint/no-unsafe-enum-comparison */ +function toVegetable(vegetable: string): Vegetable { + if (vegetable === Vegetable.Asparagus) { + return Vegetable.Asparagus; + } else if (vegetable === Vegetable.Broccoli) { + return Vegetable.Broccoli; + } /* etc */ else { + throw new Error('Invalid vegetable'); + } +} +/* eslint-enable @typescript-eslint/no-unsafe-enum-comparison */ +``` + +Alternately, you might consider making use of a validation library like [Zod](https://zod.dev/?id=native-enums). +See further discussion of this topic in [#8557](https://github.com/typescript-eslint/typescript-eslint/issues/8557). -Separately, in the rare case of relying on an third party enums that are only imported as `type`s, it may be difficult to adhere to this rule. +Finally, in the rare case of relying on an third party enums that are only imported as `type`s, it may be difficult to adhere to this rule. You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for those specific situations instead of completely disabling this rule. diff --git a/packages/eslint-plugin/tests/docs-eslint-output-snapshots/no-unsafe-enum-comparison.shot b/packages/eslint-plugin/tests/docs-eslint-output-snapshots/no-unsafe-enum-comparison.shot index 2d883379f083..a0a5e9585509 100644 --- a/packages/eslint-plugin/tests/docs-eslint-output-snapshots/no-unsafe-enum-comparison.shot +++ b/packages/eslint-plugin/tests/docs-eslint-output-snapshots/no-unsafe-enum-comparison.shot @@ -25,6 +25,11 @@ declare let vegetable: Vegetable; vegetable === 'asparagus'; ~~~~~~~~~~~~~~~~~~~~~~~~~ The two values in this comparison do not have a shared enum type. + +declare let anyString: string; + +anyString === Vegetable.Asparagus; +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The two values in this comparison do not have a shared enum type. " `; From 0222c256f14a6ce62241ee362bdb044abe715749 Mon Sep 17 00:00:00 2001 From: Kirk Waiblinger Date: Sun, 29 Sep 2024 13:55:23 -0600 Subject: [PATCH 2/3] simplify changes --- .../docs/rules/no-unsafe-enum-comparison.mdx | 120 ++++-------------- .../no-unsafe-enum-comparison.shot | 15 +-- 2 files changed, 28 insertions(+), 107 deletions(-) diff --git a/packages/eslint-plugin/docs/rules/no-unsafe-enum-comparison.mdx b/packages/eslint-plugin/docs/rules/no-unsafe-enum-comparison.mdx index 3ba2947dedff..82c67c5579cb 100644 --- a/packages/eslint-plugin/docs/rules/no-unsafe-enum-comparison.mdx +++ b/packages/eslint-plugin/docs/rules/no-unsafe-enum-comparison.mdx @@ -10,81 +10,26 @@ import TabItem from '@theme/TabItem'; > See **https://typescript-eslint.io/rules/no-unsafe-enum-comparison** for documentation. The TypeScript compiler can be surprisingly lenient when working with enums. -While overt unsafety problems with enums were [resolved in TypeScript 5.0](https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#all-enums-are-union-enums), some logical pitfalls remain permitted: - -1. Comparing an enum to its literal runtime value: - - ```ts - enum Vegetable { - Arugula = 0, - Spinach = 1, - } - - function makeSalad(vegetable: Vegetable) { - switch (vegetable) { - case 0: - console.log('Making Arugula Salad'); - break; - case 1: - console.log('Making Spinach Salad'); - break; - } - } - ``` - - The above code will break if the enum values change... - - ```ts - enum Vegetable { - Arugula = 1, - Spinach = 0, - } - - makeSalad(Vegetable.Spinach); // Prints 'Making Arugula Salad' - ``` - - ...whereas the code would have continued to work if written without explicit reference to the enum values: - - ```ts - function makeSalad(vegetable: Vegetable) { - switch (vegetable) { - case Vegetable.Arugula: - console.log('Making Arugula Salad'); - break; - case Vegetable.Spinach: - console.log('Making Spinach Salad'); - break; - } - } - ``` - - Note that using this style of comparison also allows for better IDE support, such as the "Rename Symbol" feature. - -2. Comparing an enum to a non-enum type: - - ```ts - enum HandleAction { - Open = 'OPEN', - Close = 'CLOSE', - } - - function handleAction(action: string) { - if (action === HandleAction.Open) { - openFile(); - } else if (action === HandleAction.Close) { - closeFile(); - } - } - ``` - - This pattern is extremely brittle. - It will break without complaints from the compiler if the enum values change, as before, or if the caller makes a typo: - - ```ts - handleAction('open'); // No error, but completely useless. - ``` - -This rule enforces the proper enum semantics of referring to them by name and treating their values as implementation details. +While overt unsafety problems with enums were [resolved in TypeScript 5.0](https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#all-enums-are-union-enums), some logical pitfalls remain permitted. +For example, it is allowed to compare enum values against non-enum values: + +```ts +enum Vegetable { + Asparagus = 'asparagus', +} + +declare const vegetable: Vegetable; + +vegetable === 'asparagus'; // No error +``` + +The above code snippet should instead be written as `vegetable === Vegetable.Asparagus`. +Allowing non-enums in comparisons subverts the point of using enums in the first place. +By enforcing comparisons with properly typed enums: + +- It makes a codebase more resilient to enum members changing values. +- It allows for code IDEs to use the "Rename Symbol" feature to quickly rename an enum. +- It aligns code to the proper enum semantics of referring to them by name and treating their values as implementation details. ## Examples @@ -98,20 +43,21 @@ enum Fruit { declare let fruit: Fruit; +// bad - comparison between enum and explicit value instead of named enum member fruit === 0; -``` -```ts enum Vegetable { Asparagus = 'asparagus', } declare let vegetable: Vegetable; +// bad - comparison between enum and explicit value instead of named enum member vegetable === 'asparagus'; declare let anyString: string; +// bad - comparison between enum and non-enum value anyString === Vegetable.Asparagus; ``` @@ -126,9 +72,7 @@ enum Fruit { declare let fruit: Fruit; fruit === Fruit.Apple; -``` -```ts enum Vegetable { Asparagus = 'asparagus', } @@ -146,23 +90,7 @@ vegetable === Vegetable.Asparagus; If you don't mind enums being treated as a namespaced bag of values, rather than opaque identifiers, you likely don't need this rule. Sometimes, you may want to ingest a value from an API or user input, then use it as an enum throughout your application. -While validating the input, it may be appropriate to disable the rule; use your judgement as to what makes sense in your application. -For example: - -```ts -/* eslint-disable @typescript-eslint/no-unsafe-enum-comparison */ -function toVegetable(vegetable: string): Vegetable { - if (vegetable === Vegetable.Asparagus) { - return Vegetable.Asparagus; - } else if (vegetable === Vegetable.Broccoli) { - return Vegetable.Broccoli; - } /* etc */ else { - throw new Error('Invalid vegetable'); - } -} -/* eslint-enable @typescript-eslint/no-unsafe-enum-comparison */ -``` - +While validating the input, it may be appropriate to disable the rule. Alternately, you might consider making use of a validation library like [Zod](https://zod.dev/?id=native-enums). See further discussion of this topic in [#8557](https://github.com/typescript-eslint/typescript-eslint/issues/8557). diff --git a/packages/eslint-plugin/tests/docs-eslint-output-snapshots/no-unsafe-enum-comparison.shot b/packages/eslint-plugin/tests/docs-eslint-output-snapshots/no-unsafe-enum-comparison.shot index a0a5e9585509..3b26a4df1d59 100644 --- a/packages/eslint-plugin/tests/docs-eslint-output-snapshots/no-unsafe-enum-comparison.shot +++ b/packages/eslint-plugin/tests/docs-eslint-output-snapshots/no-unsafe-enum-comparison.shot @@ -9,13 +9,9 @@ enum Fruit { declare let fruit: Fruit; +// bad - comparison between enum and explicit value instead of named enum member fruit === 0; ~~~~~~~~~~~ The two values in this comparison do not have a shared enum type. -" -`; - -exports[`Validating rule docs no-unsafe-enum-comparison.mdx code examples ESLint output 2`] = ` -"Incorrect enum Vegetable { Asparagus = 'asparagus', @@ -23,17 +19,19 @@ enum Vegetable { declare let vegetable: Vegetable; +// bad - comparison between enum and explicit value instead of named enum member vegetable === 'asparagus'; ~~~~~~~~~~~~~~~~~~~~~~~~~ The two values in this comparison do not have a shared enum type. declare let anyString: string; +// bad - comparison between enum and non-enum value anyString === Vegetable.Asparagus; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The two values in this comparison do not have a shared enum type. " `; -exports[`Validating rule docs no-unsafe-enum-comparison.mdx code examples ESLint output 3`] = ` +exports[`Validating rule docs no-unsafe-enum-comparison.mdx code examples ESLint output 2`] = ` "Correct enum Fruit { @@ -43,11 +41,6 @@ enum Fruit { declare let fruit: Fruit; fruit === Fruit.Apple; -" -`; - -exports[`Validating rule docs no-unsafe-enum-comparison.mdx code examples ESLint output 4`] = ` -"Correct enum Vegetable { Asparagus = 'asparagus', From cf986cfa07c8ba55e312c9e797e9a44b850be692 Mon Sep 17 00:00:00 2001 From: Kirk Waiblinger Date: Sun, 29 Sep 2024 16:55:15 -0600 Subject: [PATCH 3/3] unsafety lol MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Josh Goldberg ✨ --- packages/eslint-plugin/docs/rules/no-unsafe-enum-comparison.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/eslint-plugin/docs/rules/no-unsafe-enum-comparison.mdx b/packages/eslint-plugin/docs/rules/no-unsafe-enum-comparison.mdx index 82c67c5579cb..4b25e785e87d 100644 --- a/packages/eslint-plugin/docs/rules/no-unsafe-enum-comparison.mdx +++ b/packages/eslint-plugin/docs/rules/no-unsafe-enum-comparison.mdx @@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem'; > See **https://typescript-eslint.io/rules/no-unsafe-enum-comparison** for documentation. The TypeScript compiler can be surprisingly lenient when working with enums. -While overt unsafety problems with enums were [resolved in TypeScript 5.0](https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#all-enums-are-union-enums), some logical pitfalls remain permitted. +While overt safety problems with enums were [resolved in TypeScript 5.0](https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#all-enums-are-union-enums), some logical pitfalls remain permitted. For example, it is allowed to compare enum values against non-enum values: ```ts pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy