Add a discrepancies page to the documentation

[dyslexicsteak]

There are a few behavioural discrepancies that need to be clarified due to the differences between how ECMAScript and Lua define their respective behaviours. These discrepancies could cause developers to encounter difficult-to-diagnose bugs in their code. Adding a page that lists differences in behaviour between roblox-ts and ECMAScript and roblox-ts and Lua would alleviate this issue by making any "quirks" known. Methods to get "expected" behaviour, if any, could be mentioned in addition to listing the differences, improving the developer experience.

Edit: Lua is used as shorthand for Lua 5.1 and, by extension, Luau, as Luau keeps near-perfect compatibility with the former.

[LouieK22]

I'd love to get this written up and documented. What are the specific discrepancies that need to be documented?

[dyslexicsteak]

I'd love to get this written up and documented. What are the specific discrepancies that need to be documented?

I'm not familiar with all the discrepancies; you'd have to ask @osyrisrblx.

• Tuples are not Lua tuples, but tables. LuaTuple needs to be instead.
• 1-indexing.
• Something about bitwise ops, I'm not entirely sure about it.
• Declarations being hoisted.

[LouieK22]

Planned documentation:

• 1 vs 0 indexing
• bitwise operators don't sign their results
• declaration hoisting
• % uses modulo instead of remainder
• link to the existing LuaTuple docs

[Dionysusnu]

Maybe something about circular requires? (Node)JS handles them by filling in the export objects dynamically, but Roblox Luau requires that imports are returned all at once.

Also one for the list: Array and string lengths with .size() instead of .length

[Dionysusnu]

This one's niche, but maybe iteration order? JS defines it as property definition order, but Luau has random order with pairs or generalised iteration.

[dyslexicsteak]

This one's niche, but maybe iteration order? JS defines it as property definition order, but Luau has random order with pairs or generalised iteration.

If there's a difference it should be documented, it's seemingly a coin flip whether roblox-ts goes with the Lua behaviour or ECMAScript behaviour so I didn't comment on that.

[Dionysusnu]

Roblox-ts doesn't support for-in loops, so any object iteration goes through pairs, which ES obviously doesn't cover. That's why I'm conflicted on whether it belongs in this doc page, since it is consistent for pairs, just that pairs is not a default TS thing.