Editor setup

Install from the Marketplace

code --install-extension essence.essence-language

The extension is essence.essence-language on the Visual Studio Marketplace, listed as Essence. Search for Essence in the Extensions view, or run the command above in a terminal. It is not on Open VSX, the registry VSCodium installs from. In VSCodium, or another editor built from VS Code that installs from Open VSX, build the .vsix below and install that file.

Nothing has to be on your PATH for the language features. The server ships inside the extension and runs on VS Code’s own Node. VS Code’s TypeScript support ships its language service the same way, which is why it works without a typescript package installed.

A checkout of the Essence repository builds the extension, which is also the route for working on it:

bun run --cwd packages/vscode-extension package

The command writes essence-language-<version>.vsix into packages/vscode-extension, with the server bundled inside. Install that file with Extensions: Install from VSIX… in the Command Palette, or pass its path to code --install-extension.

Debugging needs more: the essence command, and a Node to run your program on. The extension looks for both on your PATH, then in the directories their installers use, then through your login shell. essence.cli.path and essence.node.path name them outright, and essence.bun.path names the Bun a checkout’s essence runs on. Debugging covers the debugger and where the extension looks.

The bundled server is also the fallback. If the essence.server.path setting names a server of your own that cannot run, the extension runs its bundled server instead and shows a warning.

Watch it work

Open a folder in VS Code and save this program in it as lights.es. Open the folder rather than the lone file, because references, renames and the project-wide Problems list work from the workspace folders.

implementation {

	choice Light {
		Red,
		Amber,
		Green,
	}

	§§ Whether a driver arriving at this Light has to stop.
	§§ @param _ — the Light as it is showing now.
	§§ @returns — true for every Light that is not Green.
	function waiting(_ light: Light) -> Boolean {
		<- match light -> Boolean {
			case #Red   { <- true }
			case #Amber { <- true }
			case #Green { <- false }
		}
	}

	constant crossing = waiting(#Red)

	Terminal.print(crossing) § true
}

Light is a choice, a type with a fixed set of cases. The match in waiting has one arm per case. An arm is a case and the block it runs. With the essence command from Installation, essence run lights.es prints true.

Now delete the case #Amber line, so that the match handles two of the three cases. About 200 milliseconds after you stop typing, a red squiggle appears under the match expression. Hover it, or open the Problems panel, and the error shows its source and code: essence(missing-case).

The code, missing-case, is the error’s stable name. You can filter the Problems panel by it, and the Diagnostics reference documents every code. In a terminal, essence check lights.es prints the same error:

[missing-case]
Error: This Match Expression does not handle every Case
    ╭─┤ lights.es:13:6 │
    │
 13 │        <- match light -> Boolean {
    │                 ──┬──
    │                   ╰──── this is a Light
    │
    │ Help: Add 'case Light#Amber', or a 'case _' that covers the rest.
    │
    │ Note: Unhandled: 'Light#Amber'.
────╯

In the editor, the text drawn under the code, this is a Light, joins the first line. The hover reads “This Match Expression does not handle every Case: this is a Light”. The note and the help follow on lines of their own.

Compared with JavaScript.

type Light = "Red" | "Amber" | "Green"

function waiting(light: Light): boolean {
  switch (light) {
    case "Red":
      return true
    case "Green":
      return false
  }
}

With strict on, TypeScript reports ts(2366) on the return type, a missing return rather than a missing case. To have the case named, you write a never check in a default branch, or turn on a lint rule such as typescript-eslint’s switch-exhaustiveness-check. The Essence compiler names the case itself, and its codes play the part of ESLint’s rule names. More on Coming from JavaScript › Tooling.

A Quick Fix is an edit the editor offers for an error. Put the cursor on the squiggle and press Ctrl+. (Cmd+. on macOS). The lightbulb offers Add missing Cases. Accepting it adds one arm at the end of the match: case Light#Amber {}. Light#Amber is the case #Amber with its choice written in front.

The new arm’s body is empty on purpose, because the Quick Fix does not guess what the case returns. Until you fill it in, the file has a different error, missing-return: “Not every path through this Function returns”.

Write <- true into the new arm, then run Format Document. The formatter lines up the arms, and essence run lights.es prints true again:

implementation {

	choice Light {
		Red,
		Amber,
		Green,
	}

	§§ Whether a driver arriving at this Light has to stop.
	§§ @param _ — the Light as it is showing now.
	§§ @returns — true for every Light that is not Green.
	function waiting(_ light: Light) -> Boolean {
		<- match light -> Boolean {
			case #Red        { <- true }
			case #Green      { <- false }
			case Light#Amber { <- true }
		}
	}

	constant crossing = waiting(#Red)

	Terminal.print(crossing) § true
}

Hover waiting where it is declared. The hover shows the signature, then renders the §§ documentation block above the function:

function waiting(_ Light) -> Boolean

Whether a driver arriving at this Light has to stop.

light — the Light as it is showing now.

Returns — true for every Light that is not Green.

@param _ documents the first parameter. The _ before light in the signature means a call passes that argument with no label, as waiting(#Red) does. The hover shows the parameter under light, the name the function’s body uses.

constant crossing has no type written. An inlay hint is text the editor draws into a line that is not in the file. Here the editor draws a faint : Boolean after crossing. Double-click the hint and : Boolean is written into the source. The lightbulb on that line offers the same edit as Add explicit Type annotation ‘: Boolean’.

The server also runs your tests while you type, as Wallaby does for a JavaScript project. After an edit, this live test session re-runs only the test files the edit reached. Those are the edited file, if it has a tests { … } section, and every test file that imports it, directly or through other modules. A failed expect is a test-failed error in Problems, even in a file you have not opened. The values a run recorded show as inlay hints beside the lines that produced them. A code lens is a clickable line of text the editor draws above code, and Run and Debug lenses sit above every test and suite. The Testing view, coverage and the test settings are on Running tests.

Settings, commands and status

The extension has nine settings. The server reads four of them and applies a change without a restart. The extension reads the other five.

essence.server.path and essence.cli.path accept ${workspaceFolder}, ~ and paths relative to the workspace. Changing essence.server.path or essence.bun.path asks whether to restart the server.

Restricted Mode is how VS Code opens a workspace you have not trusted. There it ignores workspace values of the four settings that name a program to run: essence.server.path, essence.cli.path, essence.bun.path and essence.node.path. A repository cannot point them at a program it ships. The language features stay on there. Debugging is off, because VS Code blocks debug sessions in Restricted Mode.

The extension adds three commands to the Command Palette:

• Essence: Restart Language Server stops the server and starts it again.
• Essence: Re-run Failed Tests runs only the tests that failed last.
• Essence: Show Test Session Output opens the channel where each test cycle writes its summary.

An item on the right of the status bar reads Essence. Its icon spins while the server starts, shows a tick while it runs, and shows an error when the server has stopped or failed to start. Its tooltip names the server in use and what runs it. Clicking the item restarts the server.

The Essence channel in the Output panel logs each start: which server, which runtime ran it, and where that runtime was found. It also holds the server’s log, the traffic essence.trace.server asks for, and the text of any failure. A failure shows as a notification as well, with a Show Output button. When a runtime cannot be found, the channel lists every directory searched and the PATH that VS Code started with.

For .es files the extension sets tabs, four columns wide, turns indentation detection off and makes itself the default formatter. Format Document then runs the same formatter as essence format, inside the server. Formatting describes what it does.

VS Code opens essence.json, the project file covered on Projects and essence.json, the way it opens tsconfig.json: as JSON with comments. A schema that ships with the extension completes its keys and describes each one on hover. A mistake shows in Problems on the line that holds it, while you type. A misspelled key such as "exclusions" is an unknown-setting warning, and its note lists the settings that exist at that level.

Snippets come from the server, not from a file in the extension. The server offers a snippet only where the code it inserts would parse. At a statement inside implementation, the list holds constant, function, choice, namespace, if and doc (a §§ block), among others, but no test or case.