Types
Every value in a Nish program has one type, fixed when the program is
compiled, and that type never changes. There is no any, no boxing and no
implicit conversion of any kind: two values are compatible only when their
types are identical. The normative rules are in the reference's
Types section.
Numbers
Nish names the width of a number. The ones you reach for every day are:
| Type | What it is |
|---|---|
i32 |
a 32-bit signed integer |
i64 |
a 64-bit signed integer |
f64 |
a 64-bit IEEE-754 float, JavaScript's number |
number |
i32 by default, or f64 when compiled with --number-mode f64 |
There are also u8, u16, u32 and u64 (unsigned, and they wrap on
overflow — handy for bytes and hashes) and f32. Write the explicit width when
you mean one: i32 reads the same in either number mode, number does not.
export const main = (): i32 => {
const count: i32 = 7;
const big: i64 = 9000000000;
const ratio: f64 = 0.5;
console.log(`${count} ${big} ${ratio}`); // 7 9000000000 0.5
return 0;
};
A let or const takes its type from its initializer, so in the default
number mode count needs no annotation. The other two do: without one,
9000000000 would be an i32, which it does not fit in, and 0.5 would be
an i32 too, which a fraction cannot be. When you write an annotation, it
must match the initializer exactly.
Mixing widths is always an error. i32 + i64, f64 + i32, even
u32 + i32 are refused, because the compiler will not guess which width you
meant:
const total = (a: i32, b: i64): i64 => {
return a + b;
};
Convert explicitly with toI32, toI64, toF64 (and toU8, toU16,
toU32, toU64, toF32):
const total = (a: i32, b: i64): i64 => {
return toI64(a) + b;
};
const average = (sum: i32, n: i32): f64 => toF64(sum) / toF64(n);
export const main = (): i32 => {
console.log(`${total(2, toI64(40))} ${average(7, 2)}`); // 42 3.5
return 0;
};
A numeric literal is an i32 (or f64 in f64 mode) unless the place it is
written asks for another type: an annotated declaration, a return, an
argument to a function, or the other side of an operator whose type is
known. That is why const big: i64 = 9000000000 above compiles. The full
list of those places is under
Numeric literals.
Integer arithmetic is checked: what happens when a value overflows is on the Control flow page.
Sixteen bytes of numbers held as one value — four i32 lanes, sixteen u8
lanes — are the nish:simd vector types, on the Vectors (SIMD)
page.
Math
Math gives the functions you know from JavaScript, with JavaScript's
answers. Math.sqrt, floor, ceil, trunc, round, sin, cos, tan,
exp, log, atan2 and hypot take f64; Math.abs, min, max and
sign take any number and answer in its type; Math.imul multiplies two
i32s the way JavaScript's 32-bit multiply wraps. Math.round(-0.3) is
-0, and Math.min or Math.max with a NaN operand is NaN, as in
JavaScript. Math.min, max and hypot take exactly two arguments.
Math.tan, atan2 and hypot are compiled from the standard library's
std/math.ts rather than called from the C library, so they answer the same
on every target, WebAssembly included, within one unit in the last place.
export const main = (): i32 => {
const angle: f64 = Math.atan2(1.0, 1.0);
console.log(`${Math.hypot(3.0, 4.0)} ${Math.sign(-7)} ${Math.imul(65536, 65536)}`); // 5 -1 0
console.log(`${angle * 4.0 === Math.PI}`); // true
return 0;
};
f64ToBits(x) and f32ToBits(x) give a float's raw IEEE-754 bits, as an
i64 and an i32; the whole list of builtins is in the reference's
Math table.
Booleans
boolean is true or false, and it is the only type a condition accepts.
Nish has no truthiness: if (n), if (s.length) and !xs.length are
errors. Compare instead — n !== 0, s.length !== 0. The
Control flow page has the details.
export const main = (): i32 => {
const n: i32 = 3;
const s: string = "hi";
if (n !== 0 && s.length !== 0) {
console.log("both set"); // both set
}
return 0;
};
Strings
string is an immutable sequence of bytes, usually UTF-8 text; the bytes are
not validated. Strings compare by content with ===, concatenate with +, and
are how you print a number, through a template literal: `${n}`. String(n) and n.toString() do
not exist. The Arrays and strings page covers what you
can do with one.
export const main = (): i32 => {
const n: i32 = 42;
const s: string = "answer: " + `${n}`;
console.log(`${s === "answer: 42"}`); // true
return 0;
};
Nullable types: T | null
A value that may be absent has the type T | null. T must be a class, an
interface, an array, a string or a
function reference —
a number or a boolean can never be null, so i32 | null is refused. Absence is null; undefined is not a
value a program writes (the one place it appears is a Map lookup — see
Maps and sets).
Before you read anything off a nullable value, test it. Inside the test, the
compiler treats the variable as plain T:
const firstLong = (words: string[]): string | null => {
for (const w of words) {
if (w.length > 4) {
return w;
}
}
return null;
};
export const main = (): i32 => {
const found = firstLong(["a", "tiny", "example"]);
if (found !== null) {
console.log(`${found} has ${found.length} bytes`); // example has 7 bytes
}
const none = firstLong(["no"]);
console.log(`${none === null}`); // true
return 0;
};
Reading a nullable without the test is an error:
const s: string | null = null;
console.log(`${s.length}`);
A few rules shape how narrowing works:
-
It applies to a local variable or a parameter, never to a property
path.
if (n.next !== null) { n.next.value }is refused: copyn.nextinto a local first and test that. - It ends at any assignment to the variable, and it is dropped before a loop that assigns the variable.
-
if (p === null) { return …; }narrowspfor the rest of the block, because theifcannot fall through. -
Two nullable values cannot be compared with each other — compare each with
null.
A default with ??
When all you want is a fallback, a ?? fallback gives a where it is not
null and fallback where it is. The result is plain T, so it needs no
test afterwards, and because it reads a only once, it works on a property
path too:
class Node {
value: i32;
next: Node | null = null;
constructor(value: i32) {
this.value = value;
}
}
const greet = (name: string | null): string => `hello ${name ?? "stranger"}`;
export const main = (): i32 => {
const head = new Node(1);
head.next = new Node(2);
let cur = head;
for (let i = 0; i < 5; i++) {
cur = cur.next ?? cur; // stays on the last node
}
console.log(`${greet(null)} ${cur.value}`); // hello stranger 2
return 0;
};
The fallback runs only when it is needed, as in TypeScript. If the fallback
may itself be null, the result stays T | null. One form is refused: a
default for an array element, xs[i] ?? fallback. TypeScript programs use it
for "past the end", where Node reads undefined and takes the fallback, but
Nish checks the index and stops the program instead. Test the index against
xs.length first:
const names = new Array<string | null>(2);
console.log(names[5] ?? "none");
Reaching through with ?.
To read through several nullable links, write a ?. chain and end it with a
default. Each ?. stops the chain when the value before it is null, and
the whole expression is then the default:
class Address {
city: string;
constructor(city: string) {
this.city = city;
}
}
class Customer {
address: Address | null = null;
}
const cityOf = (c: Customer | null): string => c?.address?.city ?? "unknown";
export const main = (): i32 => {
const c = new Customer();
console.log(cityOf(null)); // unknown
console.log(cityOf(c)); // unknown
c.address = new Address("Lyon");
console.log(cityOf(c)); // Lyon
return 0;
};
The chain can end in a field of any type, a number included, or in a method
call, and anything after a null link, an argument included, does not run.
Three rules keep it honest:
-
A chain must end in
??. On its ownc?.addresswould beundefinedwhencisnull, and Nish has noundefined, soconst a = c?.addressis refused. Use the chain where you want the value, with its default. -
Only
?.skips anull. Inc?.address.city, the.cityreadsaddressas it is, so ifaddressmay benullit needs a?.too. -
?.needs something that can benull. On a value that never is, write..
The reference's Nullable types section
has every form a test may take. A function that can fail, rather than find
nothing, returns a Result instead — see
Errors and Result.
Ranged integers
integer<Lo, Hi> is an i32 the compiler knows stays between Lo and Hi
inclusive — a byte value as integer<0, 255>, a digit as integer<0, 9>.
Putting a literal outside the range into one is a compile error; putting any
other i32 into one is checked once, and the program panics if it is out of
range. Taking a value out is free, and every operator reads it as a plain
i32. Because the compiler knows the bounds, a ranged value used as an
index can also spare the bounds check:
const digit: integer<0, 9> = 12;
The reference's Types section lists every rule
for integer<Lo, Hi>.
Enums
An enum names a closed set of values. It is a type of its own: a Kind is
never an i32, and an i32 is never a Kind, so a function that takes one
cannot be handed the other by mistake. ===, !== and switch are the
operations on it; there is no arithmetic.
An enum whose members are numbers is a numeric enum. A member without a
value counts up from the one before it, starting at 0:
enum Kind {
If = 1,
While = 2,
}
const weight = (k: Kind): i32 => (k === Kind.If ? 10 : 20);
export const main = (): i32 => {
console.log(`${weight(Kind.While)}`); // 20
return 0;
};
An enum whose members are all strings is a string enum. Every member
gives its string, and String(r) reads it back; it costs one load, not a
copy:
enum Role {
Admin = "admin",
Guest = "guest",
}
const greet = (r: Role): string => {
switch (r) {
case Role.Admin:
return "welcome back";
default:
return "hello";
}
};
export const main = (): i32 => {
const r = Role.Admin;
console.log(String(r)); // admin
console.log(greet(r)); // welcome back
return 0;
};
One enum holds one kind of member. Mixing strings and numbers is refused:
enum Mixed {
A = "a",
B = 2,
}
A string enum is still not a string. Comparing it with a string is refused,
because the compiler compares members, never text; compare with a member
instead, r === Role.Admin:
enum Role {
Admin = "admin",
Guest = "guest",
}
const isAdmin = (r: Role): boolean => r === "admin";
Nor does it turn into a string on its own. Write String(r) where you want
the text:
enum Role {
Admin = "admin",
Guest = "guest",
}
const label = (r: Role): string => {
const s: string = r;
return s;
};
An enum can't be | null; keep a boolean beside it, or give the enum a
member for "none". The reference's
Enums section lists every rule, and
Standard library shows a string enum read
from JSON.
Enum member types
A member of an enum is also a type. Written as an
annotation, Kind.Array is a slot that holds that one member and nothing
else, which is how a class records which of an enum's cases it is: a
readonly field of the member's type, set to the member.
enum Kind {
Scalar,
Array,
}
class ArrayNode {
readonly kind: Kind.Array = Kind.Array;
depth: i32 = 1;
}
const describe = (k: Kind): string => (k === Kind.Array ? "array" : "scalar");
export const main = (): i32 => {
const n = new ArrayNode();
console.log(describe(n.kind)); // array
return 0;
};
Only the member itself goes into such a slot. Another member is a compile
error, and so is a plain Kind value, because the compiler cannot tell which
member that holds:
enum Kind {
Scalar,
Array,
}
class ArrayNode {
readonly kind: Kind.Array = Kind.Scalar;
}
Reading the slot gives you a Kind, so it compares, switches and passes
anywhere a Kind does.
A let with no annotation follows TypeScript. Start it from a value that
already has the member type and it keeps that type. Start it from the
member's constant and it is a Kind, so it can take another member later:
enum Kind {
Scalar,
Array,
}
const keep = (k: Kind.Array): Kind.Array => k;
export const main = (): i32 => {
let held = keep(Kind.Array); // a Kind.Array
held = Kind.Scalar;
let any = Kind.Array; // a Kind
any = Kind.Scalar;
return any === held ? 0 : 1;
};
The same goes for the other places a type is worked out from what you
wrote. c ? a : a is a Kind.Array when a is, [a] is a Kind.Array[],
and so is xs ?? [a]. An arrow's result counts too: map([a], (k) => k) is a
Kind.Array[], while map([a], (k) => Kind.Array) is a Kind[], because an
arrow that answers the constant answers a Kind, as in TypeScript.
When the two arms of a ternary, or two elements of an array literal, differ
and one of them is a member type, such as c ? a : b with b a
Kind.Scalar, or c ? a : k with k a Kind, the compiler asks you to
annotate the variable (let x: Kind = c ? a : b). TypeScript would work out
a type by rules of its own: the union of the members, which for Kind's two
members is Kind itself, or the member, or the enum. Writing the type says
which one you meant.
A generic function takes the member's constant where its type parameter is
already bound to the member type, as in fold(xs, Kind.Array) with xs a
Kind.Array[]. It works out the type parameter from the arguments only, so
id(Kind.Array) is a Kind even where a Kind.Array is wanted, and so is
apply(take, Kind.Array) when take takes a Kind.Array. Both are refused.
TypeScript accepts them. Pass a value that already has the member type
instead: id(a).
An array of a member type is built with [] and push. new Array<T>(n)
fills its slots with 0, which here is Kind.Scalar, so the compiler refuses
it for any member but the one whose value is 0:
enum Kind {
Scalar,
Array,
}
export const main = (): i32 => {
const tags = new Array<Kind.Array>(4);
return tags.length;
};
The reference's Enums section has every rule.

