stash

Author: MajorLift

docs/typescript.md

@@ -2,13 +2,134 @@
 
 These guidelines specifically apply to TypeScript.
 
-## Provide explicit return types for functions/methods
+## I. Types
+
+- Type Inference
+- Type Annotations
+  - `:` operator
+  - `as const` keyword
+  - `satisfies` operator
+  - Generic type arguments (`<>`)
+- Type Assertions
+  - `as` operator
+  - `!` operator
+- Compiler Directives for Disabling Type Checking
+  - `@ts-expect-error` directive
+  - `@ts-ignore` directive
+  - `any` keyword
+
+### A. Type Inference vs. Type Declarations
+
+In general, type inference is preferable over type declarations and , unless explicit typing results in narrower, more accurate types.
+
+- Type annotations (`:`) and type assertions (`as`, `!`) prevent inference-based narrowing of the user-supplied type.
+- Type inferences are responsive to changes in code, while annotations and assertions rely on brittle hard-coding.
+
+🚫 Type declarations
+
+```ts
+const name: string = 'METAMASK'; // Type 'string'
+const BUILT_IN_NETWORKS = new Map<string, `0x${string}`>([
+  ['mainnet', '0x1'], 
+  ['goerli', '0x5'],
+]); // Type 'Map<string, `0x${string}`>'
+```
+
+✅ Type inferences
+
+```ts
+const name = 'METAMASK'; // Type 'METAMASK'
+const BUILT_IN_NETWORKS = {
+  mainnet: '0x1',
+  goerli: '0x5',
+} as const; // Type { readonly mainnet: '0x1'; readonly goerli: '0x5'; }
+```
+
+### B. Type Narrowing
+
+That said, if there is opportunity to narrow a type with an explicit type declaration, it should be taken.
+
+##### `as const`, `satisfies` can be used to further narrow inferred types
+
+- Link to `as const` entry
+- `satisfies`: coming soon
+
+##### When initializing an empty container type, provide a type annotation
+
+- The compiler cannot arbitrarily restrict the range of types that can be inserted into the container, and therefore needs to assume the widest type.
+
+```ts
+const tokens = []; // 🚫 Type 'any[]'
+const tokens: string[] = []; // ✅ Type 'string[]' 
+```
+
+#### Generic parameters can be used to narrow types
+
+- A type with generic parameter(s) that can be omitted may sometimes be written to correctly infer the parameter's type, but it may just as often use the widest possible type that satisfies the generic constraint as a default fallback value. This fallback can sometimes be `any`.
+
+🚫
+
+```ts
+arr.reduce((acc, { name, state }) => {
+  acc[name] = state
+  return acc
+}, {} as Record<string, (typeof arr)[number]['state']>)
+
+const NETWORKS = new Map({
+  'mainnet': '0x1', 
+  'goerli': '0x5',
+}); // Type 'Map<any, any>'
+
+const mockGetNetworkConfigurationByNetworkClientId = jest.fn(); // Type 'jest.Mock<any, any>'
+```
+
+✅
+
+```ts
+arr.reduce<Record<arr[number]['name'], arr[number]['state']>>((acc, { name, state }) => {
+  acc[name] = state
+  return acc
+}, {});
+
+const NETWORKS = new Map<string, `0x${string}`>({
+  'mainnet': '0x1', 
+  'goerli': '0x5',
+}); // Type 'Map<string, `0x${string}`>'
+
+const mockGetNetworkConfigurationByNetworkClientId = jest.fn<
+  ReturnType<NetworkController['getNetworkConfigurationByNetworkClientId']>,
+  Parameters<NetworkController['getNetworkConfigurationByNetworkClientId']>
+>(); // Type 'jest.Mock<NetworkConfiguration | undefined, [networkClientId: string]>'
+```
+
+##### Type guards and null checks can be used to improve type inference
+
+TypeScript types are erased (https://en.wikipedia.org/wiki/Type_erasure) during compilation. This means there is no built-in mechanism for performing runtime type checks.
+
+A popular method for runtime checks is to verify that properties exist on an object. You can use user-defined type guards to accomplish this:
+
+```ts
+function isSomeInterface(x: unknown): x is SomeInterface {
+  return 'name' in x 
+    && typeof x.name === 'string' 
+    && 'length' in x
+    && typeof x.length === 'number';
+}
+
+function f(x: SomeInterface | SomeOtherInterface) {
+  if (isSomeInterface(x)) {
+    console.log(x.name); // Cool!
+  }
+}
+```
+
+##### For functions and methods, provide explicit return types
 
 Although TypeScript is capable of inferring return types, adding them explicitly makes it much easier for the reader to see the API from the code alone and prevents unexpected changes to the API from emerging.
 
 🚫
 
-```javascript
+```ts
 async function removeAccount(address: Hex) {
   const keyring = await this.getKeyringForAccount(address);
 
@@ -25,7 +146,7 @@ async function removeAccount(address: Hex) {
 
 ✅
 
-```javascript
+```ts
 async function removeAccount(address: Hex): Promise<KeyringControllerState> {
   const keyring = await this.getKeyringForAccount(address);
 
@@ -39,3 +160,113 @@ async function removeAccount(address: Hex): Promise<KeyringControllerState> {
   return this.fullUpdate();
 }
 ```
+
+- Provide an explanation via comment when performing explicit type assertions or overriding related eslint rules (e.g. forbid `any`, forbid `non-null assertions`)
+
+### C. Type Assertions (`as`, `!`)
+
+`as` assertions and non-nullability assertions (`!`) are unsafe. They override type-checked and inferred types with user-supplied types that suppress compiler errors.
+
+While TypeScript will throw type errors against some unsafe or structurally unsound type assertion scenarios, it will generally accept the user-supplied type without type-checking. This can cause silent failures where errors are suppressed.
+
+- TypeScript and eslint will raise warnings against some unsafe or structurally unsound type assertions, but this capability is limited.
+- Type assertions make the code brittle against changes,
+
+- `as` assertions intended to exclude an empty/nullable type (e.g. `| undefined`) can be replaced with a nullish coalescing operator providing an acceptable fallback empty value that doesn't pollute the variable's type signature.
+
+```ts
+arr: string[] | undefined
+(arr as string[]) // 🚫
+(arr ?? []) // ✅
+
+s: string | undefined
+(s as string) // 🚫
+(s ?? '') // ✅
+```
+
+#### Acceptable use cases of `as`
+
+##### To prevent or fix `any` usage
+
+- At least we get working intellisense, autocomplete.
+- We also get an indication of the expected type as intended by the author.
+- For type assertions to an incompatible shape, use `as unknown as` as a last resort.
+
+##### To define user-defined type guards
+
+- https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates
+
+##### To type data objects whose shape and contents are determined at runtime
+
+- provided that schema validation is performed with type guards and unit tests
+- e.g. The output of `JSON.parse()` or `await response.json()` for a known JSON input.
+- e.g. The type of a JSON file.
+
+##### In tests, for mocking or to exclude irrelevant but required properties from an input object
+
+- Recommended: Provide accurate typing wherever possible.
+
+#### Acceptable use cases of `!`
+
+##### If type narrowing is not inferring the correct type
+
+##### If the variable is otherwise guaranteed to be non-nullable
+
+- Preferrably, leave a comment explaining why.
+
+### D. Compiler Directives for Disabling Type Checking (`any`, `@ts-ignore`, `@ts-expect-error`)
+
+- `any` doesn't actually represent the widest type. It's a compiler setting to *disable* type checking for the value or type to which it's assigned.
+
+- If `any` is used, and errors are introduced (or altered) by future changes to the code,
+  - The new or changed warnings will be suppressed, and the code will **fail silently**.
+
+- `any` infects all surrounding and downstream code.
+  - For instance, if you have a function that is declared to return any which actually returns an object, all properties of that object will be any.
+
+- `unknown` is the universal supertype i.e. the widest possible type.
+  - When typing the assignee, `any` and `unknown` are interchangeable (every type is assignable to both).
+  - When typing the assigned, `unknown` can't replace `any`, as `unknown` is only assignable to `unknown`.
+  - If replacing `any` with `unknown` doesn't work, the typing likely has underlying issues that *shouldn't be silenced*.
+
+#### Acceptable use cases of `any`
+
+##### Assigning new properties to a generic type at runtime
+
+- In most cases, `any` usage can be avoided by substituting with `as unknown as`.
+
+```ts
+for (const key of Object.keys(this.internalConfig) as (keyof C)[]) {
+  (this as unknown as C)[key] = this.internalConfig[key];
+}
+```
+
+- However, when assigning to a generic type, using `as any` is the only solution, unless the assignment itself can be avoided.
+
+```ts
+(state as RateLimitState<RateLimitedApis>).requests[api][origin] =
+  previous + 1;
+  // is generic and can only be indexed for reading.ts(2862)
+
+(state as any).requests[api][origin] =
+  previous + 1;
+```
+
+##### Within generic constraints
+
+```ts
+messenger extends RestrictedControllerMessenger<N, any, any, string, string>
+```
+
+- In general, using `any` in this context is not harmful in the same way that it is in other contexts, as the `any` types only are not directly assigned to any specific variable, and only function as constraints.
+- That said, narrower constraints provide better type safety and intellisense.
+
+##### Catching errors
+
+- `catch` only accepts `any` and `unknown` as the error type.
+- Recommended: Use `unknown` with type guards like `isJsonRpcError`.
+- Avoid typing an error object with `any` if it is used elsewhere instead of just being thrown.
+
+##### In tests, for mocking or to intentionally break features
+  
+- Recommended: Provide accurate typing wherever possible.