TSShell

TypeScript wrapper for executing shell commands with proper error handling, inspired by Python's pyshell.

Installation

npm install tsshell

Quick Start

import { shell, shellSync, ShellError } from 'tsshell';

async function example() {
  try {
    // Execute shell commands asynchronously
    const output = await shell('ls -la');
    console.log(output);

    // Execute shell commands synchronously
    const syncOutput = shellSync('pwd');
    console.log(syncOutput);

    // Use environment variables
    const result = await shell('echo "Hello $NAME"', {
      env: { NAME: 'World' }
    });

    // Git operations
    await shell('git add . && git commit -m "update"');

  } catch (error) {
    if (error instanceof ShellError) {
      console.log('Command failed:', error.returnCode);
      console.log('Error:', error.stderr);
    }
  }
}

Features

• 🚀 Promise-based: Async/await support
• ⚡ Sync support: Synchronous execution for simple scripts
• ⚡ Error propagation: Uses set -e for proper error handling
• 🔧 Environment variables: Easy env variable injection
• ⏰ Timeout support: Configurable command timeouts
• 📝 TypeScript: Full type safety and IntelliSense
• 🛠️ Rich errors: Detailed error information with stdout/stderr

API

shell(script, options?)

Executes a shell script asynchronously and returns the output.

Parameters:

• script (string): Shell script to execute
• options (object, optional):
  • env: Environment variables to merge
  • cwd: Working directory
  • timeout: Command timeout in milliseconds

Returns: Promise<string> - Command output (stdout)

Throws: ShellError - When command fails

shellSync(script, options?)

Executes a shell script synchronously and returns the output.

Parameters:

• script (string): Shell script to execute
• options (object, optional):
  • env: Environment variables to merge
  • cwd: Working directory
  • Note: timeout is not supported for sync execution

Returns: string - Command output (stdout)

Throws: ShellError - When command fails

ShellError

Error class with additional properties:

• returnCode: Process exit code
• stdout: Standard output
• stderr: Standard error

Documentation

• Usage Guide - Comprehensive examples and best practices
• Development Notes - Development workflow and testing

License

MIT