Add note to typescript guide

Author: MajorLift

docs/typescript.md

@@ -974,14 +974,19 @@ The concept of the interface as discussed in this section is not to be confused
 
 TypeScript offers several tools for crafting clear data definitions, with enumerations and unions standing as popular choices.
 
-#### Consider using enums over union types for situations with a fixed set of known values.
+> [!NOTE]
+> `enum` syntax is being phased out of TypeScript. v5.8 introduces a new flag `erasableSyntaxOnly`, which will mark enums as errors (along with namespaces and class parameter properties).
+>
+> The recommended alternative is to use objects defined with the `as const` keyword (see https://www.typescriptlang.org/docs/handbook/enums.html#objects-vs-enums).
+
+#### Consider using `as const` objects over union types when enumerating a fixed set of known values.
 
 Inevitably you will want to refer to the values of a union type somewhere (perhaps as the argument to a function). You can of course just use a literal which represents a member of that union — but if you have an enum, then all of the values are special, and any time you use a value then anyone can see where that value comes from.
 
 🚫
 
 ```typescript
-type UserRole = 'admin' | 'editor' | 'subscriber';
+type AccountTypes = 'admin' | 'user' | 'guest';
 ```
 
 ✅
@@ -992,6 +997,9 @@ enum AccountType {
   User = 'user',
   Guest = 'guest',
 }
+
+// 'admin' | 'user' | 'guest'
+type AccountTypes = `${AccountType};
 ```
 
 #### Don't use numeric enums
@@ -1025,9 +1033,28 @@ const directions = Object.values(Direction); // ["Up", "Down", "Left", "Right"]
 
 ## Functions
 
-#### For functions and methods, provide explicit return types
+#### Avoid return type annotations for functions and methods. Instead, prefer `satisfies` and the JSDoc `@returns` tag.
+
+Explicit return type annotations on functions overwrite narrower types inferred by the compiler
+
+can artificially widen the function's type signature, resulting in a loss of type information. Relying on type inference guarantees . 
+
+> Enforcing a wider type defeats the purpose of adding an explicit type declaration, as it loses type information instead of adding it.
+>
+> -- https://github.com/MetaMask/contributor-docs/blob/main/docs/typescript.md#avoid-unintentionally-widening-an-inferred-type-with-a-type-annotation
+
+There are two ways that explicit function return types can be useful. Fortunately there are 
 
-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.
+
+
+1. 
+
+Unfortunately, this comes at 
+
+ artificially widen the return type
+
+
+makes it much easier for the reader to see the API from the code alone and prevents unexpected changes to the API from emerging.
 
 **Example <a id="example-a88b18ef-b066-4aa7-8106-bc244298f9e6"></a> ([🔗 permalink](#example-a88b18ef-b066-4aa7-8106-bc244298f9e6)):**
 
@@ -1051,7 +1078,7 @@ async function removeAccount(address: Hex) {
 ✅
 
 ```typescript
-async function removeAccount(address: Hex): Promise<KeyringControllerState> {
+async function removeAccount(address: Hex) {
   const keyring = await this.getKeyringForAccount(address);
 
   if (!keyring.removeAccount) {
@@ -1061,7 +1088,7 @@ async function removeAccount(address: Hex): Promise<KeyringControllerState> {
   this.emit('removedAccount', address);
 
   await this.persistAllKeyrings();
-  return this.fullUpdate();
+  return this.fullUpdate() satisfies KeyringControllerState;
 }
 ```