Skip to content

API.md

Latest commit

 

History

History
37 lines (28 loc) · 1.5 KB

API.md

File metadata and controls

37 lines (28 loc) · 1.5 KB
Raw

Public API

Parse

Use parsePromQL, parseLogQL, or parseTraceQL when diagnostics are part of the calling workflow. Each returns { ast?, diagnostics, parserVersion, astSchemaVersion, source }. Use the corresponding OrThrow function when a QueryAstError is preferable.

Every parser accepts bounded ParseOptions. Defaults cap source bytes, tokens, AST nodes, nesting, literal bytes, regular-expression bytes, and diagnostics. Grafana variables are preserved and replaced only in an equal-width internal parser view.

Inspect and transform

  • sourceText(node, source) returns the exact original slice.
  • iterateAst(root) traverses in source-tree order.
  • visitAst(root, visitor) provides enter/leave hooks and ancestors.
  • rewriteAst(root, callback) performs immutable structural sharing.
  • queryCharacteristics(ast) returns bounded planning inputs.
  • extractFeatures(ast) returns stable, source-located capability IDs.
  • validateAst(ast, extensions) performs semantic validation.

Print

printSource returns byte-for-byte source text. printCanonical normalizes insignificant whitespace while preserving quoted content and Grafana variables. A canonical result is required to reparse under the same pinned parser triplet.

Stability

AST JSON schema version, npm package version, feature registry version, and parser triplet are versioned independently. Node kind unions are generated from the exact upstream grammar manifests; a grammar change makes the generated-artifact check fail.