@gwigz/slua-tstl-plugin 0.1.0

package/README.md

@@ -0,0 +1,195 @@
+# `@gwigz/slua-tstl-plugin`
+
+[TypeScriptToLua](https://typescripttolua.github.io) plugin to provide better DX with SLua types.
+
+## What it does
+
+- Translates TypeScript patterns to native Luau/LSL equivalents (see below)
+- Handles adjusting `Vector`, `Quaternion`, and `UUID` casing
+- Validates `luaTarget` is set to `Luau`
+- Warns if `luaLibImport` is not `none` or `inline` (for now)
+
+## 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)`       | `ll.SubStringIndex(str, x)`            |
+| `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)`            |
+
+> [!NOTE]
+> `str.indexOf(x, fromIndex)` and `str.startsWith(x, position)` with a second argument fall 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)`).
+
+### 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.
+
+## Keeping output small
+
+Some TypeScript patterns pull in large TSTL runtime helpers. Here are recommendations for keeping output lean:
+
+### 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`):
+
+```typescript
+// 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`:
+
+```typescript
+// 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:
+
+```typescript
+// 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)`:
+
+```typescript
+// 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:
+
+```typescript
+// 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> = {}
+```
+
+## Build
+
+```bash
+bun run build
+```

package/dist/__tests__/helpers.d.ts

@@ -0,0 +1 @@
+export declare function transpile(code: string): string;

package/dist/__tests__/helpers.js

@@ -0,0 +1,16 @@
+import * as tstl from "typescript-to-lua";
+import plugin from "../index";
+export function transpile(code) {
+    const result = tstl.transpileVirtualProject({ "main.ts": code }, {
+        luaTarget: tstl.LuaTarget.Luau,
+        noImplicitSelf: true,
+        noHeader: true,
+        luaLibImport: tstl.LuaLibImportKind.None,
+        luaPlugins: [{ plugin: plugin }],
+    });
+    if (result.diagnostics.length > 0) {
+        const messages = result.diagnostics.map((d) => typeof d.messageText === "string" ? d.messageText : d.messageText.messageText);
+        throw new Error(`Transpilation failed:\n${messages.join("\n")}`);
+    }
+    return result.transpiledFiles.find((f) => f.outPath === "main.lua")?.lua ?? "";
+}

package/dist/__tests__/plugin.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/plugin.test.js

@@ -0,0 +1,314 @@
+import { describe, it, expect } from "bun:test";
+import { readFileSync } from "fs";
+import { resolve } from "path";
+import * as ts from "typescript";
+import * as tstl from "typescript-to-lua";
+import plugin from "../index";
+import { transpile as transpileSimple } from "./helpers";
+const TYPES_PATH = resolve(import.meta.dir, "../../../../packages/types/index.d.ts");
+const LANG_EXT_PATH = resolve(import.meta.dir, "../../../../node_modules/@typescript-to-lua/language-extensions/index.d.ts");
+const sluaTypes = readFileSync(TYPES_PATH, "utf-8");
+const langExt = readFileSync(LANG_EXT_PATH, "utf-8");
+function transpile(code) {
+    const result = tstl.transpileVirtualProject({
+        "main.ts": code,
+        "language-extensions.d.ts": langExt,
+        "slua.d.ts": sluaTypes,
+    }, {
+        luaTarget: tstl.LuaTarget.Luau,
+        noImplicitSelf: true,
+        noHeader: true,
+        luaLibImport: tstl.LuaLibImportKind.Inline,
+        noImplicitGlobalVariables: true,
+        noLib: true,
+        strict: true,
+        luaPlugins: [{ plugin: plugin }],
+    });
+    return result.transpiledFiles.find((f) => f.outPath === "main.lua")?.lua ?? "";
+}
+describe("ts-slua plugin", () => {
+    it("beforeTransform errors on non-Luau target", () => {
+        const diagnostics = plugin.beforeTransform({}, { luaTarget: tstl.LuaTarget.Lua53 }, {});
+        expect(diagnostics).toHaveLength(1);
+        expect(diagnostics[0].messageText).toContain("Luau");
+    });
+    it("beforeTransform passes with correct config", () => {
+        const diagnostics = plugin.beforeTransform({}, {
+            luaTarget: tstl.LuaTarget.Luau,
+            luaLibImport: tstl.LuaLibImportKind.None,
+        }, {});
+        expect(diagnostics).toHaveLength(0);
+    });
+    it("beforeTransform warns on non-none luaLibImport", () => {
+        const diagnostics = plugin.beforeTransform({}, {
+            luaTarget: tstl.LuaTarget.Luau,
+            luaLibImport: tstl.LuaLibImportKind.Require,
+        }, {});
+        expect(diagnostics).toHaveLength(1);
+        expect(diagnostics[0].category).toBe(ts.DiagnosticCategory.Warning);
+    });
+});
+describe("transpilation output", () => {
+    it("does not inject self into LLEvents callbacks", () => {
+        const lua = transpile(`
+      LLEvents.on("touch_start", function(events) {
+        ll.Say(0, "touched")
+      })
+    `);
+        expect(lua).toContain("LLEvents:on");
+        expect(lua).not.toMatch(/function\(self/);
+    });
+    it("does not inject self into LLTimers callbacks", () => {
+        const lua = transpile(`
+      LLTimers.every(10, function(scheduled, interval) {
+        ll.Say(0, "tick")
+      })
+    `);
+        expect(lua).toContain("LLTimers:every");
+        expect(lua).not.toMatch(/function\(self/);
+    });
+});
+describe("floor division", () => {
+    it("translates Math.floor(a / b) to floor division operator", () => {
+        const lua = transpileSimple("declare const a: number, b: number;\nconst x = Math.floor(a / b)");
+        expect(lua).toContain("a // b");
+        expect(lua).not.toContain("math.floor");
+    });
+    it("handles literal operands", () => {
+        const lua = transpileSimple("const x = Math.floor(10 / 3)");
+        expect(lua).toContain("10 // 3");
+    });
+    it("does not transform Math.floor with non-division argument", () => {
+        const lua = transpileSimple("declare const a: number;\nconst x = Math.floor(a)");
+        expect(lua).not.toContain("//");
+        expect(lua).toContain("math.floor(a)");
+    });
+    it("does not transform Math.floor with complex non-division expression", () => {
+        const lua = transpileSimple("declare const a: number, b: number;\nconst x = Math.floor(a + b)");
+        expect(lua).not.toContain("//");
+        expect(lua).toContain("math.floor");
+    });
+});
+describe("bitwise operators", () => {
+    it("translates & to bit32.band", () => {
+        const lua = transpileSimple("const x = (1 as number) & (2 as number)");
+        expect(lua).toContain("bit32.band(1, 2)");
+    });
+    it("translates | to bit32.bor", () => {
+        const lua = transpileSimple("const x = (1 as number) | (2 as number)");
+        expect(lua).toContain("bit32.bor(1, 2)");
+    });
+    it("translates ^ to bit32.bxor", () => {
+        const lua = transpileSimple("const x = (1 as number) ^ (2 as number)");
+        expect(lua).toContain("bit32.bxor(1, 2)");
+    });
+    it("translates << to bit32.lshift", () => {
+        const lua = transpileSimple("const x = (1 as number) << (2 as number)");
+        expect(lua).toContain("bit32.lshift(1, 2)");
+    });
+    it("translates >> to bit32.arshift", () => {
+        const lua = transpileSimple("const x = (1 as number) >> (2 as number)");
+        expect(lua).toContain("bit32.arshift(1, 2)");
+    });
+    it("translates >>> to bit32.rshift", () => {
+        const lua = transpileSimple("const x = (1 as number) >>> (2 as number)");
+        expect(lua).toContain("bit32.rshift(1, 2)");
+    });
+    it("translates ~ to bit32.bnot", () => {
+        const lua = transpileSimple("const x = ~(1 as number)");
+        expect(lua).toContain("bit32.bnot(1)");
+    });
+    describe("btest optimization", () => {
+        it("translates (a & b) !== 0 to bit32.btest", () => {
+            const lua = transpileSimple("declare const a: number, b: number;\nconst x = (a & b) !== 0");
+            expect(lua).toContain("bit32.btest(a, b)");
+            expect(lua).not.toContain("bit32.band");
+        });
+        it("translates (a & b) != 0 to bit32.btest", () => {
+            const lua = transpileSimple("declare const a: number, b: number;\nconst x = (a & b) != 0");
+            expect(lua).toContain("bit32.btest(a, b)");
+        });
+        it("translates (a & b) === 0 to not bit32.btest", () => {
+            const lua = transpileSimple("declare const a: number, b: number;\nconst x = (a & b) === 0");
+            expect(lua).toContain("not bit32.btest(a, b)");
+        });
+        it("translates (a & b) == 0 to not bit32.btest", () => {
+            const lua = transpileSimple("declare const a: number, b: number;\nconst x = (a & b) == 0");
+            expect(lua).toContain("not bit32.btest(a, b)");
+        });
+        it("translates 0 !== (a & b) to bit32.btest (flipped)", () => {
+            const lua = transpileSimple("declare const a: number, b: number;\nconst x = 0 !== (a & b)");
+            expect(lua).toContain("bit32.btest(a, b)");
+        });
+    });
+    it("handles compound expressions: (a & b) | c", () => {
+        const lua = transpileSimple("declare const a: number, b: number, c: number;\nconst x = (a & b) | c");
+        expect(lua).toContain("bit32.bor(");
+        expect(lua).toContain("bit32.band(a, b)");
+        expect(lua).toMatch(/bit32\.bor\(\s*bit32\.band\(a, b\)/);
+    });
+    describe("compound bitwise assignments", () => {
+        it("translates &= to bit32.band", () => {
+            const lua = transpileSimple("declare let a: number; a &= 3");
+            expect(lua).toContain("bit32.band(a, 3)");
+        });
+        it("translates |= to bit32.bor", () => {
+            const lua = transpileSimple("declare let a: number; a |= 3");
+            expect(lua).toContain("bit32.bor(a, 3)");
+        });
+        it("translates ^= to bit32.bxor", () => {
+            const lua = transpileSimple("declare let a: number; a ^= 3");
+            expect(lua).toContain("bit32.bxor(a, 3)");
+        });
+        it("translates <<= to bit32.lshift", () => {
+            const lua = transpileSimple("declare let a: number; a <<= 3");
+            expect(lua).toContain("bit32.lshift(a, 3)");
+        });
+        it("translates >>= to bit32.arshift", () => {
+            const lua = transpileSimple("declare let a: number; a >>= 3");
+            expect(lua).toContain("bit32.arshift(a, 3)");
+        });
+        it("translates >>>= to bit32.rshift", () => {
+            const lua = transpileSimple("declare let a: number; a >>>= 3");
+            expect(lua).toContain("bit32.rshift(a, 3)");
+        });
+        it("handles property access LHS", () => {
+            const lua = transpileSimple("declare let obj: {prop: number}; obj.prop &= 3");
+            expect(lua).toContain("bit32.band(");
+            expect(lua).not.toMatch(/\s&\s/);
+        });
+    });
+    it("does not affect non-bitwise binary operators", () => {
+        const lua = transpileSimple("const x = 1 + 2");
+        expect(lua).toContain("1 + 2");
+        expect(lua).not.toContain("bit32");
+    });
+    it("does not affect non-bitwise unary operators", () => {
+        const lua = transpileSimple("const x = -(1 as number)");
+        expect(lua).toContain("-1");
+        expect(lua).not.toContain("bit32");
+    });
+});
+describe("JSON transforms", () => {
+    it("translates JSON.stringify to lljson.encode", () => {
+        const lua = transpileSimple("declare const obj: any;\nconst s = JSON.stringify(obj)");
+        expect(lua).toContain("lljson.encode(obj)");
+        expect(lua).not.toContain("JSON");
+    });
+    it("translates JSON.parse to lljson.decode", () => {
+        const lua = transpileSimple('declare const s: string;\nconst obj = JSON.parse(s)');
+        expect(lua).toContain("lljson.decode(s)");
+        expect(lua).not.toContain("JSON");
+    });
+});
+describe("base64 transforms", () => {
+    it("translates btoa to llbase64.encode", () => {
+        const lua = transpileSimple("declare const s: string;\nconst b = btoa(s)");
+        expect(lua).toContain("llbase64.encode(s)");
+        expect(lua).not.toContain("btoa");
+    });
+    it("translates atob to llbase64.decode", () => {
+        const lua = transpileSimple("declare const b: string;\nconst s = atob(b)");
+        expect(lua).toContain("llbase64.decode(b)");
+        expect(lua).not.toContain("atob");
+    });
+});
+describe("string ll.* transforms", () => {
+    it("translates toUpperCase to ll.ToUpper", () => {
+        const lua = transpileSimple('const s = "hello".toUpperCase()');
+        expect(lua).toContain("ll.ToUpper");
+    });
+    it("translates toLowerCase to ll.ToLower", () => {
+        const lua = transpileSimple('const s = "HELLO".toLowerCase()');
+        expect(lua).toContain("ll.ToLower");
+    });
+    it("translates trim to ll.StringTrim with STRING_TRIM", () => {
+        const lua = transpileSimple('declare const s: string;\nconst x = s.trim()');
+        expect(lua).toContain("ll.StringTrim");
+        expect(lua).toContain("STRING_TRIM");
+    });
+    it("translates trimStart to ll.StringTrim with STRING_TRIM_HEAD", () => {
+        const lua = transpileSimple('interface String { trimStart(): string; }\ndeclare const s: string;\nconst x = s.trimStart()');
+        expect(lua).toContain("ll.StringTrim");
+        expect(lua).toContain("STRING_TRIM_HEAD");
+    });
+    it("translates trimEnd to ll.StringTrim with STRING_TRIM_TAIL", () => {
+        const lua = transpileSimple('interface String { trimEnd(): string; }\ndeclare const s: string;\nconst x = s.trimEnd()');
+        expect(lua).toContain("ll.StringTrim");
+        expect(lua).toContain("STRING_TRIM_TAIL");
+    });
+    it("translates indexOf (1-arg) to ll.SubStringIndex", () => {
+        const lua = transpileSimple('declare const s: string;\nconst i = s.indexOf("x")');
+        expect(lua).toContain("ll.SubStringIndex");
+    });
+    it("translates indexOf with literal fromIndex to string.find with constant folding", () => {
+        const lua = transpileSimple('declare const s: string;\nconst i = s.indexOf("x", 5)');
+        expect(lua).not.toContain("ll.SubStringIndex");
+        expect(lua).toContain('string.find(s, "x", 6, true)');
+        expect(lua).toContain("(string.find(");
+        expect(lua).toContain("or 0) - 1");
+    });
+    it("translates indexOf with expression fromIndex to string.find with + 1", () => {
+        const lua = transpileSimple('declare const s: string;\ndeclare const n: number;\nconst i = s.indexOf("x", n)');
+        expect(lua).toContain('string.find(s, "x", n + 1, true)');
+        expect(lua).toContain("or 0) - 1");
+    });
+});
+describe("string Luau stdlib transforms", () => {
+    it("translates includes to string.find", () => {
+        const lua = transpileSimple('interface String { includes(searchString: string): boolean }\ndeclare const s: string;\nconst b = s.includes("x")');
+        expect(lua).toContain("string.find(s,");
+        expect(lua).toContain("true");
+        expect(lua).toContain("~= nil");
+    });
+    it("translates split(sep) to string.split", () => {
+        const lua = transpileSimple('interface String { split(separator: string): string[] }\ndeclare const s: string;\nconst a = s.split(",")');
+        expect(lua).toContain("string.split(s,");
+    });
+    it("does not transform split() with no separator", () => {
+        const lua = transpileSimple("interface String { split(separator?: string): string[] }\ndeclare const s: string;\nconst a = s.split()");
+        expect(lua).not.toContain("string.split");
+    });
+    it("translates repeat to string.rep", () => {
+        const lua = transpileSimple("interface String { repeat(count: number): string }\ndeclare const s: string;\nconst r = s.repeat(3)");
+        expect(lua).toContain("string.rep(s, 3)");
+    });
+    it("translates startsWith to string.find == 1", () => {
+        const lua = transpileSimple('interface String { startsWith(searchString: string): boolean }\ndeclare const s: string;\nconst b = s.startsWith("pre")');
+        expect(lua).toContain("string.find(s,");
+        expect(lua).toContain("true");
+        expect(lua).toContain("== 1");
+    });
+    it("does not transform startsWith with position argument", () => {
+        const lua = transpileSimple('interface String { startsWith(searchString: string, position?: number): boolean }\ndeclare const s: string;\nconst b = s.startsWith("pre", 3)');
+        expect(lua).not.toContain("string.find");
+    });
+    it("translates substring(start) to string.sub with constant folding", () => {
+        const lua = transpileSimple("declare const s: string;\nconst x = s.substring(5)");
+        expect(lua).toContain("string.sub(s, 6)");
+    });
+    it("translates substring(start, end) to string.sub with constant folding", () => {
+        const lua = transpileSimple("declare const s: string;\nconst x = s.substring(1, 5)");
+        expect(lua).toContain("string.sub(s, 2, 5)");
+    });
+    it("translates substring with expression arg to start + 1", () => {
+        const lua = transpileSimple("declare const s: string;\ndeclare const i: number;\nconst x = s.substring(i)");
+        expect(lua).toContain("string.sub(s, i + 1)");
+    });
+});
+describe("array transforms", () => {
+    it("translates includes to table.find ~= nil", () => {
+        const lua = transpileSimple("interface Array<T> { includes(searchElement: T): boolean; }\ndeclare const arr: number[];\nconst b = arr.includes(3)");
+        expect(lua).toContain("table.find(arr, 3)");
+        expect(lua).toContain("~= nil");
+    });
+    it("translates indexOf (1-arg) to (table.find or 0) - 1", () => {
+        const lua = transpileSimple("interface Array<T> { indexOf(searchElement: T, fromIndex?: number): number; }\ndeclare const arr: number[];\nconst i = arr.indexOf(3)");
+        expect(lua).toContain("table.find(arr, 3)");
+        expect(lua).toContain("- 1");
+    });
+    it("does not transform indexOf with fromIndex argument", () => {
+        const lua = transpileSimple("interface Array<T> { indexOf(searchElement: T, fromIndex?: number): number; }\ndeclare const arr: number[];\nconst i = arr.indexOf(3, 1)");
+        expect(lua).not.toContain("table.find");
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import * as tstl from "typescript-to-lua";
+declare const plugin: tstl.Plugin;
+export default plugin;

package/dist/index.js

@@ -0,0 +1,468 @@
+import * as ts from "typescript";
+import * as tstl from "typescript-to-lua";
+/**
+ * PascalCase class names that map to lowercase Lua globals.
+ * `new Vector(...)` is handled by @customConstructor, but static access
+ * like `Vector.zero` emits `Vector.zero` in Lua -- which doesn't exist.
+ * The PropertyAccessExpression visitor rewrites the Lua identifier to lowercase.
+ */
+const PASCAL_TO_LOWER = {
+    Vector: "vector",
+    Quaternion: "quaternion",
+    UUID: "uuid",
+};
+/**
+ * TSTL treats "bit32" as a Lua keyword and renames it to "____bit32" in output.
+ * This is incorrect for Luau where bit32 is a valid global library.
+ * The visitor rewrites the mangled name back; the diagnostic is suppressed
+ * separately in consumers (e.g. the playground transpiler worker).
+ */
+const TSTL_KEYWORD_FIXUPS = {
+    ____bit32: "bit32",
+};
+/**
+ * Creates a `bit32.<fn>(...args)` Lua call expression.
+ * The optional `node` attaches TypeScript source-map information; when
+ * patching already-lowered Lua AST nodes (e.g. from compound-assignment
+ * desugaring) there is no originating TS node, so it may be omitted.
+ */
+function createBit32Call(fn, args, node) {
+    return tstl.createCallExpression(tstl.createTableIndexExpression(tstl.createIdentifier("bit32"), tstl.createStringLiteral(fn)), args, node);
+}
+const BINARY_BITWISE_OPS = {
+    [ts.SyntaxKind.AmpersandToken]: "band",
+    [ts.SyntaxKind.BarToken]: "bor",
+    [ts.SyntaxKind.CaretToken]: "bxor",
+    [ts.SyntaxKind.LessThanLessThanToken]: "lshift",
+    [ts.SyntaxKind.GreaterThanGreaterThanToken]: "arshift",
+    [ts.SyntaxKind.GreaterThanGreaterThanGreaterThanToken]: "rshift",
+};
+/**
+ * Compound bitwise assignment tokens (`&=`, `|=`, etc.) map to the same
+ * `bit32.*` functions as their non-compound counterparts.  We handle
+ * these at the TypeScript AST level rather than patching the Lua AST,
+ * because TSTL's desugaring loses the distinction between `>>=`
+ * (arshift) and `>>>=` (rshift) -- both lower to the same Lua operator.
+ */
+const COMPOUND_BITWISE_OPS = {
+    [ts.SyntaxKind.AmpersandEqualsToken]: "band",
+    [ts.SyntaxKind.BarEqualsToken]: "bor",
+    [ts.SyntaxKind.CaretEqualsToken]: "bxor",
+    [ts.SyntaxKind.LessThanLessThanEqualsToken]: "lshift",
+    [ts.SyntaxKind.GreaterThanGreaterThanEqualsToken]: "arshift",
+    [ts.SyntaxKind.GreaterThanGreaterThanGreaterThanEqualsToken]: "rshift",
+};
+/**
+ * Returns true when `node` is `Math.floor(<single-arg>)`.
+ */
+function isMathFloor(node) {
+    return (node.arguments.length === 1 &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        ts.isIdentifier(node.expression.expression) &&
+        node.expression.expression.text === "Math" &&
+        node.expression.name.text === "floor");
+}
+const EQUALITY_OPS = new Set([
+    ts.SyntaxKind.EqualsEqualsToken,
+    ts.SyntaxKind.EqualsEqualsEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsEqualsToken,
+]);
+function isZeroLiteral(node) {
+    return ts.isNumericLiteral(node) && node.text === "0";
+}
+function isNegatedEquality(op) {
+    return (op === ts.SyntaxKind.ExclamationEqualsToken || op === ts.SyntaxKind.ExclamationEqualsEqualsToken);
+}
+/**
+ * Detect `(a & b) !== 0`, `0 === (a & b)`, etc. and return the `&` expression
+ * plus whether to negate the btest result.
+ */
+function extractBtestPattern(node) {
+    const op = node.operatorToken.kind;
+    if (!EQUALITY_OPS.has(op))
+        return null;
+    let bandExpr;
+    if (isZeroLiteral(node.right)) {
+        bandExpr = ts.isParenthesizedExpression(node.left) ? node.left.expression : node.left;
+    }
+    else if (isZeroLiteral(node.left)) {
+        bandExpr = ts.isParenthesizedExpression(node.right) ? node.right.expression : node.right;
+    }
+    else {
+        return null;
+    }
+    if (!ts.isBinaryExpression(bandExpr) ||
+        bandExpr.operatorToken.kind !== ts.SyntaxKind.AmpersandToken) {
+        return null;
+    }
+    // `== 0` / `=== 0` mean "no bits in common", so we negate btest (negate = true).
+    // `!= 0` / `!== 0` mean "some bits in common", which is what btest returns
+    // directly, so no negation is needed.  The `!isNegatedEquality` double-negative
+    // captures this: negated equality (!=) -> false -> don't negate btest.
+    return { band: bandExpr, negate: !isNegatedEquality(op) };
+}
+/**
+ * Type-checking helpers for catalog transforms.
+ */
+function isStringType(expr, checker) {
+    const type = checker.getTypeAtLocation(expr);
+    return !!(type.flags & ts.TypeFlags.StringLike);
+}
+function isArrayType(expr, checker) {
+    const type = checker.getTypeAtLocation(expr);
+    return checker.isArrayLikeType(type);
+}
+/**
+ * Checks whether `node` is `obj.method(args)` where `obj` matches the
+ * given type predicate and the method name matches.
+ */
+function isMethodCall(node, checker, typeGuard, method, argCount) {
+    if (!ts.isPropertyAccessExpression(node.expression))
+        return false;
+    if (node.expression.name.text !== method)
+        return false;
+    if (argCount !== undefined && node.arguments.length !== argCount)
+        return false;
+    return typeGuard(node.expression.expression, checker);
+}
+/**
+ * Checks whether `node` is `Namespace.method(args)` using syntactic
+ * identifier matching (no TypeChecker needed).
+ */
+function isNamespaceCall(node, namespace, method) {
+    if (!ts.isPropertyAccessExpression(node.expression))
+        return false;
+    if (node.expression.name.text !== method)
+        return false;
+    return (ts.isIdentifier(node.expression.expression) && node.expression.expression.text === namespace);
+}
+/**
+ * Checks whether `node` is a call to a global function by name.
+ */
+function isGlobalCall(node, name) {
+    return ts.isIdentifier(node.expression) && node.expression.text === name;
+}
+/**
+ * Creates a `ns.fn(...args)` Lua call expression.
+ */
+function createNamespacedCall(ns, fn, args, node) {
+    return tstl.createCallExpression(tstl.createTableIndexExpression(tstl.createIdentifier(ns), tstl.createStringLiteral(fn)), args, node);
+}
+const CALL_TRANSFORMS = [
+    // JSON.stringify(val) -> lljson.encode(val)
+    {
+        match: (node) => isNamespaceCall(node, "JSON", "stringify"),
+        emit: (node, context) => {
+            const args = node.arguments.map((a) => context.transformExpression(a));
+            return createNamespacedCall("lljson", "encode", args, node);
+        },
+    },
+    // JSON.parse(str) -> lljson.decode(str)
+    {
+        match: (node) => isNamespaceCall(node, "JSON", "parse"),
+        emit: (node, context) => {
+            const args = node.arguments.map((a) => context.transformExpression(a));
+            return createNamespacedCall("lljson", "decode", args, node);
+        },
+    },
+    // btoa(str) -> llbase64.encode(str)
+    {
+        match: (node) => isGlobalCall(node, "btoa") && node.arguments.length === 1,
+        emit: (node, context) => {
+            const args = node.arguments.map((a) => context.transformExpression(a));
+            return createNamespacedCall("llbase64", "encode", args, node);
+        },
+    },
+    // atob(str) -> llbase64.decode(str)
+    {
+        match: (node) => isGlobalCall(node, "atob") && node.arguments.length === 1,
+        emit: (node, context) => {
+            const args = node.arguments.map((a) => context.transformExpression(a));
+            return createNamespacedCall("llbase64", "decode", args, node);
+        },
+    },
+    // str.toUpperCase() -> ll.ToUpper(str)
+    {
+        match: (node, checker) => isMethodCall(node, checker, isStringType, "toUpperCase", 0),
+        emit: (node, context) => {
+            const str = context.transformExpression(node.expression.expression);
+            return createNamespacedCall("ll", "ToUpper", [str], node);
+        },
+    },
+    // str.toLowerCase() -> ll.ToLower(str)
+    {
+        match: (node, checker) => isMethodCall(node, checker, isStringType, "toLowerCase", 0),
+        emit: (node, context) => {
+            const str = context.transformExpression(node.expression.expression);
+            return createNamespacedCall("ll", "ToLower", [str], node);
+        },
+    },
+    // str.trim() -> ll.StringTrim(str, STRING_TRIM)
+    {
+        match: (node, checker) => isMethodCall(node, checker, isStringType, "trim", 0),
+        emit: (node, context) => {
+            const str = context.transformExpression(node.expression.expression);
+            return createNamespacedCall("ll", "StringTrim", [str, tstl.createIdentifier("STRING_TRIM")], node);
+        },
+    },
+    // str.trimStart() -> ll.StringTrim(str, STRING_TRIM_HEAD)
+    {
+        match: (node, checker) => isMethodCall(node, checker, isStringType, "trimStart", 0),
+        emit: (node, context) => {
+            const str = context.transformExpression(node.expression.expression);
+            return createNamespacedCall("ll", "StringTrim", [str, tstl.createIdentifier("STRING_TRIM_HEAD")], node);
+        },
+    },
+    // str.trimEnd() -> ll.StringTrim(str, STRING_TRIM_TAIL)
+    {
+        match: (node, checker) => isMethodCall(node, checker, isStringType, "trimEnd", 0),
+        emit: (node, context) => {
+            const str = context.transformExpression(node.expression.expression);
+            return createNamespacedCall("ll", "StringTrim", [str, tstl.createIdentifier("STRING_TRIM_TAIL")], node);
+        },
+    },
+    // str.indexOf(x) -> ll.SubStringIndex(str, x)  (1-arg only)
+    {
+        match: (node, checker) => isMethodCall(node, checker, isStringType, "indexOf", 1),
+        emit: (node, context) => {
+            const str = context.transformExpression(node.expression.expression);
+            const search = context.transformExpression(node.arguments[0]);
+            return createNamespacedCall("ll", "SubStringIndex", [str, search], node);
+        },
+    },
+    // str.indexOf(x, fromIndex) -> (string.find(str, x, fromIndex + 1, true) or 0) - 1
+    {
+        match: (node, checker) => isMethodCall(node, checker, isStringType, "indexOf", 2),
+        emit: (node, context) => {
+            const str = context.transformExpression(node.expression.expression);
+            const search = context.transformExpression(node.arguments[0]);
+            const fromArg = node.arguments[1];
+            const init = ts.isNumericLiteral(fromArg)
+                ? tstl.createNumericLiteral(Number(fromArg.text) + 1)
+                : tstl.createBinaryExpression(context.transformExpression(fromArg), tstl.createNumericLiteral(1), tstl.SyntaxKind.AdditionOperator, node);
+            const findCall = createNamespacedCall("string", "find", [str, search, init, tstl.createBooleanLiteral(true)], node);
+            const findOrZero = tstl.createBinaryExpression(findCall, tstl.createNumericLiteral(0), tstl.SyntaxKind.OrOperator, node);
+            return tstl.createBinaryExpression(tstl.createParenthesizedExpression(findOrZero), tstl.createNumericLiteral(1), tstl.SyntaxKind.SubtractionOperator, node);
+        },
+    },
+    // str.includes(x) -> string.find(str, x, 1, true) ~= nil
+    {
+        match: (node, checker) => isMethodCall(node, checker, isStringType, "includes", 1),
+        emit: (node, context) => {
+            const str = context.transformExpression(node.expression.expression);
+            const search = context.transformExpression(node.arguments[0]);
+            const findCall = createNamespacedCall("string", "find", [str, search, tstl.createNumericLiteral(1), tstl.createBooleanLiteral(true)], node);
+            return tstl.createBinaryExpression(findCall, tstl.createNilLiteral(), tstl.SyntaxKind.InequalityOperator, node);
+        },
+    },
+    // str.split(sep) -> string.split(str, sep)  (1-arg only)
+    {
+        match: (node, checker) => isMethodCall(node, checker, isStringType, "split", 1),
+        emit: (node, context) => {
+            const str = context.transformExpression(node.expression.expression);
+            const sep = context.transformExpression(node.arguments[0]);
+            return createNamespacedCall("string", "split", [str, sep], node);
+        },
+    },
+    // str.repeat(n) -> string.rep(str, n)
+    {
+        match: (node, checker) => isMethodCall(node, checker, isStringType, "repeat", 1),
+        emit: (node, context) => {
+            const str = context.transformExpression(node.expression.expression);
+            const n = context.transformExpression(node.arguments[0]);
+            return createNamespacedCall("string", "rep", [str, n], node);
+        },
+    },
+    // str.startsWith(search) -> string.find(str, search, 1, true) == 1  (1-arg only)
+    {
+        match: (node, checker) => isMethodCall(node, checker, isStringType, "startsWith", 1),
+        emit: (node, context) => {
+            const str = context.transformExpression(node.expression.expression);
+            const search = context.transformExpression(node.arguments[0]);
+            const findCall = createNamespacedCall("string", "find", [str, search, tstl.createNumericLiteral(1), tstl.createBooleanLiteral(true)], node);
+            return tstl.createBinaryExpression(findCall, tstl.createNumericLiteral(1), tstl.SyntaxKind.EqualityOperator, node);
+        },
+    },
+    // str.substring(start) -> string.sub(str, start + 1)
+    // str.substring(start, end) -> string.sub(str, start + 1, end)
+    {
+        match: (node, checker) => {
+            if (!isMethodCall(node, checker, isStringType, "substring")) {
+                return false;
+            }
+            return node.arguments.length === 1 || node.arguments.length === 2;
+        },
+        emit: (node, context) => {
+            const str = context.transformExpression(node.expression.expression);
+            const startArg = node.arguments[0];
+            const start = ts.isNumericLiteral(startArg)
+                ? tstl.createNumericLiteral(Number(startArg.text) + 1)
+                : tstl.createBinaryExpression(context.transformExpression(startArg), tstl.createNumericLiteral(1), tstl.SyntaxKind.AdditionOperator, node);
+            const args = [str, start];
+            if (node.arguments.length === 2) {
+                args.push(context.transformExpression(node.arguments[1]));
+            }
+            return createNamespacedCall("string", "sub", args, node);
+        },
+    },
+    // arr.includes(val) -> table.find(arr, val) ~= nil
+    {
+        match: (node, checker) => isMethodCall(node, checker, isArrayType, "includes", 1),
+        emit: (node, context) => {
+            const arr = context.transformExpression(node.expression.expression);
+            const val = context.transformExpression(node.arguments[0]);
+            const findCall = createNamespacedCall("table", "find", [arr, val], node);
+            return tstl.createBinaryExpression(findCall, tstl.createNilLiteral(), tstl.SyntaxKind.InequalityOperator, node);
+        },
+    },
+    // arr.indexOf(val) -> (table.find(arr, val) or 0) - 1  (1-arg only)
+    {
+        match: (node, checker) => isMethodCall(node, checker, isArrayType, "indexOf", 1),
+        emit: (node, context) => {
+            const arr = context.transformExpression(node.expression.expression);
+            const val = context.transformExpression(node.arguments[0]);
+            const findCall = createNamespacedCall("table", "find", [arr, val], node);
+            const findOrZero = tstl.createBinaryExpression(findCall, tstl.createNumericLiteral(0), tstl.SyntaxKind.OrOperator, node);
+            return tstl.createBinaryExpression(tstl.createParenthesizedExpression(findOrZero), tstl.createNumericLiteral(1), tstl.SyntaxKind.SubtractionOperator, node);
+        },
+    },
+];
+const plugin = {
+    visitors: {
+        [ts.SyntaxKind.PropertyAccessExpression]: (node, context) => {
+            const result = context.superTransformExpression(node);
+            // Rewrite identifiers in the Lua AST (PascalCase -> lowercase, TSTL keyword fixups).
+            if (tstl.isTableIndexExpression(result) && tstl.isIdentifier(result.table)) {
+                const replacement = PASCAL_TO_LOWER[result.table.text] ?? TSTL_KEYWORD_FIXUPS[result.table.text];
+                if (replacement) {
+                    result.table.text = replacement;
+                }
+            }
+            return result;
+        },
+        [ts.SyntaxKind.BinaryExpression]: (node, context) => {
+            // Check for btest pattern: (a & b) !== 0, 0 === (a & b), etc.
+            const btest = extractBtestPattern(node);
+            if (btest) {
+                const left = context.transformExpression(btest.band.left);
+                const right = context.transformExpression(btest.band.right);
+                const call = createBit32Call("btest", [left, right], node);
+                return btest.negate
+                    ? tstl.createUnaryExpression(call, tstl.SyntaxKind.NotOperator, node)
+                    : call;
+            }
+            const op = node.operatorToken.kind;
+            const fn = BINARY_BITWISE_OPS[op];
+            if (fn) {
+                const left = context.transformExpression(node.left);
+                const right = context.transformExpression(node.right);
+                return createBit32Call(fn, [left, right], node);
+            }
+            // Compound bitwise assignments (`&=`, `|=`, `^=`, `<<=`, `>>=`, `>>>=`).
+            // Manually desugar to `lhs = bit32.<fn>(lhs, rhs)` so we preserve the
+            // correct function (especially arshift vs rshift).  This path is only
+            // reached when a compound assignment is used as an *expression*; the
+            // statement case is handled by the ExpressionStatement visitor below.
+            const compoundFn = COMPOUND_BITWISE_OPS[op];
+            if (compoundFn) {
+                const left = context.transformExpression(node.left);
+                const right = context.transformExpression(node.right);
+                const call = createBit32Call(compoundFn, [left, right], node);
+                context.addPrecedingStatements(tstl.createAssignmentStatement(left, call, node));
+                return left;
+            }
+            return context.superTransformExpression(node);
+        },
+        // Compound bitwise assignments used as statements (`a &= 3;`) are handled
+        // by TSTL's ExpressionStatement -> transformBinaryExpressionStatement path,
+        // which never calls the BinaryExpression visitor.  We intercept here and
+        // manually desugar to `lhs = bit32.<fn>(lhs, rhs)` to preserve the correct
+        // function name (especially arshift vs rshift which TSTL conflates).
+        [ts.SyntaxKind.ExpressionStatement]: (node, context) => {
+            if (ts.isBinaryExpression(node.expression)) {
+                const compoundFn = COMPOUND_BITWISE_OPS[node.expression.operatorToken.kind];
+                if (compoundFn) {
+                    const left = context.transformExpression(node.expression.left);
+                    const right = context.transformExpression(node.expression.right);
+                    const call = createBit32Call(compoundFn, [left, right], node);
+                    return [tstl.createAssignmentStatement(left, call, node)];
+                }
+            }
+            return context.superTransformStatements(node);
+        },
+        [ts.SyntaxKind.CallExpression]: (node, context) => {
+            // Catalog-driven transforms
+            for (const transform of CALL_TRANSFORMS) {
+                if (transform.match(node, context.checker)) {
+                    return transform.emit(node, context);
+                }
+            }
+            // `Math.floor(a / b)` -> `a // b` (native Luau floor division operator)
+            if (isMathFloor(node)) {
+                const arg = node.arguments[0];
+                if (ts.isBinaryExpression(arg) && arg.operatorToken.kind === ts.SyntaxKind.SlashToken) {
+                    const left = context.transformExpression(arg.left);
+                    const right = context.transformExpression(arg.right);
+                    return tstl.createBinaryExpression(left, right, tstl.SyntaxKind.FloorDivisionOperator, node);
+                }
+            }
+            return context.superTransformExpression(node);
+        },
+        [ts.SyntaxKind.PrefixUnaryExpression]: (node, context) => {
+            if (node.operator === ts.SyntaxKind.TildeToken) {
+                const operand = context.transformExpression(node.operand);
+                return createBit32Call("bnot", [operand], node);
+            }
+            return context.superTransformExpression(node);
+        },
+    },
+    beforeTransform(_program, options) {
+        const diagnostics = [];
+        if (options.luaTarget !== tstl.LuaTarget.Luau) {
+            diagnostics.push({
+                file: undefined,
+                start: undefined,
+                length: undefined,
+                messageText: '@gwigz/slua-tstl-plugin requires luaTarget to be "Luau", set "luaTarget": "Luau" in tsconfig.json',
+                category: ts.DiagnosticCategory.Error,
+                code: 90000,
+                source: "@gwigz/slua-tstl-plugin",
+            });
+        }
+        if (options.luaLibImport !== undefined &&
+            ![tstl.LuaLibImportKind.None, tstl.LuaLibImportKind.Inline].includes(options.luaLibImport)) {
+            diagnostics.push({
+                file: undefined,
+                start: undefined,
+                length: undefined,
+                messageText: '@gwigz/slua-tstl-plugin requires luaLibImport to be "none" or "inline"',
+                category: ts.DiagnosticCategory.Warning,
+                code: 90002,
+                source: "@gwigz/slua-tstl-plugin",
+            });
+        }
+        return diagnostics;
+    },
+    beforeEmit(program, _options, _emitHost, result) {
+        // Strip empty module boilerplate from files without explicit exports.
+        // `moduleDetection: "force"` causes TSTL to wrap every file as a module;
+        // standalone SLua scripts don't need the ____exports wrapper.
+        for (const file of result) {
+            if (!file.code.includes("local ____exports = {}\n"))
+                continue;
+            if (!file.code.trimEnd().endsWith("return ____exports"))
+                continue;
+            const hasExplicitExports = file.sourceFiles?.some((sf) => sf.statements.some((s) => ts.isExportDeclaration(s) ||
+                ts.isExportAssignment(s) ||
+                (ts.canHaveModifiers(s) &&
+                    ts.getModifiers(s)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword))));
+            if (!hasExplicitExports) {
+                file.code = file.code
+                    .replace(/local ____exports = \{\}\n/, "")
+                    .replace(/\nreturn ____exports\n?$/, "\n");
+            }
+        }
+    },
+};
+export default plugin;

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@gwigz/slua-tstl-plugin",
+  "version": "0.1.0",
+  "description": "TypeScriptToLua plugin for targeting Second Life's SLua runtime",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gwigz/slua.git",
+    "directory": "packages/tstl-plugin"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "typescript-to-lua": "^1.33.0"
+  },
+  "peerDependencies": {
+    "typescript": "~5.7.0"
+  }
+}