@gwigz/slua-tstl-plugin 1.0.0 → 1.1.0

package/dist/optimize.d.ts

@@ -0,0 +1,29 @@
+import * as ts from "typescript";
+import type { CallTransform } from "./transforms.js";
+export interface OptimizeFlags {
+    /** Inline `.filter()` calls as `for` loops with `ipairs`. Default: false */
+    filter?: boolean;
+    /** Rewrite `x = x + n` to `x += n` (Luau compound assignment). Default: false */
+    compoundAssignment?: boolean;
+    /** Reorder `Math.floor((a / b) * c)` to `a * c // b`. */
+    floorMultiply?: boolean;
+    /** Emit bare `string.find`/`table.find` for indexOf presence checks. */
+    indexOf?: boolean;
+    /** Shorten TSTL destructuring temp names (`____fn_result_N` -> `_rN`). */
+    shortenTemps?: boolean;
+    /** Merge forward-declared `local x` with its first `x = value` assignment. */
+    inlineLocals?: boolean;
+    /** Strip `tostring()` from number-typed template literal interpolations. */
+    numericConcat?: boolean;
+}
+export declare const ALL_OPTIMIZE: Required<OptimizeFlags>;
+/**
+ * Count `arr.filter(cb)` calls and return a set of file names where inlining
+ * should be skipped (the shared `__TS__ArrayFilter` helper is smaller).
+ *
+ * When `bundle` is true (luaBundle mode), all source files end up in a single
+ * output, so the total across the program is what matters.  Otherwise each
+ * file is counted independently.
+ */
+export declare function countFilterCalls(program: ts.Program, bundle: boolean): Set<string>;
+export declare function createOptimizeTransforms(filterSkipFiles: Set<string>): CallTransform[];

package/dist/optimize.js

@@ -0,0 +1,105 @@
+import * as ts from "typescript";
+import * as tstl from "typescript-to-lua";
+import { isMethodCall, isArrayType } from "./utils.js";
+export const ALL_OPTIMIZE = {
+    filter: true,
+    compoundAssignment: true,
+    floorMultiply: true,
+    indexOf: true,
+    shortenTemps: true,
+    inlineLocals: true,
+    numericConcat: true,
+};
+/**
+ * Count `arr.filter(cb)` calls and return a set of file names where inlining
+ * should be skipped (the shared `__TS__ArrayFilter` helper is smaller).
+ *
+ * When `bundle` is true (luaBundle mode), all source files end up in a single
+ * output, so the total across the program is what matters.  Otherwise each
+ * file is counted independently.
+ */
+export function countFilterCalls(program, bundle) {
+    const skip = new Set();
+    const checker = program.getTypeChecker();
+    const sourceFiles = program.getSourceFiles().filter((sf) => !sf.isDeclarationFile);
+    if (bundle) {
+        let total = 0;
+        for (const sf of sourceFiles) {
+            ts.forEachChild(sf, function visit(node) {
+                if (isArrayFilterCall(node, checker))
+                    total++;
+                ts.forEachChild(node, visit);
+            });
+        }
+        if (total > 1) {
+            for (const sf of sourceFiles) {
+                skip.add(sf.fileName);
+            }
+        }
+    }
+    else {
+        for (const sf of sourceFiles) {
+            let count = 0;
+            ts.forEachChild(sf, function visit(node) {
+                if (isArrayFilterCall(node, checker))
+                    count++;
+                ts.forEachChild(node, visit);
+            });
+            if (count > 1) {
+                skip.add(sf.fileName);
+            }
+        }
+    }
+    return skip;
+}
+function isArrayFilterCall(node, checker) {
+    return (ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        node.expression.name.text === "filter" &&
+        node.arguments.length === 1 &&
+        isArrayType(node.expression.expression, checker));
+}
+export function createOptimizeTransforms(filterSkipFiles) {
+    let counter = 0;
+    return [
+        // arr.filter(cb) -> inline for loop with ipairs
+        {
+            match: (node, checker) => {
+                if (filterSkipFiles.has(node.getSourceFile().fileName))
+                    return false;
+                return isMethodCall(node, checker, isArrayType, "filter", 1);
+            },
+            emit: (node, context) => {
+                const n = counter++;
+                const resultId = tstl.createIdentifier(`____opt_${n}`);
+                const valueId = tstl.createIdentifier(`____opt_v_${n}`);
+                const cbId = tstl.createIdentifier(`____opt_fn_${n}`);
+                const arr = context.transformExpression(node.expression.expression);
+                const cb = context.transformExpression(node.arguments[0]);
+                // Strip TSTL's context parameter (____) from the callback if present.
+                // Array callbacks are always called positionally; the context param is dead.
+                if (tstl.isFunctionExpression(cb) &&
+                    cb.params &&
+                    cb.params.length > 0 &&
+                    cb.params[0].text === "____") {
+                    cb.params = cb.params.slice(1);
+                }
+                // local ____opt_fn_N = <callback>
+                context.addPrecedingStatements(tstl.createVariableDeclarationStatement(cbId, cb, node));
+                // local ____opt_N = {}
+                context.addPrecedingStatements(tstl.createVariableDeclarationStatement(tstl.cloneIdentifier(resultId), tstl.createTableExpression(), node));
+                // ____opt_fn_N(____opt_v_N)
+                const filterCall = tstl.createCallExpression(tstl.cloneIdentifier(cbId), [
+                    tstl.cloneIdentifier(valueId),
+                ]);
+                // ____opt_N[#____opt_N + 1] = ____opt_v_N
+                const appendStmt = tstl.createAssignmentStatement(tstl.createTableIndexExpression(tstl.cloneIdentifier(resultId), tstl.createBinaryExpression(tstl.createUnaryExpression(tstl.cloneIdentifier(resultId), tstl.SyntaxKind.LengthOperator), tstl.createNumericLiteral(1), tstl.SyntaxKind.AdditionOperator)), tstl.cloneIdentifier(valueId));
+                // if ____opt_fn_N(____opt_v_N) then ... end
+                const ifStmt = tstl.createIfStatement(filterCall, tstl.createBlock([appendStmt]));
+                // for _, ____opt_v_N in ipairs(arr) do ... end
+                context.addPrecedingStatements(tstl.createForInStatement(tstl.createBlock([ifStmt]), [tstl.createIdentifier("_"), valueId], [tstl.createCallExpression(tstl.createIdentifier("ipairs"), [arr])], node));
+                return tstl.cloneIdentifier(resultId);
+            },
+        },
+    ];
+}

package/dist/transforms.d.ts

@@ -0,0 +1,7 @@
+import * as ts from "typescript";
+import * as tstl from "typescript-to-lua";
+export type CallTransform = {
+    match: (node: ts.CallExpression, checker: ts.TypeChecker) => boolean;
+    emit: (node: ts.CallExpression, context: tstl.TransformationContext) => tstl.Expression;
+};
+export declare const CALL_TRANSFORMS: CallTransform[];

package/dist/transforms.js

@@ -0,0 +1,195 @@
+import * as ts from "typescript";
+import * as tstl from "typescript-to-lua";
+import { isMethodCall, isNamespaceCall, isGlobalCall, isStringType, isArrayType, createNamespacedCall, createStringFindCall, } from "./utils.js";
+export 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) -> (string.find(str, x, 1, true) or 0) - 1
+    {
+        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]);
+            const findOrZero = tstl.createBinaryExpression(createStringFindCall(str, search, node), tstl.createNumericLiteral(0), tstl.SyntaxKind.OrOperator, node);
+            return tstl.createBinaryExpression(tstl.createParenthesizedExpression(findOrZero), tstl.createNumericLiteral(1), tstl.SyntaxKind.SubtractionOperator, 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]);
+            return tstl.createBinaryExpression(createStringFindCall(str, search, node), 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]);
+            return tstl.createBinaryExpression(createStringFindCall(str, search, node), 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);
+        },
+    },
+    // str.replace / str.replaceAll -> ll.ReplaceSubString(str, search, replacement, count)
+    // count=1 for replace (first match only), count=0 for replaceAll
+    ...[
+        ["replace", 1],
+        ["replaceAll", 0],
+    ].map(([method, count]) => ({
+        match: (node, checker) => isMethodCall(node, checker, isStringType, method, 2),
+        emit: (node, context) => {
+            const str = context.transformExpression(node.expression.expression);
+            const search = context.transformExpression(node.arguments[0]);
+            const replacement = context.transformExpression(node.arguments[1]);
+            return createNamespacedCall("ll", "ReplaceSubString", [str, search, replacement, tstl.createNumericLiteral(count)], 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);
+        },
+    },
+];

package/dist/utils.d.ts

@@ -0,0 +1,130 @@
+import * as ts from "typescript";
+import * as tstl from "typescript-to-lua";
+/**
+ * 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.
+ */
+export declare function createBit32Call(fn: string, args: tstl.Expression[], node?: ts.Node): tstl.CallExpression;
+/**
+ * Returns true when `node` is `Math.floor(<single-arg>)`.
+ */
+export declare function isMathFloor(node: ts.CallExpression): node is ts.CallExpression & {
+    arguments: [ts.Expression];
+};
+export declare function isZeroLiteral(node: ts.Expression): boolean;
+export declare function isNegatedEquality(op: ts.SyntaxKind): boolean;
+/**
+ * Detect `(a & b) !== 0`, `0 === (a & b)`, etc. and return the `&` expression
+ * plus whether to negate the btest result.
+ */
+export declare function extractBtestPattern(node: ts.BinaryExpression): {
+    band: ts.BinaryExpression;
+    negate: boolean;
+} | null;
+/**
+ * Detects `-1` as either a PrefixUnaryExpression (minus + 1) or a numeric literal with text "-1".
+ */
+export declare function isMinusOneLiteral(node: ts.Expression): boolean;
+/**
+ * Detect `s.indexOf(x) >= 0`, `s.indexOf(x) !== -1`, etc. and return
+ * the indexOf call plus whether the check means "not found" (negate).
+ *
+ * Presence patterns (found -> truthy): `>= 0`, `> -1`, `!== -1`, `!= -1`
+ * Absence patterns (not found -> negate): `< 0`, `=== -1`, `== -1`
+ * Handles both operand orders (indexOf on left or right).
+ */
+export declare function extractIndexOfPresence(node: ts.BinaryExpression, checker: ts.TypeChecker): {
+    call: ts.CallExpression;
+    isString: boolean;
+    negate: boolean;
+} | null;
+/**
+ * Type-checking helpers for catalog transforms.
+ */
+export declare function isStringType(expr: ts.Expression, checker: ts.TypeChecker): boolean;
+/**
+ * Checks whether `expr` resolves to a string or number type.
+ * Falls back to inspecting the symbol's declared type annotation when
+ * `getTypeAtLocation` returns an unexpected type (e.g. `void` for identifiers
+ * that shadow DOM globals like `name`).
+ */
+export declare function isStringOrNumberLike(checker: ts.TypeChecker, expr: ts.Expression): boolean;
+export declare function isArrayType(expr: ts.Expression, checker: ts.TypeChecker): boolean;
+export declare function isDetectedEventType(expr: ts.Expression, checker: ts.TypeChecker): boolean;
+/**
+ * Returns true when `node` is `detectedEvent.index`, a property access
+ * on a `DetectedEvent` reading the `.index` field.
+ */
+export declare function isDetectedEventIndex(node: ts.PropertyAccessExpression, checker: ts.TypeChecker): boolean;
+/**
+ * Checks whether `node` is `obj.method(args)` where `obj` matches the
+ * given type predicate and the method name matches.
+ */
+export declare function isMethodCall(node: ts.CallExpression, checker: ts.TypeChecker, typeGuard: (expr: ts.Expression, checker: ts.TypeChecker) => boolean, method: string, argCount?: number): node is ts.CallExpression & {
+    expression: ts.PropertyAccessExpression;
+};
+/**
+ * Checks whether `node` is `Namespace.method(args)` using syntactic
+ * identifier matching (no TypeChecker needed).
+ */
+export declare function isNamespaceCall(node: ts.CallExpression, namespace: string, method: string): node is ts.CallExpression & {
+    expression: ts.PropertyAccessExpression;
+};
+/**
+ * Checks whether `node` is a call to a global function by name.
+ */
+export declare function isGlobalCall(node: ts.CallExpression, name: string): boolean;
+/**
+ * Creates a `ns.fn(...args)` Lua call expression.
+ */
+export declare function createNamespacedCall(ns: string, fn: string, args: tstl.Expression[], node?: ts.Node): tstl.CallExpression;
+/** Creates a `string.find(str, search, 1, true)` plain-text search call. */
+export declare function createStringFindCall(str: tstl.Expression, search: tstl.Expression, node?: ts.Node): tstl.CallExpression;
+/** Escapes a string for literal use inside `new RegExp(...)`. */
+export declare function escapeRegex(s: string): string;
+/**
+ * Detects `arr = arr.concat(b, c, ...)` where LHS is a simple identifier,
+ * the receiver matches LHS, and all concat arguments are array-typed.
+ */
+export declare function extractConcatSelfAssignment(expr: ts.BinaryExpression, checker: ts.TypeChecker): {
+    name: ts.Identifier;
+    args: readonly ts.Expression[];
+} | null;
+/**
+ * Detects `arr = [...arr, ...b, ...c]` where LHS is a simple identifier,
+ * all elements are spreads, the first spread matches LHS, and all tail
+ * spread expressions are array-typed.
+ */
+export declare function extractSpreadSelfAssignment(expr: ts.BinaryExpression, checker: ts.TypeChecker): {
+    name: ts.Identifier;
+    args: ts.Expression[];
+} | null;
+/**
+ * Builds nested `table.extend` calls:
+ * - Single arg: `table.extend(arr, b)`
+ * - Multiple: `table.extend(table.extend(arr, b), c)`
+ */
+export declare function emitChainedExtend(target: tstl.Expression, args: [tstl.Expression, ...tstl.Expression[]], node: ts.Node): tstl.CallExpression;
+export interface LLIndexSemantics {
+    indexArgs: Set<string>;
+    indexReturn: boolean;
+}
+/**
+ * For an `ll.Foo(...)` call, inspect the resolved signature's JSDoc tags
+ * to determine which arguments have `@indexArg` semantics and whether
+ * the return value has `@indexReturn` semantics.
+ */
+export declare function getLLIndexSemantics(node: ts.CallExpression, checker: ts.TypeChecker): LLIndexSemantics | null;
+/**
+ * Adjusts a 0-based index argument to 1-based for Lua.
+ * Constant-folds numeric literals; otherwise emits `expr + 1`.
+ */
+export declare function adjustIndexArg(arg: ts.Expression, context: tstl.TransformationContext): tstl.Expression;
+/**
+ * Emit an `ll.Foo(...)` call with automatic index adjustments:
+ * - `@indexArg` parameters get `+1`
+ * - `@indexReturn` wraps the result in a nil-safe `__tmp and (__tmp - 1)`
+ */
+export declare function emitLLIndexCall(node: ts.CallExpression, context: tstl.TransformationContext, semantics: LLIndexSemantics): tstl.Expression;