Skip to main content

@yarnpkg/shell

A JavaScript implementation of a bash-like shell (we use it in Yarn 2 to provide cross-platform scripting). This package exposes an API that abstracts both the parser and the interpreter; should you only need the parser you can check out @yarnpkg/parsers, but you probably won't need it.

Usage​

import {execute} from '@yarnpkg/shell';

process.exitCode = await execute(`ls "$0" | wc -l`, [process.cwd()]);

Features​

  • Typechecked
  • Portable across systems
  • Supports custom JS builtins
  • Supports pipes
  • Supports glob patterns (only for files that exist on the filesystem: ls *.txt)
  • Supports logical operators
  • Supports subshells
  • Supports variables
  • Supports string manipulators
  • Supports argc/argv
  • Supports background jobs with color-coded output
  • Supports the most classic builtins
  • Doesn't necessarily need to access the fs

Help Wanted​

  • Full glob support (mv build/{index.js,index.build.js}, echo {foo,bar}, FOO=a,b echo {$FOO,x})
  • More string manipulators

Non-Goals​

  • Perfect POSIX compliance (basic scripting is enough for now)
  • Multiline scripts (we mostly target one-liners)
  • Control structures (same reason)

Index

Classes

Functions

Namespaces

Type Aliases

Functions

execute

  • execute(command: string, args?: string[], __namedParameters?: Partial<UserOptions>): Promise<number>

  • Parameters

    • command: string
    • args: string[] = []
    • __namedParameters: Partial<UserOptions> = {}

    Returns Promise<number>

Type Aliases

Glob

Glob: globUtils.Glob

ShellBuiltin

ShellBuiltin: (args: string[], opts: ShellOptions, state: ShellState) => Promise<number>

Type declaration

ShellOptions

ShellOptions: { args: string[]; baseFs: FakeFS<PortablePath>; builtins: Map<string, ShellBuiltin>; glob: globUtils.Glob; initialStderr: Writable; initialStdin: Readable; initialStdout: Writable }

Type declaration

ShellState

ShellState: { backgroundJobs: Promise<unknown>[]; cwd: PortablePath; environment: {}; exitCode: number | null; nextBackgroundJobIndex: number; procedures: {}; stderr: Writable; stdin: Readable; stdout: Writable; variables: {} }

Type declaration

  • backgroundJobs: Promise<unknown>[]
  • cwd: PortablePath
  • environment: {}
    • [key string]: string
  • exitCode: number | null
  • nextBackgroundJobIndex: number
  • procedures: {}
    • [key string]: ProcessImplementation
  • stderr: Writable
  • stdin: Readable
  • stdout: Writable
  • variables: {}
    • [key string]: string

UserOptions

UserOptions: { baseFs: FakeFS<PortablePath>; builtins: {}; cwd: PortablePath; env: {}; glob: globUtils.Glob; stderr: Writable; stdin: Readable | null; stdout: Writable; variables: {} }

Type declaration