Documentation

tsrun is a minimal TypeScript runtime in Rust, designed for configuration files where you want IDE autocompletion, type checking, and error highlighting. It executes TypeScript directly using a register-based bytecode VM with no Node.js dependency.

Features

Feature Description
ES Modules Full import/export support with step-based module loading
Async/Await Promises, async functions, Promise.all/race/allSettled
Classes Inheritance, static blocks, private fields, getters/setters
Generators function*, yield, yield*, for...of iteration
Destructuring Arrays, objects, function parameters, rest/spread
Built-ins Array, String, Object, Map, Set, Date, RegExp, JSON, Math, Proxy, Reflect, Symbol
Embeddable Rust and C APIs for integration into host applications
no_std Can run in environments without the standard library

TypeScript Support

tsrun parses TypeScript syntax but strips types at runtime (no type checking). Supported TypeScript features:

  • Type annotations on variables, parameters, and return types
  • Interfaces and type aliases
  • Generic types
  • Enums (compiled to object literals with reverse mappings)
  • Decorators (class, method, property, parameter)
  • Namespaces
  • Type assertions (x as T, <T>x)
  • Optional chaining and nullish coalescing
  • Parameter properties in constructors

Step-Based Execution

The interpreter uses a step-based execution model that allows the host to control execution flow:

rust 
loop {
    match interp.step()? {
        StepResult::Continue => continue,        // Keep running
        StepResult::Complete(value) => break,    // Finished
        StepResult::NeedImports(imports) => {    // Load modules
            for import in imports {
                interp.provide_module(path, source)?;
            }
        }
        StepResult::Suspended { pending, .. } => { // Async operations
            // Fulfill pending orders and resume
        }
    }
}

This model enables:

  • Module loading - Pause to load imports from any source
  • Async operations - Pause for host-provided I/O
  • Cancellation - Stop execution at any step
  • Progress reporting - Track execution progress

Feature Flags

Flag Description Default
std Full standard library support Yes
regex Regular expression support (requires std) Yes
console Console.log builtin Yes
c-api C FFI for embedding (requires std) No

Limitations

  • No type checking - Types are parsed and stripped, not validated at runtime
  • Strict mode only - All code runs in strict mode
  • Single-threaded - One interpreter instance per thread

Next