How to create a fallback type for undefined string fields?

[sewbacca]

Suppose I want to write a vector class, which has a few functions defined, but I also want to swizzle the components.

---@class Vector
---@field x number
---@field y number
---@field z number
local Vector = {}

function Vector:normed() return --[[normed vector]] end

function Vector:__index(k)
    if Vector[k] then return Vector[k] end
    -- create new vector based on swizzle k
end

Such that the following code works:

---@type Vector
local vec

local a = vec.yxz
local b = vec:norm() + a:norm()

Swizzling means I can create a new vector from a new arrangment of the vector components using the key given to __index. So a vector (1, 2, 3) becomes (2, 1, 3), if I index the original vector with .yxz. This adds a ton of new fields in my class, so I don't wanna add them all at once. Instead I tried:

---@class Vector : { [string]: Vector }
local Vector

Which does work, but it also adds the fallback for functions (i.e. Vector.normed.normed.normed... is a thing now), as well as for the single components .x, .y, .z, which is a bit annoying because that causes a few unecessary warnings all over the place. In the latter case .x is now a number|Vector, so any function accepting only a number will throw a warning.

Does anyone know a workaround for this issue?

[tomlau10]

Firstly you can use ---@field [t1] t2 syntax for fallback type during table indexing

---@class Vector
---@field x number
---@field y number
---@field z number
---@field [string] Vector
local Vector = {}

• under this annotation, those single components .x .y .z will be having only number type
• however this seems not working well with the methods that you defined later 😕
  i.e. LuaLS will still infer Vector.normed as a function|Vector

---

The current workaround is add those methods to @field as well ...

---@class Vector
---@field x number
---@field y number
---@field z number
---@field normed fun(self: self): Vector
---@field [string] Vector
local Vector = {}

• but as you may know, the fun() syntax doesn't support generic.
• so this maybe somewhat limited compared to annotating functions just using @param style ☹️

[tomlau10]

A fix for only adding fallback type when field type not found

I debugged quite a while, and finally found a fix for this 🤔

• the reason of this behavior is that it always processes all @field types info, before looking into setfield/setmethod of the class variable
• by delaying only the processing of @field [T1] T2, we can then first check if a field type is already found
• and finally add the fallback type only if that field key type not found

However I am not sure if there are any side effects, at least it pasts all existing defined test in the project 😕

demo

---@class Vector
---@field x number
---@field y number
---@field z number
---@field [string] Vector
---@operator add(Vector): Vector
local Vector = {}

function Vector:normed() return Vector end

function Vector:__index(k)
    if Vector[k] then return Vector[k] end
    -- create new vector based on swizzle k
end

---@type Vector
local vec

local a = vec.yxz
local b = vec:normed() + a:normed()

The patch

basically just move the whole logic to the bottom

From d893ffdbf9a8ca75d2fe61c61203908002f8807b Mon Sep 17 00:00:00 2001
From: Tom Lau <[email protected]>
Date: Sat, 5 Jul 2025 20:31:16 +0800
Subject: [PATCH] fix: fallback type of `@field` should not apply when field
 type is found

---
 script/vm/compiler.lua | 91 ++++++++++++++++++++++++------------------
 1 file changed, 53 insertions(+), 38 deletions(-)

diff --git a/script/vm/compiler.lua b/script/vm/compiler.lua
index 986e85e2..ec9c8bb7 100644
--- a/script/vm/compiler.lua
+++ b/script/vm/compiler.lua
@@ -434,44 +434,6 @@ function vm.getClassFields(suri, object, key, pushResult)
                         pushResult(field, true)
                         goto CONTINUE
                     end
-                    if hasFounded[key] then
-                        goto CONTINUE
-                    end
-                    local keyType = type(key)
-                    if keyType == 'table' then
-                        -- ---@field [integer] boolean -> class[integer]
-                        local fieldNode = vm.compileNode(field.field)
-                        if vm.isSubType(suri, key.name, fieldNode) then
-                            local nkey = '|' .. key.name
-                            if not searchedFields[nkey] then
-                                pushResult(field, true)
-                                hasFounded[nkey] = true
-                            end
-                        end
-                    else
-                        local keyObject
-                        if keyType == 'number' then
-                            if math.tointeger(key) then
-                                keyObject = { type = 'integer', [1] = key }
-                            else
-                                keyObject = { type = 'number', [1] = key }
-                            end
-                        elseif keyType == 'boolean'
-                        or     keyType == 'string' then
-                            keyObject = { type = keyType, [1] = key }
-                        end
-                        if keyObject and field.field.type ~= 'doc.field.name' then
-                            -- ---@field [integer] boolean -> class[1]
-                            local fieldNode = vm.compileNode(field.field)
-                            if vm.isSubType(suri, keyObject, fieldNode) then
-                                local nkey = '|' .. keyType
-                                if not searchedFields[nkey] then
-                                    pushResult(field, true)
-                                    hasFounded[nkey] = true
-                                end
-                            end
-                        end
-                    end
                     ::CONTINUE::
                 end
             end
@@ -547,6 +509,59 @@ function vm.getClassFields(suri, object, key, pushResult)
         end
         copyToSearched()
 
+        -- search for fallback types in @field, eg: ---@field [integer] boolean
+        -- only when type for this field key is not found
+        if key ~= vm.ANY and key ~= vm.ANYDOC and not searchedFields[key] then
+            for _, set in ipairs(sets) do
+                if set.type == 'doc.class' then
+                    for _, field in ipairs(set.fields) do
+                        local fieldKey = guide.getKeyName(field)
+                        if fieldKey then
+                            -- already processed above
+                            goto CONTINUE
+                        end
+                        local keyType = type(key)
+                        if keyType == 'table' then
+                            -- ---@field [integer] boolean -> class[integer]
+                            local fieldNode = vm.compileNode(field.field)
+                            if vm.isSubType(suri, key.name, fieldNode) then
+                                local nkey = '|' .. key.name
+                                if not searchedFields[nkey] then
+                                    pushResult(field, true)
+                                    hasFounded[nkey] = true
+                                end
+                            end
+                        else
+                            local keyObject
+                            if keyType == 'number' then
+                                if math.tointeger(key) then
+                                    keyObject = { type = 'integer', [1] = key }
+                                else
+                                    keyObject = { type = 'number', [1] = key }
+                                end
+                            elseif keyType == 'boolean'
+                            or     keyType == 'string' then
+                                keyObject = { type = keyType, [1] = key }
+                            end
+                            if keyObject and field.field.type ~= 'doc.field.name' then
+                                -- ---@field [integer] boolean -> class[1]
+                                local fieldNode = vm.compileNode(field.field)
+                                if vm.isSubType(suri, keyObject, fieldNode) then
+                                    local nkey = '|' .. keyType
+                                    if not searchedFields[nkey] then
+                                        pushResult(field, true)
+                                        hasFounded[nkey] = true
+                                    end
+                                end
+                            end
+                        end
+                        ::CONTINUE::
+                    end
+                end
+            end
+            copyToSearched()
+        end
+
         for _, set in ipairs(sets) do
             if set.type == 'doc.class' then
                 -- look into extends(if field not found)
-- 
2.47.1.windows.2

[tomlau10]

By searching @field [string] in github issues, I actually found 2 related issues:

• Annotation field [string] any prevents to define functions #2171
• Typed field overrides the type of other fields #2711

So this is actually a bug, and I tested that my patch will fix them 😃
I will consider opening a PR tmr

[sewbacca]

Thank you @tomlau10! The patch works :D

[tomlau10]

👀 I just opened PR #3224