stash

Author: MajorLift

docs/typescript.md

@@ -39,3 +39,92 @@ 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`)
+
+A. 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.
+- Type Guards
+- Non-Null Assertions
+
+B. 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.
+
+C. Type Assertions (`as`)
+
+- `as` assertions intended to exclude an empty/nullable type can be replaced by a nullish coalescing operator converting nullable values into an acceptable empty value that doesn't pollute the variable's type signature.
+
+```ts
+(arr as string[])
+(arr ?? [])
+```
+
+- Acceptable usages of `as`
+
+  - 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.
+
+D. 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.
+  - If what's needed is a type that could be "anything," `unknown` should be used.
+    - When typing the assignee, `any` and `unknown` are interchangeable (every type is assignable to both).
+    - When typing the assigned, `unknown` is `any` is assignable to all types, while `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*.
+
+- If no good typing solution can be found, using forced type casting with the `as` keyword or even `as unknown as` is much preferable to using `any`:
+  - At least we get working intellisense, autocomplete.
+  - We also get an indication of the expected type as intended by the author.
+
+- Function supertype (assignable to any function):
+
+  ```ts
+  (...args: any[]) => any // 🚫
+  (...args: never[]) => unknown // ✅
+  ```
+
+- Acceptable usages of `any`
+  
+  - 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` .
+  
+  - In tests, for mocking or to intentionally break features.
+    - Recommended: Provide accurate typing through assertions wherever possible.