luaut-parser 3.1.0 → 4.0.0

package/README.md

@@ -160,6 +160,55 @@ 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:
+
+```luau
+const long = names:filter(function(n) return #n > 3 end):map(string.upper)
+const first = names:find(function(n) return n:startsWith("A") end)
+print(names:join(", "), text:trim(), text:replaceAll(",", ";"))
+```
+
+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.
+
+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:
+
+```json
+"luaut": { "types": "index.d.luaut", "lowering": "lowering.mjs" }
+```
+
+```ts
+import type { LoweringPlugin } from "luaut-parser"   // the contract, declared here
+
+const plugin: LoweringPlugin = {
+    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` }
+        }
+        return undefined
+    },
+}
+export default plugin
+```
+
+`receiver` is the luaut type the analyzer worked out, `use(key)` gives the
+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.
+
+The compiler lowers the language and nothing else: `filter` appears nowhere in
+it.
+
+`@luaut/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.
+
 **Optionality** — there is no `T?` shorthand. `?` in type position always
 belongs to a conditional type, and in expression position to a ternary or an
 optional chain.

package/dist/index.cjs

@@ -4824,8 +4824,8 @@ var TypeAnalyzer = class {
   /** Recursion guard for `preVisitBody`. */
   preVisitDepth = 0;
   run() {
-    this.registerAliasDefs(preludeProgram().body);
-    for (const lib of this.options.libs ?? []) this.registerAliasDefs(lib.body);
+    this.registerAliasDefs(preludeProgram().body, true);
+    for (const lib of this.options.libs ?? []) this.registerAliasDefs(lib.body, true);
     this.registerAliasDefs(this.program.body);
     for (const lib of this.options.libs ?? []) this.harvestDeclares(lib.body);
     this.registerImportedTypes();
@@ -4903,10 +4903,28 @@ var TypeAnalyzer = class {
       }
     }
   }
-  registerAliasDefs(block) {
+  /** `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 `@luaut/roblox` can give
+   *  `StringMethods` Luau's `split` without restating Lua's. 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) {
     for (const stmt of block.statements) {
       const alias = stmt.type === "TypeAliasStatement" ? stmt : stmt.type === "ExportTypeAliasStatement" ? stmt.alias : void 0;
-      if (alias) this.aliasDefs.set(alias.name.name, { params: alias.generics, node: alias.definition });
+      if (alias) {
+        const previous = layering ? this.aliasDefs.get(alias.name.name) : void 0;
+        const node = previous && !previous.class ? {
+          type: "IntersectionTypeNode",
+          types: [previous.node, alias.definition],
+          line: alias.definition.line,
+          column: alias.definition.column
+        } : alias.definition;
+        this.aliasDefs.set(alias.name.name, {
+          params: previous && !previous.class && previous.params.length ? previous.params : alias.generics,
+          node
+        });
+      }
       if (stmt.type === "DeclareClassStatement") {
         this.aliasDefs.set(stmt.name.name, { params: [], node: stmt.body, class: stmt });
       }
@@ -6171,13 +6189,15 @@ var TypeAnalyzer = class {
     const objects = this.expectedMembers(expected).filter((m) => m.kind === "object");
     if (!objects.length) return;
     for (const field of e.fields) {
-      if (field.type !== "TableFieldNamed") continue;
-      const key = field.key.type === "Identifier" ? field.key.name : field.key.value;
+      if (field.type !== "TableFieldNamed" && field.type !== "TableFieldShorthand") continue;
+      const key = field.type === "TableFieldShorthand" ? field.name.name : field.key.type === "Identifier" ? field.key.name : field.key.value;
       const types = objects.flatMap((o) => {
         const property = o.properties.get(key);
         return property ? [property.type] : o.indexer ? [o.indexer.value] : [];
       });
-      if (types.length) this.applyContext(field.value, union(types));
+      if (types.length) {
+        this.applyContext(field.type === "TableFieldShorthand" ? field.name : field.value, union(types));
+      }
     }
   }
   /** The members of an expected type worth matching a literal against:
@@ -6976,6 +6996,25 @@ 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 element = t.kind === "array" ? t.element : t.kind === "tuple" ? union(t.elements) : void 0;
+    const methodTable = element !== void 0 ? "ArrayMethods" : t.kind === "primitive" && t.name === "string" || t.kind === "literal" && t.base === "string" ? "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 parts = table.kind === "intersection" ? table.types.map((m) => this.expand(m)) : [table];
+    for (let i = parts.length - 1; i >= 0; i--) {
+      const part = parts[i];
+      const property = part.kind === "object" ? part.properties.get(name) : void 0;
+      if (property) return property.type;
+    }
+    return void 0;
+  }
   propertyType(raw, name) {
     const t = this.deferredAccess(this.expand(raw));
     if (t.kind === "object") {
@@ -6983,6 +7022,8 @@ 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);
+    if (built) return built;
     if (t.kind === "union") return union(t.types.map((m) => this.propertyType(m, name)));
     if (t.kind === "intersection") {
       const parts = t.types.map((m) => this.propertyType(m, name)).filter((p) => p.kind !== "unknown");
@@ -7336,7 +7377,21 @@ var TypeAnalyzer = class {
       }
     }
     if (asConst && !hadSpread) return tuple(elems);
-    return arrayOf(elems.length ? union(elems.map((t) => asConst ? t : widen(t))) : unknownType);
+    return arrayOf(elems.length ? union(elems.map((t, i) => {
+      const element = expr.elements[i];
+      return asConst || !element || element.type === "SpreadElement" ? t : this.widenUnlessAsked(t, element);
+    })) : unknownType);
+  }
+  /** A literal written inside a fresh table or array widens — `{ n = 1 }` is
+   *  `{ n: number }` — unless the surroundings said a literal belongs there.
+   *  `request({ Method: "GET" })` keeps `"GET"` when `Method` is a union of
+   *  string literals, exactly as TypeScript's contextual typing does, and
+   *  goes on widening to `string` when the parameter only says `string`.
+   *  The context was recorded by `applyContext` before the value was
+   *  inferred, so this is a lookup rather than a second pass. */
+  widenUnlessAsked(value, at) {
+    const wanted = this.expectedTypeOf.get(at);
+    return wanted === void 0 ? widen(value) : this.keepContextualLiterals(value, wanted);
   }
   inferObject(expr, env, asConst) {
     const entries = [];
@@ -7344,16 +7399,24 @@ var TypeAnalyzer = class {
     for (const field of expr.fields) {
       if (field.type === "TableFieldNamed") {
         const key = field.key.type === "Identifier" ? field.key.name : field.key.value;
-        const v = asConst ? this.inferAsConst(field.value, env) : widen(this.infer(field.value, env));
+        const v = asConst ? this.inferAsConst(field.value, env) : this.widenUnlessAsked(this.infer(field.value, env), field.value);
         entries.push([key, { type: v, optional: false, readonly: asConst }]);
       } else if (field.type === "TableFieldShorthand") {
         const v = this.infer(field.name, env);
-        entries.push([field.name.name, { type: asConst ? v : widen(v), optional: false, readonly: asConst }]);
+        entries.push([field.name.name, {
+          type: asConst ? v : this.widenUnlessAsked(v, field.name),
+          optional: false,
+          readonly: asConst
+        }]);
       } else if (field.type === "TableFieldComputed") {
         const k = this.infer(field.key, env);
         const v = this.infer(field.value, env);
         if (k.kind === "literal" && typeof k.value === "string") {
-          entries.push([k.value, { type: asConst ? v : widen(v), optional: false, readonly: asConst }]);
+          entries.push([k.value, {
+            type: asConst ? v : this.widenUnlessAsked(v, field.value),
+            optional: false,
+            readonly: asConst
+          }]);
         } else {
           indexer = mergeIndexer(indexer, { key: widen(k), value: asConst ? v : widen(v) });
         }
@@ -8178,6 +8241,7 @@ function offsetPosition(source, offset) {
 var import_node_path2 = require("path");
 function resolveTypeLibraries(config, host = nodeHost) {
   const files = [];
+  const lowerings = [];
   const problems = [];
   const loaded = /* @__PURE__ */ new Set();
   const addFile = (file) => {
@@ -8195,6 +8259,8 @@ function resolveTypeLibraries(config, host = nodeHost) {
       if (found) addPackage(found.directory, found.file, visiting);
     }
     addFile(entryFile);
+    const lowering = loweringModule(directory, host, problems, config);
+    if (lowering) lowerings.push(lowering);
   };
   for (const entry of config.types) {
     const relative = entry.startsWith("./") || entry.startsWith("../") || entry.startsWith("/") || /^[A-Za-z]:[\\/]/.test(entry);
@@ -8221,7 +8287,19 @@ function resolveTypeLibraries(config, host = nodeHost) {
       });
     }
   }
-  return { files, problems };
+  return { files, lowerings, problems };
+}
+function loweringModule(directory, host, problems, config) {
+  const manifest = readJson((0, import_node_path2.join)(directory, "package.json"), host);
+  const declared = manifest?.luaut?.lowering;
+  if (typeof declared !== "string") return void 0;
+  const from = typeof manifest?.name === "string" ? manifest.name : directory;
+  const file = (0, import_node_path2.resolve)(directory, declared);
+  if (host.readFile(file) === void 0) {
+    problems.push({ file: config.path, message: `'${from}' names a lowering module '${declared}', which is not there` });
+    return void 0;
+  }
+  return { file, from };
 }
 var ENTRY_FILE = "index.d.luaut";
 function packageEntry(directory, host) {

package/dist/index.d.cts

@@ -1309,6 +1309,13 @@ resolveModule?: (specifier: string) => ModuleExports | undefined): ModuleExports
  *
  * What a runtime provides — `print`, `string`, `game` — is not here: that is a
  * type library's job (`@luaut/lua`, `@luaut/roblox`).
+ *
+ * The methods an array and a string answer to — `names:filter(f)`,
+ * `text:trim()` — are a library's too. `propertyType` reads them from types
+ * named `ArrayMethods<T>` and `StringMethods`, whichever library declares
+ * those; the library also says which of them the compiler must emit code for
+ * (`luaut.methods` in its package.json). Nothing about `filter` is written
+ * into the analyzer.
  */
 declare const PRELUDE_SOURCE = "\n-- In Luau only `nil` and `false` are falsy: `0` and `\"\"` are truthy.\n-- These are what truthiness narrowing computes, made available to write down.\ntype Falsy = nil | false\ntype Truthy<T> = T - Falsy\n\n-- `-` is set difference. Over a union it drops members; over a concrete type\n-- it simplifies away; over an opaque type (`unknown`, an unresolved parameter)\n-- it is kept, so `Exclude<unknown, 1>` stays `unknown - 1`.\ntype Exclude<T, U> = T - U\ntype Extract<T, U> = T extends U ? T : never\ntype NonNullable<T> = T - nil\n\ntype ReturnType<T> = T extends (...unknown) -> infer R ? R : never\ntype Parameters<T> = T extends (...infer P) -> unknown ? P : never\n\ntype Partial<T> = { [K in keyof T]?: T[K] }\ntype Required<T> = { [K in keyof T]-?: T[K] }\ntype Readonly<T> = { readonly [K in keyof T]: T[K] }\ntype Mutable<T> = { -readonly [K in keyof T]: T[K] }\n\ntype Pick<T, K> = { [P in K]: T[P] }\ntype Omit<T, K> = Pick<T, Exclude<keyof T, K>>\ntype Record<K, V> = { [P in K]: V }\n";
 
@@ -1367,10 +1374,93 @@ declare function stripJsonComments(text: string): string;
 interface TypeLibraries {
     /** Definitions files, dependencies before what depends on them. */
     readonly files: readonly string[];
+    /** Lowering modules the libraries ship, in the same order. */
+    readonly lowerings: readonly LoweringModule[];
     readonly problems: readonly ConfigProblem[];
 }
+/** A library's own lowering: JavaScript the compiler loads and asks what a
+ *  call written against this library's types should become.
+ *
+ *  The library declares the *types* in its definitions file; this is the other
+ *  half. `names:filter(f)` is a call to a function only because `@luaut/lua`
+ *  says so and ships the Luau behind it — the compiler knows how to ask, and
+ *  nothing about `filter`.
+ *
+ *  `luaut.lowering` in the package.json names the module; what it must export
+ *  is the compiler's business (see luaut-build's `LoweringPlugin`). */
+interface LoweringModule {
+    /** The JavaScript module to load. */
+    readonly file: string;
+    /** The package it came from, for reporting. */
+    readonly from: string;
+}
 declare function resolveTypeLibraries(config: LuautConfig, host?: ProjectHost): TypeLibraries;
 
+/**
+ * The contract between a type library and the compiler.
+ *
+ * A library's definitions file says what a value *is*; when what it gives is
+ * not something the value already answers to, the library must also say how
+ * it runs. `names:filter(f)` is a call to a function because `@luaut/lua`
+ * declares the method and ships the Luau behind it — the compiler lowers the
+ * language (`import`, `export`, `?.`, `a ? b : c`, destructuring, spreads)
+ * and asks a library about everything else.
+ *
+ * These types are declarations only: nothing here runs, and the parser never
+ * loads a lowering module. They live here so a library can be written in
+ * TypeScript against the same contract the compiler implements, without
+ * depending on the compiler.
+ *
+ *     // lowering.ts, in a type library
+ *     import type { LoweringPlugin } from "luaut-parser"
+ *
+ *     const plugin: LoweringPlugin = {
+ *         runtime: { array: "local __NAME__ = {}\n..." },
+ *         methodCall({ method, receiver, use }) {
+ *             if (receiver?.kind === "array" && method === "filter") {
+ *                 return { callee: `${use("array")}.filter` }
+ *             }
+ *             return undefined
+ *         },
+ *     }
+ *     export default plugin
+ */
+
+interface LoweringPlugin {
+    /** Luau the plugin needs in the output, by a key it chooses. Each is a
+     *  file's worth of source with `__NAME__` standing for the local the
+     *  compiler gives it, and each is emitted once, at the top of the output,
+     *  only if `use` asked for it:
+     *
+     *      local __NAME__ = {}
+     *      function __NAME__.filter(t, test) ... end
+     */
+    readonly runtime?: Readonly<Record<string, string>>;
+    /** What `receiver:method(...)` becomes. `undefined` leaves a plain Luau
+     *  method call, which is what a value that answers to the method itself
+     *  wants — `text:upper()` reaches Lua's own. */
+    methodCall?(call: MethodCall): MethodLowering | undefined;
+}
+interface MethodCall {
+    /** The name written after `:`. */
+    readonly method: string;
+    /** The receiver's type, as the analyzer worked it out. `undefined` when
+     *  nothing typed it, where a plugin should decline rather than guess. */
+    readonly receiver: Type | undefined;
+    /** How many arguments were written. */
+    readonly argumentCount: number;
+    /** The local name the output gives one of `runtime`'s entries, emitting
+     *  it if this is the first call that needed it. */
+    use(runtime: string): string;
+}
+interface MethodLowering {
+    /** What to call instead: a name, or a `table.member` path — usually built
+     *  from `use(...)`. */
+    readonly callee: string;
+    /** Pass the receiver as the first argument. Default: yes. */
+    readonly passReceiver?: boolean;
+}
+
 /** Every file `specifier` could mean from `fromFile`, in the order they are
  *  tried. A resolver that caches should watch all of them: creating an earlier
  *  candidate changes what the import means. */
@@ -1417,4 +1507,4 @@ declare const luautparser: {
     readonly analyzeTypes: typeof analyzeTypes;
 };
 
-export { type AnalyzeTypesOptions, type AnyType, type ArrayExpression, type ArrayPattern, type ArrayPatternElement, type ArrayType, type ArrayTypeNode, type AsConstExpression, type AssignmentStatement, type BaseNode, type BaseToken, type BinaryExpression, BinaryOperators, type Binding, type BindingId, type BindingKind, type BindingTarget, type Block, type BooleanLiteral, type BreakStatement, CONFIG_FILE_NAMES, type CallExpression, type CallStatement, type ClassInfo, type CompoundAssignmentStatement, type ConditionalType, type ConditionalTypeNode, type ConfigLookup, type ConfigProblem, type ContinueStatement, type DeclareClassStatement, type DeclareStatement, type DifferenceType, type DifferenceTypeNode, type Directive, type DirectiveKind, type DirectiveOutcome, type Directives, type DoStatement, type EOFToken, type ErrorExpression, type ErrorStatement, type ExportAllStatement, type ExportDefaultStatement, type ExportNamedStatement, type ExportSpecifier, type ExportStatement, type ExportTypeAliasStatement, type ExportedType, type Expression, type FunctionBody, type FunctionDeclaration, type FunctionDeclarationStatement, type FunctionExpression, type FunctionName, type FunctionParam, type FunctionParameter, type FunctionSignature, type FunctionType, type FunctionTypeNode, type FunctionTypeParameter, type GenericForStatement, type GenericRefType, type GenericTypeParameter, type Identifier, type IdentifierPattern, type IdentifierToken, type IfClause, type IfElseExpression, type IfStatement, type ImportSpecifier, type ImportStatement, type IndexExpression, type IndexedAccessType, type IndexedAccessTypeNode, type InferType, type InferTypeNode, type InterpolatedStringExpression, type InterpolatedStringPart, type InterpolatedStringPart_Expression, type InterpolatedStringPart_String, type InterpolatedStringToken, type IntersectionType, type IntersectionTypeNode, type KeyofType, type KeyofTypeNode, type KeywordToken, Keywords, LexError, type LiteralToken, type LiteralType, type LuautConfig, type MappedType, type MappedTypeNode, type MemberExpression, type MethodCallExpression, type ModuleExports, type NeverType, type NilLiteral, type Node, type NumberLiteral, type NumericForStatement, type ObjectPattern, type ObjectPatternProperty, type ObjectProperty, type ObjectType, type OperatorToken, Operators, PRELUDE_SOURCE, type ParenthesizedExpression, type ParenthesizedTypeNode, ParseError, type ParserOptions, type PrimitiveName, type PrimitiveType, type Program, type ProjectHost, type PunctuatorToken, Punctuators, type RecoverResult, type RepeatStatement, type ReturnStatement, type SatisfiesExpression, type ScopeAnalysis, type ScopeDiagnostic, type SourceComment, type SourceMapNode, type SourceMapOptions, type SourceMapTypes, type SpreadElement, type Statement, type StringLiteral, type TableExpression, type TableField, type TableTypeNode, type TableTypeProperty, type TemplateLiteralType, type TemplateLiteralTypeNode, type Token, type TokenizeOptions, type TupleType, type TupleTypeNode, type Type, type TypeAliasStatement, type TypeAnalysis, type TypeAssertionExpression, type TypeDiagnostic, type TypeLibraries, type TypeLiteralBoolean, type TypeLiteralNumber, type TypeLiteralString, type TypeNode, type TypePackNode, type TypeParamType, type TypePredicate, type TypePredicateNode, type TypeReference, type TypedIdentifier, type TypeofTypeNode, UNUSED_EXPECT_ERROR, type UnaryExpression, UnaryOperators, type UnionType, type UnionTypeNode, type UnknownType, type VarargExpression, type VariableDeclaration, type VariadicTypeNode, type WhileStatement, analyzeScopes, analyzeTypes, anyType, applyDirectives, arrayOf, booleanType, bufferType, containsTypeParam, luautparser as default, difference, directivesOf, equalTypes, falsyType, findConfig, fn, formatType, getBinding, intersection, isAssignable, isClassType, isGlobal, isPossiblyFalsy, isPossiblyTruthy, isUnassignedGlobal, literal, loadConfig, luautparser, matchInfer, moduleCandidates, moduleExports, narrowExclude, narrowFalsy, narrowTo, narrowTruthy, neverType, nilType, nodeHost, numberType, objectType, optional, overlaps, parse, parseExpressionFromSource, parseTokens, parseWithRecovery, primitive, readDirectives, resolveModulePath, resolveTypeLibraries, setAliasExpander, sourceMapTypes, stringType, stripJsonComments, substitute, templateMatches, threadType, tokenize, tuple, typeParam, unify, union, unknownType, widen };
+export { type AnalyzeTypesOptions, type AnyType, type ArrayExpression, type ArrayPattern, type ArrayPatternElement, type ArrayType, type ArrayTypeNode, type AsConstExpression, type AssignmentStatement, type BaseNode, type BaseToken, type BinaryExpression, BinaryOperators, type Binding, type BindingId, type BindingKind, type BindingTarget, type Block, type BooleanLiteral, type BreakStatement, CONFIG_FILE_NAMES, type CallExpression, type CallStatement, type ClassInfo, type CompoundAssignmentStatement, type ConditionalType, type ConditionalTypeNode, type ConfigLookup, type ConfigProblem, type ContinueStatement, type DeclareClassStatement, type DeclareStatement, type DifferenceType, type DifferenceTypeNode, type Directive, type DirectiveKind, type DirectiveOutcome, type Directives, type DoStatement, type EOFToken, type ErrorExpression, type ErrorStatement, type ExportAllStatement, type ExportDefaultStatement, type ExportNamedStatement, type ExportSpecifier, type ExportStatement, type ExportTypeAliasStatement, type ExportedType, type Expression, type FunctionBody, type FunctionDeclaration, type FunctionDeclarationStatement, type FunctionExpression, type FunctionName, type FunctionParam, type FunctionParameter, type FunctionSignature, type FunctionType, type FunctionTypeNode, type FunctionTypeParameter, type GenericForStatement, type GenericRefType, type GenericTypeParameter, type Identifier, type IdentifierPattern, type IdentifierToken, type IfClause, type IfElseExpression, type IfStatement, type ImportSpecifier, type ImportStatement, type IndexExpression, type IndexedAccessType, type IndexedAccessTypeNode, type InferType, type InferTypeNode, type InterpolatedStringExpression, type InterpolatedStringPart, type InterpolatedStringPart_Expression, type InterpolatedStringPart_String, type InterpolatedStringToken, type IntersectionType, type IntersectionTypeNode, type KeyofType, type KeyofTypeNode, type KeywordToken, Keywords, LexError, type LiteralToken, type LiteralType, type LoweringModule, type LoweringPlugin, type LuautConfig, type MappedType, type MappedTypeNode, type MemberExpression, type MethodCall, type MethodCallExpression, type MethodLowering, type ModuleExports, type NeverType, type NilLiteral, type Node, type NumberLiteral, type NumericForStatement, type ObjectPattern, type ObjectPatternProperty, type ObjectProperty, type ObjectType, type OperatorToken, Operators, PRELUDE_SOURCE, type ParenthesizedExpression, type ParenthesizedTypeNode, ParseError, type ParserOptions, type PrimitiveName, type PrimitiveType, type Program, type ProjectHost, type PunctuatorToken, Punctuators, type RecoverResult, type RepeatStatement, type ReturnStatement, type SatisfiesExpression, type ScopeAnalysis, type ScopeDiagnostic, type SourceComment, type SourceMapNode, type SourceMapOptions, type SourceMapTypes, type SpreadElement, type Statement, type StringLiteral, type TableExpression, type TableField, type TableTypeNode, type TableTypeProperty, type TemplateLiteralType, type TemplateLiteralTypeNode, type Token, type TokenizeOptions, type TupleType, type TupleTypeNode, type Type, type TypeAliasStatement, type TypeAnalysis, type TypeAssertionExpression, type TypeDiagnostic, type TypeLibraries, type TypeLiteralBoolean, type TypeLiteralNumber, type TypeLiteralString, type TypeNode, type TypePackNode, type TypeParamType, type TypePredicate, type TypePredicateNode, type TypeReference, type TypedIdentifier, type TypeofTypeNode, UNUSED_EXPECT_ERROR, type UnaryExpression, UnaryOperators, type UnionType, type UnionTypeNode, type UnknownType, type VarargExpression, type VariableDeclaration, type VariadicTypeNode, type WhileStatement, analyzeScopes, analyzeTypes, anyType, applyDirectives, arrayOf, booleanType, bufferType, containsTypeParam, luautparser as default, difference, directivesOf, equalTypes, falsyType, findConfig, fn, formatType, getBinding, intersection, isAssignable, isClassType, isGlobal, isPossiblyFalsy, isPossiblyTruthy, isUnassignedGlobal, literal, loadConfig, luautparser, matchInfer, moduleCandidates, moduleExports, narrowExclude, narrowFalsy, narrowTo, narrowTruthy, neverType, nilType, nodeHost, numberType, objectType, optional, overlaps, parse, parseExpressionFromSource, parseTokens, parseWithRecovery, primitive, readDirectives, resolveModulePath, resolveTypeLibraries, setAliasExpander, sourceMapTypes, stringType, stripJsonComments, substitute, templateMatches, threadType, tokenize, tuple, typeParam, unify, union, unknownType, widen };

package/dist/index.d.ts

@@ -1309,6 +1309,13 @@ resolveModule?: (specifier: string) => ModuleExports | undefined): ModuleExports
  *
  * What a runtime provides — `print`, `string`, `game` — is not here: that is a
  * type library's job (`@luaut/lua`, `@luaut/roblox`).
+ *
+ * The methods an array and a string answer to — `names:filter(f)`,
+ * `text:trim()` — are a library's too. `propertyType` reads them from types
+ * named `ArrayMethods<T>` and `StringMethods`, whichever library declares
+ * those; the library also says which of them the compiler must emit code for
+ * (`luaut.methods` in its package.json). Nothing about `filter` is written
+ * into the analyzer.
  */
 declare const PRELUDE_SOURCE = "\n-- In Luau only `nil` and `false` are falsy: `0` and `\"\"` are truthy.\n-- These are what truthiness narrowing computes, made available to write down.\ntype Falsy = nil | false\ntype Truthy<T> = T - Falsy\n\n-- `-` is set difference. Over a union it drops members; over a concrete type\n-- it simplifies away; over an opaque type (`unknown`, an unresolved parameter)\n-- it is kept, so `Exclude<unknown, 1>` stays `unknown - 1`.\ntype Exclude<T, U> = T - U\ntype Extract<T, U> = T extends U ? T : never\ntype NonNullable<T> = T - nil\n\ntype ReturnType<T> = T extends (...unknown) -> infer R ? R : never\ntype Parameters<T> = T extends (...infer P) -> unknown ? P : never\n\ntype Partial<T> = { [K in keyof T]?: T[K] }\ntype Required<T> = { [K in keyof T]-?: T[K] }\ntype Readonly<T> = { readonly [K in keyof T]: T[K] }\ntype Mutable<T> = { -readonly [K in keyof T]: T[K] }\n\ntype Pick<T, K> = { [P in K]: T[P] }\ntype Omit<T, K> = Pick<T, Exclude<keyof T, K>>\ntype Record<K, V> = { [P in K]: V }\n";
 
@@ -1367,10 +1374,93 @@ declare function stripJsonComments(text: string): string;
 interface TypeLibraries {
     /** Definitions files, dependencies before what depends on them. */
     readonly files: readonly string[];
+    /** Lowering modules the libraries ship, in the same order. */
+    readonly lowerings: readonly LoweringModule[];
     readonly problems: readonly ConfigProblem[];
 }
+/** A library's own lowering: JavaScript the compiler loads and asks what a
+ *  call written against this library's types should become.
+ *
+ *  The library declares the *types* in its definitions file; this is the other
+ *  half. `names:filter(f)` is a call to a function only because `@luaut/lua`
+ *  says so and ships the Luau behind it — the compiler knows how to ask, and
+ *  nothing about `filter`.
+ *
+ *  `luaut.lowering` in the package.json names the module; what it must export
+ *  is the compiler's business (see luaut-build's `LoweringPlugin`). */
+interface LoweringModule {
+    /** The JavaScript module to load. */
+    readonly file: string;
+    /** The package it came from, for reporting. */
+    readonly from: string;
+}
 declare function resolveTypeLibraries(config: LuautConfig, host?: ProjectHost): TypeLibraries;
 
+/**
+ * The contract between a type library and the compiler.
+ *
+ * A library's definitions file says what a value *is*; when what it gives is
+ * not something the value already answers to, the library must also say how
+ * it runs. `names:filter(f)` is a call to a function because `@luaut/lua`
+ * declares the method and ships the Luau behind it — the compiler lowers the
+ * language (`import`, `export`, `?.`, `a ? b : c`, destructuring, spreads)
+ * and asks a library about everything else.
+ *
+ * These types are declarations only: nothing here runs, and the parser never
+ * loads a lowering module. They live here so a library can be written in
+ * TypeScript against the same contract the compiler implements, without
+ * depending on the compiler.
+ *
+ *     // lowering.ts, in a type library
+ *     import type { LoweringPlugin } from "luaut-parser"
+ *
+ *     const plugin: LoweringPlugin = {
+ *         runtime: { array: "local __NAME__ = {}\n..." },
+ *         methodCall({ method, receiver, use }) {
+ *             if (receiver?.kind === "array" && method === "filter") {
+ *                 return { callee: `${use("array")}.filter` }
+ *             }
+ *             return undefined
+ *         },
+ *     }
+ *     export default plugin
+ */
+
+interface LoweringPlugin {
+    /** Luau the plugin needs in the output, by a key it chooses. Each is a
+     *  file's worth of source with `__NAME__` standing for the local the
+     *  compiler gives it, and each is emitted once, at the top of the output,
+     *  only if `use` asked for it:
+     *
+     *      local __NAME__ = {}
+     *      function __NAME__.filter(t, test) ... end
+     */
+    readonly runtime?: Readonly<Record<string, string>>;
+    /** What `receiver:method(...)` becomes. `undefined` leaves a plain Luau
+     *  method call, which is what a value that answers to the method itself
+     *  wants — `text:upper()` reaches Lua's own. */
+    methodCall?(call: MethodCall): MethodLowering | undefined;
+}
+interface MethodCall {
+    /** The name written after `:`. */
+    readonly method: string;
+    /** The receiver's type, as the analyzer worked it out. `undefined` when
+     *  nothing typed it, where a plugin should decline rather than guess. */
+    readonly receiver: Type | undefined;
+    /** How many arguments were written. */
+    readonly argumentCount: number;
+    /** The local name the output gives one of `runtime`'s entries, emitting
+     *  it if this is the first call that needed it. */
+    use(runtime: string): string;
+}
+interface MethodLowering {
+    /** What to call instead: a name, or a `table.member` path — usually built
+     *  from `use(...)`. */
+    readonly callee: string;
+    /** Pass the receiver as the first argument. Default: yes. */
+    readonly passReceiver?: boolean;
+}
+
 /** Every file `specifier` could mean from `fromFile`, in the order they are
  *  tried. A resolver that caches should watch all of them: creating an earlier
  *  candidate changes what the import means. */
@@ -1417,4 +1507,4 @@ declare const luautparser: {
     readonly analyzeTypes: typeof analyzeTypes;
 };
 
-export { type AnalyzeTypesOptions, type AnyType, type ArrayExpression, type ArrayPattern, type ArrayPatternElement, type ArrayType, type ArrayTypeNode, type AsConstExpression, type AssignmentStatement, type BaseNode, type BaseToken, type BinaryExpression, BinaryOperators, type Binding, type BindingId, type BindingKind, type BindingTarget, type Block, type BooleanLiteral, type BreakStatement, CONFIG_FILE_NAMES, type CallExpression, type CallStatement, type ClassInfo, type CompoundAssignmentStatement, type ConditionalType, type ConditionalTypeNode, type ConfigLookup, type ConfigProblem, type ContinueStatement, type DeclareClassStatement, type DeclareStatement, type DifferenceType, type DifferenceTypeNode, type Directive, type DirectiveKind, type DirectiveOutcome, type Directives, type DoStatement, type EOFToken, type ErrorExpression, type ErrorStatement, type ExportAllStatement, type ExportDefaultStatement, type ExportNamedStatement, type ExportSpecifier, type ExportStatement, type ExportTypeAliasStatement, type ExportedType, type Expression, type FunctionBody, type FunctionDeclaration, type FunctionDeclarationStatement, type FunctionExpression, type FunctionName, type FunctionParam, type FunctionParameter, type FunctionSignature, type FunctionType, type FunctionTypeNode, type FunctionTypeParameter, type GenericForStatement, type GenericRefType, type GenericTypeParameter, type Identifier, type IdentifierPattern, type IdentifierToken, type IfClause, type IfElseExpression, type IfStatement, type ImportSpecifier, type ImportStatement, type IndexExpression, type IndexedAccessType, type IndexedAccessTypeNode, type InferType, type InferTypeNode, type InterpolatedStringExpression, type InterpolatedStringPart, type InterpolatedStringPart_Expression, type InterpolatedStringPart_String, type InterpolatedStringToken, type IntersectionType, type IntersectionTypeNode, type KeyofType, type KeyofTypeNode, type KeywordToken, Keywords, LexError, type LiteralToken, type LiteralType, type LuautConfig, type MappedType, type MappedTypeNode, type MemberExpression, type MethodCallExpression, type ModuleExports, type NeverType, type NilLiteral, type Node, type NumberLiteral, type NumericForStatement, type ObjectPattern, type ObjectPatternProperty, type ObjectProperty, type ObjectType, type OperatorToken, Operators, PRELUDE_SOURCE, type ParenthesizedExpression, type ParenthesizedTypeNode, ParseError, type ParserOptions, type PrimitiveName, type PrimitiveType, type Program, type ProjectHost, type PunctuatorToken, Punctuators, type RecoverResult, type RepeatStatement, type ReturnStatement, type SatisfiesExpression, type ScopeAnalysis, type ScopeDiagnostic, type SourceComment, type SourceMapNode, type SourceMapOptions, type SourceMapTypes, type SpreadElement, type Statement, type StringLiteral, type TableExpression, type TableField, type TableTypeNode, type TableTypeProperty, type TemplateLiteralType, type TemplateLiteralTypeNode, type Token, type TokenizeOptions, type TupleType, type TupleTypeNode, type Type, type TypeAliasStatement, type TypeAnalysis, type TypeAssertionExpression, type TypeDiagnostic, type TypeLibraries, type TypeLiteralBoolean, type TypeLiteralNumber, type TypeLiteralString, type TypeNode, type TypePackNode, type TypeParamType, type TypePredicate, type TypePredicateNode, type TypeReference, type TypedIdentifier, type TypeofTypeNode, UNUSED_EXPECT_ERROR, type UnaryExpression, UnaryOperators, type UnionType, type UnionTypeNode, type UnknownType, type VarargExpression, type VariableDeclaration, type VariadicTypeNode, type WhileStatement, analyzeScopes, analyzeTypes, anyType, applyDirectives, arrayOf, booleanType, bufferType, containsTypeParam, luautparser as default, difference, directivesOf, equalTypes, falsyType, findConfig, fn, formatType, getBinding, intersection, isAssignable, isClassType, isGlobal, isPossiblyFalsy, isPossiblyTruthy, isUnassignedGlobal, literal, loadConfig, luautparser, matchInfer, moduleCandidates, moduleExports, narrowExclude, narrowFalsy, narrowTo, narrowTruthy, neverType, nilType, nodeHost, numberType, objectType, optional, overlaps, parse, parseExpressionFromSource, parseTokens, parseWithRecovery, primitive, readDirectives, resolveModulePath, resolveTypeLibraries, setAliasExpander, sourceMapTypes, stringType, stripJsonComments, substitute, templateMatches, threadType, tokenize, tuple, typeParam, unify, union, unknownType, widen };
+export { type AnalyzeTypesOptions, type AnyType, type ArrayExpression, type ArrayPattern, type ArrayPatternElement, type ArrayType, type ArrayTypeNode, type AsConstExpression, type AssignmentStatement, type BaseNode, type BaseToken, type BinaryExpression, BinaryOperators, type Binding, type BindingId, type BindingKind, type BindingTarget, type Block, type BooleanLiteral, type BreakStatement, CONFIG_FILE_NAMES, type CallExpression, type CallStatement, type ClassInfo, type CompoundAssignmentStatement, type ConditionalType, type ConditionalTypeNode, type ConfigLookup, type ConfigProblem, type ContinueStatement, type DeclareClassStatement, type DeclareStatement, type DifferenceType, type DifferenceTypeNode, type Directive, type DirectiveKind, type DirectiveOutcome, type Directives, type DoStatement, type EOFToken, type ErrorExpression, type ErrorStatement, type ExportAllStatement, type ExportDefaultStatement, type ExportNamedStatement, type ExportSpecifier, type ExportStatement, type ExportTypeAliasStatement, type ExportedType, type Expression, type FunctionBody, type FunctionDeclaration, type FunctionDeclarationStatement, type FunctionExpression, type FunctionName, type FunctionParam, type FunctionParameter, type FunctionSignature, type FunctionType, type FunctionTypeNode, type FunctionTypeParameter, type GenericForStatement, type GenericRefType, type GenericTypeParameter, type Identifier, type IdentifierPattern, type IdentifierToken, type IfClause, type IfElseExpression, type IfStatement, type ImportSpecifier, type ImportStatement, type IndexExpression, type IndexedAccessType, type IndexedAccessTypeNode, type InferType, type InferTypeNode, type InterpolatedStringExpression, type InterpolatedStringPart, type InterpolatedStringPart_Expression, type InterpolatedStringPart_String, type InterpolatedStringToken, type IntersectionType, type IntersectionTypeNode, type KeyofType, type KeyofTypeNode, type KeywordToken, Keywords, LexError, type LiteralToken, type LiteralType, type LoweringModule, type LoweringPlugin, type LuautConfig, type MappedType, type MappedTypeNode, type MemberExpression, type MethodCall, type MethodCallExpression, type MethodLowering, type ModuleExports, type NeverType, type NilLiteral, type Node, type NumberLiteral, type NumericForStatement, type ObjectPattern, type ObjectPatternProperty, type ObjectProperty, type ObjectType, type OperatorToken, Operators, PRELUDE_SOURCE, type ParenthesizedExpression, type ParenthesizedTypeNode, ParseError, type ParserOptions, type PrimitiveName, type PrimitiveType, type Program, type ProjectHost, type PunctuatorToken, Punctuators, type RecoverResult, type RepeatStatement, type ReturnStatement, type SatisfiesExpression, type ScopeAnalysis, type ScopeDiagnostic, type SourceComment, type SourceMapNode, type SourceMapOptions, type SourceMapTypes, type SpreadElement, type Statement, type StringLiteral, type TableExpression, type TableField, type TableTypeNode, type TableTypeProperty, type TemplateLiteralType, type TemplateLiteralTypeNode, type Token, type TokenizeOptions, type TupleType, type TupleTypeNode, type Type, type TypeAliasStatement, type TypeAnalysis, type TypeAssertionExpression, type TypeDiagnostic, type TypeLibraries, type TypeLiteralBoolean, type TypeLiteralNumber, type TypeLiteralString, type TypeNode, type TypePackNode, type TypeParamType, type TypePredicate, type TypePredicateNode, type TypeReference, type TypedIdentifier, type TypeofTypeNode, UNUSED_EXPECT_ERROR, type UnaryExpression, UnaryOperators, type UnionType, type UnionTypeNode, type UnknownType, type VarargExpression, type VariableDeclaration, type VariadicTypeNode, type WhileStatement, analyzeScopes, analyzeTypes, anyType, applyDirectives, arrayOf, booleanType, bufferType, containsTypeParam, luautparser as default, difference, directivesOf, equalTypes, falsyType, findConfig, fn, formatType, getBinding, intersection, isAssignable, isClassType, isGlobal, isPossiblyFalsy, isPossiblyTruthy, isUnassignedGlobal, literal, loadConfig, luautparser, matchInfer, moduleCandidates, moduleExports, narrowExclude, narrowFalsy, narrowTo, narrowTruthy, neverType, nilType, nodeHost, numberType, objectType, optional, overlaps, parse, parseExpressionFromSource, parseTokens, parseWithRecovery, primitive, readDirectives, resolveModulePath, resolveTypeLibraries, setAliasExpander, sourceMapTypes, stringType, stripJsonComments, substitute, templateMatches, threadType, tokenize, tuple, typeParam, unify, union, unknownType, widen };

package/dist/index.js

@@ -4726,8 +4726,8 @@ var TypeAnalyzer = class {
   /** Recursion guard for `preVisitBody`. */
   preVisitDepth = 0;
   run() {
-    this.registerAliasDefs(preludeProgram().body);
-    for (const lib of this.options.libs ?? []) this.registerAliasDefs(lib.body);
+    this.registerAliasDefs(preludeProgram().body, true);
+    for (const lib of this.options.libs ?? []) this.registerAliasDefs(lib.body, true);
     this.registerAliasDefs(this.program.body);
     for (const lib of this.options.libs ?? []) this.harvestDeclares(lib.body);
     this.registerImportedTypes();
@@ -4805,10 +4805,28 @@ var TypeAnalyzer = class {
       }
     }
   }
-  registerAliasDefs(block) {
+  /** `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 `@luaut/roblox` can give
+   *  `StringMethods` Luau's `split` without restating Lua's. 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) {
     for (const stmt of block.statements) {
       const alias = stmt.type === "TypeAliasStatement" ? stmt : stmt.type === "ExportTypeAliasStatement" ? stmt.alias : void 0;
-      if (alias) this.aliasDefs.set(alias.name.name, { params: alias.generics, node: alias.definition });
+      if (alias) {
+        const previous = layering ? this.aliasDefs.get(alias.name.name) : void 0;
+        const node = previous && !previous.class ? {
+          type: "IntersectionTypeNode",
+          types: [previous.node, alias.definition],
+          line: alias.definition.line,
+          column: alias.definition.column
+        } : alias.definition;
+        this.aliasDefs.set(alias.name.name, {
+          params: previous && !previous.class && previous.params.length ? previous.params : alias.generics,
+          node
+        });
+      }
       if (stmt.type === "DeclareClassStatement") {
         this.aliasDefs.set(stmt.name.name, { params: [], node: stmt.body, class: stmt });
       }
@@ -6073,13 +6091,15 @@ var TypeAnalyzer = class {
     const objects = this.expectedMembers(expected).filter((m) => m.kind === "object");
     if (!objects.length) return;
     for (const field of e.fields) {
-      if (field.type !== "TableFieldNamed") continue;
-      const key = field.key.type === "Identifier" ? field.key.name : field.key.value;
+      if (field.type !== "TableFieldNamed" && field.type !== "TableFieldShorthand") continue;
+      const key = field.type === "TableFieldShorthand" ? field.name.name : field.key.type === "Identifier" ? field.key.name : field.key.value;
       const types = objects.flatMap((o) => {
         const property = o.properties.get(key);
         return property ? [property.type] : o.indexer ? [o.indexer.value] : [];
       });
-      if (types.length) this.applyContext(field.value, union(types));
+      if (types.length) {
+        this.applyContext(field.type === "TableFieldShorthand" ? field.name : field.value, union(types));
+      }
     }
   }
   /** The members of an expected type worth matching a literal against:
@@ -6878,6 +6898,25 @@ 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 element = t.kind === "array" ? t.element : t.kind === "tuple" ? union(t.elements) : void 0;
+    const methodTable = element !== void 0 ? "ArrayMethods" : t.kind === "primitive" && t.name === "string" || t.kind === "literal" && t.base === "string" ? "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 parts = table.kind === "intersection" ? table.types.map((m) => this.expand(m)) : [table];
+    for (let i = parts.length - 1; i >= 0; i--) {
+      const part = parts[i];
+      const property = part.kind === "object" ? part.properties.get(name) : void 0;
+      if (property) return property.type;
+    }
+    return void 0;
+  }
   propertyType(raw, name) {
     const t = this.deferredAccess(this.expand(raw));
     if (t.kind === "object") {
@@ -6885,6 +6924,8 @@ 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);
+    if (built) return built;
     if (t.kind === "union") return union(t.types.map((m) => this.propertyType(m, name)));
     if (t.kind === "intersection") {
       const parts = t.types.map((m) => this.propertyType(m, name)).filter((p) => p.kind !== "unknown");
@@ -7238,7 +7279,21 @@ var TypeAnalyzer = class {
       }
     }
     if (asConst && !hadSpread) return tuple(elems);
-    return arrayOf(elems.length ? union(elems.map((t) => asConst ? t : widen(t))) : unknownType);
+    return arrayOf(elems.length ? union(elems.map((t, i) => {
+      const element = expr.elements[i];
+      return asConst || !element || element.type === "SpreadElement" ? t : this.widenUnlessAsked(t, element);
+    })) : unknownType);
+  }
+  /** A literal written inside a fresh table or array widens — `{ n = 1 }` is
+   *  `{ n: number }` — unless the surroundings said a literal belongs there.
+   *  `request({ Method: "GET" })` keeps `"GET"` when `Method` is a union of
+   *  string literals, exactly as TypeScript's contextual typing does, and
+   *  goes on widening to `string` when the parameter only says `string`.
+   *  The context was recorded by `applyContext` before the value was
+   *  inferred, so this is a lookup rather than a second pass. */
+  widenUnlessAsked(value, at) {
+    const wanted = this.expectedTypeOf.get(at);
+    return wanted === void 0 ? widen(value) : this.keepContextualLiterals(value, wanted);
   }
   inferObject(expr, env, asConst) {
     const entries = [];
@@ -7246,16 +7301,24 @@ var TypeAnalyzer = class {
     for (const field of expr.fields) {
       if (field.type === "TableFieldNamed") {
         const key = field.key.type === "Identifier" ? field.key.name : field.key.value;
-        const v = asConst ? this.inferAsConst(field.value, env) : widen(this.infer(field.value, env));
+        const v = asConst ? this.inferAsConst(field.value, env) : this.widenUnlessAsked(this.infer(field.value, env), field.value);
         entries.push([key, { type: v, optional: false, readonly: asConst }]);
       } else if (field.type === "TableFieldShorthand") {
         const v = this.infer(field.name, env);
-        entries.push([field.name.name, { type: asConst ? v : widen(v), optional: false, readonly: asConst }]);
+        entries.push([field.name.name, {
+          type: asConst ? v : this.widenUnlessAsked(v, field.name),
+          optional: false,
+          readonly: asConst
+        }]);
       } else if (field.type === "TableFieldComputed") {
         const k = this.infer(field.key, env);
         const v = this.infer(field.value, env);
         if (k.kind === "literal" && typeof k.value === "string") {
-          entries.push([k.value, { type: asConst ? v : widen(v), optional: false, readonly: asConst }]);
+          entries.push([k.value, {
+            type: asConst ? v : this.widenUnlessAsked(v, field.value),
+            optional: false,
+            readonly: asConst
+          }]);
         } else {
           indexer = mergeIndexer(indexer, { key: widen(k), value: asConst ? v : widen(v) });
         }
@@ -8080,6 +8143,7 @@ function offsetPosition(source, offset) {
 import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
 function resolveTypeLibraries(config, host = nodeHost) {
   const files = [];
+  const lowerings = [];
   const problems = [];
   const loaded = /* @__PURE__ */ new Set();
   const addFile = (file) => {
@@ -8097,6 +8161,8 @@ function resolveTypeLibraries(config, host = nodeHost) {
       if (found) addPackage(found.directory, found.file, visiting);
     }
     addFile(entryFile);
+    const lowering = loweringModule(directory, host, problems, config);
+    if (lowering) lowerings.push(lowering);
   };
   for (const entry of config.types) {
     const relative = entry.startsWith("./") || entry.startsWith("../") || entry.startsWith("/") || /^[A-Za-z]:[\\/]/.test(entry);
@@ -8123,7 +8189,19 @@ function resolveTypeLibraries(config, host = nodeHost) {
       });
     }
   }
-  return { files, problems };
+  return { files, lowerings, problems };
+}
+function loweringModule(directory, host, problems, config) {
+  const manifest = readJson(join2(directory, "package.json"), host);
+  const declared = manifest?.luaut?.lowering;
+  if (typeof declared !== "string") return void 0;
+  const from = typeof manifest?.name === "string" ? manifest.name : directory;
+  const file = resolve2(directory, declared);
+  if (host.readFile(file) === void 0) {
+    problems.push({ file: config.path, message: `'${from}' names a lowering module '${declared}', which is not there` });
+    return void 0;
+  }
+  return { file, from };
 }
 var ENTRY_FILE = "index.d.luaut";
 function packageEntry(directory, host) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luaut-parser",
-  "version": "3.1.0",
+  "version": "4.0.0",
   "description": "luaut parser for roblox",
   "main": "./dist/index.js",
   "module": "./dist/index.js",