A powerful wrapper for the Piston code execution engine, featuring an integrated judger to evaluate outputs and run test cases.
npm install piston-judgerA powerful wrapper for the Piston code execution engine, featuring an integrated judger to evaluate outputs and run test cases.
This project uses the Judge Server from Piston by engineer-man.
Piston is a high-performance general purpose code execution engine.
The API design for the piston client object is inspired by node-piston by dthree.
``bash`
npm install piston-judger
#### Basic Usage (Piston Client)
Execute code using the raw Piston client.
`typescript
import { piston } from "piston-judger";
(async () => {
// Initialize the client (optional: provide a custom Piston server URL)
// Default server: https://emkc.org
const client = piston({ server: "https://emkc.org" });
// 1. Get available runtimes
const runtimes = await client.runtimes();
console.log(runtimes);
// 2. Execute code
const result = await client.execute("python", "3.10.0", {
language: "python",
version: "3.10.0",
files: [
{
content: 'print("Hello, World!")',
},
],
});
console.log(result);
// Output: { language: 'python', version: '3.10.0', run: { stdout: 'Hello, World!\n', ... } }
})();
`
#### Advanced Usage (Piston Judger)
Execute code and judge the output against expected results.
`typescript
import { pistonJudger, CompareMode } from "piston-judger";
(async () => {
const judger = pistonJudger({ server: "https://emkc.org" });
// Execute code
const executionResult = await judger.execute("c", "10.2.0", {
language: "c",
version: "10.2.0",
files: [
{
content:
#include
int main() {
printf("1\\n");
return 0;
}
,
},
],
});
// Compare the result
const judgeResult = judger.judge(executionResult, {
expectedOutput: "1",
compareMode: CompareMode.LOOSE, // LOOSE ignores trailing whitespace/newlines
});
console.log(judgeResult);
/*
{
status: 'AC',
message: 'Accepted',
actualOutput: '1\n',
expectedOutput: '1',
details: { ... }
}
*/
})();
`
#### Judger Status Codes
The judger returns a status field indicating the result of the execution and comparison:
- AC (Accepted): The output matches the expected output.
- WA (Wrong Answer): The output does not match the expected output.
- CE (Compilation Error): The code failed to compile.
- RE (Runtime Error): The code executed but crashed or returned a non-zero exit code.
- TLE (Time Limit Exceeded): The execution time exceeded the specified limit.
- MLE (Memory Limit Exceeded): The memory usage exceeded the specified limit.
- OLE (Output Limit Exceeded): The output size exceeded the limit.
- EXE (Execution Error): General execution error (e.g., Piston API failure).
#### Return Object Structure
When using judger.judge(), the returned object contains the following fields:
`typescript`
interface JudgeResult {
status: JudgeStatus; // 'AC' | 'WA' | 'CE' | 'RE' | 'TLE' | 'MLE' | 'OLE' | 'EXE'
message: string; // Human-readable status message (e.g., "Accepted")
actualOutput: string; // The actual stdout produced by the code
expectedOutput: string; // The expected output used for comparison
details: {
memory: number; // Memory usage (bytes)
runTime: number; // Execution time (ms)
signal: string | null; // Signal that terminated the process (if any)
stderr: string; // Standard error output (for debugging CE/RE)
};
}
---
這是一個針對 Piston 程式碼執行引擎的強力封裝，內建判題器 (Judger)，可用於評估程式輸出與測試案例比對。
本專案使用由 engineer-man 開發的 Piston 作為 Judge Server (判題伺服器)。
Piston 是一個高效能的通用程式碼執行引擎。
The API design for the piston client object is inspired by node-piston by dthree.
`bash`
npm install piston-judger
#### 基本使用 (Piston Client)
使用原生的 Piston 客戶端來執行程式碼。
`typescript
import { piston } from "piston-judger";
(async () => {
// 初始化客戶端 (可選：提供自定義 Piston 伺服器網址)
// 預設伺服器: https://emkc.org
const client = piston({ server: "https://emkc.org" });
// 1. 取得支援的語言環境
const runtimes = await client.runtimes();
console.log(runtimes);
// 2. 執行程式碼
const result = await client.execute("python", "3.10.0", {
language: "python",
version: "3.10.0",
files: [
{
content: 'print("Hello, World!")',
},
],
});
console.log(result);
// 輸出: { language: 'python', version: '3.10.0', run: { stdout: 'Hello, World!\n', ... } }
})();
`
#### 進階使用 (Piston Judger)
執行程式碼並將輸出與預期結果進行比對 (判題)。
`typescript
import { pistonJudger, CompareMode } from "piston-judger";
(async () => {
const judger = pistonJudger({ server: "https://emkc.org" });
// 執行程式碼
const executionResult = await judger.execute("c", "10.2.0", {
language: "c",
version: "10.2.0",
files: [
{
content:
#include
int main() {
printf("1\\n");
return 0;
}
,
},
],
});
// 進行判題
const judgeResult = judger.judge(executionResult, {
expectedOutput: "1",
compareMode: CompareMode.LOOSE, // LOOSE 模式會忽略行末空白與換行
});
console.log(judgeResult);
/*
{
status: 'AC',
message: 'Accepted',
actualOutput: '1\n',
expectedOutput: '1',
details: { ... }
}
*/
})();
`
判題器回傳的 status 欄位代表執行與比對的結果：
- AC (Accepted): 程式輸出與預期輸出相符。
- WA (Wrong Answer): 程式輸出與預期輸出不符。
- CE (Compilation Error): 程式編譯失敗。
- RE (Runtime Error): 程式執行期間發生錯誤或崩潰 (非零退出碼)。
- TLE (Time Limit Exceeded): 執行時間超過限制。
- MLE (Memory Limit Exceeded): 記憶體使用量超過限制。
- OLE (Output Limit Exceeded): 輸出大小超過限制。
- EXE (Execution Error): 一般執行錯誤 (例如 Piston API 連線失敗)。
使用 judger.judge() 時，回傳的物件包含以下欄位：
`typescript``
interface JudgeResult {
status: JudgeStatus; // 'AC' | 'WA' | 'CE' | 'RE' | 'TLE' | 'MLE' | 'OLE' | 'EXE'
message: string; // 易讀的狀態訊息 (例如 "Accepted")
actualOutput: string; // 程式實際產生的 stdout
expectedOutput: string; // 用於比對的預期輸出
details: {
memory: number; // 記憶體使用量 (bytes)
runTime: number; // 執行時間 (ms)
signal: string | null; // 終止程序的訊號 (若有)
stderr: string; // 標準錯誤輸出 (用於除錯 CE/RE)
};
}