https://github.com/elsoul/child-process
https://github.com/elsoul/child-process
Last synced: 6 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/elsoul/child-process
- Owner: elsoul
- License: apache-2.0
- Created: 2024-10-31T21:50:23.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2024-12-12T10:58:21.000Z (10 months ago)
- Last Synced: 2025-03-25T04:54:48.209Z (7 months ago)
- Language: TypeScript
- Size: 16.6 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# `@elsoul/child-process`
`@elsoul/child-process` is a lightweight utility library for executing shell
commands within [Deno](https://deno.land/). It provides simple and intuitive
functions to run commands synchronously or asynchronously, capturing output and
handling errors gracefully.## Features
- **Simple API**: Minimal and easy-to-use functions `exec`, `spawnSync`, and
`sshCmd` for command execution.
- **Error Handling**: Robust error handling with detailed messages and status
codes.
- **Argument Parsing**: Advanced argument parsing that correctly handles quoted
strings and escaped characters.
- **TypeScript Support**: Fully typed with TypeScript, providing type safety and
IntelliSense support.
- **Cross-Platform**: Works seamlessly across different operating systems
supported by Deno.## Installation
You can import `@elsoul/child-process` directly from the JavaScript Standard
Registry (JSR) or from Deno Land:### Using JSR
```ts
import { exec, spawnSync, sshCmd } from 'jsr:@elsoul/child-process'
```### Using Deno Land
```ts
import {
exec,
spawnSync,
sshCmd,
} from 'https://deno.land/x/child_process/mod.ts'
```## Usage
`@elsoul/child-process` allows you to execute shell commands effortlessly within
your Deno applications. Below are examples of how to use the provided functions.### Executing a Command Asynchronously
The `exec` function runs a command and collects its output asynchronously.
```ts
import { exec } from '@elsoul/child-process'const result = await exec('echo "Hello, World!"')
if (result.success) {
console.log('Command Output:', result.message)
} else {
console.error('Command Failed:', result.message)
}
```**Output:**
```
Command Output: Hello, World!
```### Spawning a Process Synchronously
The `spawnSync` function spawns a child process synchronously, inheriting the
parent process's standard input/output streams.```ts
import { spawnSync } from '@elsoul/child-process'const result = await spawnSync('ls -la')
if (result.success) {
console.log('Process completed successfully.')
} else {
console.error('Process failed:', result.message)
}
```**Output:**
```
(total output of `ls -la` command)
Process completed successfully.
```### Executing SSH Commands Remotely
The `sshCmd` function allows you to execute commands on a remote server via SSH
using an RSA key for authentication. It also allows specifying the working
directory on the remote server.```ts
import { sshCmd } from '@elsoul/child-process'const result = await sshCmd(
'solv',
'x.x.x.x',
'~/.ssh/id_rsa',
'solana --version',
)if (result.success) {
console.log('Command Output:', result.message)
} else {
console.error('Command Failed:', result.message)
}
```**Output:**
```
Command Output: solana-cli 1.8.5 (src:1a2bc3d4)
```### Handling Errors
Both `exec` and `spawnSync` provide detailed error information when a command
fails.```ts
import { exec } from '@elsoul/child-process'const result = await exec('some-invalid-command')
if (!result.success) {
console.error('Error Message:', result.message)
}
```**Output:**
```
Error Message: Failed to execute command: some-invalid-command
Error output: some-invalid-command: command not found
```### Advanced Argument Parsing
The library handles complex command strings with quotes and escaped characters.
```ts
import { exec } from '@elsoul/child-process';const result = await exec('echo "This is a test with spaces and 'single quotes'"');
console.log('Command Output:', result.message);
```**Output:**
```
Command Output: This is a test with spaces and 'single quotes'
```## API Reference
### Interfaces
#### `ExecResult`
Represents the result of a command execution.
- `success: boolean` - Indicates if the command executed successfully.
- `message: string` - The output or error message from the command.### Functions
#### `exec(cmd: string): Promise`
Executes a command asynchronously and collects its output.
- **Parameters:**
- `cmd: string` - The command to execute.
- **Returns:** `Promise` - The result of the command execution.#### `spawnSync(cmd: string): Promise`
Spawns a child process synchronously, inheriting standard I/O streams.
- **Parameters:**
- `cmd: string` - The command to execute.
- **Returns:** `Promise` - The result of the process execution.#### `sshCmd(user: string, host: string, rsaKeyPath: string, execCmd: string, cwd = '~'): Promise`
Executes an SSH command on a remote server synchronously.
- **Parameters:**
- `user: string` - The SSH username to use for connection.
- `host: string` - The hostname or IP address of the remote server.
- `rsaKeyPath: string` - The path to the RSA private key for authentication.
- `execCmd: string` - The command to execute on the remote server.
- `cwd: string` - The working directory on the remote server. Defaults to the
home directory.
- **Returns:** `Promise` - The result of the SSH command execution.## Contributing
Contributions are welcome! Please feel free to submit a pull request or open an
issue on GitHub:- [GitHub Repository](https://github.com/elsoul/child-process)
This project is intended to be a safe, welcoming space for collaboration, and
contributors are expected to adhere to the
[Contributor Covenant](http://contributor-covenant.org) code of conduct.## License
The package is available as open source under the terms of the
[Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0).## Code of Conduct
Everyone interacting in the `@elsoul/child-process` project’s codebases, issue
trackers, chat rooms, and mailing lists is expected to follow the
[code of conduct](https://github.com/elsoul/child-process/blob/master/CODE_OF_CONDUCT.md).