Start typing to search packages!
typeguard
By @itzbbbbas
Roblox
Mirrored from WallyTypeguard
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.
| Builder | Options | Rejects |
|---|---|---|
T.number | default, min, max, step, nan | a non-number, NaN or infinity unless nan = true, a value outside min..max, a value off the step grid |
T.int | default, min, max, step | T.number plus a fraction |
T.string | default, max_length, min_length, one_of, pattern | a non-string, a long or short 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.vector2, T.udim2, T.number_range, T.rect | default | the wrong typeof, a NaN or infinite component |
T.brick_color, T.font | default | the wrong typeof |
T.color3, T.enum_item | 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, min_keys | a missing or failing field, an unknown key unless exact = false, too many or too few keys |
T.dict(value) | key, max_count, min_count, default | a 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, default | a 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.
| Combinator | Result |
|---|---|
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
| Function | Returns |
|---|---|
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.BigMath | new, 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
Safe for commercial use
Automated license review — not legal advice.
