Typeguard

One runtime type checker for Roblox Luau. Each builder returns its spec cast to the Luau type it checks, so typeof(spec) is the static type and a shape is written once. Remote payloads, attribute schemas, content registries and DataStack store templates share it.

Typeguard = "itzbbbbas/typeguard@0.1.0"

local Typeguard = require(ReplicatedStorage.Packages.Typeguard)
local T = Typeguard

local GRAB = T.Struct({
	uid = T.String({ max_length = 64 }),
	at = T.Vector3({ max_magnitude = 4096 }),
	leaf = T.Optional(T.Int({ min = 1 })),
})
type Grab = typeof(GRAB)

local reason = Typeguard.Check(payload, GRAB, "payload")
if reason then
	warn(reason) -- payload.at: magnitude 9000 above max 4096
	return
end
local grab = payload :: Grab

Builders

Every builder takes one options table. default rides along for a template or a schema and is never checked.

Builder	Options	Rejects
`T.Number`	`default, min, max, nan`	a non-number, NaN or infinity unless `nan = true`, a value outside `min..max`
`T.Int`	`default, min, max`	`T.Number` plus a fraction
`T.String`	`default, max_length, one_of, pattern`	a non-string, a long string, a value outside `one_of`, a `string.match` miss
`T.Bool`	`default`	a non-boolean
`T.Any`	`default`	nothing
`T.Enum`	`members, default`	a value not in `members`, compared with `==`
`T.Literal(value)`		anything but `value`
`T.Big`	`default`	a value that is not a `{ m, e }` big number
`T.Vector3`	`default, max_magnitude`	a NaN or infinite component, a long vector
`T.CFrame`	`default`	a NaN or infinite position
`T.Color3`, `T.EnumItem`	`default`	the wrong `typeof`
`T.Function`		a non-function
`T.Instance`	`class`	a non-Instance, or one that fails `IsA(class)`
`T.Struct(shape)`	`exact, max_keys`	a missing or failing field, an unknown key unless `exact = false`, too many keys
`T.Dict(value)`	`key, max_count, default`	a failing value, a key of the wrong type, too many entries
`T.Array(value)`	`max_count, default`	a hole, a failing element, too many elements
`T.Optional(inner)`		a non-nil value that fails `inner`
`T.OneOf(a, b, ...)`		a value that fails every shape
`T.ServerOnly(inner)`		what `inner` rejects; sets `server_only` for DataStack replication
`T.Of(value)`		a value whose `typeof` differs, or a table that does not match `value` exactly

A raw value inside a shape is an implicit T.Of. A raw table is an exact struct, so a plain template checks as itself.

Functions

Function	Returns
`Typeguard.Check(value, spec, path?)`	`nil` on pass, else `path.key: reason`
`Typeguard.Ok(value, spec)`	boolean
`Typeguard.Defaults(spec)`	the default tree; an `Optional` is nil, a `Dict` or `Array` is empty
`Typeguard.Is(value)`	true when a builder made it
`Typeguard.Kind(spec)`	`"int"`, `"struct"`, …, or `"raw"`
`Typeguard.Unwrap(spec)`	the spec under `Optional` and `Of`
`Typeguard.Emit(spec, name?)`	Luau type source, `<name>` and `<name>Paths`
`Typeguard.BigMath`	`New`, `Add`, `Sub`, `Mul`, `Div`, `Compare`, `Short`, `ToString` for big numbers

Nothing touches a Roblox service at load, so the package runs under Lune and zune. Roblox datatype checks use typeof, so they need Roblox or a runtime that provides those datatypes.

Develop

zune run tests/lib.spec.luau
stylua --check src tests
selene src
npm run docs:check

typeguard

By @itzbbbbas

Typeguard

Builders

Functions

Develop

Package Details

Install command (Click to copy)

Version

License