I was expecting Teal to be "Lua + type annotations", similar to Mypy. However from a quick look it does indeed seem to be a "dialect" in its own right. Teal is Lua-like and compiles to Lua, but there's more to it than just static types. Perhaps it's more similar to TypeScript?
For example, Teal replaces Lua's tables - the language's signature single, highly-flexible data structure - with separate arrays, tuples, maps, records and interfaces. It changes the variable scoping rules and even adds macro expressions.
Teal therefore seems substantially more complex than Lua. The author recognizes this in the conclusion to a recent presentation [0]: Lua is "small and simple", maybe Teal is "something else"? Lua is for "scripting", maybe Teal is better suited to "applications/libraries"?
By ambitiously adding useful features, could Teal push the upstream to make progress? Probably not because Lua's scope is intended to be small (and we're no longer in the same context as 2015 era Typescript and tc39), but it's interesting to think about.
Anyway, that has not stopped large parts of the JavaScript ecosystem -- notably Angular -- from using an experimental variant of decorators, such as the one provided by TypeScript. [2]
Mypy is just one type checker for Python, but there are many others including pyright. In fact pyright is quickly becoming the dominant checker over mypy.
IIRC Mypy started off as a type annotation syntax and corresponding type checker for Python. Mypy's type annotations were adopted by Python itself (in version 3.5 - PEP 484), which reduced Mypy's role to be just a type checker.
Since then, type annotations have indeed become a core part of Python - not only are they used in frameworks and libraries, but are also required to use language features like @dataclass.
They're all just Lua tables with specialized type checking for specific behavior.
I really wish the Lua authors would add official types to Lua. The time has come.
Never going to happen IMO. Adding static types would change the nature of the language completely, even more than it has in Python.
As Teal shows, it would require giving up one of Lua's core features: tables as the language's single data structure. It would significantly complicate a language known for its simplicity.
Even the implementation would need to change radically - adding a type checker would invalidate the current approach of using a single-pass source-to-bytecode compiler.
Funny you should mention that:
> It aims to fill a niche similar to that of TypeScript in the JavaScript world, but adhering to Lua's spirit of minimalism, portability and embeddability.
https://github.com/Benjamin-Dobell/IntelliJ-Luanalysis
Admittedly, I've been focused on some other things recently, but still with some focus on type safety e.g. https://breaka.club/blog/godots-most-powerful-scripting-lang...
Teal still compiles all those things into plain Lua tables, it's just that the type system has different table subtypes for better type checking. I think the variable scoping is also the same as regular Lua?
I mean that's exactly what the page says, doesn't it?
> It aims to fill a niche similar to that of TypeScript in the JavaScript world, but adhering to Lua's spirit of minimalism, portability and embeddability.
I realized my initial dislike for lua stemmed from my experience with javascript (back in the jwquery days), where maintaining large codebases felt like navigating a minefield. The lack of type system made it all too easy to introduce bugs.
But lua isn't like that. It's not weakly typed like javascript - it's more akin to pythons dynamic duck typing system. Its simplicity makes it remarkably easy to write clean maintainable code. Type checking with type is straightforward compared to python, mostly because there are only five basic types (technically seven but I've never used userdata or thread). And I even started to enjoy using metatables once I understood how and when to apply them.
That being said, lua's lack of popularity probably stems from its limited stdlib, which often feels incomplete, and the absence of a robust package manager. luarocks is a pain to work with.
All that being said, I don't really see the point of using this project.
While I do wish type annotations were a native feature, the ones provided by the lsp are good enough for me.
And indexing arrays starting from 1 rather than 0.
>>> A table with exactly one border is called a sequence. For instance, the table {10, 20, 30, 40, 50} is a sequence, as it has only one border (5). The table {10, 20, 30, nil, 50} has two borders (3 and 5), and therefore it is not a sequence. (The nil at index 4 is called a hole.) The table {nil, 20, 30, nil, nil, 60, nil} has three borders (0, 3, and 6) and three holes (at indices 1, 4, and 5), so it is not a sequence, too. The table {} is a sequence with border 0. Note that non-natural keys do not interfere with whether a table is a sequence
Not based on my experience with even just medium-sized lua codebases. Anything over a few thousand lines and in continuous development has been a mess. Not lua's fault per se¹ but the only thing in my experience that compares is what you'd see in pre-laravel php. Every significant codebase is a messy ad hoc one-off framework in its own right.
A lot of people, as always when it comes up, are speaking of their recreational, small-project or config system lua code. Which is fine, it's good for that. But I have a lot of professional experience working in live production lua codebases and my experiences with it are different over there.
¹ A lot of large lua projects started as someone's first lua project or maybe even first code project at all, which is a tremendous accomplishment for a language but not a smooth ride for maintainers taking over those projects.
What? No, Lua's type system is practically identical to JavaScript's.
Even metatables are extraordinarily similar to prototype chains via __index (though much more powerful since they allow for operator overloading, which I wish JS had).
Lua doesn't have as many warts as languages like JavaScript or PHP do. The worst offenders are probably the 1-indexing (more of an stdlib issue than a language issue) and variables being global by default (same as JavaScript). It's a minimalist language and I guess this is one of the reason it is so popular as embedded language. But that's exactly why I find myself preferring even (modern) JavaScript to Lua. Lua is so barebones it's just too painful to use for anyone who got used to programming in other languages.
> That being said, lua's lack of popularity probably stems from its limited stdlib, which often feels incomplete, and the absence of a robust package manager. luarocks is a pain to work with.
And that's the crux of it. I guess many people are fine with writing tons of WET code using a barebones library and a bunch of copy-pasted code files thrown around when it comes to their personal scripts. That's all fine, but my brain isn't wired that way and I just feel excruciating pain every time I realize I have to write Lua again.
Luarocks is painful to use, but the main problem is that every embedded Lua you use deals with packages differently. Lua 5.1, 5.2, 5.3, 5.4 and LuaJIT are all incompatible with each other, since every version has breaking changes. Additionally, due to the lack of a standard library, many lua packages have to rely on native code, which makes portability and compatibility even worse. It all means that Lua doesn't really have a package ecosystem.
> But lua isn't like that. It's not weakly typed like JavaScript - it's more akin to pythons dynamic duck typing
I don't understand how Lua is less weakly typed than Java. Both of these languages have dynamic typing and do not support any type annotations or type inference in their core dialects, and both languages have "duck typing".
Where I feel JavaScript is vastly superior to Lua is tooling. JavaScript linters and language servers are far more advanced than Lua language servers, to the point where they can detect a lot of errors that I would waste hours on debugging with Lua. Due to Lua's atrociously bad error messages, without writing a lot of error handling code and copious printf statements, it would be quite hard to find where you've even made a typo in a variable name once your code gets large enough.
So yeah, I get why for some people Lua can be fun, because it's conceptually minimalist, but in practice I hate it with passion.
LuaJITted Lua code runs at 80% (on average, sometimes faster!) of the compiled C version of the same algorithm, typically. Lua is embedded in a surprisingly massive number of products: https://en.wikipedia.org/wiki/List_of_applications_using_Lua The startup time of a script is in nanoseconds. An "echo" written in Lua runs faster than the native echo implementation.
The only warts so far are 1-based indexing (you get used to it), and the fact that LuaJIT is stuck at Lua 5.1 while Lua itself is up to 5.3 or 5.4 and has added some niceties... with Lua proper running slower. And no real standard library to speak of (although some would argue that's a feature; there are a few options and different flavors out there if that's what you need, though- Such as functional-flavored ones...)
Anyway, there's nothing else like it out there. Especially with its relative simplicity.
There are also some neat languages that compile to (transpile to?) Lua, and deserve more attention, such as YueScript https://yuescript.org/, which is a still actively-updated enhanced dialect of MoonScript https://moonscript.org/ (described as "Coffeescript for Lua", although it hasn't been updated in 10 years) although neither of these are typed. HOWEVER... there IS this: TypescriptToLua https://typescripttolua.github.io/, which takes advantage of ALL the existing TypeScript tooling, it just outputs Lua instead of JS!
Cannot confirm this. It might be true on selected micro benchmarks. Here are the results of the Are-we-fast-yet benchmark suite, which includes a decent set of benchmarks challenging CPU, cache and memory access: https://github.com/rochus-keller/Oberon/blob/master/testcase....
On average, the C and C++ implementations are five times faster than LuaJIT.
> There are also some neat languages that compile to (transpile to?) Lua
Here is a comprehensive list: https://github.com/hengestone/lua-languages. Lanuages like Oberon or Luon directly compile to LuaJIT bytecode (i.e. not to Lua).
Roblox not only runs entirely on Lua, but they've been working on their own type inference version of Lua named Luau, and open sourced it, and it's still in very active development.
IMO this is the perfect use case for Perl. I mean, it's why Perl was invented, but to this day it remains incredibly good at doing this specific task. It's incredibly easy to write and can be very easy to read, and it's much more robust than bash. But best of all - and the reason I think Perl still has a place in the modern world - it's available on practically every computer on Earth. And it will all work. It's so backwards-compatible that 25 year old scripts will run just fine. It's so portable that nothing even comes close. Also, it's shockingly fast. Faster than you would think. Regex is really powerful and it's been the template for so many regex implementations, but definitely be careful of runaway time complexity.
Anyway, Lua is great too. Really nice for embedding into applications ala VBA. Great for config.
Lack of LuaJIT for 5.1+ isn't that big of a deal for desktop apps. The embedded world is still stuck in 5.1, but for them, the benefits of the latest Lua is marginal.
As someone else have pointed it out, they are cherry picked: https://luajit.org/extensions.html.
LuaJIT is missing bignums, ints that aren’t floats, bit operations, and native utf8 handling, but it can pretty easily be extended with libraries, ffi and metatabling. (I actually made a working bignum library that integrates with gmp, but it has a memory leak somewhere and it’s a rabbit hole/bikeshedding project at this point…)
LLM assistance helps hugely and I really like YueScript’s syntax additions. You can point any LLM at a syntax describing webpage and it will pretty much write that language for you…
Lots of default functionality missing so you MUST have these packages: inspect, luaposix, lrexlib-pcre, lrexlib-posix, lpeg, luastd/stdlib, luasocket, luahttp, luasec, luacheck, penlight
* luajit is unnecessary in almost all cases, you don't need the speed.
* use lsp or luacheck whenever you write something, entr -c luacheck file on everything.
* patterns are not regex which means they do not support lookups, backtracking or |, so you must install lrexlib-pcre or lrexlib-posix (frankly I never need pcre so I stick to lrexlib-gnu or lrexlib-posix).
* overload _ENV so it auto requires unknown things, I have a lua wrapper that does this and it makes it a joy not having all of my scripts with a bunch of require"posix" on all of them
* install inspect to inspect tables
* os.execute and io.popen only accepts strings as parameters which means you should overload it and make a function that accepts tables as well.
* 5.4 is still lacking support for many libraries, 5.3 has most of the libraries.
* assignments default to the global environment so you have to use local keyword or set _ENV to error on assignment (or better yet, don't care, just local _ENV = mymodule)
Overall, Lua is just a mixture of C with a pascal syntax and garbage collection (and also tables which is a weird data structure)
- Lua is great from the integrator/engine dev perspective. It's easy to embed and there are several libraries that help with creating bindings between Lua and your game classes.
- Lua has absolutely terrible runtime performance especially when the GC stalls. You soon learn that you have to start moving code to the native side and carefully consider the APIs that you provide for the game so that you can even dream of any type of performance. Haven't tried LuaJIT since that doesn't work with WASM so it's not an option for me.
- The loose runtime typing in Lua is absolutely terrible, and while it's easy and fast to knock up some simple script you really pay the price when you try to maintain or refactor your code and you have no typing information. For the game engine developer this also makes it very hard to provide any kind of help for the game developer, i.e. "intellisense" kind of functionality. I've basically "solved" this by assuming that variables have certain name suffixes and prefixes and when those are present I assume that it has a certain type which lets me provide a list of functions in the script editor to the game developer. Far from perfect. [see link below]
https://github.com/ensisoft/detonator/blob/master/screens/ed...
But yeah, PUC-Rio Lua is not fast, but it is acceptable, and maybe one of the most performant of all non-JIT dynamic languages. If you need speed, JIT is a requirement.
So Teal is to Lua as TypeScript is to JavaScript. Which means it automatically plays well with any Lua environment. Unlike luau and nelua which are also statically typed but have their own runtimes.
What version of Lua does it use? Lua gets new versions every few years so I don't know why so many impls don't continuously upgrade to the latest version.
Genius design.
LuaJIT is famously on 5.1 with no signs of moving.
It's got an awesome C API. It's fast, lightweight, and embeddable. It's more performant than Python. It's a staple in video game scripting.
Semantically, Lua is almost identical to the core of JavaScript. Metatables are a genius alternative to prototype chains.
Lua's syntax is beautifully simple and unambiguous, but at the cost of being moderately inconvenient in 2025 unfortunately. It could benefit from an ESNext-style renewal.
I get why they made the C API that way, but in practice it's very easy to get wrong.
I'm not sure how fast vanilla Lua is today compared to similar languages. I think LuaJIT (and Luau?) are most often used when performance is needed.
And the extension is .tl
to be used via `global_env_def` described in https://teal-language.org/book/declaration_files.html
And though they mention it as being for third party libraries, this also seems a way to declare types for your own code in an external file, thus keeping your code as runnable Lua and benefiting from type checking too. That seems like a neat workflow for developing Neovim plugins with this: instead of having to constantly regenerate Lua from .tl files so Neovim can pick up your changes during development.
Edit: or maybe https://github.com/teal-language/tl#loading-teal-code-from-l... this is the easier way to do it. `require` and use `loader` during development, generate the Lua once things are somewhat stable.
The declaration file isn't used to typecheck the code the declaration is for. It is only for consumers of the code.
I was editing my comment during your reply, and added this:
> or maybe https://github.com/teal-language/tl#loading-teal-code-from-l... this is the easier way to do it. `require` and use `loader` during development, generate the Lua once things are somewhat stable.
Does that sound like the right idea then?
[1] https://github.com/ruby/rbs [2] https://mypy.readthedocs.io/en/stable/stubs.html
I can’t tell what it is exactly. Maybe those weird global rules? Maybe inspection of objects and metatables? Maybe the weird mix of verbose and not verbose (e.g. getting output of a process requiring popen and manual handling but then function can take more arguments than declared and whateva) or exotic control flow and structures (metatable, global env).
It’s interesting language, but I just grit my teeth every time I’m interacting with it.
A couple things I want from teal: 1. I wish there was a better way to bundle files together. I have a little build.lua, but eh, I think it could be better. I know of cyan and everything but I feel like that was developed for a different application than mine. I want to have 1 complete file that I can just give people and allow them to do synbio work in any target language with a lua machine. 2. There are some annoyances around luajit vs lua5.1 functionality 3. The compiler yelling at you gets old for integrating raw lua. I tried to port json.lua in and even with the definition file, I couldn't embed the whole json.lua without having compiler errors. So eventually I just imported it as a string that is type checked, which is bad 4. I really wish syntax highlighting on github was a thing
The good bits:
It's pretty much complete. I used it a couple years ago and there were things with generics that I just couldn't do, but now it is much better. For example, how I use generics for the different parsers (fastq, fasta, genbank, slow5, pileup, etc) https://github.com/Koeng101/libB/blob/dev/src/dnadesign/src/...
Overall, love it! It is one of those pieces of software which is nearly complete, and I love using software like that.
On your wishlist items:
1. There are a few third-party projects that bundle Lua code. One that comes to mind is https://lrocket.codeberg.page/ — I don't know if this functionality should be brought into Teal itself, it sounds to me like something better left to the surrounding tooling?
2. Unfortunately those annoyances are part of the heterogeinity of the Lua ecosystem, but Teal tries to paper over them using the compat53 library (which, granted, is not available everywhere if you want to do a pure-Lua deployment on existing Lua environments). The --gen-target and --gen-compat flags should still help some, hopefully!
3. Not sure what you mean there -- you mean adding chunks of untyped Lua _in the same file_? I think that if you have a json.lua and a json.d.tl file, then it should use the definition file only and leave the .lua file alone. At least that's the intended behavior!
4. That's up to GitHub :) Last time I checked their docs I think they want something like 100 or 200 projects using the language for considering adding native highlighting for it on the website. But you can add a .gitattributes file to the root of your repository like this https://github.com/teal-language/tl/blob/master/.gitattribut... and at least it will display .tl files with .lua highlighting.
Again, thank you so much for the feedback!
2. If I recall correctly, gen-target didn't hit it because I was using some very esoteric bullshit from the luajit internal spec that couldn't have nice typing
3. Yes, untyped lua in the same file. The problem is that I want everything in a single file for distribution and embedding - kind of like the SQLite amalgamation. It'd be super cool to just add in my dnadesign.lua or dnadesign.tl file and have full bioinformatics in almost any language! Definition files don't work as well there - I still kind of use them for the type definitions, but then embed the raw file as a string
4. YES THANK YOU! I'm not sure if it is in the docs but this is SO useful!
I used Lua on the backend and my frontend was already in TypeScript, so it was nice that I could reuse the backend types without conversion in the frontend.
Arrays: {number}
How does it disambiguate it? Are single-element tuples just never used in practice? To be fair, maybe the only time I've had to use them in TypeScript is via Parameters<T>
Firefox 138.0.1
It is gradually typed, so no need to use Teal.
It's not just for performance reasons, and they don't exactly have no features from newer versions. Take a look at the compatibility tables: https://luau.org/compatibility
Also, are there any Lua constructs that are difficult/impossible to type?
Is type checking decidable? (Is the type system Turing complete?)
> How confident are you in the soundness of the type system?
I am confident it is not sound! That is by design. A typical example is how function arguments are bivariant, to allow for callbacks expressed the way programmers usually expect them to work (TypeScript does something similar).
> Also, are there any Lua constructs that are difficult/impossible to type?
Yes, many of them. The type system and the compiler are pragmatically very simple -- there are many design decisions made to favor simplicity of specification and/or implementation. (Compare the single-file, single-pass Teal compiler done mostly by a single person with the amount of engineering resources that Microsoft has put into TypeScript.) For a concrete example, we have special-cased polymorphism for functions, intended to use with very dynamically-typed Lua functions from the broader Lua ecosystem, but you cannot express similar polymorphism in Teal itself.
> Is type checking decidable? (Is the type system Turing complete?)
There is a proof (which I can't find right now) that type checking is not decidable once you combine parametric polymorphism (generics) and intersection types (like the poly functions I mentioned above), but the forms of these features supported by Teal have some restrictions which make me not extend such claims directly. And of course, I can't even claim that the implementation of the theoretical model is bug-free. The model is evolving, the implementation always lags a bit behind.
In any case, the goal for Teal's type system is not academic purity, but pragmatic utility. Other comments in this thread alluded to this as well -- there are practical constraints that come from targeting an existing language and ecosystem. Of course, there are many ways one can approach such challanges. Teal is one of them and there were and are certainly others! Everyone is free to take their shot at where they want to be in the Unix-Philosophy/Worse-is-Better vs. Lisp-Philosophy/The-Right-Thing design gradient.
I think you could basically copy your comment into an FAQ section or something on the front page.
* Your type system cannot be sound. It's going to have escape hatches and exceptions because that's how dynamic languages roll.
* There will always be constructs that you can't type. See above.
* If your type system is going to usefully type enough of the ecosystem, it will be Turing complete.
All of these things are the trade-offs you make when you set out to layer types on a dynamic language, and they're well worth it to get 99% of the way to type safety in a language that otherwise couldn't scale. Theoretical purity is meaningless if the language isn't useful.
This one I disagree with. Type assertions with runtime checks could keep the typed fragments sound, unlike TypeScript and Python. Also see Elixir's strong arrow proposal for how to encode which assertions can be elided on function calls (because the function will assert them already).
I think you could prove that you can't construct a sound & complete type system for Lua. But just saying "Your type system cannot be sound" by itself is definitely wrong. I don't understand why people are throwing out both soundness & completeness, instead of at least retaining one (and I think the choice here is pretty obvious, a sound but incomplete type system is much more useful than an unsound one).
From Flow's website[1] (a type checker for JavaScript):
> Flow tries to be as sound and complete as possible. But because JavaScript was not designed around a type system, Flow sometimes has to make a tradeoff. When this happens Flow tends to favor soundness over completeness, ensuring that code doesn't have any bugs.
I don't understand why other type systems for dynamically typed languages cannot strive for that, and in particular I am pretty salty at TypeScript for explicitly not caring about soundness.
[1]: https://flow.org/en/docs/lang/types-and-expressions/#toc-sou...
Teal's types are hints, like Python's and TypeScript's, so I suspect it's not sound by design.
> Also, are there any Lua constructs that are difficult/impossible to type?
Teal includes several types that model typical uses of Lua tables, e.g. as arrays, maps etc. It doesn't look like it can type fully general use of Lua tables, e.g. using both the "array part" and "hash part" of the same table.
There's plenty of languages with compile time type safety, just go use one of them and leave the perfectly good dynamic ones alone.
Static typing proponents need accept that dynamic typing is a perfectly valid way to write and run code: It's way less verbose, it focuses code on logic rather than syntax (a.k.a. "scripting"), it's easier to mentally parse and generally easier to both learn and use.
Inflicting types on every piece of code written is just ridiculous.
Oof. The same old excuse. So you prematurely optimize your code based on a theoretical line count in the future, cluttering your code with redundant information to save yourself from that one bug you'll encounter in QA anyways. Got it. Makes total sense. I bet you like Java FactoryFactoryImpls as well.
If you already know your code will reach 10 kloc in a project where catching a type related bug is that important, choose an appropriate type safe language. So many wasted man hours dealing with truly pedantic details.
