The Nish language
This is the normative reference for Nish, the subset of TypeScript that
nish compiles to LLVM IR. It describes what the compiler accepts today,
what each construct means, and how every rejection is worded. The design
notes (docs/wp*.md) explain why; this page says what.
Nish is 0.x, and 1.0 has no date.
Until then any minor release may change the language: a change that withdraws
or narrows an accepted construct, or changes what one means, is marked breaking
(type!) and named in the release notes. From 1.0 the rule tightens: a minor
may add a rule or turn a refusal into an acceptance, and anything else needs a
major. In either case the wording of a refusal may change in any release, but
its diagnostic code may not, because --json consumers key on it. Where the
compiler disagrees with this page, the compiler is wrong, and fixing it is not
a change to the language.
Conventions:
-
Every rule cites a test case in parentheses, e.g.
(tests/cases/cf_if), meaningtests/cases/cf_if.ts(with its.llgolden,.outnative output, or.errexpected message). Atests/link/<name>citation is a whole-program link test. Rules marked (CLI only) were verified by compiling a snippet withnishand have no dedicated test case yet. -
Error messages are quoted as the fragment
tests/run.jsmatches; the full line is<file>:<line>:<col>: error: <message>followed by a caret excerpt (wp10-ci.md). -
"i32 mode" is the default; "f64 mode" is
--number-mode f64. Everything else is mode-independent unless stated. - The exact IR for each construct is in IR_COOKBOOK.md.
Contents: Lexical rules · Types ·
Nullable types ·
Result and error handling ·
Declarations ·
Statements · Expressions ·
Builtins · Map and Set ·
Capabilities ·
Semantics decisions ·
Memory model ·
Forbidden constructs ·
Rejected by the checker ·
Known inconsistencies
Lexical rules
Nish source is TypeScript syntax, read by the compiler's own lexer and parser (src/lexer.ts, src/parser.ts), which follow TypeScript's rules for tokens, comments, and ASI; tests/lexer-oracle.js and tests/parser-oracle.js hold them to the typescript package's scanner and parser over the test corpus.
Types
Every Nish type maps 1:1 onto one LLVM first-class type.
Result and error handling
A function that can fail says so in its return type, hands back a Result<T, E>, and the caller cannot get at the success value without first deciding what happens to the failure.
Declarations
A module (one .ts file) may contain, at the top level, only function declarations (a const bound to an arrow, or the legacy function keyword), class and interface declarations, const declarations (Module constants), type aliases (Type aliases), numeric enum declarations (Enums), declare function declarations (Calling C), import statements, and export modifiers on those declarations.
Statements
Every block ({ ... }, loop body, branch) opens a scope.
Expressions
Evaluation is left to right, operands before operators, as in JavaScript; the specific orders for compound assignment and element assignment are under Semantics decisions.
Builtins
No import is needed; builtins are resolved by name.
Semantics decisions
Signed integer overflow is a checked panic; wrappingAdd, wrappingSub and wrappingMul from nish:unsafe wrap.
Forbidden constructs (Phase 0 validator)
src/validator.ts walks the whole syntax tree before the checker and rejects everything below on the first hit, regardless of where it appears (even in dead code or nested type arguments).
Rejected by the checker
Everything the validator lets through but the checker cannot compile.
Known inconsistencies
Behaviour observed with the current compiler that disagrees with the design notes, the runtime header, or JavaScript beyond the documented semantics decisions.

