esql-js

@elastic/esql is the core language-tooling package of the esql-js monorepo, giving JavaScript and TypeScript codebases a full toolchain for working with Elasticsearch’s ES|QL query language. It exposes a synchronous Parser that turns query strings into a typed abstract syntax tree, a tagged-template esql composer for building parameterized queries safely, and Walker/Visitor/mutate utilities for traversing and rewriting that tree without hand-rolling string manipulation.

The package re-exports the grammar, type definitions, and traversal primitives from its sibling workspace packages (esql-ast, esql-parser, esql-traversal, esql-types, esql-definitions) behind one entry point, so consumers install a single dependency instead of wiring together the individual pieces. It is maintained by the Kibana ES|QL team and used directly inside Kibana and other Elastic tooling to power query editors, autocomplete, and query-building UIs.

What You Get

• A synchronous Parser.parse() API that converts ES|QL query strings into a typed AST, with an option to preserve comments and whitespace for round-trip formatting
• The esql tagged-template composer for building parameterized queries with safe value injection instead of string concatenation
• Walker for simple full-tree traversal and Visitor for typed, controlled traversal that threads input/output through the walk
• Named mutate helpers for structural AST edits (adding/removing commands, renaming columns, etc.) without re-parsing
• BasicPrettyPrinter and WrappingPrettyPrinter for rendering an AST back to a readable, formatted query string
• Re-exported type definitions and language metadata (commands, functions, operators) synced from the elastic/elasticsearch source of truth

Common Use Cases

• Building an ES|QL query editor or autocomplete experience that needs a real AST instead of regex-based parsing
• Programmatically constructing ES|QL queries from application state using the esql composer or the sibling query-builder DSL
• Validating or linting user-submitted ES|QL queries before sending them to Elasticsearch
• Writing tooling that rewrites or migrates existing ES|QL queries (e.g. renaming a field across saved queries) via mutate and Visitor
• Embedding ES|QL syntax highlighting or language support in editors (Monaco, CodeMirror, Prism) using the sibling grammar packages

Under The Hood

Architecture The package is a thin, well-organized facade over a small compiler pipeline split across sibling workspace packages: esql-grammar provides ANTLR4-generated lexer/parser artifacts, esql-parser wraps them behind the Parser.parse() entry point (src/parser.ts), esql-ast and esql-traversal supply the AST node shapes plus Walker/Visitor/mutate traversal utilities, and src/pretty_print/ implements a Wadler-Lindig-style document algebra (via the standalone pretty-printer package) to render the AST back to formatted query text. src/composer/ layers a tagged-template esql API and a synth module on top of the parser for building queries programmatically with parameterized holes. Because each concern lives in its own workspace package with a narrow public surface, swapping the underlying grammar or adding a new traversal strategy touches one package rather than rippling through the whole tree.

Tech Stack TypeScript throughout, built with tsup for the distributable bundle and tsc for declaration files, targeting both CJS and ESM consumers via dual exports entries. The grammar packages use antlr4 (4.13.2) as their parser-generator runtime; tree-dump and tslib are the only non-dev runtime dependencies of the core package itself. The monorepo is managed with Yarn 4 workspaces, changesets for versioned releases, and a Buildkite pipeline dedicated to keeping the ANTLR grammars in sync with the upstream elastic/elasticsearch grammar source.

Code Quality The esql package alone carries dozens of Jest test files (__tests__/ directories under composer/, ast/, pretty_print/), including scenario-style tests for the composer and dedicated promql-composer tests, run via a shared jest.config.base.js across all workspaces. Strict TypeScript (strict: true in tsconfig.base.json) is enforced repo-wide, ESLint plus Prettier run via lint-staged on commit through Husky hooks, and each source file carries a standard Elastic License header, indicating consistent tooling discipline across the monorepo rather than ad hoc per-package conventions.

What Makes It Unique Most ES|QL tooling in the wild treats the language as a string to template or regex-match; this package instead gives it a full parser-to-AST-to-printer pipeline with typed traversal, mirroring how a real language toolchain is built, and keeps it in sync with Elasticsearch’s own grammar via an automated Buildkite sync job rather than manual updates. Bundling that with a companion query-builder DSL and multiple editor-grammar packages (Monaco, Prism, TextMate) in the same monorepo gives consumers a coherent, first-party toolkit rather than a single isolated parser.