Class generics produce unusable and wrong union types #3261

Activity

1. tomlau10 commented on Sep 2, 2025

   

   tomlau10

   on Sep 2, 2025

   Contributor

   More actions

   AFAIK, the generic support of LuaLS is very limited. 😇
   There are many caveats, and the "best" annotation that I attempted to achieve your needs is as follow:

   ---@class Stack<T>: { __hidden: T }
   ---@field protected _stack any[]
   ---@field protected _count integer
   Stack = {}
   Stack.__index = Stack
   
   ---@return Stack
   function Stack.New()
       local self = {
           _stack = {},
           _count = 0,
       }
       return setmetatable(self, Stack)
   end
   
   ---@generic T
   ---@param self Stack<T>
   ---@return T
   function Stack:Pop() return nil end
   
   ---@generic T
   ---@param self Stack<T>
   ---@return T
   function Stack:Peek() return nil end
   
   ---@generic self, T
   ---@param self self|Stack<T>
   ---@param value T
   ---@return self
   function Stack:Push(value) return self end
   
   --- demo
   
   ---@type Stack<{ num: integer }>
   local st = Stack.New()
   
   local a = st:Peek() --> { num: integer }
   local b = st:Pop() --> { num: integer }
   local c = st:Push({}) --> Stack<{ num: integer }>

   

   caveat 1

   A generic class must inherit a table with a field to store the generic type T
   ref: #1532 (comment)
   In my example you can see there is a { __hidden: T } there.
   If you remove it, then ---@param self Stack<T> annotation in the methods won't work
   => which will cause :Peek() and :Pop() annotation failing to work

   caveat 2

   A generic type in function annotation can only do type capturing but not type enforcing

   • i.e. the ---@param value T in Stack:Push actually does nothing
   • because it can only be used the match the type T in Stack<T>
   • but cannot be used the enforce value param to be of the captured type T
   • and therefore LuaLS cannot check against incorrect value type that you pass to :Push()

   ---

   If you use generic types heavily, you may want to try CppCXY's new language server written in Rust.
   It has much better generic class support 👀

   • [PREVIEW] a new lua language server #3017
   • [PREVIEW] a new lua language server #3017 (comment)