Language constructs

Conditional branching with the usual else-if chain and optional braceless single-statement bodies.

Pre-condition loop; the body runs zero or more times.

Post-condition loop; the body always runs at least once before the condition is checked. break/continue work inside it.

let i = 0
do {
  console.log(i)
  i++
} while (i < 3)

The C-style three-clause for loop.

Iterates arrays, a string (its code points), Map (its [key, value] entries, live: an entry added during the loop is visited, a deleted one is not), Set (elements), generators, a bare any holding a string, a dynamic or boxed array (by its runtime length), or any iterable through its [Symbol.iterator]() (an any loop variable; anything else throws Node's 'is not iterable' TypeError), and both the structural next(): T | null shape and the spec's real [Symbol.iterator]() protocol. The loop variable may be a destructuring pattern, including nested. A scalar next() returns a presence-flagged aggregate so a yielded 0/false doesn't end iteration.

Iterates the field names of an object as strings.

const point = { x: 10, y: 20, z: 30 }
for (const key in point) {
  console.log(key)
}

Multi-way branch with numeric, string, and boolean discriminants.

Loop break/continue, including a labeled target on an enclosing loop. A break/continue inside a nested closure can only target a loop declared within that closure's own body — a clean compile-time rejection otherwise, matching JS's no-cross-function-boundary label rule.

Typed return; an implicit void return is handled.

Throws via setjmp/longjmp. A built-in error constructor is also a first-class value (a boxed funcref with exact identity, typeof "function").

Exception handling with a single catch variable or a destructured object pattern. finally runs on early return/break/continue (labeled or not), a return in finally overrides, and nested finallys run innermost-first — inside async functions and generators too, including a finally that itself awaits.

function readWithCleanup(): number {
  try {
    return 42
  } finally {
    console.log("close resource")
  }
}

The catch parameter clause is optional (ES2019).

Semicolons are optional where JavaScript inserts them: a statement ends at a line break, before `}` or at the end of the file. A line break is refused where the grammar refuses one — before a postfix `++`/`--`, after `return`/`throw`/`break`/`continue`/`yield`, before `=>`, and between `async` and its function — so `a` then `++b` on the next line is two statements. `async` and `abstract` stay usable as names.

Reading a property, calling a method, indexing, or writing a property on a value that is undefined or null at run time throws Node's TypeError — Cannot read properties of undefined (reading 'length') / Cannot set properties of null (setting 'x') — catchable and instanceof TypeError; uncaught, the program reports it and exits 1. Covers string, object, class and Map bases, a T | undefined scalar receiver, x!.p, compound assignment and ++. Optional chaining never throws. An out-of-range element read is undefined, so rows[5].name throws too; an absent array (T[] | null, an omitted xs?: T[]) throws on xs[0] / xs.length / xs.push(), and TypeError: xs is not iterable on for…of and spread. An empty array is present: truthy and !== null.

interface User { name: string; manager?: User }
const boss: User = { name: "Ada" }
try {
  console.log(boss.manager.name)
} catch (err) {
  console.log(err instanceof TypeError)   // true
  console.log((err as Error).message)     // Cannot read properties of undefined (reading 'name')
}
console.log(boss.manager?.name)          // undefined

Parsed and erased to a no-op — an AOT-compiled native binary has no attached inspector to break into, matching plain JS with no debugger attached. debugger is a reserved word, never a real identifier.

Decimal, float, hex, binary, and octal numeric literals.

Underscore digit separators, stripped at lex time so every downstream consumer sees a clean literal. A leading/trailing/doubled separator, or one inside a legacy-octal literal, is a clean lexer error.

Single- and double-quoted strings; the full ES escape grammar is decoded (\b \f \v, \xHH, \uHHHH, \u{H…}, Annex B legacy octal, line continuation, and the NonEscapeCharacter rule). Templates share the same decoding.

Boolean literals.

The null literal; a T | null union type is supported.

The undefined literal.

Backtick template literals with arbitrary interpolation depth.

const msg = `Hello, ${name}!`

The five basic arithmetic operators.

Right-associative exponentiation (ES2016), binding tighter than * / %, with **=. number operands are doubles so 2 ** -1 is 0.5 and 2 ** 0.5 is a real root; explicit integer-typed operands use exact i64 exponentiation-by-squaring and stay i64. -2 ** 2 is a SyntaxError, matching JS.

The comparison operators; string comparison via strcmp. NaN compares per JS: NaN !== NaN is true while ===/</>/<=/>= against NaN are all false.

Genuinely short-circuiting logical operators. Result type is bool under -compat=strict (default); -compat=js makes &&/|| value-preserving (x || "default" yields the string; scalars of different kinds yield their union, 0 || "x" is number | string).

The bitwise and shift operators, including the unsigned right shift >>>.

The full set of compound assignment operators.

Genuinely short-circuiting logical assignment (ES2021). Works against scalar variables, array elements, object fields, static class fields, and a computed dynamic-object key (dynObj[key] ??= v), including a nullable-scalar field routed through the presence-flagged path so obj.n ??= v fires exactly when the field is absent.

Prefix and postfix increment/decrement on an identifier, member (obj.x++, this.x++, C.staticField++, makeObj().x++), or index (arr[i]++, makeArr()[i]++) target. A member/index target desugars to += 1 / -= 1; prefix yields the new value, postfix the old. A consumed postfix hoists any side-effecting component so each runs exactly once, matching JS.

The conditional (ternary) operator. A cond ? scalar : null mix is a T | null value, and scalar branches of different kinds (c ? 1 : "a", c ? 1 : true) yield their union (number | string), narrowable with typeof.

function label(n: number) { return n % 2 === 0 ? n : "odd" }
console.log(label(2), label(3))   // 2 odd
console.log(typeof label(3))       // string

Evaluates each operand left to right and yields the last (its type is the sequence's type). Also usable in a for header.

Works on a pointer T | null (string/object/…) and a non-pointer scalar T | null (number | null, boolean | null) via a real presence bit — so let x: number | null = null; x ?? 42 yields 42 while a present 0 yields 0. Operands of different kinds (n ?? "none", s ?? 0) yield their union, number | string, narrowable with typeof. A pointer left operand keeps its own type, so the result is usable in place — (row ?? dflt).name — and stays T | undefined when the right operand can itself be absent; an element of a (number | undefined)[] coalesced with a number is a plain number.

All three forms — property a?.b, element a?.[k] and call f?.(args) / a?.m(args) — short-circuit to a real undefined on a null or undefined base, and the chain short-circuits as a whole: in a?.b.c or a?.b.m(x) a nullish a skips every later link and leaves call arguments and element keys unevaluated. Parentheses end the chain, as in JavaScript. The result is typed T | undefined.

Compile-time constant resolved from inferred type. Heap-backed built-in values (a Promise, Map/Set, a generator, Date, null) are "object"; classes, implemented built-in constructors, and implemented global functions are "function"; Math/JSON/console are "object"; an undeclared name or runtime-absent static is "undefined".

Evaluates its operand for its side effects and yields undefined. A function may name a parameter or variable undefined, which then reads that binding.

console.log(void 0)          // undefined
console.log(void track())    // undefined, track() still runs

Reduces to the same compile-time FieldIndex lookup Object.hasOwn() uses — object shapes are fully structural/static, so a string-literal key against an object is a compile-time-constant true/false, not a runtime scan. Parsed as a contextual keyword at instanceof precedence.

Array-literal spread.

var is function-scoped and re-declarable; let/const are block-scoped and const rebinding is rejected. A top-level const/let/var is a module global — readable and writable from any named function whenever its type is determinable before main() runs. Block redeclaration, TDZ, and use-before-assignment are compile errors.

Array destructuring with holes, defaults (fire when past the source length), and a rest element that makes a real independent copy. Usable as a for-of loop variable and a destructured parameter; nested patterns work in a declaration/for-of/parameter.

Object destructuring with renaming, string/numeric-literal keys, nested patterns, and a rest element that binds a fresh residual object. Usable as a for-of loop variable and destructured parameter. Assignment to already-declared targets requires parens.

Desugars to a plain call — interpolated values reach the tag as real typed values, not implicitly stringified. Any callable works as a tag, including an arrow/closure with a ...rest parameter. The strings parameter is a TemplateStringsArray with its raw text in strings.raw, each call site's template object is the same object on every call, and a generic tag takes explicit type arguments (tag<T>`…`).

Named top-level functions with typed params and return. A leading this parameter (function f(this: T, …)) is parsed and erased, exactly as real TS does. The arguments object holds the values a call passed (.length counts them), with indexing and for…of.

Full closures; captures via a heap-allocated env struct.

function makeCounter(): () => number {
  let count = 0
  return (): number => {
    count = count + 1
    return count
  }
}

Anonymous and named function expressions, including as callback arguments. A named function expression binds its own name inside its own body for recursion without leaking — even when that name shadows a top-level function of the same name (the self-reference is the expression; outer calls reach the top-level function). async function(...) {...} expressions are supported. Reuses arrow closure machinery.

const add = function (x: number, y: number): number {
  return x + y;
};

Default parameter values.

Optional parameters. An omitted argument reads as a real `T | undefined` inside the body (as in TS) — a present 0/"" is distinguishable from an omitted argument; narrow, `?? d`, or `!` to consume it.

Works on named function declarations, class methods, arrow functions/closures, and function type annotations ((...xs: number[]) => R and the same as a type alias) alike.

Object- and array-destructured parameters. A destructured callback parameter needs no annotation — its type is supplied by contextual typing from the higher-order method's element type, so the common `Object.entries(o).map(([k, v]) => …)` / Map-entries / pair-array idiom works. A heterogeneous tuple pattern binds each position by its own type. Each element/field may have its own default; nested patterns work; supported on named functions, class methods/constructors, and arrow functions.

A helper function declared inside another function's body — hoisted (letrec-style: a capturing declaration is usable before its declaration statement), forward-referenceable, self-recursive, and visible to its own further-nested descendants. Captures enclosing locals/parameters by reference — arrays and loop variables included (a C-style or iterator `let` loop variable is captured per-iteration, JS semantics; `var` shares) — and escapes by name as a real closure value with an inferred type; a nested generator escapes as a first-class constructor closure.

function outer(x: number): number {
  function double(y: number): number {
    return y * 2;
  }
  return double(x) + 1;
}

f.call/f.apply lower to a direct call; f.apply(thisArg, arr) spreads into a rest slot; f.bind builds a new partially-applied closure. All type-checked against f's parameters exactly as a normal call.

const add = (a: number, b: number): number => a + b;
console.log(add.call(null, 3, 4));
console.log(add.apply(null, [5, 6]));

Overload signature heads (a `function` head terminated by `;` with no body) are parsed and then erased — call sites type-check against the implementation's parameter list, matching this compiler's TS-modifier stance.

Real suspend/resume via this compiler's ucontext-based fiber primitive. The full iterator protocol: .throw(e) injects at the suspension point, .return(v) completes running enclosing finally blocks, and yield* delegates to an inner generator.

function* basic(): Generator<number, number> {
  yield 1;
  yield 2;
  return 3;
}
const g = basic();
console.log(g.next().value, g.next().done);

Every async fn returns a real task-shaped Promise<T>: a fn containing an await runs on a ucontext fiber; a no-await one settles inline. Named declarations, async arrows, and async function expressions are all supported. No libcurl linked unless fetch is used.

async function add(a: number, b: number): Promise<number> {
  return a + b
}
const sum = await add(10, 32)

A Promise is a reusable value — await p twice returns the same result. Every await yields a microtask tick, of an already-settled promise and of a non-promise value, FIFO-ordered with .then/queueMicrotask, matching JS. Registers a resume reaction and parks — at the entry program's top level too: a module with a top-level await runs as a coroutine, so its continuation is ordered among the promise's other reactions exactly as in Node, and an await nothing can settle ends the process with Node's warning and exit code 13.

Real concurrency over Array<Promise<Response>> (fetch) and over Array<Promise<T>> from may-suspend async fns. Each member is a reusable value. .race/.any return the shortest-delay member via an event-driven waiter list. A rejecting member rejects .all/.race and reports rejected in .allSettled. A rejected .allSettled element's .reason is the original rejected value with full fidelity — a primitive keeps its typeof and JSON, a rejected Error serializes as {} and reads .message/.name/String and instanceof (TDD-00169). An error-subclass instance reason reads .message/.name, renders Name: message and serializes its own enumerable fields as Node does. A list may mix promises and plain values ([p, 4]).

Over task promises it skips rejected members and resolves to the first fulfilled one; when every member rejects it throws a real AggregateError carrying each reason on .errors. Over raw fetches, an HTTP 404/500 is a fulfilled fetch, per WHATWG.

Both build a settled task promise, so await/.then/.catch/.finally and the combinators all work. Promise.resolve(v) fulfils with v (an already-promise arg flattens through); Promise.reject(e) is typed Promise<never>, so a rejected value assigns to any binding. No fiber/libcurl linked.

The executor constructor with thenable adoption (resolve(anotherPromise) settles the outer promise with the inner's value, reaction-based; a class instance, object or interface value with a then method is adopted through a job that calls its then, as await, Promise.resolve and the combinators also do), synchronous resolve/reject, first-settle-wins, and deferred resolution from a setTimeout callback. The executor may be an arrow, function expression, closure variable, or bare top-level-function reference.

.then/.catch/.finally directly on a raw fetch Promise<Response> never block the synchronous script — the wait is deferred to a queued microtask. The callback runs as a microtask when the promise settles and its result chains into the returned promise. A missing callback slot is a pass-through. queueMicrotask is a FIFO drained after the sync script and before timers.

V8/spec step timing: .next() starts the body synchronously up to the first await/yield; an await inside the body parks the step. Top-level or nested async function* and a class async *m() method. .next() returns a real Promise<{value,done}>. Full protocol: .throw(e)/.return(v) and yield* over an inner async generator or a Symbol.asyncIterator iterable.

Consumes an async-generator instance, a user class or object literal implementing the async-iteration protocol, or any sync iterable the sync for...of takes (awaiting each element). Awaits each .next() promise before reading .done/.value; the loop is itself a suspension point. A destructuring loop variable unpacks each element.

Numeric enums with auto-increment and explicit values.

enum Direction {
  North,
  East,
  South,
  West,
}
console.log(Direction.East)  // 1

String enums; members are interned string constants. The enum name (and its [] array form) as a type annotation resolves to the enum's ptr backing type, so a typed variable/param/field/array, comparison, and switch all work.

Merges with a same-name top-level function X(...) — TS's callable-object duality idiom (assert(x) + assert.sameValue(...)); members desugar to flat top-level declarations.

Structural interfaces backed by heap-allocated objects.

Type alias declarations.

A key may be an identifier, or a string/numeric literal.

get/set are contextual (not reserved). No new storage: an accessor is registered as an ordinary method under an internal dispatch key. obj.x / obj.x = v / compound assignment all route through the accessor, including from inside the class's own methods and through optional chaining. On object literals too: the literal is lowered to a synthetic anonymous class so the accessor body gets a real this reading/writing the object's own fields.

The base Error constructor.

A small fixed kind enum (a hidden runtime tag on the shared Error object shape, not a real class hierarchy), plus a real .name field. instanceof Error matches any kind; instanceof TypeError matches only that one. new DOMException(message?, name?) takes its .name from the 2nd argument. The ES2022 error-options bag works too: new Error(msg, { cause }) stores any value as err.cause (default undefined), preserved through throw/catch.

Constructs an array of length n.

Constructs a Map.

Constructs a Set.

Instances reuse the same heap-object/GEP machinery interfaces use; methods compile to plain static calls (this as an implicit first arg). Instance-field initializers work, and a class with fields needs no explicit constructor. Static field initializers run in declaration order. Qualified constructors/bases parse.

class Point {
  x: number;
  y: number;
  constructor(x: number, y: number) {
    this.x = x;
    this.y = y;
  }
}
const p = new Point(3, 4);

A visibility/readonly modifier on a constructor parameter (public/private/protected/readonly) both declares the field and assigns it from the parameter — the TypeScript shorthand for the declare-plus-assign boilerplate.

class Point {
  constructor(public x: number, public readonly y: number) {}
}
const p = new Point(3, 4);
console.log(p.x, p.y);

static members are inherited through extends (a non-redeclared static field shares its base's storage). private/protected are compile-time-only (zero runtime check, matching TS erasure), checked with tsc's own diagnostics (including super.privateMethod() and private or protected constructors); o["p"] reaches a private member, as in TypeScript. abstract reuses override-detection; implements is checked by the type checker (tsc's TS2420).

Fields, methods, static fields/methods, and get/set accessors — exact-class-only access (the same rule private enforces), plus real reflection-hiding (Object.keys/.values/.entries/JSON.stringify/spread never see a #-named field, unlike private's type-level-only erasure).

Single inheritance, base-first field layout, super(args)/super.method(args), and an implicit pass-through constructor when a derived class adds no fields. Dispatch is static except for a method provably overridden somewhere, which goes through a per-tree vtable (decided at compile time via whole-program analysis). extends also accepts the imported EventEmitter, with or without an event-map type argument.

The instance is the promise itself: await, instanceof Promise and instanceof the class, passing it where a Promise is expected, console.log as Node shows it (Timed [Promise] { 'x', label: 'timed' }), and Promise's then/catch/finally and statics (resolve, reject, all, race, allSettled, any) making instances of the class through its constructor, as Node's species does. The same holds through any.

The instance is the RegExp itself: test and exec, source, flags and lastIndex (read and written) on it and through super, the string methods that take a RegExp (replace, split, match and the rest), new RegExp(r), instanceof RegExp and instanceof the class both ways, passing it where a RegExp is expected, String(r), the same through any, and console.log as Node shows it (Slug /[^a-z0-9]+/g { label: 'slug' }).

The instance is the Date itself: new D(…) and super(…) take Date's arguments, Date's getters and setters act on it, an override (toString) wins, and instanceof Date and the class both ways, String(d), +d, JSON.stringify, passing it where a Date is expected, the same through any, and console.log as Node shows it (Day 2024-02-28T00:00:00.000Z).

The instance is the array itself: elements and length, every Array (or typed array) method on it and through super, an override reached even through a plain number[], species results (map, filter, slice, subarray) and from/of making instances of the class, Array.isArray, instanceof both ways, destructuring, spread, Object.keys/values/entries, for…in, passing it where an array is expected, the same through any, and console.log as Node shows it (Stack(2) [ 1, 2 ], Bytes(3) [Uint8Array] [ 1, 2, 3 ]). A static [Symbol.species] override is a compile error, and a species result that changes the element type (a generic map<U> override returning super.map, or Array's map through any) is a plain array.

The instance is the collection itself: Map's or Set's methods and size on it and through super, iteration and spread as the host's, instanceof Map and instanceof the class both ways, passing it where a Map or Set is expected, the same through any, and console.log as Node shows it (Visits(2) [Map] { 'Athens' => 2, x: 1 }). Extending Array or a typed array is not supported yet.

Every instance carries a hidden runtime type tag. A class-typed variable whose static class is T or an ancestor of T folds to a compile-time constant; one whose static class is an ancestor of the right-hand class needs a real runtime tag read. instanceof against Array/Map/Set/Date/RegExp is a compile-time constant for a statically typed value; a value held in any is tested at run time.

Experimental class (constructor), property (target, key), parameter (target, key, index), and method (target, key, descriptor) decorators run at the class's source position — member decorators first, then class decorators (bottom-up). A method decorator receives a live descriptor whose value is the method as a callable; mutating descriptor.value or returning a new descriptor re-routes that method's calls through a per-method runtime slot. With -emit-decorator-metadata, decorated members and a decorated class's constructor get design:* metadata readable via Reflect.getMetadata.