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.

[arr2036]

Just +1ing this for OpenResty code. It's a complete PITA that we can't mark up functions which return control to NGINX as never returning.

[tomlau10]

For the very specific case of OP, we can use the runtime.special config to specify that custom_error has the special meaning as (built-in) error
https://luals.github.io/wiki/settings/#runtimespecial

• .luarc.json

{
    "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
    "runtime.special": {
        "custom_error": "error"
    }
}

• test code

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

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

local function custom_error()
    error()
end

---@return number
local function get_bar_with_custom_error()
    local foo = get_foo()
    if foo == nil then
        custom_error()
    end
    return foo.bar --> `Foo.bar: number`
    -- instead of `Foo|nil.bar: number` which triggers nil check error
end