Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/osyrisrblx/t

A Runtime Typechecker for Roblox
https://github.com/osyrisrblx/t

lua roblox

Last synced: 3 months ago
JSON representation

A Runtime Typechecker for Roblox

Awesome Lists containing this project

README 

        
t




	

		CI Status

	

	

		Coverage Status

	






	A Runtime Type Checker for Roblox




 



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.](https://raw.githubusercontent.com/osyrisrblx/t/master/lib/init.lua)



## 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](http://wiki.roblox.com/index.php?title=API:Class/Instance/FindFirstAncestorWhichIsA))



**`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](https://github.com/gcanti/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))`