@tilua-types/roblox 4.1.0 → 5.0.0

package/README.md

@@ -1,7 +1,7 @@
 # @tilua-types/roblox
 
 Luau and the whole Roblox API as tilua types: every class (921 of them), enum
-(633), data type, service and global, plus what Luau adds to Lua — `typeof`,
+(633), data type, service and global, plus what Luau adds to Lua —
 `buffer`, `bit32`, `utf8`, `table.create`, `string.split`, `math.clamp`, ...
 
 Luau is Roblox's language, so the two ship together. Underneath is
@@ -27,7 +27,8 @@ tree, down to `script.Parent`.
   `declare class` (`Part extends FormFactorPart extends BasePart ...`). A
   `Part` passes wherever a `BasePart` or `Instance` is expected, but a
   `Folder` does not pass as a `Part`, and a table never passes as an
-  `Instance`. `typeof(instance)` is `"Instance"`.
+  `Instance`. `typeof instance` is `"Instance"`: `TypeofNames` tells the
+  language's `typeof` what each Roblox value answers.
 - **Events with typed arguments.** In `Players.PlayerAdded:Connect(function(player) ... end)`,
   `player` is a `Player`. Callbacks assigned to a property, such as
   `remote.OnServerInvoke = function(player, ...)`, are typed the same way.

package/index.d.tilua

@@ -11,13 +11,13 @@
 --
 -- Every Roblox type is a `declare class`: nominal, the way the engine sees it.
 -- A `Part` is an `Instance` because it extends one, and a table is never a
--- `Part`. Classes are not tables, so `typeof(part)` is "Instance".
+-- `Part`. Classes are not tables, so `typeof part` is "Instance".
 --
 -- `inst:IsA("Model")`, `game:GetService("Players")` and `Instance.new("Part")`
 -- are generic signatures over the maps at the end of this file: `K` infers the
 -- string literal that was passed, and the map gives back its class.
 --
--- The file opens with what Luau adds to Lua 5.1 (`typeof`, `buffer`, `bit32`,
+-- The file opens with what Luau adds to Lua 5.1 (`buffer`, `bit32`,
 -- ...), copied from scripts/luau.d.tilua — Luau is Roblox's, so they ship
 -- together. The Lua 5.1 standard library underneath is `@tilua-types/lua`.
 
@@ -32,28 +32,6 @@
 --
 -- Edit this file, then regenerate the Roblox definitions.
 
--- ============================================================
--- `typeof()`
--- ------------------------------------------------------------
--- Luau's own: `type()`'s answers plus the Roblox data types further down this
--- file, which it reports by name rather than as `userdata`. Narrowing works
--- exactly as it does for `type()` — see `@tilua-types/lua` for how the overloads
--- drive it.
--- ============================================================
-
-declare function typeof(value: nil): "nil"
-declare function typeof(value: boolean): "boolean"
-declare function typeof(value: number): "number"
-declare function typeof(value: string): "string"
-declare function typeof(value: thread): "thread"
-declare function typeof(value: buffer): "buffer"
-declare function typeof(value: (...args: unknown[]) => unknown): "function"
-declare function typeof(value: { [unknown]: unknown }): "table"
-declare function typeof<T>(value: T): string
-
--- Luau's `type()` knows one answer Lua's does not.
-declare function type(value: buffer): "buffer"
-
 -- ============================================================
 -- Base library
 -- ============================================================
@@ -66,6 +44,7 @@ declare debug: {
     info: (...args: unknown[]) => unknown,
     profilebegin: (label: string) => nil,
     profileend: () => nil,
+    getmemorycategory: () => string,
     setmemorycategory: (tag: string) => nil,
     resetmemorycategory: () => nil,
     dumpcodesize: () => nil,
@@ -99,6 +78,11 @@ declare math: {
     isnan: (n: number) => boolean,
     isinf: (n: number) => boolean,
     isfinite: (n: number) => boolean,
+    nan: number,
+    e: number,
+    phi: number,
+    sqrt2: number,
+    tau: number,
 }
 
 declare table: {
@@ -8679,7 +8663,7 @@ declare script: LuaSourceContainer
 declare plugin: Plugin
 declare game: DataModel
 declare workspace: Workspace
-declare shared: any
+declare shared: { [string]: unknown }
 declare task: { synchronize: () => nil, desynchronize: () => nil, defer: <A extends unknown[], R>(threadOrFunction: thread | ((...args: A) => R), ...args: A) => thread, spawn: <A extends unknown[], R>(threadOrFunction: thread | ((...args: A) => R), ...args: A) => thread, delay: <A extends unknown[], R>(duration?: number, threadOrFunction: thread | ((...args: A) => R), ...args: A) => thread, wait: (duration?: number) => number, cancel: (thread: thread) => nil }
 type NotificationButton = { Text: string, ButtonType: Enum.NotificationButtonType, OnActivated: () => any }
 type NotificationInfo = { Title?: string, Text?: string, Icon?: string, Buttons?: NotificationButton[], OnDisplay?: () => any, OnDismiss?: () => any }
@@ -8939,7 +8923,7 @@ declare class Instance extends Object {
     UniqueId: UniqueId,
     AddTag: (self: Instance, tag: string) => nil,
     ClearAllChildren: (self: Instance) => nil,
-    Clone: (self: Instance) => Instance,
+    Clone: <T extends Instance>(self: T) => T,
     Destroy: (self: Instance) => nil,
     FindFirstAncestor: <T = Instance>(self: Instance, name: string) => T | nil,
     FindFirstAncestorOfClass: <K extends keyof ClassMap>(self: Instance, className: K) => ClassMap[K] | nil,
@@ -19811,54 +19795,56 @@ type CreatableClassMap = {
     WrapTextureTransfer: WrapTextureTransfer,
 }
 
--- `type()` is "userdata" for every Roblox type; `typeof()` names the data
--- type, or says "Instance", "EnumItem", ... These add to the overloads in
--- the Luau layer above, and a class is never a table, so none of them is
--- "table".
-declare function type(value: Axes | BrickColor | CFrame | CatalogSearchParams | Color3 | ColorSequence | ColorSequenceKeypoint | Content | DateTime | DockWidgetPluginGuiInfo | Faces | FloatCurveKey | Font | InstanceHandle | NumberRange | NumberSequence | NumberSequenceKeypoint | OverlapParams | Path2DControlPoint | PathWaypoint | PhysicalProperties | RBXScriptConnection | Random | Ray | RaycastParams | Rect | Region3 | Region3int16 | RotationCurveKey | Secret | SecurityCapabilities | SharedTable | TweenInfo | UDim | UDim2 | User | ValueCurveKey | Vector2 | Vector2int16 | Vector3 | Vector3int16 | Object | EnumItem | Enum | Enums): "userdata"
-declare function typeof(value: Axes): "Axes"
-declare function typeof(value: BrickColor): "BrickColor"
-declare function typeof(value: CFrame): "CFrame"
-declare function typeof(value: CatalogSearchParams): "CatalogSearchParams"
-declare function typeof(value: Color3): "Color3"
-declare function typeof(value: ColorSequence): "ColorSequence"
-declare function typeof(value: ColorSequenceKeypoint): "ColorSequenceKeypoint"
-declare function typeof(value: Content): "Content"
-declare function typeof(value: DateTime): "DateTime"
-declare function typeof(value: DockWidgetPluginGuiInfo): "DockWidgetPluginGuiInfo"
-declare function typeof(value: Faces): "Faces"
-declare function typeof(value: FloatCurveKey): "FloatCurveKey"
-declare function typeof(value: Font): "Font"
-declare function typeof(value: InstanceHandle): "InstanceHandle"
-declare function typeof(value: NumberRange): "NumberRange"
-declare function typeof(value: NumberSequence): "NumberSequence"
-declare function typeof(value: NumberSequenceKeypoint): "NumberSequenceKeypoint"
-declare function typeof(value: OverlapParams): "OverlapParams"
-declare function typeof(value: Path2DControlPoint): "Path2DControlPoint"
-declare function typeof(value: PathWaypoint): "PathWaypoint"
-declare function typeof(value: PhysicalProperties): "PhysicalProperties"
-declare function typeof(value: RBXScriptConnection): "RBXScriptConnection"
-declare function typeof(value: Random): "Random"
-declare function typeof(value: Ray): "Ray"
-declare function typeof(value: RaycastParams): "RaycastParams"
-declare function typeof(value: Rect): "Rect"
-declare function typeof(value: Region3): "Region3"
-declare function typeof(value: Region3int16): "Region3int16"
-declare function typeof(value: RotationCurveKey): "RotationCurveKey"
-declare function typeof(value: Secret): "Secret"
-declare function typeof(value: SecurityCapabilities): "SecurityCapabilities"
-declare function typeof(value: SharedTable): "SharedTable"
-declare function typeof(value: TweenInfo): "TweenInfo"
-declare function typeof(value: UDim): "UDim"
-declare function typeof(value: UDim2): "UDim2"
-declare function typeof(value: User): "User"
-declare function typeof(value: ValueCurveKey): "ValueCurveKey"
-declare function typeof(value: Vector2): "Vector2"
-declare function typeof(value: Vector2int16): "Vector2int16"
-declare function typeof(value: Vector3): "Vector3"
-declare function typeof(value: Vector3int16): "Vector3int16"
-declare function typeof(value: Instance): "Instance"
-declare function typeof(value: Object): "Object"
-declare function typeof(value: EnumItem): "EnumItem"
-declare function typeof(value: Enum): "Enum"
-declare function typeof(value: Enums): "Enums"
+-- What `typeof` answers for a Roblox value: the data type's own name, or
+-- "Instance", "EnumItem", ... Each property is the name `typeof` gives a
+-- value of the property's type, and a value several of them fit — a `Part`
+-- is an `Instance` and an `Object` — is the first one's. A class is never a
+-- table, so none of these is an "array" or an "object".
+type TypeofNames = {
+    Axes: Axes,
+    BrickColor: BrickColor,
+    CFrame: CFrame,
+    CatalogSearchParams: CatalogSearchParams,
+    Color3: Color3,
+    ColorSequence: ColorSequence,
+    ColorSequenceKeypoint: ColorSequenceKeypoint,
+    Content: Content,
+    DateTime: DateTime,
+    DockWidgetPluginGuiInfo: DockWidgetPluginGuiInfo,
+    Faces: Faces,
+    FloatCurveKey: FloatCurveKey,
+    Font: Font,
+    InstanceHandle: InstanceHandle,
+    NumberRange: NumberRange,
+    NumberSequence: NumberSequence,
+    NumberSequenceKeypoint: NumberSequenceKeypoint,
+    OverlapParams: OverlapParams,
+    Path2DControlPoint: Path2DControlPoint,
+    PathWaypoint: PathWaypoint,
+    PhysicalProperties: PhysicalProperties,
+    RBXScriptConnection: RBXScriptConnection,
+    Random: Random,
+    Ray: Ray,
+    RaycastParams: RaycastParams,
+    Rect: Rect,
+    Region3: Region3,
+    Region3int16: Region3int16,
+    RotationCurveKey: RotationCurveKey,
+    Secret: Secret,
+    SecurityCapabilities: SecurityCapabilities,
+    SharedTable: SharedTable,
+    TweenInfo: TweenInfo,
+    UDim: UDim,
+    UDim2: UDim2,
+    User: User,
+    ValueCurveKey: ValueCurveKey,
+    Vector2: Vector2,
+    Vector2int16: Vector2int16,
+    Vector3: Vector3,
+    Vector3int16: Vector3int16,
+    Instance: Instance,
+    Object: Object,
+    EnumItem: EnumItem,
+    Enum: Enum,
+    Enums: Enums,
+}

package/lowering.mjs

@@ -26,9 +26,9 @@
 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 */
-/** @typedef {import("@tilua/parser").Type} Type */
 
 const here = dirname(fileURLToPath(import.meta.url))
 const roblox = readFileSync(join(here, "runtime", "roblox.luau"), "utf8")
@@ -43,58 +43,23 @@ const SERVICE_METHODS = new Map([
     ["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"))
-}
+ *  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"])
 
-/** Does every signature of `receiver`'s `method` return a tuple — several
- *  values, as tilua has them in one array?
- *  @type {(receiver: Type | undefined, method: string) => boolean} */
-function returnsSeveral(receiver, method) {
-    const members = parts(receiver)
-    if (!members.length) return false
-    return members.every(m => {
-        if (m.kind !== "object") return false
-        const found = m.properties.get(method)?.type
-        const signatures = !found ? [] : found.kind === "intersection" ? found.types : [found]
-        return signatures.length > 0 && signatures.every(f => f.kind === "function" && f.returns.kind === "tuple")
-    })
-}
-
-/** @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}` }
+        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 (returnsSeveral(receiver, method)) {
-            return { callee: `${use("roblox")}.values`, prepend: [JSON.stringify(method)] }
+        if (returnsTuple(receiver, method)) {
+            return { callee: `${use("roblox")}.values`, prepend: [luauString(method)] }
         }
         return undefined
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tilua-types/roblox",
-  "version": "4.1.0",
+  "version": "5.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"
   },
+  "peerDependencies": {
+    "@tilua/parser": "^3.1.0"
+  },
   "dependencies": {
-    "@tilua-types/lua": "^4.0.0"
+    "@tilua-types/lua": "^5.0.0"
   },
   "keywords": [
     "tilua",