luaut-parser 2.0.0 → 3.0.0

package/README.md

@@ -71,10 +71,10 @@ npm i -D @luaut/roblox        # or just @luaut/luau
 - **Which config applies** — the nearest one in the file's folder or above.
   `luaut.config.json` and `luaut.config.jsonc` in the same folder is an error.
   Both forms accept comments and trailing commas.
-- **`types`** — `"luau"` is looked up as `@luaut/luau`, then as a package named
-  `luau`, in `node_modules` from the config upward. A full package name or a
-  relative path (`"./types"`, `"./defs.d.luaut"`) works too. A type library's
-  own type-library dependencies load first.
+- **`types`** — any name, looked up as the package `@luaut/<name>` in
+  `node_modules` from the config upward; one that is not installed is an
+  error. A relative path (`"./types"`, `"./defs.d.luaut"`) loads the project's
+  own definitions. A type library's own type-library dependencies load first.
 - **`paths`** — tsconfig rules: an exact pattern wins, then the `*` pattern
   with the longest prefix; targets resolve from `baseUrl` (default: the
   config's folder).
@@ -106,6 +106,22 @@ must.
 
 **Declarations** — `const` and `let` only; Lua's `local` is gone.
 
+**Functions** — `function name() ... end` declares `name` in the enclosing
+scope; like a TypeScript function declaration it cannot be reassigned.
+`const` and `let` do not apply to functions. `function T.name()` and
+`function T:name()` define a member.
+
+**Modules** — `import { a, b as c } from "./m"`, `import D from "./m"` and
+`import * as M from "./m"`; `export const`, `export function`, `export default`,
+`export { a as b }`, `export { a } from "./m"` and `export * from "./m"`.
+Imports are read-only: assigning to an imported name, or to a member of a
+namespace (`M.x = 1`), is an error.
+
+`import type { A } from "./m"` (also `import type D` and `import type * as M`)
+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.
+
 **Optionality** — there is no `T?` shorthand. `?` in type position always
 belongs to a conditional type, and in expression position to a ternary.
 
@@ -117,6 +133,43 @@ name: T | nil   -- must be written, but may be nil
 Omitting an argument requires `?` (or a default), as in TypeScript — a
 parameter typed `T | nil` still has to be passed something.
 
+**Classes** — types are structural, except for classes. A definitions file
+declares one with `declare class`, and it is nominal, as Roblox's classes are:
+
+```luau
+declare class BasePart extends PVInstance { Size: Vector3 }
+declare class Part extends BasePart { Shape: EnumItem }
+```
+
+A `Part` is a `BasePart` and an `Instance` because it extends them. A
+`ReplicatedStorage` is not a `Part`, and no table literal is an `Instance`,
+however alike their members. A class still fits a shape that names members it
+has (`{ Name: string }`). It is not a table, though, so `typeof(part)` picks
+the `"Instance"` overload, not `"table"`. Members are inherited, and a subclass
+may narrow one (`Parent: SomeFolder`).
+
+**Callbacks** — a function written where a function type is expected takes
+its parameter types from it: in `signal:Connect(function(player) ... end)`,
+`player` is typed from `Connect`. The same applies to an annotated `const`
+and to an assignment such as `remote.OnServerInvoke = function(player) ...`.
+
+**Type packs** — `type Signal<T... = ...any> = { Connect: (self, cb: (T...) -> ()) -> () }`.
+A pack parameter takes every type argument from its position on:
+`Signal<Player, string>`, `Signal<()>` for none.
+
+**Operators** — on a type that declares metamethods (`__add`, `__mul`,
+`__unm`, ...), an operator has the metamethod's result, tried on the left
+operand and then the right one, as Luau does. So `Vector3 + Vector3` and
+`2 * vector` are both `Vector3`.
+
+**Qualified type names** — a definitions file may declare `Enum.Material`
+(`declare class Enum.Material extends EnumItem {}`), and code writes it the
+same way.
+
+**Contextual typing** — an expression takes its type from where it is
+written, as in TypeScript: `let queue: thread[] = []` is a `thread[]`, and so
+is `[]` passed where one is expected, including inside an object literal.
+
 **Calls** — every argument is checked against its parameter, and a generic
 parameter against its constraint (`GetService<K extends keyof Services>`
 rejects `""`).