Mutually-exclusive multi-return

[ChristopherJTrent]

I'll open by acknowledging that this might not be supported, but it's something I'd like to know for certain.

I'm working on a codebase that uses golang style Errors As Values, and I was hoping to get a little more tooling support from the language server.

To speak more specifically, a function will either return Error, nil or nil, result, but never Error, result or nil, nil
The benefit to this idiom is that you know for certain that if Error is nil you have a result and vice versa.
This works great in practice, but the LS hates it. Every time I use the return values from one of these functions, the LS thinks that result could be nil (which makes sense) even though technically, it can't be because I've made sure that Error is nil.

Is there something clever I can do in the annotations to make this work the way I'm expecting?

[tomlau10]

This has been feature requested in multiple issues and discussion:

• @return支持多种类型 #1583
• overload type narrowing for returns #2933
• @overload return union unexpected behaviour #3078
• 这种return类型推断能否更智能一点? #3086

And from comments of maintainers #3086 (comment)
it is planned to support the following syntax:

---@return =(true, some_type)
---@return =(false, string)

(but not yet implemented of course)

[ChristopherJTrent]

Gotcha.

I don't really associate it with overloading (and I don't speak chinese) which explains why I couldn't find it when I did my search.

I'll continue using my workaround for the time being, then. (below)

local err, nextIndex = self:GetNextValidIndex()
if err == nil then ---@cast nextIndex integer
    -- use nextIndex
end

[tomlau10]

Just an additional note:

if your :GetNextValidIndex() is already returning integer|nil for nextIndex
and you want to "remove" the nil type in that specific if branch
you can actually use ---@cast nextIndex -? / ---@cast nextIndex -nil 😃
https://luals.github.io/wiki/annotations/#cast

if err == nil then ---@cast nextIndex -?
    -- nextIndex will then have the `nil` type removed
    -- such that you don't need to hardcode `integer` type in the `@cast`
end