feat: add type annotations for plenary.functional

Author: delphinus

lua/plenary/functional.lua

@@ -1,5 +1,9 @@
+---@class PlenaryFunctional
 local f = {}
 
+---@generic T, U
+---@param t table<T, U>
+---@return { [1]: T, [2]: U }[]
 function f.kv_pairs(t)
   local results = {}
   for k, v in pairs(t) do
@@ -8,14 +12,27 @@ function f.kv_pairs(t)
   return results
 end
 
+---@generic T, U, V
+---@param fun fun(pair: { [1]: T, [2]: U }): V
+---@param t table<T, U>
+---@return V[]
 function f.kv_map(fun, t)
   return vim.tbl_map(fun, f.kv_pairs(t))
 end
 
+---@generic T
+---@param array T[]
+---@param sep? string
+---@return string
 function f.join(array, sep)
   return table.concat(vim.tbl_map(tostring, array), sep)
 end
 
+---@param fn function
+---@param n integer
+---@param a any
+---@param ... any
+---@return function
 local function bind_n(fn, n, a, ...)
   if n == 0 then
     return fn
@@ -25,10 +42,17 @@ local function bind_n(fn, n, a, ...)
   end, n - 1, ...)
 end
 
+---@param fun function
+---@param ... any
+---@return function
 function f.partial(fun, ...)
   return bind_n(fun, select("#", ...), ...)
 end
 
+---@generic T, U
+---@param fun fun(k: T, v: U): boolean
+---@param iterable table<T, U>
+---@return boolean
 function f.any(fun, iterable)
   for k, v in pairs(iterable) do
     if fun(k, v) then
@@ -39,6 +63,10 @@ function f.any(fun, iterable)
   return false
 end
 
+---@generic T, U
+---@param fun fun(k: T, v: U): boolean
+---@param iterable table<T, U>
+---@return boolean
 function f.all(fun, iterable)
   for k, v in pairs(iterable) do
     if not fun(k, v) then
@@ -49,6 +77,11 @@ function f.all(fun, iterable)
   return true
 end
 
+---@generic T, U
+---@param val any?
+---@param was_nil T
+---@param was_not_nil U
+---@return T|U
 function f.if_nil(val, was_nil, was_not_nil)
   if val == nil then
     return was_nil
@@ -57,6 +90,9 @@ function f.if_nil(val, was_nil, was_not_nil)
   end
 end
 
+---@generic T
+---@param n integer
+---@return fun(...: T): T
 function f.select_only(n)
   return function(...)
     local x = select(n, ...)
@@ -68,6 +104,9 @@ f.first = f.select_only(1)
 f.second = f.select_only(2)
 f.third = f.select_only(3)
 
+---@generic T
+---@param ... T
+---@return T
 function f.last(...)
   local length = select("#", ...)
   local x = select(length, ...)

lua/plenary/init.lua

@@ -1,5 +1,6 @@
 -- Lazy load everything into plenary.
 ---@class Plenary
+---@field functional PlenaryFunctional
 ---@field path PlenaryPath
 local plenary = setmetatable({}, {
   __index = function(t, k)