From b9fbb9c39e8c1e6260eec6b3024286ba862bdfc4 Mon Sep 17 00:00:00 2001
From: Erez Makavy <hepi.yellow@gmail.com>
Date: Sat, 10 Aug 2024 14:25:47 +0200
Subject: [PATCH] Caveats: Add Avoid Type Assertions section

---
 docs/caveats.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/caveats.md b/docs/caveats.md
index 4f15c47..91d4919 100644
--- a/docs/caveats.md
+++ b/docs/caveats.md
@@ -209,3 +209,35 @@ for (const featureClass of FEATURE_CLASSES) {
 ```
 
 Importatly, once we have a barrel file, we do not have to artificially split up the number of classes. This is because TSTL does not transpile exports with any local variables at all. Thus, we can have an unlimited number of exports inside of the barrel file without ever hitting the Lua local variable limit.
+
+### Avoid Type Assertions
+
+Due to some optimizations which depend on type correctness, you should keep in mind that using Type Assertions may have an effect on transpiled code, and can in some cause unexpected behavior. 
+> If you want to be on the safe side, we recommend that you don't use Type Assertions.
+
+#### Example
+```
+const someObj = {} as {x: number}
+const y = true ? someObj.x : 5
+```
+
+The value of y would be 5 ! (And not `nil`)
+This because the type says `someObj.x` exists and is not "falsy", so instead of a safe transpile (with `if..else..`), we optimize and use LUA's Ternary-Like construct:
+```
+local y = true and someObj.x or 5
+```
+Because `someObj.x` is `nil` at runtime, then y will be 5. (That is how LUA works)
+
+#### Lint rule
+
+You may even want to prevent Type Assertions completely, by using [ESLint](https://eslint.org) with a rule such as:
+```json
+{
+  "rules": {
+    "@typescript-eslint/consistent-type-assertions": ["error", {
+      "assertionStyle": "never"
+    }]
+  }
+}
+```
+