@tilua-types/roblox 7.1.0 → 9.0.0

package/lowering.mjs

@@ -1,79 +1,88 @@
-// @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 where Luau answers several values, tilua has one — an array. A method
- * whose type returns a tuple (`workspace:FindPartOnRay(ray)`, `signal:Wait()`)
- * is called through the runtime's `values`, which gathers them, and so are the
- * Luau globals that answer several (`string.unpack`, `utf8.codepoint`,
- * `coroutine.close`).
- *
- * `print`, `error` and the console are the compiler's own: Lua's standard
- * library is built into tilua.
- */
-import { readFileSync } from "node:fs"
-import { dirname, join } from "node:path"
-import { fileURLToPath } from "node:url"
-import { hasMembers, isInstanceOf, luauString, returnsTuple } from "@tilua/parser"
-
-/** @typedef {import("@tilua/parser").LoweringPlugin} LoweringPlugin */
-
-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"],
-])
-
-/** `RBXScriptSignal<T...>` is structural once it is resolved: an object that
- *  can be connected to and waited on. */
-const SIGNAL_MEMBERS = ["Connect", "Once", "Wait"]
-
-/** Luau globals answering several values, which the runtime gathers. */
-const GATHERED_GLOBALS = new Set(["string.unpack", "coroutine.close", "utf8.codepoint", "utf8.codes", "utf8.graphemes"])
-
-/** @type {LoweringPlugin} */
-const plugin = {
-    runtime: { roblox },
-
-    methodCall({ method, receiver, use }) {
-        if (SIGNAL_METHODS.has(method) && hasMembers(receiver, SIGNAL_MEMBERS)) return { callee: `${use("roblox")}.${method}` }
-        const service = SERVICE_METHODS.get(method)
-        if (service !== undefined && isInstanceOf(receiver, service)) return { callee: `${use("roblox")}.${method}` }
-        if (returnsTuple(receiver, method)) {
-            return { callee: `${use("roblox")}.values`, prepend: [luauString(method)] }
-        }
-        return undefined
-    },
-
-    globalCall({ name, use }) {
-        if (GATHERED_GLOBALS.has(name)) return { callee: `${use("roblox")}.globals.${name.replace(".", "_")}` }
-        return undefined
-    },
-
-    globalValue({ name, use }) {
-        if (name === "task") return `${use("roblox")}.task`
-        if (GATHERED_GLOBALS.has(name)) return `${use("roblox")}.globals.${name.replace(".", "_")}`
-        return undefined
-    },
-}
-
-export default plugin
+// @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.
+ *
+ * `HttpService:JSONEncode(value)` is the language's JSON (the runtime's
+ * `JSONEncode`), which knows `[]` from `{}` where Roblox's sees two empty
+ * tables; `JSONDecode` reads back the same.
+ *
+ * And where Luau answers several values, tilua has one — an array. A method
+ * whose type returns a tuple (`workspace:FindPartOnRay(ray)`, `signal:Wait()`)
+ * is called through the runtime's `values`, which gathers them, and so are the
+ * Luau globals that answer several (`string.unpack`, `utf8.codepoint`,
+ * `coroutine.close`).
+ *
+ * `print`, `error` and the console are the compiler's own: Lua's standard
+ * library is built into tilua.
+ */
+import { readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { hasMembers, isInstanceOf, luauString, returnsTuple } from "@tilua/parser"
+
+/** @typedef {import("@tilua/parser").LoweringPlugin} LoweringPlugin */
+
+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"],
+])
+
+/** HttpService's JSON, which the runtime writes and reads as tilua's values
+ *  are: `[]` an array and `{}` an object, empty or not. */
+const JSON_METHODS = new Set(["JSONEncode", "JSONDecode", "JSONEncodeAsync", "JSONDecodeAsync"])
+
+/** `RBXScriptSignal<T...>` is structural once it is resolved: an object that
+ *  can be connected to and waited on. */
+const SIGNAL_MEMBERS = ["Connect", "Once", "Wait"]
+
+/** Luau globals answering several values, which the runtime gathers. */
+const GATHERED_GLOBALS = new Set(["string.unpack", "coroutine.close", "utf8.codepoint", "utf8.codes", "utf8.graphemes"])
+
+/** @type {LoweringPlugin} */
+const plugin = {
+    runtime: { roblox },
+
+    methodCall({ method, receiver, use }) {
+        if (SIGNAL_METHODS.has(method) && hasMembers(receiver, SIGNAL_MEMBERS)) return { callee: `${use("roblox")}.${method}` }
+        if (JSON_METHODS.has(method) && isInstanceOf(receiver, "HttpService")) return { callee: `${use("roblox")}.${method}` }
+        const service = SERVICE_METHODS.get(method)
+        if (service !== undefined && isInstanceOf(receiver, service)) return { callee: `${use("roblox")}.${method}` }
+        if (returnsTuple(receiver, method)) {
+            return { callee: `${use("roblox")}.values`, prepend: [luauString(method)] }
+        }
+        return undefined
+    },
+
+    globalCall({ name, use }) {
+        if (GATHERED_GLOBALS.has(name)) return { callee: `${use("roblox")}.globals.${name.replace(".", "_")}` }
+        return undefined
+    },
+
+    globalValue({ name, use }) {
+        if (name === "task") return `${use("roblox")}.task`
+        if (GATHERED_GLOBALS.has(name)) return `${use("roblox")}.globals.${name.replace(".", "_")}`
+        return undefined
+    },
+}
+
+export default plugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tilua-types/roblox",
-  "version": "7.1.0",
+  "version": "9.0.0",
   "description": "Luau and the whole Roblox API as tilua types: every class, enum, data type, service and global",
   "license": "ISC",
   "files": [
@@ -14,8 +14,11 @@
     "types": "index.d.tilua",
     "lowering": "lowering.mjs"
   },
+  "dependencies": {
+    "@tilua-types/luau": "^8.0.0"
+  },
   "peerDependencies": {
-    "@tilua/parser": "^6.0.0"
+    "@tilua/parser": "^8.0.0"
   },
   "keywords": [
     "tilua",

package/runtime/roblox.luau

@@ -1,124 +1,139 @@
--- 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 })
-
--- Where Luau answers several values, tilua has one: an array. A Roblox method
--- whose type says it returns several — `workspace:FindPartOnRay(ray)`,
--- `signal:Wait()`, `cf:ToOrientation()` — is called through this, which
--- hands its values back as that array.
-function __NAME__.values(name, receiver, ...)
-	return { receiver[name](receiver, ...) }
-end
-
--- The same for Luau's own globals that answer several values.
-__NAME__.globals = {
-	string_unpack = function(...)
-		return { string.unpack(...) }
-	end,
-	coroutine_close = function(co)
-		return { coroutine.close(co) }
-	end,
-	utf8_codepoint = function(...)
-		return { utf8.codepoint(...) }
-	end,
-	-- An iteration — `{ step, state, first }` — whose steps answer one
-	-- `{ position, code }` each, as a loop walks them.
-	utf8_codes = function(s)
-		local step, state, first = utf8.codes(s)
-		return {
-			function(_, previous)
-				local position, code = step(state, previous ~= nil and previous[1] or first)
-				if position == nil then
-					return nil
-				end
-				return { position, code }
-			end,
-			s,
-			nil,
-		}
-	end,
-	utf8_graphemes = function(s, i, j)
-		local step = utf8.graphemes(s, i, j)
-		return function()
-			local first, last = step()
-			if first == nil then
-				return nil
-			end
-			return { first, last }
-		end
-	end,
-}
+-- 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 })
+
+-- HttpService's JSON, as tilua's values have it: `[]` is an array and `{}`
+-- an object, empty or not — `JSONEncode` alone writes every empty table as
+-- `[]` — and what `JSONDecode` reads back is the same. `__JSON__` is the
+-- language's; the Async ones yield nothing here, the work being the same.
+function __NAME__.JSONEncode(_, value)
+	return __JSON__.encode(value)
+end
+
+function __NAME__.JSONDecode(_, text)
+	return __JSON__.decode(text)
+end
+
+__NAME__.JSONEncodeAsync = __NAME__.JSONEncode
+__NAME__.JSONDecodeAsync = __NAME__.JSONDecode
+
+-- Where Luau answers several values, tilua has one: an array. A Roblox method
+-- whose type says it returns several — `workspace:FindPartOnRay(ray)`,
+-- `signal:Wait()`, `cf:ToOrientation()` — is called through this, which
+-- hands its values back as that array.
+function __NAME__.values(name, receiver, ...)
+	return { receiver[name](receiver, ...) }
+end
+
+-- The same for Luau's own globals that answer several values.
+__NAME__.globals = {
+	string_unpack = function(...)
+		return { string.unpack(...) }
+	end,
+	coroutine_close = function(co)
+		return { coroutine.close(co) }
+	end,
+	utf8_codepoint = function(...)
+		return { utf8.codepoint(...) }
+	end,
+	-- An iteration — `{ step, state, first }` — whose steps answer one
+	-- `{ position, code }` each, as a loop walks them.
+	utf8_codes = function(s)
+		local step, state, first = utf8.codes(s)
+		return {
+			function(_, previous)
+				local position, code = step(state, previous ~= nil and previous[1] or first)
+				if position == nil then
+					return nil
+				end
+				return { position, code }
+			end,
+			s,
+			nil,
+		}
+	end,
+	utf8_graphemes = function(s, i, j)
+		local step = utf8.graphemes(s, i, j)
+		return function()
+			local first, last = step()
+			if first == nil then
+				return nil
+			end
+			return { first, last }
+		end
+	end,
+}