feat: nio async library

[rcarriga]

Neotest is migrating away from using plenary's async library, and replacing it with a new library called nio. There are several reasons for this change.

Reasoning

Some major ones are:

• Documentation: There is no vimdoc documentation and minimal documentation in the README.
• Typing: I believe providing type hints and docstrings make a huge difference when using a
  library. Plenary has very few of either.
• Consistency: The API has several inconsistencies that mean I regularly have to
  check source code for how to use it (e.g. some control objects use regular .
  syntax such as mpsc whereas others use : syntax such as Semaphore).
• Error handling: Handling errors in async functions requires using a custom apcall

This is not to say the plenary library has not been great and I absolutely appreaciate all the effort that went into it but the library is now seemingly no longer actively maintained (e.g. nvim-lua/plenary.nvim#293 and nvim-lua/plenary.nvim#298) and I believe there are significant enough changes to be made to justify packaging a new library.

The new library has a simple goal: providing common asynchronous primitives and asynchronous APIs for Neovim's core. It has been heavily influenced by the previous work for async IO in neovim including plenary and others. There are plans for Neovim to embed an async library within core which will provide a barebones core for libraries to share for compatibility (see neovim/neovim#19624). Nio aims to maintain compatibility with this library.

Features of nio include:

• Task objects which track running async functions
• Handling results and errors of tasks along with cancelling.
• Helper functions for coordinating tasks, including gathering results from a list of tasks and getting the result of the first task to complete (and cancelling the others).
• Async versions of many libuv functions, pretty much the same way plenary does it with the added bonus of all of the functions being typed with emmylua annotations so users will have full type inference.
• Creating a fully documented and typed LSP client interface which is generated by a script based off of the LSP spec meta model and then implemented very simply with some metatables.
• Async primitives (futures, queues, events and semaphores) which are often useful in async code, again based off of Python's asyncio modules.

What does this mean for adapters?

I've been using the library embedded in nvim-dap-ui for a while now but neotest provides a better use case as the async usages are more complex and diverse. Right now I'll be leaving it embedded in neotest, with it being released as a separate plugin in future.

I've checked the source code all the adapters mentioned here (gotten from the neotest README) and most of them won't see any user facing issues as they are using neotest.async which has been migrated to point to nio. All usage of fn, api and uv will work as before.

Those adapters using require("plenary.async.tests") will have broken tests, which can be fixed by switching to require("nio").tests.

neotest-jest and neotest-dotnet do use the control module which which has changed significantly. I will open PRs to make changes to use the new primitives.

I'm planning on merging these changes relatively soon so please let me know of any issues but hopefully this will be a painless switch 😄

[rcarriga]

neotest-dotnet: @Issafalcon
neotest-deno: @MarkEmmons
neotest-jest: @haydenmeade
neotest-elixir: @jfpedroza
neotest-vitest: @marilari88
neotest-haskell: @mrcjkb
neotest-go: @sergii4 @akinsho
neotest-phpunit: @olimorris
neotest-rspec: @olimorris
neotest-rust: @rouge8
neotest-testthat: @shunsambongi
neotest-dart: @sidlatau
neotest-scala: @stevanmilic
neotest-pest: @theutz

[mrcjkb]

Had to replace a neotest.async require with nio, but otherwise all is good from my side.

[olimorris]

Completely agree with the rationale. I've found the documentation for plenary to be subpar for a while now (ChatGPT to the rescue).

I updated my adapters with a conditional for nio.

I noticed that my overseer consumer is broken though (cc: @stevearc)

[stevearc]

I have a PR up for overseer that uses the new library and generally works, but it spits out this error:

[ERROR] Task Neotest dispatch callback on_output: ...vearc/.local/share/nvim/lazy/neotest/lua/nio/control.lua:48: attempt to call local 'callback' (a nil value)

I've tried fiddling with the implementation and passing functions around, but I can't seem to find where this is coming from. This highlights my main issue with writing async code in most languages: stack traces lose information and it becomes a lot harder to debug.

@rcarriga Do you have any tips for figuring out where this control.wait is getting called from?

[rcarriga]

Thanks for the testing and updating everyone! I'd forgotten to check overseer, but great to see it updated too.

I've tried fiddling with the implementation and passing functions around, but I can't seem to find where this is coming from. This highlights my main issue with writing async code in most languages: stack traces lose information and it becomes a lot harder to debug.

@rcarriga Do you have any tips for figuring out where this control.wait is getting called from?

Providing stack traces is actually a big thing I tried to do in nio because I had the same experience of things just failing mysteriously 😅

The reason there's no trace here is because it's not nio that is catching the error, it is this code:
https://github.com/stevearc/overseer.nvim/blob/1ddb3671b7198b64c73824a5e5e21f8eb2ab47c3/lua/overseer/task.lua#L445-L450

Changing the code to use xpcall would allow you to get the traceback and place it in the message

local ok, result = xpcall(comp[name], function (err)
  log:error("Task %s dispatch %s.%s: %s\n%s", self.name, comp.name, name, err, debug.traceback(err, 2))
end, comp, self, ...)
if ok and result ~= nil then
  table.insert(ret, result)
end

The error is happening because you're using queue.put which is an asynchronous function within the callback for on_output which is not called in an asynchronous context.
https://github.com/stevearc/overseer.nvim/blob/1ddb3671b7198b64c73824a5e5e21f8eb2ab47c3/lua/neotest/client/strategies/overseer.lua#L115
Changing to put_nowait should fix the issue 😄

Calling wrapped functions is supported to allow users to be able to use them in non-async contexts with the usual callback style without having to choose between an async version and synchronous version. This has the disadvantage of not giving a very helpful error because it's be up to the wrapped function to check for callback. Nio could check that a callback is provided in non-async contexts and error if it's not but that would prevent uses where a callback is optional. As a middleground we can log a warning to nio's log file.

[stevearc]

Thanks for the help! The overseer PR is ready to go with full support for the new nio library.

[Issafalcon]

Hi @rcarriga - Thanks for the update.

I've tested your changes on my end. All looks fine to me. The (few) tests I have still pass also.

[rcarriga]

Brilliant, since we're looking good I'll get to merging this