@gooddata/maql-antlr4ts

中文文档
0.7.2发布于 2026/10/27MITTypeScriptES Module近 30 天下载 4.2万

TypeScript lexer and parser for MAQL

原始使用文档
文档目录4 节
  1. Local development
  2. Linking the package to other modules
  3. Publishing
  4. Trusted publisher setup

MAQL ANTLR4TS npm package

The module bundles TypeScript MAQL lexer and parser generated from MAQL grammar, a visitor to create MAQL AST, and an abstract AST visitor to work with MAQL AST.

The lexer and parser are generated by antlr-ng and run on the antlr4ng runtime, which is declared as a dependency of this package. The runtime has no dependencies of its own and no Node.js built-in requirements, so the package works in browsers without polyfills.

Note: antlr4ng must resolve to a single copy in the consuming application. If the application depends on antlr4ng directly or through another package (for example antlr4-c3), it must use the exact same version as this package, otherwise instanceof checks between the runtime copies fail.

The package name keeps the historical antlr4ts suffix; the antlr4ts runtime is no longer used.

Example usage:

import { CharStream, CommonTokenStream } from "antlr4ng";

import { MaqlLexer, MaqlParser, MaqlAstVisitor, AstNormalizer } from "@gooddata/maql-antlr4ts";

const maql =
    "parse metric SELECT SUM(0.81 * {fact/price} * {fact/quantity}) BY {attribute/country} WITHOUT PF";
const charStream = CharStream.fromString(maql);
const lexer = new MaqlLexer(charStream);
const tokenStream = new CommonTokenStream(lexer);
const parser = new MaqlParser(tokenStream);
const parseTree = parser.maql();
const astVisitor = new MaqlAstVisitor(workspace, tokenStream);
const ast = astVisitor.visit(parseTree);
const normalizer = new AstNormalizer();
const normalizedAst = normalizer.visit(ast);

The grammar declares the caseInsensitive option and the generated lexer honors it, so MAQL keywords may be written in any letter case with a plain CharStream.

Use the exported CaseInsensitiveCharStream instead of CharStream.fromString when token positions have to match JavaScript string offsets or LSP ranges. The antlr4ng stream indexes by Unicode code point, so a character outside the Basic Multilingual Plane (an emoji, for example) shifts every following start, stop and column by one against the source string. CaseInsensitiveCharStream indexes by UTF-16 code unit, so its positions are string offsets.

Local development

Requirements: pnpm

commandeffect
pnpm installinstall all dependencies
pnpm buildgenerate source files, type-check, and compile into esm/
pnpm codegengenerate source files from MAQL grammar and function definitions
pnpm antlr4generate lexer, parser, listener and visitor from the MAQL grammar
pnpm funcdefgenerate source files from MAQL function definitions
pnpm build-checktype-check all sources, including tests
pnpm build-tscompile src/ into esm/ without type-checking
pnpm cleanremove the esm/ output
pnpm testrun all tests in watch mode
pnpm test-oncerun all tests once
pnpm test-cirun all tests once with a junit.xml output file
pnpm lintrun oxlint and ESLint
pnpm lint-fixautomatically fix oxlint and ESLint errors
pnpm formatcheck formatting with oxfmt
pnpm format-fixautomatically fix formatting with oxfmt
pnpm validaterun pnpm lint and pnpm format

The ANTLR grammar lives in ../maql-parser/src/main/antlr. Generated sources go to src/gen/ and are not committed; pnpm build regenerates them. The generator runs on Node.js, no Java is required.

Linking the package to other modules

First install the dependencies, then build the module.

pnpm install

pnpm build

Warning: Do not use pnpm link or npm link.

Symbolically linking this package can make the consuming application load a second copy of the antlr4ng runtime, which breaks instanceof checks between the two copies at runtime.

Use yalc to link the package to other repositories.

  1. Run yalc publish in the current directory.
  2. Run yalc add @gooddata/maql-antlr4ts in the target directory
  3. Once you are done with testing run yalc remove @gooddata/maql-antlr4ts or yalc remove --all

Publishing

To publish the package, run the publish_maql_antlr4ts_npm GitHub workflow manually.

The workflow publishes a prerelease version <package.json version + 1 patch>-<commit sha>.0, for example 0.5.1-a5e4f136.0. It moves the npm latest dist-tag to this version. It does not commit the version back. To raise the base version, change version in package.json in a PR before you run the workflow.

The workflow publishes to npm with trusted publishing (OIDC), so it does not need an npm token. Trusted publishing does not support self-hosted runners, so the workflow runs on a GitHub-hosted runner.

Trusted publisher setup

The trusted publisher for the package is set once on npm. This section records how it was set up, so that you can change it or set it up again.

You can set it up in one of these ways:

  • In the npm UI at https://www.npmjs.com/package/@gooddata/maql-antlr4ts/access.

  • With the npm CLI. Use npm 11.10.0 or newer, which has the npm trust command. Log in to npm (npm login) as user gooddata-ci. The user must have publish access to @gooddata/maql-antlr4ts and two-factor authentication. Then run:

    npm trust github @gooddata/maql-antlr4ts \
        --file publish_maql_antlr4ts_npm.yml \
        --repo gooddata/gdc-nas \
        --allow-publish
    

To see the current configuration, run npm trust list @gooddata/maql-antlr4ts.

版本与发布记录

@gooddata/maql-antlr4ts 共发布 784 个版本,首次发布于 2023/07/18;过去 12 个月发布了 158 个版本。

版本发布日期距今
0.7.2latest2026/10/2720 天前
0.7.2-58cc7118.0prerelease2026/10/2720 天前
0.7.12026/10/2720 天前
0.7.2-567f11f5.02026/10/2720 天前
0.7.1-94ac12dd.02026/10/2720 天前
0.6.1-0c023234.02026/10/2720 天前

关于 @gooddata/maql-antlr4ts 的常见问题

@gooddata/maql-antlr4ts 是什么?

TypeScript lexer and parser for MAQL

如何安装 @gooddata/maql-antlr4ts?

在项目目录运行 npm install @gooddata/maql-antlr4ts,或使用 pnpm add / yarn add / bun add。

@gooddata/maql-antlr4ts 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gooddata/maql-antlr4ts 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gooddata/maql-antlr4ts 可以商用吗?

@gooddata/maql-antlr4ts 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gooddata/maql-antlr4ts 的下载量有多少?

根据 npm 官方下载统计,@gooddata/maql-antlr4ts 在 2026/10/17 – 2026/11/15 这 30 天内被下载 41,764 次,日均约 1,392 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gooddata/maql-antlr4ts 还在维护吗?

最新版本 0.7.2 发布于 2026/10/27(20 天前);至今共发布 784 个版本,其中过去 12 个月发布了 158 个;首次发布于 2023/07/18。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。