rbxts-transform-boost 0.1.0 → 1.1.0

package/README.md

@@ -4,11 +4,11 @@
 >
 > **What carried over:** Luau type annotation injection on function parameters for native codegen (primitives, Roblox value types, arrays).
 >
-> **What's new:** `--!optimize 2` on every file, `game:GetService()` hoisting to module-level locals, repeated property chain hoisting, loop bounds hoisting — all without needing `//!native` in every file.
+> **What's new:** `--!optimize 2` on every file, `game:GetService()` hoisting to module-level locals, repeated property chain hoisting, `const` keyword for TypeScript `const` declarations, output formatting so compiled files look human-written.
 >
-> **What's different:** The old package also annotated return types, local variable declarations, class methods, and user-defined interfaces/type aliases. Those are not yet in this package — they're planned but the implementation is non-trivial. The old package also had reliability issues that this rewrite addresses.
+> **What's different:** The old package also annotated return types, local variable declarations, class methods, and user-defined interfaces/type aliases. Those are not yet in this package — they're planned. The old package also had reliability issues that this rewrite addresses.
 
-A roblox-ts transformer that automatically applies Luau performance directives at compile time — no runtime cost, no code changes required.
+A TypeScript transformer for Roblox that automatically applies Luau performance directives and cleans up compiled output at build time — no runtime cost, no code changes required.
 
 ## Installation
 
@@ -24,6 +24,7 @@ npm install --save-dev rbxts-transform-boost
             {
                 "transform": "rbxts-transform-boost",
                 "optimize": true,
+                "strict": true,
                 "hoist": true
             }
         ]
@@ -36,14 +37,15 @@ npm install --save-dev rbxts-transform-boost
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `optimize` | `boolean` | `true` | Prepend `--!optimize 2` to every file that doesn't already have it |
+| `strict` | `boolean` | `true` | Prepend `--!strict` to every file that doesn't already have it |
 | `hoist` | `boolean` | `true` | Hoist `GetService` calls and repeated property reads to locals |
 
-`--!native` is never auto-inserted. Add `//!native` at the top of your TypeScript file for hot paths you've profiled — rotor preserves it.
+`--!native` is never auto-inserted. Add `//!native` at the top of your TypeScript file for hot paths you've profiled — the compiler preserves it.
 
 ```typescript
 //!native
 export function integrate(pos: Vector3, vel: Vector3, acc: Vector3, dt: number) {
-    ...
+    // ...
 }
 ```
 
@@ -53,21 +55,10 @@ export function integrate(pos: Vector3, vel: Vector3, acc: Vector3, dt: number)
 
 ### `--!optimize 2` — always on top
 
-Every file gets `--!optimize 2` prepended if it doesn't already have it. Roblox already runs all scripts at optimization level 2, but the directive makes Studio behaviour match production and signals intent.
-
-```typescript
-// TypeScript source
-export function encodeFixed(buf: buffer, offset: number, value: number, scale: number): number {
-    const fixed = math.floor(value * scale);
-    const clamped = math.clamp(fixed, -32768, 32767);
-    buffer.writei16(buf, offset, clamped);
-    return offset + 2;
-}
-```
+Every file gets `--!optimize 2` prepended if it doesn't already have it. Roblox already runs all scripts at optimization level 2 in live games, but the directive makes Studio behaviour match production and signals intent.
 
 ```lua
 -- Without transformer
--- Compiled with rotor v2.2.0
 local function encodeFixed(buf, offset, value, scale)
     local fixed = math.floor(value * scale)
     local clamped = math.clamp(fixed, -32768, 32767)
@@ -79,20 +70,41 @@ end
 ```lua
 -- With transformer
 --!optimize 2
--- Compiled with rotor v2.2.0
-local function encodeFixed(buf: buffer, offset: number, value: number, scale: number)
-    local fixed = math.floor(value * scale)
-    local clamped = math.clamp(fixed, -32768, 32767)
+
+local function encodeFixed(buf: buffer, offset: number, value: number, scale: number): number
+    const fixed = math.floor(value * scale)
+    const clamped = math.clamp(fixed, -32768, 32767)
     buffer.writei16(buf, offset, clamped)
+
     return offset + 2
 end
 ```
 
 ---
 
+### `const` for TypeScript `const` declarations
+
+TypeScript `const` declarations are emitted as Luau `const` (shipped in Roblox Studio March 2026). TypeScript `let` stays as `local`. Rotor-generated internal variables (`_cache0`, `_shouldIncrement`, etc.) are not affected.
+
+```typescript
+// TypeScript
+const N = 100000;
+let i = 0;
+const elapsed = os.clock() - t0;
+```
+
+```lua
+-- Compiled output
+const N = 100000
+local i = 0
+const elapsed = os.clock() - t0
+```
+
+---
+
 ### GetService hoisting
 
-Every `game:GetService("X")` call in a file is hoisted to a module-level local on first load. Functions that call `GetService` on every invocation — the most common pattern in rotor output — pay the registry lookup cost zero times at runtime.
+Every `game:GetService("X")` call in a file is hoisted to a module-level local on first load. Functions that call `GetService` on every invocation — the most common compiled pattern — pay the registry lookup cost zero times at runtime.
 
 ```typescript
 // TypeScript source
@@ -115,12 +127,15 @@ end
 ```lua
 -- With transformer
 --!optimize 2
-local _Players = game:GetService("Players")   -- hoisted once at module load
+
+-- Services
 local _RunService = game:GetService("RunService")
+local _Players = game:GetService("Players")
+
+local function serviceWork(): string
+    const count = #_Players:GetPlayers()
+    const running = _RunService:IsRunning()
 
-local function serviceWork()
-    local count = #_Players:GetPlayers()
-    local running = _RunService:IsRunning()
     return `{count}-{running}`
 end
 ```
@@ -146,8 +161,8 @@ export function cameraWork(camera: Camera): number {
 ```lua
 -- Without transformer
 local function cameraWork(camera)
-    local pos = camera.CFrame.Position   -- engine call #1
-    local look = camera.CFrame.LookVector -- engine call #2
+    local pos = camera.CFrame.Position
+    local look = camera.CFrame.LookVector
     local fov = camera.FieldOfView
     return pos.Magnitude + look.X + fov
 end
@@ -155,48 +170,28 @@ end
 
 ```lua
 -- With transformer
-local function cameraWork(camera: Camera)
-    local _cache0 = camera.CFrame         -- one engine call
-    local pos = _cache0.Position           -- local read
-    local look = _cache0.LookVector        -- local read
-    local fov = camera.FieldOfView
+local function cameraWork(camera: Camera): number
+    const _cache0 = camera.CFrame
+    const pos = _cache0.Position
+    const look = _cache0.LookVector
+    const fov = camera.FieldOfView
+
     return pos.Magnitude + look.X + fov
 end
 ```
 
 **1.5× faster.** Also hoists value type field reads (`.X`, `.Y`, `.Z`) when they appear multiple times — the `cross` function reads each component twice, so all six are hoisted:
 
-```typescript
-// TypeScript source
-export function cross(a: Vector3, b: Vector3): Vector3 {
-    return new Vector3(
-        a.Y * b.Z - a.Z * b.Y,
-        a.Z * b.X - a.X * b.Z,
-        a.X * b.Y - a.Y * b.X,
-    );
-}
-```
-
-```lua
--- Without transformer
-local function cross(a, b)
-    return Vector3.new(
-        a.Y * b.Z - a.Z * b.Y,
-        a.Z * b.X - a.X * b.Z,
-        a.X * b.Y - a.Y * b.X
-    )
-end
-```
-
 ```lua
 -- With transformer
-local function cross(a: Vector3, b: Vector3)
-    local _cache0 = a.Y  -- each component read twice → all hoisted
-    local _cache1 = b.Z
-    local _cache2 = a.Z
-    local _cache3 = b.Y
-    local _cache4 = b.X
-    local _cache5 = a.X
+local function cross(a: Vector3, b: Vector3): Vector3
+    const _cache0 = a.Y
+    const _cache1 = b.Z
+    const _cache2 = a.Z
+    const _cache3 = b.Y
+    const _cache4 = b.X
+    const _cache5 = a.X
+
     return Vector3.new(
         _cache0 * _cache1 - _cache2 * _cache3,
         _cache2 * _cache4 - _cache5 * _cache1,
@@ -209,106 +204,109 @@ end
 
 ---
 
-### Loop bounds hoisting
+### Luau type annotation injection
 
-`arr.size()` in a `for` loop condition is re-evaluated on every iteration in rotor's output. The loops pass hoists it to a `const` before the loop.
+After the compiler writes `.luau` files, the transformer injects Luau type annotations on function parameters and return types. This lets the native compiler generate specialized code for numeric and Roblox value types.
 
 ```typescript
 // TypeScript source
-export function sumWeighted(values: Array<number>, weights: Array<number>): number {
-    let total = 0;
-    for (let i = 0; i < values.size(); i++) {
-        total += values[i] * weights[i];
-    }
-    return total;
+export function dot(a: Vector3, b: Vector3): number {
+    return a.X * b.X + a.Y * b.Y + a.Z * b.Z;
 }
 ```
 
 ```lua
 -- Without transformer
-local function sumWeighted(values, weights)
-    local total = 0
-    for i = 0, #values - 1 do   -- #values evaluated once per iteration
-        total += values[i + 1] * weights[i + 1]
-    end
-    return total
+local function dot(a, b)
+    return a.X * b.X + a.Y * b.Y + a.Z * b.Z
 end
 ```
 
 ```lua
 -- With transformer
-local function sumWeighted(values: {number}, weights: {number})
-    local total = 0
-    local _len_values = #values   -- hoisted: evaluated once total
-    for i = 0, _len_values - 1 do
-        total += values[i + 1] * weights[i + 1]
-    end
-    return total
+local function dot(a: Vector3, b: Vector3): number
+    return a.X * b.X + a.Y * b.Y + a.Z * b.Z
 end
 ```
 
-**2.3× faster** (combined with `--!native` and type annotations on `values`/`weights`).
+Supported types: `number`, `string`, `boolean`, `Vector3`, `Vector2`, `CFrame`, `UDim2`, `Color3`, `buffer`, `Instance`, `BasePart`, `Player`, `Camera`, `RunService`, `Players`, `Workspace`, and array forms (`{number}`, `{Vector3}`, etc.).
 
 ---
 
-### Luau type annotation injection
+### Output formatting
 
-After rotor writes `.luau` files, the transformer injects Luau type annotations on function parameters. This lets the native compiler generate specialized code for numeric and Roblox value types.
+This one's a personal pet peeve — yes, most people will never open a compiled `.luau` file. But the transformer post-processes every compiled `.luau` file so the output looks like a human wrote it anyway, not a compiler.
+
+**Preamble organisation** — top-level declarations are sorted into labeled sections in dependency order. Sections are sorted by line length (longest first). If you put a comment before a group of imports in TypeScript, that comment becomes the section label:
 
 ```typescript
-// TypeScript source
-export function dot(a: Vector3, b: Vector3): number {
-    return a.X * b.X + a.Y * b.Y + a.Z * b.Z;
-}
-```
+// Shared
+import * as utils from "../shared/utils";
 
-```lua
--- Without transformer
-local function dot(a, b)
-    return a.X * b.X + a.Y * b.Y + a.Z * b.Z
-end
+// Server
+import * as data from "../server/data";
 ```
 
 ```lua
--- With transformer
-local function dot(a: Vector3, b: Vector3)
-    return a.X * b.X + a.Y * b.Y + a.Z * b.Z
-end
+--!optimize 2
+--!native
+
+-- Compiled with rotor v2.2.0
+
+-- Runtime
+local TS = require(...)
+
+-- Services
+local _ReplicatedStorage = game:GetService("ReplicatedStorage")
+local _Workspace = game:GetService("Workspace")
+
+-- Shared
+local utils = TS.import(script, ...)
+
+-- Server
+local data = TS.import(script, ...)
 ```
 
-Supported types: `number`, `string`, `boolean`, `Vector3`, `Vector2`, `CFrame`, `UDim2`, `Color3`, `buffer`, `Instance`, `BasePart`, `Player`, `Camera`, `RunService`, `Players`, `Workspace`, and array forms (`{number}`, `{Vector3}`, etc.).
+**Spacing inside functions** — blank lines are added so blocks breathe:
+
+- Before `return` when it's not the only statement in the function
+- After `end` blocks when the next line is not another `end`, `else`, or `elseif`
+- Before block starters (`do`/`while`/`for`/`if`) when preceded by a group of `local`/`const` assignments
+- At `const` → `local` transitions
+
+**`--!` directives** are sorted by length and separated from the rotor header comment with a blank line.
 
 ---
 
 ## Benchmarks
 
-Measured in Roblox Studio server context. 100,000 iterations per benchmark (10,000 for `cfLookAt`). Same TypeScript source compiled two ways — with and without the transformer.
+Measured in Roblox Studio server context. 100,000 iterations per benchmark (10,000 for `cfLookAt`). Both suites use `//!native` — the only variable is whether the transformer is applied, so the numbers reflect what the transformer itself contributes on top of native.
 
 | Benchmark | With transformer | Without | Speedup | Driver |
 |-----------|-----------------|---------|---------|--------|
-| integrate (Verlet) | 0.042 µs | 0.055 µs | **1.3×** | `--!native` + type annotations |
-| dot (V3 manual) | 0.016 µs | 0.032 µs | **2.0×** | `--!native` |
-| cross (V3 manual) | 0.018 µs | 0.049 µs | **2.7×** | `--!native` + 6× field hoisting |
-| lerpVec3 (V3 manual) | 0.015 µs | 0.047 µs | **3.1×** | `--!native` + 3× field hoisting |
-| encodeFixed (buf+math) | 0.015 µs | 0.032 µs | **2.1×** | `--!native` |
-| encodePacket (3× fixed) | 0.018 µs | 0.067 µs | **3.7×** | `--!native` stacked across 3 calls |
-| sumWeighted (loop) | 0.046 µs | 0.107 µs | **2.3×** | `--!native` + loop bounds hoist |
-| dotProduct (loop) | 0.067 µs | 0.109 µs | **1.6×** | `--!native` + loop bounds hoist |
-| norm (loop+sqrt) | 0.048 µs | 0.111 µs | **2.3×** | `--!native` + loop bounds hoist |
-| mathHeavy (trig+sqrt) | 0.038 µs | 0.052 µs | **1.4×** | `--!native` |
-| fib(20) (iter) | 0.048 µs | 0.155 µs | **3.2×** | `--!native` on integer loop |
-| cfLookAt (ctor) | 0.079 µs | 0.079 µs | 1.0× | C++ floor — no Luau work |
-| cfChain (mul+angles) | 0.076 µs | 0.077 µs | 1.0× | C++ floor — no Luau work |
-| serviceWork (GetService ×2) | 0.185 µs | 0.440 µs | **2.4×** | GetService hoisting |
-| multiSvc (GetService ×3) | 0.142 µs | 0.480 µs | **3.4×** | GetService hoisting |
-| cameraWork (prop chain) | 0.148 µs | 0.215 µs | **1.5×** | `camera.CFrame` hoisted (2 reads → 1) |
-| formatStats (template) | 0.170 µs | 0.175 µs | ~1× | String — no arithmetic |
-| buildKey (template) | 0.068 µs | 0.086 µs | **1.3×** | `--!native` |
+| integrate (Verlet) | 0.058 µs | 0.071 µs | **1.2×** | type annotations |
+| dot (V3 manual) | 0.025 µs | 0.046 µs | **1.8×** | type annotations |
+| cross (V3 manual) | 0.024 µs | 0.072 µs | **3.0×** | 6× field hoisting + type annotations |
+| lerpVec3 (V3 manual) | 0.026 µs | 0.061 µs | **2.3×** | 3× field hoisting + type annotations |
+| encodeFixed (buf+math) | 0.025 µs | 0.026 µs | ~1× | — |
+| encodePacket (3× fixed) | 0.030 µs | 0.028 µs | ~1× | — |
+| sumWeighted (loop) | 0.051 µs | 0.054 µs | ~1× | type annotations |
+| dotProduct (loop) | 0.050 µs | 0.060 µs | **1.2×** | type annotations |
+| norm (loop+sqrt) | 0.052 µs | 0.058 µs | **1.1×** | type annotations |
+| mathHeavy (trig+sqrt) | 0.044 µs | 0.050 µs | **1.1×** | type annotations |
+| fib(20) (iter) | 0.062 µs | 0.071 µs | **1.1×** | type annotations |
+| cfLookAt (ctor) | 0.087 µs | 0.082 µs | ~1× | C++ floor — no Luau work |
+| cfChain (mul+angles) | 0.102 µs | 0.092 µs | ~1× | C++ floor — no Luau work |
+| serviceWork (GetService ×2) | 0.243 µs | 0.481 µs | **2.0×** | GetService hoisting |
+| multiSvc (GetService ×3) | 0.154 µs | 0.505 µs | **3.3×** | GetService hoisting |
+| cameraWork (prop chain) | 0.185 µs | 0.218 µs | **1.2×** | `camera.CFrame` hoisted (2 reads → 1) |
+| formatStats (template) | 0.191 µs | 0.187 µs | ~1× | string — no arithmetic |
+| buildKey (template) | 0.085 µs | 0.079 µs | ~1× | — |
 
 ### What the transformer cannot help with
 
-- **Pure engine API calls** — `CFrame.lookAt`, `CFrame.Angles`, `CFrame` multiplication all execute immediately in C++. `--!native` cannot speed up code that is already running natively. `cfLookAt` and `cfChain` show 1.0× for this reason.
-- **Single-access properties** — the cache pass only hoists when a property is read 2+ times in the same function. One read has nothing to eliminate.
+- **Pure engine API calls** — `CFrame.lookAt`, `CFrame.Angles`, `CFrame` multiplication execute immediately in C++. `--!native` cannot speed up code that is already running natively.
+- **Single-access properties** — the cache pass only hoists when a property is read 2+ times in the same function.
 - **String-heavy functions** — Luau string operations are not meaningfully accelerated by the native compiler.
 
 ---
@@ -316,8 +314,10 @@ Measured in Roblox Studio server context. 100,000 iterations per benchmark (10,0
 ## Development
 
 ```bash
-npm run build          # build the transformer
-npm run bench:rbxlx    # build both versions + produce bench/benchmark.rbxlx
+npm run build              # compile the transformer (tsc → dist/)
+npm run bench:build        # build the benchmark suite with transformer applied
+npm run bench:build:baseline  # build the baseline suite (no transformer)
+npm run bench:rbxlx        # produce bench/benchmark.rbxlx (both suites in one place)
 ```
 
-Open `bench/benchmark.rbxlx` in Roblox Studio and run the server. The optimized suite prints first, then the baseline suite, sequentially in the output window.
+Open `bench/benchmark.rbxlx` in Roblox Studio and run the server. The optimized suite prints first, then the baseline suite.

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 export interface PluginConfig {
     optimize?: boolean;
+    strict?: boolean;
     hoist?: boolean;
 }

package/dist/index.js

@@ -3,18 +3,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = default_1;
 const native_1 = require("./passes/native");
 const cache_1 = require("./passes/cache");
-const loops_1 = require("./passes/loops");
 const annotate_1 = require("./passes/annotate");
 function default_1(program, config = {}, { ts }) {
-    const { optimize = true, hoist = true } = config;
+    const { optimize = true, strict = true, hoist = true } = config;
     return (ctx) => (sourceFile) => {
         (0, annotate_1.annotatePass)(ts, program, sourceFile);
         let result = sourceFile;
         if (hoist)
             result = (0, cache_1.cachePass)(ts, program, ctx, result);
-        result = (0, loops_1.loopsPass)(ts, program, ctx, result);
-        if (optimize)
-            result = (0, native_1.nativePass)(ts, ctx, result);
+        if (optimize || strict)
+            result = (0, native_1.nativePass)(ts, ctx, result, optimize, strict);
         return result;
     };
 }