@tilua-types/roblox 1.0.0 → 2.0.0

package/README.md

@@ -43,6 +43,31 @@ tree, down to `script.Parent`.
 Deprecated members are left out. Deprecated globals such as `wait` and
 `spawn` stay.
 
+## Errors in callbacks
+
+A bundle's entry runs under `xpcall`, so an uncaught error names the project's
+files, not lines of the bundle. A callback that Roblox runs later on its own
+thread is outside that `xpcall`. This package's lowering (`lowering.mjs`) wraps
+those callbacks in the same handler:
+
+- `signal:Connect(f)`, `signal:Once(f)`, `signal:ConnectParallel(f)`
+- `task.spawn`, `task.defer`, `task.delay`, including `const spawn = task.spawn`
+- `RunService:BindToRenderStep`, `game:BindToClose`,
+  `ContextActionService:BindAction` and `BindActionAtPriority`
+
+```
+main.tilua:5: attempt to index nil with 'Name'
+    at main.tilua:5 (touched)
+    at main.tilua:7
+```
+
+The error is still raised on the callback's thread, so the callback stops the
+same way it did before. A callback that runs synchronously (a `table.sort`
+comparator, `names:map(f)`) is not wrapped, because it is already inside its
+caller's `xpcall`. `coroutine` is not wrapped either: `coroutine.resume`
+returning `false, err` is part of how it behaves. Outside a bundle, nothing is
+wrapped.
+
 ## Where it comes from
 
 `index.d.tilua` is generated. Don't edit it by hand; change

package/lowering.mjs

@@ -0,0 +1,84 @@
+// @ts-check
+/**
+ * What tilua lowers for Roblox: callbacks that Roblox runs later, on a thread
+ * of their own.
+ *
+ * The entry of a bundle runs under `xpcall`, which is what reports an error
+ * in the project's files instead of in the bundle's lines. A callback given
+ * to `task.spawn` or to `signal:Connect` is not under it when it runs, so its
+ * callback is wrapped in the same handler first (see runtime/roblox.luau):
+ *
+ *     part.Touched:Connect(onTouched)   ->  tilua_roblox.Connect(part.Touched, onTouched)
+ *     task.spawn(work, 1)               ->  tilua_roblox.task.spawn(work, 1)
+ *
+ * Only where Roblox starts a thread. A callback run synchronously — a
+ * `table.sort` comparator, `names:map(f)` — has its caller's `xpcall` already,
+ * and `coroutine` is left alone: `coroutine.resume` answering `false, err` is
+ * part of what it promises.
+ *
+ * `print`, `error` and the console come from `@tilua-types/lua`, which this
+ * package depends on.
+ */
+import { readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+/** @typedef {import("@tilua/parser").LoweringPlugin} LoweringPlugin */
+/** @typedef {import("@tilua/parser").Type} Type */
+
+const here = dirname(fileURLToPath(import.meta.url))
+const roblox = readFileSync(join(here, "runtime", "roblox.luau"), "utf8")
+
+const SIGNAL_METHODS = new Set(["Connect", "Once", "ConnectParallel"])
+
+/** A service's methods that keep a callback, by the class that has them. */
+const SERVICE_METHODS = new Map([
+    ["BindToRenderStep", "RunService"],
+    ["BindToClose", "DataModel"],
+    ["BindAction", "ContextActionService"],
+    ["BindActionAtPriority", "ContextActionService"],
+])
+
+/** The members of a type that may be nil: a check the analyzer asked for
+ *  elsewhere, not a reason to lower differently here.
+ *  @type {(type: Type | undefined) => Type[]} */
+function parts(type) {
+    if (!type) return []
+    if (type.kind !== "union") return [type]
+    return type.types.filter(m => !(m.kind === "primitive" && m.name === "nil"))
+}
+
+/** `RBXScriptSignal<T...>` is structural once it is resolved: an object that
+ *  can be connected to and waited on.
+ *  @type {(type: Type | undefined) => boolean} */
+function isSignal(type) {
+    const members = parts(type)
+    return members.length > 0 && members.every(m =>
+        m.kind === "object" && m.properties.has("Connect") && m.properties.has("Once") && m.properties.has("Wait"))
+}
+
+/** @type {(type: Type | undefined, className: string) => boolean} */
+function isInstanceOf(type, className) {
+    const members = parts(type)
+    return members.length > 0 && members.every(m =>
+        m.kind === "object" && m.class !== undefined && m.class.ancestors.includes(className))
+}
+
+/** @type {LoweringPlugin} */
+const plugin = {
+    runtime: { roblox },
+
+    methodCall({ method, receiver, use }) {
+        if (SIGNAL_METHODS.has(method) && isSignal(receiver)) return { callee: `${use("roblox")}.${method}` }
+        const service = SERVICE_METHODS.get(method)
+        if (service !== undefined && isInstanceOf(receiver, service)) return { callee: `${use("roblox")}.${method}` }
+        return undefined
+    },
+
+    globalValue({ name, use }) {
+        if (name === "task") return `${use("roblox")}.task`
+        return undefined
+    },
+}
+
+export default plugin

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "@tilua-types/roblox",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Luau and the whole Roblox API as tilua types: every class, enum, data type, service and global",
   "license": "ISC",
   "files": [
     "index.d.tilua",
+    "lowering.mjs",
+    "runtime",
     "README.md",
     "THIRD_PARTY_NOTICES.md"
   ],
   "tilua": {
-    "types": "index.d.tilua"
+    "types": "index.d.tilua",
+    "lowering": "lowering.mjs"
   },
   "dependencies": {
-    "@tilua-types/lua": "^1.0.0"
+    "@tilua-types/lua": "^2.0.0"
   },
   "keywords": [
     "tilua",

package/runtime/roblox.luau

@@ -0,0 +1,77 @@
+-- Callbacks Roblox runs on a thread of their own, reported in the project's
+-- files.
+--
+-- A bundle's entry runs under `xpcall`, so an error nothing caught names the
+-- file and line the author wrote. A callback handed to `task.spawn` or to
+-- `signal:Connect` runs later, on a new thread, where that `xpcall` is not on
+-- the stack: its errors would name lines of the bundle. `guard` gives such a
+-- callback the same handler — `__FAIL__`, the bundle's own — and raises what
+-- it returns on the callback's thread, where Roblox reports it as before.
+--
+-- The error is raised again, never swallowed: code that relied on it
+-- stopping the callback still sees it stop. Outside a bundle there is nothing
+-- to map, and callbacks are passed through untouched.
+
+local __NAME__ = {}
+local fail = __FAIL__
+
+local function guard(callback)
+	if type(callback) ~= "function" or fail == nil then
+		return callback
+	end
+	return function(...)
+		local results = table.pack(xpcall(callback, fail, ...))
+		if not results[1] then
+			error(results[2], 0)
+		end
+		return table.unpack(results, 2, results.n)
+	end
+end
+
+__NAME__.guard = guard
+
+-- `signal:Connect(f)` and its siblings.
+function __NAME__.Connect(signal, callback)
+	return signal:Connect(guard(callback))
+end
+
+function __NAME__.Once(signal, callback)
+	return signal:Once(guard(callback))
+end
+
+function __NAME__.ConnectParallel(signal, callback)
+	return signal:ConnectParallel(guard(callback))
+end
+
+-- Services that keep a callback and run it later.
+function __NAME__.BindToRenderStep(service, name, priority, callback)
+	return service:BindToRenderStep(name, priority, guard(callback))
+end
+
+function __NAME__.BindToClose(game, callback)
+	return game:BindToClose(guard(callback))
+end
+
+function __NAME__.BindAction(service, name, callback, ...)
+	return service:BindAction(name, guard(callback), ...)
+end
+
+function __NAME__.BindActionAtPriority(service, name, callback, ...)
+	return service:BindActionAtPriority(name, guard(callback), ...)
+end
+
+-- `task`, with the functions that start a thread guarding what they start.
+-- A thread passed instead of a function is left as it is. Everything else is
+-- `task`'s own. Standing in for the global, rather than rewriting calls,
+-- covers `local spawn = task.spawn` too.
+__NAME__.task = setmetatable({
+	spawn = function(target, ...)
+		return task.spawn(guard(target), ...)
+	end,
+	defer = function(target, ...)
+		return task.defer(guard(target), ...)
+	end,
+	delay = function(duration, target, ...)
+		return task.delay(duration, guard(target), ...)
+	end,
+}, { __index = task })