Axon Language Reference

Axon is an AI-native programming language that transpiles to JavaScript. It is designed from the ground up to be written, read, and reasoned about by language models — with unambiguous grammar, intent-first declarations, constraint-enforced types, and explicit effect tracking.

At a glance

Quick Start

Axon ships as a Node.js CLI. Install from source and run the compiler against any .axn file.

Hello, Axon

Design Goals

Functions

All functions in Axon are declared with fn. The :: separator introduces the full type signature. Functions are first-class values and can be passed as arguments or returned from other functions.

Full-form function

The canonical form uses :: to separate the name from the typed signature, with the body in a block.

Short-form function v0.5 expanded

When the body is a single expression, use = expr to eliminate the block. An optional return-type annotation is supported with ->. A block body { ... } is also valid without the :: sigil.

Nested functions v0.5

A fn declaration inside a block body is emitted as a let-bound lambda — a local helper scoped to the enclosing function.

Lambda expressions

.field accessor shorthand

A bare .fieldName in any expression position is syntactic sugar for a single-argument lambda that accesses that field. Chained access is supported.

Types & Constraints

Axon's primitive types map directly to JavaScript. Type aliases add names; where clauses add runtime-enforced predicates.

Primitive types

Type aliases

Constrained types with where

Any type alias can carry a where predicate. Functions parameterised by a constrained type automatically receive injected guard clauses — no manual validation needed.

Records

Records are named structured data types — plain objects with known fields. They have no methods and carry no behaviour; that belongs in standalone functions.

Immutable updates

Records are updated functionally. The spread operator returns a new record with changed fields; the original is untouched.

Enums

An enum declares a closed set of named string values. It compiles to a frozen, immutable object — safe to use as a constant, in pattern matching, and across module boundaries.

Enum pattern matching

Use the Enum.Variant syntax inside a match expression.

Generated output

Tagged Unions

Tagged unions (also called sum types or algebraic data types) express a value that is exactly one of several named variants. They are the preferred replacement for inheritance hierarchies.

Pattern Matching

match is an expression, not a statement. Every arm produces a value. The checker warns when a match is not exhaustive unless a wildcard arm is present.

Basic patterns

when guards

Any arm can carry a boolean guard. Guards have full access to names bound by the pattern.

Tagged union patterns

Pattern types

Pipelines

The pipeline operator |> threads a value through a sequence of transformations. Each step receives the previous step's result as its first argument.

|> as name — named intermediate results

Any pipeline step can be named with as. When present, the entire pipeline emits as an IIFE block with const bindings, making intermediates available for reuse or debugging.

Destructuring

Destructuring let unpacks object and array values into named bindings in a single statement.

Strings

String interpolation

Any string containing {ident} or {ident.prop} is automatically treated as an interpolated string. No extra syntax required.

Triple-quote strings """..."""

Multiline string literals that preserve newlines exactly. A leading newline immediately after """ is stripped for idiomatic alignment. Support the same {ident} interpolation as regular strings. Compile to JavaScript template literals.

Optional Chaining & Nullish Coalescing

Safe navigation through potentially-null values without nested conditionals.

Control Flow

Result Type & ? Propagation

Axon has a built-in Result<T> tagged union for explicit error handling. Construct values with ok() / err(), consume them with match or stdlib helpers, and chain fallible calls cleanly with the ? propagation operator.

Constructing and consuming Result

? — early-return on Err

@pure & @total

@pure declares that a function has no side effects — it does not access globals, mutate state, or call effectful methods. The checker verifies this statically.

@total declares that a function is defined for all inputs and will always return a value (no throws, no unbounded recursion).

@intent

The single most important annotation in Axon. @intent is a machine-readable natural language description of what a function is for — not what it does mechanically, but why it exists. It is preserved as a JSDoc @intent tag in generated output.

@effects

Declares the set of side effects a function produces. In v0.4 this is a documentation annotation; it becomes a compiler-enforced contract in v0.8 (The Async & Reactive Update).

@memo

Wraps a @pure @total function in a Map-based memoization cache at compile time. Results are cached after the first call; subsequent calls with the same arguments return instantly.

@exhaustive

Placed on a match expression to opt into strict exhaustiveness checking. The checker verifies that all variants of a tagged union are covered.

@test

Top-level inline test declarations. Tests are registered in __axon_tests at runtime and can be run via __runAxonTests() in the browser, or the CLI --test flag.

@throws

Mark a function as fallible. @throws fn f() -> Result<T> signals to the checker and to callers that this function may return Err. The static checker warns if a @throws result is silently ignored without a match or ? operator.

Standard Library

The Axon stdlib is a small set of higher-order functions prepended to every generated file. All functions are pure.

CLI

Numeric Literals

Axon v0.9.5 extends numeric literals with underscore separators, hexadecimal 0x…, and binary 0b… prefixes. Separators are stripped at compile time; the notation is preserved in generated JS output.

New CLI Commands

Three new commands ship with v0.9.0, covering static analysis, formatting, and live recompilation.

axon --check

Runs the static checker without emitting any output file. Useful in CI or as a pre-commit hook.

$ axon --check src/main.axn
✓  main.axn — no issues

$ axon --check src/main.axn
  WARNING [line 14]: @pure function 'render' accesses effectful global 'console'

axon --fmt

Canonical formatter. Normalises 2-space indentation, spacing around operators (=, ->, =>, ::, |>, binary arithmetic), brace padding, and trailing whitespace. Does not modify </> spacing to preserve generic type parameters.

$ axon --fmt src/main.axn           # formatted source → stdout
$ axon --fmt src/main.axn --write   # rewrite in-place
✓  main.axn — formatted
✓  main.axn — already canonical     # if no changes needed

axon --watch

Watches a source file with fs.watch and recompiles on every save. Timestamped output for each recompile. Ctrl+C to stop.

$ axon --watch src/main.axn dist/main.js
[14:02:11]  ✓  main.axn → main.js
Watching main.axn for changes… (Ctrl+C to stop)
[14:02:45]  ✓  main.axn → main.js
[14:03:12]  ✗  [line 8:3] Expected } but got EOF

Browser Compiler API

axon.compiler.js is a self-contained IIFE bundle that runs the full Axon compiler client-side. Load it in any web page — no server, no build step, no dependencies.

<script src="axon.compiler.js"></script>
<script>
  const { js, errors, warnings } = AxonCompiler.compile(source);
</script>

AxonCompiler.compile(source)

Transpiles an Axon source string to JavaScript. Always returns an object — never throws.

Error object shape

AxonCompiler.check(source)

Runs only the static checker. Returns { warnings }. Useful for lightweight lint-on-type without full codegen.

AxonCompiler.version

String — the compiler version, e.g. "0.9.0".

Modules

Split a project across multiple .axn files. Use import to bring names into scope and export to mark declarations as public.

export type Tile = | Floor | Wall | Door | Stairs | Chest

export fn tile_glyph(tag: string) -> string =
  match tag {
    | "Floor"  => "·"
    | "Wall"   => "█"
    | "Door"   => "▯"
    | _        => "?"
  }

@test "wall glyph" { tile_glyph("Wall") == "█" }

import { tile_glyph } from "./tiles"
import { generate }   from "./generator"
import { render_map } from "./renderer"

fn main() {
  let map  = generate(20, 40, 1, 7777)
  let html = render_map(map)
  document.getElementById("output").innerHTML = html
}

main()

The bundler resolves imports depth-first, topo-sorts modules so dependencies come before dependents, and emits a single JS file with the stdlib included once at the top. All bundled code shares a single flat scope — no runtime module system overhead.

refine

refine x: "prose claim" is an AI-native semantic narrowing statement. It annotates a binding with a human-readable constraint that is too nuanced for a type signature — emitted as structured JSDoc and queryable by AI tooling. It compiles to a no-op comment at runtime; the value is unchanged.

Generic Type Parameters

Add type parameters to record, fn, and type declarations using angle-bracket syntax. Type parameters are erased at compile time — no runtime overhead.

Generic records

Generic functions

Generic type aliases

Interfaces

Declare structural type contracts with interface. Any record that carries the required fields and methods satisfies the interface — no explicit implements keyword needed. Interfaces are emitted as JSDoc @interface comments.

fn(T) -> U Function Types

Function types are first-class in Axon. Use fn(A, B) -> C syntax anywhere a type is expected — in record fields, interface definitions, and generic function signatures.

let infer

let infer x = expr is an AI-native annotation that signals the type of a binding should be resolved from context by the model — not written explicitly by the programmer. It compiles to an ordinary let with no runtime difference.

store

store Name { field: Type = default } declares a reactive mutable state container — an explicit effects boundary that separates pure logic from observable state. Getters expose each field; .set(patch) updates state and notifies all subscribers atomically.

async fn & await

Prefix any function declaration with async to make it asynchronous. Inside an async fn, use await expr to resolve a Promise without blocking. The stdlib provides delay(ms) for timer-based pauses.

on StoreName.change { … }

on StoreName.change { body } is syntactic sugar for registering a reactive subscription. The body runs once immediately when the subscription is registered, then again after every StoreName.set(…) call. Multiple subscriptions can target the same store.

Version History

Roadmap to v1.0

Each milestone ships a demo that couldn't be written before it. Internal plumbing without a visible payoff doesn't ship.