How to annotate a function that can never return?

[idanarye]

Say I have something like this:

---@class Foo
---@field bar number

---@return Foo?
local function get_foo()
    return nil
end

local function custom_error()
    error()
end

local foo = get_foo()

if foo == nil then
    custom_error()
end

print(foo.bar)

LuaLS complains that I've accessed foo.bar even though foo could be nil:

But if I use the builtin error instead of my custom_error, LuaLS knows that this point cannot be reached when foo is nil:

Is there a way to annotate custom_error so that LuaLS will know that it never returns, just like the builtin error?

[C3pa]

If you put your code into a function and add a return after the custom_error() call, you'll end with no errors:

I hope that can help in your use case.

[idanarye]

This works for this specific usecase, but not for the more complex ones:

• Inside a function that needs to return a value:
  
  Of course, I can always replace the return with an error(), but this will just look weird.
• When using the nil or pattern:
  
  This is actually what I want this the most for, since it allows ergonomic handling of nil cases (when I catch the specific error I raise from custom_error). This is useful for UI, when the user is allowed to cancel the input which makes the input function return nil and then I just abort the entire action by throwing a custom error.

[C3pa]

Try annotating your get_foo function as returning number|nil

[idanarye]

You mean change get_bar_... to return number|nil? (because get_foo already returns Foo?, which is not a number and the same as Foo|nil)

This will remove the error, of course, but now I'll have a wrong return type for bar, because bar can't actually return nil - it can either return a number or throw an error.

[C3pa]

Well, a function with early return doesn't return anything, or in other words, it's equivalent to returning nil explicitly.

I agree that my suggestion isn't the most clean way to document your code, but that's what we can do with existing annotations.