How to properly annotate lazy-loaded sub-modules?

[Bekaboo]

Say, I have a module called utils inside which I have sub-modules utils.fs,
utils.str and utils.web:

utils
├── init.lua
├── fs.lua
├── str.lua
└── web.lua

I want to be able to require only the utils module and be able to access
the sub-modules as if they are fields of the utils module, i.e.

local utils = require('utils')

utils.fs.fs_helper_fun(...)
utils.str.str_helper_fun(...)
utils.web.web_helper_fun(...)

But I don't want to load the sub-modules at once on requiring the utils
module, instead, they should only be loaded when needed, so in utils/init.lua
I have:

return setmetatable({}, {
  __index = function(_, key)
    return require('utils.' .. key)
  end,
})

But this confuses LuaLS and it does not provide any completion for sub-modules,
e.g. utils.fs, utils.str, etc.

I am aware that there is ---@module, I tried with

return setmetatable({
  fs = {} ---@module 'utils.fs'
  str = {} ---@module 'utils.str'
  web = {} ---@module 'utils.web'
}, {
  __index = function(_, key)
    return require('utils.' .. key)
  end,
})

with no luck.

Is there a way to make LuaLS aware of the sub-modules when I index to utils?

[tomlau10]

Your code snippet is working correctly on my side 🤔
except that you missed , in your utils/init.lua (which I believe is typo only?)

---

However I doubt that your code won't work 😕
Because when you include those fs / str / web field as empty object in the table of utils/init.lua
=> since these fields already exist
=> when you do utils.fs, it will skip the __index trigger and just return the empty object

You will need to use nil as initial value for these fields:

• utils/init.lua

return setmetatable({
    fs = nil,   ---@module 'utils.fs'
    str = nil,  ---@module 'utils.str'
    web = nil,  ---@module 'utils.web'
}, {
    __index = function(_, key)
        return (require('utils.' .. key))
    end,
})

• test.lua

local utils = require "utils"
for k, v in pairs(utils.fs) do
    print(k, v)
end
--[[ will print
fs_helper_fun	function: 0000000000fdca10
]]

[Bekaboo]

Thanks! After changing {} to nil and properly setting paths in .luarc.json the completions works, for reference, this is my .luarc.json (used for neovim config files), the key point here is "lua/?.lua" and "lua/?/init.lua" in path because neovim will only look for lua files under lua/ folder in runtimepath when it require a lua module:

{
    "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
    "workspace": {
        "library": [
            "$VIMRUNTIME",
            "$XDG_DATA_HOME/nvim",
            "$HOME/.local/share/nvim",
            "${3rd}/luv/library"
        ],
        "checkThirdParty": "Disable"
    },
    "runtime": {
        "version": "LuaJIT",
        "path": [
            "lua/?.lua",
            "lua/?/init.lua",
             "/usr/share/luajit-2.1.0-beta3/?.lua",
             "/usr/local/share/lua/5.1/?.lua",
             "/usr/local/share/lua/5.1/?/init.lua",
             "/usr/share/lua/5.1/?.lua",
             "/usr/share/lua/5.1/?/init.lua"
        ]
    },
    "diagnostics.globals": [
        "vim"
    ]
}