Feature Request: ability to overload the return value type

How are you using the lua-language-server?

Visual Studio Code Extension (sumneko.lua)

Which OS are you using?

macOS

What is the issue affecting?

Annotations

Feature request

In my game's ECS bindings I have getter functions that work like this:

---@param id integer
---@return number? inv_mass
---@return number? restitution
function ecs.get_collision_body_values(id) end

local inv_mass, restitution = ecs.get_collision_body_values(entity_id)

This calls into a native ECS implementation that either pushes the 2 return values and returns with return 2; (2 return values) or if the return values doesn't exist, push nothing and return 0; (zero return values).

This can be used in my game code like this:

local function debug_body(id)
      local inv_mass, restitution = ecs.get_collision_body_values(id)
      if inv_mass == nil then -- collision_body component not set, do nothing
          return
      end
      ---@cast restitution number
      -- ^^ have to cast restitution number? -> number to avoid warning
      print(inv_mass, restitution)
end

Would be nice if there was a way to annotate an "all or nothing" multiple return value type. E.g., a function will either return multiple return values (e.g., not number? but number) or that it will return nothing. Or I guess more generally, the ability to somehow specify a union of different multivalue return types.

FWIW, it'd be possible to return "a bunch of values" or "nothing" by using a table? return type. However, I'm trying very hard not to allocate tables in my hot game's hot paths, thus I favor concrete types and multiple return.

Start by tracing how the language server represents annotated multiple return values and checks them at call sites. Use the ECS example in the issue as the behavior to investigate, including the zero-value and two-value cases. Done means a supported annotation can express all-or-nothing or unioned multivalue returns without requiring the shown cast, with diagnostics covered for both cases.