feat(lua): add vim.async

Problem: Nvim has many Lua APIs that start callback-driven work: timers,
jobs, libuv handles, and other event-loop tasks. Callers that need to
sequence or cancel that work have to build their own coroutine wrappers,
task bookkeeping, and cleanup rules. This makes async control flow hard
to share, test, and document.

Solution: Add `vim.async`, a structured-concurrency module vendored from
async.nvim. It provides task handles, await/pawait helpers,
sleep/timeout helpers, completion-order iteration, and semaphores on top
of Nvim's event loop.

The API follows the same broad model as Trio: async work has an owner,
tasks are awaited explicitly, and cancellation is cooperative. Include
generated vimdoc with an introductory overview and examples, a news
entry, and functional tests for the new module.

AI-assisted

1 files changed, 46 insertions, 0 deletions

diff --git a/runtime/lua/vim/async/_runtime.lua b/runtime/lua/vim/async/_runtime.lua
new file mode 100644
index 0000000000..d7a84f65af
--- /dev/null
+++ b/runtime/lua/vim/async/_runtime.lua
@@ -0,0 +1,46 @@
+-- LuaLS cannot model the generic annotations used by this vendored implementation.
+---@diagnostic disable: no-unknown, undefined-doc-name, luadoc-miss-symbol, missing-return, missing-return-value, param-type-mismatch, return-type-mismatch, redundant-return-value, undefined-field, need-check-nil, await-in-sync
+
+local validate = vim.validate
+
+--- @class vim.async.Timer: vim.async.Closable
+--- @nodoc
+--- @field start fun(self, timeout: integer, repeat_interval: integer, callback: fun())
+
+--- @alias vim.async.TimerFactory fun(): vim.async.Timer
+--- @nodoc
+
+--- @class vim.async.ConfigOpts
+--- @nodoc
+--- @field wait? fun(timeout: integer, predicate: fun(): boolean): boolean Run the event loop until the predicate succeeds or the timeout expires.
+--- @field schedule? fun(callback: fun()) Queue a callback to run once on a later event-loop turn.
+--- @field new_timer? vim.async.TimerFactory Create libuv-compatible timers for `sleep()` and `timeout()`.
+--- @field debug? boolean Capture task creation metadata for debugging.
+
+--- @class vim.async.Runtime
+--- @nodoc
+--- @field wait fun(timeout: integer, predicate: fun(): boolean): boolean
+--- @field schedule fun(callback: fun())
+--- @field new_timer vim.async.TimerFactory
+--- @field debug boolean
+local M = {}
+M.debug = false
+
+--- @nodoc
+--- @param opts vim.async.ConfigOpts
+function M.config(opts)
+  validate('opts', opts, 'table')
+  validate('opts.wait', opts.wait, 'callable', true)
+  validate('opts.schedule', opts.schedule, 'callable', true)
+  validate('opts.new_timer', opts.new_timer, 'callable', true)
+  validate('opts.debug', opts.debug, 'boolean', true)
+
+  M.wait = opts.wait or M.wait
+  M.schedule = opts.schedule or M.schedule
+  M.new_timer = opts.new_timer or M.new_timer
+  if opts.debug ~= nil then
+    M.debug = opts.debug
+  end
+end
+
+return M