@thigasdevelopment/luam 0.17.0 → 0.18.1

package/README.md

@@ -44,7 +44,7 @@ class Luam {
     end
 }
 
-local luam = new Luam('0.15.6')
+local luam = new Luam('0.18.0')
 
 outputServerLog(luam:compile('src/server/main.luam'))
 ```
@@ -232,7 +232,7 @@ name = 'my-resource'
 serverPath = 'C:/MTA Server'
 ```
 
-Optional fields cover `meta.xml` info, `compilerOptions`, `sources`, `assets`,
+Optional fields cover `meta.xml` info, `compiler`, `sources`, `assets`,
 `dependencies`, `engine.minVersion`, `environment`, `outDir`, `loadOrder`,
 `output`, `helpers`, `resourcesDir`, `development.logs` and
 `development.server.executable`.
@@ -248,7 +248,20 @@ Optional fields cover `meta.xml` info, `compilerOptions`, `sources`, `assets`,
 The **Luam** VS Code extension runs a language server built on the same frontend
 as the CLI, so the editor and the build never disagree: syntax highlighting,
 diagnostics on every keystroke, scoped completion, hover types, go to
-definition, find references and rename.
+definition, find references and rename. It ships the `Luam Dark` and
+`Luam Light` themes — pick one under **File → Preferences → Theme → Color
+Theme**:
+
+<table>
+<tr>
+<td><img src="assets/theme-luam-dark.svg" alt="The README example highlighted by the Luam Dark theme" width="100%"></td>
+<td><img src="assets/theme-luam-light.svg" alt="The README example highlighted by the Luam Light theme" width="100%"></td>
+</tr>
+<tr>
+<td align="center"><sub><b>Luam Dark</b></sub></td>
+<td align="center"><sub><b>Luam Light</b></sub></td>
+</tr>
+</table>
 
 Supported and auto-installed by `luam setup`: VS Code, VS Code Insiders, Cursor,
 VSCodium and Windsurf. The language server itself is editor-agnostic and speaks
@@ -262,16 +275,22 @@ VSCodium and Windsurf. The language server itself is editor-agnostic and speaks
 
 ## Known limitations
 
-- **No type narrowing.** `if value ~= nil then` does not refine `string?`.
-- **Declaration order matters for classes within a file.**
+- **Narrowing reaches names, not fields.** `if value ~= nil then` refines a local;
+  `self.value` keeps its declared type however you test it.
+- **A class is a type everywhere, a value from its declaration** — `extends` may
+  name a parent written further down, a top-level `new` may not.
 - **The MTA catalog can lag a release** — a newer function stays `any`.
 - **No static members, declared metamethods, or generic classes.**
-- **The editor does not re-check an open file when another one changes.**
+- **The editor re-checks by declaration** — a declaration change re-analyzes every
+  file that can see it, an edit inside a function body only its own file.
 - **An export is named, never verified** against the side that calls it.
+- **Type annotations are erased**, so validate anything a client can send.
 
 > [Limitations](https://thigasdevelopment.github.io/luam/en/reference/limitations)
 > · [Limitações](https://thigasdevelopment.github.io/luam/pt-br/reference/limitations)
-> — with the workaround for each.
+> — each one labelled planned, design boundary, upstream or platform constraint,
+> with the workaround. The decisions behind the boundaries are recorded in
+> [`docs/adr`](docs/adr).
 
 ---
 

package/lua/class.lua

@@ -24,21 +24,69 @@ local function bindSuper(value, inherited)
     end
 end
 
+local function bindLateSuper(definition, key, value)
+    return function(self, ...)
+        local inherited = definition.__super and definition.__super[key]
+
+        if type(inherited) ~= 'function' then
+            return value(self, ...)
+        end
+
+        return bindSuper(value, inherited)(self, ...)
+    end
+end
+
+local function declare(name)
+    local existing = classes[name]
+
+    if existing then
+        return existing
+    end
+
+    local definition = { __name = name, __pending = true }
+
+    classes[name] = definition
+
+    return definition
+end
+
+local function pendingAncestor(definition)
+    local current = definition.__super
+
+    while current do
+        if current.__pending then
+            return current.__name
+        end
+
+        current = current.__super
+    end
+
+    return nil
+end
+
 local function create(name, struct, options)
-    if classes[name] then
+    local definition = classes[name]
+
+    if definition and not definition.__pending then
         error('Class ' .. tostring(name) .. ' already exists.')
     end
 
-    local definition = {
-        __name = name,
-        __super = options.super,
-        __metamethods = options.metamethods,
-    }
+    definition = definition or { __name = name }
+
+    definition.__pending = nil
+    definition.__super = options.super
+    definition.__metamethods = options.metamethods
+
+    local pending = definition.__super and definition.__super.__pending
 
     for key, value in pairs(struct) do
         local inherited = definition.__super and definition.__super[key]
 
-        if type(value) == 'function' and type(inherited) == 'function' then
+        if type(value) ~= 'function' then
+            definition[key] = value
+        elseif pending then
+            definition[key] = bindLateSuper(definition, key, value)
+        elseif type(inherited) == 'function' then
             definition[key] = bindSuper(value, inherited)
         else
             definition[key] = value
@@ -59,11 +107,7 @@ function class(name)
 
     local modifiers = {
         extends = function(self, super)
-            options.super = classes[super]
-
-            if not options.super then
-                error('Class ' .. tostring(name) .. ' extends ' .. tostring(super) .. ', which is not defined.')
-            end
+            options.super = declare(super)
 
             return self
         end,
@@ -131,13 +175,19 @@ end
 function new(name)
     local definition = classes[name]
 
-    if not definition then
+    if not definition or definition.__pending then
         error('Class ' .. tostring(name) .. ' is not defined.')
     end
 
     local constructor = constructors[definition]
 
     if not constructor then
+        local missing = pendingAncestor(definition)
+
+        if missing then
+            error('Class ' .. tostring(name) .. ' extends ' .. tostring(missing) .. ', which is not defined.')
+        end
+
         constructor = createConstructor(definition)
         constructors[definition] = constructor
     end
@@ -170,9 +220,23 @@ function enum(names)
 end
 
 function getClasses()
-    return classes
+    local defined = {}
+
+    for name, definition in pairs(classes) do
+        if not definition.__pending then
+            defined[name] = definition
+        end
+    end
+
+    return defined
 end
 
 function getClass(name)
-    return classes[name]
+    local definition = classes[name]
+
+    if not definition or definition.__pending then
+        return nil
+    end
+
+    return definition
 end