Types#

Types are required on function parameters. A missing return type is inferred from the function's returns (Return types), and everything else is inferred too. type Name = … declares an alias; it is checked even where nothing uses it. An alias may refer to itself only when it is an object type, or an intersection of object types, written out (type Tree = { kids: Tree[]; v: number }): it is then the interface with those fields (Intersection types). An alias or interface may share its name with a constant or function, as in TypeScript (Types and values of one name). any and unknown hold a value of any type, checked at run time (any and unknown); dynamic JSON is JsonValue (velt/encoding/json).

The names TypeScript does not have (i8…i64, isize, u8…u64, usize, f32, f64, bool) are like library globals: a type alias, class, interface or enum of the module with one of these names, or one it imports, takes their place there, as a local Map would in TypeScript. So TypeScript code that declares type u8 = number compiles and behaves as in Node. A module that declares none of them has Velt's types. TypeScript's own names (number, boolean, string, …) cannot be declared.

Booleans#

boolean and bool are the same type, and either name can be used anywhere a type is written: annotations, generic arguments, unions and function types. boolean is TypeScript's name, so code that is shared with TypeScript uses it; bool is Velt's shorter name. Diagnostics, hover and inlay hints print boolean; velt fmt keeps the name you wrote.

function isEven(n: i64): boolean {
  return n % 2 == 0;
}

const check: (n: i64) => bool = isEven;
const flags: (boolean | null)[] = [check(2), null];
console.log(flags);               // [ true, null ]

Numbers#

number is a JavaScript number, always: an IEEE-754 double, with -0, NaN, ±Infinity and rounding past 2^53, exactly as in Node. The compiler stores a number as a 32- or 64-bit integer where it proves the result is identical (loop counters, indexes, % m sums, the result of | 0), so integer code runs at integer speed without changing what it computes. velt build --report numbers lists the number variables in loops that stay doubles, and why.

Integer types (i8..i64, u8..u64, isize, usize) and f32 are Velt's opt-in for speed and memory where you want a fixed width; code shared with TypeScript never names them.

Literals#

7 and 0.5 are numbers. Where an integer type is expected, a literal takes it: const n: i64 = 7, n + 1 with n: i64, f(2) with an i32 parameter, 300 as u8 (44). A suffix states the type: 7u8 is a u8. A module-level const N = 4 stands for its literal wherever it is used (TS types it 4): i < N with i: i64 compares integers. shared(0) is a shared<i64>, an atomic counter.

• Locals declared from literals: let i = 0 is a number unless the function uses i only as one integer type (Locals declared from literals).

The standard library hands you numbers#

Its JavaScript API (the globals Array, String, Map, Date, Math, fetch, URL, …) gives numbers where JavaScript does: xs.length, s.indexOf(t), m.size, Date.now(), res.status and the indexes of entries() and of array callbacks (inside the standard library they stay usize/i64). Velt's own modules (velt/db, velt/hash, velt/math, …) and the methods JS has no counterpart of (compareTo, leadingZeros, trailingZeros, countOnes) keep the integer types they declare, as do a program's and its packages' own functions and extend methods.

Where an integer type is expected, the standard library's integers convert by themselves#

Such a number is an integer below 2^53, so it converts implicitly to an integer type that holds every value it can have, as the integer itself (no conversion happens at run time). A length or a size goes into usize, u64, i64 or isize, and an index that can be -1 (indexOf) into i64 or isize. That covers a declared local, a parameter, a field, a return value or an explicit type argument, arithmetic, a shift or a compound assignment next to such an integer, and arithmetic with a literal where such an integer is expected (at(xs, xs.length - 1)). Otherwise it stays a number, as in TypeScript, also next to a local declared without a type:

function at(xs: string[], i: usize): string {
  return xs[i];
}
const xs = ["a", "b", "c"];
const n: usize = xs.length; // 3
let depth: usize = 1;
depth += xs.length; // 4
console.log(n, depth, at(xs, xs.length - 1)); // 3 4 c
console.log(xs.length / 2); // 1.5: a number

Narrower types still need as (xs.length as u32), and so does usize for indexOf. A number passed to an integer parameter of a standard library function converts like JS's ToIntegerOrInfinity (truncated; NaN is 0): xs.slice(0, xs.length / 2) takes the first half. A callback that the standard library expects to return a number, such as a sort comparator, may return an integer of any type: items.sort((a, b) => a.id - b.id) with id: i64.

Integers next to numbers#

i8..i32, u8..u32 and f32 convert to a number implicitly, because every value converts exactly (k * 0.5 with k: i32). i64, u64, isize and usize need as number, and a number going into a declared integer needs as T (n as usize). Comparisons are exact: i < xs.length with i: usize compares the integers.

Declared integers keep Rust semantics#

They wrap at their width, / truncates (7i64 / 2 is 3), / 0 and % 0 panic, ** is integer power, and % takes the sign of the dividend. On numbers, / 0 is Infinity, % 0 is NaN and -4 % 2 is -0, as in JS. Math.trunc(a / b) on integers is one integer division.

• as converts between number types with Rust semantics, and is TypeScript's type assertion for every other type (as).
• A float index (xs[i] with i: number, xs[Math.floor(n / 2)], xs[parseInt(s)]) must be a whole number at run time; anything else panics like an index out of bounds (JS reads undefined). Indexing with a quotient directly, xs[n / 2], stays an error: write Math.trunc(n / 2).

Bitwise operators on numbers are JS's 32-bit operators#

| & ^ << >> ~ take ToInt32 of their operands (truncate, then wrap modulo 2^32 into the signed 32-bit range; NaN and ±Infinity give 0) and >>> takes ToUint32; shift counts are taken modulo 32, and the result is a number: (a / 13) | 0 truncates, -1 >>> 0 is 4294967295, 1 << 32 is 1. A product inside such an operand rounds like JS's double multiply past 2^53, so (y * 0x2c1b3c6d) | 0 is Node's value; Math.imul(y, 0x2c1b3c6d) is the 32-bit wrapping product (one instruction). They compile to 32-bit integer instructions. Operands of a declared integer type keep their own width (n >>> 3 with n: i64 is a 64-bit shift), and so does a constant of two literals where an integer type is expected (const m: u64 = 1 << 40).

• Printing follows Node: 10, 1.5, 0.30000000000000004, 1e+21, NaN, Infinity. console.log(-0) prints -0 (also inside arrays and objects); `${-0}`, String(-0), (-0).toString() and JSON.stringify(-0) give 0.

const a = 7;                              // a number
console.log(a / 2, a + 0.5, -a * 0);      // 3.5 7.5 -0
const n: i64 = 7;                         // a declared integer: integer arithmetic
console.log(n / 2, Math.trunc(a / 2));    // 3 3
let small: u8 = 250;
small += 10;                              // wraps: 4
console.log(small, n as number / 2, 300 as u8);  // 4 3.5 44
const h = 0x12345678;
console.log((h * 0x2c1b3c6d) | 0, Math.imul(h, 0x2c1b3c6d), -1 >>> 0); // -1019940576 -1019940584 4294967295

function collatz(start: i64): i64 {
  let x = start;
  let steps = 0;                          // returned as an i64: an i64
  while (x != 1) {
    x = x % 2 == 0 ? x / 2 : 3 * x + 1;
    steps++;
  }
  return steps;
}
console.log(collatz(27));                 // 111

Locals declared from literals#

let i = 0 declares a number, unless the function uses i only with one integer type T and never as a number; then i is a T, as if declared let i: T = 0. So let steps = 0; … return steps in a function returning i64 counts in an i64, and let i = 0; i < n with n: i64 makes i an i64.

• A use with T is assigning, passing, returning or storing the local (or arithmetic on it: acc + i) where a T is expected, or combining or comparing it with a 64-bit integer of type T.
• A use as a number is combining it with another number (0.5, xs.length), /, **, a number parameter or a method call on it, and a bitwise operator unless the other operand is a 64-bit integer (x << 40 shifts by 8, as in JS).

Arithmetic (+ - * %, -x, +=, ++) on a local allows only a 64-bit T: let n = 200; takeU8(n); n + n would wrap in a u8, so n is a number and takeU8(n) needs n as u8. Only types the program names count: passing the local to an integer parameter of the JavaScript API (s.slice(k)) or using it as an index (xs[k]) leaves it a number, which the optimizer stores as an integer where that gives the same results.

Locals used together (x = y, x + y) get one type. A local used both ways stays a number, and each use as T is an error that says why, with the fix: declare the type (let i: i64 = 0, which makes / on it integer division) or convert (i as i64).

as#

as converts with Rust semantics: floats truncate and saturate (3.9 as i64 is 3, NaN as i64 is 0), integers wrap (300 as u8 is 44, -1 as u8 is 255). So x as i32 (saturates) and x | 0 (wraps modulo 2^32, as in JS) are different operations.

To any other type, as is TypeScript's type assertion and converts nothing: the expression is typed as if annotated with that type, so a literal takes its shape ([["a", 1]] as [string, u8][], [] as string[]), and it must be a value of that type.

Checked assertions#

An assertion that narrows is checked like x!: TypeScript trusts it, Velt panics with type assertion failed: … when the value is not a T. Such assertions are:

• x as T with x: T | null (or | undefined);
• u as A with A a member of union u;
• u as A | B (also | undefined) with some of u's members; u as A | B of a u: A | B | C | undefined panics on a nothing as u! does.

In generic code, x as T of an x: T | undefined is checked only where T has no undefined of its own: at T = U | undefined every value of x is a T and passes as it is. At T = U | null an undefined is no T value (Velt's U | null cannot hold one), so it stops with a TypeError instead of reading as null: an assertion never changes the value.

u as A with A a member of u is checked in generic code too (mod as Mod<T> with mod: T | Mod<T>), and so is a union of some of u's members that are not themselves type parameters (r as Ok<T> | Err with r: Ok<T> | Err | Pend). Where a member is a type parameter, the check follows the instantiation: at T = unknown (or any) every value is a T, so x as T of an x: T | string holding a string passes, and mod as Mod<T> of a T converts that unknown as u as Mod<unknown> would.

Tuple assertions#

A tuple asserts element by element (t as [object, string] with t: [any, string | symbol]), each element converted or checked as it would be alone. The result is a new tuple of those elements, so a write into one of the two tuples does not show in the other, and t2 === t is false (an element that is an object is the same object in both).

Field reads of an assertion#

A field read of such an assertion, (u as A).f with u a variable or a field path (outside generic code) whose union has as a member the object type A, which has the field f, reads as JavaScript does instead of checking the assertion. An A gives its field, and a value of another member gives its own property f: another object type's field f, the length of an array or a string, and undefined for an array, a string, a number, a boolean or an object type that has no such property. null or undefined stops with Node's TypeError: Cannot read properties of null (reading 'f') ((u as A)?.f is undefined there). A member whose property needs a lookup at run time (a class instance, which may be of a subclass, or a member of a prototype such as an array's map) checks the assertion.

The read has the field's type. Where it is only tested, the value read is tested as it is: in a condition (of if, a loop or ?:, and the operands of !, && and || there) its truthiness, and in === undefined, == null, ??, ?. and typeof its value, undefined included. So the common test of one member's field works as in Node:

type VNode = { type: string; props: number };
type Child = VNode | string | number | Child[];
function describe(c: Child): string {
  if ((c as VNode).type) return "node " + (c as VNode).type;
  if (Array.isArray(c)) return c.length + " children";
  return "text";
}
console.log(describe([1, "a"]), describe({ type: "div", props: 1 }), describe("s"));
// 2 children node div text

Used as a value, the property read converts to the field's type, checked: an array's undefined read as a string field stops with TypeError: the value is not a string (it is undefined), where Node goes on with undefined. An operand of <, >, <=, >=, -, *, /, % and ** is the exception: there a number field's undefined is NaN, which gives Node's answer ((c as A).count > 0 is false, (c as A).count - 1 is NaN). A method call (u as A).m() and a write (u as A).f = v check the assertion (a call of what another member holds would be a TypeError in Node too, unless it has a method of that name), and so does a member whose property needs a lookup at run time, also under typeof: typeof (c as A).at of a string stops with type assertion failed (Node answers "function").

Precedence#

As in TypeScript, as and satisfies take a whole type: x as A | B is a union and x as A & B an intersection (a leading | may start the type on the next line), so a bitwise operator after a cast needs parentheses: (x as i32) | y. A number literal after | in a cast type (x as i32 | 1) is an error that shows both spellings, (x as i32) | 1 and x as (i32 | 1).

Strings#

A string is an immutable value, like in JS: assign it, pass it, return it, store it, capture it, take it out of a field, an array element, a for...of element or Map.get. The source stays usable and no copy method is needed.

• + concatenates two strings; s += x appends to a variable or field in place when s holds the only reference to its text, growing it geometrically, so building a string in a loop costs time linear in its length. s = s + x and s = `${s}${x}` append the same way. Other copies of s never change.
• + with a string on one side and a number or boolean (or one of those or null) on the other concatenates, as in JS: "Total: " + 5 is "Total: 5", "a" + true is "atrue" and s += n appends. The number is written as String(n) and console.log write it (1.5, 1e+21, NaN, Infinity, 0 for -0). An array or a tuple is written as join() writes it ("" + [1, 2] is "1,2"), a class instance by its valueOf() when that returns a primitive (+ asks for it before toString(), as in JS; a Date by its toString()), else by its toString(), and a value whose type is a type parameter as String(x) writes the type it is instantiated with (an any and a class instance with +'s order: valueOf() first), also inside another type ("v=" + t[k] with k: K extends keyof T). Any other value next to a string is written as String(x) writes it: "" + s of a string | string[] | null is "k,l", "x" or "null", an object without a toString() is [object Object], a map [object Map]. A function value there is a compile error.
• String(x) converts any value that can be printed to its text, exactly as `${x}` writes it (String(1.5) is "1.5", String(null) is "null", String([1, 2]) is "1,2", also when the array is held by a union: String(x) of a string | number[] or a T | string). Number(x) converts a string (as JS: the whole trimmed string, "" is 0, else NaN), a number or a boolean (1 / 0); Boolean(x) is x's truthiness. They are called as functions, not as values (xs.map(String) is not supported yet: write xs.map((x) => String(x))).
• A template literal writes ${x} as JS's String(x) does (Lexical structure): an array's elements joined with , (${[1, 2]} is 1,2, nested arrays the same way, null elements as empty text, a class instance through its toString(), another object as [object Object], a map as [object Map], a set as [object Set]), and a class instance through its toString(), else as [object Object]. An array whose elements JS writes with a method Velt cannot call there (a struct's toString(), an Error, a RegExp) is a compile error in a template literal, in join and in toString(): write `${xs.map((x) => x.toString()).join(",")}`.
• A string is a sequence of UTF-16 code units, as in JavaScript: s.length counts them, and every position (slice, indexOf, charCodeAt, padStart, regex offsets, s[i]) is a code-unit index. A character outside the Basic Multilingual Plane, such as an emoji, is two units (a surrogate pair): "Zoë".length is 3 and "😀".length is 2. A position may fall between the two halves of a pair; slicing there keeps the half as a lone surrogate ("😀".slice(0, 1) is "\uD83D"), and gluing the halves back together gives the pair again. Output writes a lone surrogate as U+FFFD. The byte size of a string in UTF-8 is Buffer.byteLength(s).
• s[i] is s.charAt(i): the code unit at i as a one-unit string, or "" past the end (JS: undefined). for (const c of s) and [...s] iterate the characters (code points: a pair is one element), as JS's string iterator does; s.split("") gives code units.
• Methods: slice substring indexOf lastIndexOf includes startsWith endsWith split trim trimStart trimEnd toUpperCase toLowerCase replace replaceAll repeat padStart padEnd charAt at charCodeAt, plus String.fromCharCode, parseInt, parseFloat, String(x) and Number(s) (prelude).
• <, > and sort() without a comparator compare by code units, as JS ("～" < "😀" is false); == compares content.
• Cost model: strings of up to 23 bytes (22 when they are not ASCII) are stored inline (no heap allocation); longer ones live in a reference-counted immutable buffer. A copy is 24 bytes plus, for a heap string, one count increment, and the compiler moves instead of copying at a last use. s.clone() compiles and is just a copy. Text is stored as UTF-8 (files, sockets and HTTP bodies need no conversion), with the code-unit count kept in the value: length is a load, and indexing ASCII text reads a byte. Indexing other text translates the position: a step from the last position of the same string, so a sequential loop over one or two strings at a time stays linear (each thread remembers its last two long non-ASCII strings), or a lookup in a table built for long strings plus a scan of at most 63 units (random access to long non-ASCII text is several times slower than in JS engines; in a long non-ASCII literal, which has no table, it scans from the closer end).
• A slice or substring of a heap string (and a piece from trim or split) that is at least a quarter of its buffer shares the buffer instead of copying (as JS engines' sliced strings do), so a parser that consumes its input with rest = rest.slice(n) runs in linear time. A smaller piece is copied, so a short slice never keeps a much larger string alive: live slices hold at most four times their own size.
• A string holds less than 2 GiB of text (more than JS engines allow). Making a longer one stops the program with string too long (repeat panics with JS's RangeError message instead).

function label(name: string, count: i64): string {
  let s = name;                   // a copy: `name` stays usable
  s += ":";
  return `${s} ${count} (${name.length} units, ${Buffer.byteLength(name)} bytes)`;
}

console.log(label("tea", 3), "a,b".split(","), "  x ".trim().padStart(3, "*"));
// tea: 3 (3 units, 3 bytes) [ 'a', 'b' ] **x
console.log(label("Zoë", 1), label("😀", 2));
// Zoë: 1 (3 units, 4 bytes) 😀: 2 (2 units, 4 bytes)

Symbols#

Symbol(description?) makes a new symbol, a value different from every other one and compared by identity; Symbol.for(key) returns the registry's symbol for key (the same one on every call), and Symbol.keyFor(s) its key. A symbol has a description (null where Node says undefined) and toString() (Symbol(description)); typeof s is "symbol", and console.log shows it as Node does. Symbols are Map keys and Set members. The well-known symbols are values too (Symbol.iterator, Symbol.asyncIterator, Symbol.toStringTag, …). Converting a symbol to a string implicitly (${s}, "k" + s, also of a string | symbol) is an error, as JavaScript throws a TypeError there; String(s) is allowed. Where the compiler cannot see the symbol, Velt panics with that TypeError (exit code 101) instead: joining an array or tuple that holds one ([s].join(), String([s]), ${[s]}, ${pair} of a [string, symbol], also of a (string | symbol)[] that holds one), and a template literal part whose type is a type parameter that is symbol or a union holding a symbol (`v=${x}` with x: T, called with a symbol; the union's other members are written as usual). Unlike Node's TypeError, this panic cannot be caught with try/catch. The API is Symbol.

A symbol a module constant holds names a member: [KEY]: T in an interface, an object type or a class, { [KEY]: v } in an object literal, o[KEY] and KEY in o. The constant is initialized with Symbol("...") (the description a string literal or a string constant) or Symbol.for("...") (TypeScript's unique symbol; const KEY: unique symbol = Symbol("k") declares the same), or with another such constant, and may be imported. Velt objects have fixed fields, so the compiler resolves these members while compiling: reading o[KEY] costs what reading a named field does. A symbol key known only at run time (a symbol made in a function) is an error: use a Map. In an object literal, a string key known only at run time ({ [o.tag]: v }, { [name]: v } with a local name) makes the object a Record<string, V>, as TypeScript gives it a string index signature. A module constant holding a string literal names that field the same way (const NAME = "name", [NAME]: T). In a declaration (an interface, an object type or a class), a string or number literal in brackets is the plain name (["k"]: number is k: number; [1]: string and 1: string name the member "1", [-1]: string the member "-1", 1e3: number the member "1000"), also after a modifier (readonly 7 = 4), and so in a destructuring pattern (const { 1.5: a, [-1]: b } = o). [-0] names the member "0", as String(-0) is in JavaScript (TypeScript's checker reads it as "-0"). Such a name is for fields: a method or accessor named by a literal (["a-b"]() {}, get "c d"(), get 1(), 1e3() {}) is not supported yet. A symbol made in place ([Symbol("x")]: v, also in an object literal) is an error that asks for a module constant. An enum member names the member its value spells, as in TypeScript: [ReactiveFlags.SKIP]?: boolean with SKIP = "__v_skip" is the member __v_skip, and a numeric enum's member is its number ([Slot.First] is "0"). It works in declarations, in object literals ({ [ReactiveFlags.SKIP]: true }), in o[ReactiveFlags.SKIP] (also as an assignment target) and in ReactiveFlags.SKIP in o, also with an imported enum. In a destructuring pattern, a computed key is a string or number literal or a name ({ [KEY]: v } = o); a path or another expression ({ [t.tag]: v } = o) is an error: store the key in a variable first (const k = t.tag; const { [k]: v } = o). A class or interface may declare a method, getter or setter with such a key ([KEY]() {}, get [KEY]()) or a well-known symbol key (get [Symbol.toStringTag]()); o[KEY], o[KEY](), o[KEY] = v and KEY in o find it. A quoted key is an ordinary string key, also one that reads like a symbol ("[x]", "[Symbol(k)]"); only names starting with "[Symbol. or with the noncharacter U+FFFF are reserved (Velt names symbol-keyed members with them). console.log shows a symbol-keyed member after the others as [Symbol(description)]: v, and JSON.stringify and Object.keys leave it out, as in Node; JSON.parse never fills one, whatever keys the text has (a required symbol-keyed field makes the decode fail).

A literal asserted to a type may carry a symbol-keyed member the type doesn't declare ({ type, props, [VNODE]: true } as VNode): TypeScript allows it and the object keeps the member, so Velt adds the optional field [VNODE]?: boolean to VNode (an interface or an object type alias of the program; the field's type is the literal value's, any for another value or for literals of different types). Objects built without it don't have it, as in Node: console.log shows it only where it is set, spreads copy it, VNODE in v tests it, and it is read and written through any ((v as any)[VNODE] === true, (v as any)[VNODE] = true on an object of a type that has the field). The key is resolved in the module of the literal, so the type may be declared where VNODE is not imported. Reading such a key through any from a value without fields (a string, number, boolean, array or function) gives undefined, as in Node.

const BRAND: unique symbol = Symbol("brand");

type Tagged = { tag: string };

function branded(tag: string): Tagged {
  return { tag, [BRAND]: true } as Tagged;
}

const a = branded("div");
const b: Tagged = { tag: "p" };
console.log(a, b, BRAND in a, BRAND in b); // { tag: 'div', [Symbol(brand)]: true } { tag: 'p' } true false
console.log((b as any)[BRAND] === true, { ...a }); // false { tag: 'div', [Symbol(brand)]: true }

KEY in o is true when o's type declares the member, false when it doesn't, and for an optional member ([KEY]?: T in an object type or interface) whether it is present, tested at run time (a class's optional field is always present, as TypeScript-compiled classes define it). On a union it answers for the member o holds, and in an if it narrows the union to the members that may have the key, as TypeScript does. Symbol.iterator in o and Symbol.asyncIterator in o answer from the type's methods: arrays, Maps, Sets and generators have Symbol.iterator, async generators Symbol.asyncIterator, and Symbol.asyncIterator in g() on a generator is false. Another well-known symbol in a built-in object (Symbol.toStringTag in m) is an error rather than a guess.

const VNODE: unique symbol = Symbol("vnode");
const MODEL = Symbol.for("app.model");

interface VNode {
  type: string;
  [VNODE]: true;
}

function isVNode(v: VNode | string): boolean {
  return typeof v !== "string" && v[VNODE] === true;
}

type Cell = { value: number; [VNODE]?: boolean };

function describe(c: Cell | VNode): string {
  if (VNODE in c) {
    return "vnode or marked cell";
  }
  return `cell ${c.value}`;
}

const n: VNode = { type: "div", [VNODE]: true };
console.log(n, isVNode(n), VNODE in n); // { type: 'div', [Symbol(vnode)]: true } true true
console.log(JSON.stringify(n), MODEL === Symbol.for("app.model")); // {"type":"div"} true
const tokens = new Map<symbol, string>();
tokens.set(MODEL, "model");
console.log(tokens.get(Symbol.for("app.model")), typeof VNODE); // model symbol
console.log(describe({ value: 1 }), describe({ value: 2, [VNODE]: true })); // cell 1 vnode or marked cell

A module constant initialized with Symbol(...) or Symbol.for("...") is one symbol for the whole program, made while compiling (module constants are otherwise evaluated at each use), so reading it costs no call; Symbol.for(k) at run time gives that same symbol for its key. A symbol Symbol(...) makes at run time lives until the program ends. A symbol brand added with Object.defineProperty(o, KEY, …) is an optional symbol-keyed field of o's type (Object built-ins). A record holds symbol keys made at run time too (see Record<K, V> in Objects, arrays, tuples and maps). PropertyKey is TypeScript's string | number | symbol; a proxy trap's key is a string | symbol.

SIMD vectors#

A SIMD vector holds several numbers of one type, its lanes, and an operation on it works on all of them with one CPU instruction: a u8x16 is sixteen u8, an f32x4 four f32. The types are i8x16 u8x16 i16x8 u16x8 i32x4 u32x4 i64x2 u64x2 f32x4 f64x2, each 128 bits, which every x86-64 and arm64 CPU has: the same source compiles everywhere, with no CPU flag, in debug and release builds. On WebAssembly they are v128 values: WebAssembly SIMD is part of Velt's WebAssembly baseline, and a program that uses vectors needs an engine with it (every current browser and runtime). They are Velt's own, and not global: a module imports the ones it names from velt/simd (import { u8x16 } from "velt/simd";), so a module that does not is free to use these names for its own types, as TypeScript code may.

A vector is a value like a number: it is copied when assigned or passed, lives in a register, and can be a field, an array element, T | null or a Map value. Its operations are methods (simd), not operators, and it has no ==, truthiness, printed or JSON form: comparing two vectors with eq, lt, … gives a mask (mask8x16 for a u8x16), one lane per lane, set or not, which any(), all(), first(), count() and bitmask() turn into a boolean or a number and select into a choice between two vectors.

import { u8x16 } from "velt/simd";

// The position of the first `b` in `d`, sixteen bytes at a time.
function indexOf(d: u8[], b: u8): i64 {
  const needle = u8x16.splat(b);
  let i: usize = 0;
  while (u8x16.fits(d, i)) {
    const found = u8x16.load(d, i).eq(needle);
    if (found.any()) {
      return (i + found.first()) as i64;
    }
    i += 16;
  }
  while (i < d.length) {
    if (d[i] == b) {
      return i as i64;
    }
    i++;
  }
  return -1;
}

const text: u8[] = Buffer.alloc(100);
text[70] = 33;
console.log(indexOf(text, 33)); // 70

load and store panic with a RangeError unless the whole vector is inside the array, and lane(i) unless i is a lane. fits(xs, i) is the test they make: in a loop that runs while it holds, as above, nothing is left for them to check. A loop over plain numbers is often compiled to the same instructions without any of this (summing an array, adding two arrays); vectors are for the loops it cannot do that for, such as one that stops early, or a sum of floats, whose order it must keep.

Equality and comparison#

• == and === (and != and !==) differ only against null and undefined, as in JavaScript: x == null and x == undefined match either nothing, === only the one written (Null and undefined). Everywhere else they are the same operator: there is no coercion, and the operands' types must overlap, as in TypeScript (1 == "1" is a compile error; an i64 compared with an i32 needs a cast). An interface value compares with a value of a class or struct that implements it, and a base class value with a subclass value.

• Numbers, bools and strings compare by value. Objects (class instances, arrays, maps, structs, object literals, interface and function values) compare by identity, like JS: [1] == [1] is false, and a == b is true when b refers to the same object as a. T | null, unions and tuples compare their parts that way. A T | null compares with a T (in either order) as if both were T | null: null equals no value. Likewise a union compares with one of its members (string | number with number): the two are equal when the union holds that member with an equal value, so the string "3" never equals the number 3, as with === in JS.

• Every number is a number, though: in a union of several number types (f64 | u8, which [bytes[0], bytes.length] has) two values are equal when their numbers are, whichever members hold them, so 1.0 equals 1u8 (in ===, switch, Map and Set keys, indexOf, includes and deepEqual), and x === 1 tests every member that can hold a 1. A number literal type is a number member too: in 1 | 2 | u8, the 1 equals 1u8. The comparison is exact: an i64 above 2^53 equals no f64 it only rounds to. A literal goes to a member that can hold it (256 as f64 | u8 is the f64); when none holds it exactly, a float member takes it rounded, as a plain float type does (x === 0.1 with x: f32 | u8 tests the f32 nearest 0.1). includes finds a NaN in a union array, as in a number[]; indexOf doesn't, as in JS.

  ts

  const bytes = new Uint8Array([7]);
  const pair = [bytes[0], bytes.length]; // (f64 | u8)[]
  console.log(deepEqual(pair, [7, 1]), pair.includes(1)); // true true

• An interface value compares the object behind it: two Shape values of one class instance are equal. A function value is equal to its copies, and a named function to itself; each evaluation of an arrow or function expression is a new function, as in JS, also when it captures nothing (so emitter.off(h) finds the h given to emitter.on(h), and two arrows made by one loop differ). indexOf, includes, Set elements and Map keys agree with == (includes and keys also find NaN, as in JS), except that Map and Set keys of a struct type compare by content. Comparing costs only the programs that do it: there, an arrow without captures gets an empty environment of its own when it is created, and a struct converted to an interface value that is compared is counted, so the interface value refers to it rather than to a copy.

  ts

  const h = () => console.log("h");
  const handlers = [h];
  const fresh: (() => void)[] = [];
  for (let i = 0; i < 2; i++) {
    fresh.push(() => console.log("h"));
  }
  console.log(handlers.indexOf(h), h === h, fresh[0] === fresh[1]); // 0 true false

• Content comparison: deepEqual(a, b) (prelude) compares arrays, structs and object literals by their contents, recursively; maps and records by their keys and values, in any key order; other class instances by identity. A value that holds itself (a ring of object values) compares without looping: the same cycle on both sides is equal. assertEq uses it.

• <, <=, >, >= work on numbers and strings, and on a class or struct implementing Comparable (Date, DateTime) or a generic T extends Comparable<T>: a < b is a.compareTo(b) < 0 (Comparable).

Null and undefined#

null and undefined are two values, as in JavaScript. A value that may be absent has type T | null, T | undefined or T | null | undefined (A | B | undefined for a union), stored without an extra allocation where possible; T | null and T | undefined take the same space, and T | null | undefined holds a T | null with one more flag. undefined behaves as in Node:

function find(xs: string[], s: string): string | undefined {
  return xs.includes(s) ? s : undefined;
}

const a = find(["x"], "y");
console.log(a, typeof a, a === undefined, a == null); // undefined undefined true true
console.log(a ?? "none", `${a}`, [a]);                 // none undefined [ undefined ]
console.log(JSON.stringify({ a, b: 1 }), JSON.stringify([a]));    // {"b":1} [null]
const v: number | undefined = void console.log("ran"); // `void e` evaluates `e`: undefined

A T | null | undefined keeps the two apart: x === null and x === undefined each test one, x == null both, and typeof, printing and JSON.stringify see which one it holds. x !== undefined narrows it to T | null, x !== null to T | undefined, and both tests (or x != null, or truthiness) narrow it to T. Compared with a T | null or a T | undefined, === tells the nothings apart and == does not, as in Node. A conditional with both a null and an undefined arm (i === 1 ? null : i === 2 ? undefined : i) is a T | null | undefined. A generic union whose type argument brings a nothing (T | string | undefined at T = number | null) holds it like the union written out (number | string | null | undefined): == null, ===, ?? and narrowing see it, inside the generic function too. At T = unknown (or any) such a union (T | string, T | Mod<T>) holds any value: one that is no other member's is its unknown member's (null, 0, an object literal of no member's shape: other fields, values its fields cannot hold, judged for literals and for variables and field paths by their types, or a discriminant no member has), and null tests (also a == b of a null and an undefined), truthiness (!x, if (x), &&, ||), ??, ??=, ?., typeof (also typeof x === "number" and switch (typeof x)), printing and JSON.stringify ask that value itself, as they do a plain unknown. Where typeof x === "string" holds, x reads as a string also when generic code put the string in the T member (s<T>(v) with v: T passed to s<T>(x: T | string)). A variable or field of a type parameter passed for such a parameter (i<T>(v) with i<T>(x: T | Foo), also T | null, T | undefined and T | Foo | null) goes to the member its value belongs to at T = unknown (or any), as an unknown passed where the type is written out does, so x instanceof Foo, x === null, x === undefined, x === true and x === "a" see a Foo, a nothing, a boolean or a string that generic code passed; at other instantiations the value passes as it is. A value passed another way (a call's result passed as it is: i<T>(f(v))) stays in the T member. a == b of two values of a type parameter's type (also T | null | undefined) compares with JavaScript's coercions at T = unknown or any (1 == "1"), as == on any does. An any or unknown converted to it (const n: number | null | undefined = v, v as T | null | undefined) gives null for a null and undefined for an undefined. Converted to a T | null or a T | undefined, it gives the nothing that type has, and stops with a TypeError for the other one (const n: number | null = v with a v holding undefined), as for any other value the type cannot hold: Node would keep the undefined. undefined alone is a type too (its only value is undefined), and an undefined with no type to take has it (const u = undefined, [1, undefined] is a (number | undefined)[]), and a conditional of null and undefined with no type to take is a null | undefined (const d = c ? null : undefined). A let x: T | undefined; without an initializer starts as undefined, and so do let x: any; and let x: unknown;. null alone is a type as well, as in TypeScript's discriminated unions where a field is always null in one member ({ st: "idle"; value: null } | { st: "ready"; value: number }).

function show(x: string | null | undefined): string {
  if (x === undefined) return "undefined";
  if (x === null) return "null";
  return x.toUpperCase();
}

const xs: (string | null | undefined)[] = ["a", null, undefined];
console.log(xs.map(show), xs.map((x) => typeof x)); // [ 'A', 'null', 'undefined' ] [ 'string', 'object', 'undefined' ]
console.log(JSON.stringify({ a: xs[1], b: xs[2] }), xs[2] ?? "d"); // {"a":null} d
let later: number | undefined;
console.log(later, [1, undefined]); // undefined [ 1, undefined ]

x == null and x == undefined match either nothing; x === undefined tests a T | undefined for its nothing, and x === null on a T | undefined is false (!==: true) and narrows nothing, as in Node. tsc accepts it; Velt warns (this `=== null` is always false: `string | undefined` is never `null` ), since it is usually a test of an optional parameter or field written for null, which is undefined when left out: write x == null to test for either nothing, or x === undefined. switch compares like ===. typeof x === "undefined" narrows, ?. on a value that may be undefined gives undefined (a T | null result becomes T | null | undefined), and JSON.stringify leaves out a field holding undefined and writes an array element as null. A destructuring default applies where the value is undefined (an undefined element or field, an absent optional field, a too short array), never to a null a field or element is declared to hold: const { a = 1 } = o keeps the null of a field a: T | null, and of an optional a?: T | null that holds null. sort(cmp) and toSorted(cmp) on a (T | undefined)[] never pass an undefined element to cmp and put those elements last. return undefined; in a void function is return;, and return void e; (or an arrow body (): void => void e) is e; then return;. T | void is T | undefined (a void function's value is undefined), so a callback typed (e: Error) => boolean | void may return a boolean or nothing. A function whose result type allows undefined returns it from a bare return; and when it reaches its end; one whose result type is inferred, that returns values and also return; or can reach its end, returns T | undefined, as in TypeScript. null where T | undefined is expected, and undefined where T | null is, are errors (TS2322), also for a T | undefined value where a T | null is expected and the reverse.

A parameter's default applies where the argument is undefined, as in JavaScript: f(undefined) and f(v) with a v: number | undefined that holds undefined give function f(x = 5) its 5. So does a T | null | undefined value for a T | null parameter with a default (before: Node | null = null given a before?: Node | null): undefined takes the default, a null stays null. A parameter whose type allows undefined may have a default too (function f(x: number | undefined = 5), or status = 302 in a method whose interface declares status?: number); it is a number in the body.

function label(n: number = 1, unit: string = "px"): string {
  return `${n}${unit}`;
}

function inc(n: number | undefined = 7): number {
  return n + 1;
}

const found = [1, 2].find((x) => x > 5); // number | undefined
console.log(label(found), label(undefined, "em"), inc(), inc(undefined), inc(1)); // 1px 1em 8 8 2

Not supported yet, each with a precise error: null | undefined alone as a written type, JSON.stringify of a value that may itself be undefined and JSON.parse into a type holding undefined; x === undefined and typeof x === "undefined" on a T | null (its null may be JavaScript's undefined, see below; x == null tests for either) and case null / case undefined with the nothing the type lacks; as between T | undefined and T | null; a parameter default other than undefined on a parameter whose type allows both nothings (T | null | undefined); and a type argument whose nothing differs from one the generic keeps of it, directly or through what it calls (undefined, or a T | undefined, for a generic function holding a T | null), which includes a generic alias applied that way (type Nullable<T> = T | null as Nullable<number | undefined>). The other way round is supported: a generic holding a U | undefined at U = T | null holds a T | null | undefined. A Map or Record value type may allow either nothing or both (Map<string, number | null | undefined>, Record<string, V | undefined>): an entry holding null or undefined is present (has, size, Object.keys, iteration and console.log list it) and reads back as what it holds, a missing key reads undefined, and JSON.stringify leaves out an entry holding undefined and writes null, as Node does. JSON.parse into a type holding a T | null | undefined (as Record<string, V | null | undefined>) reads each value as its T | null, since JSON has no undefined; into a T | undefined without null it is not supported yet. Also not supported yet, although TypeScript accepts them:

• a type argument that allows undefined for generic code that sorts an array of its type parameter (xs.sort(cmp) inside function f<T>(xs: T[], …)): an undefined element would reach the comparator;
• JSON.stringify of a value holding a class whose toJSON() may return undefined (its own or a subclass's).

The standard library#

Where TypeScript's lib.d.ts says undefined, so does Velt's standard library, as in Node: a missing key of a Map (m.get("z")) or of an open Record (r["z"]), find / findLast with no match, pop / shift of an empty array, at out of range (arrays, strings, typed arrays), the value of a finished iterator's result, WeakMap.get, WeakRef.deref of a freed target, Symbol.keyFor and description of a symbol without one, and an unset process.env.X. Each gives a T | undefined (a T | null | undefined when T holds null: m.get("a") of a Map<string, number | null> tells a stored null from a missing key). Velt's own collections follow the same rule (Deque, PriorityQueue, SortedMap, BTreeMap). APIs whose lib.d.ts result is null keep it: RegExp.exec, String.match, Headers.get, URLSearchParams.get.

const m = new Map<string, number | null>([["a", null]]);
console.log(m.get("a"), m.get("z"), m.get("z") === undefined); // null undefined true
const xs = [1, 2, 3];
const none: number[] = [];
console.log(xs.find((x) => x > 5), none.pop(), xs.at(9));     // undefined undefined undefined

Indexing past the end of an array (xs[9]) still panics: TypeScript types it as T, not T | undefined. The helpers isNull, unwrap, unwrapOr and map work on these results as on a T | null (prelude).

Optional values#

Optional fields and parameters (a?: T) hold undefined when left out, as in TypeScript, and so do the standard library's lookups (see above). ??, ?., ! and x != null treat both nothings alike:

• x ?? d (default; x ?? null of a T | null | undefined is a T | null), x?.f / x?.m() (optional access; the result may be undefined), if (x != null) { … } and early exits narrow x to T (a local or a field path of one, see below), and so does a truthy chain that goes on after x?. (if (x?.m.has(k)) x.m.get(k), if (x?.ok())); switch supports case null and case undefined. The type of x ?? d is x's non-null type when d converts to it, else d's type when x's non-null type converts to that, else their union, as in TypeScript: with n: number | null, n ?? "none" is a number | string. Where an any (or unknown) is expected and one side is an any, it is an any (see || in Variables).
• x ??= d assigns d when x is null or undefined and narrows x (likewise x ||= d and x &&= d). Its value is x afterwards, which is not null when d is not, also for a module-level variable ((handlers ??= []).push(h)). The target may not call a function yet (m[key()] ??= v): store the key in a variable first.
• x! is x known to be neither null nor undefined, checked at run time (the non-null assertion).
• a?: T reads as T | undefined, and a?: T | null as T | null | undefined. An optional parameter b?: T is b: T | undefined = undefined (Functions): callers may leave it out or pass undefined (or a value that may be undefined), but not null (TS2322), and it cannot also have a default.
• An optional field of a class without an initializer is an own property holding undefined, as in Node with ES2022 class fields: console.log shows a: undefined, JSON.stringify leaves it out, and "a" in o is true. It can be set to null only when declared a?: T | null; it then prints null and JSON.stringify writes null. A spread always copies it, set or not (in a generic function too): over an earlier value of a field that can hold undefined its undefined overrides, as in Node, and over a required field ({ ...u, ...c } with u.n: number) an unset one stops the program with the TypeError of absent keys.
• An optional field of an object type or of an interface with only fields keeps an absent key apart from a key holding undefined, as Node does (absent keys).
• A spread of a conditional of object literals, { id, ...(c ? { boundaryId: id } : {}) }, adds the keys of the branch taken, as in Node (absent keys).
• An object literal may leave out an optional field ({ port: i64; host?: string } accepts { port: 80 }). A field of an object type declared a: T | null may be left out too, and is then null.
• In an object type, ? is part of the type, as in TypeScript: { a?: string } and { a: string | undefined } read alike but are different types (the first may be absent), with no implicit conversion between them; copy with { ...x }. Difference from TypeScript: TypeScript also accepts a { a: F | undefined } where a { a?: F } is expected; in Velt the two are different types (the second keeps a presence flag), so copy with { ...x } there.
• JSON.parse<T>: an absent key leaves an optional field absent (undefined). An explicit null for an a?: T field, whose type has no null, leaves it absent too (a Velt rule: the type cannot hold the null); for an a?: T | null field it is a present null. The TypeScript forms that take the type from the context, JSON.parse(text) as T and const t: T = JSON.parse(text), reject that null instead (expected string at $.a), as they reject a value of another type. A field declared a: T | null (not optional) may be missing, and is then null, as for an explicit null. A JsonValue always tells them apart: v.has("a") vs v.get("a")?.isNull().
• x?.a.b short-circuits the rest of the chain like TypeScript (undefined when x is null or undefined; .b is never evaluated). This holds for a T | null x too, as in JavaScript: with u: User | null, u?.name is a string | undefined, and a rest of type T | null gives T | null | undefined. Parentheses end a chain: (x?.a).b needs x?.a to be neither null nor undefined.
• Null checks narrow locals and field paths of locals (narrowing nullable values), and a variable a closure assigns until the next assignment (variables a closure assigns), and module variables and record entries (module variables).
• x == null, x != null, x === undefined and x ?? d are allowed on a value whose type has neither null nor undefined, as in TypeScript (a defensive check): the test is false (!=: true) and d is not evaluated. On an element read of an array, a string or a typed array (xs[i] ?? d, xs[i] == null) the index is checked instead, so past the end the result is d (true), as in JavaScript, where reading past the end gives undefined.
• const x = node.left / const row = grid[i] refers to the same object as the field or element (objects are references, Memory model); when the rest of the block replaces node.left, x keeps referring to the old object, as in JS.

class User {
  name: string = "ann";
  nickname?: string;              // starts as undefined
}

function greet(name: string, greeting?: string): string {
  return `${greeting ?? "Hello"}, ${name}`;   // greet("ann") works: greeting is undefined
}

function first(xs: i64[]): i64 | null {
  return xs.length > 0 ? xs[0] : null;
}

function doubledFirst(xs: i64[]): i64 | null {
  const f = first(xs);
  if (f == null) {
    return null;                  // early exit: f is i64 below
  }
  return f * 2;
}

const u: User | null = new User();
console.log(u?.name, u?.nickname ?? "(none)", doubledFirst([]) ?? -1, greet("bo"));
const f = first([4, 5]);
if (f != null) {
  console.log(f + 1);             // f is i64 here
}

The non-null assertion x!#

x! is x known to be neither null nor undefined (TS's non-null assertion). TypeScript trusts it; Velt checks it: a nothing panics with non-null assertion failed.

A write into a tuple behind ! or as (one that keeps the tuple's type, or a union's tuple member; an element-wise tuple assertion makes a new tuple, see as) changes the tuple in place, wherever it is held:

• a variable or a field;
• an element (h.t![0] = v, xs[i++]![1] = "q", g[r][c]![0] += 1), or a tuple inside such a tuple (g[0]![0]![1] = 9);
• a field read through an interface (iface.opt![0] = 3, is[q++].t![0]++);
• a union member ((u as [number, string])[0] = 9);
• the object a conditional or a call gives ((c ? a : b).t![0] = 5, ps.find(f)!.t![1] = "x").

Every index is evaluated once, before the right side. If the right side (or another task during its await) sets the field to null, the program panics with the tuple this assignment writes into was set to null while its right-hand side ran, where Node writes into the tuple the field held before; a right side that changes a union to another member panics with type assertion failed.

Absent keys#

An optional field of an object type or of an interface with only fields keeps an absent key apart from a key holding undefined, as Node does:

• an absent field is not printed by console.log, and "a" in o is false;
• { a: undefined } is allowed, prints { a: undefined }, and "a" in o is true;
• JSON.stringify leaves out both, and writes a present null (of an a?: T | null).

A spread ({ ...a, ...b }) copies a field b has over an earlier value, also one holding undefined or null, and keeps the earlier value where b lacks the field (update(u, { deletedAt: undefined }) below clears deletedAt, as in Node).

Where the target field is required and cannot hold undefined (a Partial<U> spread back into a U), a source that lacks the field keeps the earlier value, and one that holds undefined stops the program with a TypeError (a spread copies `undefined` into a field of type `string` ): Node would copy the undefined, which the field's type can't hold. Without a target type the field has the earlier part's type, as TypeScript types it ({ ...u, ...p } with u.n: number and p.n?: number has n: number), so the same holds there.

type User = { name: string; deletedAt?: string | null };

function update(u: User, patch: Partial<User>): User {
  return { ...u, ...patch };
}

const u: User = { name: "ann", deletedAt: "2026-01-01" };
console.log(JSON.stringify(update(u, {}))); // {"name":"ann","deletedAt":"2026-01-01"}
console.log(JSON.stringify(update(u, { deletedAt: null }))); // {"name":"ann","deletedAt":null}
console.log(update(u, { deletedAt: undefined })); // { name: 'ann', deletedAt: undefined }
const v: User = { name: "bo" };
console.log(JSON.stringify(v), "deletedAt" in v); // {"name":"bo"} false
console.log(update(v, { deletedAt: null })); // { name: 'bo', deletedAt: null }

A spread of a conditional of object literals, { id, ...(c ? { boundaryId: id } : {}) }, adds the keys of the branch taken, as in Node: the conditional is an object type in which a field only some branches write is optional (TypeScript's { boundaryId: number } | {}, spread as { boundaryId?: number }), so the key is absent when the other branch is taken. Each branch is checked under the narrowing of the condition (r ? { redirect: { ...r } } : {}); a key the branches write with different types has their union (c ? { k: 1 } : { k: "s" } spreads k: number | string; c ? { k: [1] } : { k: null } spreads k: number[] | null), and so does a key an earlier property or spread gives another type ({ k: false, ...(c ? { k: 1 } : {}) } has k: number | boolean). The result is one object type, not TypeScript's union of object types, so "k" in o does not narrow o.k (a present key may hold undefined): test o.k itself. A getter of a branch is called where the spread reads it, in property order, after the values written before it. A getter using this, or one that a value other than a literal follows, is not supported there yet (an error), and a setter keeps the literal's own rules.

Narrowing nullable values#

Narrowing applies to locals and to field paths of locals (this.x, node.left), like TypeScript (module variables: see below); assigning a non-null value narrows too (also in the declaration: let x: string | null = "a").

After an if or a switch, what holds is what each way out ends with: the facts of the condition a branch started from unless it reassigned the variable, and what its own statements established:

• if (x == null) { x = d; } narrows x after it; if (x == null) return; else x = null; does not;
• a case passes on what holds at its break;
• after a while loop without break its condition is false: while (y === null) { y = next(); }.

A narrowed field is re-checked where its payload is read (see module variables for where that is), so a call that set it to null in between stops the program with TypeError: `node.left` was checked, but it was set to null before this read (undefined for an optional field) instead of reading null. A field path of a local is read as its payload wherever no type is expected (const { n } = o.f, "n" in o.f, const c = o.f), and as it is in a log argument, a template, a + with a string and a test. Node's message for the same mistake is different (Cannot read properties of null (reading 'x')), and Node throws a TypeError a program can catch, where Velt stops. An optional member of function type can be called once a check narrowed it (if (o.onError) o.onError(e), if (def?.transform) def.transform(v)).

Inside a closure, a variable narrowed where the closure is created stays narrowed when the function assigns it nowhere after that (nor in a loop around the closure), as in TypeScript: the closure may run after such an assignment. It stays narrowed in the whole closure body, also after a branch or loop where the closure first names it.

Variables a closure assigns#

A null check (!= null, !== undefined, truthiness) of a variable that a closure assigns narrows it in the function that makes the check until the next assignment there, as in TypeScript (if (cleanupFn) cleanupFn();). A call in between may run the closure, so each such read checks the value again and stops with a TypeError if the closure set it to null (JavaScript throws one where it calls or reads through the null). The closures that capture the variable do not see the narrowing.

Other tests (typeof, instanceof, union members) do not narrow such a variable, where TypeScript keeps the narrowing: the variable may no longer hold what was checked. Test a const copy instead, which nothing can reassign; the error at such a use says so:

class Conn {
  send(msg: string): string { return `sent ${msg}`; }
}

let conn: Conn | string = new Conn();
const close = () => { conn = "closed"; };
const c = conn;                 // `if (conn instanceof Conn) { conn.send(…) }` is an error
if (c instanceof Conn) {
  close();
  console.log(c.send("bye"));   // sent bye
}

Module variables and record entries#

A module-level let (or a module const kept as module state), also an imported one, is narrowed by a null check in the function that makes it, as in TypeScript (if (handler) handler();, if (!ctx) return; ctx.onMounted(fn), if (app?.provides.has(k)) return app.provides.get(k)), and so are its field paths (if (state.next) state.next.name, typeof state.v === "string"). Any call may run code that assigns it (a function of its module, a callback, a getter, another task across an await, a generator's caller across a yield), so each narrowed read checks the value again, like a variable a closure assigns, and stops with a TypeError if it became null (`ctx` was checked, but it was set to null before this read).

The variable (or field path) is read as its payload only where that is needed: as a receiver (ctx.m(), ctx.n = 1), a callee, an operand of a numeric operator or a comparison (n + 1, n > 2, -n, s + 1, s + t with both narrowed), a spread (...xs), where the expected type does not take the value as it is (use(ctx) with c: Ctx, return ctx from a function returning Ctx, len(st.v) with v: string after typeof st.v === "string") or what a destructuring takes apart (const { name } = ctx). Elsewhere it is read as it is: console.log(ctx), JSON.stringify(ctx), an element of an untyped array (unlike TypeScript, [x, y] of two narrowed Box | null module variables, module fields or r[k] is a (Box | null)[], and holds null where a call cleared one), a template, a + with a string ("a" + s, s + "!", s += x, also a branch of a ternary there: "a" + (c ? s : "z")), ===, and where the expected type takes it (a parameter of type Ctx | null | undefined, or Base | null for a S1 | S2 | null of subclasses, or string | number for a field typeof narrowed to a string). So is the operand of a test, ?. or ??, so if (ctx) { reset(); ctx?.name } gives undefined, as in JavaScript.

• An untyped copy (let c = ctx, const c = state.next, const s = st.v after a typeof test, and a copy of such a copy) holds what it read, null or a value of another member included, and keeps the narrowing: its reads follow the same rule (console.log(c) prints null, c.name stops with a TypeError), and assigning it back (state.next = c, ctx = c) narrows the field or variable again, checked the same way.
• A write through a narrowed field path takes the object first, as JavaScript does: state.next.items[0] = f() writes into the object state.next held before f() ran, also when f() set state.next to null, and so do state.next.ts[0][1] = f() (a tuple in an array), state.next.p.x = f() (a struct or object field) and a.items[0] = a.items[1] = f(). A tuple right behind the narrowed field is a value, not an object, so state.t[0] = f() stops with the TypeError when f() cleared state.t.
• An assignment in the function drops the narrowing (and narrows to what it assigned), and so does a loop that assigns the variable. Closures don't see the narrowing of the function they are made in (TypeScript keeps it in one made after the variable's last assignment).
• typeof, instanceof and union-member tests do not narrow a module variable itself, and instanceof does not narrow its field paths: copy the value into a const and test that.

r[k] on a Record<string, V> with a key that is a const narrows like r.name: after if (!r[k]) r[k] = []; it is a V, and so is r[k] in for (const k in r). Assigning r or delete r[k] drops the narrowing; a read is checked again where its payload is needed, as a field's is, so a call that deleted the key gives undefined in console.log(r[k]).

let current: { name: string } | null = null;

function show(): void {
  current = { name: "ann" };
  if (current) console.log(current.name);            // ann
}

function group(words: string[]): Record<string, string[]> {
  const out: Record<string, string[]> = {};
  for (const w of words) {
    const k = w.slice(0, 1);
    if (!out[k]) out[k] = [];
    out[k].push(w);
  }
  return out;
}

show();
const g = group(["ab", "ac", "b"]);
for (const k in g) console.log(k, g[k].length);      // a 2, then b 1

Literal types#

A string, number or bool literal is a type with that one value: "circle", 42, -1, 1.5, 5u8, true. type Dir = "up" | "down" is a union of literal types.

• A literal takes a literal type only where one is expected (an annotation, a parameter, a field, a union with literal members); elsewhere it has its base type (const s = "up" is a string). A literal-typed value converts implicitly to its base type (const s: string = d;).
• Literal types work as type arguments too, negative numbers included: f<"x" | null>(), g<-1>(5). As in TypeScript, a < -1 stays a comparison: a literal after < starts type arguments only when >, | or , follows it.
• A literal type is zero-sized; a union of literals is only its tag. Printing, ${} and JSON.stringify show the value; typeof gives the base type's tag.
• JSON.parse checks a literal type against its value (expected "task" at $.kind).
• e as const is accepted and keeps the value as it is. An array literal of strings keeps their literal types and is read-only, like TypeScript's readonly ["a", "b"]: const NAMES = ["a", "b"] as const is an array of "a" | "b" (and ["a"] as const of "a"), so for (const n of NAMES) f(n) and f(NAMES[0]) pass a "a" | "b" parameter, and a readonly string[] parameter or variable, an Iterable<string> parameter and the array new Set<string>(…) copies from take it, or any array of a literal type (as a copy of strings, which the callee cannot tell apart, since it cannot write through the parameter). Other values need no readonly or literal-type annotation for it.

Union types#

A | B | C of any types is a tagged union. Member order and nesting don't matter; T | null is the nullable type; void cannot be a member.

• Widening is implicit: a member value (also a subclass of a class member, or a value implementing an interface member) converts to the union, and a union converts to a wider union. An array literal with no type from context whose elements have different types is an array of their union, as in TypeScript ([1, "a"] is a (number | string)[], and [a, d] of a number | undefined and a string | null holds all four). null and undefined elements make it allow them ([1, null] is a (number | null)[]), a nested array literal keeps its own type ([[1], ["a"]] is a (number[] | string[])[]), and [...xs, true] adds boolean to the spread arrays' element type. A literal takes the member it belongs to; add a suffix (5i32) when several number members match.
• Narrowing by typeof, instanceof, literals, in and assignment selects members (Narrowing).
• Printing and template literals show the active member's value. A union with a member that cannot be printed (a closure) prints once a test has narrowed it to members that can (typeof v !== "function"). JSON.stringify works on unions; JSON.parse decodes them when the JSON value tells the members apart (discriminated unions by their discriminant; see velt/encoding/json).
• A union of numbers, bools, strings and literals is copied; one holding an object refers to it like any other variable.
• A union alias may name itself behind an indirection: as an array's element, an index signature's or a Map's value, or in a function type, as JSON-like types do; its members may include null, undefined or both (type Child = Node | string | null | undefined | Child[]). A generic one (type Content<F> = string | F | Content<F>[]) is a union of its own at each type argument. Elsewhere (type L = number | { next: L }, a tuple) a value would contain itself, which is an error: give such a type a nominal member, such as an interface or a class.

type Json = string | number | boolean | null | readonly Json[] | { readonly [key: string]: Json };
type Tree = number | Tree[];

function depth(t: Tree): number {
  if (typeof t === "number") {
    return 0;
  }
  let max = 0;
  for (const k of t) {
    max = Math.max(max, depth(k));
  }
  return max + 1;
}

const v: Json = { a: [1, "x", { b: null }] };
console.log(JSON.stringify(v)); // {"a":[1,"x",{"b":null}]}
console.log(depth([1, [2, [3]]])); // 3

Narrowing#

Using a member's fields or methods needs that member, except x.toString(), which every member has: it gives what String(x) does (a class's own toString(), a primitive's text), also as x?.toString() on a union that may be null. These tests and assignments narrow a union:

• typeof x === "string" | "number" | "boolean" | "symbol" | "object" | "function" (and !==): all number types are "number"; classes, structs, arrays, maps and null are "object"; closures are "function". An impossible tag is an error. On a value that is not a union, a test it always passes leaves it never where the test fails, when its type fixes the answer (numbers, strings, booleans, symbols, functions, classes, structs, arrays, maps); not for object, which may hold a function, nor for interfaces with methods or enums. On a value whose type is a type parameter (also T | undefined), typeof tells the instantiation's value at run time, and x === undefined / x == null too (T may be undefined or null); for a variable, neither boxes the value.
• x instanceof C matches members whose class is C or a subclass. A member of a base class of C, or an interface value, is tested at run time and narrows to C (downcasts). x instanceof Promise matches the promise member (View | Promise<View>), when no class named Promise is in scope.
• x == literal / x != literal selects the literal's member.
• "key" in x keeps the members that may have the key (declare it, optionally or not) and !("key" in x) those that may lack it (the in operator). On a narrowed x only the members left count (typeof x === "object" && "root" in x on a union with string and boolean members).
• typeof tests narrow a field path of a local too (typeof node.text === "string", this.label, h.node.text), as in TypeScript, until the path or a part of it is assigned. A call between the test and a read may change the field, so each read checks the member again and stops the program if the field now holds another member (Node would go on with the new value). A field narrowed to its function member can be called (typeof p.f === "function" ? p.f() : p.f), and one narrowed to some of its members reads as the union of them (with its null or undefined when no test ruled that out).
• A U | null variable narrowed to some of U's members (typeof x !== "number", the false branch of a type predicate) is a value of the union of those members with its null: return x where the return type is VNode | string | null.
• Conditions of if, while, &&, ||, !, ternaries and early exits narrow a local until it is reassigned; a || b narrows to the members either side allows (typeof c === "string" || typeof c === "number" leaves c a string | number); switch narrows each case (switch). A local that a closure assigns is not narrowed by these tests (variables a closure assigns).
• Assigning a member's value narrows to that member until the next assignment or join, also in the declaration (let u: string | number = "x"; u.length, else { p = new B(); } p.b), as in TypeScript.

class NotFound {
  id: string;
  constructor(id: string) {
    this.id = id;
  }
}

function find(id: string): string | NotFound {
  return id == "1" ? "ann" : new NotFound(id);
}

function show(v: string | i64): string {
  if (typeof v === "string") {
    return v.toUpperCase();
  }
  return `${v + 1}`;
}

const r = find("2");
if (r instanceof NotFound) {
  console.log("missing", r.id);
} else {
  console.log(r);
}
console.log(show("a"), show(41));

Discriminated unions#

A union of object types (anonymous object types, structs, classes or interfaces) whose members all have a field of a literal type is a discriminated union; that field (any name; kind below) is the discriminant. It is compiled like a Rust enum: the discriminant is the tag, not a stored string.

type Shape =
  | { kind: "circle"; r: f64 }
  | { kind: "rect"; w: f64; h: f64 };

function area(s: Shape): f64 {
  switch (s.kind) {
    case "circle":
      return Math.PI * s.r * s.r;   // s is the circle member here
    case "rect":
      return s.w * s.h;
  }                                 // every kind handled: no return needed after the switch
}

function isRound(s: Shape): bool {
  return s.kind === "circle";
}

const shapes: Shape[] = [{ kind: "circle", r: 1.0 }, { kind: "rect", w: 2.0, h: 3.0 }];
for (const s of shapes) {
  console.log(s.kind, area(s), isRound(s));
}

• An object literal where the union is expected picks its member by the discriminant's literal (else by its field names); an impossible discriminant is an error ("square"` is not a valid `kind` for `Shape` ).
• x.kind === "circle" / !== and switch (x.kind) narrow a local x; comparing with an impossible literal is an error. A bool discriminant is also a condition: if (r.done) / if (!r.done) narrow r of { value: T; done: false } | { done: true }.
• A field every member has (like kind) can be read without narrowing; other fields need narrowing (no field `r` on type `Shape` ), except value on an IteratorResult<T>, which reads as T | null (Iterables). Fields cannot be assigned through the union.
• Members may be interfaces with methods, and intersections of one with object types (Base<T> & { state: "errored" } & ({ value: T; hasValue: true } | { value: null; hasValue: false }), one member per part of the inner union). A field every member has reads through each one's getter, and a method every member has is called on the union: through an interface every member extends that declares it, else each member's own when they have the same type. Members may be classes too (Circle | Sq with area() on both, or a union of classes only): each member's own method runs on the value itself: the receiver first, then the arguments in order, each evaluated once. The call's type is the union of the members' results (number | string when scale() returns a number on Circle and a string on Sq), as in TypeScript. A getter every class of a union of classes has reads the same way (.size of a Map<K, V> | Set<T>).

interface Base {
  describe(): string;
}
interface Circle extends Base {
  readonly kind: "circle";
  readonly r: number;
}
interface Square extends Base {
  readonly kind: "square";
  readonly side: number;
}
type Shape = Circle | Square;

const shapes: Shape[] = [
  { kind: "circle", r: 1, describe: () => "round" },
  { kind: "square", side: 2, describe: () => "four corners" },
];
for (const s of shapes) {
  console.log(s.kind, s.describe()); // circle round, then square four corners
  if (s.kind === "square") console.log(s.side); // 2
}

• A discriminated union may name itself behind an indirection (type Tree = { kind: "leaf"; v: number } | { kind: "node"; kids: Tree[] }; see Union types).
• Payload enums and match do not exist; both are errors with a hint to use a discriminated union.
• A live object can be cast to a union of interfaces (union views).

Union views#

A live object can be a union of interfaces: when every member is an interface with methods and the members share an interface (Base above), one object whose getters change can be cast to the union, as libraries build such state machines (impl as AsyncState<T>): wide as Shape keeps the same object, and every discriminant test, switch and field read on the union calls its getters again, so the union sees the object change, as in Node.

The cast needs the object's type to have every member's fields, each typed as the union of the members' types (kind: "circle" | "square"), and the methods of the shared interface (a class instance converts through an interface its class implements: new Wide() as Shape); else it is an error.

A read after a test is checked against the member the test selected: an object whose state no longer fits it (kind is "circle" but r is null) gives a TypeError, never a value of the wrong type. Values built from literals keep their member and its tag, and can sit next to the live object in one variable or array.

interface Base {
  describe(): string;
}
interface Circle extends Base {
  readonly kind: "circle";
  readonly r: number;
}
interface Square extends Base {
  readonly kind: "square";
  readonly side: number;
}
type Shape = Circle | Square;

interface Wide {
  readonly kind: "circle" | "square";
  readonly r: number;
  readonly side: number;
  describe(): string;
}
let kind: "circle" | "square" = "circle";
const wide: Wide = {
  get kind() {
    return kind;
  },
  r: 1,
  side: 2,
  describe: () => "changes",
};
const live = wide as Shape;
console.log(live.kind, live.describe()); // circle changes
kind = "square";
if (live.kind === "square") console.log(live.side); // 2

Type predicates#

A function whose return type is a type predicate x is T (TypeScript's user-defined type guard) returns a boolean; a call of it in a condition (if, while, ?:, &&, ||, !) narrows the variable passed as x, as a typeof or instanceof test would: to the union members that are T (or to the subclass T), and to the others when the call is false. A T | null variable narrows to T.

function isString(v: string | number): v is string {
  return typeof v === "string";
}

function show(v: string | number): string {
  if (isString(v)) {
    return v.toUpperCase();
  }
  return (v + 1).toString();
}
console.log(show("ab"), show(41)); // AB 42

• TypeScript does not check that a predicate's body answers correctly. A call that narrows checks the value at run time against what its result says, as typeof or instanceof would, and panics when they disagree (the type predicate `isString` returned false for a value that is `string` ; exit code 101), where Node would go on with a value that is not of the type it was narrowed to. Unlike a thrown error, this panic cannot be caught with try/catch. A predicate that answers correctly behaves as in Node.
• A literal predicate type (x is "a" on string | number) narrows to the member it is a value of (string) when the call is true and leaves the variable as it is when false; a type no member of the variable's type is (x is Dog on string | number) does not narrow. An object type that is no member narrows, when the call is true, to the members whose values have every required member of it: v is { length: number } on string | number to string (strings, arrays and functions have length), and v is Computed<unknown> on a JSXChild (primitives, arrays and object types without value) to nothing, as TypeScript's intersection with them has no value Velt can hold: the code there type-checks (v.value) and does not run, and a predicate that returns true anyway panics as above. A union with an interface value or a class instance isn't narrowed. When false, the variable is left as it is.
• The function must be declared with function and not be generic for its calls to narrow; a predicate on an arrow or a function type ((x: unknown) => x is T) is just a boolean result. this is T is accepted and not used for narrowing yet.
• asserts x is T and asserts x declare an assertion function, which returns nothing (it throws instead of returning false). A call of it as a statement narrows the variable passed as x for the rest of the block, as if (!isT(x)) throw …; would: to T, or for asserts x to a truthy value (string | null to string). As for a predicate, the value is checked after the call, and an assertion function that returns for a value that is not T makes the call panic (the assertion function `assertDog` returned for a value that is not `Dog` ; exit code 101, which try/catch cannot catch). The errors the function throws itself are ordinary errors.

function assertIsString(v: string | number): asserts v is string {
  if (typeof v !== "string") throw new Error("not a string");
}

function shout(v: string | number): string {
  assertIsString(v);
  return v.toUpperCase();
}
console.log(shout("hi")); // HI

Intersection types#

A & B is the object type with the fields of both A and B, as in TypeScript. The parts are object types: anonymous ones, aliases of them, interfaces with only fields, results of utility types, other intersections, and unions of these. & binds tighter than | (A & B | C is (A & B) | C), and a leading & is allowed like a leading |.

type Named = { name: string };
type Aged = { age: number };
type Person = Named & Aged; // { name: string; age: number }

interface HasId {
  id: string;
}
type Entity = HasId & { createdAt: number };
type WithMeta<T> = T & { meta: string };

const ada: Person = { name: "Ada", age: 36 };
console.log(JSON.stringify(ada)); // {"name":"Ada","age":36}
const e: Entity = { id: "e1", createdAt: 1700 };
const n: Named = { name: "Grace" };
const grace: Named & Aged = { ...n, age: 45 }; // spread builds one from the parts
const w: WithMeta<{ x: number }> = { x: 3, meta: "m" };
console.log(e.id, grace.age, w.meta); // e1 45 m

• Fields are the first part's, then the next part's new ones: the key order of { ...a, ...b }, so printing and JSON.stringify match Node.
• A field in several parts gets the intersection of its types: the same type stays, object types merge ({ p: { x } } & { p: { y } } has p: { x; y }), a literal type and its base type give the literal, and union members that have no value in common drop out. The field is optional only when it is optional in every part, and readonly only when it is readonly in every part that has it (both as in TypeScript).
• Unions distribute: (Circle | Square) & { id: string } is (Circle & { id: string }) | (Square & { id: string }), a discriminated union that narrows as usual; Shape & { kind: "circle" } keeps only the circle member, and (A | null) & B is A & B.
• The result is an ordinary object type: there is no cost at run time, and A & B is the same type as the object type with those fields written out in the same order.
• Conversions: a value converts to an object type whose fields it has, by name, as in TypeScript, as a new object (conversions between object types); an extension that adds only optional fields shares its base's object (extensions with optional fields).
• An alias may refer to itself through & when its parts are object types written out (recursive intersection aliases).

type Named = { name: string };
type Scored = { score: number };

function greet(n: Named): string {
  return `hi ${n.name}`;
}

function rank(p: Scored & Named): string {
  return `${p.name}: ${p.score}`;
}

type Tree = { kids: Tree[] } & { v: number };

const ken: Named & Scored = { name: "Ken", score: 7 };
console.log(greet(ken), rank(ken)); // hi Ken Ken: 7
const t: Tree = { kids: [{ kids: [], v: 2 }], v: 1 };
console.log(t.kids[0].v); // 2

A part may be a type parameter (T & { $set: (v: T) => void }, TMain & TSub), in a generic alias or written in a generic signature: the intersection is worked out where the type arguments are known, so a caller sees the object type with both parts' fields, and a type argument that can't be a part (a class, say) is reported there. A type argument inferred through such a parameter comes from the fields the object part names (T = { n: number } for a Signal<{ n: number }>), else from the argument's parts the pattern doesn't name (T = A for a value declared A & { id: string }), else from the whole argument (T = { a: number; id: string } for { a: 1, id: "x" } against T & { id: string }), as in TypeScript. Such an argument is inferred from before the other arguments are checked, so reset(s, { st: "done", data: null }) with reset<T>(s: Signal<T>, v: T) checks the literal against the T that s fixes. any, unknown and object parts intersect as in TypeScript: any & X is any, unknown & X is X, and object & X is X when X is an object type (so T & object at an object type T is T). object & X keeps only the members of X that are objects, and has no value (never) when none is: T & object at number is never, so sigx's PrimitiveSignal<T> | Signal<T & object> at a number is PrimitiveSignal<number>; never & X is never. In a generic body, T & object is T under a T extends object bound (an overload returning Signal<T> fits an implementation returning Signal<T & object>), and a value of T & object (or of an intersection with such a part) is an object, so it can be a WeakMap key. So is an intersection with a part that is an object type and no part that is a type parameter ({ value: T } & { $set(v: T): void }): it satisfies T extends object. T & { __brand: "Id" } with an unbounded T is not an object (at T = string it is a branded string). In a generic body, a value of such an intersection may be returned or passed as T, or as one of its object parts (s: T & { $set } as T, as { $set }), as TypeScript allows: it is the same value where both are one type at an instantiation, and otherwise a new object with the fields of the expected type. TypeScript passes the same object there, so such a copy is an error where the program could tell it from the original: comparing values of the expected type with ===, assigning a field of either object, printing or serializing it (the copy lacks the other fields).

Type-level forms and keys in generic code. A mapped type, T[K], keyof T or a utility type over a type parameter (Partial<T>, Pick<T, K>, …) may be written in a generic function's signature or body, not only in an alias: it is evaluated at every instantiation, as TypeScript evaluates it there. A key parameter K extends keyof T is inferred as the literal key the call passes (the union of the keys when several arguments pass one: swap(o, "x", "y") has K = "x" | "y"), and x[k] reads or writes that field of x: T, the field itself (an array read through it is === to the original; a write reaches the object, a value a call returned too: first(os)[key()] = v). The object and the key may be any expressions, each evaluated once, in order. An optional field reads as F | undefined, and typeof, === undefined and == null on a T[K] value test the instantiation's value (typeof o[k] is "undefined" for an absent optional field, "number" for a present one). A key type of several keys reads or writes the field the key holds (k: "x" | "y" on { x: number; y: number }). When those fields have different types, T[K] is the union of them (number | string for "id" | "name" on { id: number; name: string }): a read gives the field the key names as that union, and a write takes the value's member when it is the field's type, and otherwise stops the program with a TypeError where TypeScript would store a value of the wrong type (setField(u, k, 5) with k holding "name"). A key of an optional field reads as F | undefined.

An object of such a form is built as TypeScript's standard pick builds it: const r = {} as Pick<T, K> (or Partial<T>, Omit<T, K>, any object type over a type parameter), keys set with r[k] = o[k], then returned as that type. {} as D is a dictionary until then; the conversion to D takes each of D's fields from it (checked like a conversion from any), and a key of a required field that was never set stops the program with a TypeError naming it, where TypeScript would hand out an object without it. Velt's object has D's fields in D's order, where JavaScript's has the keys in the order they were set: keys set in another order (pick(o, ["name", "id"])), or a key D lacks ((r as any).extra = 5), stop the program with a TypeError too, rather than print, serialize or list the keys differently.

function pick<T, K extends keyof T>(o: T, ks: K[]): Pick<T, K> {
  const r = {} as Pick<T, K>;
  for (const k of ks) r[k] = o[k];
  return r;
}
console.log(pick({ id: 1, name: "a", age: 3 }, ["id", "name"])); // { id: 1, name: 'a' }

Where Velt's fixed layouts cannot hold what TypeScript would store, generic code stops with a TypeError that try does not catch:

• a write x[k] = v through a union of keys, of a value whose type is not the field's (swapKeys(q, "id" as keyof U, "name" as keyof U), which Node stores);
• a write of null or undefined through such a key into a field that cannot hold it (undefined into a required field or a number | null one, null into a b?: number);
• {} as D with a required key never set, keys set in another order than D's fields, or a key D lacks;
• a value of another type written into that dictionary through any;
• a cast to T & X (x as Signal<T & object>) of a value that is not one at the instantiation, which is checked at run time;
• as T & object of null.

These stops are not exceptions: a catch around the call is never reached, and the program exits with status 101 after printing the TypeError.

An error at an instantiation is reported in the generic function, where the failing form is, with the call that instantiates it and the type arguments (and each call on the way, when another generic function's body makes the call). A call whose argument breaks a type parameter's constraint (get(p, "w"), a key p lacks) is one error, at that argument, as in TypeScript, and is not instantiated. An alias declared in a generic function's body may name the function's type parameters.

function get<T extends object, K extends keyof T>(source: T, key: K): T[K] {
  return source[key];
}
function set<T extends object, K extends keyof T>(target: T, key: K, v: T[K]): void {
  target[key] = v;
}
function update<T extends object>(x: T, patch: Partial<T>): T {
  return { ...x, ...patch };
}

const st = { count: 0, name: "a" };
set(st, "count", get(st, "count") + 2);
console.log(st.count, JSON.stringify(update(st, { name: "b" }))); // 2 {"count":2,"name":"b"}

Spreads in generic code. { ...t } and { ...t, tag: "x" } with t: T build a new object at each instantiation, as Node copies an object's own properties: the fields of T's type argument, then the explicit ones (a later field overrides an earlier one and keeps its position), with nested objects and arrays shared rather than copied. The literal is a T, or a T & { tag: string }, as in TypeScript, so explicit properties are checked against the expected type ($set: (v) => … gets its parameter type from Signal<T>). An instantiation whose T is not an object type ({ ...t } at T = number) is an error there. An optional field of a later part overrides an earlier value of it only while present, as in Node: an absent name keeps the earlier one. A field required in an earlier part keeps its type under a later optional one (n: number, as TypeScript types it; both parts must give the field one type), so, as for a concrete spread, a present undefined over it is a TypeError: Node keeps undefined in a field typed number, which Velt can't represent. A spread used directly as a T (return { ...x, ...patch } from a function returning T) is built as T the same way. A source whose type argument is an interface with methods is an error at that instantiation: a spread copies an object's own properties, which are its methods for an object literal but not for a class instance, and an interface value may be either. A source of a concrete type that may be undefined or null (...v with v: V | undefined) spreads nothing while missing, as in Node; one whose type has a type parameter (x: T | undefined) is not supported yet: test it first (x === undefined ? {} : { ...x }).

type Signal<T> = T & { $set: (v: T) => void };

function withSet<T extends object>(t: T, log: string[]): Signal<T> {
  return {
    ...t,
    $set: (v) => {
      log.push(JSON.stringify(v));
    },
  };
}

const log: string[] = [];
const s = withSet({ n: 1 }, log);
s.$set({ n: 2 });
console.log(s.n, log); // 1 [ '{"n":2}' ]

A value of a generic body used as one of its parts (s: T & { tag: string } returned as a T or passed as a { tag: string }, { ...t } returned as a T) is the same value. TypeScript always passes the same object; Velt's object types have fixed layouts, so this is allowed only at instantiations where both are one object type (a T that already has tag, or { ...t } at any object type), and an instantiation where they differ (T = { a: number }, whose values would have to be copied, losing identity and writes) is an error at the generic function. x as T & object, for an x of a type parameter T without an object bound, is checked at run time: the value itself (not a copy) when it is an object, a TypeError when it is a primitive, null or undefined (TypeScript keeps such a value; write the cast after a test that rules primitives out, as sigx's signal does). A generic alias used at type parameters (Signal<{ value: V }> in function f<V>) is the object type its intersection makes, as if written out. So is a generic function's result Signal<T> at a T that mentions the caller's type parameters (signal({ st: "idle", data: d as D | null }) in function cell<D>): its fields are read, written, destructured and reached with ?., and $set is called, on the same value. Omit<T, never> and Pick<T, never> name no fields.

type Signal<T> = T & { $set: (v: T) => void };

function relay<T extends object>(s: Signal<T>): Signal<T> {
  return s;
}

function stamp<T>(x: T & { id: string }): T & { id: string } {
  return x;
}

let last = 0;
const s: Signal<{ n: number }> = {
  n: 1,
  $set: (v) => {
    last = v.n;
  },
};
const r = relay(s); // Signal<{ n: number }>: `n` and `$set`
r.$set({ n: r.n + 1 });
const t = stamp({ a: 1, id: "x" });
console.log(last, t.a, t.id); // 2 1 x

Differences from TypeScript, each a compile error with a note on what to write instead:

• A field that is a type parameter in one part and a type in another ({ a: D } & { a: string }) is D when D's constraint is that type (D extends string), the deferred D & X when X is an object type or a type parameter, and an error otherwise. Two function types in one field (nested Signal<Signal<T>>'s $sets) are one function when one of them takes every argument the other does (its parameters have a subset of the other's fields); other overloads are errors.
• When the parts have no value in common ({ k: string } & { k: number }, or two different discriminants), TypeScript makes the type, or the field, never; Velt reports no value has type `…`: field `k` is `string` in one part and `f64` in another.
• A class instance with object types (Map<K, V> & { $set(v: Map<K, V>): void }, sigx's Signal<T> at a Map, or T & { … } at a class T) is a brand of the instance, as a primitive's is (branded types): the value is the instance itself (x as such a type keeps the object, === holds), with the class's members, instanceof, iteration, spreads, printing and the reflective operations (Object.keys, for...in, in, Object.hasOwn, Object.assign, { ...x }, JSON.stringify see the class's fields). It converts to the class; an instance converts to it implicitly when every member of the object part is optional or a field, method or getter of the class of that type (C & { y?: number }, C & { inc(): number }), else only with as. When the object part adds nothing to the class (C & { id: string } where C declares id: string) the type is C itself. A member only the object part declares (s.$set(v)) is read from the object at run time, as through any, and checked as the member's type then: a proxy's get trap can provide it, and an instance that lacks it stops with a TypeError at the read (Node reads undefined).
• Two classes (A & B) and structs are not parts (Velt classes are nominal, not structural): use Pick<C, …> or a field-only interface. Arrays (also Signal<T> at an array T, reported at the call) and function types (overloads) are not parts either; T extends A & B stays a bound on two interfaces.
• An interface with methods is a part, with rules of its own for classes that implement it, accessors and conflicting members (interfaces as parts).
• In generic code, a value of an intersection with a type parameter part (x: T & { id: string }) is passed on and returned as it is, and the members of its object parts are read (also with ?. and destructuring), written and called on the value itself (x.id = "b", s.$set(v) for s: Signal<T>); its conversion to one part (T or { id: string }) and building one ({ ...t, id }) are not supported yet.
• An intersection is the same type as the object type with its fields written out, so where a program has both forms, inference through T & { id: string } treats them alike: an object literal { a: 1, id: "x" } gives T = A when the program also declares a value of type A & { id: string } (TypeScript: { a: number; id: string }). It differs only where code depends on T itself, such as JSON.parse(s) returned as a T.
• Interface declarations merge as in TypeScript (declaration merging).

type Conflict = { k: string } & { k: number }; // error: no value has type ...

Conversions between object types#

A value converts to an object type whose fields it has, by name, as in TypeScript: A & B where an A or a B is expected, B & A (or { b; a }) where A & B is expected, and to a type with an optional field the value lacks (it is absent). Object types have fixed layouts, so the conversion builds a new object of the expected type holding the same field values: one allocation and a copy of each field, paid where a program converts (nested objects and arrays are shared, not copied).

TypeScript passes the same object, so where the program could tell the difference, the conversion is an error with the fix (build the object from its fields, { a: ab.a }, or take the wider type). That is where the program:

• assigns a copied field of either type (a.a += 1 on an A anywhere), or an optional field the value lacks (x.c = "s" on an { a: number; c?: string }; a write through any, x.a = 1 or x[k] = v with x: any, counts only when the program converts the copy, its original or a value that may hold one to any, unknown or object, since only such objects are reached through one);
• compares values of the expected type with === (also as A | null or another union holding it);
• prints, serializes or lists the keys of a value holding the expected type;
• spreads a value of the expected type ({ ...x, c: 3 }; Node would show or copy the original's fields, in its order);
• tests a value of the expected type with in for a key the copy left out ("b" in a, which Node finds on the original).

Each counts directly or in generic code the program calls (xs.indexOf(x) and xs.includes(x) compare with ===). Keys compared by identity count as ===: a WeakMap, WeakSet or WeakRef of the expected type. So does converting a value that may be the copy (followed through variables, parameters and results; anywhere once the copy is stored in a field or an array) to any, unknown or object when the program compares two such values that may be objects ((a as any) === (ab as any), not x !== undefined), keys a Set<any>, Map<object, V> or weak collection by them, or prints, spreads or lists the keys of one.

type A = { a: number };
type B = { b: number };
const ab: A & B = { a: 1, b: 2 };
const a: A = ab; // error: this conversion copies, and the copy's field `a` is assigned below
a.a += 1;

An array converts element by element only when fresh, like wider element types: const ns: Named[] = roster(); for a roster() that returns a new (Named & Scored)[]; copy another one with xs.map((p) => ({ name: p.name })).

Extensions with optional fields#

For an interface that extends one object type (an interface with only fields, or an object alias that refers to itself) and adds only optional fields the base lacks, as in interface InternalVNode extends VNode { _ns?: boolean }, a program that converts between the two (vnode as InternalVNode, passing a VNode where an InternalVNode is expected or the reverse, also as VNode[] and InternalVNode[] or as the values of a Map) converts the same object, as in TypeScript: a field written through either type is there through the other, and === holds.

For that, every object of the base's layout gets room for the extensions' fields, absent until written: in a tree of 1,048,575 four-field VNodes with an extension adding five optional fields, an object grows from 88 to 144 bytes and the peak memory from 198.7 MB to 214.8 MB. An extension the program only declares (often one in a dependency) costs nothing.

Each type keeps its own fields: VNode has no member _ns, and keyof VNode, mapped types (Required<VNode>) and structural conversions see VNode's fields only. Printing and JSON.stringify show the whole object, an added field once it is written (one holding a function is printed, and left out of JSON, as in Node).

Object.keys, for...in, spreads and in list the fields of the type the program looks through, so one of those on a VNode is an error once the program may give its objects an added field: assigns it, writes it in an object literal of an extension ({ ...v, _ns: true } too), or makes such objects from text or a dynamic value (JSON.parse, x as VNode of an any), whose keys are not known (look through v as InternalVNode).

Several such extensions of one base share it while they give a field of one name the same type; one that gives another type (_subTree?: VNode next to _subTree?: VNode | null) keeps its own layout and converts by copying, as conversions do, the extension nearest to the base (by module path) sharing it. Neither the base nor the extension may be generic. As for other optional fields written after construction, printing lists them in declared order (the base's fields, then each extension's), not in the order they were written.

Recursive intersection aliases#

An alias may refer to itself through & when its parts are object types written out: type Tree = { kids: Tree[] } & { v: number } is the interface with the fields kids and v. A part may also name a non-generic alias of such a type, or an interface with only fields, declared in the same module (type Tree = Base & { kids: Tree[] } with type Base = { v: number } or interface Base { v: number }). A field in two parts is one field when its type is written the same in both (Base & { v: number; kids: Tree[] }, also for function types; not yet for index or call signatures).

Object aliases may also refer to each other (type A = { b: B | null }; type B = { a: A[] }, or through a named part or an alias that renames another): each is an interface. An object alias that names itself is one whatever other aliases name it back (type Visitor = (t: Tree) => void).

A recursive alias is an error otherwise: with a part that is a type parameter, a generic alias (Box<number> & { … }), an alias or interface of another module, an interface with methods, or a field of two types; the error points at that part.

Interfaces as parts#

An interface with methods is a part: I & { errors: number } (and A & B, or T & { … } at an interface T) is an interface with every part's members, one whatever the order of the parts (A & B is B & A).

An object literal implements it. A class that implements each interface part, itself or through a base class (and has the object parts' fields, or get/set accessors for them, which reads and writes through it run), converts to it as the same object, generic classes too, and a field written through it reaches the class's field. A generic class's field provides a part's field at the instance's type arguments (val: T of Cell<string> for { val: string }). Its values convert to each interface part as the same object (=== holds).

Writing through it a field that a class has only a get for stops the program with Node's TypeError: Cannot set property n of #<C> which has only a getter (what strict code gets), also when a subclass overrides only the getter of its base's pair.

Pick<I, K> and Omit<I, K> of such an interface are interfaces with those members, which values of I convert to the same way; in general an interface value converts to any interface whose members it has (an interface it extends, a structurally equal one, in both directions).

Methods of one name with different signatures in two parts (overloads in TypeScript) are an error, and so is a field in one part with a method of that name in another (no value has both), and converting such a value to its object part ({ errors: number }), which would copy it. For the same reason, a value of an interface that extends a field-only interface B does not convert to B: B is an object type with a fixed layout, and TypeScript keeps the same object. T & object at an interface or class T is T: t as T & object is the same value.

Branded types#

A primitive & an object type (string & { __brand: "UserId" }) is a branded type: a nominal alias of the primitive, with no cost at run time. x as UserId brands a value; a branded value works wherever its primitive does (members, operators, ${}, arguments, map keys, typeof, also in generic code: typeof x of an x: T & { n?: number } at T = number is "number"); a plain string, or another brand of it, does not convert to the brand.

type UserId = string & { __brand: "UserId" };
type Cents = number & { readonly __unit: "cents" };

function greet(id: UserId): string {
  return `user ${id}`;
}

const id = "u-42" as UserId;
console.log(greet(id), id.length, id.toUpperCase()); // user u-42 4 U-42
const price = 449 as Cents;
console.log(price / 100); // 4.49

type UserId = string & { __brand: "UserId" };
const id: UserId = "u-1"; // error: a plain `string` does not convert to it; brand a value with `x as UserId`

Indexed access types#

T["k"] is the type of field k of a concrete object type T, and T["a" | "b"] the union of the fields' types, as in TypeScript: Person["name"] is string, and an optional field email?: string gives string | undefined. On an interface with methods it reads a field or a getter (get size(): number gives number). A key that is not a field is an error. The key is a string literal type or a union of them; on a type parameter it is not supported yet.

Type queries and keyof#

typeof x in a type is the type of the value x, as in TypeScript: a module constant, a function, a local variable or parameter (in a function body), or a field of one (typeof config.port); typeof ns.f names an export of a namespace import. A constant initialized with a string or boolean literal has that literal type (const s = "a" gives typeof s, the type "a"). With a number literal it is number, where TypeScript gives the literal type (const N = 4 gives 4; number literal types are not complete yet), so / on it divides as in TypeScript. A function's type includes the result its body gives, so ReturnType<typeof f> names a result type nobody wrote down, even in the signature of another function, declared before or after it. A signature that needs its own type (function f(x: ReturnType<typeof f>), also through other functions) is an error, as in TypeScript (TS2502). ReturnType<F> is the result type of function type F, and Parameters<F> its parameter types as a tuple. typeof f of a function with a rest, optional or default parameter is not supported yet. In a field of an interface, object type or class (signal: typeof signal), typeof f is the type the function's declaration writes: its parameter types and its written result, and no error (a function there needs a written result, and one that throws needs its throws written in a function type instead). typeof of a symbol constant (const K = Symbol("k")) is symbol there too.

keyof T is the union of an object type's keys as string literal types (keyof { a: number; b: string } is "a" | "b"; a key a mapped type made from a number literal stays that number: keyof { [K in 1 | 2]: K } is 1 | 2), and on a Record with literal keys it is the key type.

const DEFAULTS = { host: "localhost", port: 8080 };
type Settings = typeof DEFAULTS; // { host: string; port: number }

function parse(line: string) {
  const [key, value] = line.split("=");
  return { key, value };
}

function show(entry: ReturnType<typeof parse>): string {
  return `${entry.key} -> ${entry.value}`;
}

function read(s: Settings, k: keyof typeof DEFAULTS): string {
  return `${s[k]}`;
}

const s: Settings = { host: "example.org", port: 443 };
console.log(show(parse("a=1")), read(s, "port")); // a -> 1 443

A function generic only over the errors its callbacks throw (setTimeout<E>(task: () => Promise<void, E>, ms: i64)) has the function type without them (typeof setTimeout takes a callback that does not throw), as TypeScript declares such functions without type parameters.

Not supported yet (each is an error): typeof of another generic function, of an async or generator function (function types have no type parameters), of a class or enum itself (TypeScript's constructor and enum object types; the type of a class's instances is its name), of this and of a local function value; typeof import("./m"); type arguments after the name (typeof f<string>); typeof of a function or a constant without a type annotation in classes and interfaces (their fields and methods); keyof of a class, of a type parameter and of a string-keyed Record (TypeScript's string | number). A local's type is its declared type: TypeScript's typeof x sees a narrowing (if (x !== null)) that Velt's doesn't.

Conditional, mapped and template literal types#

TypeScript's type-level forms work as in TypeScript where their type arguments are known: an alias like type Getters<T> = … is evaluated at each use (Getters<User>), at compile time, and the result is an ordinary object type, union or literal type.

• Conditional types C extends E ? T : F: C is tested for assignability to E (structurally for object types). When C is a type parameter written alone, the test is made for each member of a union (boolean is true | false; never gives never); [C] extends [E] tests the whole type. As with --strict, function parameters are compared contravariantly, an optional field does not fill a required one, an object type whose fields are all optional takes only an object type with none of its own or one field in common ({ b: 1 } extends { a?: 1 } is false), {} takes any value but null and undefined, and number literals compare by value (1 and 1.0 are one type). Two Records relate by their type arguments (the key the other way round), else by their fields: Record<"a" | "b", 1> extends Record<string, number>.
• infer X in E of a conditional type names the part of C it stands for: in a generic type, an object type's field, a function type, a tuple, or a template literal pattern. An infer that finds nothing is TypeScript's unknown, which Velt supports only as NonNullable<X> ({}). An infer X in several function parameters finds their intersection.
• Mapped types { readonly [K in S as N]?: V }: one field per key of the literal union S. Over keyof X, each field keeps X's ? and readonly unless +, - or a modifier says otherwise; -? also removes undefined from the field's type. as N renames a key, and a key renamed to never is dropped; keys renamed alike have the union of the values. A number literal key stays a number. With keyof T for a type parameter T, a union argument gives the union of each member's mapped type. T[K] of an optional field is F | undefined, as TypeScript reads it (inside these forms and outside them).
• Template literal types `on${K}`: the union of the strings they spell, with Uppercase, Lowercase, Capitalize and Uncapitalize; after extends they are patterns (K extends `model:${string}`, S extends `${infer F}${infer R}`). A boolean hole is "true" | "false", and a hole of literal types each of them spelled out (`${boolean}x` is "truex" | "falsex").
• NonNullable<T>, Exclude<T, U> and Extract<T, U>; Awaited<T>, what await gives (the value of a promise, of each member of a union, also over a type parameter; a thenable that is not a Promise stays itself, as await takes only promises); string & K with K a string literal type is K; keyof of a union is the keys its members share.

type Getters<T> = { [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K] };
type OptionalKeys<T> = { [K in keyof T]: undefined extends T[K] ? K : never }[keyof T];
type Unbox<T> = T extends { value: infer V } ? V : never;

type User = { name: string; age?: number };
const getters: Getters<User> = { getName: () => "Ann", getAge: () => 36 };
const key: OptionalKeys<User> = "age";
const n: Unbox<{ value: number }> = 42;
console.log(getters.getName(), key, n); // Ann age 42

In generic code. An alias whose body needs an argument that is still a type parameter (function f<T>(x: T): Getters<T>, a generic class's or interface's field props: PropsAccessor<TProps>) stays unevaluated, as in TypeScript, and is evaluated once the type arguments are known: at a call, at new, and for every instantiation the program reaches. In the generic body a value of such a type can be stored, passed and returned as that same type. Reading a field of it, assigning it to another type, or assigning anything else to it is not supported yet in the generic body, even where TypeScript allows it (return x from x: T into PropsAccessor<T>, const s: string = t for t: IsString<T>, t.length): it reports an error. Where TypeScript rejects such code too (TS2322, TS2339), the error is the same.

type PropsAccessor<P> = { readonly [K in keyof P]: P[K] };
type IsString<T> = T extends string ? "yes" : "no";

interface SetupContext<P> {
  props: PropsAccessor<P>;
}

function setup<P>(props: PropsAccessor<P>): SetupContext<P> {
  return { props };
}

function tag<T>(x: T, t: IsString<T>): IsString<T> {
  return t;
}

const ctx = setup<{ title: string }>({ title: "hi" });
console.log(ctx.props.title, tag(1, "no")); // hi no

Not supported yet (each is an error): these forms written directly (not through an alias) with an argument that is still a type parameter (function f<T>(x: T extends string ? 1 : 2)); reading a member of a deferred type in the generic body, which TypeScript answers from the type parameter's constraint (T[K] with K extends keyof T, a mapped type over keyof T); a mapped type over an array or tuple type, or over string; a template literal type with a string or number hole outside a pattern.

Enums#

TypeScript-style enums only:

• numeric enum Color { Red, Green = 5, Blue }: auto-incremented; Color.Blue as i64 is its number; printed as a number;
• string enum Dir { Up = "UP", Down = "DOWN" }: every member needs a string; printed and serialized as its string; converts to string; no as cast.

Enums are not generic and have no payloads; use a discriminated union for tagged data.

Objects, arrays, tuples and maps#

• Object literals { name: "a", n: 1 } have anonymous object types { name: string; n: i64 } with a fixed layout (a field access is one load). An object type accepts exactly its fields: extra fields are a type error, and adding a property later is an error (use a Map or a Record).
• Quoted property names: see Quoted property names.
• Key order of an object type is JavaScript's: field names that are array indices ("0", "404": canonical, up to 2^32 - 2) come first, ascending, then the others in declaration order. console.log, JSON.stringify and Object.keys all follow it. So do a Record and a JsonValue object: their array-index keys come first, ascending, then the others in insertion order (JSON.parse too).
• Generic object types are structural, as in TypeScript: an instance is the object type it spells out, so with type Box<T> = { v: T }, Box<string> is { v: string }, and so is the instance of a generic interface with only fields. An instance whose field is void (Box<void>, or sigx's __ref: TRef brand with TRef = void) is accepted, as in TypeScript, but the field keeps no value: what is written to it (ref: null as any) is dropped, and a read of it is void (which can't be printed or tested). Printing the object directly or writing it as JSON (directly or through a generic) is a compile error, and printing it through a generic or an any, writing it as JSON through an any or unknown, or reading the field through an any, stops with a TypeError, where Node shows the value written. A void field written in an object type, a struct or a class, or a class instance with one (new Holder<void>()), is an error.

type Box<T> = { v: T };

function box<T>(v: T): Box<T> {
  return { v };
}

const b: { v: string } = box("hi"); // `Box<string>` is `{ v: string }`
console.log(b.v); // hi

satisfies#

value satisfies T checks value against T, with T as its context (as an annotation const x: T = value does), and is value: { version: "1" } satisfies Stamp. Its type is T, as for the annotated x; TypeScript keeps the value's own, more precise type instead (a field T declares as number | string but given a number is a number after satisfies there), which Velt does not do yet.

readonly fields#

In { readonly id: i64; name: string }, assigning id is an error (cannot assign to `id`: it is a readonly field); like TypeScript's, the check is shallow (u.tags.push(x) is fine). A value converts between a type and the same type without readonly, in both directions, and stays the same object.

• JSON.stringify(x) / JSON.parse<T>(s) are generated at compile time for numbers, bools, strings, literal types, arrays, tuples, enums, nullable values, Map<string, V>, Record<K, V>, structs, classes and anonymous objects (velt/encoding/json). JSON.stringify writes a class's or struct's private fields, as Node does, and skips ES private fields (#x). JSON.parse<T> cannot build a type with a private or # field (a compile error naming the field: decoding does not run the constructor). A type holding a std type's private state (a runtime handle) has no JSON form in either direction, so handles can't be forged from JSON.

struct Point {
  x: i64;
  y: i64;
}

const p: Point = { x: 1, y: 2 };
const moved = { ...p, y: 5, label: "moved" };
const [first, ...rest] = [10, 20, 30];
const counts = new Map<string, i64>();
for (const word of "a b a".split(" ")) {
  counts.upsert(word, 1, (n) => n + 1);
}
for (const [word, n] of counts) {
  console.log(word, n);
}
console.log(moved, first, rest, [3, 1, 2].map((x) => x * 2).filter((x) => x > 2));
const ports = new Map([["http", 80], ["https", 443]]); // Map<string, i64>
console.log(ports.get("https")); // 443

Quoted property names#

Quoted property names work as in TypeScript, for names that are not identifiers: type Headers = { "content-type": string }, { "a-b": 1 }, interface A { "data-id": string } and const { "a-b": n } = o. o["a-b"] (or o[`a-b`]) reads the field; with any string literal, o["name"] is the same as o.name.

A key whose type is a string literal or a union of them works too, as in TypeScript: const k = "a-b"; o[k] reads o["a-b"], and o[k] with k: "a" | "b" reads the field k holds when it runs, typed as the union of the fields' types (number | string). Assigning through such a key (o[k] = v, o[k] += 1, o[k]++) needs the fields to have one type; o[k] += v reads the field before v runs, as JavaScript does. The key can be any expression of such a type (o[pick()], o[keys[1]], h.o[h.k]), evaluated once; the object must be a variable, this or a field of one.

console.log quotes the names that are not identifiers, as Node does ({ 'a-b': 1 }), and JSON.stringify writes them as given.

Methods in object literals#

{ name(x: T): R { ... } } is a property holding the function, as { name: (x: T): R => { ... } } is; async name() {} holds an async function. As in an arrow, the parameter types may be left out where the literal's type gives them.

this in such a method, and getters and setters (get x() {}, set x(v) {}), are supported where the literal implements an interface with methods (Object literals implementing interfaces) and in a literal with no expected type (this in object-literal methods), not yet in a literal of an object type.

A generic method (match<R>(arms: Arms<R>): R { ... }) is a property holding a generic function value; in a literal that implements an interface, such a method can't use this yet (an error says so).

A generator method *name() { ... } (async *name()) is a property holding a generator function, as name: function* () { ... } is; a generator method with a symbol key only as *[Symbol.iterator]() (Iterable object literals).

Method signatures in object types#

{ size(n: number): number; stop(): void } declares fields of function type, as { size: (n: number) => number; stop: () => void } does, and label?(p: string): string an optional one (((p: string) => string) | undefined, absent when left out; call it as o.label?.(p)). A generic method signature (run<T>(f: () => T): T) declares a method in an interface; in an object type, and as an optional one in an interface (wrap?<A>(a: A): A), it declares a field of generic function type (<T>(f: () => T) => T), a generic function value.

A call signature alone (interface F { (x: T): R }, type F = { (x: T): R }) declares the function type (x: T) => R: a value of it is called as f(x), any function or arrow of that type is one, and typeof f is "function". With members, an object type or interface with one call signature is a function with properties (TypeScript's ((x: T) => R) & { stop(): void }). A parameter initializer in a call signature ((x = 1): void) is an error, as in TypeScript.

A generic call signature (<T>(x: T): T) is a generic function type, planned. A construct signature (new (x: T): C; as in TypeScript, new(…) in an object type is never a method, while in a class it is) is the type of a class used as a value, new (x: T) => C (Functions).

interface Formatter {
  (value: number, unit: string): string;
}

const fmt: Formatter = (value, unit) => `${value} ${unit}`;
console.log(fmt(3, "kg"), typeof fmt); // 3 kg function

type Handler = {
  get(target: string, key: string): number;
  label?(prefix: string): string;
};

const h: Handler = {
  get(target, key) {
    return target.length + key.length;
  },
};
console.log(h.get("ab", "c"), h.label?.("x") ?? "none"); // 3 none

Utility types#

Utility types build an object type from a concrete one (an object type, an interface with only fields, or a class or struct, whose public fields are used):

• Partial<T>: every field optional;
• Required<T>: no field optional;
• Readonly<T>: every field readonly;
• Pick<T, K>: only the fields named in K;
• Omit<T, K>: every other field.

K is a string literal type or a union of them ("id" | "email"). In Pick a name that is not a field is an error; in Omit it is a warning, as TypeScript accepts it (so type WithoutChildren<P> = Omit<P, "children"> works on types without children).

The results are ordinary object types: Pick<User, "name"> is { name: string }, and declaration order doesn't matter. As in TypeScript, Required removes only the ?: a field written a: T | null, or a?: T | null, stays nullable.

Differences from TypeScript: an operator on a type parameter (Partial<T> in a generic function) is not supported yet; and a type can't apply one to itself in its own fields (interface Node { patches: Partial<Node>[] }).

interface User {
  readonly id: i64;
  name: string;
  email?: string;
}

type Patch = Partial<User>;               // { readonly id?: i64; name?: string; email?: string }
type Summary = Pick<User, "id" | "name">; // { readonly id: i64; name: string }

function apply(u: User, p: Patch): User {
  return { id: u.id, name: p.name ?? u.name, email: p.email ?? u.email };
}

const s: Summary = { id: 1, name: "ann" };
console.log(apply({ id: s.id, name: s.name }, { email: "a@x" }).email); // a@x

Spread#

{ ...a, b: 1 } builds a merged object at compile time (later keys win); [x, ...xs] builds a new array, converting each element to the expected element type (integer elements spread into a number[], const ns: Named[] = [...cs]). Spread arguments, f(...xs), fill a rest parameter (Functions). Whatever for...of takes can be spread into an array or a rest parameter too: [..."héllo"] (characters), [...map] (entries), [...gen()], Math.max(...set) (Consuming an iterable).

Elements, arguments and properties run in written order, as in JS: [f(), ...g()] calls f first, an iterable is consumed where it is written, and { y: f(), x: g() } calls f first whatever the order of its type's fields; a property a later spread overrides ({ a: f(), ...o }) still runs. A spread copies its source's elements or properties where it is written, before later ones run: { ...o, a: f(o) } and [...xs, ...f(xs)] copy o and xs before f changes them, and [n, ...bump()] reads n before bump does.

Wider element types#

An array, object type or generic class converts to the same type with wider elements (C[] to Named[] for a class C implements Named, i64[] to (i64 | null)[], Box<C> to Box<Named>) only when the value is fresh: a literal, a new expression, or the result of a call of a function that returns a new value on every path (a literal, new, such a call, or a local it builds and returns without storing or passing it anywhere, as map and filter do). The conversion builds a new value with each element converted.

A call that may return a value something else still holds (a getter returning a field) is an error with the same fix as below, and so is a conversion in a field initializer or a default value for now. TypeScript also converts an existing array, which is unsound: storing a Named that is not a C through the Named[] would put it into the C[]. Velt reports that and suggests a copy, [...cs] or cs.map((x): Named => x).

An as cast of an existing array to another element type (cs as Named[]) is allowed and gives a view of the array (see "any and unknown" below), checked element by element as it is read and written. A generic class converts only when it has no base class, no subclasses and no [Symbol.dispose](); the new object shares the old one's field values.

interface Named {
  name(): string;
}

class C implements Named {
  name(): string {
    return "c";
  }
}

function make(): C[] {
  return [new C()];
}

const ns: Named[] = make(); // a fresh C[]: converted
const cs = make();
const copy: Named[] = [...cs]; // `const ns2: Named[] = cs;` is an error
console.log(ns.length, copy.length); // 1 1

Destructuring#

Destructuring takes a value apart: const [a, b] = pair;, const [head, ...rest] = xs;, const { a, b } = obj;, and for (const [k, v] of map). Array destructuring checks the length like indexing: a shorter array panics with the same index out of bounds message. A string, a map or an iterable is destructured like in JS (const [first, ...rest] = "abc"): const [a, b] = gen() takes two values and closes the iterator; one that has fewer values panics like a short array, unless the pattern gives defaults. Nested patterns work too (const [[a, b], [c]] = [gen(), gen()]).

An object pattern reads properties, as in JS: const { length } = xs; and const { length: n } = "abcd"; read the length, and a getter is called (const { area } = rect;). A method or function-typed member destructured out of an object or interface value is a function value (const { insert, remove } = options;), bound to the object it was read from (in JS it is unbound, so the two differ only where JS would throw a TypeError for a method that uses this).

As in TypeScript, an array pattern over an array literal types the literal as a tuple (const [n, s] = [1, "s"] gives a number and a string, also in a destructuring assignment, for […] as const and for a const c = [2, "y"] as const taken apart, also in a closure or function that captures c and where c is a module constant; c itself stays a read-only array of the union, with length, indexing, iteration and the read methods). Taking c apart reads its elements, so a write made through a cast ((c as unknown as (number | string)[])[0] = 7) is seen; an element overwritten with a value of another type stops with a TypeError.

Destructuring an any reads each element or property through it (const [a, b] = v is v[0], v[1], each an any, read once; a default applies where the read gives undefined; a ...rest of an any is not supported yet).

A computed key naming a variable (const { [k]: v = 0 } = r, ({ [k]: p } = r), a local, an outer function's or a module variable, read when the pattern runs) reads r[k]; one naming a module constant holding a string or a symbol ([KEY]) reads that member, also of an object, interface or class; a string, number or template key ({ ["a"]: v }, { [0]: v }), like a quoted or numeric property name ({ "a": v, 0: w }), names that property. Any other key expression ({ [f()]: v }) is an error: store the key in a variable first.

On an array or a tuple a numeric key reads that element and length the length, a tuple's arity (const { 0: first, length } = xs, also with defaults, nested, also inside a tuple element, const [i, { 0: c }] = t, in for...of and in parameters). Defaults on a Record or index-signature pattern apply where the key is missing (const { port = 80 } = env).

Object rest#

const { children, ...rest } = props; (also in let, nested patterns, next to defaults and in parameters, function f({ id, ...rest }: P)): rest holds the other own properties, in the object's order, as in JS. The rest is a new object: its fields are copied (a nested object or array is shared, as in JS).

Its type is TypeScript's: on an object type or an interface of fields, the object type of the other fields (Omit<P, "children">; an optional field is copied only while present); on a class instance, the other fields (its methods and getters live on the prototype, so the rest has none, nor #private fields); on a Record<string, V>, a Record<string, V> of the other keys.

interface Props { id: number; title: string; hidden?: boolean }
const props: Props = { id: 1, title: "t" };
const { id, ...rest } = props;
console.log(id, rest); // 1 { title: 't' }

Defaults#

Defaults in const and let patterns: const { host = "localhost", port = 80 } = opts; takes the default when the field is absent (optional) or undefined, and const [first = 0] = xs; when the array is too short or the element is undefined, as in JS; a field or element declared T | null keeps its null, and so does an optional field declared a?: T | null that holds null. for...of patterns take defaults (and an object rest) the same way: for (const { name, port = 80 } of servers), and so do parameter patterns (function f({ a = 1 }: { a?: number })). A nested pattern's defaults apply the same way, also inside a tuple element (const [i, { a = 5 }] = t with t: [number, { a?: number }]).

Destructuring assignment#

A destructuring assignment takes a value apart into places that already exist, as in JS: [a, b] = [b, a] swaps, and the targets may be variables, fields and elements ([xs[i], xs[j]] = [xs[j], xs[i]], [this.x, this.y] = [y, x], ({ w: box.width } = size)), nested ([p.x, { y: p.inner.y }] = src). The value is evaluated first, then each target in order, left to right, each assigned before the next is evaluated ([i, xs[i]] = [1, 5] writes xs[1]).

Defaults ([a = 1, b = a] = xs, ({ host, port = 80 } = opts) with the shorthand { port = 80 }, which is only allowed in such a target, TS1312) apply where the value is undefined, as in declarations, and each is evaluated when its turn comes, so it sees the targets assigned before it ([a, b = a] = [5] gives 5 5). A last ...rest takes the other elements or properties ([first, ...others] = xs, ({ id, ...rest } = p)), a hole skips an element ([a, , b] = xs; a hole elsewhere, [1, , 2], is not supported), and an object target needs parentheses as a statement (({ a, b } = o);), as in JS.

for...of and for...in assign to such targets too, and to a variable or place declared elsewhere: for (x of xs), for ([k, v] of map), for ({ name, port = 80 } of servers). The assignment has no value yet: x = [a, b] = c is an error (a destructuring assignment cannot be used as a value yet; assign c to x first).

class Point { x = 1; y = 2; }
let a = 1, b = 2;
[a, b] = [b, a];
const xs = [10, 20, 30];
[xs[0], xs[2]] = [xs[2], xs[0]];
const p = new Point();
[p.x, p.y = p.x * 10] = [3];
let host = "", port = 0;
({ host, port = 80 } = { host: "h" } as { host: string; port?: number });
let first = 0, rest: number[] = [];
[first, , ...rest] = xs;
console.log(a, b, xs, p.x, p.y, host, port, first, rest); // 2 1 [ 30, 20, 10 ] 3 30 h 80 30 [ 10 ]
let k = "", v = 0;
for ([k, v] of new Map([["one", 1]])) console.log(k, v); // one 1

Arrays#

T[] has length and xs[i] (bounds-checked: panics index out of bounds: the len is L but the index is I; a read where a T | undefined is expected, return xs[0] from a function returning T | undefined or const v: T | undefined = xs[i], and any read of an array whose element type allows undefined, gives undefined outside the array instead, as in JS).

Its methods include push (any number of items: xs.push(a, b), xs.push(...ys), all evaluated before the first is pushed, as in JS), pop(): T | null, forEach map filter reduce find findIndex some every indexOf lastIndexOf includes slice concat reverse isEmpty entries fill, join and toString() (any elements, written as ${xs} writes them), sort() on numbers, strings and Comparable elements, and sort(cmp) (stable, any element type, like JS's Array.prototype.sort(compareFn)). The full list is in the prelude.

Callbacks get the element and its index, like JS (xs.map((x, i) => …), the index a number, also when written (x: number, i: number)), and may take fewer parameters. A predicate (filter, find, findIndex, some, every) may return any value, tested for truthiness as in JS: [0, 3, 0, 4].filter((n) => n) is [3, 4].

Arrays, strings and maps are Iterable: they convert to Iterable<T> values, and xs[Symbol.iterator]() returns an Iterator<T>.

new Array and Array.from#

new Array<T>(n).fill(v) and Array.from({ length: n }, (_, i) => f(i)) build an array of n elements in one allocation. A bare new Array<T>(n) is an error: arrays have no holes. As in JS, new Array<T>(n) takes n as xs.length = n does: a negative, fractional or NaN n panics with RangeError: Invalid array length, while Array.from truncates its length (and takes a negative one or NaN as 0). A numeric enum's value is a length too. An argument that is no number (a string, a string enum's value, an object) makes an array of that one element, as in JS (new Array("3").fill("x") is ["x"]); one whose type may be either (number | string, an unbounded type parameter) is an error, since JS decides between the two at run time: test typeof n === "number" first. new Array(...args) with a tuple follows JS: one element is the argument, any other count makes that many elements. Array.from(src) and Array.from(src, (v, i) => …) copy (and map) anything for...of takes: an array, a string's characters, a map's entries, a generator, any iterable.

Length limit#

An array holds at most 2^52 - 1 elements, and its elements take at most 2^52 - 1 bytes together, where JS stops at 2^32 - 1 elements. Velt allows more on purpose: its arrays are native buffers, so a byte array, a column of numbers or a buffer may be larger than 4 GiB, as in Rust, while 2^52 bytes (4 PiB) is still beyond any machine's memory. So xs.length = 2 ** 32 is a RangeError in Node but truncates a longer Velt array.

Growing an array past the limit (push, concat, splice, spread, Array.from, new Array<T>(n)) panics with RangeError: Invalid array length: an array holds at most 2^52 - 1 elements, and its elements at most 2^52 - 1 bytes, and so does xs.length = n with an n past 2^52 - 1 (also through any). An array within the limit but larger than the machine's memory stops the program with memory allocation of <n> bytes failed, on every target (on WebAssembly, any buffer past 2^31 - 1 bytes). The bound is also what lets the compiler count a loop such as for (let i = 0; i <= xs.length; i++) in integers. Typed arrays hold at most 2^52 - 1 bytes.

readonly T[]#

readonly T[] and ReadonlyArray<T> (the same type) are array types, and readonly [A, B] a tuple type; a T[] is passed where one is expected. A variable or parameter declared with a read-only array type cannot be written through: a mutating method (property 'push' does not exist on type 'readonly number[]', TypeScript's TS2339, also pop, shift, unshift, splice, sort, reverse, fill, copyWithin) and an element assignment (xs[0] = x, TS2542) are errors; the elements' own fields may change (xs[0].n = 1). The check follows the variable: a readonly T[] copied into a T[] variable or passed as a T[] parameter (TypeScript's TS4104) is not reported yet.

ReadonlySet<T> and ReadonlyMap<K, V> are Set<T> and Map<K, V> seen through a type that may not change them, as in TypeScript: a Set or Map is passed where one is expected (const keys: ReadonlySet<string> = new Set(["a"])), and everything that reads it works (has, get, size, forEach, keys(), for...of, new Map(m)). Through a variable or parameter declared with one, the methods that change the collection (add, set, delete, clear, upsert, update, getOrInsert) are TypeScript's TS2339 (property 'add' does not exist on type 'ReadonlySet<string>' (TypeScript's TS2339)), also when it is declared through a type alias of the program (type Tags = ReadonlySet<string>, also an alias of one, one in | null / | undefined, and a generic alias whose body is read-only, type RO<T> = ReadonlySet<T>), made by a cast (new Set() as ReadonlySet<string>, also inline: (xs as readonly T[]).push(x)), captured by a closure, narrowed (if (s), s!), read with ?., or copied into a variable without a type (const t = s); the same holds for readonly T[]. A cast to a type that is not read-only (xs as string[], s as Set<string>) may change the value, as a variable or inline, and so may a collection narrowed by s instanceof Set (or Map) where the test holds.

An element of an array whose elements are read-only (k: readonly (readonly T[])[], Array<ReadonlySet<T>>) is read-only too: k[0].push(x) is TS2339 and k[0][0] = x TS2542, while writing into an element that may change (j[0].push(x), j[0].length = 1 with j: readonly T[][]) is allowed, as in TypeScript; only replacing the element of a read-only array (j[0] = []) is TS2542.

Not reported yet (TypeScript reports them): such a method called on a field, an element copied into a variable (const e = k[0]), an element of an alias of the whole array type (type Grid = readonly (readonly T[])[]), an element three levels deep, an element typed | undefined read with ?. or !, a destructured or returned value or a for...of variable of a read-only type, a method read as a value (const add = s.add), a read-only type given to an alias whose body is its parameter (type Box<T> = T, then Box<ReadonlySet<string>>), and passing or assigning a read-only collection where a Set or Map is expected (TS2345, TS2739).

Tuples#

[A, B]: t[0], destructuring, printed like arrays. Element labels document the elements and are otherwise ignored, as in TypeScript: type Wire = [kind: string, b64: string]. Optional elements ([A, B?], [name: string, age?: number]) and rest elements (variadic tuple types, [A, ...T], [first: string, ...rest: number[]]) parse, with TypeScript's errors for their order (an optional element after a rest one, TS1266; a required one after an optional one, TS1257), and using one is an error saying it is not supported yet. Promise.all over tuples of different types is not supported.

Map<K, V>#

new Map<K, V>(), new Map(entries) from an array of [key, value] tuples (new Map([["a", 1], ["b", 2]]): as in JS, the array stays as it is, the map shares its keys and values, and a repeated key keeps its first position and its last value) or from any iterable of them (new Map(pairs())).

A map has set, get(k): V | undefined (the stored value itself, as in JS; undefined for a missing key), has, delete, size, keys(), values(), entries(), for (const [k, v] of m), plus single-lookup updates: upsert(k, init, (v) => v + 1), update(k, (v) => { v.push(x); }): bool (the callback gets the stored value itself) and getOrInsert(k, () => v) (Map). Iteration follows insertion order, like JS.

Keys compare as in JS: numbers, bool and string by value, objects (class instances, object types, arrays, maps, records, interface and function values) by identity, as === compares them, so two equal object literals are two keys and a key changed after insertion keeps its entry; tuples compare part by part. Structs are Velt value types: their keys compare and hash by content, field by field, so an equal struct finds the entry. Float keys compare like JS's (SameValueZero: 0 and -0 are one key, NaN finds itself).

A value type may include null (Map<string, number | null>, Record<string, T | null>): an entry holding null is present like any other (has is true, it is counted, iterated and printed), and get gives null for it and undefined for a missing key, as in JS. If such an entry holding null has a content key that changed after insertion, then while the map has deleted entries not yet compacted away, forEach, for...of and console.log skip it (keys(), values() and entries() list it).

Record<K, V>#

A dictionary written with object syntax, like TypeScript's Record. K is string, a union of string literal types, or a string enum; any other key type is an error (use a Map), also when a generic function or class gets it as a type argument. console.log and JSON treat a record as an object. A class cannot extends a Record (its constructor would leave a closed record without its keys); hold one in a field instead.

Number keys#

Record<number, V> and Record<string | number, V> are Record<string, V>, as JavaScript makes a number key its string: r[n] with a number n reads and writes r[String(n)] (r[1.5] is r["1.5"]), and Object.keys lists the keys as strings, array indices first. Through a variable or parameter declared with one, a string key that is not a number's name is an error, as in TypeScript: r["abc"] (TS7015), r.abc (TS2339) and { a: v } as its initializer (TS2353); r["1"] and r["1.5"] are keys. A number index works on any string-keyed record. A type parameter given number as a record key is not supported yet.

Symbol keys and accessors#

A string-keyed record also holds symbol keys, in a table of its own as in Node, made when the first symbol key is written (a record without symbol keys pays nothing for it): Record<string | symbol, V> and Record<PropertyKey, V> are Record<string, V>. r[s], r[s] = v, r[s] ??= v, delete r[s], s in r and Object.hasOwn(r, s) take a symbol s (a module constant, a well-known symbol such as Symbol.iterator, or one made at run time), a string | symbol key or a PropertyKey (string | number | symbol, also a union of literals; a number is its string), and a symbol constant is a key of a record literal ({ [KEY]: v }). Object.keys, Object.values, Object.entries, for...in and JSON.stringify skip the symbol keys; Object.getOwnPropertySymbols(r) lists them in insertion order, Reflect.ownKeys(r) lists the string keys (array indices first) and then the symbols, and a spread copies them, as in Node. console.log writes the symbol keys after the string keys as Node 26 does ({ a: 1, Symbol(k): 2 }).

Object.defineProperty(r, k, { get, set, configurable }) defines an accessor under a string or symbol key, not enumerable (the listings above skip it, Reflect.ownKeys lists it after the entries of its kind); reads, writes, in and delete run or test it, a write without a setter and a delete or redefinition of an accessor that is not configurable are Node's TypeError. The getter and setter may throw: the error leaves at the read or write that ran them, where no try catches it yet, so it ends the process with Node's Uncaught report and exit code 1. Object.defineProperty(r, k, { value, enumerable: true, writable: true, configurable: true }) writes an entry; an enumerable accessor and other attributes are not supported yet. Object.getOwnPropertyDescriptor(r, k) describes an entry ({ value, writable: true, enumerable: true, configurable: true }) or an accessor ({ get, set, enumerable: false, configurable }), or is undefined.

In a program with proxies, a proxy whose target is a record forwards symbol keys to its symbol table through Reflect, and indexing an any with a symbol key reads, writes and tests it there. The methods for symbol keys and accessors are loaded only by a program that mentions symbols, property definitions, Proxy or Reflect.

const K = Symbol("k");
const rec: Record<string, number> = { a: 1 };
rec[K] = 2;
console.log(rec, Object.keys(rec), Object.getOwnPropertySymbols(rec).length); // { a: 1, Symbol(k): 2 } [ 'a' ] 1

Casts to records#

A cast to Record<symbol, unknown> (or Record<symbol, any>) looks at a value's symbol-keyed members, as through any: (v as Record<symbol, unknown>)[BRAND] === true reads the member BRAND names, or undefined, as a value of the record's value type (unknown must be narrowed before use, as TypeScript's TS2322 says). A string key (["a"], .a, TypeScript's TS2339) and any key that is not a symbol (a string or symbol | string variable, TS7053) are errors; an any key reads as through any. A key computed by a call or a condition and a well-known symbol ([Symbol.iterator]) are not supported yet, and neither is any other use of the cast: writing through it and keeping it are not supported yet.

On an any x, (x as Record<K, V>)[k] and (x as Record<K, V>).k read and write x itself, as the assertion converts nothing in TypeScript: a read is a V | undefined (a V where one is expected, a missing key then a TypeError), and a value written is checked as a V, also by ??=, ||= and &&= (and += on a number member takes a number).

Open and closed records#

With string keys a record is open: r[k] and r.name are V | undefined, r[k] = v inserts or replaces, r[k] ??= v sets a missing key, and delete r[k] removes. Because a key may be missing, r[k] += 1, r[k]++ and the other compound assignments are errors on an open record: say what a missing key starts from with r[k] = (r[k] ?? 0) + 1 (JS would give NaN).

With literal or enum keys it is closed: it always holds every key, so r.cpu is V, r.cpu += 1 works, a typo is an error, and delete is not allowed. On an enum-keyed record, r.mem names the member whose value is "mem".

In generic code, where the key type is a type parameter K, reads are V | undefined and the record may be closed, so it cannot start empty (only a literal with a spread builds one) and delete is not allowed.

Building records#

Build a record from an object literal where a record is expected (const r: Record<string, i64> = {}; a closed record's literal must list every key) or with new Record<string, V>(). A literal may spread another record ({ ...r, x: 1 }) and have computed keys ({ [k]: v, [a + b]: w }, in order with the other keys). An object literal with a computed key that is not a module constant (a module let is read when the literal is built), or one that spreads a variable r of type Record<string, V>, is a Record<string, V> also where no record is expected (spreading a record into an object of a fixed shape is an error: its keys are known only at run time).

A string or integer literal key in brackets is the plain key ({ ["a"]: 1 } is { a: 1 }), as is a numeric property name, which is the number as String spells it ({ 7: v }, { 0x10: v }, { 1.50: v } and { 1e3: v } have the keys "7", "16", "1.5" and "1000", and { 9007199254740993: v } the key "9007199254740992", the nearest double). A computed key is a string, or a number converted to its string as in JavaScript ({ [i + 0.5]: v } with i = 3 has the key "3.5"); a symbol made at run time is an error, and so is a key of any other type ({ [true]: v }, TypeScript's TS2464).

Key order and Object.keys#

A record has no methods of its own and is not iterable: Object.keys(r) (a string[]), Object.values(r) and Object.entries(r) return arrays in JavaScript's order: keys that are array indices ("0" to "4294967294") first, ascending, then the others in insertion order (for (const [k, v] of Object.entries(r))). console.log and JSON.stringify use the same order. Given an object literal, Object.values and Object.entries read it as a Record<string, V>, so its values need one type.

Object.keys accepts any object, as in TypeScript: an object literal or object type (Object.keys({ a: 1, b: "x" }) is ["a", "b"]), a struct, or a class instance, whose fields it lists in declaration order (base class fields first, private ones too; not ES private #x fields, static fields or methods). A struct's optional field is listed only when it is present. On a class with subclasses it lists the fields of the object's actual class (a Shape holding a Rect lists the Rect fields too), and on an interface value those of the class it holds (an interface also implemented by a struct is an error: struct values carry no class).

On an any it lists the fields of the class instance held, when every value the program converts to a dynamic type is a class instance; in a program that also converts other values (an array, a string, an object type, a function) it is a compile error.

Index signatures#

An object type or interface with an index signature and no other members, { [key: string]: V }, is Record<string, V>, as in TypeScript where the two are interchangeable: a value converts between them and stays the same object, and everything said of Record above holds (any key may be read, written and deleted; keys are listed in JavaScript's order, array-index keys such as "2" first). A number key, { [id: number]: V }, is the same record: JavaScript makes a number key its string, so r[1] is r["1"] (as for Record<number, V>). A generic interface works too (interface Groups<T> { [name: string]: T[] }).