@fnet/shell-flow

@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