ClearScript Documentation

A type-safe scripting language with a Rust runtime, embeddable in Node.js and the browser. This page covers installation, the language tour, the standard library, and every embedding API.

Installation

Three ways to run ClearScript depending on what you're building:

1. The CLI (native Rust binary)

git clone https://github.com/clearscript/clearscript
cd clearscript
cargo build --release
./target/release/clear-cli run examples/hello.clear

2. Node.js embedding (npm)

npm install clearscript

Single platform-independent WASM bundle — no native compilation, no node-gyp. Works on macOS, Linux, Windows.

3. Browser (WASM)

import init, { run_clearscript } from './wasm/clear_wasm.js';
await init();
const result = JSON.parse(run_clearscript('fn main() { print("hi") }'));

Hello, World

Save the following as hello.clear:

fn main() {
  print("Hello, ClearScript!")
}

Run it:

clear-cli run hello.clear
# or via Node:
npx clear-node hello.clear

The main() function is invoked automatically if defined.

The CLI

Syntax overview

ClearScript is expression-oriented. Almost everything returns a value. Statements end at newlines (no semicolons required).

// Single-line comment
/* Block
   comment */

let name = "world"          // immutable
let mut count = 0          // mutable

fn greet(n: String) {
  print("Hello, ", n)
}

fn main() {
  greet(name)
}

Types & values

Variables

let x = 5              // immutable, type inferred
let mut y = 10         // mutable
let z: Int = 15        // explicit type annotation
y = y + 1             // ok, mut
// x = x + 1            // compile error: x is immutable

Functions & lambdas

fn add(a: Int, b: Int) -> Int {
  a + b                    // last expression is the return value
}

// Lambdas — first-class functions
let double = |x| x * 2
let result = map([1, 2, 3], double)   // [2, 4, 6]

// Inline:
filter(nums, |n| n > 10)

Control flow

// if/else (expressions, return values)
let tier = if score >= 90 { "A" } else if score >= 75 { "B" } else { "C" }

// while
while count < 10 { count = count + 1 }

// for-in (works on lists, ranges, strings, maps)
for i in 0..10 { print(i) }
for ch in "hello" { print(ch) }

// loop / break / continue
loop {
  if done { break }
}

Pattern matching

match value {
  0           => "zero",
  1           => "one",
  n if n > 0  => "positive",
  _           => "other",
}

// Bind values:
match result {
  0 => print("empty"),
  n => print("got", n),    // `n` binds to value
}

Collections

let nums = [1, 2, 3]
nums[0]                  // 1 — index access
len(nums)                // 3

let user = {name: "Ada", age: 36}
user["name"]             // "Ada"

String interpolation

Any expression can be spliced into a string with ${...}. The hole is parsed and evaluated at runtime; the result is converted to a string and concatenated.

let name = "Ada"
let age = 36
print("Hello, ${name}! You are ${age} years old.")
// Hello, Ada! You are 36 years old.

// Arbitrary expressions — not just identifiers:
let nums = [1, 2, 3]
print("Sum = ${sum(nums)}, doubled = ${sum(nums) * 2}")
// Sum = 6, doubled = 12

Operators

Standard Library — I/O

Standard Library — String

Standard Library — Array

Standard Library — Math

Standard Library — Functional

map([1,2,3], |x| x * 2)         // [2, 4, 6]
filter([1,2,3,4], |x| x % 2 == 0) // [2, 4]
reduce([1,2,3], |acc, x| acc + x, 0) // 6  — args: (list, fn, init)

Standard Library — Map

Standard Library — JSON

Round-trips through serde_json. Maps, arrays, strings, numbers, bools, and null are all supported.

Standard Library — Filesystem

Native only. In WASM (browser playground) these throw a clear "filesystem not available" error.

Standard Library — Env & Time

Standard Library — Type & assertion

Embedding in Node.js

Install:

npm install clearscript

Run source

const cs = require('clearscript');

// Returns { ok, output, error } — never throws on script errors
const result = cs.run(`
  fn main() {
    let nums = [1, 2, 3, 4, 5]
    print("sum:", sum(nums))
  }
`);
console.log(result.output);  // ['sum: 15']

// execute() throws on failure
try {
  const out = cs.execute('fn main() { print("hi") }');
} catch (e) {
  if (e instanceof cs.ClearScriptError) {
    console.error(e.message, e.output);
  }
}

require() .clear files

require('clearscript/register');    // install loader hook
require('./hello.clear');            // runs the file, output → stdout

Reusable context (REPL / notebook)

const ctx = cs.createContext();
ctx.eval('fn greet(name: String) { print("hi", name) }');
ctx.eval('fn main() { greet("world") }');  // → ['hi world']
ctx.reset();

ESM

import { run, execute, createContext } from 'clearscript';

CLI

npx clear-node hello.clear
npx clear-node --eval 'fn main() { print("hi") }'
npx clear-node --repl
npx clear-node --version

Node API reference

Embedding in the browser (WASM)

<script type="module">
  import init, { run_clearscript } from './wasm/clear_wasm.js';
  await init();
  const { ok, output, error } = JSON.parse(
    run_clearscript('fn main() { print("hi from wasm") }')
  );
  document.body.textContent = output.join('\n');
</script>

Diagnostic codes

Current limitations

ClearScript is pre-1.0. The compiler frontend, tree-walking interpreter, type checker, and module resolver are complete. Still in progress:

• Trait system — declarations parse; method dispatch via traits is in design.
• Async / await — syntax reserved, runtime not yet implemented.
• Generics — parsed; full inference + monomorphisation in design.
• Bytecode VM / JIT — currently a tree-walking interpreter. Bytecode planned for v0.3.
• String interpolation in patterns — ${expr} works in normal strings but match-arm patterns cannot contain interpolated strings yet.

✅ Shipped in v0.1.3: bidirectional type checker, module resolution with cycle detection, JSON / fs / env / time stdlib, "did you mean?" suggestions.
✅ Shipped in v0.1.5: full ${expr} string interpolation, O(n) unique(), zero clippy warnings.

FAQ

Why a new language?

JavaScript's footguns (coercion, hoisting, this, ==) are all fixable, but only if the compiler refuses the bad code. ClearScript bakes those refusals into the language as the 10 Laws.

How fast is the WASM interpreter?

The current tree-walking interpreter is suitable for scripts and config DSLs — roughly 5-20× slower than V8 for compute, comparable for I/O-bound work. A bytecode VM is on the roadmap.

Can I use it in production?

Not yet. v0.1 is for early experimentation. Open source launch on June 25, 2026.

Is there an N-API native addon?

Not yet — the npm package uses WASM for portability. N-API is on the roadmap for hot-path embedding scenarios.