@gwigz/slua-tstl-plugin 1.0.0 → 1.1.0

package/README.md

@@ -2,6 +2,50 @@
 
 [TypeScriptToLua](https://typescripttolua.github.io) plugin to provide better DX with SLua types.
 
+## Usage
+
+Add the plugin to `tstl.luaPlugins` in your `tsconfig.json`:
+
+```jsonc
+{
+  "tstl": {
+    "luaTarget": "Luau",
+    "luaPlugins": [{ "name": "@gwigz/slua-tstl-plugin" }],
+  },
+}
+```
+
+To enable output optimizations, pass `optimize: true` for all flags, or pick individual ones:
+
+```jsonc
+{
+  "tstl": {
+    "luaPlugins": [
+      // all optimizations
+      { "name": "@gwigz/slua-tstl-plugin", "optimize": true },
+    ],
+  },
+}
+```
+
+```jsonc
+{
+  "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)
@@ -34,24 +78,26 @@ For SL-typed JSON (preserving vector/quaternion/uuid), use `lljson.slencode`/`ll
 
 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.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.replaceAll(a, b)` | `ll.ReplaceSubString(str, a, b, 0)`       |
+| 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)` 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.
+> `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
 
@@ -134,6 +180,132 @@ This only applies when the argument is directly a `/` expression. `Math.floor(x)
 > [!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.
 
+## 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.
+
+```typescript
+const result = arr.filter((x) => x > 0)
+```
+
+```lua
+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.
+
+```typescript
+const { a, b } = fn()
+```
+
+Default output:
+
+```lua
+local ____fn_result_0 = fn()
+local a = ____fn_result_0.a
+local b = ____fn_result_0.b
+```
+
+Optimized output:
+
+```lua
+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:
+
+```lua
+local x
+x = 5
+```
+
+Optimized output:
+
+```lua
+local x = 5
+```
+
+### `numericConcat`
+
+Strips `tostring()` from number-typed (and string-typed) template literal interpolations, since Luau's `..` operator handles numeric concatenation natively.
+
+```typescript
+// count is number
+const msg = `items: ${count}`
+```
+
+Default output:
+
+```lua
+local msg = "items: " .. tostring(count)
+```
+
+Optimized output:
+
+```lua
+local msg = "items: " .. count
+```
+
+Non-numeric types (booleans, `any`, etc.) still get wrapped in `tostring()`.
+
 ## Keeping output small
 
 Some TypeScript patterns pull in large TSTL runtime helpers. Here are recommendations for keeping output lean:

package/dist/constants.d.ts

@@ -0,0 +1,25 @@
+import * as ts from "typescript";
+/**
+ * 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.
+ */
+export declare const PASCAL_TO_LOWER: Record<string, string>;
+/**
+ * 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).
+ */
+export declare const TSTL_KEYWORD_FIXUPS: Record<string, string>;
+export declare const BINARY_BITWISE_OPS: Record<number, string>;
+/**
+ * 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.
+ */
+export declare const COMPOUND_BITWISE_OPS: Record<number, string>;
+export declare const EQUALITY_OPS: Set<ts.SyntaxKind>;

package/dist/constants.js

@@ -0,0 +1,50 @@
+import * as ts from "typescript";
+/**
+ * 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.
+ */
+export 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).
+ */
+export const TSTL_KEYWORD_FIXUPS = {
+    ____bit32: "bit32",
+};
+export 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.
+ */
+export 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",
+};
+export const EQUALITY_OPS = new Set([
+    ts.SyntaxKind.EqualsEqualsToken,
+    ts.SyntaxKind.EqualsEqualsEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsEqualsToken,
+]);

package/dist/index.d.ts

@@ -1,3 +1,11 @@
 import * as tstl from "typescript-to-lua";
-declare const plugin: tstl.Plugin;
-export default plugin;
+import type { CallTransform } from "./transforms.js";
+import type { OptimizeFlags } from "./optimize.js";
+export type { CallTransform, OptimizeFlags };
+export interface SluaPluginOptions {
+    /** Enable per-transform output optimizations. Pass `true` to enable all. */
+    optimize?: boolean | OptimizeFlags;
+    [key: string]: any;
+}
+declare function createPlugin(options?: SluaPluginOptions): tstl.Plugin;
+export default createPlugin;