@fnet/shell

The @fnet/shell project is a useful tool designed to help users execute shell commands within a Node.js environment. It provides a convenient way to run commands both synchronously and asynchronously, with the flexibility to configure command execution options. This tool is particularly handy for users who need to perform shell operations as part of their Node.js applications effortlessly.

How It Works

@fnet/shell functions by allowing you to execute shell commands through JavaScript code. You can pass in either a simple command string or an object specifying the command and various options. The shell command is executed, and the results, such as the exit code, standard output, and standard error, are returned as a promise, providing a straightforward way to handle asynchronous command execution.

Key Features

• Command Execution: Easily execute shell commands through JavaScript within a Node.js environment.
• Asynchronous Support: Enable asynchronous execution to run commands without blocking the Node.js main thread.
• Configurable Options: Customize the execution environment and output handling, including working directory and silent mode.
• Promise-based Results: Receive command results asynchronously, including the exit code, standard output, and standard error.

Conclusion

The @fnet/shell project provides a simple and efficient solution for integrating shell command execution into your Node.js applications. It offers flexibility in command execution and result handling, making it a practical tool for developers needing such functionality.

Developer Guide for @fnet/shell

Overview

The @fnet/shell library simplifies the execution of shell commands from within a Node.js application. The primary functionality of this library is to execute shell commands asynchronously or synchronously, handling standard output and errors with ease. This allows developers to seamlessly integrate shell command execution into their applications without dealing with low-level process management.

Installation

To install the @fnet/shell package, you can use either npm or yarn. Here are the commands:

Using npm:

npm install @fnet/shell

Using yarn:

yarn add @fnet/shell

Usage

The library provides a single exported function which allows you to execute shell commands with specified options.

Basic Usage

To execute a shell command, you can directly pass it as a string. This will execute the command and return a promise that resolves with the result of the command execution.

import shell from '@fnet/shell';

shell('ls -l')
  .then(result => {
    console.log('Command executed successfully:');
    console.log(result.stdout);
  })
  .catch(error => {
    console.error('Command execution failed:', error);
  });

Advanced Usage

If you need more control over the execution, such as specifying options or handling command execution asynchronously, you can pass an object with a cmd property and options.

import shell from '@fnet/shell';

// Execute a command with specific options
shell({
  cmd: 'echo "Hello, World!"',
  options: { silent: true }
})
  .then(result => {
    console.log('Command Output:', result.stdout);
  })
  .catch(error => {
    console.error('Error:', error.stderr);
  });

// Running a command asynchronously
shell({
  cmd: 'long-running-command',
  options: { async: true }
})
  .then(result => {
    console.log(result.stdout); // "Command is running in the background."
  });

Examples

Here are some examples to demonstrate typical use cases of the library:

Example 1: Synchronous Command Execution

Execute a simple shell command to list files in a directory:

shell('ls').then(result => {
  console.log(result.stdout);
});

Example 2: Asynchronous Command Execution

Run a shell command in the background:

shell({ cmd: 'sleep 10', options: { async: true } })
  .then(result => {
    console.log(result.stdout); // Outputs: "Command is running in the background."
  });

Example 3: Error Handling

Handle errors if the shell command fails:

shell('invalid-command')
  .catch(error => {
    console.error(`Error executing command: ${error.stderr}`);
  });

Acknowledgement

@fnet/shell leverages the shelljs library to execute shell commands, which provides a set of portable Unix shell commands within Node.js environments.

This guide delivers a practical understanding of the @fnet/shell library, allowing developers to effectively execute shell commands within their Node.js applications.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
type:
  - object
  - string
properties:
  cmd:
    type: string
    description: The shell command to be executed.
  options:
    type: object
    properties:
      silent:
        type: boolean
        default: false
        description: If true, suppresses the output of the command.
      cwd:
        type: string
        description: Sets the current working directory before executing the command.
      async:
        type: boolean
        description: If true, executes the command asynchronously.
  wait:
    type: boolean
    default: true
    description: If false and options.async is true, the function will not wait for
      the command to complete.