@fnet/shell-flow v0.1.4

@fnet/shell-flow

This project is designed to help users execute a series of shell commands efficiently and flexibly. With @fnet/shell-flow, you can manage how multiple commands run, specifying whether they should run sequentially, in parallel, or as separate forked processes. It provides a straightforward way to control error handling during shell command execution, ensuring that your scripts run smoothly even when errors occur.

How It Works

@fnet/shell-flow operates by taking in an array of shell commands, which can be structured in different formats: sequentially, in parallel, or as forked processes. You can set error handling policies that determine whether the execution should stop, continue, or simply log errors when they occur. This flexibility allows you to customize your command execution flow based on the needs of your project.

Key Features

• Sequential Execution: Run commands one after the other, ensuring that each completes before the next begins.
• Parallel Execution: Execute multiple commands at the same time, which can help save time by running independent tasks simultaneously.
• Forked Processes: Run commands as forked processes, which allows them to operate independently of each other.
• Error Handling Options: Choose how errors are handled with options to stop, continue, or log errors without disrupting the execution flow.
• Environmental Control: Pass specific environment variables and working directories to your commands for greater flexibility and control.

Conclusion

In essence, @fnet/shell-flow provides a flexible and controlled environment for executing multiple shell commands. Whether you need sequential order or simultaneous execution, this tool helps streamline your command processing with easy-to-manage error handling and execution options. It's a practical solution for efficiently managing complex shell command sequences.

@fnet/shell-flow Developer Guide

Overview

The @fnet/shell-flow library is designed to simplify the execution of shell commands in a flexible and error-tolerant manner. By providing a structured way to run commands sequentially, in parallel, or forked, it allows developers to manage complex shell command workflows with ease. The library's key feature is its ability to handle errors using customizable policies, making it a versatile tool for both straightforward and intricate shell task automation.

Installation

You can install the @fnet/shell-flow library using npm or yarn. Here are the instructions for both:

Using npm

npm install @fnet/shell-flow

Using yarn

yarn add @fnet/shell-flow

Usage

To use the @fnet/shell-flow library, import the default function and execute your shell commands by defining them in an array. You can specify how to handle errors to fit your needs, whether you want to stop execution, continue despite errors, or simply log them.

Example: Basic Command Execution

import runShellFlow from '@fnet/shell-flow';

(async () => {
  await runShellFlow({
    commands: ['echo "Hello, world!"', 'ls -al'],
    onError: 'continue',  // Options: 'stop', 'continue', 'log'
  });
})();

Example: Parallel and Forked Execution with Error Handling

import runShellFlow from '@fnet/shell-flow';

(async () => {
  await runShellFlow({
    commands: [
      { 
        parallel: ['echo "Command 1"', 'invalidcommand'],
        onError: 'log'
      },
      { 
        fork: ['echo "Forked command 1"', 'echo "Forked command 2"'],
        onError: 'notifyParent'
      }
    ],
  });
})();

Examples

Execute Commands Sequentially

import runShellFlow from '@fnet/shell-flow';

(async () => {
  await runShellFlow({
    commands: ['echo "Starting process"', 'node --version'],
    onError: 'stop',
  });
})();

Execute Multiple Commands in Parallel

import runShellFlow from '@fnet/shell-flow';

(async () => {
  await runShellFlow({
    commands: [
      {
        parallel: ['echo "Command A"', 'echo "Command B"'],
        onError: 'continue',
      },
    ],
  });
})();

Forked Command Execution

import runShellFlow from '@fnet/shell-flow';

(async () => {
  await runShellFlow({
    commands: [
      {
        fork: ['echo "First Task"', 'echo "Second Task"'],
        onError: 'log',
      },
    ],
  });
})();

Each of these examples demonstrates how to utilize the primary function to manage shell operations efficiently, regardless of whether tasks need to run in parallel or in different forks.

Acknowledgement

The functionality provided by this library simplifies command management in applications where complex execution flows are necessary. The patterns used here are based on common practices in system automation and scripting.

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: "#/definitions/commandGroup"
  onError:
    type: string
    default: stop
    enum:
      - stop
      - continue
      - log
    description: |
      Global error handling policy: "stop", "continue", or "log".
required:
  - commands
definitions:
  commandGroup:
    type: object
    additionalProperties: false
    properties:
      steps:
        type: array
        items:
          oneOf:
            - type: string
            - $ref: "#/definitions/commandGroup"
        description: Array of commands to execute sequentially in steps.
      parallel:
        type: array
        items:
          oneOf:
            - type: string
            - $ref: "#/definitions/commandGroup"
        description: Array of commands to execute in parallel.
      fork:
        type: array
        items:
          oneOf:
            - type: string
            - $ref: "#/definitions/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.
    oneOf:
      - required:
          - steps
      - required:
          - parallel
      - required:
          - fork