request-converter

request-converter is Elastic’s official library for translating Elasticsearch requests written in Dev Console syntax into working code for six target formats: curl, Python, JavaScript, PHP, Ruby, and C#. It parses the Dev Console script against the Elasticsearch API specification, resolves each request to its matching API definition, and renders idiomatic client code through per-language template exporters.

Beyond the core convertRequests and listFormats functions, the library exposes a documented FormatExporter interface so consumers can register custom output formats, plus ExternalExporter, SubprocessExporter, and WebExporter base classes for wiring in exporters that run out-of-process, as a WASM bundle, or as a remote web service (the shipped C# exporter uses exactly this pattern to delegate to a separately published .NET WASM bundle). A thin CLI (es-request-converter) wraps the same API for terminal use, and a hosted browser demo lets users try conversions without installing anything.

What You Get

• A convertRequests(source, format, options) function that parses Dev Console syntax and emits code for curl, Python, JavaScript, PHP, Ruby, or C#
• A listFormats() helper that enumerates the currently supported output languages
• Per-format options (e.g. complete, printResponse, elasticsearchUrl) documented per exporter, including snake_case wire-compatible options for the C# exporter
• A FormatExporter interface plus ExternalExporter/SubprocessExporter/WebExporter base classes for adding or hosting custom exporters
• A bundled es-request-converter CLI that pipes stdin Dev Console text through the same conversion logic
• A getCompletions API for building Dev Console-style autocomplete on top of the Elasticsearch spec

Common Use Cases

• Turning Dev Console examples copied from Elasticsearch or Kibana docs into runnable application code in your target language
• Building internal tooling or docs sites that need to show the same Elasticsearch request in multiple client languages
• Powering the CLI or library programmatically in CI/build scripts to keep multi-language code samples in sync with a canonical Dev Console script
• Prototyping Elasticsearch queries in Dev Console, then converting them straight into a Python/JS/PHP/Ruby/C# script for production use

Under The Hood

Architecture The library parses Dev Console syntax with a PEG.js grammar (src/es_parser.pegjs, compiled to src/es_parser.ts via ts-pegjs) into structured ParsedRequest objects (src/parse.ts), matching each request’s path against the Elasticsearch API specification (schema.json/metamodel.ts) using a radix router (find-my-way-ts) to resolve the API name, availability, and accepted media types. Resolved requests are handed to a per-language FormatExporter (src/exporters/*.ts) that renders a precompiled Handlebars template (*.tpl) into the target code. A thin cli.ts wraps convertRequests for terminal use, and the C# exporter is the architectural outlier: rather than templating in-process, it delegates to a separately published .NET WASM bundle via the library’s own ExternalExporter/SubprocessExporter/WebExporter abstraction, which lets any exporter run out-of-process, as WASM, or as a remote web service.

Tech Stack Written in TypeScript, compiled to CommonJS via tsc, with Handlebars templates precompiled at build time (compile-templates.mjs) rather than parsed at runtime. Parsing relies on PEG.js/ts-pegjs-generated grammar code and find-my-way-ts for spec-route matching; base64url encodes payloads passed to subprocess and external exporters; commander drives the CLI; prettier is a runtime dependency used to format generated code. Testing runs on Jest (with jest-expect-message) with coverage collection, linting on ESLint (eslint-config-standard plus typescript-eslint) and Prettier enforced via Husky pre-commit hooks, API docs generated with TypeDoc, and CI/publish/integration workflows run on GitHub Actions.

Code Quality The project pairs a focused unit test suite (tests/parse.test.ts, tests/convert.test.ts, tests/complete.test.ts) with an unusually thorough integration suite: it actually executes the generated code against live Elasticsearch language clients (Python, JavaScript, PHP, Ruby, curl) and diffs the resulting HTTP requests against the original examples pulled straight from the Elasticsearch specification, with a documented skip-list (tests/integration/skip.ts) for known-divergent cases. Public functions carry JSDoc describing parameters and return values, errors are raised as explicit typed Errors rather than swallowed, and style is enforced by ESLint/Prettier in CI and pre-commit hooks.

API Design The public surface is intentionally small — convertRequests and listFormats cover the common path in one async call, with an options bag for per-exporter behavior. Consumers who need a format the library doesn’t ship can implement the documented FormatExporter interface directly, or reuse the ExternalExporter/SubprocessExporter/WebExporter base classes to host an exporter as WASM, a subprocess, or a remote service — the same mechanism the library uses internally for its own C# exporter. The bundled CLI and hosted browser demo both wrap this same API, so there’s no separate mental model to learn between the terminal, script, and browser paths.