lots of refinement

Author: audreyality

custom-words.txt

@@ -79,6 +79,8 @@ subprocessor
 toolset
 TOTP
 typealias
+typecheck
+typechecks
 typesafe
 WCAG
 Xcodes.app

docs/architecture/adr/0025-ts-deprecate-enums.md

@@ -29,13 +29,13 @@ TypeScript deprecation can be linted using a fairly short ESLint plugin. The cod
 contributed to main][no-enum-lint] as a suggestion. The same PR adds `FIXME` comments for each team
 to address.
 
-### Replacement pattern
+### The Enum-like Pattern
 
 In most cases, enums are unnecessary. A readonly (`as const`) object coupled with a type alias
 avoids both code generation and type inconsistencies.
 
 ```ts
-// declare the raw data and reduce repetition with an inner type
+// declare the raw data and reduce repetition with an internal type
 const _CipherType = {
   Login: 1,
   SecureNote: 2,
@@ -50,67 +50,37 @@ type _CipherType = typeof _CipherType;
 export type CipherType = _CipherType[keyof _CipherType];
 
 // assert that the raw data is of the enum-like type
-export const CipherType: Readonly<{ [K in keyof typeof _CipherType]: CipherType }> =
+export const CipherType: Readonly<{ [K in keyof _CipherType]: CipherType }> =
   Object.freeze(_CipherType);
 ```
 
-This code creates a type `CipherType` that allows arguments and variables to be typed similarly to
-an enum. It also strongly types the `CiperType` constant so that direct accesses of its members
-preserve type safety. No type assertions are needed to work directly with `CipherType`.
-
-This pattern has two negative consequences. First, mapped types cannot determine that a mapped type
-is fully specified. Code like the following causes a compiler error:
+This code creates a `type CipherType` that allows arguments and variables to be typed similarly to
+an enum. It also strongly types the `const CiperType` so that direct accesses of its members
+preserve type safety. This ensures that type inference properly limits the accepted values to those
+allowed by `type CipherType`. Without the type assertion, the compiler infers `number` in these
+cases:
 
 ```ts
-type MappedType = { [K in CipherType]: boolean };
-
-const instance: MappedType = {
-  [CipherType.Login]: true,
-  [CipherType.SecureNote]: true,
-  [CipherType.Card]: true,
-  [CipherType.Identity]: true,
-  [CipherType.SshKey]: true,
-};
+const s = new Subject(CipherType.Login); // `s` is a `Subject<CipherType>`
+const a = [CipherType.Login, CipherType.Card]; // `a` is an `Array<CipherType>`
+const m = new Map([[CipherType.Login, ""]]); // `m` is a `Map<CipherType, string>`
 ```
 
-This happens because each enum members' literal type is overridden by `CipherType`. The compiler
-cannot determine that every kind of `CipherType` is listed. There are a few workarounds:
+:::warning
 
-```ts
-// option A: use a type assertion to construct the mapped type
-const instance: MappedType = {
-  [CipherType.Login]: true,
-  // ...
-} as MappedType;
+- Types that use enums like [computed property names][computed-property-names] issue a compiler
+  error with this pattern. [This issue is fixed as of TypeScript 5.8][no-member-fields-fixed].
+- Certain objects are more difficult to create with this pattern. This is explored in
+  [Appendix A](#appendix-a-mapped-types-and-enum-likes).
 
-// option B: make the type partial and it fully typechecks, but you
-//   need to inspect its properties to use them.
-type PartialMappedType = { [K in CipherType]?: boolean };
-const instance = {
-  [CipherType.Login]: true,
-  // ...
-};
-if (instance[CipherType.Login]) {
-  // work with `instance`
-}
-```
-
-The other problem is that mapped types cannot specify the enum-like's members as field names. Code
-like the following causes a compiler error:
-
-```ts
-type SomeType = { [CipherType.SecureNote]: boolean };
-```
-
-[This issue is fixed as of TypeScript 5.8][no-member-fields-fixed] and won't be explored further in
-this document.
+:::
 
 ## Considered Options
 
 - **Allow enums, but advise against them** - This is the current state of affairs. With this option,
   teams **must** address the FIXMEs, but _may_ address them by disabling the lint.
-- **Deprecate enum use** - Allow enums to exist for historic purposes, but prohibit the introduction
-  of new ones. Increase the lint to a "warning" and allow the lint to be disabled.
+- **Deprecate enum use** - Allow enums to exist for historic or technical purposes, but prohibit the
+  introduction of new ones. Increase the lint to a "warning" and allow the lint to be disabled.
 - **Eliminate enum use** - Prohibit the introduction of any new enum and replace all enums in the
   codebase with typescript objects. Increase the lint to an "error" and prohibit disabling of the
   lint.
@@ -124,19 +94,103 @@ Chosen option: **Deprecate enum use**
 - Allows for cases where autogenerated code introduces an enum by necessity.
 - Developers receive a warning in their IDE to discourage new enums.
 - The warning can direct them to our contributing docs, where they can learn typesafe alternatives.
-- Over time, our code size decreases as enums are replaced.
+- Our compiled code size decreases when enums are replaced.
 - If all teams eliminate enums in practice, the warning can be increased to an error.
 
 ### Negative Consequences
 
 - Unnecessary usage may persist indefinitely on teams carrying a high tech debt.
-- The lint increases the number of FIXME comments in the code by about 10%.
+- The lint increased the number of FIXME comments in the code by about 10%.
 
 ### Plan
 
 - Update contributing docs with patterns and best practices for enum replacement.
 - Update the reporting level of the lint to "warning".
 
+[computed-property-names]:
+  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer#computed_property_names
+[literal-type]: https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types
 [no-enum-lint]: https://github.com/bitwarden/clients/blob/main/libs/eslint/platform/no-enums.mjs
 [no-member-fields-fixed]:
   https://devblogs.microsoft.com/typescript/announcing-typescript-5-8-beta/#preserved-computed-property-names-in-declaration-files
+
+## Appendix A: Mapped Types and Enum-likes
+
+Mapped types cannot determine that a mapped enum-like object is fully specified. Code like the
+following causes a compiler error:
+
+```ts
+const instance: Record<CipherType, boolean> = {
+  [CipherType.Login]: true,
+  [CipherType.SecureNote]: false,
+  [CipherType.Card]: true,
+  [CipherType.Identity]: true,
+  [CipherType.SshKey]: true,
+};
+```
+
+#### Why does this happen?
+
+The members of `const _CipherType` all have a literal type. `_CipherType.Login`, for example, has a
+[literal type][literal-type] of `1`. `type CipherType` maps over these members, aggregating them
+into the structural type `1 | 2 | 3 | 4 | 5`.
+
+`const CipherType` asserts its members have `type CipherType`, which overrides the literal types the
+compiler inferred for the member in `const _CipherType`. The compiler sees the type of
+`CipherType.Login` as `type CipherType` (which aliases `1 | 2 | 3 | 4 | 5`).
+
+Now consider a mapped type definition:
+
+```ts
+// `MappedType` is structurally identical to Record<CipherType, boolean>
+type MappedType = { [K in CipherType]: boolean };
+```
+
+When the compiler examines `instance`, it only knows that the type of each of its members is
+`CipherType`. That is, the type of `instance` to the compiler is
+`{ [K in 1 | 2 | 3 | 4 | 5]?: boolean }`. This doesn't sufficiently overlap with `MappedType`, which
+is looking for `{ [1]: boolean, [2]: boolean, [3]: boolean, [4]: boolean, [5]: boolean }`. The
+failure occurs, because the inferred type can have fewer fields than `MappedType`.
+
+### Workarounds
+
+**Option A: Assert the type is correct.** You need to manually verify this. The compiler cannot
+typecheck it.
+
+```ts
+const instance: MappedType = {
+  [CipherType.Login]: true,
+  // ...
+} as MappedType;
+```
+
+**Option B: Define the mapped type as a partial.** Then, inspect its properties before using them.
+
+```ts
+type MappedType = { [K in CipherType]?: boolean };
+const instance: MappedType = {
+  [CipherType.Login]: true,
+  // ...
+};
+
+if (CipherType.Login in instance) {
+  // work with `instance[CipherType.Login]`
+}
+```
+
+**Option C: Use a collection.** Consider this approach when downstream code reflects over the result
+with `in` or using methods like `Object.keys`.
+
+```ts
+const collection = new Map([[CipherType.Login, true]]);
+
+const instance = collection.get(CipherType.Login);
+if (instance) {
+  // work with `instance`
+}
+
+const available = [CipherType.Login, CipherType.Card];
+if (available.includes(CipherType.Login)) {
+  // ...
+}
+```