hyperlark (TypeScript)

Hyperlark

Hyperlark is a Rust reimplementation of the Lark parsing toolkit, compiled to WebAssembly, with a JS/TS interface.

Hyperlark can parse all context-free languages. To put it simply, it means that it is capable of parsing almost any programming language out there, and to some degree most natural languages too.

Hyperlark is competitive in speed with the fastest JS parsers, and provides a lot more features and parsing power. Hyperlark also provides interfaces for Python, Rust and C.

Status: 0.1.0-beta.1 — pre-1.0, APIs may still change between betas.

Install

npm install hyperlark@beta

(hyperlark is still in beta, so use the beta dist-tag and not latest)

Runs on Node ≥ 20 and in the browser, bundlers, Deno, Bun and edge.

We currently offer 3 entrypoints:

Entry	Loads the wasm	Compiles `.lark` source
`hyperlark`	synchronously (Node only)	yes
`hyperlark/web`	asynchronously, via `await init()`	yes
`hyperlark/slim`	synchronously (Node only)	no — `Lark.fromJSON` only

slim drops the grammar compiler, the heaviest component in the module, for a noticeably smaller download; it can only load a grammar compiled ahead of time.

Not supported: threads. The binding is single-threaded by design.

Hello World

import { Lark, pretty } from "hyperlark";

const parser = new Lark(`
    start: WORD+
    %import common.WORD
    %ignore " "
`);

const tree = parser.parse("hello world");
console.log(pretty(tree));

In a browser, a bundler, Deno or an edge runtime, import hyperlark/web and await init() once before the first parse. Everything after that is identical:

import init from "hyperlark/web";

const { Lark } = await init();          // idempotent; auto-fetches the .wasm
const tree = new Lark(grammar).parse("hello world");

For complete, runnable programs — a calculator, JSON streaming, ambiguity, interactive parsing — see the examples page.

Features

An industry-standard grammar. Lark is widely used, its grammar syntax was adopted by OpenAI for their official API, and .lark files get syntax highlighting on GitHub.
Choose between LALR(1) and Earley (SPPF) parsers. LALR(1) is fast, linear-time and low on memory. Earley can parse every context-free grammar, and can efficiently handle and store every ambiguity, for later queries.
Choose between several lexers, or provide your own. Hyperlark provides sophisticated lexers that can help LALR(1) disambiguate tokens based on the parser state, and that help Earley handle lexical ambiguities much faster than scannerless methods. A postlex pass, such as the bundled Indenter, covers indentation-sensitive languages.
Automatic tree construction. Use the Transformer / Visitor / Interpreter classes on the parse tree, or pass a transformer to parse(text, { transformer }) to skip tree construction entirely.
Interactive parsing (for LALR). Drive the parser and query it at any point of the parse. Useful for error handling, checkpoints & backtracking, and even debugging.
Line positions. Hyperlark keeps track of the line and column of every token, and will even propagate the ranges to the tree nodes when propagate_positions: true.
Grammar composition. Import rules, terminals, or entire grammars into your grammar, using an inheritance-like interface (namespaces, overrides), for better re-use and modularity.
Typed end to end. The package ships its own .d.ts; trees, tokens, errors and options are all typed, and a transformer's fold result is inferred.

Performance

Hyperlark is in the same class as the fastest JS parser libraries, like peggy and chevrotain.

Actual speed depends on grammar, input size and how Hyperlark is used.

For more information, see the benchmarks.

License

Free for noncommercial use, including evaluation and testing inside commercial organizations. Commercial use requires a separate license — contact [email protected].