Recommend same type and value name for enums (#607)

* feat: recommend same type and value names

Use the same name for the type and the value allows us to emulate regular Enums much better.

* feat: merge with @audreyality version from #605

Co-authored-by: ✨ Audrey ✨ <ajensen@bitwarden.com>

* fix: remove broken link

* fix: change name -> value

Co-authored-by: ✨ Audrey ✨ <ajensen@bitwarden.com>

---------

Co-authored-by: ✨ Audrey ✨ <ajensen@bitwarden.com>

Author: coroiu

docs/contributing/code-style/enums.md

@@ -1,25 +1,87 @@
-# TypeScript Const Enums
+# Avoid TypeScript Enums
 
-We don't use Typescript enums because they are not fully type-safe and can cause surprises. Instead
-of using enums, we use constant objects.
+TypeScript enums are not fully type-safe and can [cause surprises][enum-surprises]. Your code should
+use [constant objects][constant-object-pattern] instead of introducing a new enum.
 
 ## Our Recommended Approach
 
+- Use the same name for your type- and value-declaration.
+- Use `type` to derive type information from the const object.
+- Create utilities to convert and identify enums modelled as primitives.
+
+:::tip
+
+This pattern should simplify the usage of your new objects, improve type safety in files that have
+adopted TS-strict, and make transitioning an enum to a const object much easier.
+
+:::
+
+### Example
+
+Given the following enum:
+
 ```ts
-export const PasskeyActions = {
-  Register: "register",
-  Authenticate: "authenticate",
+export enum CipherType = {
+  Login: 1,
+  SecureNote: 2,
+  Card: 3,
+  Identity: 4,
+  SshKey: 5,
+};
+```
+
+You can redefine it as an object like so:
+
+```ts
+const _CipherType = {
+  Login: 1,
+  SecureNote: 2,
+  Card: 3,
+  Identity: 4,
+  SshKey: 5,
 } as const;
 
-export type PasskeyActionValue = (typeof PasskeyActions)[keyof typeof PasskeyActions];
+type _CipherType = typeof _CipherType;
+
+export type CipherType = _CipherType[keyof _CipherType];
+export const CipherType: Readonly<{ [K in keyof typeof _CipherType]: CipherType }> =
+  Object.freeze(_CipherType);
+```
+
+And use it like so:
+
+```ts
+// Can be imported together
+import { CipherType } from "./cipher-type";
 
-declare function usePasskeyAction(action: PasskeyActionValue): void;
+// Used as a type
+function doSomething(type: CipherType) {}
 
-usePasskey(PasskeyActions.Register); // ✅ Valid
-usePasskey(0); // ❌ Invalid
+// And used as a value (just like a regular `enum`)
+doSomething(CipherType.Card);
 ```
 
-## Resources Used
+The following utilities may assist introspection:
+
+```ts
+import { CipherType } from "./cipher-type";
+
+const namesByCipherType = new Map<CipherType, keyof CipherType>(
+  Array.fromEntries(Object.entries(CipherType), ([k, v]) => [v, k]),
+);
+
+export function isCipherType(value: number): value is CipherType {
+  return namesByCipherType.has(value);
+}
+
+export function asCipherType(value: number): CipherType | undefined {
+  return isCipherType(value) ? value : undefined;
+}
+
+export function nameOfCipherType(value: CipherType): keyof CipherType | undefined {
+  return namesByCipherType.get(value);
+}
+```
 
-- https://dev.to/ivanzm123/dont-use-enums-in-typescript-they-are-very-dangerous-57bh
-- https://www.typescriptlang.org/docs/handbook/enums.html#objects-vs-enums
+[enum-surprises]: https://dev.to/ivanzm123/dont-use-enums-in-typescript-they-are-very-dangerous-57bh
+[constant-object-pattern]: https://www.typescriptlang.org/docs/handbook/enums.html#objects-vs-enums