t

t is a module which allows you to create type definitions to check values against.

Download

You can download the latest copy of t here.

Why?

When building large systems, it can often be difficult to find type mismatch bugs.\
Typechecking helps you ensure that your functions are recieving the appropriate types for their arguments.

In Roblox specifically, it is important to type check your Remote objects to ensure that exploiters aren't sending you bad data which can cause your server to error (and potentially crash!).

Crash Course

``Lua
local t = require(path.to.t)

local fooCheck = t.tuple(t.string, t.number, t.optional(t.string))
local function foo(a, b, c)
assert(fooCheck(a, b, c))
-- you can now assume:
-- a is a string
-- b is a number
-- c is either a string or nil
end

foo() --> Error: Bad tuple index #1: string expected, got nil
foo("1", 2)
foo("1", 2, "3")
foo("1", 2, 3) --> Error: Bad tuple index #3: (optional) string expected, got number
`

Check out src/t.spec.lua for a variety of good examples!

Primitives

|Type | |Member |
|---------|--|-----------|
|boolean |=>|t.boolean |
|thread |=>|t.thread |
|function |=>|t.callback |
|nil |=>|t.none |
|number |=>|t.number |
|string |=>|t.string |
|table |=>|t.table |
|userdata |=>|t.userdata |

Any primitive can be checked with a built-in primitive function.\
Primitives are found under the same name as their type name except for two:
- nil -> t.none
- function -> t.callback

These two are renamed due to Lua restrictions on reserved words.

All Roblox primitives are also available and can be found under their respective type names.\
We won't list them here to due how many there are, but as an example you can access a few like this:
`Lua
t.Instance
t.CFrame
t.Color3
t.Vector3
-- etc...
`

You can check values against these primitives like this:
`Lua
local x = 1
print(t.number(x)) --> true
print(t.string(x)) --> false, "string expected, got number"
`

Type Composition


Often, you can combine types to create a composition of types.\
For example:
`Lua
local mightBeAString = t.optional(t.string)
print(mightBeAString("Hello")) --> true
print(mightBeAString()) --> true
print(mightBeAString(1)) --> false, "(optional) string expected, got number"
`

These get denoted as function calls below with specified arguments. check can be any other type checker.

Meta Type Functions

The real power of t is in the meta type functions.

t.any\
Passes if value is non-nil.

t.literal(...)\
Passes if value matches any given value exactly.

t.keyOf(keyTable)\
Returns a t.union of each key in the table as a t.literal

t.valueOf(valueTable)\
Returns a t.union of each value in the table as a t.literal

t.optional(check)\
Passes if value is either nil or passes check

t.tuple(...)\
You can define a tuple type with t.tuple(...).\
The arguments should be a list of type checkers.

t.union(...) - ( alias: t.some(...) )\
You can define a union type with t.union(...).\
The arguments should be a list of type checkers.\
At least one check must pass\
i.e. t.union(a, b, c) -> a OR b OR c

t.intersection(...) - ( alias: t.every(...) )\
You can define an intersection type with t.intersection(...).\
The arguments should be a list of type checkers.\
All checks must pass\
i.e. t.intersection(a, b, c) -> a AND b AND c

t.keys(check)\
Matches a table's keys against check

t.values(check)\
Matches a table's values against check

t.map(keyCheck, valueCheck)\
Checks all of a table's keys against keyCheck and all of a table's values against valueCheck

There's also type checks for arrays and interfaces but we'll cover those in their own sections!

Special Number Functions

t includes a few special functions for checking numbers, these can be useful to ensure the given value is within a certain range.

General:\
t.nan\
determines if value is NaN\
All of the following checks will not pass for NaN values.\
If you need to allow for NaN, use t.union(t.number, t.nan)

t.integer\
checks t.number and determines if value is an integer

t.numberPositive\
checks t.number and determines if the value > 0

t.numberNegative\
checks t.number and determines if the value < 0

Inclusive Comparisons:\
t.numberMin(min)\
checks t.number and determines if value >= min

t.numberMax(max)\
checks t.number and determines if value <= max

t.numberConstrained(min, max)\
checks t.number and determines if min <= value <= max

Exclusive Comparisons:\
t.numberMinExclusive(min)\
checks t.number and determines if value > min

t.numberMaxExclusive(max)\
checks t.number and determines if value < max

t.numberConstrainedExclusive(min, max)\
checks t.number and determines if min < value < max

Special String Functions

t includes a few special functions for checking strings

t.match(pattern)\
checks t.string and determines if value matches the pattern via string.match(value, pattern)

Arrays

In Lua, arrays are a special type of table where all the keys are sequential integers.\
t has special functions for checking against arrays.

t.array(check)\
determines that the value is a table and all of it's keys are sequential integers and ensures all of the values in the table match check

Interfaces


Interfaces can be defined through t.interface(definition) where definition is a table of type checkers.\
For example:
`Lua
local IPlayer = t.interface({
Name = t.string,
Score = t.number,
})

local myPlayer = { Name = "TestPlayer", Score = 100 }
print(IPlayer(myPlayer)) --> true
print(IPlayer({})) --> false, "[interface] bad value for Name: string expected, got nil"
`

You can use t.optional(check) to make an interface field optional or t.union(...) if a field can be multiple types.

You can even put interfaces inside interfaces!
`Lua
local IPlayer = t.interface({
Name = t.string,
Score = t.number,
Inventory = t.interface({
Size = t.number
})
})

local myPlayer = {
Name = "TestPlayer",
Score = 100,
Inventory = {
Size = 20
}
}
print(IPlayer(myPlayer)) --> true
`

If you want to make sure an value _exactly_ matches a given interface (no extra fields),\
you can use t.strictInterface(definition) where definition is a table of type checkers.\
For example:
`Lua
local IPlayer = t.strictInterface({
Name = t.string,
Score = t.number,
})

local myPlayer1 = { Name = "TestPlayer", Score = 100 }
local myPlayer2 = { Name = "TestPlayer", Score = 100, A = 1 }
print(IPlayer(myPlayer1)) --> true
print(IPlayer(myPlayer2)) --> false, "[interface] unexpected field 'A'"
`

Roblox Instances

t includes two functions to check the types of Roblox Instances.

t.instanceOf(className[, childTable])\
ensures the value is an Instance and it's ClassName exactly matches className\
If you provide a childTable, it will be automatically passed to t.children()

t.instanceIsA(className[, childTable])\
ensures the value is an Instance and it's ClassName matches className by a IsA comparison. (see here)

t.children(checkTable)\
Takes a table where keys are child names and values are functions to check the children against.\
Pass an instance tree into the function.

Warning! If you pass in a tree with more than one child of the same name, this function will always return false

Roblox Enums

t allows type checking for Roblox Enums!

t.Enum\
Ensures the value is an Enum, i.e. Enum.Material.

t.EnumItem\
Ensures the value is an EnumItem, i.e. Enum.Material.Plastic.

but the real power here is:

t.enum(enum)\
This will pass if value is an EnumItem which belongs to enum.

Function Wrapping


Here's a common pattern people use when working with t:
`Lua
local fooCheck = t.tuple(t.string, t.number, t.optional(t.string))
local function foo(a, b, c)
assert(fooCheck(a, b, c))
-- function now assumes a, b, c are valid
end
`

t.wrap(callback, argCheck)\
t.wrap(callback, argCheck) allows you to shorten this to the following:
`Lua
local fooCheck = t.tuple(t.string, t.number, t.optional(t.string))
local foo = t.wrap(function(a, b, c)
-- function now assumes a, b, c are valid
end, fooCheck)
`

OR

`Lua
local foo = t.wrap(function(a, b, c)
-- function now assumes a, b, c are valid
end, t.tuple(t.string, t.number, t.optional(t.string)))
`

Alternatively, there's also:
t.strict(check)\
wrap your whole type in t.strict(check) and it will run an assert on calls.\
The example from above could alternatively look like:
`Lua
local fooCheck = t.strict(t.tuple(t.string, t.number, t.optional(t.string)))
local function foo(a, b, c)
fooCheck(a, b, c)
-- function now assumes a, b, c are valid
end
`

Tips and Tricks

You can create your own type checkers with a simple function that returns a boolean.\
These custom type checkers fit perfectly with the rest of t's functions.

If you roll your own custom OOP framework, you can easily integrate t with a custom type checker.\
For example:
`Lua
local MyClass = {}
MyClass.__index = MyClass

function MyClass.new()
local self = setmetatable({}, MyClass)
-- setup instance
return self
end

local function instanceOfClass(class)
return function(value)
local tableSuccess, tableErrMsg = t.table(value)
if not tableSuccess then
return false, tableErrMsg or "" -- pass error message for value not being a table
end

local mt = getmetatable(value)
if not mt or mt.__index ~= class then
return false, "bad member of class" -- custom error message
end

return true -- all checks passed
end
end

local instanceOfMyClass = instanceOfClass(MyClass)

local myObject = MyClass.new()
print(instanceOfMyClass(myObject)) --> true
`

Known Issues

You can put a t.tuple(...) inside an array or interface, but that doesn't really make any sense..\
In the future, this may error.

Notes

This library was heavily inspired by io-ts, a fantastic runtime type validation library for TypeScript.

Why did you name it t?

The whole idea is that most people import modules via:\
local X = require(path.to.X)\
So whatever I name the library will be what people name the variable.\
If I made the name of the library longer, the type definitions become more noisy / less readable.\
Things like this are pretty common:\
local fooCheck = t.tuple(t.string, t.number, t.optional(t.string))`