Piston API Client

A comprehensive TypeScript client for the Piston API with WebSocket support for interactive code execution.

Features

• 🔥 Simple API: Execute code with one line
• 🌐 Interactive Sessions: Real-time WebSocket communication
• 📝 Input Support: Send input to running programs
• 🛡️ Type Safety: Full TypeScript support with Zod validation
• 📊 Event-Driven: Listen to session lifecycle events
• 🚀 High-Level: Automatic session management

Installation

npm install
npm run build

Quick Start

Simple Code Execution

import { PistonClient } from "./src/managers/client";

const piston = new PistonClient({ baseUrl: "http://localhost:2000" });

// Execute Python code
const result = await piston.run({
  language: "python",
  version: "*",
  code: 'print("Hello, World!")',
});
console.log(result.run.stdout); // "Hello, World!"

// Execute with input
const result2 = await piston.run({
  language: "python",
  version: "*",
  code: "print(input())",
  stdin: "User Input",
});
console.log(result2.run.stdout); // "User Input"

Interactive Sessions

// Create interactive session
const sessionId = await piston.runInteractive(
  `
while True:
    expr = input("> ")
    if expr == 'quit':
        break
    print(f"= {eval(expr)}")
`,
  "python"
);

// Listen for output
piston.on("sessionOutput", (id, output) => {
  console.log("Output:", output);
});

// Send input
piston.sendInput(sessionId, "2 + 3\\n");
piston.sendInput(sessionId, "quit\\n");

// Cleanup
piston.destroySession(sessionId);

C++ with Input

// C++ calculator
const result = await piston.run({
  language: "cpp",
  version: "*",
  code: `
#include <iostream>
using namespace std;

int main() {
    int a, b;
    cout << "Enter two numbers: ";
    cin >> a >> b;
    cout << "Sum: " << (a + b) << endl;
    return 0;
}`,
  stdin: "10\\n5\\n",
});

console.log(result.run.stdout); // "Enter two numbers: Sum: 15"

API Reference

PistonClient

Methods

• run(request) - Execute code once
• runInteractive(code, language) - Start interactive session
• sendInput(sessionId, input) - Send input to session
• destroySession(sessionId) - End session
• getRuntimes(input?, force?) - Get available languages
• installPackage(request) - Install specific package version
• installRuntime(language) - Install latest version of a runtime
• validateInstance() - Check if Piston is available

Events

• sessionCreated - Session started
• sessionReady - Session ready for input
• sessionOutput - Session produced output
• sessionCompleted - Session ended
• sessionError - Session error occurred
• sessionDestroyed - Session cleaned up

Supported Languages

The client supports all languages available in Piston:

• Python (python, py)
• JavaScript (javascript, js, node)
• C++ (c++)
• C (c)
• Java (java)
• Go (go)
• Rust (rust)
• And many more!

Check available runtimes:

const runtimes = await piston.getRuntimes();
runtimes.forEach((r) => console.log(`${r.language} ${r.version}`));

// Install latest version of a runtime
await piston.installRuntime("python");

// Install specific package version
await piston.installPackage({ language: "python", version: "3.11.0" });

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.