The compatibility dialect
Nish compiles a strict subset of TypeScript. The compatibility dialect is the second way to build a program: it accepts more of TypeScript, one feature at a time, for code that was written for Node and is being moved over. You ask for it by name, a build that does not ask is unchanged, and the compiled program says which one it was built in.
The dialect changes the number a bare number is, and it has six features:
optional-chaining, nullish, string-switch, for-of-string,
optional-params and overloads. Each admits a form of TypeScript the strict
dialect refuses, with the meaning Node gives it.
The rules are in the reference, under The compatibility dialect.
Asking for it
Pass --compat where you would build or run the program:
nish --link app.ts --compat -o app
nish run --compat app.ts
Or say so once in your package.json, and every build of the package is a
compat build with no flag:
{
"name": "ported",
"private": true,
"nish": {
"compat": true
}
}
const half = (n: number): number => n / 2
export const main = (): void => {
console.log(half(7))
}
That prints 3.5. In the strict dialect a bare number is a 32-bit integer
and the same program prints 3.
"compat" is true for every feature this compiler has, or an array naming
the ones you want, such as ["nullish"]. [] is the dialect with no feature.
--compat=<feature>,... is the array on the command line.
When the strict dialect refuses something a feature would accept, the error says which feature to add:
main.ts:4:10: error: Nullish coalescing `??` is forbidden in Nish (narrow with `!== null` instead)
= add `nullish` to `nish.compat` in package.json to accept it
A name that is no feature
A name that is no feature is refused, on the command line (exit 2) and in
package.json (NL3056), so a typo cannot quietly leave a feature off:
{
"name": "ported",
"private": true,
"nish": {
"compat": ["asnyc"]
}
}
export const main = (): void => {
console.log(1)
}
package.json:5:16: error: `asnyc` is no feature of the compatibility dialect: `nish.compat` is `true` or an array of feature names, and the ones this compiler has built are `nullish`, `optional-chaining`, `string-switch`, `for-of-string`, `optional-params`, `overloads`
Numbers are doubles
The dialect implies --number-mode f64: a bare number is a 64-bit
float, as it is in Node. Everything --number-mode f64 means holds, its
errors included. The one you are most likely to meet is main's return type:
the exit code is a 32-bit integer, so a main that returns a bare number is
refused.
{
"name": "ported",
"private": true,
"nish": {
"compat": true
}
}
export const main = (): number => {
return 0
}
Write main(): i32 or main(): void instead. Types that spell their width
(i32, f64, u8) mean the same in both dialects.
A program whose arithmetic was written for 32-bit integers can keep them:
--compat --number-mode i32 is honoured. The compiler says once what that
costs, as a performance warning (NL9020), because arithmetic that leaves 32
bits panics there where a double would carry on. --no-warn-performance
silences it.
app.ts:1:1: performance: `--number-mode i32` beside the compatibility dialect: a bare `number` is the 32-bit integer and not the double a JavaScript engine computes with, so arithmetic that leaves 32 bits panics here where it would carry on there; drop `--number-mode i32` for the dialect's own f64
Optional chaining as a statement
The strict dialect takes a ?. chain only as the left side of a ??, which
gives it a value when a link is missing. With optional-chaining, a chain
that is a statement of its own compiles too: it runs when every link is
there, and does nothing from the first null link, its call's arguments
included, as Node does.
{
"name": "ported",
"private": true,
"nish": {
"compat": ["optional-chaining"]
}
}
class Counter {
n: number = 0
bump(by: number): void {
this.n += by
}
}
export const main = (): void => {
const a: Counter | null = new Counter()
const b: Counter | null = null
a?.bump(2)
b?.bump(5)
console.log(a === null ? -1 : a.n)
}
That prints 2. An element read may sit inside a chain, as in
rows?.[i].length ?? -1: the bounds check runs only when the array is there.
What stays refused
Two forms stay refused in both dialects, because Node's answer and the
compiled program's would part. An element read the chain would carry on past
is refused (NL1067): a ?.[i] that ends a ?? chain or a statement, and,
in a statement, any element read that ends it, h?.xs[i];, or that a ?.
tests, xs[i]?.bump(); or (xs[i])?.bump();. Past the end of the array Node answers undefined
and goes on, where Nish's bounds check panics. Test the index against
length instead. (With a ?? default, xs[i]?.n ?? 0 is the strict
dialect's own: the ?. tests a nullable element, and the read is
bounds-checked as every element read is. So is a plain element read that
ends a ?? chain, h?.xs[5] ?? 0: it panics past the end where Node gives
0, exactly as the strict build does.) (A ?.[i] that ends a chain anywhere else, as in
const x = xs?.[0], is refused as a chain with no default.) And an optional
call f?.() is refused (NL1068): narrow f with !== null and call it.
{
"name": "ported",
"private": true,
"nish": {
"compat": ["optional-chaining"]
}
}
const first = (xs: number[] | null): number => xs?.[0] ?? -1
export const main = (): void => {
console.log(first([42]))
}
Nullish coalescing on a value that is never missing
The strict dialect refuses a ?? whose left side can never be null: the
default would never run. Code written for Node often has one anyway. With
nullish it compiles to its left side, as Node computes it, and the compiler
says so in a performance warning (NL9021) that names the default to drop:
{
"name": "ported",
"private": true,
"nish": {
"compat": ["nullish"]
}
}
const size = (p: string | null): number => {
if (p !== null) {
return (p ?? "fallback").length
}
return 0
}
export const main = (): void => {
console.log(size("abc"))
}
main.ts:3:13: performance: `p` is never `null` or `undefined`, so `??` never runs its default: the build keeps the left operand alone (drop `?? "fallback"`)
This covers a left side the compiler can see JavaScript never leaves
undefined: a literal, a name, this, a new, an arithmetic or logical
operation, or a field read of one of these. A call or a ternary on the left,
twice(x) ?? 1 or (c ? a : b) ?? 0, keeps the strict refusal for now, as
does an element read, xs[i] ?? 0, which can run past the end.
The default must still have the type of the left side, as TypeScript asks
(NL2370). A ?? on a value that may be null is the strict dialect's own,
and means the same in both.
A switch on a string
The strict dialect switches on integers and enums only. With string-switch,
a switch on a string compiles too, and picks its case as Node does:
{
"name": "ported",
"private": true,
"nish": {
"compat": ["string-switch"]
}
}
const HELLO: string = "hello"
const kind = (word: string): string => {
switch (word) {
case "a":
case "b":
return "letter"
case HELLO:
return "greeting"
default:
return "other"
}
}
export const main = (): void => {
console.log(kind("b"))
console.log(kind("hello"))
console.log(kind("zz"))
}
That prints letter, greeting and other. A label is a string literal or a
module constant of type string, since a label is compared without being run;
a label the compiler would have to run, such as a parameter or a call, is
refused (NL2799), and so are two labels with the same text, however each is
spelled ("\u00e9" and "é" are one label). Fallthrough, default,
break, return and continue mean what they mean in Node, and the word is
worked out once, before the first comparison. A string | null word is not a
string, so its switch gets the strict refusal, which names no feature to
add: check it for null first. The compiler compares the
word with each label in turn, so a switch with many cases costs a comparison
per case before the one that matches.
for...of over a string
The strict dialect walks arrays. With for-of-string, for...of walks a
string one character at a time, as Node does: a character outside the
Basic Multilingual Plane, such as an emoji, is one step, not two.
{
"name": "ported",
"private": true,
"nish": {
"compat": ["for-of-string"]
}
}
export const main = (): void => {
let out: string = ""
for (const c of "né😀") {
out = `${out}[${c}]`
}
console.log(out)
}
That prints [n][é][😀]. Each character is a new string, which lives
until the function around the loop returns (or the loop around it ends a
pass), so keeping one after the loop is safe; a walk of a long string holds
one small string per character until then. break, continue and labels
work as they do over an array. A destructuring head, for (const [c] of s),
stays refused, and so does a walk of a string | null, with the strict
refusal: check it for null first.
A string that is not valid UTF-8, such as one built with
String.fromCharCode(200), is walked byte by byte where its bytes do not
form a character: a byte that starts a character but is not followed by the
bytes that finish it is one step on its own, and the next byte gets its own
step. So String.fromCharCode(200) + "abc" takes four steps, as it does in
Node, although the first step's bytes are nish's, not Node's.
Optional parameters and defaults that run
The strict dialect asks for a default on every parameter a call may leave
out, and takes only a constant for it. With optional-params, a parameter
may be written x?: T, and a top-level function's default may be any
expression, run as Node runs it.
{
"name": "ported",
"private": true,
"nish": {
"compat": ["optional-params"]
}
}
const fallback = (): number => {
console.log("fallback ran")
return 10
}
function greet(name: string, greeting?: string): string {
return `${greeting ?? "hello"}, ${name}`
}
function area(width: number, height: number = fallback(), scale: number = width + height): number {
return width * height * scale
}
export const main = (): void => {
console.log(greet("ada"))
console.log(greet("ada", "hi"))
console.log(area(2))
console.log(area(2, 3))
}
That prints hello, ada, hi, ada, fallback ran, 240 and 30: a
default runs once for each call that leaves its argument out, after the
arguments it got, and never for a call that writes the argument.
An x? parameter is read only as the left side of ??, as in
greeting ?? "hello". A call that leaves it out gives undefined in Node and
null here, and ?? is the one read that treats the two alike; anything
else, greeting.length or return greeting, is refused (NL2803). An x?
must be of a type that has null to stand for the missing argument, such as
a string or a class; factor?: number is refused (NL2804), so give it a
default, factor: number = 1, instead. A default on a method or a
constructor is still a constant.
A default that runs is taken only on a function every call to which the
module can see: one that is not exported and not overloaded, with a default
on every parameter from the first such default to the last. An exported
function, an overloaded one, or one with a required parameter between two
such defaults keeps the strict refusal, and its message says which rule it
missed. Write the default as a constant there, or move the computation into
the body: xs: number[] | null = null and const list = xs ?? fresh().
Overload signatures
With overloads, a function, a method or a constructor may be written as
bodiless signatures followed by its implementation, as TypeScript reads them:
{
"name": "ported",
"private": true,
"nish": {
"compat": ["overloads"]
}
}
function area(side: number): number
function area(width: number, height: number): number
function area(width: number, height: number = -1): number {
return height < 0 ? width * width : width * height
}
export const main = (): void => {
console.log(`${area(3)} ${area(2, 5)}`)
}
That prints 9 10. The compiled program is the implementation alone; the
signatures decide which calls are allowed. Each signature must be one the
implementation can stand behind, with exactly the same return type (tsc
also allows a narrower one), or it is refused (NL2800). A call is held to the signatures, not to the
implementation, so a call that no signature takes is refused (NL2801)
even when the implementation would run it, as tsc refuses it. A call
through a function value is held to the implementation only. A function
with signatures cannot be exported to C or Node with --emit-header,
--emit-napi or --emit-dts (NL2802): export one function per signature
instead.
Dependencies follow the root package
A program is compiled in one dialect: the one its root package asks for, the
package whose package.json is nearest above the file you compile. A
dependency cannot widen it. If a package in node_modules asks for
"compat" and yours does not, the import is refused (NL3057):
main.ts:3:23: error: Package `pkg_loose` asks for the compatibility dialect, which the root package's `compat` does not allow: a program is compiled in its root package's dialect, so `pkg_loose` cannot be part of this one until the root's `package.json` allows it in `nish.compat` (or the build passes `--compat`)
Add "compat" to your own package.json, or pass --compat, and it
compiles. A strict dependency inside a compat program needs nothing: it is
compiled in the program's dialect like every other module, so its bare
number is a double there too.
What a compat build tells you
Every module a compat build writes ends with a mark that names the dialect, the number mode and the features:
!nish.compat = !{!0}
!0 = !{!"f64", !"nullish", !"optional-chaining", !"string-switch", !"for-of-string", !"optional-params", !"overloads"}
A strict build has no such line, so you can tell from a .ll file which
dialect its source was written in. --emit-checked opens with the same facts
(compat number=f64 features=[nullish,optional-chaining,string-switch,for-of-string,optional-params,overloads]).
What it does not change
- A build that does not ask for the dialect compiles every program it accepted before to the same IR, byte for byte.
-
A program the strict dialect accepts compiles under the dialect to the
program
--number-mode f64compiles. It is not slower, and nothing is checked more loosely. - A feature accepts programs the strict dialect refuses, and runs them as Node does. It never changes what a program means when the strict dialect accepts it.

