Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

Feature Request: Typestate / Self-Type Refinement for Method Calls

Aberta
  • Algo errado?
#3,407 3 comentários 0 reações 0 responsáveis Ver no GitHub

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
5/5
Tempo estimado
Mais de uma semana
Facilidade para iniciantes
45/100
Tipo de issue
Funcionalidade
Clareza
Razoavelmente clara
Status de atividade
Pouca atividade
Stack de tecnologia
lua
Domínio
devtools

Direção de pesquisa

A issue não nomeia arquivos de implementação nem testes. Comece revisando como o LuaLS atualmente lida com ---@cast explícitos e chamadas de métodos; em seguida, avalie o escopo de refinamento proposto: chamadas diretas, o escopo atual e anotações explícitas. O trabalho estará concluído quando houver um design de anotações definido, com refinamento de capacidades sensível ao fluxo, autocompletar e diagnósticos funcionando sem um cast manual.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

Problem

Lua is a highly dynamic language, and many real-world Lua frameworks mutate object capabilities at runtime.

This pattern is especially common in:

  • game engines
  • UI frameworks
  • ECS architectures
  • builder APIs
  • runtime mixin systems
  • userdata bindings from native engines

Currently, LuaLS/LuaCats cannot properly express:

"after calling this method, self now has additional capabilities/methods"

This becomes a major DX limitation for frameworks that dynamically extend objects.

Real-world Example

Consider a UI framework where all elements start as a generic UIElement.

---@class UIElement
local UIElement = {}

Calling:

element:setupUIImage()

injects image-related functionality into the element at runtime:

element:setImage(...)

However, LuaLS still sees element as only UIElement.

The only current workaround is manual casting:

element:setupUIImage()

---@cast element UIImage
element:setImage(material)

This works technically, but becomes repetitive and hurts DX significantly in large codebases.

Comparison to TypeScript

TypeScript supports type refinement after method calls through assertion signatures such as:

asserts this is SomeType

This allows APIs to safely refine object types after capability-changing methods.

A good real-world example is discord.js, where Interaction objects can be refined into subtypes through methods like:

interaction.isButton()
interaction.isChatInputCommand()

After refinement, TypeScript understands the new subtype automatically.

Lua frameworks often use similar runtime patterns, but LuaLS currently cannot model them.

Proposed Solution

Introduce a LuaCats annotation for self-type refinement / capability injection.

Possible syntax examples:

---@injects UIImage
function UIElement:setupUIImage() end

or:

---@mutates self UIImage
function UIElement:setupUIImage() end

or:

---@becomes UIImage
function UIElement:setupUIImage() end

Expected Behavior

After:

element:setupUIImage()

LuaLS would understand:

element :: UIElement & UIImage

allowing:

element:setImage(...)

without requiring manual casts.

Why This Matters

This would greatly improve support for:

  • dynamic Lua architectures
  • runtime capability injection
  • engine bindings
  • UI frameworks
  • builder APIs
  • fluent APIs
  • mixin systems

while keeping Lua's dynamic nature intact.

This feature would also reduce:

  • repetitive ---@cast
  • noisy annotations
  • inaccurate supersets in base classes
  • degraded autocomplete quality

Additional Notes

This feature does not need to become full typestate analysis or advanced dependent typing.

Even a pragmatic flow-sensitive refinement system limited to:

  • direct method calls
  • current scope
  • explicit annotations only

would already provide massive DX improvements.

Example Use Case

---@class UIImage
---@field setImage fun(self: UIImage, material: string)

---@class UIElement

---@injects UIImage
function UIElement:setupUIImage() end

local element = UIElement.new()

element:setupUIImage()

element:setImage("icon")

Expected:

  • autocomplete works
  • diagnostics recognize setImage
  • no manual cast required

Thanks for all the amazing work on LuaLS and LuaCats.
This would significantly improve tooling support for dynamic Lua patterns commonly used in real-world frameworks and game engines.

Linguagem predominante
Lua
Estrelas
4.4k
Forks
442
Merge médio
8d 9h
PRs com merge (30d)
1

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de LuaLS/lua-language-server

Todas as issues de LuaLS/lua-language-server

Issues semelhantes

Mais issues de Lua

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.