[Feature Request] Primitive Type Extensions / Metatable Override Support

Hello, I am not sure if this is something that is already possible to annotate, but I am not able to figure out how to get this to work.

By default, Lua does not have full indexing support with its base primitive types. Due to this, it is not possible to do certain things such as chaining method calls, indexing certain types in a way that feels natural, or doing some more 'common-practice' things in other languages.

Take the following examples that are invalid, by default:

local num_test = 2;
print(num_test:pow(2)); -- Error: attempt to index local 'num_test' (a number value)

local str_test = 'Hello World';
print(str_test[1]); -- Error: (returns nil)

local tbl_test = { 1, 2, 3, 4 };
print(tbl_test:remove(1)); -- Error: attempt to call method 'remove' (a nil value)

However, Lua does offer the means to enable this features in a legit manner by using the debug.setmetatable function. The above examples can be made valid by doing the following:

local math_mt = {};     -- Table to hold custom math extension methods.
local string_mt = {};   -- Table to hold custom string extension methods.
local table_mt = {};   -- Table to hold custom table extension methods.

-- Number Metatable Override
debug.setmetatable(0, {
    __index = function (_, k)
        return
            math[k] or
            math_mt[k] or
            error(string.format('Number type does not contain a definition for: %s', tostring(k)));
    end,
});

-- String Metatable Override
debug.setmetatable('', {
    __index = function (self, k)
        return
            string[k] or
            string_mt[k] or
            type(k) == 'number' and (k == 0 and #self or string.sub(self, k, k)) or
            error(string.format('String type does not contain a definition for: %s', tostring(k)));
    end,
});

Additionally, with this kind of setup, someone can then extend the built-in tables for things like math, string, table, etc. by adding things to the respective extension tables. For example, I can add new string extensions such as:

string_mt.starts_with = function (self, s)
    return self:sub(0, #s) == s;
end

string_mt.ends_with = function (self, s)
    return self:sub(-#s) == s;
end

For tables, you can also extend them to add indexing through a helper such as:

T = function (t)
    return setmetatable(t or { }, {
        __index = function (_, k)
            return table_mt[k] or table[k];
        end
    });
end

Doing this would allow indexing a table directly, such as:

local tbl = T({ 1, 2, 3, 4 });
print(tbl:remove(1));

My issue is that I do not see a way to properly annotate this kind of setup so that I can get proper intellisense on the various primitive types with my custom extensions and the added indexing to the types that normally don't have it.

Using the examples above, I should be able to do the following and have the intellisense pickup my extensions:

local num = 2;
print(num:pow(2));
print(num:add(2)); -- Assuming 'add' is an extension method in the 'math_mt' table.
print(math.add(num, 2));

local str = 'Hello world';
print(str:starts_with('H'));
print(('test'):ends_with('st'));
print(string.starts_with('test', 'te'));
print(str[1]);

And so on.

Searching past issues, I've only seen one that slightly mentioned this kind of thing here: https://github.com/LuaLS/lua-language-server/issues/2065

To give a more full-scale example of this kind of setup and what I am doing/referring to, you can see this in use via my sugar library for one of my projects here:

• https://github.com/AshitaXI/Ashita-v4beta/blob/main/addons/libs/sugar.lua
• https://github.com/AshitaXI/Ashita-v4beta/tree/main/addons/libs/sugar

Commencez par examiner l’issue #2065 et les exemples de sugar.lua qui y sont liés, puisqu’aucun fichier du dépôt ni aucun test n’est identifié ici. Définissez comment les annotations doivent exposer les extensions personnalisées et l’indexation pour les types primitifs et les tables, la complétion et les diagnostics couvrant les exemples de number, string et table décrits dans l’issue.