Documentation - tsrun
Description: tsrun documentation - features, API reference, and architecture.

# 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

- API Reference - Rust and C APIs
- Architecture - VM design and internals
- Examples - Code examples