npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@fnet/shell-flow

v0.1.12

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

912

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