Skip to content

Commit aa7dcee

Browse files
jrmelshajrmelsha
committed
Add initial documentation files for Asserts module, Atlas project format, Luau language rules, Roblox reference, Vide UI library, and coding style guidelines.
1 parent 2af1cc2 commit aa7dcee

8 files changed

Lines changed: 2743 additions & 0 deletions

File tree

‎asserts.mdc‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
---
2+
description: Asserts module API reference for runtime type validation
3+
alwaysApply: false
4+
---
5+
# Asserts Module
6+
7+
Runtime type validation for Luau. Located at `ReplicatedStorage.UserGenerated.Lang.Asserts`.
8+
9+
## Basic Usage
10+
11+
```luau
12+
local Asserts = require(ReplicatedStorage.UserGenerated.Lang.Asserts)
13+
14+
-- Direct validation (throws on failure)
15+
local n = Asserts.Integer(someValue)
16+
local s = Asserts.String(input)
17+
18+
-- Composed validators return functions
19+
local validatePositiveInt = Asserts.IntegerPositive
20+
local value = validatePositiveInt(input)
21+
```
22+
23+
## Primitives
24+
25+
| Function | Description |
26+
|----------|-------------|
27+
| `Number(x)` | Any number |
28+
| `String(x)` | UTF-8 validated string |
29+
| `RawString(x)` | String without UTF-8 validation |
30+
| `Boolean(x)` | Boolean value |
31+
| `Buffer(x)` | Buffer type |
32+
| `Function(x)` | Function type |
33+
| `Thread(x)` | Coroutine thread |
34+
| `Any(x)` | Passthrough, no validation |
35+
36+
## Numbers
37+
38+
| Function | Description |
39+
|----------|-------------|
40+
| `Finite(x)` | Excludes NaN and infinity |
41+
| `FinitePositive(x)` | Finite and > 0 |
42+
| `FiniteNonNegative(x)` | Finite and >= 0 |
43+
| `Positive(x)` | > 0 (excludes NaN) |
44+
| `NonNegative(x)` | >= 0 (excludes NaN) |
45+
| `Real(x)` | Excludes NaN only |
46+
| `Integer(x)` | Whole number, finite |
47+
| `IntegerPositive(x)` | Integer >= 1 |
48+
| `IntegerNonNegative(x)` | Integer >= 0 |
49+
| `Index(x)` | Alias for IntegerPositive |
50+
| `Unsigned32(x)` | 32-bit unsigned integer (direct validator) |
51+
| `UInt32` | Returns a validator for 32-bit unsigned integers (factory) |
52+
| `Range(a, b)` | Returns validator for [a, b] |
53+
| `IntegerRange(a, b)` | Returns validator for integer [a, b] |
54+
55+
## Strings
56+
57+
| Function | Description |
58+
|----------|-------------|
59+
| `ASCII(x)` | Printable ASCII only (32-126) |
60+
| `ASCIIRange(a, b)` | ASCII with length in [a, b] |
61+
| `StringRange(a, b)` | UTF-8 with char count in [a, b] |
62+
| `Pattern(pattern)` | Returns validator matching Lua pattern |
63+
| `HexLower(x)` | Lowercase hex string |
64+
| `HexUpper(x)` | Uppercase hex string |
65+
| `Base64(x)` | Valid Base64 encoding |
66+
| `UUID(x)` | UUID with dashes (36 chars) |
67+
| `UUIDStripped(x)` | UUID without dashes (32 chars) |
68+
| `IsoDate(x)` | ISO 8601 date string |
69+
70+
## Roblox Types
71+
72+
| Function | Description |
73+
|----------|-------------|
74+
| `Vector2(x)`, `Vector3(x)` | Basic vector validation |
75+
| `Vector2Finite(x)`, `Vector3Finite(x)` | Vectors with finite components |
76+
| `Vector2Unit(x)`, `Vector3Unit(x)` | Unit vectors (magnitude ≈ 1) |
77+
| `Vector3Positive(x)` | All components > 0 |
78+
| `CFrame(x)`, `CFrameFinite(x)` | CFrame validation |
79+
| `UDim(x)`, `UDim2(x)`, `Rect(x)` | UI types |
80+
| `Region3(x)`, `Region3int16(x)` | Region types |
81+
| `Vector2int16(x)`, `Vector3int16(x)` | Integer vector types |
82+
| `PhysicalProperties(x)` | PhysicalProperties validation |
83+
84+
## Instances
85+
86+
| Function | Description |
87+
|----------|-------------|
88+
| `Instance(x)` | Any Instance |
89+
| `InstanceOf<T>(className)` | Returns validator using IsA |
90+
| `InstanceClass<T>(className)` | Returns validator for exact ClassName |
91+
| `Player(x)`, `Model(x)`, `Humanoid(x)` | Specific instance types |
92+
| `BasePart(x)`, `Part(x)`, `MeshPart(x)` | Part types |
93+
| `Sound(x)`, `Animation(x)`, `ParticleEmitter(x)` | Other common types |
94+
95+
## Enums
96+
97+
```luau
98+
-- Validate EnumItem of specific type
99+
local validateMaterial = Asserts.Enum(Enum.Material)
100+
local mat = validateMaterial(Enum.Material.Plastic)
101+
102+
-- Validate enum by numeric value
103+
local validateMaterialValue = Asserts.EnumValue(Enum.Material)
104+
local matValue = validateMaterialValue(256)
105+
```
106+
107+
## Collections
108+
109+
### Arrays
110+
111+
```luau
112+
-- Validate array elements
113+
local validateNumbers = Asserts.Array(Asserts.Integer)
114+
local nums = validateNumbers({1, 2, 3})
115+
116+
-- Array with unique elements
117+
local validateUniqueStrings = Asserts.UniqueArray(Asserts.String)
118+
119+
-- Transform elements (Coerce variants)
120+
local toIntegers = Asserts.ArrayCoerce(Asserts.ToNumber(Asserts.Integer))
121+
local nums = toIntegers({"1", "2", "3"}) -- {1, 2, 3}
122+
123+
-- Unique array with coercion
124+
local toUniqueInts = Asserts.UniqueArrayCoerce(Asserts.ToNumber(Asserts.Integer))
125+
```
126+
127+
### Maps
128+
129+
```luau
130+
-- Validate key-value pairs
131+
local validateScores = Asserts.Map(Asserts.String, Asserts.Integer)
132+
local scores = validateScores({alice = 100, bob = 200})
133+
134+
-- Optional length limit
135+
local limitedMap = Asserts.Map(Asserts.String, Asserts.Any, 10)
136+
137+
-- Map with key/value coercion
138+
local coercedMap = Asserts.MapCoerce(Asserts.String, Asserts.ToNumber(Asserts.Integer))
139+
```
140+
141+
### Tables (Structured Objects)
142+
143+
```luau
144+
-- Validate specific keys (strict - no extra keys allowed)
145+
local validatePlayer = Asserts.Table({
146+
name = Asserts.String,
147+
score = Asserts.IntegerNonNegative,
148+
active = Asserts.Boolean,
149+
})
150+
151+
-- Permissive variant (ignores extra keys)
152+
local validatePartial = Asserts.TablePermissive({
153+
id = Asserts.String,
154+
})
155+
156+
-- Transform values (Coerce variant)
157+
local parseConfig = Asserts.TableCoerce({
158+
port = Asserts.ToNumber(Asserts.IntegerPositive),
159+
host = Asserts.String,
160+
})
161+
```
162+
163+
## Combinators
164+
165+
```luau
166+
-- Optional (nil allowed)
167+
local maybeString = Asserts.Optional(Asserts.String)
168+
169+
-- Default value when nil
170+
local withDefault = Asserts.Default(Asserts.Integer, 0)
171+
172+
-- Union types (first match wins)
173+
local stringOrNumber = Asserts.AnyOf(Asserts.String, Asserts.Number)
174+
175+
-- Intersection (all must pass)
176+
local positiveFinite = Asserts.AllOf(Asserts.Positive, Asserts.Finite)
177+
178+
-- Exact value match
179+
local validateVersion = Asserts.Equals(1)
180+
181+
-- Set membership
182+
local validateRarity = Asserts.Set({"Common", "Rare", "Epic", "Legendary"})
183+
184+
-- String to number conversion
185+
local parseInteger = Asserts.ToNumber(Asserts.Integer)
186+
```
187+
188+
## Special Validators
189+
190+
```luau
191+
-- DataStore-compatible types
192+
Asserts.Storable(data) -- boolean | number | string | buffer | nested tables
193+
194+
-- Network-replicable types (includes Roblox types)
195+
Asserts.Networkable(data) -- Storable + CFrame, Vector3, Instance, etc.
196+
197+
-- Table without metatable
198+
Asserts.NoMetatable(t)
199+
Asserts.AnyTable(t) -- Allows metatables
200+
```
201+
202+
## Predicate Functions
203+
204+
For conditional logic without throwing:
205+
206+
```luau
207+
if Asserts.IsFinite(x) then ... end
208+
if Asserts.IsInteger(x) then ... end
209+
if Asserts.IsASCII(s) then ... end
210+
if Asserts.IsCFrameFinite(cf) then ... end
211+
if Asserts.IsVector2Finite(v) then ... end
212+
if Asserts.IsVector3Finite(v) then ... end
213+
```
214+
215+
## Exported Types
216+
217+
```luau
218+
Asserts.Map<K, V> -- Type returned by Map validator
219+
Asserts.MapCoerce<K, V, K2, V2> -- Type returned by MapCoerce validator
220+
Asserts.Table<T> -- Type returned by Table validator
221+
Asserts.TableCoerce<T, T2> -- Type returned by TableCoerce validator
222+
Asserts.Storable -- DataStore-compatible value type
223+
Asserts.Networkable -- Network-replicable value type
224+
```
225+
226+
## Error Handling
227+
228+
Validators throw descriptive errors with key paths:
229+
230+
```luau
231+
-- Error: "Integer $[2]" (second array element failed)
232+
-- Error: "String $["name"]" (name field failed)
233+
-- Error: "Range(1,100) $["config"]["port"]" (nested path)
234+
```
235+
236+
Use `pcall` to catch validation errors:
237+
238+
```luau
239+
local success, result = pcall(Asserts.Table({
240+
id = Asserts.UUID,
241+
}), untrustedInput)
242+
243+
if not success then
244+
warn("Validation failed:", result)
245+
end
246+
```

0 commit comments

Comments
 (0)