Multiple return values - annotating "all or nothing"

[nurpax]

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

Is there 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.

(PS. I filed this first as an issue, but maybe it's better as a discussion.

[Frityet]

---@type (fun(integer))|(fun(integer): integer, integer)