Class CommandExecutor

Command executor for running external programs with resource constraints. Manages process lifecycle, timeout enforcement, memory limits, and cleanup. Supports cross-platform execution (Unix/Windows) with platform-specific optimizations.

CommandExecutor

Example

import { executor } from './executor';

const result = await executor.execute('./solution', {
  timeout: 2000,
  memoryLimitMB: 256,
  silent: false
});

Constructors

constructor

new CommandExecutor(): CommandExecutor
Returns CommandExecutor

Properties

`Private`tempFiles

tempFiles: string[] = []

`Private`activeProcesses

activeProcesses: Set<ChildProcess> = ...

Methods

execute

execute(command: string, options: ExecutionOptions): Promise<ExecutionResult>
Execute a shell command with timeout and memory limits. Automatically kills the process if it exceeds time or memory constraints.
Parameters
- command: string
  Shell command to execute
- options: ExecutionOptions
  Execution configuration
Returns Promise<ExecutionResult>
Execution result with stdout, stderr, and status
Throws
If command fails and no onError callback is provided

Throws
If timeout occurs and no onTimeout callback is provided

Throws
If memory limit exceeded and no onMemoryExceeded callback is provided
Example
```
// Run a C++ solution
const result = await executor.execute('./solution', {
  timeout: 1000,
  memoryLimitMB: 256
});
```
Example
```
// With error handling
const result = await executor.execute('./buggy_solution', {
  timeout: 2000,
  onError: (result) => console.log('Solution failed:', result.stderr),
  onTimeout: (result) => console.log('TLE')
});
```
- Defined in executor.ts:118

`Private`applyMemoryLimit

applyMemoryLimit(command: string, memoryLimitMB?: number): string
Private
Applies memory limit to a command using platform-specific methods. For Java programs, uses -Xmx flag. For Unix, uses ulimit. Windows memory limits are not fully supported.
Parameters
- command: string
  Command to wrap with memory limit
- OptionalmemoryLimitMB: number
  Memory limit in megabytes
Returns string
Command wrapped with memory limit enforcement
Example
```
// Java command
applyMemoryLimit('java Solution', 256)
// Returns: 'java -Xmx256m Solution'
```
Example
```
// C++ command on Unix
applyMemoryLimit('./solution', 256)
// Returns: '(ulimit -v 262144; ./solution)'
```
- Defined in executor.ts:186

`Private`normalizeCommandForPlatform

normalizeCommandForPlatform(command: string): string
Private
Normalizes command syntax for the current platform.
- On Windows, converts './foo' to '.\foo' and forward slashes in the executable path to backslashes to avoid ERROR_PATH_NOT_FOUND (3).
- Leaves arguments and redirections intact.
Parameters
- command: string
  Command line string to normalize
Returns string
Normalized command string appropriate for the platform
- Defined in executor.ts:214

`Private`spawnProcess

spawnProcess(
command: string,
options: ExecutionOptions,
): { process: ChildProcessWithoutNullStreams; result: ExecutionResult }
Private
Spawns a child process for command execution. Creates a detached process in shell mode to allow process tree management. Registers process in active processes set for cleanup tracking.
Parameters
- command: string
  Shell command to spawn
- options: ExecutionOptions
  Execution options including cwd
Returns { process: ChildProcessWithoutNullStreams; result: ExecutionResult }
Spawned process and empty result object
Example
```
const { process, result } = this.spawnProcess('./solution', { timeout: 1000 });
```
- Defined in executor.ts:253

`Private`createEmptyResult

createEmptyResult(): ExecutionResult
Private
Creates an empty execution result object with default values. Used as initial state before process execution completes.

Returns ExecutionResult
Empty result with default values
Example
```
const result = this.createEmptyResult();
// Returns: { stdout: '', stderr: '', exitCode: 0, success: false, ... }
```
- Defined in executor.ts:280

`Private`createOutputCollectors

createOutputCollectors(
child: ChildProcess,
): { stdout: string; stderr: string; isResolved: boolean }
Private
Creates output collectors for stdout and stderr streams. Attaches data event handlers to accumulate process output. Tracks whether the result has been resolved to prevent race conditions.
Parameters
- child: ChildProcess
  Child process to collect output from
Returns { stdout: string; stderr: string; isResolved: boolean }
Output collectors object
Example
```
const collectors = this.createOutputCollectors(child);
// collectors.stdout and collectors.stderr accumulate as process runs
```
- Defined in executor.ts:304

`Private`cancellableDelay

cancellableDelay(ms: number): [Promise<void>, () => void]
Private
Creates a cancellable delay promise for timeout implementation. Returns both the timeout promise and a cancel function. Cancel function clears the timeout to prevent unnecessary process kills.
Parameters
- ms: number
  Delay duration in milliseconds
Returns [Promise<void>, () => void]
Tuple of [timeout promise, cancel function]
Example
```
const [timeoutPromise, cancelTimeout] = this.cancellableDelay(1000);
timeoutPromise.then(() => console.log('Timed out'));
// Later, if process finishes early:
cancelTimeout();
```
- Defined in executor.ts:332

`Private`handleTimeout

handleTimeout(
    child: ChildProcess,
    options: ExecutionOptions,
    result: ExecutionResult,
    collectors: { stdout: string; stderr: string; isResolved: boolean },
    resolve: (value: ExecutionResult) => void,
    reject: (reason?: unknown) => void,
): void
Private
Handles timeout scenario when process exceeds time limit. Kills the process tree, updates result with timeout status, and invokes callbacks. Uses SIGKILL after grace period to ensure process termination.
Parameters
- child: ChildProcess
  Process that timed out
- options: ExecutionOptions
  Execution options with timeout callback
- result: ExecutionResult
  Result object to update
- collectors: { stdout: string; stderr: string; isResolved: boolean }
  Output collectors
- resolve: (value: ExecutionResult) => void
  Promise resolve function
- reject: (reason?: unknown) => void
  Promise reject function
Returns void
Example
```
// Called internally when timeout occurs
this.handleTimeout(child, options, result, collectors, resolve, reject);
```
- Defined in executor.ts:363

`Private`attachEventHandlers

attachEventHandlers(
    child: ChildProcess,
    options: ExecutionOptions,
    result: ExecutionResult,
    collectors: { stdout: string; stderr: string; isResolved: boolean },
    cancelTimeout: () => void,
    resolve: (value: ExecutionResult) => void,
    reject: (reason?: unknown) => void,
): void
Private
Attaches event handlers for process lifecycle events (close, error). Handles process completion, cleanup, and error scenarios. Ensures timeout is cancelled when process ends naturally.
Parameters
- child: ChildProcess
  Child process to attach handlers to
- options: ExecutionOptions
  Execution options
- result: ExecutionResult
  Result object to populate
- collectors: { stdout: string; stderr: string; isResolved: boolean }
  Output collectors
- cancelTimeout: () => void
  Function to cancel timeout
- resolve: (value: ExecutionResult) => void
  Promise resolve function
- reject: (reason?: unknown) => void
  Promise reject function
Returns void
Example
```
// Called internally during execute()
this.attachEventHandlers(child, options, result, collectors, cancelTimeout, resolve, reject);
```
- Defined in executor.ts:445

`Private`handleProcessClose

handleProcessClose(
    code: number | null,
    signal: Signals | null,
    options: ExecutionOptions,
    result: ExecutionResult,
    collectors: { stdout: string; stderr: string },
    resolve: (value: ExecutionResult) => void,
    reject: (reason?: unknown) => void,
): void
Private
Handles process close event and determines outcome. Routes to appropriate handler based on exit code and signals. Checks for memory errors, success (code 0), or general errors.
Parameters
- code: number | null
  Process exit code
- signal: Signals | null
  Process termination signal
- options: ExecutionOptions
  Execution options
- result: ExecutionResult
  Result object to populate
- collectors: { stdout: string; stderr: string }
  Output collectors
- resolve: (value: ExecutionResult) => void
  Promise resolve function
- reject: (reason?: unknown) => void
  Promise reject function
Returns void
Example
```
// Called internally by close event handler
this.handleProcessClose(0, null, options, result, collectors, resolve, reject);
```
- Defined in executor.ts:517

`Private`isMemoryError

isMemoryError(
    code: number | null,
    signal: Signals | null,
    stderr: string,
): boolean
Private
Detects if process failed due to memory issues. Checks both exit codes (137, SIGABRT) and error messages in stderr. Recognizes common memory error patterns across languages.
Parameters
- code: number | null
  Process exit code
- signal: Signals | null
  Process termination signal
- stderr: string
  Standard error output
Returns boolean
True if memory error detected
Example
```
// Exit code 137 indicates OOM kill
this.isMemoryError(137, null, '') // returns true
```
Example
```
// C++ bad_alloc exception
this.isMemoryError(1, null, 'terminate called after throwing bad_alloc') // returns true
```
- Defined in executor.ts:563

`Private`handleMemoryError

handleMemoryError(
    code: number | null,
    signal: Signals | null,
    options: ExecutionOptions,
    result: ExecutionResult,
    resolve: (value: ExecutionResult) => void,
    reject: (reason?: unknown) => void,
): void
Private
Handles memory limit exceeded scenario. Updates result with MLE status and invokes appropriate callback. Displays warning unless silent mode is enabled.
Parameters
- code: number | null
  Process exit code
- signal: Signals | null
  Process termination signal
- options: ExecutionOptions
  Execution options with MLE callback
- result: ExecutionResult
  Result object to update
- resolve: (value: ExecutionResult) => void
  Promise resolve function
- reject: (reason?: unknown) => void
  Promise reject function
Returns void
Example
```
// Called when OOM detected
this.handleMemoryError(137, null, options, result, resolve, reject);
```
- Defined in executor.ts:599

`Private`handleSuccess

handleSuccess(
    options: ExecutionOptions,
    result: ExecutionResult,
    resolve: (value: ExecutionResult) => void,
): void
Private
Handles successful process execution (exit code 0). Updates result status, displays output unless silent, and invokes success callback.
Parameters
- options: ExecutionOptions
  Execution options with success callback
- result: ExecutionResult
  Result object to update
- resolve: (value: ExecutionResult) => void
  Promise resolve function
Returns void
Example
```
// Called when process exits with code 0
this.handleSuccess(options, result, resolve);
```
- Defined in executor.ts:637

`Private`handleError

handleError(
    options: ExecutionOptions,
    result: ExecutionResult,
    resolve: (value: ExecutionResult) => void,
    reject: (reason?: unknown) => void,
): void
Private
Handles failed process execution (non-zero exit code). Updates result status, displays error unless silent, and invokes error callback or rejects.
Parameters
- options: ExecutionOptions
  Execution options with error callback
- result: ExecutionResult
  Result object to update
- resolve: (value: ExecutionResult) => void
  Promise resolve function
- reject: (reason?: unknown) => void
  Promise reject function
Returns void
Example
```
// Called when process exits with non-zero code
this.handleError(options, result, resolve, reject);
```
- Defined in executor.ts:666

`Private`handleProcessError

handleProcessError(
    err: Error,
    options: ExecutionOptions,
    result: ExecutionResult,
    resolve: (value: ExecutionResult) => void,
    reject: (reason?: unknown) => void,
): void
Private
Handles process spawn errors (e.g., command not found, permission denied). Updates result with error information and invokes error callback or rejects.
Parameters
- err: Error
  Error from process spawn
- options: ExecutionOptions
  Execution options with error callback
- result: ExecutionResult
  Result object to update
- resolve: (value: ExecutionResult) => void
  Promise resolve function
- reject: (reason?: unknown) => void
  Promise reject function
Returns void
Example
```
// Called when spawn() throws error
this.handleProcessError(new Error('ENOENT'), options, result, resolve, reject);
```
- Defined in executor.ts:705

`Private`killProcessTree

killProcessTree(pid: number): void
Private
Kills a process and its entire child process tree. Uses platform-specific methods: taskkill on Windows, process groups on Unix. Attempts to kill process group first, falls back to single process.
Parameters
- pid: number
  Process ID to kill
Returns void
Example
```
// Kill process tree on Unix
this.killProcessTree(12345);
// Sends SIGKILL to -12345 (process group)
```
Example
```
// Kill process tree on Windows
this.killProcessTree(12345);
// Runs: taskkill /pid 12345 /T /F
```
- Defined in executor.ts:746

executeWithRedirect

executeWithRedirect(
    command: string,
    options: ExecutionOptions,
    inputFile?: string,
    outputFile?: string,
): Promise<ExecutionResult>
Execute a command with input/output file redirection. Wraps the execute method with automatic stdin/stdout redirection.
Parameters
- command: string
  Shell command to execute
- options: ExecutionOptions
  Execution configuration
- OptionalinputFile: string
  Path to file for stdin redirection (optional)
- OptionaloutputFile: string
  Path to file for stdout redirection (optional)
Returns Promise<ExecutionResult>
Execution result
Example
```
// Run solution with test input and capture output
await executor.executeWithRedirect(
  './solution',
  { timeout: 1000 },
  'tests/test1.txt',
  'output.txt'
);
```
- Defined in executor.ts:786

`Private`buildRedirectedCommand

buildRedirectedCommand(
    command: string,
    inputFile?: string,
    outputFile?: string,
): string
Private
Builds a shell command with input/output redirection. Appends stdin (<) and stdout (>) redirections as needed.
Parameters
- command: string
  Base command to execute
- OptionalinputFile: string
  Optional input file path for stdin
- OptionaloutputFile: string
  Optional output file path for stdout
Returns string
Command with redirection operators
Example
```
buildRedirectedCommand('./solution', 'input.txt', 'output.txt')
// Returns: './solution < input.txt > output.txt'
```
Example
```
buildRedirectedCommand('./solution', 'input.txt')
// Returns: './solution < input.txt'
```
- Defined in executor.ts:818

registerTempFile

registerTempFile(filePath: string): void
Register a temporary file for tracking. Useful for cleanup operations after execution completes.
Parameters
- filePath: string
  Path to the temporary file
Returns void
Example
```
executor.registerTempFile('/tmp/test_output.txt');
```
- Defined in executor.ts:854

cleanup

cleanup(): Promise<void>
Clean up all active processes and clear temp file registry. Kills any running processes and resets internal state. Should be called when shutting down or after batch operations. On Windows, waits for file handles to be released.

Returns Promise<void>
Resolves when cleanup is complete
Example
```
try {
  await runAllTests();
} finally {
  await executor.cleanup();
}
```
- Defined in executor.ts:873

`Private`killAllActiveProcesses

killAllActiveProcesses(): void
Private
Kills all currently active processes tracked by the executor. Iterates through active processes set and kills each process tree. Used during cleanup or shutdown operations.

Returns void
Example
```
// Called by cleanup() method
this.killAllActiveProcesses();
```
- Defined in executor.ts:896

getTempFiles

getTempFiles(): string[]
Get a copy of the registered temporary files list.

Returns string[]
Array of temporary file paths
Example
```
const tempFiles = executor.getTempFiles();
tempFiles.forEach(file => fs.unlinkSync(file));
```
- Defined in executor.ts:918

Class CommandExecutor

Example

Index

Constructors

Properties

Methods

Constructors

constructor

Returns CommandExecutor

Properties

PrivatetempFiles

PrivateactiveProcesses

Methods

execute

Parameters

Returns Promise<ExecutionResult>

Throws

Throws

Throws

Example

Example

PrivateapplyMemoryLimit

Parameters

Returns string

Example

Example

PrivatenormalizeCommandForPlatform

Parameters

Returns string

PrivatespawnProcess

Parameters

Returns { process: ChildProcessWithoutNullStreams; result: ExecutionResult }

Example

PrivatecreateEmptyResult

Returns ExecutionResult

Example

PrivatecreateOutputCollectors

Parameters

Returns { stdout: string; stderr: string; isResolved: boolean }

Example

PrivatecancellableDelay

Parameters

Returns [Promise<void>, () => void]

Example

PrivatehandleTimeout

Parameters

Returns void

Example

PrivateattachEventHandlers

Parameters

Returns void

Example

PrivatehandleProcessClose

Parameters

Returns void

Example

PrivateisMemoryError

Parameters

Returns boolean

Example

Example

PrivatehandleMemoryError

Parameters

Returns void

Example

PrivatehandleSuccess

Parameters

Returns void

Example

PrivatehandleError

Parameters

Returns void

Example

PrivatehandleProcessError

Parameters

Returns void

Example

PrivatekillProcessTree

Parameters

Returns void

`Private`tempFiles

`Private`activeProcesses

`Private`applyMemoryLimit

`Private`normalizeCommandForPlatform

`Private`spawnProcess

`Private`createEmptyResult

`Private`createOutputCollectors

`Private`cancellableDelay

`Private`handleTimeout

`Private`attachEventHandlers

`Private`handleProcessClose

`Private`isMemoryError

`Private`handleMemoryError

`Private`handleSuccess

`Private`handleError

`Private`handleProcessError

`Private`killProcessTree

`Private`buildRedirectedCommand

`Private`killAllActiveProcesses