@tilua-types/luau 8.0.0 → 9.0.0

package/README.md

@@ -1,37 +1,67 @@
-# @tilua-types/luau
-
-Luau as a tilua type library.
-
-tilua itself knows Lua: its standard library is Lua's, and what the compiler
-writes runs on Lua 5.1 to 5.4, LuaJIT and Luau alike. This library is what
-makes a project Luau:
-
-- **Luau's additions, typed.** `buffer`, `bit32`, `utf8`, `string.split`,
-  `table.find`, `table.freeze`, `warn`, `debug.info` and the rest — added to
-  the standard library's own tables rather than replacing them.
-- **Luau's syntax in the output.** The compiler writes `a += b`, `continue`,
-  `if c then a else b`, `a // b` and `for _, v in t` as they are, where plain
-  Lua needs longer forms: shorter output, and the code Luau compiles fastest.
-  A bundle of several files loads the others with `require` by path.
-
-```bash
-npm i -D @tilua-types/luau
-```
-
-```json
-{ "types": ["luau"] }
-```
-
-[`@tilua-types/roblox`](../roblox) loads it: Roblox's Lua is Luau, so a
-Roblox project has both without naming this one.
-
-<!-- compatibility:start -->
-## Compatibility
-
-`@tilua-types/luau@8.0.0` works with these tilua packages. *Released with* is the
-version it was built and tested against.
-
-| Package | Range | Released with | |
-| --- | --- | --- | --- |
-| `@tilua/parser` | `^8.0.0` | 8.0.0 | peer |
-<!-- compatibility:end -->
+# @tilua-types/luau
+
+Luau as a tilua type library.
+
+tilua itself knows Lua: its standard library is Lua's, and what the compiler
+writes runs on Lua 5.1 to 5.4, LuaJIT and Luau alike. This library is what
+makes a project Luau:
+
+- **Luau's additions, typed.** `buffer`, `bit32`, `utf8`, `string.split`,
+  `table.find`, `table.freeze`, `warn`, `debug.info` and the rest — added to
+  the standard library's own tables rather than replacing them.
+- **Luau's syntax in the output.** The compiler writes `a += b`, `continue`,
+  `if c then a else b`, `a // b` and `for _, v in t` as they are, where plain
+  Lua needs longer forms: shorter output, and the code Luau compiles fastest.
+  A bundle of several files loads the others with `require` by path.
+- **Typed exports.** A bundle whose entry exports is cast to the entry's
+  exports, written as Luau types, so a script that `require`s it knows what
+  it got (see below).
+
+```bash
+npm i -D @tilua-types/luau
+```
+
+```json
+{ "types": ["luau"] }
+```
+
+[`@tilua-types/roblox`](../roblox) loads it: Roblox's Lua is Luau, so a
+Roblox project has both without naming this one.
+
+## Typed exports
+
+```lua
+export type Point = { x: number, y: number }
+export type Dog = { name: string, friend: (self: Dog) -> Dog, ClassObject: DogClass }
+type DogClass = { new: (name: string) -> Dog, name: "Dog", ParentClass: nil }
+return (G.require("src/main") :: any) :: { origin: () -> Point, Dog: DogClass, id: <T>(v: T) -> T }
+```
+
+- Every `export type` of the entry is written as one, so the requirer can
+  name it: `local p: Main.Point = Main.origin()`.
+- Any other named type the exports reach — a class, an interface — gets a
+  local alias, which is also how a type that reaches itself is written.
+- A class the host made (a Roblox `Part`, `Vector3`) is named as it is: its
+  Luau has that type already.
+- What Luau's types cannot say is written as near as they come: a tuple is a
+  table of its elements' union, a template literal type a `string`, and a
+  conditional or mapped type that was never resolved `any`. A `private`
+  member is left out.
+
+The cast goes through `any`, so it is never an error in the bundle itself.
+It is this library's option, on unless the config turns it off:
+
+```json
+{ "types": ["luau"], "typedExports": false }
+```
+
+<!-- compatibility:start -->
+## Compatibility
+
+`@tilua-types/luau@9.0.0` works with these tilua packages. *Released with* is the
+version it was built and tested against.
+
+| Package | Range | Released with | |
+| --- | --- | --- | --- |
+| `@tilua/parser` | `^9.0.0` | 9.0.0 | peer |
+<!-- compatibility:end -->

package/exports.mjs

@@ -0,0 +1,311 @@
+// @ts-check
+/**
+ * What the entry exports, written as a Luau type.
+ *
+ * A bundle that exports is a ModuleScript, and the script that `require`s it
+ * reads its type from what it returns. Lowered, that is `G.require(...)` — a
+ * table nothing types — so the bundle casts it on the way out:
+ *
+ *     export type Point = { x: number, y: number }
+ *     type DogClass = { new: (name: string) -> Dog, ... }
+ *     export type Dog = { name: string, friend: (self: Dog) -> Dog, ... }
+ *     return (G.require("src/main") :: any) :: { origin: () -> Point, Dog: DogClass }
+ *
+ * The cast goes through `any`, so it can never be an error in the bundle
+ * itself. Every `export type` of the entry is written as one, so a requirer
+ * can name it (`Main.Point`). Any other named type the exports reach — a
+ * class, an interface — gets a local alias, which is also what lets a type
+ * that reaches itself (`friend(): Dog`) be written at all. A class the host
+ * made (a Roblox `Part`) is named as it is: its Luau has that type already.
+ *
+ * It is the reader's view, not a proof: what Luau's types cannot say — a
+ * tuple, a conditional, a mapped type — is written as near as Luau comes,
+ * and as `any` where nothing comes near.
+ */
+import { isIdentifier, isLuauName, luauString } from "@tilua/parser"
+
+/** @typedef {import("@tilua/parser").Type} Type */
+/** @typedef {import("@tilua/parser").ModuleExports} ModuleExports */
+/**
+ * @typedef {object} Alias
+ * @property {string} name
+ * @property {Type} type
+ * @property {readonly string[]} params
+ * @property {string} shape  its property names, to tell two types of one name apart
+ * @property {string} [body]
+ * @property {boolean} [exported]
+ */
+
+/** How deep an unnamed type is written before the rest is `any`. */
+const MAX_DEPTH = 12
+
+/**
+ * The type of `exports`' table, and the aliases it names — or `undefined`
+ * when the module's exports are not known.
+ * @param {ModuleExports} exports
+ * @returns {{ declarations: string[], type: string } | undefined}
+ */
+export function typedExports(exports) {
+    if (exports.partial) return undefined
+    const writer = new TypeWriter()
+    // The module's own `export type`s first: they keep the names they have.
+    // `default` is the type of an `export default class`, which the class's
+    // own name already says.
+    const named = [...exports.types].filter(([name]) => isLuauName(name) && name !== "default")
+    for (const [name, exported] of named) writer.reserve(name, exported.type, exported.params)
+    /** @type {[string, Type][]} */
+    const fields = [...exports.values]
+    if (exports.default) fields.push(["default", exports.default])
+    const type = writer.table(fields.map(([name, type]) => ({ name, type, optional: false })), undefined, new Set(), new Set(), 0)
+    for (const [name, exported] of named) writer.define(name, exported.type, exported.params)
+    return { declarations: writer.declarations(), type }
+}
+
+class TypeWriter {
+    constructor() {
+        /** @type {Map<Type, Alias>} */
+        this.byType = new Map()
+        /** @type {Map<string, Alias>} */
+        this.byName = new Map()
+        /** Aliases by what the program called them, every one of that name.
+         *  @type {Map<string, Alias[]>} */
+        this.written = new Map()
+        /** @type {Alias[]} */
+        this.order = []
+    }
+
+    /** Claim `name` for `type` before anything is written, so that the
+     *  program's own name is the one it keeps.
+     *  @param {string} name @param {Type} type @param {readonly string[]} params */
+    reserve(name, type, params) {
+        this.add(name, name, type, params).exported = true
+    }
+
+    /** Write the body of an alias `reserve` claimed.
+     *  @param {string} name @param {Type} type @param {readonly string[]} params */
+    define(name, type, params) {
+        const alias = this.byName.get(name)
+        if (alias && alias.body === undefined) alias.body = this.write(type, new Set(params), new Set(), 0, true)
+    }
+
+    /** @returns {string[]} */
+    declarations() {
+        return this.order.filter(a => a.body !== undefined).map(a => {
+            const params = a.params.length ? `<${a.params.join(", ")}>` : ""
+            return `${a.exported ? "export " : ""}type ${a.name}${params} = ${a.body}`
+        })
+    }
+
+    /** @param {string} given @param {string} name @param {Type} type @param {readonly string[]} params */
+    add(given, name, type, params) {
+        /** @type {Alias} */
+        const alias = { name, type, params, shape: shapeOf(type) }
+        // Two names for one type: the first keeps it.
+        if (!this.byType.has(type)) this.byType.set(type, alias)
+        this.byName.set(name, alias)
+        const same = this.written.get(given) ?? []
+        same.push(alias)
+        this.written.set(given, same)
+        this.order.push(alias)
+        return alias
+    }
+
+    /** The alias that writes the named type `type` — the program's name for
+     *  it, or a fresh one where that is taken by a different type.
+     *  @param {string} given @param {Type} type @param {ReadonlySet<string>} scope */
+    named(given, type, scope) {
+        const known = [this.byType.get(type), ...(this.written.get(given) ?? [])]
+            .find(a => a !== undefined && a.params.length === 0 && (a.type === type || a.shape === shapeOf(type)))
+        if (known) return known.name
+        const base = luauTypeName(given)
+        let name = base
+        for (let n = 2; this.byName.has(name) || scope.has(name); n++) name = `${base}${n}`
+        const alias = this.add(given, name, type, [])
+        // Registered before it is written: a type that reaches itself names
+        // the alias on the way back instead of writing itself forever.
+        alias.body = this.write(type, new Set(), new Set(), 0, true)
+        return name
+    }
+
+    /**
+     * `type` in Luau. `scope` holds the type parameters that may be named
+     * here; `seen`, the unnamed types being written further up. `body` says
+     * this is the alias's own body, which is written out, not named.
+     * @param {Type} type @param {ReadonlySet<string>} scope @param {ReadonlySet<Type>} seen
+     * @param {number} depth @param {boolean} [body]
+     * @returns {string}
+     */
+    write(type, scope, seen, depth, body = false) {
+        // A type an alias already writes is named, not written again — even
+        // inside its own alias, which is how a type reaches itself.
+        const alias = body ? undefined : this.byType.get(type)
+        if (alias && alias.params.length === 0) return alias.name
+        if (depth > MAX_DEPTH || seen.has(type)) return "any"
+        const inner = new Set(seen).add(type)
+        /** @param {Type} t @param {ReadonlySet<string>} [s] */
+        const next = (t, s = scope) => this.write(t, s, inner, depth + 1)
+        switch (type.kind) {
+            case "any": return "any"
+            case "unknown": return "unknown"
+            case "never": return "never"
+            case "primitive":
+                if (type.name === "void") return "nil"
+                return type.name === "object" ? "any" : type.name
+            case "literal":
+                if (type.base === "string") return luauString(String(type.value))
+                return type.base === "boolean" ? String(type.value) : "number"
+            case "array": return `{ ${next(type.element)} }`
+            case "tuple": {
+                // A table of the elements: Luau has no type for each place.
+                const members = [...type.elements, ...(type.rest ? [type.rest] : [])]
+                return members.length ? `{ ${union(members.map(m => next(m)))} }` : "{}"
+            }
+            case "object": {
+                if (!body) {
+                    // `Box<number>`: an instance of a generic alias this file writes.
+                    const ref = type.nameRef
+                    const generic = ref && this.byName.get(ref.name)
+                    if (ref && generic && generic.params.length === ref.typeArguments.length) {
+                        return `${generic.name}<${ref.typeArguments.map(a => next(a)).join(", ")}>`
+                    }
+                    // A class the host made — a Roblox `Part` — is a type
+                    // its Luau already has, by the same name.
+                    if (type.class && !type.class.runtime && isLuauName(type.class.name)) {
+                        const args = type.class.typeArguments?.get(type.class.name)
+                        return args?.length ? `${type.class.name}<${args.map(a => next(a)).join(", ")}>` : type.class.name
+                    }
+                    if (type.name && !ref) return this.named(type.name, type, scope)
+                }
+                const properties = [...type.properties]
+                    // What only the class itself may read is not the requirer's.
+                    .filter(([, p]) => !p.private)
+                    .map(([name, p]) => ({ name, type: p.type, optional: p.optional }))
+                return this.table(properties, type.indexer, scope, inner, depth)
+            }
+            case "function": {
+                const generic = new Set([...scope, ...(type.typeParams ?? [])])
+                const params = type.params.map((p, i) => {
+                    const written = this.write(p.type, generic, inner, depth + 1)
+                    const shown = p.optional ? optional(written) : written
+                    // A method's receiver is Luau's `self`.
+                    const name = i === 0 && (p.name === "this" || p.name === "self") ? "self" : p.name
+                    return name && isLuauName(name) ? `${name}: ${shown}` : shown
+                })
+                if (type.varargs) {
+                    params.push(type.restIsWhole ? "...any" : `...${this.write(type.varargs, generic, inner, depth + 1)}`)
+                }
+                const generics = type.typeParams?.length ? `<${type.typeParams.join(", ")}>` : ""
+                // Nothing, where Luau says so: `-> ()`, not one `nil`.
+                const returns = type.returns.kind === "primitive" && (type.returns.name === "void" || type.returns.name === "nil")
+                    ? "()" : atom(this.write(type.returns, generic, inner, depth + 1))
+                return `${generics}(${params.join(", ")}) -> ${returns}`
+            }
+            case "typeParam":
+                if (scope.has(type.name)) return type.name
+                return type.constraint ? next(type.constraint) : "any"
+            case "union": {
+                const members = type.types.map(t => next(t))
+                const hasNil = type.types.some(t => t.kind === "primitive" && (t.name === "nil" || t.name === "void"))
+                const rest = members.filter(m => m !== "nil")
+                if (!hasNil) return union(rest)
+                if (!rest.length) return "nil"
+                return rest.length === 1 ? optional(rest[0]) : `${union(rest)} | nil`
+            }
+            case "intersection": {
+                const members = [...new Set(type.types.map(t => atom(next(t))))]
+                return members.includes("any") ? "any" : members.join(" & ")
+            }
+            case "genericRef": {
+                const generic = this.byName.get(type.name)
+                if (generic && generic.params.length === type.typeArguments.length && generic.params.length > 0) {
+                    return `${generic.name}<${type.typeArguments.map(a => next(a)).join(", ")}>`
+                }
+                if (scope.has(type.name) && !type.typeArguments.length) return type.name
+                const expanded = type.origin?.expand(type)
+                return expanded && expanded !== type ? next(expanded) : "any"
+            }
+            case "templateLiteral": return "string"
+            case "difference": return next(type.base)
+            default: return "any"
+        }
+    }
+
+    /**
+     * A table type: `{ name: T, ["not a name"]: U, [K]: V }`.
+     * @param {readonly { name: string, type: Type, optional: boolean }[]} properties
+     * @param {{ key: Type, value: Type } | undefined} indexer
+     * @param {ReadonlySet<string>} scope @param {ReadonlySet<Type>} seen @param {number} depth
+     */
+    table(properties, indexer, scope, seen, depth) {
+        const fields = properties.map(p => {
+            const written = this.write(p.type, scope, seen, depth + 1)
+            const key = isLuauName(p.name) ? p.name : `[${luauString(p.name)}]`
+            return `${key}: ${p.optional ? optional(written) : written}`
+        })
+        if (indexer) fields.push(`[${this.write(indexer.key, scope, seen, depth + 1)}]: ${this.write(indexer.value, scope, seen, depth + 1)}`)
+        return fields.length ? `{ ${fields.join(", ")} }` : "{}"
+    }
+}
+
+/** @param {readonly string[]} members */
+function union(members) {
+    const unique = [...new Set(members)]
+    if (unique.includes("any")) return "any"
+    // `true | false` is how the analyzer holds a `boolean`.
+    if (unique.includes("true") && unique.includes("false")) {
+        unique.splice(unique.indexOf("true"), 1, "boolean")
+        unique.splice(unique.indexOf("false"), 1)
+    }
+    return unique.length ? unique.map(atom).join(" | ") : "never"
+}
+
+/** `T?`, with `T` in parentheses where `?` would bind to less of it.
+ *  @param {string} written */
+function optional(written) {
+    if (written === "any" || written === "unknown" || written === "nil" || written.endsWith("?")) return written
+    if (written.endsWith(" | nil")) return written
+    return `${atom(written)}?`
+}
+
+/** `written` in parentheses where it is a function, a union or an
+ *  intersection: an operand of `|`, `&` or `?`, or a function's result.
+ *  @param {string} written */
+function atom(written) {
+    return isCompound(written) ? `(${written})` : written
+}
+
+/** Does `written` have `->`, `|` or `&` outside every bracket?
+ *  @param {string} written */
+function isCompound(written) {
+    let depth = 0
+    let quoted = false
+    for (let i = 0; i < written.length; i++) {
+        const c = written[i]
+        if (quoted) {
+            if (c === "\\") i++
+            else if (c === "\"") quoted = false
+            continue
+        }
+        if (c === "\"") quoted = true
+        else if (c === "(" || c === "{" || c === "<") depth++
+        else if (c === ")" || c === "}" || (c === ">" && written[i - 1] !== "-")) depth--
+        else if (depth === 0 && (c === "|" || c === "&" || (c === "-" && written[i + 1] === ">"))) return true
+    }
+    return false
+}
+
+/** A type's property names: two types the program gave one name are one
+ *  type only if they have the same members.
+ *  @param {Type} type */
+function shapeOf(type) {
+    return type.kind === "object" ? [...type.properties.keys()].sort().join(",") : type.kind
+}
+
+/** A name the program gave a type, as a Luau type name: `typeof Dog` — the
+ *  class table — is `DogClass`.
+ *  @param {string} given */
+function luauTypeName(given) {
+    const name = given.startsWith("typeof ") ? `${given.slice("typeof ".length)}Class` : given
+    const cleaned = name.replace(/[^A-Za-z0-9_]/g, "_")
+    return isIdentifier(cleaned) && isLuauName(cleaned) ? cleaned : `T_${cleaned}`
+}

package/lowering.mjs

@@ -10,7 +10,12 @@
  *     if c then a else b     rather than  a function called on the spot
  *     for _, v in t          rather than  ipairs(t), or a function doing what Luau does
  *     require("./chunk")     rather than  loadfile, which Luau has none of
+ *
+ * Luau has types, too: with `typedExports` (on unless the config turns it
+ * off), what the bundle's entry exports is cast to its type, so a script that
+ * `require`s the bundle knows what it got (see exports.mjs).
  */
+import { typedExports } from "./exports.mjs"
 
 /** @typedef {import("@tilua/parser").LoweringPlugin} LoweringPlugin */
 
@@ -26,6 +31,13 @@ const plugin = {
         "numberLiterals",
         "requireByPath",
     ],
+    entryExports({ value, exports, options }) {
+        if (options.typedExports === false) return undefined
+        const typed = typedExports(exports)
+        if (!typed) return undefined
+        // Through `any`, so the cast is never an error in the bundle itself.
+        return { statements: typed.declarations, value: `(${value} :: any) :: ${typed.type}` }
+    },
 }
 
 export default plugin

package/package.json

@@ -1,19 +1,27 @@
 {
   "name": "@tilua-types/luau",
-  "version": "8.0.0",
+  "version": "9.0.0",
   "description": "Luau as a tilua type library: what Luau adds to Lua 5.1 (buffer, bit32, string.split, ...), and Luau's syntax in the compiled output",
   "license": "ISC",
   "files": [
     "index.d.tilua",
     "lowering.mjs",
+    "exports.mjs",
     "README.md"
   ],
   "tilua": {
     "types": "index.d.tilua",
-    "lowering": "lowering.mjs"
+    "lowering": "lowering.mjs",
+    "options": {
+      "typedExports": {
+        "type": "boolean",
+        "default": true,
+        "description": "Cast what the bundle's entry exports to its Luau type, so a script that requires the bundle knows what it got."
+      }
+    }
   },
   "peerDependencies": {
-    "@tilua/parser": "^8.0.0"
+    "@tilua/parser": "^9.0.0"
   },
   "keywords": [
     "tilua",