piston-js

A JavaScript client for Piston-Batch, A fork from Piston, a high performance general purpose code execution engine that supports batch submissions and code evaluation.

Contains Full TypeScript Typings

 

Installation

$ npm install piston-js

Basic Usage

import Piston from 'piston-js';

(async () => {
  const piston = new Piston('https://pistonserver.com');
  try {
    const result: SubmissionResult = await piston.run({
      language: {
        name: 'python',
        version: '3.9.1',
      },
      fileName: 'main.py',
      sourceCode: 'print(int(input())*3)',
      input: ['2'],
      expectedOutput: ['4'],
    });
    console.log(result);
    /*{
     run: [ { stdout: '6', stderr: '', code: 0, signal: null, stdin: '2' } ],
     verdict: { status: 'WA', stdout: '6', stdin: '2', expected_output: '4' }
    } */
  } catch (err) {
    console.log(err.response.data);
  }
})();

API

Piston(config: PistonConfig) : Piston

Returns an instance of Piston

PistonConfig

An object type representing the config for the Piston instance

properties

Property	Type	Description	Default
baseURL	string	the base url of the piston server	-
apiKey	string?	the api key used to access the piston server	""
apiKeyHeader	string?	name of the api key header	""

Piston.run(submission: Submission) : Promise< SubmissionResult>

Runs a submission and returns the result

Submission

An object representing a submission

properties

Property	Type	Description	Default
sourceCode	string	the source code to execute	-
language	Language	the programming language to execute	-
fileName	string	name of the file to execute, 'e.g: Main.java'. Some languages like Java need files to have the same name as the Main class.	-
input?	string[]	batch stdin to execute	[""]
expectedOutput?	string[]	if provided, the execution will be evaluated against all stdout resulted from input. if provided, must have equal length to input	null
runTimeout?	number	milliseconds before timing out the program (TLE)	3000
compileTimeout?	number	milliseconds before timing out the compilation of the source code (applies only to compiled languages) (TLE)	10000

Language

Type of Language required in Submission

properties

Property	Type	Description	Default
name	string	name of the language	-
version	string	version of the language	-

SubmissionResult

An object representing the result of a Submission

properties

Property	Type	Description
compile?	ProcessOutput	only available in compiled languages
run	ProcessOutput	result of each individual stdin in the batch
result	BatchResult	Final result of the submission batch after evaluation

ProcessOutput

Type of an execution process output

properties

Property	Type	Description
stdin	string	process stdin
stdout	string	process stdout
stderr	string	process stderr
code	number	process return code
signal	string	process signal

BatchResult

Type of an execution process output

properties

Property	Type	Description
status	Verdict	submission evaluation verdict
stdout	string	stdout of the first failed submission in the batch
stdin	string	stdin of the first failed submission in the batch
expectedOutput	string	expected output of the first failed submission in the batch
signal	string	process signal

• A submission is considered a failed submission in the batch if its Verdict is not accepted (AC)
• If a submission batch is accepted, stdout and stdin will have the results of the first submission in the batch

Verdict

An enum representing the verdict of a submission as strings

Property	Value	description
AC	'AC'	The source code executed successfully/passed all test cases
COMPILATION	'COMPILATION'	Compilation error
ERROR	'ERROR'	An error during the whole execution process
MLE	'MLE'	Memory limit exceeded (NOT YET IMPLEMENTED)
PENDING	'PENDING'	Submission is pending
RUNTIME	'RUNTIME'	Runtime error
TLE	'TLE'	Time limit exceeded (timedout)
WA	'WA'	Wrong answer (Failed test cases)