Feature Request: Assertion Functions

[Mayron]

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!

[C3pa]

Your function assertIsString doesn't have a return value. Why specify a ---@return annotation?

[Mayron]

@C3pa I was trying to show what it might look like in Lua based on the TypeScript version:

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

I guess it could look like this instead:

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

But, also there are some other open feature requests for LuaLS asking for type predicate functions for narrowing and I wanted to make assertions as an addon to this same feature so I was trying to use similar syntax, but maybe @asserts would make more sense?

This is an example of the "type predicate narrowing" feature-request just for context:

---@param pet table
---@return pet is Fish
local function IsFish(pet)
   return pet.swim ~= nil
end

if isFish(somePet) then
   somePet.swim() -- no warning as LuaLS should assume its now of type Fish with a swim function
end

This one actually returns a boolean and if true then the "pet is Fish" condition is also true, else pet is not a Fish.

[Mayron]

I've edited my original issue now as I agree with @C3pa that it made no sense and ideally it should be @asserts <condition> as shown above.

[sumneko]

There is no plan to support type operations for the time being

[C3pa]

Looks like this issue is essentially the same as #1429.