Luau Type Checking Beta

January 16, 2020

Hello!

We’ve been quietly working on building a type checker for Lua for quite some time now. It is now far enough along that we’d really like to hear what you think about it.

I am very happy to offer a beta test into the second half of the Luau effort.

Beta Test

First, a word of caution: In this test, we are changing the syntax of Lua. We are pretty sure that we’ve mostly gotten things right, but part of the reason we’re calling this a beta is that, if we learn that we’ve made a mistake, we’re going to go back and fix it even if it breaks compatibility.

Please try it out and tell us what you think, but be aware that this is not necessarily our final form. 🙂

Beta testers can try it out by enabling the “Enable New Lua Script Analysis” beta feature in Roblox Studio.

Overview

Luau is an ahead-of-time typechecking system that sits atop ordinary Lua code. It does not (yet) feed into the runtime system; it behaves like a super powerful lint tool to help you find bugs in your code quickly.

It is also what we call a gradual type system. This means that you can choose to add type annotations in some parts of your code but not others.

Two Modes

Luau runs in one of two modes: strict, and nonstrict.

Nonstrict Mode

Nonstrict mode is intended to be as helpful as possible for programs that are written without type annotations. We want to report whatever we can without reporting an error in reasonable Lua code.

If a local variable does not have a type annotation and it is not initially assigned a table, its type is any
Unannotated function parameters have type any
We do not check the number of values returned by a function
Passing too few or too many arguments to a function is ok

Strict Mode

Strict mode is expected to be more useful for more complex programs, but as a side effect, programs may need a bit of adjustment to pass without any errors.

The types of local variables, function parameters, and return types are deduced from how they are used
Errors are produced if a function returns an inconsistent number of parameters, or if it is passed the wrong number of arguments

Strict mode is not enabled by default. To turn it on, you need to add a special comment to the top of your source file.

Embedded content

New syntax

You can write type annotations in 5 places:

After a local variable
After a function parameter
After a function declaration (to declare the function’s return type)
In a type alias, and
After an expression using the new as keyword.

Embedded content

Type syntax

Primitive types

nil, number, string, and boolean

any

The special type any signifies that Luau shouldn’t try to track the type at all. You can do anything with an any.

Tables

Table types are surrounded by curly braces. Within the braces, you write a list of name: type pairs:

Embedded content

Table types can also have indexers. This is how you describe a table that is used like a hash table or an array.

Embedded content

Functions

Function types use a => to separate the argument types from the return types.

Embedded content

If a function returns more than one value, put parens around them all.

Embedded content

Unions

You can use a | symbol to indicate an “or” combination between two types. Use this when a value can have different types as the program runs.

Embedded content

Options

It’s pretty commonplace to have optional data, so there is extra syntax for describing a union between a type and nil. Just put a ? on the end. Function arguments that can be nil are understood to be optional.

Embedded content

Type Inference

If you don’t write a type annotation, Luau will try to figure out what it is.

Embedded content

Future Plans

This is just the first step!

We’re excited about a whole bunch of stuff:

Nonstrict mode is way more permissive than we’d like
Generics!
Editor integration