@getvim/execute

中文文档
1.0.0发布于 2019/12/02ISCTypeScriptCommonJS零依赖近 30 天下载 1.6万

Extremely opinionated Bash execution from Node.js

原始使用文档
文档目录10 节
  1. Requirements
  2. Usage
  3. Installation
  4. Basic usage
  5. Environment variables
  6. Piping
  7. Errors
  8. Behavior
  9. Why?
  10. Common Bash Pitfalls

@getvim/execute

This is an extremely opinionated, zero dependencies, tiny module for executing command line programs from Node.js using a Bash shell.

The design philosophy behind this module aims to abstract away many of the Bash pitfalls most of us never knew existed.

Requirements

You must be working in an environment where /bin/bash is available.

Minimal Node.js version is 8.0.0.

Usage

Installation

npm install --save @getvim/execute
yarn add @getvim/execute

Basic usage

const { execute } = require('@getvim/execute');
execute('ls')
    .then(console.log); // result: "feature.js\nfeature.spec.js"

Environment variables

const { execute } = require('@getvim/execute');
execute('echo $MY_NAME', { env: { MY_NAME: 'Jake Chambers' } })
    .then(console.log); // result: "Jake Chambers"

Piping

Piping allows you to interleave shell commands with modern JS features that are safer and easier to use than a lot of shell alternatives like using external modules, concurrency, loops or string formatters.

const { execute, pipe } = require('@getvim/execute');
const mailer = require('@fictional/mail-client')
execute('ls | grep temp')
    .then(tempFiles => {
        mailer('[email protected]', 'Temp files being deleted', tempFiles);
        return tempFiles;
    })
    .then(pipe('xargs rm'));

Errors

const { execute } = require('@getvim/execute');
execute('npm install')
    .then(() => execute('npm test')) // Has a failing test
    .then(() => execute('npm publish'))
    .catch(error => console.error('Failed CI/CD!', error));
    /* result:
        Failed CI/CD! 
        { 
            killed: false, 
            code: 1, 
            signal: null, 
            cmd: "set -euo pipefail\nnpm test" 
            stdout: "... test results ..."
            stderr: "... failing test ..."
        } 
    */

Behavior

  • execute's Promise will reject in the following cases:
    • Usage of an undefined environment variable
    • A command, in a pipe or otherwise, returned an exit code other than 0 (even greping without a result will do this)
  • Results are always a string.
  • Processes are not interactive and do not print to the screen. If a process is waiting for user input, (like a prompt for a Y/N confirmation) the Promise will never resolve/reject.

Why?

Bash has a lot of pitfalls. As code organizations grow their reliance on CI/CD scripts or internal tooling for day-to-day work grow as well. Most organizations write those scripts in pure Bash. Most of the people reading/writing these scripts will find themselves victims of those counter intuitive Bash pitfalls. This module aims to take some very opinionated decisions that will guard its users from 80% of these common mistakes.

Every problem that this tool purports to solve can be solved using Bash only solutions, but it requires learning time most developers will not invest. Using this module you can use language features you're already familiar with instead of learning the archaic and unintuitive Bash solutions.

Common Bash Pitfalls

Only the last error counts

Problem:

npm install
npm test # this contains a failing test, the exit code here is nonzero
npm publish # Bash continues to run the script and npm publish will still happen

Solution: Any command run with execute will be run with the set -e flag and the script will immediately exit with a Promise rejection on any line that returns a non zero exit code.

Failure mid-pipe doesn't count

Problem:

failingCommand | echo "a" # failingCommand does not throw an error because it's in a pipe
echo "b"
# result:
# a
# b

Solution: Any command run with execute will be run with the set -o pipefail flag and the script will immediately exit with a Promise rejection on any command in a pipe chain that returns a non zero exit code.

Using unset variables does not throw errors

Problem:

rm -rf $BUILD_FOLDER/* # If $BUILD_FOLDER is unset by mistake, this line would delete the entire filesystem

Solution: Any command run with execute will be run with the set -u flag and the script will immediately exit with a Promise rejection on any usage of an unset environment variable.

Basic built-in language features like string manipulation are easy to get wrong

Problem:

# Trying to extract the Nth word in a string
echo $STRING | awk -v N=$N '{print $N}' # You have to learn awk or other tools

Solution: Usage of execute.pipe allows to easily jump between a Bash context and a JS context.

const { execute, pipe } = require('@getvim/execute');
const N = 5;
execute('echo $STRING', { env: { STRING:'My name is Inigo Montoya'}})
    .then(result => result.split(' ')[N - 1])
    .then(pipe('rev'))
    .then(console.log); // Result: "ayotnoM"

Basic built-in language constructs like IF-ELSE / Conditionals are easy to get wrong

Problem: It very easy to get Syntax error or unintended behavior from Bash's language constructs.

# Checking if a variable is greater than 0
if [$VAR > 0]; then ... # Syntax error, forgot spaces

if [ $VAR > 0 ]; then ... # ">" Means stream redirection

if [[ $VAR > 0 ]]; then ... # ">" Means comparison, but of strings (lexicographs)

if [[ $VAR -gt 0 ]]; then ... # Finally works!

if (( $VAR > 0 )); then ... # Confusingly, this also works...

Solution: Execute allows to easily jump between a Bash context and a JS context.

const { execute, pipe } = require('@getvim/execute');
execute('wc -l file.txt')
    .then(lineCount => lineCount > 0 ? "Success" : "Failure")
    .then(pipe("tee SomeFile.txt"))

版本与发布记录

@getvim/execute 共发布 7 个版本,首次发布于 2019/11/27;过去 12 个月发布了 0 个版本。

版本发布日期距今
1.0.0latest2019/12/026 年前
0.12.22019/12/016 年前
0.12.12019/12/016 年前
0.12.02019/12/016 年前
0.11.02019/11/286 年前
0.10.02019/11/286 年前

关于 @getvim/execute 的常见问题

@getvim/execute 是什么?

Extremely opinionated Bash execution from Node.js

如何安装 @getvim/execute?

在项目目录运行 npm install @getvim/execute,或使用 pnpm add / yarn add / bun add。

@getvim/execute 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@getvim/execute 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@getvim/execute 可以商用吗?

@getvim/execute 使用 ISC 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@getvim/execute 的下载量有多少?

根据 npm 官方下载统计,@getvim/execute 在 2026/10/17 – 2026/11/15 这 30 天内被下载 15,858 次,日均约 529 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@getvim/execute 还在维护吗?

最新版本 1.0.0 发布于 2019/12/02(6 年前);至今共发布 7 个版本,其中过去 12 个月发布了 0 个;首次发布于 2019/11/27。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。