@fnet/shell-flow
v0.1.15
Published
The `@fnet/shell-flow` module is a utility designed to facilitate the execution of shell commands with a versatile error handling mechanism. This tool aims to provide users with flexibility in controlling the flow of command execution, including support f
Downloads
1,322
Readme
@fnet/shell-flow
The @fnet/shell-flow
module is a utility designed to facilitate the execution of shell commands with a versatile error handling mechanism. This tool aims to provide users with flexibility in controlling the flow of command execution, including support for sequential, parallel, and forked command execution patterns.
How It Works
This module allows users to execute shell commands from JavaScript or TypeScript code by defining an array of command strings or groups. Users can specify an error handling policy, choosing whether to stop execution on error, continue executing remaining commands, or simply log errors without halting progress.
When you provide a list or sequence of commands, the module will process them based on the defined structure — either running them one after the other, simultaneously, or as split processes, depending on the setup. It captures and handles output and errors effectively, and if needed, can create temporary script files to execute more complex workflows.
Key Features
- Sequential Execution: Run commands one after the other in a specified order.
- Parallel Execution: Execute multiple commands simultaneously without waiting for each one to finish before starting the next.
- Forked Execution: Run commands as background processes.
- Flexible Error Handling: Define policy to stop, continue, or log errors during execution.
- Environment and Directory Control: Specify environment variables and working directories for command execution.
- Temporary Script File Creation: Handle complex sequences via temporary shell scripts when necessary.
Conclusion
@fnet/shell-flow
offers practical functionality for managing and executing shell commands with a simple API, giving users flexibility and control over how commands are run and errors are handled. This utility can be an asset for developers looking to integrate command-line operations into their applications with ease and clarity.
Developer Guide for @fnet/shell-flow
Overview
The @fnet/shell-flow
library provides developers with a streamlined way to execute shell commands in sequence or in parallel, with versatile error handling. This library can automate complex workflows and manage shell-based operations with ease. It supports sequential, parallel, forked, and grouped command execution while allowing flexible responses to command failures.
Installation
To include @fnet/shell-flow
in your project, run one of the following commands:
Using npm:
npm install @fnet/shell-flow
Using yarn:
yarn add @fnet/shell-flow
Usage
Here's a basic guide on how to use the @fnet/shell-flow
library in your projects.
Sequential and Parallel Command Execution
You can execute a series of commands sequentially or in parallel. The execution flow can be customized based on success or failure criteria.
import shellFlow from '@fnet/shell-flow';
async function runCommands() {
try {
await shellFlow({
commands: [
'echo "Starting process..."',
{
steps: [
'echo "Step 1: Preparation"',
'echo "Step 2: Execution"'
],
onError: 'stop'
},
{
parallel: [
'echo "Task A"',
'echo "Task B"'
],
onError: 'continue'
},
],
onError: 'log'
});
console.log('All commands executed successfully');
} catch (error) {
console.error('Command execution failed:', error);
}
}
runCommands();
Examples
Example 1: Simple Sequential Execution
This example demonstrates executing a series of shell commands in sequence. If any command fails, execution stops.
import shellFlow from '@fnet/shell-flow';
shellFlow({
commands: [
'echo "Hello World"',
'echo "This is a sequential command execution"',
'invalid-command' // This will cause the process to stop.
],
onError: 'stop'
})
.catch((error) => console.error(error.message));
Example 2: Parallel Execution with Continued Processing
Execute multiple commands in parallel where failure of one does not affect the others. A detailed log of each success and failure is maintained.
import shellFlow from '@fnet/shell-flow';
shellFlow({
commands: [
{
parallel: [
'echo "Running Task 1"',
'invalid-task-command', // This will log an error but won't stop execution.
'echo "Running Task 3"'
],
onError: 'continue'
}
]
})
.then(() => console.log('Tasks completed'))
.catch((error) => console.error('Some tasks failed:', error.message));
Acknowledgement
Development of this library was influenced by the need for robust command-line tooling. We acknowledge the contributions of all collaborative efforts in the open-source community that enhance toolset interoperability and functionality.
Input Schema
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
commands:
description: Command string or array of commands or command groups to execute.
type: array
items:
oneOf:
- type: string
- $ref: "#/$defs/commandGroup"
onError:
type: string
default: stop
enum:
- stop
- continue
- log
description: |
Global error handling policy: "stop", "continue", or "log".
required:
- commands
$defs:
commandGroup:
type: object
additionalProperties: false
properties:
steps:
type: array
items:
oneOf:
- type: string
- $ref: "#/$defs/commandGroup"
description: Array of commands to execute sequentially in steps.
parallel:
type: array
items:
oneOf:
- type: string
- $ref: "#/$defs/commandGroup"
description: Array of commands to execute in parallel.
fork:
type: array
items:
oneOf:
- type: string
- $ref: "#/$defs/commandGroup"
description: Array of commands to execute in fork.
env:
type: object
additionalProperties: true
description: Environment variables for the command group.
wdir:
type: string
description: Working directory for the command group.
onError:
type: string
enum:
- stop
- continue
- log
description: Error handling policy for this command group.
useScript:
type: boolean
default: false
description: >
If true, steps commands in this group are executed via a temporary
script file.
Ignored for parallel and fork.
captureName:
type: string
description: >
If set, the output of the command group is captured and stored in a
file with this name.
Ignored for parallel and fork.
oneOf:
- required:
- steps
- required:
- parallel
- required:
- fork