Luv and the Luvit definitions

[Bilal2453]

Recently, in PR #1760 metadata for the Luv library were added, and I want to take this chance to talk about some of the issues and falls, seeking opinions and possible workarounds of issues and features I've faced when using and writing Luv/Luvit apps.

First, an introduction of what Luvit and Luv are: Luv is (was) mainly developed as the backend for the framework Luvit, Luvit is a framework built-on the LuaJIT runtime aiming at mimic-ing the Nodejs framework (the main place libuv came into mind), it does that by pre-including some binaries such as lua-5.3 compat, OpenSSL, WinSVC, Rex (for Regex), LPeg, and of course Luv. Then an interface of Lua API is introduced making use of those binaries. While Luv was made just for that, it was also made available for general use by Lua and LuaJIT.

Some general notes that I have about the current definition of luv:

1- The metadata do not seem to be working with luv on normal Lua, in Lua the way you require Luv is require("luv") while the metadata are currently referring to it as uv only (more on that later), while at the same time having luv as the trigger word, this actively prevents require("uv") from being picked up by the third-party libraries auto-detection feature.

2. The uv.lua module does not return uv, so require("uv") even when detected won't work, you have to explicitly cast it to uv.

3. types.lua feels hacky to me, why are things that can be aliases (like the options you can pass to uv.spawn) being defined as classes? that is obvious as it is also try inheriting from a table.
   Why not just the alias? I am sure there was a reason to do it so more clarification needed on this.

4. While I understand why this have been cut into smaller files... that is annoying, require("luv suggests all kinds of invalid modules, require("types") is a thing when it should not be, we need a way to only let the uv.lua file show up as a module (the way I do this is by simply having a single file as it is one module, this is also how it is done in love2d definitions). All those files shall be combined into one.

5. While the err_name alias return sums it up, it is both annoying and inaccurate, annoying because a lot of functions do return err_name, fairly clogs the view up, and inaccurate because each method only have the chance of returning a set of those not all of them. Wouldn't it be better to just ditch that alias?

6. Missed opportunity to add @nodiscard.

7. While the error message is typed as an alias uv.error.message, success return is not and rather repeated everywhere as 0|nil.

Second, the general limitations that can be improved by the language server, on that the first thing that comes to mind are unioned returns, more specifically being able to somehow tell the language server "Hey, if the first return is nil, then the second one is guaranteed to be a string" as this would simplify the error handling done by luv so much, specially when multiple returns are present.

Quite honestly it is a bit hard to exactly fix those right now as they were auto-generated already, I do maintain the luvit-meta project which also happen to define Luv meta-definitions which solve some of those points (like having nodiscard, being defined in a single file, etc) but also lacks some of the features presented in here (like error aliasing). I am not entirely sure what should be done form here but, the two projects most likely need to be merged.

In Luvit the Luv module is loaded with require("uv"), although when Luv is used in general Lua/LuaJIT it is loaded with require("luv"), this is easily fixable by making two files, one uv.lua which contains the main stuff and another luv.lua which simply returns a cast to uv (or a require to it). I am mainly bringing this up as it would be nice to also include the Luvit metadata definitions here now that Luv is included.

Currently, I have to deal with multiple annoying issues in my Luvit definitions, the main issue that I can remember right now is the following:

Since Luvit comes with Lua 5.3 compat (adds some of the Lua 5.3 features) while also using LuaJIT as its runtime, I had to disable many built-in definitions to be able to redefine the version, telling the language server "Hey this method even though it is a Lua 5.3 one, but it also works here", namely I had to disable and redefine the following built-ins: basic, package, string, table. While my workaround works fine, the annoying part comes with the descriptions of those default methods, I cannot just simply copy what the language server use as it uses the special #DES 'funciton name' syntax which cannot be used here. I need a way to keep the descriptions but change the version metadata.

What do you think can be done to integrate the Luvit metadata? Should we just simply re-do the luv definitions? Work on my luv definitions to support what the current things support and replace the current definitions with that? Try fixing the current ones?

[Bilal2453]

@flrgh Would like your opinion on this as well.

[flrgh]

Sure thing. The libuv API doesn't change very often so I didn't automate the process 100%. I wrote a quick n dirty script that read the markdown doc from stdin to generate a rough draft of the types, and then I spent an afternoon reformatting and reorganizing with vim macros.

[Bilal2453]

About what I also did myself xD

I will do it manually (again) if I had to I guess. Should be a bunch of copy-paste.

[carsakiller]

Hello! Just a heads-up that the addon manager for VS Code should be releasing soon. If you'd like your definitions to be available from the addon manager, you can add them to LLS-Addons. This would require your definitions to live in their own git repository.

[Bilal2453]

Hi. Those are some exciting news, very cool! They are already in their own repo at https://github.com/Bilal2453/luvit-meta. This would do it for the Luvit definitions; although the current luv definitions situation stays as is (unless it gets removed from the language server and each maintains their own in the LLS-Addons manager). If they are not going to be removed I am still interested in fixing the mentioned issues.

[carsakiller]

All the currently included meta projects will be removed. They have been moved to LuaCATS and included in LLS-Addons for use with the addon manager.