@tilua/parser 3.0.1 → 4.0.0

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(index_exports, {
   CONFIG_FILE_NAMES: () => CONFIG_FILE_NAMES,
   Keywords: () => Keywords,
   LANGUAGE_GLOBALS: () => LANGUAGE_GLOBALS,
+  LUAU_KEYWORDS: () => LUAU_KEYWORDS,
   LexError: () => LexError,
   Operators: () => Operators,
   PRELUDE_SOURCE: () => PRELUDE_SOURCE,
@@ -45,20 +46,27 @@ __export(index_exports, {
   difference: () => difference,
   directivesOf: () => directivesOf,
   equalTypes: () => equalTypes,
+  escapeLuauString: () => escapeLuauString,
   falsyType: () => falsyType,
   findConfig: () => findConfig,
   fn: () => fn,
   formatType: () => formatType,
   getBinding: () => getBinding,
+  hasMembers: () => hasMembers,
   intersection: () => intersection,
   isAssignable: () => isAssignable,
   isClassType: () => isClassType,
+  isFunctionType: () => isFunctionType,
   isGlobal: () => isGlobal,
+  isIdentifier: () => isIdentifier,
+  isInstanceOf: () => isInstanceOf,
+  isLuauName: () => isLuauName,
   isPossiblyFalsy: () => isPossiblyFalsy,
   isPossiblyTruthy: () => isPossiblyTruthy,
   isUnassignedGlobal: () => isUnassignedGlobal,
   literal: () => literal,
   loadConfig: () => loadConfig,
+  luauString: () => luauString,
   matchInfer: () => matchInfer,
   moduleCandidates: () => moduleCandidates,
   moduleExports: () => moduleExports,
@@ -81,6 +89,7 @@ __export(index_exports, {
   readDirectives: () => readDirectives,
   resolveModulePath: () => resolveModulePath,
   resolveTypeLibraries: () => resolveTypeLibraries,
+  returnsTuple: () => returnsTuple,
   setAliasExpander: () => setAliasExpander,
   setDeferredBound: () => setDeferredBound,
   sourceMapTypes: () => sourceMapTypes,
@@ -99,7 +108,8 @@ __export(index_exports, {
   unknownType: () => unknownType,
   widen: () => widen,
   withAliasName: () => withAliasName,
-  withoutAliasName: () => withoutAliasName
+  withoutAliasName: () => withoutAliasName,
+  withoutNil: () => withoutNil2
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -701,6 +711,8 @@ var UNUSED_EXPECT_ERROR = "Unused '@tilua-expect-error' directive";
 
 // src/ast/builders.ts
 var NO_DOTS = "tilua has no bare '...': take a rest parameter, '...args: T[]', or 'scriptArgs' for the script's own";
+var NO_MEMBER_NAME = "Expected a name after '.'";
+var NO_TYPEOF_CALL = "'typeof' is an operator, not a function: write 'typeof v'";
 var ACCESSIBILITIES = /* @__PURE__ */ new Set(["public", "private", "protected"]);
 var CLASS_MODIFIERS = /* @__PURE__ */ new Set([...ACCESSIBILITIES, "static", "abstract", "override", "readonly"]);
 function bindThis(func, at) {
@@ -708,7 +720,7 @@ function bindThis(func, at) {
   func.isMethod = true;
 }
 function bindThisParam(params, at) {
-  params.unshift({ type: "FunctionParameter", name: "this", ...spanFrom(at, at) });
+  params.unshift({ type: "FunctionParameter", name: "this", implicit: true, ...spanFrom(at, at) });
 }
 var ParseError = class extends Error {
   constructor(message, line, column) {
@@ -1765,7 +1777,7 @@ var Parser = class {
         };
       }
       if (isMethod) {
-        func.params.unshift({ type: "FunctionParameter", name: "self", ...spanFrom(target, target) });
+        func.params.unshift({ type: "FunctionParameter", name: "self", implicit: true, ...spanFrom(target, target) });
         func.isMethod = true;
       }
       return {
@@ -1959,47 +1971,7 @@ var Parser = class {
     const isStatic = modifiers.has("static");
     if (this.checkKeyword("function")) {
       this.advance();
-      const memberName = this.parseIdentifier();
-      if (modifiers.has("abstract")) {
-        const head = this.parseFunctionHead();
-        const func = {
-          type: "FunctionBody",
-          generics: head.generics,
-          params: head.params,
-          hasVarargs: head.hasVarargs,
-          returnType: head.returnType,
-          predicate: head.predicate,
-          body: { type: "Block", statements: [], ...spanFrom(head.start, this.previous()) },
-          ...spanFrom(head.start, this.previous())
-        };
-        if (!isStatic) bindThis(func, start);
-        if (!head.returnType) this.problem("An abstract method has no body to infer from: write its return type");
-        if (this.checkPunctuator("{")) this.problem("An abstract method has no body");
-        return { type: "ClassMethod", name: memberName, isStatic, func, isAbstract: true, ...spanFrom(start, this.previous()) };
-      }
-      const signatures = [];
-      let written = memberName;
-      while (true) {
-        const head = this.parseFunctionHead();
-        if (this.isClassOverloadContinuation(memberName.name, isStatic)) {
-          if (!isStatic) bindThisParam(head.params, start);
-          signatures.push({ ...this.headToSignature(head), name: written });
-          if (isStatic) this.advance();
-          this.expectKeyword("function");
-          written = this.parseIdentifier();
-          continue;
-        }
-        const func = this.headToBody(head, start);
-        if (!isStatic) bindThis(func, start);
-        return {
-          type: "ClassMethod",
-          name: memberName,
-          isStatic,
-          func,
-          signatures: signatures.length ? signatures : void 0,
-          ...spanFrom(start, this.previous())
-        };
-      }
+      return this.parseClassMethod(start, modifiers);
     }
     if (!isStatic && this.checkIdentifierValue("constructor") && this.punctuatorAt(1, "(")) {
       this.advance();
@@ -2009,6 +1981,9 @@ var Parser = class {
       bindThis(func, start);
       return { type: "ClassConstructor", func, ...spanFrom(start, this.previous()) };
     }
+    if (this.startsMethodShorthand(0)) {
+      return this.parseClassMethod(start, modifiers);
+    }
     if ((this.checkIdentifierValue("get") || this.checkIdentifierValue("set")) && this.peek(1).type === "Identifier" && this.punctuatorAt(2, "(")) {
       const kind = this.advance().value;
       const memberName = this.parseIdentifier();
@@ -2038,25 +2013,90 @@ var Parser = class {
       return { type: "ClassField", name: memberName, isStatic, typeAnnotation, init, ...spanFrom(start, this.previous()) };
     }
     if (this.recover) {
-      this.softError("Expected a class member: a field, 'function', 'constructor', 'get' or 'set'");
+      this.softError("Expected a class member: a field, a method, 'constructor', 'get' or 'set'");
       this.advance();
       return void 0;
     }
-    this.error("Expected a class member: a field, 'function', 'constructor', 'get' or 'set'");
+    this.error("Expected a class member: a field, a method, 'constructor', 'get' or 'set'");
+  }
+  /** A name at `offset` opening a method without `function`: `name(` or
+   *  `name<T>(`. A field's name is followed by `:` or `=` instead. */
+  startsMethodShorthand(offset) {
+    if (this.peek(offset).type !== "Identifier") return false;
+    const next = this.peek(offset + 1);
+    return (next.type === "Punctuator" || next.type === "Operator") && (next.value === "(" || next.value === "<");
+  }
+  /** A method, from its name on: `function` (if written) and the modifiers
+   *  are behind. */
+  parseClassMethod(start, modifiers) {
+    const isStatic = modifiers.has("static");
+    const memberName = this.parseIdentifier();
+    if (modifiers.has("abstract")) {
+      const head = this.parseFunctionHead();
+      const func = {
+        type: "FunctionBody",
+        generics: head.generics,
+        params: head.params,
+        hasVarargs: head.hasVarargs,
+        returnType: head.returnType,
+        predicate: head.predicate,
+        body: { type: "Block", statements: [], ...spanFrom(head.start, this.previous()) },
+        ...spanFrom(head.start, this.previous())
+      };
+      if (!isStatic) bindThis(func, start);
+      if (!head.returnType) this.problem("An abstract method has no body to infer from: write its return type");
+      if (this.checkPunctuator("{")) this.problem("An abstract method has no body");
+      return { type: "ClassMethod", name: memberName, isStatic, func, isAbstract: true, ...spanFrom(start, this.previous()) };
+    }
+    const signatures = [];
+    let written = memberName;
+    while (true) {
+      const head = this.parseFunctionHead();
+      const skip = this.classOverloadContinuation(memberName.name, isStatic);
+      if (skip !== void 0) {
+        if (!isStatic) bindThisParam(head.params, start);
+        signatures.push({ ...this.headToSignature(head), name: written });
+        for (let i = 0; i < skip; i++) this.advance();
+        written = this.parseIdentifier();
+        continue;
+      }
+      const func = this.headToBody(head, start);
+      if (!isStatic) bindThis(func, start);
+      return {
+        type: "ClassMethod",
+        name: memberName,
+        isStatic,
+        func,
+        signatures: signatures.length ? signatures : void 0,
+        ...spanFrom(start, this.previous())
+      };
+    }
   }
-  /** Give a class method its `this`: a real first parameter, the way
-   *  `function T:m()` gets a real `self`. Every later pass — scopes, types,
-   *  arity, lowering — then sees an ordinary parameter and needs to know
-   *  nothing about classes. */
   /** After a bodyless head inside a class body, does another declaration of
-   *  the same member follow? Then the head was an overload signature. */
-  isClassOverloadContinuation(name, isStatic) {
-    const offset = isStatic ? 1 : 0;
-    if (isStatic && !this.checkIdentifierValue("static")) return false;
+   *  the same member follow? Then the head was an overload signature, and
+   *  this is how many tokens stand before the next one's name: a `;` that
+   *  ends the head, as TypeScript writes it, the modifiers, and `function`
+   *  when it is written. `undefined` when no overload follows. Each head may
+   *  be written either way, with `function` or without. */
+  classOverloadContinuation(name, isStatic) {
+    let offset = 0;
+    if (this.punctuatorAt(0, ";")) offset++;
+    let sawStatic = false;
+    while (true) {
+      const t = this.peek(offset);
+      const word = t.type === "Identifier" ? t.value : void 0;
+      if (word === void 0 || !CLASS_MODIFIERS.has(word) || this.startsMethodShorthand(offset)) break;
+      if (word === "static") sawStatic = true;
+      offset++;
+    }
+    if (sawStatic !== isStatic) return void 0;
     const keyword = this.peek(offset);
-    if (!(keyword.type === "Keyword" && keyword.value === "function")) return false;
-    const named = this.peek(offset + 1);
-    return named.type === "Identifier" && named.value === name;
+    const hasKeyword = keyword.type === "Keyword" && keyword.value === "function";
+    if (hasKeyword) offset++;
+    const named = this.peek(offset);
+    if (!(named.type === "Identifier" && named.value === name)) return void 0;
+    if (!hasKeyword && !this.startsMethodShorthand(offset)) return void 0;
+    return offset;
   }
   operatorAt(ahead, value) {
     const token = this.peek(ahead);
@@ -2210,6 +2250,7 @@ var Parser = class {
    *  `:` Identifier followed by one of Lua's call forms. */
   startsMethodCall(offset = 0) {
     if (this.peek(offset + 1).type !== "Identifier") return false;
+    if (this.startsOwnLine(this.peek(offset), this.peek(offset + 1))) return false;
     const after = this.peek(offset + 2);
     if (after.type === "Punctuator") {
       const v = String(after.value);
@@ -2235,6 +2276,23 @@ var Parser = class {
     const isString = t.type === "InterpolatedString" || t.type === "Literal" && t.kind === "string";
     return isString && this.punctuatorAt(1, ":") && this.startsMethodCall(1);
   }
+  /** Is there no member name at `offset`, after the `.` or `:` before it? */
+  namelessAfter(offset) {
+    const name = this.peek(offset);
+    if (name.type !== "Identifier") return true;
+    const before = offset === 0 ? this.previous() : this.peek(offset - 1);
+    return before !== void 0 && this.startsOwnLine(before, name);
+  }
+  /** Recovery only. `obj.` may go on to its name on a later line, as in
+   *  JavaScript — but while `obj.` is still being typed, the line below is
+   *  whatever statement was already there, and reading it as the name turns
+   *  one unfinished line into errors about the next. So, as a missing `}`
+   *  is placed, the indentation says which: a line that carries the access
+   *  on is indented deeper than the line it carries on from. */
+  startsOwnLine(before, name) {
+    if (!this.recover || name.line.start <= before.line.end) return false;
+    return this.indentOf(name) <= this.indentOf(before);
+  }
   /** Does the next token start right where the current one ends? */
   touchesNext() {
     const current = this.current();
@@ -2276,6 +2334,7 @@ var Parser = class {
     const t = this.current();
     if (t.type === "Keyword" && t.value === "not") return "not";
     if (t.type === "Operator" && (t.value === "-" || t.value === "#")) return t.value;
+    if (t.type === "Identifier" && t.value === "typeof") return "typeof";
     return null;
   }
   /** Runs `fn` inside a bracket, where a `:` can only ever be a method
@@ -2375,6 +2434,10 @@ var Parser = class {
     const op = this.isUnaryOperator();
     if (op) {
       const opTok = this.advance();
+      const next = this.current();
+      if (op === "typeof" && this.checkPunctuator("(") && next.line.start === opTok.line.end && next.column.start === opTok.column.end) {
+        this.problemAt(next, NO_TYPEOF_CALL);
+      }
       const argument = this.parseExpression(UNARY_PRECEDENCE);
       return {
         type: "UnaryExpression",
@@ -2544,6 +2607,13 @@ var Parser = class {
       if (this.checkPunctuator("?") && this.touchesNext()) {
         const next = this.peek(1);
         const punct = next.type === "Punctuator" ? String(next.value) : void 0;
+        if (punct === "." && this.recover && this.namelessAfter(2) && !this.punctuatorAt(2, "[") && !this.punctuatorAt(2, "(")) {
+          this.advance();
+          this.advance();
+          this.problemAt(this.previous(), NO_MEMBER_NAME);
+          base = { type: "ErrorExpression", expression: base, ...spanFrom(base, this.previous()) };
+          break;
+        }
         if (punct === "." && this.peek(2).type === "Identifier") {
           this.advance();
           this.advance();
@@ -2598,9 +2668,9 @@ var Parser = class {
         }
       }
       if (this.matchPunctuator(".")) {
-        if (this.recover && !this.checkType("Identifier")) {
-          this.softError("Expected identifier");
-          base = { type: "ErrorExpression", ...spanFrom(base, this.previous()) };
+        if (this.namelessAfter(0)) {
+          this.problemAt(this.previous(), NO_MEMBER_NAME);
+          base = { type: "ErrorExpression", expression: base, ...spanFrom(base, this.previous()) };
           break;
         }
         const prop = this.parseIdentifier();
@@ -2613,6 +2683,12 @@ var Parser = class {
         base = { type: "IndexExpression", object: base, index, ...spanFrom(base, this.previous()) };
         continue;
       }
+      if (this.recover && !this.ternaryColons && this.checkPunctuator(":") && this.peek(1).line.start > this.current().line.end && !this.startsMethodCall()) {
+        this.advance();
+        this.problemAt(this.previous(), "Expected a name after ':'");
+        base = { type: "ErrorExpression", expression: base, ...spanFrom(base, this.previous()) };
+        break;
+      }
       if (this.checkPunctuator(":") && this.startsMethodCall() && this.takeMethodColon()) {
         this.advance();
         const method = this.parseIdentifier();
@@ -3456,6 +3532,7 @@ var Parser = class {
       return { type: "TupleTypeNode", elements, ...rest ? { rest } : {}, ...spanFrom(t, this.previous()) };
     }
     if (t.type === "Identifier" && t.value === "typeof" && this.peek(1).type === "Punctuator" && this.peek(1).value === "(") {
+      this.problemAt(this.peek(1), NO_TYPEOF_CALL);
       this.advance();
       this.advance();
       const expression = this.parseExpression();
@@ -3836,7 +3913,7 @@ var BinaryOperators = [
   "and",
   "or"
 ];
-var UnaryOperators = ["-", "not", "#"];
+var UnaryOperators = ["-", "not", "#", "typeof"];
 
 // src/ast/analyzeScopes.ts
 function getBinding(analysis, id) {
@@ -4463,7 +4540,9 @@ var Analyzer = class {
       case "BooleanLiteral":
       case "NumberLiteral":
       case "StringLiteral":
+        return;
       case "ErrorExpression":
+        if (expr.expression) this.visitExpression(expr.expression, scope);
         return;
       case "InterpolatedStringExpression":
         for (const part of expr.parts) {
@@ -4676,11 +4755,34 @@ declare metatable<T> T[]: {
 -- \`nil\` when it is missing; an indexer's keys follow the named ones. A
 -- member of the table's own with one of these names is what a call reaches,
 -- and a class instance, which has a metatable of its own, has none of them.
+--
+-- The rest are JavaScript's \`Object\` functions, written as methods of the
+-- table they take first:
+--
+--     point:hasOwn("x")           -- Object.hasOwn(point, "x")
+--     point:assign({ z: 3 })      -- Object.assign(point, { z: 3 })
+--     point:freeze()              -- Object.freeze(point)
+--
+-- \`hasOwn\` asks the table itself, not what its metatable's \`__index\`
+-- lends it. \`assign\` copies each source's members onto the table, later ones
+-- over earlier ones, skipping a \`nil\` source, and answers the table. \`freeze\`
+-- is Luau's \`table.freeze\`; under Lua 5.1, which cannot freeze a table, the
+-- table is answered as it is and \`isFrozen\` is false.
 declare metatable<T extends {}> T: {
     __index: {
         keys: (self: T) => ObjectKeys<T>,
         values: (self: T) => ObjectValues<T>,
         entries: (self: T) => ObjectEntries<T>,
+
+        hasOwn: (self: T, key: unknown) => boolean,
+        hasOwnProperty: (self: T, key: unknown) => boolean,
+        assign: (<U>(self: T, source: U) => T & U)
+            & (<U, V>(self: T, a: U, b: V) => T & U & V)
+            & (<U, V, W>(self: T, a: U, b: V, c: W) => T & U & V & W)
+            -- Generic like the rest: a plain signature would be tried first.
+            & (<S extends {}>(self: T, ...sources: S[]) => T),
+        freeze: (self: T) => Readonly<T>,
+        isFrozen: (self: T) => boolean,
     },
 }
 `;
@@ -5746,6 +5848,13 @@ function mergeEnv(a, b, base) {
   }
   return out;
 }
+function joinNarrowings(into, a, aFrom, b, bFrom) {
+  for (const [key, left] of a) {
+    const right = b.get(key);
+    if (right === void 0 || left === aFrom.get(key) || right === bFrom.get(key)) continue;
+    into.set(key, union([left, right]));
+  }
+}
 function mergeIndexer(a, b) {
   return a ? { key: union([a.key, b.key]), value: union([a.value, b.value]) } : b;
 }
@@ -6025,6 +6134,10 @@ function unwrapParens(e) {
   while (e.type === "ParenthesizedExpression") e = e.expression;
   return e;
 }
+function memberLabel(label, key) {
+  if (label === void 0 || key === void 0) return void 0;
+  return typeof key === "number" ? `${label}[${key}]` : `${label}.${key}`;
+}
 function expressionLabel(e, depth = 0) {
   if (depth > 6) return void 0;
   const args = (list) => {
@@ -6096,6 +6209,7 @@ var TypeAnalyzer = class {
   metatables = [];
   metatableCache = /* @__PURE__ */ new WeakMap();
   methodSources = /* @__PURE__ */ new Map();
+  typeofTables = /* @__PURE__ */ new Map();
   /** Public: each alias resolved once (generic aliases keep their params as
    *  `typeParam` nodes in the body). */
   aliases = new LazyMap();
@@ -6174,7 +6288,7 @@ var TypeAnalyzer = class {
       const given = this.options.globalTypes?.[name];
       if (given) this.bindingType.set(id, given);
       else if (this.libGlobalTypes.has(name)) this.bindingType.defer(id, () => this.libGlobalTypes.get(name) ?? anyType);
-      else if (LANGUAGE_GLOBALS.includes(name)) this.bindingType.set(id, arrayOf(unknownType));
+      else if (LANGUAGE_GLOBALS.includes(name)) this.bindingType.set(id, arrayOf(declaredUnknownType));
       else this.bindingType.set(id, anyType);
     }
     setAliasExpander((t) => this.expand(t));
@@ -6197,6 +6311,7 @@ var TypeAnalyzer = class {
       aliases: this.resolveDeferredAliases(),
       loops: this.loops,
       methodSources: this.methodSources,
+      typeofTables: this.typeofTables,
       metatableMembers: (type) => this.metatableMembers(type),
       diagnostics: this.diagnostics
     };
@@ -7047,7 +7162,12 @@ var TypeAnalyzer = class {
         this.aliases.defer(name, () => this.classType(cls));
         continue;
       }
-      if (this.dependsOnTypeQuery(name)) continue;
+      if (this.dependsOnTypeQuery(name)) {
+        if (def.runtimeClass) {
+          this.aliases.defer(name, () => this.withTypeParams(def.params, () => this.resolveDef(def)));
+        }
+        continue;
+      }
       this.withTypeParams(def.params, () => {
         this.aliases.set(name, this.resolveDef(def));
       });
@@ -7055,14 +7175,16 @@ var TypeAnalyzer = class {
   }
   typeQueryDependents = /* @__PURE__ */ new Map();
   /** Does alias `name` contain a `typeof`, itself or through an alias it
-   *  names? */
+   *  names? Its parameters count: `class C<K extends Config["key"]>`
+   *  resolves the bound along with the class. */
   dependsOnTypeQuery(name, visiting = /* @__PURE__ */ new Set()) {
     const known = this.typeQueryDependents.get(name);
     if (known !== void 0) return known;
     const def = this.aliasDefs.get(name);
     if (!def || def.class || visiting.has(name)) return false;
     visiting.add(name);
-    const result = containsTypeQuery(def.node) || referencedTypeNames(def.node).some((other) => other !== name && this.dependsOnTypeQuery(other, visiting));
+    const nodes = [def.node, ...def.params.flatMap((p) => [p.constraint, p.default])];
+    const result = nodes.some(containsTypeQuery) || referencedTypeNames(nodes).some((other) => other !== name && this.dependsOnTypeQuery(other, visiting));
     visiting.delete(name);
     this.typeQueryDependents.set(name, result);
     return result;
@@ -7787,7 +7909,7 @@ var TypeAnalyzer = class {
           }
         }
         const mode = this.initIsAsConst(source) ? "asconst" : !isFreshLiteralExpr(source) ? "keep" : stmt.kind === "const" ? "const" : "widen";
-        this.bindPattern(target, inferred, env, mode);
+        this.bindPattern(target, inferred, env, mode, source && expressionLabel(source));
         if (stmt.kind === "const") {
           this.correlateDestructuring(target, inferred, env);
           this.correlateIndexed(target, source, env);
@@ -7880,9 +8002,10 @@ var TypeAnalyzer = class {
         } else if (target.type === "MemberExpression" || target.type === "IndexExpression") {
           this.infer(target, env);
           this.checkReadonlyAssign(target, env);
+          this.checkMemberAssign(stmt, target, vt, env);
           this.assignToRef(target, isFreshLiteralExpr(source) ? widen(vt) : vt, env);
         } else if (target.type === "ObjectPattern" || target.type === "ArrayPattern") {
-          this.reassignPattern(target, vt, env);
+          this.reassignPattern(target, vt, env, expressionLabel(source));
         }
         return;
       }
@@ -9248,7 +9371,8 @@ var TypeAnalyzer = class {
   }
   /** Like `bindPattern`, but the leaves are *existing* bindings (a `{a} = t`
    *  assignment). Updates their flow type; keeps a declared annotation. */
-  reassignPattern(target, valueType, env) {
+  reassignPattern(target, valueType, env, label) {
+    if (target.type === "ObjectPattern" || target.type === "ArrayPattern") valueType = this.destructured(target, valueType, label);
     switch (target.type) {
       case "IdentifierPattern": {
         const id = this.scopes.bindingOf.get(target);
@@ -9273,21 +9397,43 @@ var TypeAnalyzer = class {
         for (const p of target.properties) {
           const key = !p.computed && p.key.type === "Identifier" ? p.key.name : !p.computed && p.key.type === "StringLiteral" ? p.key.value : void 0;
           const pt = key !== void 0 ? this.propertyType(valueType, key) : unknownType;
-          this.reassignPattern(p.value, this.withDefault(pt, p.default, env), env);
+          this.reassignPattern(p.value, this.withDefault(pt, p.default, env), env, memberLabel(label, key));
         }
         if (target.rest) this.reassignPattern(target.rest, this.withoutKeys(valueType, target.properties), env);
         return;
       }
       case "ArrayPattern": {
         target.elements.forEach((el, i) => {
-          if (el) this.reassignPattern(el.value, this.withDefault(this.elementType(valueType, i), el.default, env), env);
+          if (el) this.reassignPattern(el.value, this.withDefault(this.elementType(valueType, i), el.default, env), env, memberLabel(label, i + 1));
         });
         if (target.rest) this.reassignPattern(target.rest, this.restAfter(valueType, target.elements.length), env);
         return;
       }
     }
   }
-  bindPattern(target, valueType, env, mode) {
+  destructuredReported = /* @__PURE__ */ new WeakSet();
+  /** What a pattern reads from. `const { a } = v` is `v.a`, and fails where
+   *  that would: on a `v` that may be nil, and on one that is `unknown`.
+   *  `label` is the value as it would be written — `args[1]` for the inner
+   *  pattern of `const [{ a }] = args`. */
+  destructured(pattern, raw, label) {
+    let type = raw;
+    const report = (message) => {
+      if (!this.emitDiagnostics || this.destructuredReported.has(pattern)) return;
+      this.destructuredReported.add(pattern);
+      this.diagnostics.push({ node: pattern, message: `${label === void 0 ? "Object" : `'${label}'`} ${message}` });
+    };
+    if (this.includesNil(type)) {
+      const t = this.expand(type);
+      report(t.kind === "primitive" ? "is nil" : "is possibly nil. Check it first, or give it a default");
+      type = withoutNil(t);
+    }
+    const read = this.expand(type);
+    if (read.kind === "unknown" && read.declared) report("is of type 'unknown'");
+    return type;
+  }
+  bindPattern(target, valueType, env, mode, label) {
+    if (target.type === "ObjectPattern" || target.type === "ArrayPattern") valueType = this.destructured(target, valueType, label);
     switch (target.type) {
       case "IdentifierPattern": {
         const id = this.bindingIdByName(target.name, target);
@@ -9308,7 +9454,7 @@ var TypeAnalyzer = class {
         for (const p of target.properties) {
           const key = !p.computed && p.key.type === "Identifier" ? p.key.name : !p.computed && p.key.type === "StringLiteral" ? p.key.value : void 0;
           const propType = key !== void 0 ? this.propertyType(valueType, key) : unknownType;
-          this.bindPattern(p.value, this.withDefault(propType, p.default, env), env, mode);
+          this.bindPattern(p.value, this.withDefault(propType, p.default, env), env, mode, memberLabel(label, key));
         }
         if (target.rest) this.bindPattern(target.rest, this.withoutKeys(valueType, target.properties), env, mode);
         return;
@@ -9316,7 +9462,7 @@ var TypeAnalyzer = class {
       case "ArrayPattern": {
         target.elements.forEach((el, i) => {
           if (!el) return;
-          this.bindPattern(el.value, this.withDefault(this.elementType(valueType, i), el.default, env), env, mode);
+          this.bindPattern(el.value, this.withDefault(this.elementType(valueType, i), el.default, env), env, mode, memberLabel(label, i + 1));
         });
         if (target.rest) this.bindPattern(target.rest, this.restAfter(valueType, target.elements.length), env, mode);
         return;
@@ -9881,6 +10027,7 @@ var TypeAnalyzer = class {
       }
       // Broken syntax is reported by the parser; nothing more to say.
       case "ErrorExpression":
+        if (expr.expression) this.infer(expr.expression, env);
         return anyType;
       case "Identifier": {
         const id = this.bindingIdOf(expr);
@@ -9944,6 +10091,14 @@ var TypeAnalyzer = class {
             this.checkOperands(expr, "#", arg);
             return numberType;
           }
+          case "typeof": {
+            const names = this.typeofNamesOf(arg);
+            const tables = names && [...names].filter((name) => name === "array" || name === "object");
+            if (tables?.length === 1) this.typeofTables.set(expr, tables[0]);
+            else this.typeofTables.delete(expr);
+            const answers = names?.size ? [...names] : [...this.typeofTypes().keys()];
+            return union(answers.map((name) => literal(name)));
+          }
         }
         return arg;
       }
@@ -9986,7 +10141,9 @@ var TypeAnalyzer = class {
             return booleanType;
           case "==":
           case "~=":
-            this.checkOverlap(expr, op, l, r);
+            if (!this.checkTypeofName(expr, expr.left, expr.right) && !this.checkTypeofName(expr, expr.right, expr.left)) {
+              this.checkOverlap(expr, op, l, r);
+            }
             return booleanType;
           case "+":
           case "-":
@@ -10187,6 +10344,7 @@ var TypeAnalyzer = class {
     const fromMetatable = this.receiverMetatableMember(objType, expr.method.name);
     if (fromMetatable) this.methodSources.set(expr, fromMetatable.source);
     const method = fromMetatable?.type ?? this.propertyType(objType, expr.method.name);
+    this.typeOf.set(expr.method, method);
     const united = this.unionSignatures(method);
     const fns = united ?? this.overloadsOf(method);
     const explicit = this.explicitTypeArguments(expr, fns);
@@ -10327,6 +10485,43 @@ var TypeAnalyzer = class {
       message: `Cannot assign to '${name}' because it is a read-only property`
     });
   }
+  /** `t.x = v` against what `x` was declared as. Only a property the
+   *  table's type names is checked: a key it does not name is the Lua
+   *  table growing, which `checkMissingMember` is not about. */
+  checkMemberAssign(stmt, target, value, env) {
+    if (!this.emitDiagnostics) return;
+    let name;
+    if (target.type === "MemberExpression") {
+      name = target.property.name;
+    } else {
+      const index = this.expand(this.infer(target.index, env));
+      if (index.kind !== "literal" || typeof index.value !== "string") return;
+      name = index.value;
+    }
+    if (target.object.type === "Identifier") {
+      const id = this.bindingIdOf(target.object);
+      if (id !== void 0 && this.scopes.bindings.get(id)?.declaredBy === "namespace") return;
+    }
+    const declared = this.declaredProperty(this.expand(this.infer(target.object, env)), name);
+    if (!declared || declared.kind === "any" || declared.kind === "unknown") return;
+    if (this.fitsAnnotation(stmt.value, declared, value, env)) return;
+    this.diagnostics.push({
+      node: stmt,
+      message: `Type '${briefType(value)}' is not assignable to '${briefType(declared)}'` + this.explainMismatch(value, declared)
+    });
+  }
+  /** The type a property was declared with, where the type names it. */
+  declaredProperty(t, name) {
+    if (t.kind === "object") {
+      const p = t.properties.get(name);
+      return p && (p.optional ? optional(p.type) : p.type);
+    }
+    if (t.kind === "intersection") {
+      const parts = t.types.flatMap((m) => this.declaredProperty(this.expand(m), name) ?? []);
+      return parts.length ? intersection(parts) : void 0;
+    }
+    return void 0;
+  }
   isReadonlyProperty(t, name) {
     if (t.kind === "object") return t.properties.get(name)?.readonly === true;
     if (t.kind === "intersection" || t.kind === "union") {
@@ -10722,13 +10917,23 @@ var TypeAnalyzer = class {
     if (cond.type === "BinaryExpression") {
       const { operator: op, left, right } = cond;
       if (op === "and") {
-        this.applyNarrowing(left, env, t, forkEnv(env));
-        this.applyNarrowing(right, t, t, forkEnv(t));
+        const before = forkEnv(env);
+        const leftFailed = forkEnv(env);
+        this.applyNarrowing(left, env, t, leftFailed);
+        const between = forkEnv(t);
+        const rightFailed = forkEnv(t);
+        this.applyNarrowing(right, t, t, rightFailed);
+        joinNarrowings(f, leftFailed, before, rightFailed, between);
         return;
       }
       if (op === "or") {
-        this.applyNarrowing(left, env, forkEnv(env), f);
-        this.applyNarrowing(right, f, forkEnv(f), f);
+        const before = forkEnv(env);
+        const leftHeld = forkEnv(env);
+        this.applyNarrowing(left, env, leftHeld, f);
+        const between = forkEnv(f);
+        const rightHeld = forkEnv(f);
+        this.applyNarrowing(right, f, rightHeld, f);
+        joinNarrowings(t, leftHeld, before, rightHeld, between);
         return;
       }
       if (op === "==" || op === "~=") {
@@ -10747,11 +10952,13 @@ var TypeAnalyzer = class {
     this.narrowOptionalLinks(cond, env, t);
   }
   /** `a == b` / `a ~= b`. Handles, in order: a declaration-driven
-   *  `typeof(x) == "..."` test, a literal/`nil` comparison against a
+   *  `typeof x == "..."` test, a literal/`nil` comparison against a
    *  reference, and a reference-to-reference comparison. */
   narrowByComparison(left, right, eq, env, t, f) {
     const yes = eq ? t : f;
     const no = eq ? f : t;
+    if (this.narrowByTypeof(left, right, yes, no, env)) return;
+    if (this.narrowByTypeof(right, left, yes, no, env)) return;
     if (this.narrowByCallResult(left, right, yes, no, env)) return;
     if (this.narrowByCallResult(right, left, yes, no, env)) return;
     const litOf = (e) => {
@@ -10778,18 +10985,149 @@ var TypeAnalyzer = class {
       this.narrowRef(right, env, yes, no, (cur) => ({ yes: narrowTo(cur, lt), no: cur }));
     }
   }
-  /** Declaration-driven `typeof(x) == "number"`.
-   *
-   *  `typeof` is not special-cased: it is declared in the definitions as an
-   *  overload set whose members return *string-literal* types
-   *  (`(value: number) -> "number"`, ...). So for `f(x) == "lit"` we keep the
-   *  parameter types of the overloads that can return `"lit"`, and that union
-   *  is what `x` narrows to. Any user function declared the same way gets the
-   *  same treatment for free.
+  // --------------------------------------------------------
+  // typeof
+  // --------------------------------------------------------
+  //
+  // `typeof v` answers what Luau's `typeof` does, except for a table: that
+  // is an `"array"` or an `"object"`. The names of a runtime's own values —
+  // Roblox's `"Instance"`, `"Vector3"` — are a library's to give: it
+  // declares `type TypeofNames = { Vector3: Vector3, Instance: Instance }`,
+  // each property the name `typeof` answers for a value of that type. A
+  // value several of them fit is the first one's.
+  typeofTypesCache;
+  /** Every name `typeof` answers, and what a value it answered that for
+   *  is — `unknown` where nothing more is known. */
+  typeofTypes() {
+    if (this.typeofTypesCache) return this.typeofTypesCache;
+    const types = /* @__PURE__ */ new Map([
+      ["nil", nilType],
+      ["boolean", booleanType],
+      ["number", numberType],
+      ["string", stringType],
+      ["function", fn([], declaredUnknownType, declaredUnknownType)],
+      ["array", arrayOf(declaredUnknownType)],
+      ["object", objectType([], { key: declaredUnknownType, value: declaredUnknownType })],
+      ["thread", threadType],
+      ["buffer", bufferType],
+      ["userdata", unknownType]
+    ]);
+    for (const [name, type] of this.typeofLibraryNames()) if (!types.has(name)) types.set(name, type);
+    return this.typeofTypesCache = types;
+  }
+  typeofLibraryCache;
+  typeofLibraryNames() {
+    if (this.typeofLibraryCache) return this.typeofLibraryCache;
+    const declared = this.aliases.get("TypeofNames");
+    const names = declared && this.expand(declared);
+    return this.typeofLibraryCache = names?.kind === "object" ? [...names.properties].map(([name, property]) => [name, property.type]) : [];
+  }
+  /** The names `typeof` can answer for a value of type `raw`, or
+   *  `undefined` where the type does not say. */
+  typeofNamesOf(raw, depth = 0) {
+    if (depth > 8) return void 0;
+    const t = this.expand(raw);
+    switch (t.kind) {
+      case "never":
+        return /* @__PURE__ */ new Set();
+      case "primitive":
+        return /* @__PURE__ */ new Set([t.name]);
+      case "literal":
+        return /* @__PURE__ */ new Set([t.base]);
+      case "templateLiteral":
+        return /* @__PURE__ */ new Set(["string"]);
+      case "array":
+      case "tuple":
+        return /* @__PURE__ */ new Set(["array"]);
+      case "function":
+        return /* @__PURE__ */ new Set(["function"]);
+      case "object": {
+        const named = t.class && this.typeofLibraryNames().find(([, type]) => isAssignable(t, type));
+        return /* @__PURE__ */ new Set([named ? named[0] : "object"]);
+      }
+      case "union": {
+        const all = /* @__PURE__ */ new Set();
+        for (const member of t.types) {
+          const names = this.typeofNamesOf(member, depth + 1);
+          if (!names) return void 0;
+          for (const name of names) all.add(name);
+        }
+        return all;
+      }
+      case "intersection": {
+        const known = t.types.map((part) => this.typeofNamesOf(part, depth + 1)).filter((names) => names !== void 0);
+        if (!known.length) return void 0;
+        const common = [...known[0]].filter((name) => known.every((names) => names.has(name)));
+        return new Set(common.length ? common : known[0]);
+      }
+      case "typeParam":
+        return t.constraint ? this.typeofNamesOf(t.constraint, depth + 1) : void 0;
+      case "difference":
+        return this.typeofNamesOf(t.base, depth + 1);
+      default:
+        return void 0;
+    }
+  }
+  /** `typeof v == "table"`: a name `typeof` never answers. Returns true if
+   *  the comparison needs no further checking. */
+  checkTypeofName(node, typeofSide, nameSide) {
+    const test = unwrapParens(typeofSide);
+    if (test.type !== "UnaryExpression" || test.operator !== "typeof") return false;
+    const name = this.asLiteral(unwrapParens(nameSide));
+    if (typeof name !== "string") return false;
+    if (name === "nil") return true;
+    if (this.typeofTypes().has(name)) return false;
+    if (this.emitDiagnostics) {
+      this.diagnostics.push({
+        node,
+        message: name === "table" ? `'typeof' never answers "table": a table is an "array" or an "object"` : `'typeof' never answers "${name}"`
+      });
+    }
+    return true;
+  }
+  /** `typeof x == "number"`: `x` is what answers that name where the test
+   *  holds, and what does not where it fails. Returns true if `testSide` is
+   *  a `typeof` compared with a name. */
+  narrowByTypeof(testSide, nameSide, yes, no, env) {
+    const test = unwrapParens(testSide);
+    if (test.type !== "UnaryExpression" || test.operator !== "typeof") return false;
+    const name = this.asLiteral(unwrapParens(nameSide));
+    if (typeof name !== "string") return false;
+    const answered = this.typeofTypes().get(name);
+    if (!answered) return true;
+    const opaque = answered.kind !== "unknown";
+    const subtracts = opaque && name !== "array" && name !== "object";
+    const members = (cur) => {
+      const t = this.expand(cur);
+      return t.kind === "union" ? t.types.flatMap(members) : [t];
+    };
+    if (this.refKeyOf(test.argument) !== void 0) {
+      this.narrowRef(test.argument, env, yes, no, (cur) => {
+        const kept = [];
+        const dropped = [];
+        for (const member of members(cur)) {
+          const names = this.typeofNamesOf(member);
+          if (!names) {
+            kept.push(opaque ? narrowTo(member, answered) : member);
+            dropped.push(subtracts ? narrowExclude(member, answered) : member);
+            continue;
+          }
+          if (names.has(name)) kept.push(member);
+          if (!(names.size === 1 && names.has(name))) dropped.push(member);
+        }
+        return { yes: union(kept), no: union(dropped) };
+      });
+    }
+    this.narrowOptionalLinks(test.argument, env, name === "nil" ? no : yes);
+    return true;
+  }
+  /** Declaration-driven `kind(x) == "number"`.
    *
-   *  The analyzer knows nothing about the names `type` and `typeof`: with no
-   *  definitions loaded there are no literal-returning overloads and this
-   *  narrows nothing. Returns true if it handled the comparison. */
+   *  A function declared as an overload set whose members return
+   *  *string-literal* types (`(value: number) => "number"`, ...) says by its
+   *  answer what it was given. So for `f(x) == "lit"` we keep the parameter
+   *  types of the overloads that can return `"lit"`, and that union is what
+   *  `x` narrows to. Returns true if it handled the comparison. */
   narrowByCallResult(callSide, litSide, yes, no, env) {
     if (callSide.type !== "CallExpression" || callSide.arguments.length !== 1) return false;
     const name = this.asLiteral(litSide);
@@ -11866,7 +12204,53 @@ function aliasTargets(config, specifier) {
 
 // src/project/sourcemap.ts
 var import_node_path4 = require("path");
+
+// src/luau.ts
+var LUAU_KEYWORDS = /* @__PURE__ */ new Set([
+  "and",
+  "break",
+  "do",
+  "else",
+  "elseif",
+  "end",
+  "false",
+  "for",
+  "function",
+  "if",
+  "in",
+  "local",
+  "nil",
+  "not",
+  "or",
+  "repeat",
+  "return",
+  "then",
+  "true",
+  "until",
+  "while"
+]);
 var IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function isIdentifier(name) {
+  return IDENTIFIER.test(name);
+}
+function isLuauName(name) {
+  return IDENTIFIER.test(name) && !LUAU_KEYWORDS.has(name);
+}
+var NAMED_ESCAPES = {
+  "\\": "\\\\",
+  '"': '\\"',
+  "\n": "\\n",
+  "\r": "\\r",
+  "	": "\\t"
+};
+function escapeLuauString(text) {
+  return text.replace(/[\\"\x00-\x1f\x7f]/g, (c) => NAMED_ESCAPES[c] ?? `\\${c.charCodeAt(0).toString().padStart(3, "0")}`);
+}
+function luauString(text) {
+  return `"${escapeLuauString(text)}"`;
+}
+
+// src/project/sourcemap.ts
 var INSTANCE_MEMBERS = /* @__PURE__ */ new Set(["Name", "ClassName", "Parent", "Archivable"]);
 var SCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([".tilua", ".luau", ".lua"]);
 function sourceMapTypes(text, path, options) {
@@ -11893,7 +12277,7 @@ function sourceMapTypes(text, path, options) {
     const alias = aliasFor(segments);
     aliasOfNode.set(node, alias);
     for (const filePath of node.filePaths ?? []) aliasOfFile.set(fileKey((0, import_node_path4.resolve)(directory, filePath)), alias);
-    const className = IDENTIFIER.test(node.className) && options.classes.has(node.className) ? node.className : "Instance";
+    const className = isIdentifier(node.className) && options.classes.has(node.className) ? node.className : "Instance";
     const taken = options.membersOf?.(className) ?? INSTANCE_MEMBERS;
     const members = [];
     if (parent) members.push(`Parent: ${parent}`);
@@ -11902,7 +12286,7 @@ function sourceMapTypes(text, path, options) {
       if (!isNode(child)) continue;
       const childAlias = visit(child, [...segments, child.name], alias);
       const service = child.name === child.className && options.classes.has(child.className);
-      if (!IDENTIFIER.test(child.name) || taken.has(child.name) && !service || named.has(child.name)) continue;
+      if (!isIdentifier(child.name) || taken.has(child.name) && !service || named.has(child.name)) continue;
       named.add(child.name);
       members.push(`${child.name}: ${childAlias}`);
     }
@@ -11944,6 +12328,34 @@ function fileKey(path) {
   return process.platform === "win32" ? normalized.toLowerCase() : normalized;
 }
 
+// src/loweringHelpers.ts
+function withoutNil2(type) {
+  if (!type) return [];
+  const members = type.kind === "union" ? type.types : [type];
+  return members.filter((m) => !(m.kind === "primitive" && m.name === "nil"));
+}
+function isFunctionType(type) {
+  const members = withoutNil2(type);
+  return members.length > 0 && members.every((m) => m.kind === "function" || m.kind === "intersection" && m.types.every(isFunctionType));
+}
+function everyObject(type, test) {
+  const members = withoutNil2(type);
+  return members.length > 0 && members.every((m) => m.kind === "object" && test(m));
+}
+function isInstanceOf(type, className) {
+  return everyObject(type, (m) => m.class !== void 0 && m.class.ancestors.includes(className));
+}
+function hasMembers(type, names) {
+  return everyObject(type, (m) => names.every((name) => m.properties.has(name)));
+}
+function returnsTuple(receiver, method) {
+  return everyObject(receiver, (m) => {
+    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");
+  });
+}
+
 // src/index.ts
 var tilua = {
   tokenize,
@@ -11964,6 +12376,7 @@ var index_default = tilua;
   CONFIG_FILE_NAMES,
   Keywords,
   LANGUAGE_GLOBALS,
+  LUAU_KEYWORDS,
   LexError,
   Operators,
   PRELUDE_SOURCE,
@@ -11984,20 +12397,27 @@ var index_default = tilua;
   difference,
   directivesOf,
   equalTypes,
+  escapeLuauString,
   falsyType,
   findConfig,
   fn,
   formatType,
   getBinding,
+  hasMembers,
   intersection,
   isAssignable,
   isClassType,
+  isFunctionType,
   isGlobal,
+  isIdentifier,
+  isInstanceOf,
+  isLuauName,
   isPossiblyFalsy,
   isPossiblyTruthy,
   isUnassignedGlobal,
   literal,
   loadConfig,
+  luauString,
   matchInfer,
   moduleCandidates,
   moduleExports,
@@ -12020,6 +12440,7 @@ var index_default = tilua;
   readDirectives,
   resolveModulePath,
   resolveTypeLibraries,
+  returnsTuple,
   setAliasExpander,
   setDeferredBound,
   sourceMapTypes,
@@ -12038,5 +12459,6 @@ var index_default = tilua;
   unknownType,
   widen,
   withAliasName,
-  withoutAliasName
+  withoutAliasName,
+  withoutNil
 });