How does type hinting work when using require?

[michaeldebetaz]

Hi everyone 👋 I am getting confortable with Neovim and I recently started to develop my own lua modules, in order to create custom snippets with luasnip and treesitter.

When adding my snippets, I see that local ls = require("luasnip") does not import types hints for the lua-ls LSP. However, local extras = require("luasnip.extras") does import them.

I am a bit lost on how this works in lua or with the LSP. I would like to know if it's possible to get autocompletion for something like local t = ls.text_node and also would like to use that knowledge on leveraging the LSP in order to import my types when requiring my own custom lua modules.

Sorry if I am too much of a newbie for being clear. I would be happy to help you help me! Thank you for your time and specially to L3MON4D3 for this amazing plugin 🔥

[L3MON4D3]

Hey!
I think this may be down to extras/init.lua being a simple table, while ls is not.
The reason behind this is that ls contains a bunch of entries from other modules, and we want to make these accessible lazily to decrease the upfront cost of loading all of them.
As to how luals could be made aware of them, maybe type-hints? But that would be quite a large endeavour 😅

[michaeldebetaz]

Thanks for taking the time to give me an answer :) That's very interesting! As I understand it, lua-ls can indeed track the types from a direct return statement (like return { foo = "bar" }. But it doesn't if we return M.

I'll play around to see if I can find something to leverage without having to add a whole new documentation!

EDIT : I was right! lua-ls does pick the type hints from the required module. The only thing to do now, is to find a way to maybe cast the type hints to you lazy_table.

[michaeldebetaz]

Okay I'm pumped! As I see after cloning your repo, the simplest way to add type hints for the snippets would be to cast when returning.

I would be happy to contrbute to better type hinting for Luasnip, but I need to understand the code better.

Here is a first try:

-- In lua/luasnip/init.lua
...
---@class LSLazyTable
---@field expand_or_jumpable fun(): boolean
---@field expand_or_locally_jumpable fun(): boolean
---@field locally_jumpable fun(dir: number): boolean
---@field jumpable fun(dir: number): boolean
---@field expandable fun(): boolean
---@field in_snippet fun(): boolean
---@field expand fun(): boolean
---@field snip_expand fun(snippet: any, opts: table): unknown
---@field s fun(context: any, nodes: any, opts: any): unknown
---@field etc...

---@cast ls LSLazyTable
return ls

A more elegant solution would be to leverage the lazy_table function with the use of the @generics annotation (https://github.com/LuaLS/lua-language-server/wiki/Annotations).

[L3MON4D3]

Oh that's pretty cool👌👌
You can find all of the exported functions in DOC.md (at the very end), but anything's better than nothing, so feel free to contribute what you have :D

(Although @generics sounds much better, if it's possible to do this almost-automatically instead of manually annotating the output of lazy_table)

[michaeldebetaz]

Hi @L3MON4D3 👋 I tried to play around this morning so I can contribute to type hinting Luasnip :) However, as I try to move up the code to type hint the data flow, I stumble on some of your code which makes difficult for me to guess the type you are expecting.

For example, in snippet_collection:

local by_prio = {
        snippets = {
                -- stores sorted keys, eg 1=1000, 2=1010, 3=1020,..., used for
                -- quick iterating.
                order = {},
        },
        autosnippets = {
                order = {},
        },
}

Can you help me understand what is the type of this class or table? I think it will take me some time to be more comfortable with the code 😅

Thanks a lot for your time!

[L3MON4D3]

Oh, getting right into it, awesome :D
by_prio.snippets/.autosnippets maps a number (the priority) to a table that maps a filetypes to a list of snippets (or, to be more precise, to a list of expandables). tbl.order stores the priorities present in tbl, such that we can quickly iterate all priorities in ascending, I think, order.
I think you can better see this in the code that actually adds the snippet, there's something like table.insert(by_prio.snippets[prio][ft], snippet)

I'll go a bit into snippet vs expandable vs addable, I think it's relevant if you're adding type-info, and I don't think I've done so anywhere else:

• a snippet is the thing in your buffer you jump around in, so it needs to store positions
• an expandable is what we actually store in eg. by_prio, and it doesn't need to store any info about the buffer, but has to store expand-conditions like the conditon and the trigger/trigEngine
• an addable is yet another abstraction, it mainly exists so multiple snippets can be added with a single object (see for example multiSnippet, which generates multiple expandables from multiple contexts, but all of those expandables expand to the same snippet)

[michaeldebetaz]

Thanks for taking the time to explain all of that! I'm still making baby steps, but it helps a lot to have a reference to understand the logic under the code.

I am thinking: maybe a way to bring autocompletion quicker for the community without having to type hint everything from the first function would be to type cast the code at the end and work our way up invrementally. Doing so would allow me to submit a PR quickly and let you unstuck me when I can't find the intended type for a specific class.

For the exemple above, my question would be what type do you intend for it ? Here what I was guessing:

---@class ByPrioSnippets
---@field order table<integer, integer>
---@field [integer] integer

---@class ByPrio
---@field snippets ByPrioSnippets
---@field autosnippets ByPrioSnippets
local by_prio = {
        snippets = {
                -- stores sorted keys, eg 1=1000, 2=1010, 3=1020,..., used for
                -- quick iterating.
                order = {},
        },
        autosnippets = {
                order = {},
        },
}

Again, my aim is to provide a fully type hinted experience for your plugin :) Luckly we don't break the code by doing so!

[L3MON4D3]

Thanks for taking the time to explain all of that! I'm still making baby steps, but it helps a lot to have a reference to understand the logic under the code.

Yeah, of course; it's a lot to unpack in the beginning

type cast the code at the end and work our way up invrementally

Yeah, I think that's much more prudent, in the end there are pretty few people who would benefit from type hinting of luasnip-internals 😅

---@field order table<integer, integer>
---@field [integer] integer

I think that last [integer] integer should be [integer] table<string, Expandable[]> (where string is a filetype, like "lua").
And order should probably be integer[] to express that the key-integers are continuous (so that ipairs can be used to iterate them in order :D)

[michaeldebetaz]

Hello @L3MON4D3 👋 I finished my first draft that gives Luasnip some autocompletion and type hinting. I cloned your repo, checked out to a new branch typehint and git push --set-upstream origin typehint. I am unfortunately unable to submit my pull request? Or did I do something wrong?

Sorry for my noobness in submitting PR, I'm still unfamiliar with them. Can't wait to discuss the type hints with you!

[L3MON4D3]

Hey :)
Sounds great👍👍
I think you'll have to officially "fork" luasnip on GitHub and push your changes to the fork. Then there should be a "Submit PR-"Button somewhere

[michaeldebetaz]

Oh that's right, I always clone insted and the have to git remote stuffs 😋 I submitted the PR! I didn't touch much of the code (maybe just one or two variable names in order to find myself in the code). So you shouldn't have any repercussion to the functionnality.

As I wrote in my PR, what's hard for me to type hint are typically the opts: any that can be anything or not exist. I guess they are a table, but it's not always clear what class I should give them.

Oh, I see I failed the test, but I don't understand why...

EDIT: Damned, I left some test code in it! My bad.

[michaeldebetaz]

Et voilà for the result so far: