Getting Started

tsrun is a minimal TypeScript runtime in Rust, perfect for configuration files where you want IDE autocompletion, type checking, and error highlighting. It executes TypeScript directly without transpilation, with no Node.js dependency.

Installation

CLI Tool

Install the command-line tool with Cargo:

bash 
cargo install tsrun

Rust Library

Add tsrun to your Cargo.toml:

toml 
[dependencies]
tsrun = "0.1"

C/C++ Library

Build the shared library with C API support:

bash 
cargo build --release --features c-api
# Produces: target/release/libtsrun.so (Linux)
#           target/release/libtsrun.dylib (macOS)
#           target/release/tsrun.dll (Windows)

CLI Usage

Run TypeScript files directly:

bash 
# Run a TypeScript file
tsrun script.ts

# With ES modules - imports are resolved automatically
tsrun main.ts

Example script.ts:

typescript 
interface User {
    name: string;
    email: string;
}

function greet(user: User): string {
    return `Hello, ${user.name}!`;
}

const user: User = { name: "Alice", email: "alice@example.com" };
console.log(greet(user));

Rust Library

Basic usage with the step-based execution model:

rust 
use tsrun::{Interpreter, StepResult};

fn main() -> Result<(), tsrun::JsError> {
    let mut interp = Interpreter::new();

    // Prepare code for execution
    interp.prepare("1 + 2 * 3", None)?;

    // Step until completion
    loop {
        match interp.step()? {
            StepResult::Continue => continue,
            StepResult::Complete(value) => {
                println!("Result: {}", value.as_number().unwrap());
                break;
            }
            _ => break,
        }
    }
    Ok(())
}

Working with Objects

rust 
use tsrun::{Interpreter, api};
use serde_json::json;

let mut interp = Interpreter::new();
let guard = api::create_guard(&interp);

// Create values from JSON
let user = api::create_from_json(&mut interp, &guard, &json!({
    "name": "Alice",
    "age": 30,
    "tags": ["admin", "developer"]
}))?;

// Read properties
let name = api::get_property(&user, "name")?;
assert_eq!(name.as_str(), Some("Alice"));

// Modify properties
api::set_property(&user, "email", JsValue::from("alice@example.com"))?;

C/C++ Embedding

Include the header and link against the library:

c 
#include "tsrun.h"

int main() {
    TsRunContext* ctx = tsrun_new();

    // Prepare and run code
    tsrun_prepare(ctx, "1 + 2 * 3", NULL);
    TsRunStepResult result = tsrun_run(ctx);

    if (result.status == TSRUN_STEP_COMPLETE) {
        printf("Result: %g\n", tsrun_get_number(result.value));
        tsrun_value_free(result.value);
    }

    tsrun_step_result_free(&result);
    tsrun_free(ctx);
    return 0;
}

Compile with:

bash 
gcc -o myapp myapp.c -L./target/release -ltsrun

Next Steps