Feature Request: Assertion Functions

I would like annotation and type checking that supports and implements TypeScript's "Assertion Functions":
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions

It's similar to other open feature requests for type predicates / narrowing except it avoids the need for if statements and to return a boolean from the function where true means a variable is of a given type and false if it's not that type.

I mentioned this briefly in another open issue but the original issue was for implementing narrowing/type predicates:
https://github.com/LuaLS/lua-language-server/issues/704#issuecomment-1484060572

This TypeScript code illustrates the feature:

function assertIsString(val: any): asserts val is string {
  if (typeof val !== "string") {
    throw new AssertionError("Not a string!");
  }
}

This tells the linter that the argument passed to the val parameter is a string if no assertion raised an error.

In Lua, this might look like the following:

---@param val any
---@asserts val is string
local function assertIsString(val)
  assert(type(val) == "string", "Not a string!")
end

---@param str any
local function yell(str)
  assertIsString(str)  
  -- No error was thrown! Therefore, the next line should not be marked as a warning and `str` must be a string.
  return str:upper()
end

The problem at the moment is that I need to add ---@cast val string after every usage of assertIsString:

local function yell(str)
  assertIsString(str)  
  ---@cast str string
  return str:upper()  -- LuaLS complains that str might not be a string unless I cast it
end

There is no other way of telling LuaLS that the result has been confirmed to be a string unless the assert expression is directly in the same body of code.

I would suggest adding narrowing with type predicates first as this feature request seems like the next feature on top of that feature, but I'd like to see what people think :)

Thank you!

Beginne mit dem Lesen der Referenz zu Assertion-Funktionen in TypeScript 3.7 und des verknüpften Type-Predicate-Issues 704. Untersuche anschließend, wie vorhandene @cast-Annotationen das Narrowing durchführen. Die Aufgabe ist erledigt, wenn eine Lua-Assertion-Annotation das Argument nach einem erfolgreichen Assertion-Aufruf eingrenzen kann, sodass das yell-Beispiel str:upper() ohne einen separaten Cast akzeptiert.