stash

Author: MajorLift

docs/typescript.md

@@ -39,3 +39,100 @@ async function removeAccount(address: Hex): Promise<KeyringControllerState> {
   return this.fullUpdate();
 }
 ```
+
+## Overriding Types
+
+- Order of preference: `infer` > `:` > `as` > `any`
+- Provide explanation via comment when explicitly casting types or overriding related eslint rules (e.g. forbid `any`, forbid `non-null assertions`)
+
+### 1. Type Inference
+
+- Prefer type inference: Inferences are responsive to changes in code, while assertions rely on brittle hard-coding. 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.
+
+- Generic Parameters
+  - `Object.entries`
+  - `Array.prototype.reduce`
+- Type Narrowing
+  - In some cases, type assertions can be replaced with type narrowing with type guards and null checks.
+
+### 2. Type Annotations (`:`)
+
+- If a type constraint needs to be imposed, prefer the `satisfies` keyword (for TypeScript v4.9+), since it allows type inference to a more narrow type.
+- `:` type declarations also enable type constraints to be imposed, but don't allow narrowing by inference.
+
+### 3. Type Assertions (`as`, `!`)
+
+- `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 usages 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.
+  - To define user-defined type guards: https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates
+  - To type inputs/outputs that are defined 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 usages 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.
+
+### 4. Disable Type Checking (`any`)
+
+- `any` doesn't actually represent the widest type. It's a compiler setting to disable type checking for the value and/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_.
+
+- Function supertype (assignable to any function):
+
+  ```ts
+  (...args: any[]) => any // 🚫
+  (...args: never[]) => unknown // ✅
+  ```
+
+#### Acceptable use cases
+
+- Assigning new properties to an object or class at runtime:
+
+  ```ts
+  (this as any)[key] = obj[key];
+  ```
+
+- 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 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 the object is used elsewhere instead of just being thrown.
+
+- In tests, for mocking or to intentionally break features.
+  - Recommended: Provide accurate typing wherever possible.