{"id":"itzbbbbas/typeguard","name":"typeguard","scope":"itzbbbbas","platform":"roblox","description":"One runtime type checker for Roblox Luau. Builders return the Luau type they check, so typeof(spec) is the static type. Remote payloads, attribute schemas, content registries and DataStack store templates share it.","version":"0.3.0","latest":"0.3.0","versions":["0.1.0","0.3.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"01085cf2600525a0018dfeffce1c1ec2cd2c6df24e7f12b1b2d345859d3716be","likes":0,"downloads":0,"install":"forest install itzbbbbas/typeguard","url":"https://forest.dev/p/roblox/itzbbbbas/typeguard","files":"https://api.forest.dev/ai/package/roblox/itzbbbbas/typeguard/files","readme":"# Typeguard\n\nOne 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](https://github.com/itzbbbbas/DataStack) store templates share it.\n\n```toml\nTypeguard = \"itzbbbbas/typeguard@0.3.0\"\n```\n\n```lua\nlocal Typeguard = require(ReplicatedStorage.Packages.Typeguard)\nlocal T = Typeguard\n\nlocal GRAB = T.struct({\n\tuid = T.string({ max_length = 64 }),\n\tat = T.vector3({ max_magnitude = 4096 }),\n\tleaf = T.optional(T.int({ min = 1 })),\n})\ntype Grab = typeof(GRAB)\n\nlocal reason = Typeguard.check(payload, GRAB, \"payload\")\nif reason then\n\twarn(reason) -- payload.at: magnitude 9000 above max 4096\n\treturn\nend\nlocal grab = payload :: Grab\n```\n\n## Builders\n\nEvery builder takes one options table. `default` rides along for a template or a schema and is never checked.\n\n| Builder | Options | Rejects |\n| --- | --- | --- |\n| `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 |\n| `T.int` | `default, min, max, step` | `T.number` plus a fraction |\n| `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 |\n| `T.bool` | `default` | a non-boolean |\n| `T.any` | `default` | nothing |\n| `T.enum` | `members, default` | a value not in `members`, compared with `==` |\n| `T.literal(value)` | | anything but `value` |\n| `T.big` | `default` | a value that is not a `{ m, e }` big number |\n| `T.vector3` | `default, max_magnitude` | a NaN or infinite component, a long vector |\n| `T.cframe` | `default` | a NaN or infinite position |\n| `T.vector2`, `T.udim2`, `T.number_range`, `T.rect` | `default` | the wrong `typeof`, a NaN or infinite component |\n| `T.brick_color`, `T.font` | `default` | the wrong `typeof` |\n| `T.color3`, `T.enum_item` | `default` | the wrong `typeof` |\n| `T.Function` | | a non-function |\n| `T.instance` | `class` | a non-Instance, or one that fails `IsA(class)` |\n| `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 |\n| `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 |\n| `T.array(value)` | `max_count, min_count, default` | a hole, a failing element, too many or too few elements |\n| `T.optional(inner)` | | a non-nil value that fails `inner` |\n| `T.one_of(a, b, ...)` | | a value that fails every shape |\n| `T.refine(inner, predicate, message?)` | | what `inner` rejects, then a false `predicate(value)` |\n| `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 |\n| `T.server_only(inner)` | | what `inner` rejects; sets `server_only` for DataStack replication |\n| `T.of(value)` | | a value whose `typeof` differs, or a table that does not match `value` exactly |\n\nA raw value inside a shape is an implicit `T.of`. A raw table is an exact struct, so a plain template checks as itself.\n\nStruct 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.\n\n| Combinator | Result |\n| --- | --- |\n| `T.pick(spec, keys)` | only the listed fields |\n| `T.omit(spec, keys)` | every field but the listed ones |\n| `T.partial(spec)` | every field wrapped in `T.optional` |\n| `T.merge(a, b)` | the fields of `a` and `b`, `b` wins. Pass a raw table as `b` to add fields |\n\n## Functions\n\n| Function | Returns |\n| --- | --- |\n| `Typeguard.check(value, spec, path?)` | `nil` on pass, else `path.key: reason` |\n| `Typeguard.ok(value, spec)` | boolean |\n| `Typeguard.parse(value, spec, path?)` | the value typed as the spec, or `nil` and the reason. `ok` does not narrow, this does |\n| `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 |\n| `Typeguard.defaults(spec)` | the default tree; an `optional` is nil, a `dict` or `array` is empty |\n| `Typeguard.is(value)` | true when a builder made it |\n| `Typeguard.kind(spec)` | `\"int\"`, `\"struct\"`, …, or `\"raw\"` |\n| `Typeguard.unwrap(spec)` | the spec under `optional`, `refine` and `of` |\n| `Typeguard.emit(spec, name?)` | Luau type source, `<name>` and `<name>Paths` |\n| `Typeguard.BigMath` | `new`, `add`, `sub`, `mul`, `div`, `compare`, `short`, `to_string` for big numbers |\n\nNothing 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.\n\n## Develop\n\n```sh\nzune run tests/lib.spec.luau\nstylua --check src tests\nselene src\nnpm run docs:check\n```\n","readmeTruncated":false}