Coming from JavaScript

Every JavaScript habit beside its Essence spelling and the error you get if you forget, in one lookup table per topic.

Each row of a topic table pairs a JavaScript or TypeScript habit with its Essence spelling and the error you get if you write the habit instead. A dash in the error column means the habit carries over or has no error. Nothing here is explained: each Essence cell links to the page that explains it, and each error code links to its entry in the diagnostics reference. To look up a message the compiler printed, see What the compiler says when you type JavaScript.

Here is a five-line TypeScript function, then the same function in Essence. Both drop the empty names and greet the rest.

function greeting(names: string[]): string {
	const known = names.filter((name) => name.length > 0)
	if (known.length === 0) return "Hello, nobody"
	return `Hello, ${known.join(" and ")}`
}

console.log(greeting(["Ada", "", "Grace"])) // Hello, Ada and Grace
console.log(greeting([])) // Hello, nobody

implementation {
	function greeting(to names: List<String>) -> String {
		constant known = names::everyItem(where (name) {
			<- name::hasCharacters()
		})

		if known::isEmpty() {
			<- "Hello, nobody"
		}

		<- "Hello, {known::join(with " and ")}"
	}

	Terminal.print(greeting(to ["Ada", "", "Grace"])) § Hello, Ada and Grace
	Terminal.print(greeting(to [])) § Hello, nobody
}

This program uses parts the language pages teach later. Programs and values teaches implementation, the § comments, constant, string and list literals, List<String> and the {…} interpolation. Method calls teaches :: calls and their labels, and Conditions teaches if. Functions teaches function, the to label, -> String and <-, and Functions as values teaches the (name) { … } literal. The library calls are everyItem(where:), isEmpty(), join(with:), hasCharacters() and Terminal.print.

Five differences show at once. A method is called with ::, and . calls a static such as Terminal.print. A function’s return type is required, where TypeScript would infer it. <- returns, inside the callback too. Each call writes its labels: to, where, with. And the comparisons > 0 and === 0 are the methods hasCharacters() and isEmpty().

Bindings

constant and variable replace const and let. A variable can be reassigned, and a record, a list or a dictionary is never changed in place.

Operators

There are none. Arithmetic, comparison and logic are method calls, read left to right.

Every row of this table reports operator-not-supported, whose helps name the method for the operator you wrote. Only the last row is something else.

Numbers

There is no number and no floating point. An Integer is a whole number with no largest value; a Rational is an exact fraction.

Strings

Double quotes only, and every string literal interpolates. length() counts characters as a reader sees them.

Collections

Records, lists and dictionaries are all immutable. A method that would change one returns a new one.

Null, undefined and exceptions

There is no null and no undefined. A value that may be missing is an Optional; an operation that can fail with a reason returns a Result.

Functions

A function declaration writes the type of every parameter and its return type. A call writes each label, in order.

Control flow

if is a statement and produces no value. define is the conditional expression, and match branches on a value’s case; both produce a value. There is no loop statement.

Types

A type names a shape and is structural. A choice is a closed set of cases and is nominal. There are no classes.

Namespaces and protocols

Methods live in namespaces, outside the type. A protocol is a contract: a namespace declares it meets one with is Named (a conformance), and a type parameter requires one with <infer T is Named> (a bound).

Modules

A file is a module with named exports, the way ES modules work.

Tooling

One essence command does the work of several tools, and tests live in the source file.

What the compiler says when you type JavaScript

Most of these errors name the JavaScript habit they refuse, and the table below pairs each with its fix. Each error starts with its code in brackets and a one-line message, then points at the code, like this one for constant total = 1 + 2:

[operator-not-supported]
Error: Essence has no '+' operator
   ╭─┤ Total.es:2:21 │
   │
 2 │     constant total = 1 + 2
   │                        ▲  
   │                        ╰── this is not a Method call
   │ 
   │ Help 1: Write 'a::add(b)' for Numbers.
   │ Help 2: Write 'a::append(b)' to join two Strings.
   │ 
   │ Note: Arithmetic, comparison and logic are Method calls in Essence, read left to right — there are no operators, and so no precedence to remember.
───╯

The table lists the errors you are likely to hit first: what you typed, the error’s code and message, and the fix. Where your editor offers a Quick Fix, it writes the fix for you.

Same as JavaScript

These need no relearning. Each carries its one caveat.

• Function hoisting. A function can be called above its declaration. Caveat: a namespace cannot be used by a statement above it.
• The constant’s dead zone. A constant cannot be read above its line, the way const has a temporal dead zone. Caveat: a function body written above the constant cannot read it either.
• { x, y } shorthand. It builds a record from the names in scope. Caveat: { point with x } merges a record named x; it is not shorthand for x = x.
• Structural object types. A record with more members passes where a narrower type is asked for, and keeps them. Caveat: a literal written where a type is declared is checked for extra members, as TypeScript’s excess-property check does; a value passed along keeps them.
• Renames with as. constant { y as row } = point and from "./Money.es" { twice as double }. Caveat: in a pattern, : annotates a type instead of renaming.
• ES-module shape. A file imports by relative path and exports by name. Caveat: the .es extension is written, and there is no default export.
• Default parameters are evaluated per call, in the callee. A default runs on every call that leaves its argument out, and may read the parameters to its left. Caveat: a call that passes the argument still writes its label.
• reduce is accumulator-first. [1, 2, 3]::reduce(startingWith 0, (total, item) { <- total::add(item) }) is 6. Caveat: the start value comes first, labelled startingWith.
• 1_000. Digit groups are separated with _, after a decimal point too: 1_000.000_5. Caveat: _ belongs to numbers only, so snake_case is not a name.
• "".split("\n") is [""]. ""::split(on "\n") prints [""]. Caveat: the separator is labelled on.

What is not in the language

Each entry names what stands in its place, where anything does.

• Operators. Arithmetic, comparison and logic are method calls.
• null and undefined. A value that may be missing is an Optional.
• Truthiness. A condition is a Boolean; if count is refused as condition-not-boolean.
• Exceptions. There is no throw, try or catch; a failure with a reason is a Result.
• Mutation of data. Records, lists and dictionaries are immutable; with builds a new record and append a new list.
• Loop statements. There is no for, while, break or continue; iteration is map, reduce and the loop family.
• Classes and new. A type names a shape, a namespace holds its methods, and a literal builds the value.
• Recursive type declarations. A type or choice cannot name itself, so a tree is not a type you can declare.
• Tuples. A pair is a record with two named members.
• File or JSON in the standard library. Terminal prints, writes, inspects and reads the program’s input, and Http sends a request.
• async, await and Promise. Work that has not run is a Future, a value: complete waits for what one answers with and start puts one in flight. See Asynchrony.
• Floating point. Integer and Rational are exact: 0.1::add(0.2)::is(0.3) is true.
• Calling JavaScript from Essence. An import names .es files only; a .js specifier is an invalid-module-specifier. JavaScript calls Essence instead, as Calling Essence from JavaScript shows.
• Call-site type arguments. identity<Integer>(1) is refused as foreign-syntax: a call writes no type arguments, and every one of them is inferred.
• More than one protocol bound per parameter. <infer T is A, is B> is a syntax error. Combine them through a protocol: protocol Both is A, is B is the one bound.
• Reading program arguments. No standard-library function reads the arguments a program was started with.