Forest Logo
search
package_2

typeguard

By @itzbbbbas

Roblox

Mirrored from Wally

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.3.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.

BuilderOptionsRejects
T.numberdefault, min, max, step, nana non-number, NaN or infinity unless nan = true, a value outside min..max, a value off the step grid
T.intdefault, min, max, stepT.number plus a fraction
T.stringdefault, max_length, min_length, one_of, patterna non-string, a long or short string, a value outside one_of, a string.match miss
T.booldefaulta non-boolean
T.anydefaultnothing
T.enummembers, defaulta value not in members, compared with ==
T.literal(value)anything but value
T.bigdefaulta value that is not a { m, e } big number
T.vector3default, max_magnitudea NaN or infinite component, a long vector
T.cframedefaulta NaN or infinite position
T.vector2, T.udim2, T.number_range, T.rectdefaultthe wrong typeof, a NaN or infinite component
T.brick_color, T.fontdefaultthe wrong typeof
T.color3, T.enum_itemdefaultthe wrong typeof
T.Functiona non-function
T.instanceclassa non-Instance, or one that fails IsA(class)
T.struct(shape)exact, max_keys, min_keysa missing or failing field, an unknown key unless exact = false, too many or too few keys
T.dict(value)key, max_count, min_count, defaulta failing value, a key that is the wrong type or fails the key spec, too many or too few entries
T.array(value)max_count, min_count, defaulta hole, a failing element, too many or too few elements
T.optional(inner)a non-nil value that fails inner
T.one_of(a, b, ...)a value that fails every shape
T.refine(inner, predicate, message?)what inner rejects, then a false predicate(value)
T.variant(tag, shapes)a value with an unknown tag, or one that fails its tag's shape. The tag field joins each shape as a literal
T.server_only(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.

Struct combinators build a new struct from an old one and keep its exact, max_keys and min_keys. They return any, so annotate the binding.

CombinatorResult
T.pick(spec, keys)only the listed fields
T.omit(spec, keys)every field but the listed ones
T.partial(spec)every field wrapped in T.optional
T.merge(a, b)the fields of a and b, b wins. Pass a raw table as b to add fields

Functions

FunctionReturns
Typeguard.check(value, spec, path?)nil on pass, else path.key: reason
Typeguard.ok(value, spec)boolean
Typeguard.parse(value, spec, path?)the value typed as the spec, or nil and the reason. ok does not narrow, this does
Typeguard.compile(spec)a (value, path?) -> string? checker built once. Same reasons as check, about 2x faster on a nested payload, and it builds a field path only on a reject
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, refine and of
Typeguard.emit(spec, name?)Luau type source, <name> and <name>Paths
Typeguard.BigMathnew, add, sub, mul, div, compare, short, to_string 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

Package Details

Install command (Click to copy)


Version

0.3.0

License

MIT

check_circle

Safe for commercial use

Automated license review — not legal advice.