Node Runtime Controller (node-rc)

npm install node-rc
# or
yarn add node-rc
# or
pnpm add node-rc

Quick Start

import { RuntimeController } from 'node-rc';

// Create a runtime controller
const rc = new RuntimeController();

// Execute Python code
const python = rc.PythonInterpreter();
const pyResult = await python.execute(`
    import numpy as np
    data = np.array([1, 2, 3, 4, 5])
    print(f"Mean: {np.mean(data)}")
`);
console.log(pyResult.output); // "Mean: 3.0"

// Execute JavaScript with Porffor AOT compilation
const js = rc.JavaScriptInterpreter({ enableTracing: true });
const jsResult = await js.execute(`
    const numbers = [1, 2, 3, 4, 5];
    const doubled = numbers.map(n => n * 2);
    console.log(doubled);
`);
console.log(jsResult.trace.metrics.executionTime); // ~50μs with predictable performance

// Execute TypeScript
const ts = rc.TypeScriptInterpreter();
const tsResult = await ts.execute(`
    interface User {
        name: string;
        age: number;
    }
    
    const user: User = { name: "Alice", age: 30 };
    console.log(JSON.stringify(user));
`);
console.log(tsResult.output); // {"name":"Alice","age":30}

// Execute C code
const c = rc.CInterpreter();
const cResult = await c.execute(`
    #include <stdio.h>
    int main() {
        printf("Hello from C\\n");
        return 0;
    }
`);
console.log(cResult.output); // "Hello from C"

// Execute Java code
const java = rc.JavaInterpreter();
const javaResult = await java.execute(`
    public class Main {
        public static void main(String[] args) {
            System.out.println("Hello from Java");
        }
    }
`);
console.log(javaResult.output); // "Hello from Java"

// Execute Ruby code
const ruby = rc.RubyInterpreter();
const rubyResult = await ruby.execute(`
    puts "Hello from Ruby"
    [1, 2, 3].each { |n| puts n * 2 }
`);
console.log(rubyResult.output); // "Hello from Ruby\n2\n4\n6"

// Execute Go code
const go = rc.GoInterpreter();
const goResult = await go.execute(`
    fmt.Println("Hello from Go")
`);
console.log(goResult.output); // "Hello from Go"

API

RuntimeController

The main controller for managing runtime instances.

const rc = new RuntimeController(config?: RuntimeConfig);

Configuration Options

interface RuntimeConfig {
  maxConcurrency?: number;      // Max parallel executions (default: 100)
  defaultTimeout?: number;       // Default timeout in ms (default: 30000)
  defaultMemoryLimit?: number;   // Memory limit in bytes (default: 256MB)
  enableTracing?: boolean;       // Enable execution tracing (default: true)
}

Language Interpreters

Each interpreter provides a consistent interface:

const interpreter = rc.PythonInterpreter(options?: InterpreterOptions);

// Execute code
const result = await interpreter.execute(code: string);

// Execute with input
const result = await interpreter.executeWithIO(code: string, stdin: string);

// Get interpreter info
const info = interpreter.getInfo();

// Clean up
await interpreter.destroy();

Interpreter Options

interface InterpreterOptions {
  timeout?: number;              // Execution timeout in ms
  memoryLimit?: number;          // Memory limit in bytes
  enableTracing?: boolean;       // Enable detailed tracing
  env?: Record<string, string>;  // Environment variables
  workingDirectory?: string;     // Working directory
  sandboxLevel?: 'strict' | 'moderate' | 'relaxed';
}

Execution Results

interface ExecutionResult {
  success: boolean;              // Execution successful?
  output: string;                // Standard output
  errorOutput?: string;          // Standard error
  value?: any;                   // Return value
  error?: ExecutionError;        // Error details if failed
  trace?: ExecutionTrace;        // Detailed trace (if enabled)
}

interface ExecutionTrace {
  id: string;                    // Unique execution ID
  language: Language;            // Language used
  sourceCode: string;            // Original code
  metrics: ExecutionMetrics;     // Performance metrics
  variables?: Record<string, any>; // Variable state
  callStack?: CallFrame[];      // Call stack trace
  memorySnapshots?: MemorySnapshot[]; // Memory usage over time
}

Advanced Usage

Concurrent Execution

const rc = new RuntimeController({ maxConcurrency: 200 });

// Run multiple languages in parallel
const results = await Promise.all([
  rc.PythonInterpreter().execute('print("Python")'),
  rc.JavaScriptInterpreter().execute('console.log("JS")'),
  rc.TypeScriptInterpreter().execute('console.log("TS")'),
  rc.CInterpreter().execute('#include <stdio.h>\nint main() { printf("C\\n"); return 0; }'),
  rc.JavaInterpreter().execute('System.out.println("Java");'),
  rc.RubyInterpreter().execute('puts "Ruby"'),
  rc.GoInterpreter().execute('fmt.Println("Go")')
]);

// All 7 languages execute concurrently!

Custom Sandboxing

// Strict sandboxing for untrusted code
const untrusted = rc.PythonInterpreter({
  sandboxLevel: 'strict',
  timeout: 5000,
  memoryLimit: 64 * 1024 * 1024, // 64MB
  env: {} // No environment variables
});

// Relaxed for trusted operations
const trusted = rc.PythonInterpreter({
  sandboxLevel: 'relaxed',
  timeout: 60000,
  memoryLimit: 1024 * 1024 * 1024, // 1GB
});

AI Agent Integration

// Execute code with full tracing for AI analysis
const js = rc.JavaScriptInterpreter({ enableTracing: true });

const result = await js.execute(`
  function processData(items) {
    return items.map(x => x * 2).filter(x => x > 10);
  }
  
  const data = [1, 5, 8, 12, 3];
  const result = processData(data);
  console.log(result);
`);

// Access detailed execution trace
console.log('Execution ID:', result.trace.id);
console.log('Total time:', result.trace.metrics.totalTime, 'μs');
console.log('Memory used:', result.trace.metrics.peakMemoryUsage, 'bytes');
console.log('Variables:', result.trace.variables);

// Use trace for AI agent training
const trainingData = {
  code: result.trace.sourceCode,
  output: result.output,
  metrics: result.trace.metrics,
  success: result.success
};

Performance

Sandbox Levels

1. Strict: No file system, network, or system access
2. Moderate: Limited file system (tmp only), no network
3. Relaxed: Read-only file system, controlled network access

Capability Model

const interpreter = rc.PythonInterpreter({
  sandboxLevel: 'moderate',
  // Explicitly grant capabilities
  capabilities: ['filesystem_read', 'system_time']
});

Development

Building from Source

# Clone repository
git clone https://github.com/rizome-dev/node-rc.git
cd node-rc

# Install dependencies
npm install

# Build native bindings
npm run build:native

# Build TypeScript
npm run build:ts

# Run tests
npm test

In Progress

• Add distributed execution support
• Integrate TeaVM for better Java → WASM compilation
• Add Rust support
• Add Zig support

---

Made with ❤️ by Rizome Labs