@gwigz/slua-tstl-plugin 1.0.0 → 1.2.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,178 @@ 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.
 
+### 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.
+
+```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()`.
+
+### `defaultParams`
+
+Collapses default-parameter nil-checks into a single `or` expression.
+
+```typescript
+function respondPoll(extraHtml = "") {
+  // ...
+}
+```
+
+Default output:
+
+```lua
+function respondPoll(extraHtml)
+    if extraHtml == nil then
+        extraHtml = ""
+    end
+end
+```
+
+Optimized output:
+
+```lua
+function respondPoll(extraHtml)
+    extraHtml = extraHtml or ""
+end
+```
+
+Safe for string and number defaults (both truthy in Lua). Not applied to `false` defaults.
+
 ## 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/define.d.ts

@@ -0,0 +1,19 @@
+import * as ts from "typescript";
+export type DefineMap = Map<string, boolean | number | string>;
+/**
+ * Attempt to statically evaluate a TS expression against the define map.
+ * Returns the resolved value, or `undefined` if the expression cannot be
+ * statically resolved (i.e. it should be left to the normal transpiler).
+ *
+ * Supported forms:
+ * - Bare identifier: `CONFIG_X` -> lookup
+ * - Negation: `!CONFIG_X`
+ * - Strict equality: `CONFIG_X === true`, `CONFIG_X !== false`, etc.
+ */
+export declare function tryEvaluateCondition(expr: ts.Expression, defineMap: DefineMap): boolean | undefined;
+/**
+ * Check whether a node has a `@define FLAG` JSDoc tag whose flag
+ * is in the define map and resolves to falsy. When true, the
+ * entire declaration should be stripped from the output.
+ */
+export declare function shouldStripDefineGuard(node: ts.Node, defineMap: DefineMap): boolean;

package/dist/define.js

@@ -0,0 +1,83 @@
+import * as ts from "typescript";
+/**
+ * Attempt to statically evaluate a TS expression against the define map.
+ * Returns the resolved value, or `undefined` if the expression cannot be
+ * statically resolved (i.e. it should be left to the normal transpiler).
+ *
+ * Supported forms:
+ * - Bare identifier: `CONFIG_X` -> lookup
+ * - Negation: `!CONFIG_X`
+ * - Strict equality: `CONFIG_X === true`, `CONFIG_X !== false`, etc.
+ */
+export function tryEvaluateCondition(expr, defineMap) {
+    // Bare identifier: CONFIG_X
+    if (ts.isIdentifier(expr)) {
+        const value = defineMap.get(expr.text);
+        return value === undefined ? undefined : !!value;
+    }
+    // Negation: !CONFIG_X
+    if (ts.isPrefixUnaryExpression(expr) && expr.operator === ts.SyntaxKind.ExclamationToken) {
+        const inner = tryEvaluateCondition(expr.operand, defineMap);
+        return inner === undefined ? undefined : !inner;
+    }
+    // Strict equality/inequality: CONFIG_X === true, CONFIG_X !== false, etc.
+    if (ts.isBinaryExpression(expr)) {
+        const op = expr.operatorToken.kind;
+        if (op !== ts.SyntaxKind.EqualsEqualsEqualsToken &&
+            op !== ts.SyntaxKind.ExclamationEqualsEqualsToken) {
+            return undefined;
+        }
+        let identValue;
+        let literalValue;
+        // Try both orientations: CONFIG_X === true  or  true === CONFIG_X
+        if (ts.isIdentifier(expr.left)) {
+            identValue = defineMap.get(expr.left.text);
+            literalValue = extractLiteral(expr.right);
+        }
+        else if (ts.isIdentifier(expr.right)) {
+            identValue = defineMap.get(expr.right.text);
+            literalValue = extractLiteral(expr.left);
+        }
+        if (identValue === undefined || literalValue === undefined)
+            return undefined;
+        const equal = identValue === literalValue;
+        return op === ts.SyntaxKind.EqualsEqualsEqualsToken ? equal : !equal;
+    }
+    return undefined;
+}
+/**
+ * Check whether a node has a `@define FLAG` JSDoc tag whose flag
+ * is in the define map and resolves to falsy. When true, the
+ * entire declaration should be stripped from the output.
+ */
+export function shouldStripDefineGuard(node, defineMap) {
+    const jsDocs = node.jsDoc;
+    if (!jsDocs || jsDocs.length === 0)
+        return false;
+    for (const tag of ts.getJSDocTags(node)) {
+        if (tag.tagName.text === "define" && typeof tag.comment === "string") {
+            const flag = tag.comment.trim();
+            if (defineMap.has(flag) && !defineMap.get(flag)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function extractLiteral(expr) {
+    if (expr.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (expr.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    if (ts.isNumericLiteral(expr))
+        return Number(expr.text);
+    if (ts.isStringLiteral(expr))
+        return expr.text;
+    // Handle negative numbers: -123
+    if (ts.isPrefixUnaryExpression(expr) &&
+        expr.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(expr.operand)) {
+        return -Number(expr.operand.text);
+    }
+    return undefined;
+}

package/dist/index.d.ts

@@ -1,3 +1,14 @@
 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";
+import type { DefineMap } from "./define.js";
+export type { CallTransform, OptimizeFlags, DefineMap };
+export interface SluaPluginOptions {
+    /** Enable per-transform output optimizations. Pass `true` to enable all. */
+    optimize?: boolean | OptimizeFlags;
+    /** Compile-time defines for dead code elimination. */
+    define?: Record<string, boolean | number | string>;
+    [key: string]: any;
+}
+declare function createPlugin(options?: SluaPluginOptions): tstl.Plugin;
+export default createPlugin;