Skip to content
BranchesTags

Repository files navigation

Calcit Programming Language

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

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:

  • 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 Independent experimental production generator owning deterministic Rust/Calcit/TypeScript/WIT generation, manifests, compatibility diff, and stale checks. Core retains only Interface IR export/schema/conformance; the completed cutover is tracked in #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.
calcit-calx-bench Independent experimental harness and report archive consuming core's revision-pinned session adapter; the completed adapter migration and core product-asset cutover are tracked in #558 and #559, while Calx lowering, cache, runtime semantics, and correctness gates remain in core.

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 GitHub Release

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

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

The recommended workflow is plain text editing plus CLI validation, often driven by an AI agent in terminal.

Common commands:

calcit docs agents --full   # read the current agent workflow guide
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:

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).
  • Ternary Tree for immutable list data structure.

Other tools:

Some resources:

License

MIT

About

Indentation-based ClojureScript dialect in Rust and compiling to JavaScript ES Modules

calcit-lang.org/

Topics

cirruclojureclojurescriptimmutable-data-structuresindentationlanguagelisp

Resources

Readme
Activity
Custom properties

Stars

143 stars

Watchers

5 watching

Forks

3 forks
Report repository

Releases

Used by

Contributors

Languages