How to annotate module types

[bryanforbes]

I have a function similar to this:

local req = function(moduleName)
  local status, mod = pcall(require, moduleName)

  if not status then
    return nil
  end

  return mod
end

local thing = req('thing')

Annotating moduleName and status is simple enough, however annotating mod, the return type, and thing seem to be much harder:

---@param moduleName string
---@return ??? | nil
local req = function(moduleName)
  ---@type boolean
  local status
  ---@type ???
  local mod
  status, mod = pcall(require, moduleName)

  if not status then
    return nil
  end

  return mod
end

---@type ??? | nil
local thing = req('thing')

Let's look at the two variables:

• For mod, if the value of moduleName was known, it could be annotated as ---@module 'valueOfModuleName'. Is there a way to dynamically pass a value to @module today?
• For thing, I don't see a way to annotate a variable as a @module or another type, which would allow me to ignore the dynamic @module for mod and set the return value of req to any.

For the return type, I don't see a way to do any of these:

• Annotate returning a @module
• Annotate returning a @module or another value
• Dynamically set the value of the @module based on some computed value (as pointed out above)

Perhaps I'm just missing how to do all of this, so any help is greatly appreciated.

[sumneko]

When parsing the code, require is treated as a special keyword and cannot be supported currently.

[bryanforbes]

That's understandable and I anticipated that would be part of the answer. I'm still wondering if there's a way to annotate a variable as a module or nil:

-- `thing` can be either the module 'thing' or nil
---@type ???
local thing = req('thing')

Right now, it seems I can either annotate the variable as ---@module 'thing' or ---@type nil, but not a union of the two.

[przepompownia]

Is it still (3 years later) so difficult to add a way completion of module names? It's possible for require or @module but seems to be not possible for a custom function whose parameter is module name (like req here).

[tomlau10]

You're right. And due to the built-in require only accept 1st param as module name, if your custom require function wants to accept module name as 2nd param, then it will not work in this case...

[przepompownia]

if your custom require function wants to accept module name as 2nd param, then it will not work in this case...

I know, but it's a minor problem in my simple loader, where the second parameter is simple callback with no parameter (available directly from snippet).

https://github.com/przepompownia/nvim-arctgx/blob/ed881a135cc919209e52cf9c601dd9c50d0a96a1/lua/arctgx/lazy.lua#L32-L38

[tomlau10]

still requires referencing it by some local variable before.

I don't know what do you mean by referencing it by some local variable, but judging the file that you provided I think you can write it as:

--- to fake LuaLS that this is a  standard `require` function for module name autocompletion
lazy.setupOnLoad = require

--- @param modname string
--- @param callback fun()
function lazy.setupOnLoad(modname, callback)
  addConfig(modname, {callback = callback})
end

This is enough to trick LuaLS 😄

---

Otherwise if you are 100% sure that in your other projects, you always import this module as lazy and then call the function as lazy.setupOnLoad, then you can edit your .luarc-static.json (?) to:

"runtime": {
  ... // your other runtime settings
  "special": {
    "lazy.setupOnLoad": "require"
  }
}

Note that by using runtime.special method, if you import this module as another name, then it will not work:

local lz = require "lazy"
lz.setupOnLoad("no module name auto completion here")

But the 1st method DO work.

[przepompownia]

I tried it before, forgetting that I need to call lazy.setupOnLoad literally (not require('arctgx.lazy')):

I tried also

    "special": {
      "require('arctgx.lazy').setupOnLoad": "require"
    },

but it does not work.

Summarizing, thanks for interesting tricks, although I wouldn't like affect my Lua code for them (except annotations if any) - at most LuaLS configs.

For explanation, I use .luarc-static.json as an optional project-specific static part of the resultant .luarc.json with generateLuarcJson.lua.

[tomlau10]

OIC, you want to directly write require('arctgx.lazy').setupOnLoad() in your other project code without first assign the module to a local variable. But strange enough, I used my first trick and it works well with this syntax 😕

But I use vscode, maybe it doesn't work in neovim.

---

Anyway you're welcome 😄