@geastack/compiler

中文文档
1.0.49发布于 2026/10/29Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 4029

The geastack TypeScript-to-C++ compiler: one semantic spine, no source-shaped authority, no boxing of statically typed values.

原始使用文档
文档目录10 节
  1. Where it fits in GeaStack
  2. Layering
  3. Constraints
  4. Architecture gate
  5. Diagnostics
  6. Coverage
  7. Carriers
  8. Emitting C++
  9. npm scripts
  10. License

geatsc

geatsc compiles TypeScript ahead of time to C++. The output contains no JavaScript engine or interpreter. A C++ toolchain builds it into a native binary for the target: ESP32 or RP2350 firmware, a macOS, iOS, Linux or Windows app, an Xbox game, or a server executable.

The input is an ordinary TypeScript program, type-checked by the TypeScript compiler. geatsc uses those types to pick native C++ representations: classes become structs, numbers become native numeric types, and typed arrays, maps and records become typed containers. This is what lets the same TypeScript run on a microcontroller, and lets a compiled server use a fraction of the memory the same code needs under Node.

Where it fits in GeaStack

geatsc is the compiler for GeaStack, a framework for writing apps in TypeScript and JSX and running them natively on embedded boards, desktop, mobile and consoles. The other repositories plug into it:

  • core — the Gea framework (app API, reactivity, rendering engine, host services) and geatsc-plugin-gea, the plugin that teaches geatsc about Gea components and JSX.
  • cli — the gea command. gea build runs vite, and core's build-gea-vite-geatsc.mjs hands the module graph to geatsc compile-module-graph. The target's toolchain then builds the generated C++.
  • targets, apple, linux, windows — the platform projects that compile and link the generated C++. apple also ships a geatsc plugin for the Apple SDK bindings.
  • Xbox — the Xbox target is not open source; it is available commercially. Contact [email protected].
  • node-compat — the Node.js runtime and geatsc plugin for compiling Node servers (node:http, HTTP frameworks) to native executables. It is a dependency of this package: running geatsc with no input file inside a Node project builds each of the project's entry points through node-compat into dist/.

The Gea and Apple plugins are peer dependencies. Other plugins are loaded with --plugin; see docs/CLI-PLUGINS.md.

docs/ARCHITECTURE.md describes the pipeline, the layering and the constraints. CLAUDE.md has the code conventions.

Layering

identity/        canonical IDs
semantics/       target-neutral frontend: regions, structural types,
                 operations, edges, coverage
representation/  physical carriers, the sealed plan, fail-closed guards
conversion/      the closed dynamic-conversion capability algebra
preflight/       whole-pipeline capability census and certificate
ir/              typed IR: verified operations and SSA values
targets/cpp/     C++ emission; consumes typed IR only
diagnostics/     authority-component sweep, deterministic ordering

semantics/ is the frontend/backend boundary. Nothing after it may import typescript or touch a TypeScript AST.

Constraints

  1. No source-shaped authority. No decision may depend on a file name, path, source offset, .pos/.end/getStart() compared to a literal, source text, declaration or local spelling, statement layout, or generated C++ text. Identity is a checker symbol/declaration, a sealed semantic ID, or a versioned protocol identity.
  2. No boxing. A value with a static type never gets the dynamic carrier. Representation.dynamic is allowed only for the four DynamicReason values declared in src/representation/model.ts.
  3. Fail closed. When a guard fires, the defect is upstream. Do not relax a guard, downgrade an unresolved, or substitute a default for a missing fact. unresolved is lattice bottom, not an answer.

Architecture gate

scripts/architecture.mjs checks src/**/*.ts for:

  • file and directory size limits
  • RegExp literals under src/targets/cpp/
  • source-position literal comparisons
  • typescript imports outside src/semantics/
  • source-shaped discriminants
  • unclassified Authority/Admission/Proof contracts
  • class declarations under src/targets/
  • any

It reports every violation in one run.

Diagnostics

node dist/cli.js test/fixtures/spread.ts

Runs the full pipeline and prints every diagnostic. Exits non-zero when no capability certificate was minted. --preflight prints the obligation census as canonical NDJSON.

Coverage

node dist/cli.js coverage app/index.ts --plugin ../node-compat/plugin/v2.mjs

Prints one row per statement with a code, a status and a one-line reason, followed by a summary and a count per code. Boxed carriers are reported as rows too. Exits 0 only if a certificate was minted and nothing was refused during lowering or emission.

CodeLayer
G1xxxTypeScript checker errors
G2xxxcensus blocker: a language primitive family the compiler lacks
G3xxxrepresentation guard violation
G4xxxpreflight obligation missing/unsupported, by obligation kind
G5xxxIR lowering blocker
G6xxxemission refusal, by emitter category
G7xxxcalling-convention (ABI) projection blocker
G8xxxboxed carrier (gea::Value), by reason

The trailing digits index fixed tables in src/cli-coverage.ts, so rewording a message does not change its code. x999 means the table has no row for it.

Options: --project/--no-project, --plugin, --plugin-option, --json (rows and summary as one object), --no-derived (roots only), --no-boxed (refusals only).

Carriers

node scripts/probe-carriers.mjs test/fixtures/language.ts

Prints the carrier and C++ spelling chosen for every declaration, and counts unresolved and boxed carriers.

Emitting C++

node dist/cli.js compile app/index.ts --out-dir build/generated

The gea build pipeline runs this command (build-gea-vite-geatsc.mjs passes it through --geatsc-bin). It writes to --out-dir:

  • the generated C++
  • gea_runtime.h and generated_support.hpp
  • any files the installed hosts need beside the unit
  • geatsc-sources.txt, the list of .cpp files to compile
  • geatsc-header.txt (per-file layout only), the shared header to precompile
OptionMeaning
--project <tsconfig.json>Project to compile the input under. Default: the nearest one. A .js bundle has none.
--entry-symbol <name>C++ function the program starts at. Default __gea_top_level, called by core/gea_app_entry.cpp.
--dynamic-fallbackAllow boxed C++ runtime dispatch for supported dynamic features. No JavaScript engine is involved. See docs/DYNAMIC-FALLBACK.md.
--isolate-symbolsMake every definition private to this program, for builds that link several programs into one binary. Programs that cannot be isolated are refused.
--translation-units single | per-file | balancedsingle (default): one C++ file. per-file: one file per source file, plus a shared <stem>.hpp and a program unit. balanced: per-file with small units grouped. See docs/TRANSLATION-UNITS.md.
--plugin <module>Load a compiler plugin. Repeatable. See docs/CLI-PLUGINS.md.
--plugin-option <lib.key>=<value>Passed unchanged to the library named by the prefix, e.g. gea.cpp-prelude=....

compile-module-graph <gea-module-graph.json> --entry <file> does the same from vite's module graph instead of files on disk. Application builds use this form. It takes the same options.

npm scripts

ScriptPurpose
architectureRun the architecture gate
typechecktsc -p tsconfig.json --noEmit
buildArchitecture gate, then compile to dist/
formatprettier --write .
format:checkprettier --check .
checkArchitecture gate, typecheck and format check

License

The compiler and the runtime it links into generated programs are Apache-2.0 (see LICENSE). Programs you compile with geatsc are yours; their license depends only on what they link. The GeaStack framework and the desktop, mobile and web targets are also Apache-2.0. The embedded board support (targets, @geastack/chips) is GPL-3.0-only; closed-source firmware needs a commercial license. Contact [email protected] for commercial terms.

版本与发布记录

@geastack/compiler 共发布 49 个版本,首次发布于 2026/09/20;过去 12 个月发布了 49 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.0.49latest2026/10/2917 天前
1.0.482026/10/2720 天前
1.0.472026/10/2422 天前
1.0.462026/10/2324 天前
1.0.452026/10/2324 天前
1.0.442026/10/2225 天前

其他发布通道:next → 1.0.21。

关于 @geastack/compiler 的常见问题

@geastack/compiler 是什么?

The geastack TypeScript-to-C++ compiler: one semantic spine, no source-shaped authority, no boxing of statically typed values.

如何安装 @geastack/compiler?

在项目目录运行 npm install @geastack/compiler,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 geatsc,可以用 npx geatsc 直接运行。

@geastack/compiler 支持 TypeScript 吗?

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

@geastack/compiler 支持 ESM 还是 CommonJS?

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

@geastack/compiler 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20.19。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@geastack/compiler 可以商用吗?

@geastack/compiler 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@geastack/compiler 的下载量有多少?

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

@geastack/compiler 还在维护吗?

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