Skip to content

Latest commit

 

History

History

tstl-plugin

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 

README.md

@gwigz/slua-tstl-plugin

TypeScriptToLua plugin to provide better DX with SLua types.

Usage

Add the plugin to tstl.luaPlugins in your tsconfig.json:

{
  "tstl": {
    "luaTarget": "Luau",
    "luaPlugins": [{ "name": "@gwigz/slua-tstl-plugin" }],
  },
}

To enable output optimizations, pass optimize: true for all flags, or pick individual ones:

{
  "tstl": {
    "luaPlugins": [
      // all optimizations
      { "name": "@gwigz/slua-tstl-plugin", "optimize": true },
    ],
  },
}
{
  "tstl": {
    "luaPlugins": [
      // pick individual optimizations
      {
        "name": "@gwigz/slua-tstl-plugin",
        "optimize": {
          "compoundAssignment": true,
          "shortenTemps": true,
          "inlineLocals": true,
        },
      },
    ],
  },
}

What it does

  • Translates TypeScript patterns to native Luau/LSL equivalents (see below)
  • Automatically adjusts ll.* index arguments and return values from 0-based to 1-based
  • Optimizes self-reassignment array concat/spread to in-place table.extend
  • Optimizes multi-value push to native table.append and table.extend
  • Handles adjusting Vector, Quaternion, and UUID casing
  • Validates luaTarget is set to Luau

Transforms

The plugin replaces TSTL lualib helpers with native Luau stdlib and LSL function calls for better performance and smaller output.

JSON

TypeScript Lua output
JSON.stringify(val) lljson.encode(val)
JSON.parse(str) lljson.decode(str)

For SL-typed JSON (preserving vector/quaternion/uuid), use lljson.slencode/lljson.sldecode directly.

Base64

TypeScript Lua output
btoa(str) llbase64.encode(str)
atob(str) llbase64.decode(str)

String methods

String methods are translated to LSL ll.* functions or Luau string.* stdlib calls:

TypeScript Lua output
str.toUpperCase() ll.ToUpper(str)
str.toLowerCase() ll.ToLower(str)
str.trim() ll.StringTrim(str, STRING_TRIM)
str.trimStart() ll.StringTrim(str, STRING_TRIM_HEAD)
str.trimEnd() ll.StringTrim(str, STRING_TRIM_TAIL)
str.indexOf(x) (string.find(str, x, 1, true) or 0) - 1
str.indexOf(x, from) (string.find(str, x, from + 1, true) or 0) - 1
str.includes(x) string.find(str, x, 1, true) ~= nil
str.startsWith(x) string.find(str, x, 1, true) == 1
str.split(sep) string.split(str, sep)
str.repeat(n) string.rep(str, n)
str.substring(start) string.sub(str, start + 1)
str.substring(s, e) string.sub(str, s + 1, e)
str.replace(a, b) ll.ReplaceSubString(str, a, b, 1)
str.replaceAll(a, b) ll.ReplaceSubString(str, a, b, 0)

Note

str.indexOf(x, fromIndex) adjusts the fromIndex to 1-based (constant-folded for literals). str.startsWith(x, position) with a second argument falls through to TSTL's default handling. Similarly, str.split() with no separator is not transformed.

Array methods

TypeScript Lua output
arr.includes(val) table.find(arr, val) ~= nil
arr.indexOf(val) (table.find(arr, val) or 0) - 1

Note

arr.indexOf(val, fromIndex) with a second argument falls through to TSTL's default handling.

Bitwise operators

TypeScript bitwise operators are automatically translated to bit32 library calls, since SLua does not support native Lua bitwise operators.

TypeScript Lua output
a & b bit32.band(a, b)
a | b bit32.bor(a, b)
a ^ b bit32.bxor(a, b)
a << b bit32.lshift(a, b)
a >> b bit32.arshift(a, b)
a >>> b bit32.rshift(a, b)
~a bit32.bnot(a)

Compound assignments (&=, |=, ^=, <<=, >>=, >>>=) are also supported and desugar to the same bit32 calls.

btest optimization

Comparisons of a bitwise AND against zero are automatically optimized to bit32.btest:

TypeScript Lua output
(a & b) !== 0 bit32.btest(a, b)
(a & b) === 0 not bit32.btest(a, b)

This works with !=, ==, and with the zero on either side (0 !== (a & b)).

ll.* index adjustment

SLua's ll.* functions use 1-based indexing (Lua convention), but TypeScript uses 0-based. The plugin automatically adjusts index arguments and return values based on @indexArg and @indexReturn JSDoc tags in the type definitions:

TypeScript Lua output
ll.GetSubString("hello", 0, 2) ll.GetSubString("hello", 1, 3)
ll.GetSubString("hello", i, j) ll.GetSubString("hello", i + 1, j + 1)
ll.ListFindList(a, b) ____tmp = ll.ListFindList(a, b); ____tmp and (____tmp - 1)
  • @indexArg parameters get + 1 (constant-folded for literals)
  • @indexReturn wraps the result in a nil-safe ____tmp and (____tmp - 1) expression
  • Functions without these tags (e.g. ll.Say) are left unchanged

Ruleset dict keys

Functions like ll.HTTPRequest and ll.SetCameraParams accept a dict instead of a flat list. The types use camelCase keys, and the plugin renames them to the snake_case keys the SLua runtime reads:

TypeScript Lua output
ll.HTTPRequest(url, { maxBodyLength: 4096 }, "") ll.HTTPRequest(url, {max_body_length = 4096}, "")
params.userAgent = "bot" params.user_agent = "bot"
params["verifyCert"] params.verify_cert
const { focusLag } = camera local focusLag = camera.focus_lag

Keys are renamed by the type they are declared on, so the same names on other objects are left alone. Object literals are renamed when they are typed as a dict where they are written, such as an argument, an annotated variable, or a return value. Keys inside customHeader are header names and are never renamed.

The plugin reports an error when a key cannot be renamed at compile time:

  • Dynamic keys, such as params[key] or key in params
  • Destructuring outside a const/let statement, or with a rest element
  • An object built without the dict type, then passed where a dict is expected
const settings = { maxBodyLength: 4096 } // keys stay camelCase
ll.HTTPRequest(url, settings, "") // error, type `settings` as HttpRequestParams

const params: HttpRequestParams = { maxBodyLength: 4096 } // renamed
ll.HTTPRequest(url, params, "")

Object.keys and Object.entries on a dict return the snake_case runtime keys, so the plugin warns about them.

Array concat self-assignment

When an array is reassigned to itself with additional elements appended, the plugin emits table.extend (SLua's in-place append) instead of TSTL's __TS__ArrayConcat which allocates a new table:

TypeScript Lua output
arr = arr.concat(b) table.extend(arr, b)
arr = arr.concat(b, c) table.extend(table.extend(arr, b), c)
arr = [...arr, ...b] table.extend(arr, b)
arr = [...arr, ...b, ...c] table.extend(table.extend(arr, b), c)

This optimization only applies when:

  • The expression is a statement (not const result = arr.concat(b))
  • The LHS is a simple identifier matching the receiver/first spread
  • All concat arguments / spread expressions are array-typed

Array push

A push with more than one value compiles to TSTL's __TS__ArrayPush, which packs its arguments into a new table on every call. When the returned length is unused, the plugin emits SLua's native table.append or table.extend instead:

TypeScript Lua output
arr.push(a, b) table.append(arr, a, b)
arr.push(...b) table.extend(arr, b)
arr.push(...b, ...c) table.extend(table.extend(arr, b), c)

This optimization only applies when:

  • The expression is a statement (not const length = arr.push(a, b))
  • The receiver is array-typed
  • The arguments are all plain values or all array-typed spreads

A single value (arr.push(a)) already compiles to arr[#arr + 1] = a and is left unchanged.

Floor division

Math.floor(a / b) is translated to the native Luau floor division operator //:

TypeScript Lua output
Math.floor(a / b) a // b

This only applies when the argument is directly a / expression. Math.floor(x) with a non-division argument is left as-is.

Warning

JavaScript integer truncation idioms ~~x and x | 0 do not map cleanly to Luau. ~~x emits bit32.bnot(bit32.bnot(x)) and x | 0 emits bit32.bor(x, 0), neither of which preserves correct semantics for negative numbers (the bit32 library operates on unsigned 32-bit integers). Use math.floor(x) for floor truncation instead.

Passthrough arrow closures

Zero-parameter arrow functions that just call another zero-parameter function are collapsed to a direct function reference:

TypeScript Lua output
LLTimers.once(1, () => patchNext()) LLTimers:once(1, patchNext)
LLEvents.on("on_rez", () => refreshUrl()) LLEvents:on("on_rez", refreshUrl)

This applies when:

  • The arrow has zero parameters
  • The body is a single call with zero arguments
  • The callee is a simple identifier (not a method call)
  • The callee's type signature has zero parameters (so extra args from the caller are harmlessly ignored)

Optimizations

Pass optimize: true to enable all optimizations, or pass an object to pick individual flags. All flags default to false when not specified.

filter

Inlines arr.filter(cb) as an ipairs loop instead of pulling in __TS__ArrayFilter.

Automatically disabled for files with more than one .filter() call, where the shared helper is results in a smaller script.

const result = arr.filter((x) => x > 0)
local function ____opt_fn_0(x)
    return x > 0
end
local ____opt_0 = {}
for _, ____opt_v_0 in ipairs(arr) do
    if ____opt_fn_0(____opt_v_0) then
        ____opt_0[#____opt_0 + 1] = ____opt_v_0
    end
end
local result = ____opt_0

compoundAssignment

Rewrites self-reassignment arithmetic to Luau compound assignment operators.

TypeScript Lua output
x = x + n x += n
x = x - 1 x -= 1
x = x .. s x ..= s

Only currently only applies to simple identifiers.

floorMultiply

Reorders Math.floor((a / b) * c) to use the floor division operator, avoiding a math.floor call.

TypeScript Lua output
Math.floor((used / limit) * 100) used * 100 // limit

Plain Math.floor(a / b) is always optimized to a // b regardless of this flag.

indexOf

Emits bare string.find / table.find for indexOf presence checks instead of the full (find or 0) - 1 pattern.

TypeScript Lua output
s.indexOf(x) >= 0 string.find(s, x, 1, true)
s.indexOf(x) !== -1 string.find(s, x, 1, true)
s.indexOf(x) === -1 not string.find(s, x, 1, true)
arr.indexOf(x) >= 0 table.find(arr, x)
arr.indexOf(x) === -1 not table.find(arr, x)

Bare indexOf calls without a comparison will still emit (find or 0) - 1 to retain 0-index style responses.

shortenTemps

Shortens TSTL's destructuring temp names and collapses consecutive field accesses into multi-assignment.

const { a, b } = fn()

Default output:

local ____fn_result_0 = fn()
local a = ____fn_result_0.a
local b = ____fn_result_0.b

Optimized output:

local _r0 = fn()
local a, b = _r0.a, _r0.b

inlineLocals

Merges forward-declared local x with its first x = value assignment when there are no references to x in between.

Default output:

local x
x = 5

Optimized output:

local x = 5

numericConcat

Strips tostring() from number-typed (and string-typed) template literal interpolations, since Luau's .. operator handles numeric concatenation natively.

// count is number
const msg = `items: ${count}`

Default output:

local msg = "items: " .. tostring(count)

Optimized output:

local msg = "items: " .. count

Non-numeric types (booleans, any, etc.) still get wrapped in tostring().

defaultParams

Collapses default-parameter nil-checks into a single or expression.

function respondPoll(extraHtml = "") {
  // ...
}

Default output:

function respondPoll(extraHtml)
    if extraHtml == nil then
        extraHtml = ""
    end
end

Optimized output:

function respondPoll(extraHtml)
    extraHtml = extraHtml or ""
end

Safe for string and number defaults (both truthy in Lua). Not applied to false defaults.

tableClear

Compiles the statement arr.length = 0 to SLua's native table.clear(arr) instead of TSTL's __TS__ArraySetLength helper.

TypeScript Lua output
arr.length = 0 table.clear(arr)

Both keep the table's allocated capacity, so the memory stays reserved for the next items. In Second Life, clearing a list of 200 numbers freed nothing either way, and dropping the helper saved 316 B of script memory. To get the memory back, assign a new array or call table.shrink(arr) after clearing.

table.clear also removes hash keys. An array normally has none, but a string key set on one (arr["tag"] = 1) survives the helper and not table.clear.

It only applies when:

  • The expression is a statement (not const n = (arr.length = 0))
  • The receiver is array-typed
  • The right side is the literal 0, so arr.length = n still uses the helper

Keeping output small

Some TypeScript patterns pull in large TSTL runtime helpers. Here are recommendations for keeping output lean.

Tip

Install @gwigz/slua-oxlint-config to enforce these recommendations at lint time.

Avoid delete on objects

The delete operator pulls in __TS__Delete, which depends on the entire Error class hierarchy (Error, TypeError, RangeError, etc.), __TS__Class, __TS__ClassExtends, __TS__New, and __TS__ObjectGetOwnPropertyDescriptors, roughly 150 lines of runtime code.

Instead, type your records to allow undefined and assign undefined (which compiles to nil):

// Bad
const cache: Record<string, Data> = {}
delete cache[key]

// Good, compiles to `cache[key] = nil`
const cache: Record<string, Data | undefined> = {}
cache[key] = undefined

To clear an entire record, use let and reassign instead of iterating with delete:

// Bad
for (const key of Object.keys(cache)) {
  delete cache[key]
}

// Good
let cache: Record<string, Data | undefined> = {}
// ...
cache = {}

Avoid Array.splice()

splice() pulls in __TS__ArraySplice and __TS__CountVarargs, roughly 75 lines. Rebuild the array instead:

// Bad
for (let i = items.length - 1; i >= 0; i--) {
  if (shouldRemove(items[i])) {
    items.splice(i, 1)
  }
}

// Good, compiles to simple table operations
let items: Item[] = []
const remaining: Item[] = []

for (const item of items) {
  if (!shouldRemove(item)) {
    remaining.push(item)
  }
}

items = remaining

Prefer for...in over Object.entries()

Object.entries() pulls in __TS__ObjectEntries. Use Object.keys() with indexing, or for...in which compiles directly to for key in pairs(obj):

// Pulls in __TS__ObjectEntries
for (const [key, value] of Object.entries(obj)) { ... }

// Compiles to `for key in pairs(obj)`, no helpers
for (const key in obj) {
  const value = obj[key]
}

Avoid Map and Set

TSTL's Map and Set polyfills add ~400 lines of runtime. Use plain Record<string, T> and arrays instead:

// Bad, ~400 lines of runtime
const lookup = new Map<string, UUID>()
const seen = new Set<string>()

// Good, plain Lua tables
const lookup: Record<string, UUID | undefined> = {}
const seen: Record<string, boolean> = {}

Report lualib helpers

Set reportLualib: true to see which TSTL lualib helpers each output file uses:

{
  "tstl": {
    "luaPlugins": [{ "name": "@gwigz/slua-tstl-plugin", "reportLualib": true }],
  },
}

The plugin adds one warning per output file that uses any. A helper with a native alternative says what to write instead. The last line lists helpers that only come in as dependencies of the others.

warning TS90002: dist/queue.slua uses 7 lualib helpers
  __TS__ArrayPush: `push` as a statement compiles to `table.append` or `table.extend`, unless it mixes values and spreads
  __TS__ArraySetLength: the `tableClear` optimize flag compiles `arr.length = 0` to `table.clear(arr)`
  __TS__New
  Set: a `Record<K, true>` table avoids the polyfill
  __TS__Class, __TS__Iterator, __TS__Symbol: pulled in by the helpers above

With luaBundle, the bundle gets one warning, and each helper names the modules that use it.

Build

bun run build

Documentation

Full API reference and usage examples are available at slua.gwigz.link/docs/slua.