Errors and Result
Nish has no exceptions. There is no throw, no try and no catch: a
function that can fail says so in its return type by returning a
Result<T, E>, and the compiler makes every caller decide what happens to the
failure before it can touch the success value. The rules here are defined in
the reference under
Result and error handling.
A function that can fail
A Result<T, E> is either a success carrying a T or a failure carrying an
E. You build one with Ok(value) or Err(error), and both take their type
from the function's return type:
const parseDigit = (c: string): Result<i32, string> => {
if (c.length !== 1) {
return Err(`'${c}' is not one character`);
}
const code = c.charCodeAt(0);
if (code < 48 || code > 57) {
return Err(`'${c}' is not a digit`);
}
return Ok(code - 48);
};
export const main = (): i32 => {
const good = parseDigit("7");
if (good.isOk()) {
console.log(`parsed ${good.value}`);
}
const bad = parseDigit("x");
if (bad.isErr()) {
console.log(`failed: ${bad.error}`);
}
return 0;
};
This prints parsed 7 and then failed: 'x' is not a digit.
The error type is yours to choose: a string is the simplest, an enum or a
class lets a caller tell failures apart. An operation that can fail but has
nothing to hand back on success returns Result<void, E> and succeeds with
Ok().
Reading a Result
| You write | You get |
|---|---|
r.isOk(), r.isErr(), r.ok |
whether it succeeded; each one is also a test the compiler understands |
r.value |
the T, only where a test proved r is a success |
r.error |
the E, only where a test proved r is a failure |
r.orReturn() |
the T, or else return the failure from the current function |
r.unwrapOr(d) |
the T, or d if r is a failure |
r.expect(message) |
the T, or else print message and exit with status 1 |
const checkAge = (age: i32): Result<i32, string> => {
if (age < 0) {
return Err(`${age} is not an age`);
}
return Ok(age);
};
export const main = (): i32 => {
const r = checkAge(30);
if (r.isOk()) {
console.log(`${r.value}`); // 30
}
console.log(`${checkAge(-1).unwrapOr(0)}`); // 0
console.log(`${checkAge(7).expect("7 is an age")}`); // 7
return 0;
};
A union on either side
Either side of a Result can be a discriminated union. The
success of a parse that answers one of several shapes is the union, and
Ok(new Circle(r)) converts the variant into it, as passing it to a
Shape parameter would. Read the value into a local, then switch on its tag:
enum Kind {
Circle,
Square,
}
class Circle {
readonly kind: Kind.Circle = Kind.Circle;
r: i32;
constructor(r: i32) {
this.r = r;
}
}
class Square {
readonly kind: Kind.Square = Kind.Square;
side: i32;
constructor(side: i32) {
this.side = side;
}
}
type Shape = Circle | Square;
const parseShape = (text: string, size: i32): Result<Shape, string> => {
if (text === "circle") {
return Ok(new Circle(size));
}
if (text === "square") {
return Ok(new Square(size));
}
return Err(`${text} is not a shape`);
};
export const main = (): void => {
const r = parseShape("square", 4);
if (r.ok) {
const shape = r.value;
switch (shape.kind) {
case Kind.Circle:
console.log(`circle of radius ${shape.r}`);
break;
case Kind.Square:
console.log(`square of side ${shape.side}`); // square of side 4
break;
}
}
const bad = parseShape("star", 1);
if (!bad.ok) {
console.log(bad.error); // star is not a shape
}
};
The rules that stop a failure being ignored
TypeScript lets you forget about an exception. Nish turns each way of forgetting about a failure into a compile error.
You cannot reach the value without checking first. r.value compiles only
inside code that a test of r has proved is the success case, so the error
path is always written before the success path:
const half = (n: i32): Result<i32, string> => {
return Ok(n / 2);
};
export const main = (): i32 => {
const r = half(8);
console.log(`${r.value}`);
return 0;
};
The test can be if (r.isOk()), if (r.ok), r.isOk() && …, a ternary, or
an early exit: after if (r.isErr()) { return 1; } the rest of the function
knows r succeeded. As with nullable types, the test applies to a
local variable, not to a field: copy obj.result into a const and test that.
You cannot drop one. Calling a function that returns a Result and
ignoring the answer is an error, and so is storing it in a local that is never
read:
const save = (name: string): Result<void, string> => {
if (name.length === 0) {
return Err("no name");
}
return Ok();
};
export const main = (): i32 => {
save("notes.txt");
return 0;
};
Passing a Result to another function or returning it counts as using it: the
responsibility moves with the value.
Passing a failure up
Most of the time the right thing to do with a failure is to hand it to your
own caller. orReturn() does that in one call, as ? does in Rust: it gives
you the success value, or returns the failure from the enclosing function.
const half = (n: i32): Result<i32, string> => {
if (n % 2 !== 0) {
return Err(`${n} is odd`);
}
return Ok(n / 2);
};
const quarter = (n: i32): Result<i32, string> => {
const h = half(n).orReturn();
return half(h);
};
export const main = (): i32 => {
const r = quarter(6);
if (r.isErr()) {
console.error(r.error);
return 1;
}
console.log(`${r.value}`);
return 0;
};
quarter(6) halves 6 to 3, then fails on the odd 3, so this prints 3 is odd
on stderr and exits with status 1.
Because orReturn() returns early, it is allowed only in a function that
itself returns a Result whose error type matches. A function that passes a
failure on has to admit it in its own signature:
const half = (n: i32): Result<i32, string> => {
return Ok(n / 2);
};
export const main = (): i32 => {
const h = half(8).orReturn();
return h;
};
There is no automatic conversion between error types. When a callee fails with one type and your function reports another, convert it yourself:
enum ConfigError {
BadPort,
}
const parsePort = (text: string): Result<i32, string> => {
if (text !== "8080") {
return Err(`cannot parse '${text}'`);
}
return Ok(8080);
};
const loadPort = (text: string): Result<i32, ConfigError> => {
const r = parsePort(text);
if (r.isErr()) {
return Err(ConfigError.BadPort);
}
return Ok(r.value);
};
export const main = (): i32 => {
return loadPort("8080").unwrapOr(80) === 8080 ? 0 : 1;
};
When failure is not an option: panic
throw is refused, with a message that names the two replacements:
export const main = (): i32 => {
throw new Error("unreachable");
};
A failure a caller could handle is a Result. A situation that means the
program itself is wrong, an invariant that cannot hold, is panic(message):
it prints the message on stderr and ends the process with status 1. panic
never returns, so a function may end with it where it would otherwise need a
return. r.expect(message) is the same ending for a Result you are
certain succeeded, and it insists on a reason, which is why there is no
unwrap().
const daysIn = (month: i32): i32 => {
if (month === 2) {
return 28;
}
if (month >= 1 && month <= 12) {
return month === 4 || month === 6 || month === 9 || month === 11 ? 30 : 31;
}
panic(`month ${month} does not exist`);
};
export const main = (): i32 => {
console.log(`${daysIn(9)}`);
return 0;
};
There are no map, andThen or orElse methods on a Result, because they
would take a callback, often one that captures a variable, which a
function reference cannot hold; a test and
orReturn() cover what they are for.
It still type-checks as TypeScript
Every program on this page is valid TypeScript. With the declarations in
runtime/nish.d.ts on the include path, tsc
and your editor model Result as a tagged union and refuse r.value before a
test, just as nish does. nish stays the authority: tsc cannot see that a
Result was dropped, or that orReturn() returns early.

