@gwigz/slua-tstl-plugin 1.1.0 → 1.3.0

package/README.md

@@ -180,6 +180,22 @@ 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.
@@ -306,9 +322,42 @@ 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:
+Some TypeScript patterns pull in large TSTL runtime helpers. Here are recommendations for keeping output lean.
+
+> [!TIP]
+> Install [`@gwigz/slua-oxlint-config`](../oxlint-config) to enforce these recommendations at lint time.
 
 ### Avoid `delete` on objects
 
@@ -398,3 +447,7 @@ const seen: Record<string, boolean> = {}
 ```bash
 bun run build
 ```
+
+## Documentation
+
+Full API reference and usage examples are available at [slua.gwigz.link/docs/slua](https://slua.gwigz.link/docs/slua).

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,10 +1,13 @@
 import * as tstl from "typescript-to-lua";
 import type { CallTransform } from "./transforms.js";
 import type { OptimizeFlags } from "./optimize.js";
-export type { CallTransform, OptimizeFlags };
+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;

package/dist/index.js

@@ -1,16 +1,91 @@
 import * as ts from "typescript";
 import * as tstl from "typescript-to-lua";
 import { PASCAL_TO_LOWER, TSTL_KEYWORD_FIXUPS, BINARY_BITWISE_OPS, COMPOUND_BITWISE_OPS, } from "./constants.js";
-import { createBit32Call, isMathFloor, isStringOrNumberLike, extractBtestPattern, extractIndexOfPresence, extractConcatSelfAssignment, extractSpreadSelfAssignment, emitChainedExtend, getLLIndexSemantics, emitLLIndexCall, isDetectedEventIndex, createNamespacedCall, createStringFindCall, escapeRegex, } from "./utils.js";
+import { createBit32Call, isMathFloor, isStringOrNumberLike, extractBtestPattern, extractIndexOfPresence, extractConcatSelfAssignment, extractSpreadSelfAssignment, emitChainedExtend, getLLIndexSemantics, emitLLIndexCall, isDetectedEventIndex, createNamespacedCall, createStringFindCall, } from "./utils.js";
 import { CALL_TRANSFORMS } from "./transforms.js";
 import { createOptimizeTransforms, countFilterCalls, ALL_OPTIMIZE } from "./optimize.js";
+import { tryEvaluateCondition, shouldStripDefineGuard } from "./define.js";
+import { stripInternalJSDocTags, stripEmptyModuleBoilerplate, collapseDefaultParamNilChecks, shortenTempNames, collapseFieldAccesses, inlineForwardDeclarations, } from "./lua-transforms.js";
 function createPlugin(options = {}) {
     const opt = options.optimize === true ? ALL_OPTIMIZE : options.optimize || {};
     const filterSkipFiles = new Set();
     const optTransforms = opt.filter ? createOptimizeTransforms(filterSkipFiles) : [];
     const transforms = [...CALL_TRANSFORMS, ...optTransforms];
+    const defineMap = new Map(options.define ? Object.entries(options.define) : []);
     const plugin = {
         visitors: {
+            [ts.SyntaxKind.Identifier]: defineMap.size > 0
+                ? (node, context) => {
+                    const value = defineMap.get(node.text);
+                    if (value === undefined)
+                        return context.superTransformExpression(node);
+                    // Don't replace if this identifier is:
+                    // - A property name in a property access (obj.CONFIG_X)
+                    // - A declaration name (const CONFIG_X = ...)
+                    // - A parameter name
+                    // - A property assignment name ({ CONFIG_X: ... })
+                    // - A shorthand property assignment name ({ CONFIG_X })
+                    const parent = node.parent;
+                    if (ts.isPropertyAccessExpression(parent) && parent.name === node) {
+                        return context.superTransformExpression(node);
+                    }
+                    if ((ts.isVariableDeclaration(parent) ||
+                        ts.isFunctionDeclaration(parent) ||
+                        ts.isParameter(parent) ||
+                        ts.isEnumMember(parent)) &&
+                        parent.name === node) {
+                        return context.superTransformExpression(node);
+                    }
+                    if (ts.isPropertyAssignment(parent) && parent.name === node) {
+                        return context.superTransformExpression(node);
+                    }
+                    if (ts.isShorthandPropertyAssignment(parent) && parent.name === node) {
+                        return context.superTransformExpression(node);
+                    }
+                    if (typeof value === "boolean") {
+                        return tstl.createBooleanLiteral(value, node);
+                    }
+                    if (typeof value === "number") {
+                        return tstl.createNumericLiteral(value, node);
+                    }
+                    return tstl.createStringLiteral(value, node);
+                }
+                : undefined,
+            [ts.SyntaxKind.IfStatement]: defineMap.size > 0
+                ? (node, context) => {
+                    const result = tryEvaluateCondition(node.expression, defineMap);
+                    if (result === undefined) {
+                        return context.superTransformStatements(node);
+                    }
+                    if (result) {
+                        const stmts = ts.isBlock(node.thenStatement)
+                            ? [...node.thenStatement.statements]
+                            : [node.thenStatement];
+                        return stmts.flatMap((s) => context.transformStatements(s));
+                    }
+                    if (node.elseStatement) {
+                        const stmts = ts.isBlock(node.elseStatement)
+                            ? [...node.elseStatement.statements]
+                            : [node.elseStatement];
+                        return stmts.flatMap((s) => context.transformStatements(s));
+                    }
+                    return [];
+                }
+                : undefined,
+            [ts.SyntaxKind.FunctionDeclaration]: defineMap.size > 0
+                ? (node, context) => {
+                    if (shouldStripDefineGuard(node, defineMap))
+                        return [];
+                    return context.superTransformStatements(node);
+                }
+                : undefined,
+            [ts.SyntaxKind.VariableStatement]: defineMap.size > 0
+                ? (node, context) => {
+                    if (shouldStripDefineGuard(node, defineMap))
+                        return [];
+                    return context.superTransformStatements(node);
+                }
+                : undefined,
             [ts.SyntaxKind.PropertyAccessExpression]: (node, context) => {
                 const result = context.superTransformExpression(node);
                 // Rewrite identifiers in the Lua AST (PascalCase -> lowercase, TSTL keyword fixups).
@@ -187,6 +262,35 @@ function createPlugin(options = {}) {
                 }
                 return parts.reduce((prev, current) => tstl.createBinaryExpression(prev, current, tstl.SyntaxKind.ConcatOperator));
             },
+            // Collapse `() => fn()` to just `fn` when fn has zero parameters.
+            // Extra args from the caller are harmlessly ignored by zero-param functions.
+            [ts.SyntaxKind.ArrowFunction]: (node, context) => {
+                if (node.parameters.length === 0) {
+                    let callExpr;
+                    if (ts.isCallExpression(node.body)) {
+                        callExpr = node.body;
+                    }
+                    else if (ts.isBlock(node.body) && node.body.statements.length === 1) {
+                        const stmt = node.body.statements[0];
+                        if (ts.isExpressionStatement(stmt) && ts.isCallExpression(stmt.expression)) {
+                            callExpr = stmt.expression;
+                        }
+                        else if (ts.isReturnStatement(stmt) &&
+                            stmt.expression &&
+                            ts.isCallExpression(stmt.expression)) {
+                            callExpr = stmt.expression;
+                        }
+                    }
+                    if (callExpr && callExpr.arguments.length === 0 && ts.isIdentifier(callExpr.expression)) {
+                        const type = context.checker.getTypeAtLocation(callExpr.expression);
+                        const sigs = type.getCallSignatures();
+                        if (sigs.length > 0 && sigs.every((s) => s.parameters.length === 0)) {
+                            return context.transformExpression(callExpr.expression);
+                        }
+                    }
+                }
+                return context.superTransformExpression(node);
+            },
         },
         beforeTransform(program, compilerOptions) {
             const diagnostics = [];
@@ -214,152 +318,34 @@ function createPlugin(options = {}) {
             }
             return diagnostics;
         },
-        beforeEmit(program, _options, _emitHost, result) {
-            // Strip internal @indexArg / @indexReturn JSDoc tags from Lua comments.
-            // These are only consumed by the plugin at transpile time; they should
-            // not leak into the output as Lua comments.
-            for (const file of result) {
-                file.code = file.code
-                    .replace(/^--\s*@index(?:Arg|Return)\b.*\n/gm, "")
-                    .replace(/^(---.*)\n(?:-- *\n)+(?=local |ll\.)/gm, "$1\n");
-            }
-            // 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.
+        afterPrint(program, _options, emitHost, result) {
             for (const file of result) {
-                if (!file.code.includes("local ____exports = {}\n"))
+                if (!file.luaAst)
                     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");
-                }
-            }
-            // Shorten TSTL destructuring temp names: ____fn_result_N -> _rN
-            // Then collapse consecutive field accesses into multi-assignment:
-            // local a = _r0.x\nlocal b = _r0.y -> local a, b = _r0.x, _r0.y
-            if (opt.shortenTemps) {
-                for (const file of result) {
-                    const seen = new Map();
-                    let counter = 0;
-                    // Collect all unique temp names in order of first occurrence
-                    for (const match of file.code.matchAll(/____\w+_result_\d+/g)) {
-                        if (!seen.has(match[0])) {
-                            seen.set(match[0], `_r${counter++}`);
-                        }
-                    }
-                    // Replace all long names with short aliases in a single pass
-                    if (seen.size > 0) {
-                        const combined = new RegExp(`\\b(${[...seen.keys()].join("|")})\\b`, "g");
-                        file.code = file.code.replace(combined, (m) => seen.get(m) ?? m);
-                    }
-                    // Collapse consecutive field accesses from the same temp into multi-assignment
-                    const lines = file.code.split("\n");
-                    const collapsed = [];
-                    let li = 0;
-                    while (li < lines.length) {
-                        const m = lines[li].match(/^(\s*)local\s+(\w+)\s*=\s*(_r\d+)\.(\w+)\s*$/);
-                        if (m) {
-                            const [, indent, name, temp, field] = m;
-                            const names = [name];
-                            const accesses = [`${temp}.${field}`];
-                            const nextRe = new RegExp(`^${escapeRegex(indent)}local\\s+(\\w+)\\s*=\\s*${temp}\\.(\\w+)\\s*$`);
-                            while (li + 1 < lines.length) {
-                                const next = lines[li + 1].match(nextRe);
-                                if (!next)
-                                    break;
-                                names.push(next[1]);
-                                accesses.push(`${temp}.${next[2]}`);
-                                li++;
-                            }
-                            if (names.length > 1) {
-                                collapsed.push(`${indent}local ${names.join(", ")} = ${accesses.join(", ")}`);
-                            }
-                            else {
-                                collapsed.push(lines[li]);
-                            }
-                        }
-                        else {
-                            collapsed.push(lines[li]);
-                        }
-                        li++;
-                    }
-                    file.code = collapsed.join("\n");
+                let dirty = false;
+                // Always-on transforms
+                dirty = stripInternalJSDocTags(file.luaAst) || dirty;
+                dirty = stripEmptyModuleBoilerplate(file.luaAst, file.sourceFiles) || dirty;
+                // Opt-in transforms
+                if (opt.defaultParams)
+                    dirty = collapseDefaultParamNilChecks(file.luaAst) || dirty;
+                if (opt.shortenTemps) {
+                    dirty = shortenTempNames(file.luaAst) || dirty;
+                    dirty = collapseFieldAccesses(file.luaAst) || dirty;
                 }
-            }
-            // Merge forward-declared `local x` with its first `x = value` assignment.
-            // Only inlines when there are no references to x between declaration and assignment.
-            if (opt.inlineLocals) {
-                for (const file of result) {
-                    const lines = file.code.split("\n");
-                    const removedLines = new Set();
-                    for (let i = 0; i < lines.length; i++) {
-                        if (removedLines.has(i))
-                            continue;
-                        // Match forward declaration: `local var1, var2, ...` with no `=`
-                        const declMatch = lines[i].match(/^(\s*)local\s+((?:\w+(?:,\s*)*)*\w+)\s*$/);
-                        if (!declMatch)
-                            continue;
-                        const indent = declMatch[1];
-                        const escapedIndent = escapeRegex(indent);
-                        const vars = declMatch[2]
-                            .split(/,\s*/)
-                            .map((v) => v.trim())
-                            .filter(Boolean);
-                        const inlined = new Set();
-                        for (const varName of vars) {
-                            // Hoist regex compilation outside inner loop; negative lookahead
-                            // rejects multi-variable assignment lines like `a, b = fn()`
-                            const assignRe = new RegExp(`^${escapedIndent}${varName}(?!\\s*,)\\s*=\\s*(.+)$`);
-                            const refRe = new RegExp(`\\b${varName}\\b`);
-                            for (let j = i + 1; j < lines.length; j++) {
-                                if (removedLines.has(j))
-                                    continue;
-                                // Check for bare single-variable assignment at same indentation
-                                const assignMatch = lines[j].match(assignRe);
-                                if (assignMatch) {
-                                    // Don't inline if RHS references the variable (self-referencing)
-                                    if (refRe.test(assignMatch[1]))
-                                        break;
-                                    lines[j] = `${indent}local ${varName} = ${assignMatch[1]}`;
-                                    inlined.add(varName);
-                                    break;
-                                }
-                                // Reference to varName prevents inlining
-                                if (refRe.test(lines[j]))
-                                    break;
-                            }
-                        }
-                        if (inlined.size === 0)
-                            continue;
-                        const remaining = vars.filter((v) => !inlined.has(v));
-                        if (remaining.length === 0) {
-                            removedLines.add(i);
-                        }
-                        else {
-                            lines[i] = `${indent}local ${remaining.join(", ")}`;
-                        }
-                    }
-                    file.code = lines.filter((_, idx) => !removedLines.has(idx)).join("\n");
+                if (opt.inlineLocals)
+                    dirty = inlineForwardDeclarations(file.luaAst) || dirty;
+                // Re-print if AST was modified
+                if (dirty) {
+                    const printer = new tstl.LuaPrinter(emitHost, program, file.fileName);
+                    const printed = printer.print(file.luaAst);
+                    file.code = printed.code;
+                    file.sourceMap = printed.sourceMap;
+                    file.sourceMapNode = printed.sourceMapNode;
                 }
-            }
-        },
-        // Compound assignment runs in afterEmit so it applies after other plugins
-        // that may also post-process the Lua source in beforeEmit.
-        // `+=` is Luau-only syntax and would be garbled by Lua 5.1 parsers.
-        afterEmit(_program, _options, emitHost, result) {
-            if (!opt.compoundAssignment)
-                return;
-            for (const file of result) {
-                file.code = file.code.replace(/^(\s*)(\w+) = \2 (\/\/|\.\.|[+\-*/%^]) (\S+)(\s*(?:--.*)?)$/gm, "$1$2 $3= $4$5");
-                if (emitHost.writeFile) {
-                    emitHost.writeFile(file.outputPath, file.code, false);
+                // Compound assignment stays as regex (no Lua AST node for +=)
+                if (opt.compoundAssignment) {
+                    file.code = file.code.replace(/^(\s*)(\w+) = \2 (\/\/|\.\.|[+\-*/%^]) (\S+)(\s*(?:--.*)?)$/gm, "$1$2 $3= $4$5");
                 }
             }
         },

package/dist/lua-ast-walk.d.ts

@@ -0,0 +1,10 @@
+import * as lua from "typescript-to-lua";
+export type BlockVisitor = (statements: lua.Statement[]) => void;
+/** Walk all statement arrays in a File. Depth-first. */
+export declare function walkBlocks(file: lua.File, visitor: BlockVisitor): void;
+type IdentifierCallback = (id: lua.Identifier) => void;
+/** Walk all Identifier nodes in a File. Callback may mutate id.text. */
+export declare function walkIdentifiers(file: lua.File, cb: IdentifierCallback): void;
+/** Check if an expression tree contains an Identifier with the given name. */
+export declare function containsIdentifier(node: lua.Node, name: string): boolean;
+export {};