@tilua/parser 2.4.0 → 3.0.0

package/README.md

@@ -260,22 +260,51 @@ brings in names that are types and nothing else: unlike TypeScript, using one
 as a value is an error, and only type positions — `typeof A` included — may
 name it. Compiled code keeps no trace of it.
 
-**Array and string methods** — an array and a string answer to methods
-written with `:`, the way JavaScript writes them:
+**Methods of strings, arrays and tables** — a value answers to the methods
+its metatable's `__index` has, written with `:`:
 
 ```luau
 const long = names:filter(n => #n > 3):map(string.upper)
-const first = names:find(n => n:startsWith("A"))
-print(names:join(", "), text:trim(), text:replaceAll(",", ";"))
+print(names:join(", "), text:trim(), text:upper())
+const point = { x: 1, y: "up" }
+const [x, y] = point:values()   -- [number, string]
 ```
 
-Which methods those are is not the language's business. The analyzer looks for
-two types by name — `ArrayMethods<T>` and `StringMethods` — and reads an
-array's or a string's members out of whichever type library declared them;
-without such a library an array has no methods at all.
+Strings, arrays and tables are the language's own, so their metatables are
+too: the prelude declares them, in tilua, and they are there with no type
+library at all. A string's is Lua's (`upper`, `sub`, with one value where Lua
+answers several: `find` is an array) plus the JavaScript-shaped ones (`trim`,
+`startsWith`, ...); an array's is JavaScript's (`filter`, `map`, `join`, ...),
+with Lua's indices — the first element is 1, `indexOf` answers `nil` rather
+than -1 — and `push`, `pop`, `shift`, `unshift`, `sort` and `reverse` change
+the array. A table's are `keys`, `values` and `entries`, which answer a tuple
+in the order the table's type wrote its members, not `string[]` as
+JavaScript's `Object.keys` does; the analyzer supplies that order as
+`ObjectKeys<T>`, `ObjectValues<T>` and `ObjectEntries<T>`. A member of a
+value's own with the same name is what a call reaches, and a class instance,
+which has a metatable of its own, has none of them.
+
+No Lua array or table really has these methods, so the compiler lowers each
+call into its own runtime (`names:filter(f)` becomes `array.filter(names, f)`);
+a string's Lua methods stay plain method calls.
+
+A library adds to a metatable by declaring the same target again, and a
+metatable can be declared for any type:
 
-Running them is that library's business too. A library points at a JavaScript
-module in its package.json, and the compiler asks it what a call becomes:
+```luau
+declare metatable string: { __index: { split: (self: string, separator?: string) => string[] } }
+declare metatable<T> T[]: { __index: { first: (self: T[]) => T | nil } }
+declare metatable<T extends {}> T: { __index: { size: (self: T) => number } }
+```
+
+`<T> T[]` is every array, `T` what it holds; `<T extends C> T` every value
+that is a `C`, `T` the value itself; a target with no parameters, every value
+of that type. The most specific target a value matches is its metatable.
+
+A method a library's metatable gives may be one the value really has, as
+Luau's `split` is. When it is not, the library says how it runs. It points at
+a JavaScript module in its package.json, and the compiler asks it — and only
+it — what a call through a metatable it declared becomes:
 
 ```json
 "tilua": { "types": "index.d.tilua", "lowering": "lowering.mjs" }
@@ -285,11 +314,9 @@ module in its package.json, and the compiler asks it what a call becomes:
 // @ts-check
 /** @type {import("@tilua/parser").LoweringPlugin} */   // the contract, declared here
 const plugin = {
-    runtime: { array: "local __NAME__ = {}\nfunction __NAME__.filter(t, test) ... end" },
-    methodCall({ method, receiver, use }) {
-        if (receiver?.kind === "array" && method === "filter") {
-            return { callee: `${use("array")}.filter` }
-        }
+    runtime: { array: "local __NAME__ = {}\nfunction __NAME__.first(t) return t[1] end" },
+    methodCall({ method, use }) {
+        if (method === "first") return { callee: `${use("array")}.first` }
         return undefined
     },
 }
@@ -300,7 +327,9 @@ export default plugin
 local name that table got — emitted once, at the top of the output, only if a
 call needed it — and the receiver is passed as the call's first argument. An
 answer of `undefined` leaves an ordinary Luau method call, which is what
-`text:upper()` wants, since a string already answers to it.
+`text:split(",")` wants, since a Luau string already answers to it. A method
+of a value's own (`console:log`, a member of a declared table) is asked of
+every library, the last loaded first.
 
 A call can also carry more than was written. Every hook is told `at`, where
 the call was written (`{ file, line, column }`), and `arguments`: each one's
@@ -314,13 +343,6 @@ hook is asked about it. A runtime can read `__LINES__`, the bundle's line map
 project. `console:log`, `print` and `error` in `@tilua-types/lua` are built on
 these hooks.
 
-The compiler lowers the language and nothing else: `filter` appears nowhere in
-it.
-
-`@tilua-types/lua` ships the JavaScript-shaped set; there, indices are Luau's (the
-first element is 1, `indexOf` answers `nil` rather than -1) and `push`, `pop`,
-`shift`, `unshift`, `sort` and `reverse` change the array they are called on.
-
 **A `(` that starts a line** continues the statement above it, as in Lua and
 in JavaScript — `const v = map[key]` followed by `("A"):upper()` is one
 statement, a call of `map[key]`. tilua says so rather than letting it pass:

package/dist/index.cjs

@@ -734,7 +734,8 @@ var DECLARATION_STATEMENTS = /* @__PURE__ */ new Set([
   "ExportNamedStatement",
   "ExportAllStatement",
   "DeclareStatement",
-  "DeclareClassStatement"
+  "DeclareClassStatement",
+  "DeclareMetatableStatement"
 ]);
 function spanFrom(start, end) {
   return {
@@ -1352,6 +1353,9 @@ var Parser = class {
       if (p1.type === "Identifier" && p1.value === "class" && this.peek(2).type === "Identifier") {
         return this.parseDeclareClassStatement();
       }
+      if (p1.type === "Identifier" && p1.value === "metatable" && !this.punctuatorAt(2, ":")) {
+        return this.parseDeclareMetatableStatement();
+      }
       if (p1.type === "Identifier" || p1.type === "Keyword" && p1.value === "function") {
         return this.parseDeclareStatement();
       }
@@ -1404,6 +1408,17 @@ var Parser = class {
     }
     return tokenIdentifier(first);
   }
+  // `declare metatable<T> T[]: { __index: { ... } }`
+  parseDeclareMetatableStatement() {
+    const start = this.current();
+    this.advance();
+    this.advance();
+    const generics = this.checkOperator("<") ? this.parseGenericTypeParameterList() : [];
+    const target = this.parseType();
+    this.expectPunctuator(":");
+    const metatable = this.parseType();
+    return { type: "DeclareMetatableStatement", generics, target, metatable, ...spanFrom(start, this.previous()) };
+  }
   // `declare class Name extends Base { member: T, ... }`
   parseDeclareClassStatement() {
     const start = this.current();
@@ -2112,6 +2127,14 @@ var Parser = class {
   parseExpressionStatement() {
     const start = this.current();
     if (this.checkPunctuator("{") || this.checkPunctuator("[")) {
+      const call = this.tryParse(() => {
+        const errors = this.errors.length;
+        const expression2 = this.parseAtom();
+        if (expression2.type !== "MethodCallExpression" && expression2.type !== "CallExpression") throw new ParseRecover("not a call");
+        if (this.errors.length > errors) throw new ParseRecover("not a call");
+        return expression2;
+      });
+      if (call) return { type: "CallStatement", expression: call, ...spanFrom(start, this.previous()) };
       const target = this.checkPunctuator("{") ? this.parseObjectPattern(true) : this.parseArrayPattern(true);
       return this.parseAssignmentRest(start, target);
     }
@@ -2433,11 +2456,9 @@ var Parser = class {
     if (t.type === "Identifier" && t.value === "class") {
       return this.parseClassExpression();
     }
-    if (t.type === "Punctuator" && t.value === "{") {
-      return this.parseTableExpression();
-    }
-    if (t.type === "Punctuator" && t.value === "[") {
-      return this.parseArrayExpression();
+    if (t.type === "Punctuator" && (t.value === "{" || t.value === "[")) {
+      const literal2 = t.value === "{" ? this.parseTableExpression() : this.parseArrayExpression();
+      return this.checkPunctuator(":") && this.startsMethodCall() ? this.parseSuffixes(literal2) : literal2;
     }
     if (this.checkType("Identifier") && this.punctuatorAt(1, "=>")) return this.parseArrow();
     if (this.checkPunctuator("(") || this.checkOperator("<")) {
@@ -2514,6 +2535,11 @@ var Parser = class {
     } else {
       this.error("Expected identifier or '('");
     }
+    return this.parseSuffixes(base);
+  }
+  /** What follows a prefix expression's base: `.name`, `[key]`, `:m(...)`,
+   *  a call, and their optional forms. */
+  parseSuffixes(base) {
     while (true) {
       if (this.checkPunctuator("?") && this.touchesNext()) {
         const next = this.peek(1);
@@ -4264,6 +4290,11 @@ var Analyzer = class {
       case "DeclareClassStatement":
         this.visitType(stmt.body, scope);
         return;
+      case "DeclareMetatableStatement":
+        this.visitGenerics(stmt.generics, scope);
+        this.visitType(stmt.target, scope);
+        this.visitType(stmt.metatable, scope);
+        return;
       case "TypeAliasStatement":
       case "ExportTypeAliasStatement":
         this.visitGenerics(
@@ -4529,6 +4560,101 @@ type Mutable<T> = { -readonly [K in keyof T]: T[K] }
 type Pick<T, K> = { [P in K]: T[P] }
 type Omit<T, K> = Pick<T, Exclude<keyof T, K>>
 type Record<K, V> = { [P in K]: V }
+
+-- ============================================================
+-- The metatables of the language's own values
+-- ============================================================
+
+-- A string's methods. The first group is Lua's string library, which a
+-- string really answers to; where Lua answers several values, tilua answers
+-- one, as the global functions do (\`find\` is an array, \`gsub\` the new
+-- string). The second group is written the way JavaScript writes it.
+--
+-- Positions are Lua's: \`sub\` and \`slice\` count from 1, and \`indexOf\` is
+-- \`nil\` when the text is not there.
+declare metatable string: {
+    __index: {
+        upper: (self: string) => string,
+        lower: (self: string) => string,
+        len: (self: string) => number,
+        sub: (self: string, i: number, j?: number) => string,
+        rep: (self: string, n: number, separator?: string) => string,
+        reverse: (self: string) => string,
+        format: (self: string, ...args: unknown[]) => string,
+        byte: ((self: string, i?: number) => number) & ((self: string, i: number, j: number) => number[]),
+        find: (self: string, pattern: string, init?: number, plain?: boolean) => [number, number, ...string[]] | nil,
+        match: (self: string, pattern: string, init?: number) => [...string[]] | nil,
+        gmatch: (self: string, pattern: string) => () => [string, ...string[]] | nil,
+        gsub: (self: string, pattern: string, replacement: unknown, n?: number) => string,
+
+        trim: (self: string) => string,
+        trimStart: (self: string) => string,
+        trimEnd: (self: string) => string,
+        startsWith: (self: string, text: string) => boolean,
+        endsWith: (self: string, text: string) => boolean,
+        includes: (self: string, text: string) => boolean,
+        indexOf: (self: string, text: string, start?: number) => number | nil,
+        slice: (self: string, start?: number, stop?: number) => string,
+        replace: (self: string, text: string, replacement: string) => string,
+        replaceAll: (self: string, text: string, replacement: string) => string,
+        padStart: (self: string, length: number, padding?: string) => string,
+        padEnd: (self: string, length: number, padding?: string) => string,
+    },
+}
+
+-- An array's methods. Lua gives an array no metatable: the compiler lowers
+-- each call to a plain function, so they work on any array, one a Lua
+-- library made included.
+--
+-- Indices are Lua's: the first element is 1, and \`indexOf\` / \`findIndex\`
+-- answer \`nil\` rather than JavaScript's -1. \`sort\` takes Lua's comparator
+-- (true when \`a\` comes first). \`push\`, \`pop\`, \`shift\`, \`unshift\`,
+-- \`sort\` and \`reverse\` change the array; everything else returns a new one.
+declare metatable<T> T[]: {
+    __index: {
+        find: (self: T[], test: (value: T, index: number) => boolean) => T | nil,
+        findIndex: (self: T[], test: (value: T, index: number) => boolean) => number | nil,
+        filter: (self: T[], test: (value: T, index: number) => boolean) => T[],
+        map: <U>(self: T[], transform: (value: T, index: number) => U) => U[],
+        forEach: (self: T[], visit: (value: T, index: number) => nil) => nil,
+        some: (self: T[], test: (value: T, index: number) => boolean) => boolean,
+        every: (self: T[], test: (value: T, index: number) => boolean) => boolean,
+        reduce: <U>(self: T[], step: (total: U, value: T, index: number) => U, initial: U) => U,
+        includes: (self: T[], value: T) => boolean,
+        indexOf: (self: T[], value: T, start?: number) => number | nil,
+        join: (self: T[], separator?: string) => string,
+        concat: (self: T[], ...others: T[][]) => T[],
+        slice: (self: T[], start?: number, stop?: number) => T[],
+        flat: (self: T[]) => T[],
+        reverse: (self: T[]) => T[],
+        sort: (self: T[], compare?: (a: T, b: T) => boolean) => T[],
+        push: (self: T[], ...args: T[]) => number,
+        pop: (self: T[]) => T | nil,
+        shift: (self: T[]) => T | nil,
+        unshift: (self: T[], ...args: T[]) => number,
+    },
+}
+
+-- A table's methods. Unlike JavaScript's \`Object.keys\`, they answer a
+-- tuple, in the order the table's type wrote its members:
+--
+--     const point = { x: 1, y: "up" }
+--     point:keys()     -- ["x", "y"]
+--     point:values()   -- [number, string]
+--     point:entries()  -- [["x", number], ["y", string]]
+--
+-- A Lua table has no order of its own, so the compiler hands its runtime the
+-- keys as the type lists them. An optional member keeps its place, holding
+-- \`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.
+declare metatable<T extends {}> T: {
+    __index: {
+        keys: (self: T) => ObjectKeys<T>,
+        values: (self: T) => ObjectValues<T>,
+        entries: (self: T) => ObjectEntries<T>,
+    },
+}
 `;
 var prelude;
 function preludeProgram() {
@@ -5894,6 +6020,10 @@ var TypeAnalyzer = class {
   typeOfTypeNode = /* @__PURE__ */ new Map();
   expectedTypeOf = /* @__PURE__ */ new Map();
   loops = /* @__PURE__ */ new Map();
+  /** Every `declare metatable`, libraries first, in declaration order. */
+  metatables = [];
+  metatableCache = /* @__PURE__ */ new WeakMap();
+  methodSources = /* @__PURE__ */ new Map();
   /** Public: each alias resolved once (generic aliases keep their params as
    *  `typeParam` nodes in the body). */
   aliases = new LazyMap();
@@ -5960,6 +6090,9 @@ var TypeAnalyzer = class {
     this.registerNestedClasses();
     this.registerNestedAliases();
     for (const lib of this.options.libs ?? []) this.harvestDeclares(lib.body);
+    this.harvestMetatables(preludeProgram().body, { origin: "language" });
+    (this.options.libs ?? []).forEach((lib, i) => this.harvestMetatables(lib.body, { origin: "library", library: i }));
+    this.harvestMetatables(this.program.body, { origin: "program" });
     this.registerImportedTypes();
     this.resolveAllAliases();
     this.harvestDeclares(this.program.body, true);
@@ -5991,6 +6124,8 @@ var TypeAnalyzer = class {
       expectedTypeOf: this.expectedTypeOf,
       aliases: this.resolveDeferredAliases(),
       loops: this.loops,
+      methodSources: this.methodSources,
+      metatableMembers: (type) => this.metatableMembers(type),
       diagnostics: this.diagnostics
     };
   }
@@ -6048,8 +6183,7 @@ var TypeAnalyzer = class {
   }
   /** `layering` is on for the prelude and for definitions files: a second
    *  library that declares an alias already declared *adds* to it, the way a
-   *  second `declare` of a table's name does, so `@tilua-types/roblox` can give
-   *  `StringMethods` Luau's `split` without restating Lua's. The file being
+   *  second `declare` of a table's name does. The file being
    *  analysed is not a layer: its own alias replaces what the libraries
    *  gave, which is how a project opts out of a set. */
   registerAliasDefs(block, layering = false) {
@@ -6967,7 +7101,7 @@ var TypeAnalyzer = class {
       if (record.type === "TypeReference" && typeof record.base === "string") {
         const name = typeof record.namespace === "string" ? `${record.namespace}.${record.base}` : record.base;
         const resolved = this.typeOfTypeNode.get(node);
-        const unresolved = resolved?.kind === "genericRef" && resolved.name === name && !this.aliasDefs.has(name) && !this.importedTypes.has(name) && this.options.libTypes?.[name] === void 0 && !STRING_INTRINSICS.has(name) && !this.importedNames().has(name.split(".")[0]);
+        const unresolved = resolved?.kind === "genericRef" && resolved.name === name && !this.aliasDefs.has(name) && !this.importedTypes.has(name) && this.options.libTypes?.[name] === void 0 && !INTRINSICS.has(name) && !this.importedNames().has(name.split(".")[0]);
         const at = node;
         const key = `${at.line.start}:${at.column.start}`;
         if (unresolved && !reported.has(key)) {
@@ -7085,7 +7219,7 @@ var TypeAnalyzer = class {
           const tp = this.lookupTypeParam(node.base);
           if (tp) return typeParam(tp.name, tp.constraint, tp.isConst);
           if (node.typeArguments.length === 1 && !this.aliasDefs.has(node.base)) {
-            const intrinsic = this.applyStringIntrinsic(
+            const intrinsic = this.applyIntrinsic(
               node.base,
               this.resolveType(node.typeArguments[0])
             );
@@ -7292,7 +7426,7 @@ var TypeAnalyzer = class {
           return difference(this.reduceType(t.base), this.reduceType(t.excluded));
         case "genericRef": {
           if (t.typeArguments.length !== 1 || this.aliasDefs.has(t.name)) return t;
-          return this.applyStringIntrinsic(t.name, t.typeArguments[0]) ?? t;
+          return this.applyIntrinsic(t.name, t.typeArguments[0]) ?? t;
         }
         case "conditional":
           return this.reduceConditional(t);
@@ -7405,6 +7539,41 @@ var TypeAnalyzer = class {
     }
     return union(combos.map((c) => literal(c)));
   }
+  /** A type function the analyzer supplies, since tilua cannot write it. */
+  applyIntrinsic(name, arg) {
+    return this.applyStringIntrinsic(name, arg) ?? this.applyObjectIntrinsic(name, arg);
+  }
+  /** `ObjectKeys<T>`, `ObjectValues<T>`, `ObjectEntries<T>`: an object's
+   *  members as a tuple, in the order they were written — `{ a: 1, b: "x" }`
+   *  has keys `["a", "b"]`, values `[number, string]` and entries
+   *  `[["a", number], ["b", string]]`. TypeScript answers `string[]` for
+   *  `Object.keys`, since its objects have no order; tilua's lowering hands
+   *  the runtime the written order, so the tuple is what runs. An indexer's
+   *  keys follow the named ones, as the tuple's rest. */
+  applyObjectIntrinsic(name, arg) {
+    if (!OBJECT_INTRINSICS.has(name)) return void 0;
+    const t = this.expand(this.reduceType(arg));
+    if (containsTypeParam(t)) return void 0;
+    if (t.kind === "union") return union(t.types.map((m) => this.applyObjectIntrinsic(name, m) ?? unknownType));
+    const parts = t.kind === "intersection" ? t.types.map((m) => this.expand(m)) : [t];
+    if (!parts.every((m) => m.kind === "object" && !m.class)) return unknownType;
+    const properties = /* @__PURE__ */ new Map();
+    let indexer;
+    for (const part of parts) {
+      for (const [key, property] of part.properties) properties.set(key, property);
+      indexer ??= part.indexer;
+    }
+    const entries = [...properties].map(([key, p]) => [literal(key), p.optional ? optional(p.type) : p.type]);
+    const listed = (elements, rest) => !elements.length && rest ? arrayOf(rest) : tuple(elements, rest);
+    switch (name) {
+      case "ObjectKeys":
+        return listed(entries.map(([key]) => key), indexer?.key);
+      case "ObjectValues":
+        return listed(entries.map(([, value]) => value), indexer?.value);
+      default:
+        return listed(entries.map((entry) => tuple([...entry])), indexer && tuple([indexer.key, indexer.value]));
+    }
+  }
   /** TypeScript's four string intrinsics. They cannot be written in tilua —
    *  there is no character-level type arithmetic — so the analyzer supplies
    *  them, and only them, as named type functions. */
@@ -9086,28 +9255,122 @@ var TypeAnalyzer = class {
       this.resolvingAliases.delete(t.name);
     }
   }
-  /** `names:filter(f)`, `text:trim()` — the methods arrays and strings have.
-   *  They are written in the prelude as `ArrayMethods<T>` and
-   *  `StringMethods`, so a file (or a type library) that declares one of
-   *  those names again replaces the whole set, and nothing here is a special
-   *  case in the analyzer. The build lowers each call to a plain function. */
-  builtInMethod(t, name) {
-    const parts = (t.kind === "union" ? t.types : [t]).map((m) => this.expand(m));
-    const elements = parts.map((m) => m.kind === "array" ? m.element : m.kind === "tuple" ? union(m.elements) : void 0);
-    const element = elements.every((e) => e !== void 0) ? union(elements) : void 0;
-    const isString = (m) => m.kind === "primitive" && m.name === "string" || m.kind === "literal" && m.base === "string" || m.kind === "templateLiteral";
-    const methodTable = element !== void 0 ? "ArrayMethods" : parts.every(isString) ? "StringMethods" : void 0;
-    const def = methodTable === void 0 ? void 0 : this.aliasDefs.get(methodTable);
-    if (!def || def.class) return void 0;
-    const table = this.expand(this.instantiateAlias(def, element !== void 0 ? [element] : []));
-    const layers = table.kind === "intersection" ? table.types.map((m) => this.expand(m)) : [table];
-    for (let i = layers.length - 1; i >= 0; i--) {
-      const part = layers[i];
-      const property = part.kind === "object" ? part.properties.get(name) : void 0;
-      if (property) return property.type;
+  // --------------------------------------------------------
+  // Metatables
+  // --------------------------------------------------------
+  harvestMetatables(block, source) {
+    for (const stmt of block.statements) {
+      if (stmt.type === "DeclareMetatableStatement") this.metatables.push({ node: stmt, source });
+    }
+  }
+  resolvedMetatable(entry) {
+    entry.resolved ??= this.withTypeParams(entry.node.generics, () => ({
+      target: this.resolveType(entry.node.target),
+      metatable: this.resolveType(entry.node.metatable)
+    }));
+    return entry.resolved;
+  }
+  /** Does a value (`whole`, whose union members are `parts`) have the
+   *  metatable `entry` declares — and if so how specifically, and what its
+   *  type parameters stand for there. Three kinds of target:
+   *
+   *   - `<T> T[]`: every array and tuple, `T` what they hold;
+   *   - `<T extends C> T`: every value that is a `C` other than a class
+   *     instance, which has a metatable of its own; `T` the value itself;
+   *   - a type with no parameters (`string`): every value that is one.
+   *
+   *  A bare parameter matches the most, so it is the least specific: an
+   *  array that is also a `{}` takes an array's metatable. */
+  matchMetatable(entry, whole, parts) {
+    if (!parts.length || parts.some((m) => m.kind === "any" || m.kind === "unknown" || m.kind === "never")) return void 0;
+    const { target } = this.resolvedMetatable(entry);
+    if (target.kind === "array" && target.element.kind === "typeParam") {
+      const elements = parts.map((m) => m.kind === "array" ? m.element : m.kind === "tuple" ? union(tupleMembers(m)) : void 0);
+      if (!elements.every((e) => e !== void 0)) return void 0;
+      return { specificity: 2, bindings: /* @__PURE__ */ new Map([[target.element.name, union(elements)]]) };
+    }
+    if (target.kind === "typeParam") {
+      const constraint = target.constraint;
+      if (parts.some((m) => m.kind === "object" && m.class)) return void 0;
+      if (constraint && !parts.every((m) => isAssignable(m, constraint))) return void 0;
+      return { specificity: 1, bindings: /* @__PURE__ */ new Map([[target.name, whole]]) };
+    }
+    if (containsTypeParam(target)) return void 0;
+    return parts.every((m) => isAssignable(m, target)) ? { specificity: 2, bindings: /* @__PURE__ */ new Map() } : void 0;
+  }
+  /** The metatables `t` has: every declaration of the most specific target
+   *  it matches, instantiated for it, in declaration order — a later one
+   *  adds to an earlier, the way a library layers on another. A type
+   *  parameter is read at its constraint. */
+  metatablesOf(t) {
+    if (!this.metatables.length) return [];
+    const cached = this.metatableCache.get(t);
+    if (cached) return cached;
+    const expanded = this.expand(t);
+    const parts = (expanded.kind === "union" ? expanded.types : [expanded]).map((m) => this.expand(m)).map((m) => m.kind === "typeParam" && m.constraint ? this.expand(m.constraint) : m);
+    const whole = union(parts);
+    const matches = this.metatables.flatMap((entry) => {
+      const match = this.matchMetatable(entry, whole, parts);
+      return match ? [{ entry, ...match }] : [];
+    });
+    const best = Math.max(0, ...matches.map((m) => m.specificity));
+    const found = matches.filter((m) => m.specificity === best).map(({ entry, bindings }) => ({
+      type: this.expand(this.reduceType(substitute(this.resolvedMetatable(entry).metatable, bindings))),
+      source: entry.source
+    }));
+    this.metatableCache.set(t, found);
+    return found;
+  }
+  /** The `__index` tables of `t`'s metatables, each with the library that
+   *  declared it, in declaration order. */
+  metatableIndexes(t) {
+    return this.metatablesOf(t).flatMap(({ type, source }) => {
+      const parts = type.kind === "intersection" ? type.types.map((m) => this.expand(m)) : [type];
+      return parts.flatMap((part) => {
+        const index = part.kind === "object" ? part.properties.get("__index") : void 0;
+        if (!index) return [];
+        const table = this.expand(index.type);
+        return (table.kind === "intersection" ? table.types.map((m) => this.expand(m)) : [table]).map((m) => ({ table: m, source }));
+      });
+    });
+  }
+  /** `name` read through `t`'s metatable: `text:upper()` is `upper` in the
+   *  string metatable's `__index`. The last declaration to give the name
+   *  wins. The language's own metatables are declared in the prelude, in
+   *  tilua, like any library's; a library adds to them the same way. */
+  metatableMember(t, name) {
+    const indexes = this.metatableIndexes(t);
+    for (let i = indexes.length - 1; i >= 0; i--) {
+      const { table, source } = indexes[i];
+      const property = table.kind === "object" ? table.properties.get(name) : void 0;
+      if (property) return { type: property.type, source };
     }
     return void 0;
   }
+  metatableMethod(t, name) {
+    return this.metatableMember(t, name)?.type;
+  }
+  hasMetatable(t) {
+    return this.metatablesOf(t).length > 0;
+  }
+  metatableMembers(t) {
+    const members = /* @__PURE__ */ new Map();
+    for (const { table } of this.metatableIndexes(t)) {
+      if (table.kind !== "object") continue;
+      for (const [name, property] of table.properties) members.set(name, property.type);
+    }
+    return members;
+  }
+  /** `text:upper()`, `scores:keys()`: the method a value's metatable gives
+   *  it, when the value has no member of that name of its own. Called with
+   *  `:`, it answers before an object's indexer, since a metatable's
+   *  `__index` is only read for a key the table does not hold. */
+  receiverMetatableMember(objType, name) {
+    const t = this.expand(objType);
+    const parts = (t.kind === "union" ? t.types : [t]).map((m) => this.expand(m));
+    if (parts.some((m) => m.kind === "object" && m.properties.has(name))) return void 0;
+    return this.metatableMember(t, name);
+  }
   /** The most a deferred type could turn out to be. A conditional is one of
    *  its branches, and the true branch stands for a member of what was
    *  tested (`T` in `T extends U ? T : never`); an indexed access reads
@@ -9173,7 +9436,7 @@ var TypeAnalyzer = class {
     if (index.kind !== "literal" || typeof index.value !== "string") return void 0;
     const parts = this.stringParts(object);
     if (!parts) return void 0;
-    const found = parts.map((part) => this.builtInMethod(part, index.value));
+    const found = parts.map((part) => this.metatableMethod(part, index.value));
     return found.every((t) => t !== void 0) ? union(found) : void 0;
   }
   /** The members of `t` when every one of them is a string — `"a" | "b"` is
@@ -9194,13 +9457,13 @@ var TypeAnalyzer = class {
    *  not one of them is a mistake worth reporting, rather than the nil Lua
    *  would hand back. */
   checkStringMember(node, object, key) {
-    if (!this.emitDiagnostics || !this.aliasDefs.has("StringMethods")) return;
+    if (!this.emitDiagnostics || !this.hasMetatable(stringType)) return;
     const parts = this.stringParts(object);
     if (!parts) return;
     const keys = (key.kind === "union" ? key.types : [key]).map((m) => this.expand(m));
     if (!keys.length || !keys.every((m) => m.kind === "literal" && typeof m.value === "string")) return;
     const names = keys.map((m) => String(m.value));
-    if (names.some((name) => parts.some((part) => this.builtInMethod(part, name)))) return;
+    if (names.some((name) => parts.some((part) => this.metatableMethod(part, name)))) return;
     this.diagnostics.push({
       node,
       message: names.length === 1 ? `'${names[0]}' does not exist on a string` : `'${briefType(key)}' does not name a member of a string`
@@ -9232,24 +9495,24 @@ var TypeAnalyzer = class {
       switch (part.kind) {
         case "primitive":
           if (part.name === "nil") continue;
-          if (part.name === "string" && !this.aliasDefs.has("StringMethods")) return false;
-          if (part.name === "string" && this.builtInMethod(part, name)) continue;
+          if (part.name === "string" && !this.hasMetatable(part)) return false;
+          if (part.name === "string" && this.metatableMethod(part, name)) continue;
           break;
         case "literal":
         case "templateLiteral":
           if (part.kind === "templateLiteral" || part.base === "string") {
-            if (!this.aliasDefs.has("StringMethods")) return false;
+            if (!this.hasMetatable(part)) return false;
           }
-          if (this.builtInMethod(part, name)) continue;
+          if (this.metatableMethod(part, name)) continue;
           break;
         case "array":
         case "tuple":
-          if (!this.aliasDefs.has("ArrayMethods")) return false;
-          if (this.builtInMethod(part, name)) continue;
+          if (!this.hasMetatable(part)) return false;
+          if (this.metatableMethod(part, name)) continue;
           break;
         case "object":
           if (part.properties.has(name)) continue;
-          if (part.indexer || part.properties.size === 0 && !part.class || this.builtInMethod(part, name)) return false;
+          if (part.indexer || part.properties.size === 0 && !part.class || this.metatableMethod(part, name)) return false;
           break;
         default:
           return false;
@@ -9384,10 +9647,10 @@ var TypeAnalyzer = class {
       if (p) return p.optional ? optional(p.type) : p.type;
       if (t.indexer) return t.indexer.value;
     }
-    const built = this.builtInMethod(t, name);
+    const built = this.metatableMethod(t, name);
     if (built) return built;
     if (t.kind === "union") {
-      const built2 = this.builtInMethod(t, name);
+      const built2 = this.metatableMethod(t, name);
       if (built2) return built2;
       return union(t.types.map((m) => this.propertyType(m, name)));
     }
@@ -9788,7 +10051,9 @@ var TypeAnalyzer = class {
     this.checkPrivateMember(expr.method, objType, expr.method.name);
     this.checkStringMember(expr.method, objType, literal(expr.method.name));
     this.checkMissingMember(expr.method, objType, expr.method.name);
-    const method = this.propertyType(objType, expr.method.name);
+    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);
     const united = this.unionSignatures(method);
     const fns = united ?? this.overloadsOf(method);
     const explicit = this.explicitTypeArguments(expr, fns);
@@ -11030,6 +11295,8 @@ function containsTypeQuery(node) {
   return found;
 }
 var STRING_INTRINSICS = /* @__PURE__ */ new Set(["Uppercase", "Lowercase", "Capitalize", "Uncapitalize"]);
+var OBJECT_INTRINSICS = /* @__PURE__ */ new Set(["ObjectKeys", "ObjectValues", "ObjectEntries"]);
+var INTRINSICS = /* @__PURE__ */ new Set([...STRING_INTRINSICS, ...OBJECT_INTRINSICS]);
 function briefType(t) {
   if (t.kind === "union" && t.types.length > 8) {
     const shown = t.types.slice(0, 6).map(formatType).join(" | ");
@@ -11237,7 +11504,8 @@ function resolveTypeLibraries(config, host = nodeHost) {
     }
     addFile(entryFile);
     const lowering = loweringModule(directory, host, problems, config);
-    if (lowering) lowerings.push(lowering);
+    const library = files.findIndex((file) => pathKey(file) === pathKey(entryFile));
+    if (lowering) lowerings.push({ ...lowering, library });
   };
   for (const entry of config.types) {
     const relative = entry.startsWith("./") || entry.startsWith("../") || entry.startsWith("/") || /^[A-Za-z]:[\\/]/.test(entry);