Calcit Programming Language

A typed functional language for interactive and real-time applications. Built with Rust and compiling to JavaScript ES Modules.

• Home https://calcit-lang.org/
• API Doc https://apis.calcit-lang.org/
• Guidebook https://guide.calcit-lang.org/

Browse examples or also try WASM version online.

Core design:

• Interpreter runs on Rust, extensible with Rust FFI
• Persistent Data Structure
• Indentation-based Cirru syntax, friendly to plain text editing
• Code-as-data macros and functional style
• Nominal structs/enums, traits, methods, Option/Result, and static analysis
• Compiles to JavaScript in ES Modules, JavaScript Interop
• Hot code swapping friendly

Current direction:

• 编译后端的新增投入集中在 WebAssembly，并以共享 Calcit 语义用例逐步扩大可编译范围
• calcit.cirru is the canonical source snapshot; retired compact.cirru inputs receive migration guidance
• CLI-first development with the calcit runtime and the independently released caps package manager, designed to work well with AI agents in terminal workflows
• Better CLI editing and validation for CI, docs lookup, module management, and incremental updates
• Consistent support for real-time web applications: typed WebSocket messages, deterministic state updates, diff/patch synchronization, acknowledgement, and resynchronization

Repository Boundaries

Calcit keeps language semantics, runtime behavior, backend lowering, the calcit CLI/Agent interface, and versioned language documentation in this repository. Products with independent dependencies and release cadence are maintained separately or tracked for extraction:

Module	Status and ownership
calcit-bindgen	独立的实验性生成器；负责确定性的 Rust/Calcit/TypeScript/WIT generation、manifest、compatibility diff 与 stale check。已覆盖 Struct record、闭合单态 Enum 与明确宽度数值；0.1.7 把 Component Interface IR v4、async export/import、作用域化有界字节流与有界 WASI HTTP client 打包为可运行 Component，并生成读取严格 Cirru EDN 参数/结果的默认拒绝 Wasmtime host；支持经 preopen 授权的文件参数/结果与稳定业务退出码，真实 Cargo 运行后仍可 check 与安全再生成。resource、HTTP service 等后续能力继续按独立 milestone 推进。core 只保留 Interface IR export/schema/conformance；已完成的 generator 拆分由 #544 追踪。
calcit-native-ffi	Independent production shared ABI/helper crate for native modules; canonical ABI ownership is tracked in calcit-native-ffi#7.
caps	Independent production package manager released as the calcit-caps crate; the completed core cutover is tracked in #555.

See #549 for the bilingual repository-boundary roadmap. Calcit has no near-term LSP plan, so analysis and Agent CLI capabilities remain in this repository and release unit rather than being split for a hypothetical consumer.

Install

Build and install with Rust:

# get Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# install the independently versioned user-facing tools
cargo install calcit --bin calcit
cargo install calcit-caps

Installed binaries:

• calcit, the runtime and JS compiler
• caps, for downloading dependencies declared in deps.cirru

从首次包含该资产的版本起，Ubuntu 22.04 x86_64 的低资源机器可下载 Release 中的 calcit-ubuntu22.04-x86_64-no-wasm，无需在本机编译；安装与功能边界见 无 WASM 构建。源码构建可用 cargo build --release --no-default-features --bin calcit 关闭 WASM/WASI 代码生成依赖，native 运行与 JS 编译仍可使用。

When developing Calcit core from source, install its runtime locally and install caps from its own release:

cargo install --path . --bin calcit
cargo install calcit-caps

For new GitHub Actions workflows, use setup-calcit@v1. It installs the Calcit version declared in deps.cirru, installs a separately versioned stable caps release, and creates a lightweight cr -> calcit compatibility link for existing workflow commands. For pre-rename Calcit releases it falls back to cr and exposes the equivalent calcit command. Local Calcit releases no longer include caps; migrate local scripts directly instead of relying on a wrapper. Existing setup-cr workflow tags remain supported.

Quick Start

Evaluate snippets:

calcit eval 'range 100'

calcit eval -- '-> 100 range (map $ \ * % %)'

Run with the canonical runtime snapshot calcit.cirru:

calcit calcit.cirru # run once (default)
calcit # reads calcit.cirru from the current directory

calcit -w # watch mode (explicit flag required)

By default Calcit reads :init-fn and :reload-fn from calcit.cirru :entries.default. You may also specify functions:

calcit --init-fn='app.main/main!' --reload-fn='app.main/reload!'

You may also configure :entries in calcit.cirru:

calcit --entry server

JavaScript codegen

Calcit compiles to JavaScript with consistent semantics. In browser or Node projects, JavaScript interop is still expected.

calcit js # compile to js, also picks `calcit.cirru` by default
calcit js --emit-path=out/ # compile to js and save in `out/`

By default, js code is generated to js-out/. You will need Vite or Node to run it, from an entry file:

import { main_$x_, reload_$x_ } from "./js-out/app.main.mjs";
main_$x_(); // which corresponds to `main!` function in calcit

CLI and Agent Workflow

常规修改先读取紧凑 Agent 契约，再查询、结构化编辑并验证；复杂操作按需读取完整指南。不要把 calcit.cirru Snapshot 当作普通文本直接改写。

Common commands:

calcit docs agents --contract # read the compact mutation contract first
calcit query search 'foo'   # locate code by symbol or string
calcit edit ...             # structured edits for defs, imports, config, modules
calcit js                   # compile once
calcit js -w                # watch mode
caps                         # install/update dependencies from deps.cirru

Calcit Editor is no longer the recommended path for everyday development. If you still need the older editor workflow, see Calcit Editor.

Related examples and workflows:

• Minimal Calcit
• Respo Calcit Workflow
• setup-calcit for new GitHub Actions workflows

Modules

deps.cirru declares dependencies that need to download, which correspond to repositories on GitHub. Specify a branch or a tag:

{} (:calcit-version |0.9.11)
  :dependencies $ {} (|calcit-lang/memof |0.0.11) (|calcit-lang/lilac |main)
  :dev-dependencies $ {} (|calcit-lang/calcit-test |0.1.0)

Run caps to resolve the recursive dependency graph and install it. Immutable revisions are stored under ~/.config/calcit/module-caches/, while the current project receives links under .calcit/modules/. Different projects can therefore use different revisions without switching a shared checkout. Existing project module links are the only runtime source for package-style module paths; explicit relative and absolute paths retain their normal direct resolution.

Published SemVer tags are preferred. Branch refs remain supported for development, but caps warns with the resolved commit. When a graph requests several SemVer tags for one repository, the highest requested version is selected and reported.

Root projects install both :dependencies and :dev-dependencies. Recursive resolution only follows :dependencies, so test and maintenance modules declared by a dependency do not leak into consumers. Use caps add --dev <org/repo>@<ref> and caps remove --dev <org/repo> to manage the development group.

:calcit-version helps with version checks and provides hints in CI.

To load modules, use :modules configuration and the runtime snapshot file calcit.cirru:

:entries $ {}
  :default $ {}
    :modules $ [] |memof/calcit.cirru |lilac/

Paths defined in :modules load from the snapshot directory's .calcit/modules/, e.g. .calcit/modules/memof/calcit.cirru. Run caps to materialize or refresh that project-local view.

Modules ending with / are automatically suffixed with calcit.cirru. A module containing only retired compact.cirru is rejected with migration guidance.

Inspect and verify the resolved graph with:

caps tree
caps why calcit-lang/memof
caps status
caps verify
caps verify --toolchain # after yarn install, for JS projects

Development

Local validation commands:

# run tests in Rust
cargo run --bin calcit -- calcit/test.cirru

# run tests in Node.js
cargo run --bin calcit -- calcit/test.cirru js && yarn try-js

# run snippet
cargo run --bin calcit -- eval 'range 100'

# internal compiler/WASM validation when working on this repository
cargo run --bin calcit -- calcit/test.cirru ir
yarn try-wasm

For repository development, the usual validation flow is:

cargo fmt
cargo clippy -- -D warnings
yarn compile
cargo test
yarn check-all

• Cirru Parser for indentation-based syntax parsing.
• Cirru EDN for canonical runtime snapshot parsing (calcit.cirru).
• FingerVec for the immutable List data structure.

Other tools:

• Error Viewer for displaying .calcit/error.cirru
• IR Viewer for rendering program-ir.cirru

Some resources:

• Dev Logs https://github.com/calcit-lang/calcit/discussions
• 视频记录 https://space.bilibili.com/14227306/channel/seriesdetail?sid=281171

License

MIT