Getting Started - tsrun
Description: Get started with tsrun - installation, setup, and first steps.

# 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

- Try the Playground - Run TypeScript in your browser
- Documentation - Full API reference and guides
- API Reference - Rust and C APIs
- Examples - Real-world usage examples