LuaLS processes the wrong LuaDoc for Penlight tablex.filter #3317

Activity

1. tomlau10 commented on Dec 18, 2025

   

   tomlau10

   on Dec 18, 2025

   Last edited by tomlau10

   Contributor

   More actions

   explanation of this behavior (?)

   AFAIK, the server will try to type narrow the function signature when applicable.
   One of the criteria is number of min/max params
   

   lua-language-server/script/vm/function.lua

   Lines 25 to 65 in 3a65772

   	function vm.countParamsOfFunction(func)
   	local min = 0
   	local max = 0
   	local def = 0
   	if func.type == 'function' then
   	if func.args then
   	max = #func.args
   	def = max
   	for i = #func.args, 1, -1 do
   	local arg = func.args[i]
   	if arg.type == '...' then
   	max = math.huge
   	elseif arg.type == 'self'
   	and i == 1 then
   	min = i
   	break
   	elseif getDocParam(arg)
   	and not vm.compileNode(arg):isNullable() then
   	min = i
   	break
   	end
   	end
   	end
   	end
   	if func.type == 'doc.type.function' then
   	if func.args then
   	max = #func.args
   	def = max
   	for i = #func.args, 1, -1 do
   	local arg = func.args[i]
   	if arg.name and arg.name[1] =='...' then
   	max = math.huge
   	elseif not vm.compileNode(arg):isNullable() then
   	min = i
   	break
   	end
   	end
   	end
   	end
   	return min, max, def
   	end

   • I added a debug print(min, max, def) just before the return line
     • for the 1st one it prints 3, 3, 3
     • for the 2nd one it prints 2, 3, 3
   • note the difference of min param of the functions 😕
     => the server thinks that the 1st function signature requires 3 params, all are required and none are optional
     => since your code snippet only gives 2 params

     tablex.filter(
         {},
         function() end
     )

   => the server "filtered" it out, and narrowed to the 2nd one...

   possible workaround

   Looking at the code inside vm.countParamsOfFunction, it basically uses :isNullable() to determine the min value.
   

   lua-language-server/script/vm/node.lua

   Lines 162 to 178 in 3a65772

   	function mt:isNullable()
   	if self.optional then
   	return true
   	end
   	if #self == 0 then
   	return true
   	end
   	for _, c in ipairs(self) do
   	if c.type == 'nil'
   	or (c.type == 'global' and c.cate == 'type' and c.name == 'nil')
   	or (c.type == 'global' and c.cate == 'type' and c.name == 'any')
   	or (c.type == 'global' and c.cate == 'type' and c.name == '...') then
   	return true
   	end
   	end
   	return false
   	end

   • currently it only treats nil|any|... as optional, but not for generic param
     (I am not sure if this is intended behavior)
   • however it also treats a manually ? marked param as optional
   • so the workaround is to mark arg as optional with ? 🤔

   ---@param arg? A # note the `?` after `arg`

   or if you prefer using |nil

   ---@param arg A|nil # note the `|nil` after `A`

   => then server can type narrow the function correctly

   ---

   In short, the workaround is mark arg as optional.
   Meanwhile whether generic param not counted as optional is a "feature" or bug, has to be clarified by maintainers. 😕
2. FunctionDJ commented on Dec 18, 2025

   

   FunctionDJ

   on Dec 18, 2025

   Last edited by FunctionDJ

   Author

   More actions

   @tomlau10 Thanks a ton for this breakdown! Very insightful and comprehensible.

   From the user-side, just passing any value as a third parameter (that can go unused in the predicate function) does indeed make LuaLS pick the correct type definition and doesn't yield a type warning.

   local tablex = require("pl.tablex")
   
   local doubled = tablex.filter(
       { 1, 2, 3 },
       function(num, unused) return num * 2 end, -- no linting error and you'd usually not even specify the unused param
       nil
   )

   👍React with 👍1Reacted by Tom Lau