API Docs for:
Show:

safeps Class

Contains methods to safely spawn and manage various file system processes. It differs from the standard node.js child_process (https://nodejs.org/docs/v0.11.13/api/child_process.html#child_process_child_process) module in that it intercepts and handles many common errors that might occur when invoking child processes that could cause an application to crash. Most commonly, errors such as ENOENT and EACCESS. This enables an application to be both cleaner and more robust.

Methods

determineExecPath

(
  • possibleExecPaths
  • [opts]
  • next
)
private

Determine an executable path from the passed array of possible file paths. Called by getExecPath to find a path for a given executable name.

Parameters:

  • possibleExecPaths Array

    string array of file paths

  • [opts] Object optional
    • [sync] Boolean optional

      true to execute sync rather than async

  • next Function
    • err Error
    • execPath String

exec

(
  • command
  • [opts]
  • next
)
Object

Syncronised version of safeps.exec. Runs a command in a shell and buffers the output. Will not return until the child process has fully closed. Results can be returned from the method call or via a passed callback. Even if a callback is passed to execSync, the method will still be syncronised with the child process and the callback will only return after the child process has closed. Note: Stdout and stderr should be Buffers but they are strings unless encoding:null for now, nothing we should do, besides wait for joyent to reply https://github.com/joyent/node/issues/5833#issuecomment-82189525.

Parameters:

  • command Object
  • [opts] Object optional
    • [sync] Boolean optional

      true to execute sync rather than async

    • [cwd] String optional

      Current working directory of the child process

    • [env] Object optional

      Environment key-value pairs

    • [encoding='utf8'] String optional
    • [shell] String optional

      Shell to execute the command with (Default: '/bin/sh' on UNIX, 'cmd.exe' on Windows, The shell should understand the -c switch on UNIX or /s /c on Windows. On Windows, command line parsing should be compatible with cmd.exe.)

    • [timeout=0] Number optional
    • [maxBuffer=200*1024] Number optional

      Largest amount of data (in bytes) allowed on stdout or stderr - if exceeded child process is killed.

    • [killSignal='SIGTERM'] String optional
    • [uid] Number optional

      Sets the user identity of the process.

    • [gid] Number optional

      Sets the group identity of the process.

  • next Function
    • err Error
    • stdout Buffer | String

      out buffer

    • stderr Buffer | String

      error buffer

Returns:

Object:

{error, stdout, stderr}

exec

(
  • command
  • [opts]
  • next
)

Wrapper around node's exec command for a cleaner, more robust and powerful API. Runs a command in a shell and buffers the output. Note: Stdout and stderr should be Buffers but they are strings unless encoding:null for now, nothing we should do, besides wait for joyent to reply https://github.com/joyent/node/issues/5833#issuecomment-82189525.

Parameters:

  • command Object
  • [opts] Object optional
    • [sync] Boolean optional

      true to execute sync rather than async

    • [cwd] String optional

      Current working directory of the child process

    • [env] Object optional

      Environment key-value pairs

    • [encoding='utf8'] String optional
    • [shell] String optional

      Shell to execute the command with (Default: '/bin/sh' on UNIX, 'cmd.exe' on Windows, The shell should understand the -c switch on UNIX or /s /c on Windows. On Windows, command line parsing should be compatible with cmd.exe.)

    • [timeout=0] Number optional
    • [maxBuffer=200*1024] Number optional

      Largest amount of data (in bytes) allowed on stdout or stderr - if exceeded child process is killed.

    • [killSignal='SIGTERM'] String optional
    • [uid] Number optional

      Sets the user identity of the process.

    • [gid] Number optional

      Sets the group identity of the process.

  • next Function
    • err Error
    • stdout Buffer | String

      out buffer

    • stderr Buffer | String

      error buffer

getCountryCode

(
  • localeCode
)
String

Given the localeCode, return the country code.

Parameters:

  • localeCode String

Returns:

String:

getEnvironmentPaths

() Array

Get the system's environment paths.

Returns:

Array:

string array of file paths

getExecPath

(
  • execName
  • [opts]
  • next
)

Given an executable name, search and find its actual path. Will search the standard file paths defined by the environment to see if the executable is in any of those paths.

Parameters:

  • execName Object
  • [opts] Object optional
    • [cache=true] Boolean optional
  • next Function
    • err Error
    • foundPath String

      path to the executable

getGitPath

(
  • [opts]
  • next.err
  • next.gitPath
)

Path to the evironment's GIT directory. As 'git' is not always available in the environment path, we should check common path locations and if we find one that works, then we should use it.

Parameters:

  • [opts] Object optional
    • [cache=true] Object optional
  • next.err Error
  • next.gitPath String

getHomePath

(
  • [opts]
  • next
)

Get home path. Returns the user's home directory. Based upon home function from: https://github.com/isaacs/osenv

Parameters:

  • [opts] Object optional
    • [cache=true] Object optional
  • next Function
    • err Error
    • homePath String

getLanguageCode

(
  • localeCode
)
String

Given the localeCode, return the language code.

Parameters:

  • localeCode String

Returns:

String:

getLocaleCode

(
  • lang
)
String

Get locale code - eg: en-AU, fr-FR, zh-CN etc.

Parameters:

  • lang String

Returns:

String:

getNodePath

(
  • [opts]
  • next.err
  • next.nodePath
)

Path to the evironment's Node directory. As 'node' is not always available in the environment path, we should check common path locations and if we find one that works, then we should use it

Parameters:

  • [opts] Object optional
    • [cache=true] Object optional
  • next.err Error
  • next.nodePath String

getNpmPath

(
  • [opts]
  • next.err
  • next.npmPath
)

Path to the evironment's NPM directory. As 'npm' is not always available in the environment path, we should check common path locations and if we find one that works, then we should use it

Parameters:

  • [opts] Object optional
    • [cache=true] Object optional
  • next.err Error
  • next.npmPath String

getStandardExecPaths

(
  • execName
)
Array private

Get the possible paths for the passed executable using the standard environment paths. Basically, get a list of places to look for the executable. Makes allowances for Windows executables possibly needing an extension to ensure execution (.exe, .cmd, .bat).

Parameters:

  • execName String

Returns:

Array:

string array of file paths

getStandardExecPaths

(
  • execName
)
Array private

Get the possible paths for the passed executable using the standard environment paths. Basically, get a list of places to look for the executable. Only safe for non-Windows systems.

Parameters:

  • execName String

Returns:

Array:

string array of file paths

getTmpPath

(
  • [opts]
  • next.err
  • next.tmpPath
)

Path to the evironment's temporary directory. Based upon tmpdir function from: https://github.com/isaacs/osenv

Parameters:

  • [opts] Object optional
    • [cache=true] Object optional
  • next.err Error
  • next.tmpPath String

hasExecSync

() Boolean

Has exec sync. Returns true if the child_process execSync method exists, otherwise false

Returns:

Boolean:

hasSpawnSync

() Boolean

Has spawn sync. Returns true if the child_process spawnSync method exists, otherwise false

Returns:

Boolean:

initGitRepo

(
  • opts
  • next
)

Initialize a git Repository. Requires internet access.

Parameters:

  • opts Object
    • path String

      path to initiate local repository

    • [remote='origin'] String optional
    • url String

      url to git remote repository

    • [branch='master'] String optional
    • log String
    • output String
    • [cwd=process.cwd()] String optional

      Current working directory of the child process.

  • next Function
    • err Error
    • results Array

      array of spawn results

    • results[i].stdout Stream

      out stream

    • results[i].stderr Stream

      error stream

    • results[i].status Number

      node.js exit code

    • results[i].signal String

      unix style signal such as SIGKILL or SIGHUP

initNodeModules

(
  • opts
  • next
)

Init Node Modules with cross platform support supports linux, heroku, osx, windows

Parameters:

  • opts Object
  • next Function
    • err Object
    • stdout Stream

      out stream

    • stderr Stream

      error stream

    • status Number

      node.js exit code

    • signal String

      unix style signal such as SIGKILL or SIGHUP

initOrPullGitRepo

(
  • opts
  • next
)

Pull from a git repository if it already exists on the file system else initialize new Git repository. Requires internet access.

Parameters:

  • opts Object
    • path String

      path to local repository

    • [remote='origin'] String optional
    • url String

      url to git remote repository

    • [branch='master'] String optional
    • log String
    • output String
    • [cwd=process.cwd()] String optional

      Current working directory of the child process.

  • next Function
    • err Error
    • results Array

      array of spawn results

    • results[i].stdout Stream

      out stream

    • results[i].stderr Stream

      error stream

    • results[i].status Number

      node.js exit code

    • results[i].signal String

      unix style signal such as SIGKILL or SIGHUP

isExecutable

(
  • path
  • [opts]
  • next
)
Boolean

Is the path to a file object an executable? Boolean result returned as the isExecutable parameter of the passed callback. next(err, isExecutable)

Parameters:

  • path String

    path to test

  • [opts] Object optional
    • [sync] Boolean optional

      true to test sync rather than async

  • next Function

    callback

    • err Error
    • isExecutable Boolean

Returns:

Boolean:

returned if opts.sync = true

isExecutableSync

(
  • path
  • opts
  • [next]
)
Boolean

Is the path to a file object an executable? Synchronised version of isExecutable

Parameters:

  • path String

    path to test

  • opts Object
  • [next] Function optional
    • err Error
    • isExecutable Boolean

Returns:

Boolean:

isWindows

() Boolean

Returns whether or not we are running on a windows machine

Returns:

Boolean:

openProcess

(
  • fn
)

Open a file. Pass your callback to fire when it is safe to open the process

Parameters:

  • fn Function

    callback

outputData

(
  • data
  • [channel = 'stdout']
  • prefix
)
private

Internal: Set output data

Parameters:

  • data Object
  • [channel = 'stdout'] Object optional
  • prefix Object

prefixData

(
  • data
  • [prefix = '>\t']
)
Object private

Internal: prefix data

Parameters:

  • data Object
  • [prefix = '>\t'] String optional

Returns:

Object:

data

prepareExecutableOptions

(
  • [opts]
)
Object private

Internal: Prepare options for an execution. Makes sure all options are populated or exist and gives the opportunity to prepopulate some of those options.

Parameters:

  • [opts] Object optional
    • [stdin=null] Stream optional

      in stream

    • [stdio=null] Array optional

      Child's stdio configuration

    • [safe=true] Boolean optional
    • [env=process.env] Object optional

Returns:

Object:

opts

spawn

(
  • command
  • [opts]
  • next
)

Wrapper around node's spawn command for a cleaner, more robust and powerful API. Launches a new process with the given command. Command line arguments are part of the command parameter (unlike the node.js spawn). Command can be an array of command line arguments or a command line string. Opts allows additional options to be sent to the spawning action.

Simple usage example:

var safeps = require('safeps');
var command = ['npm', 'install','jade','--save'];

//a lot of the time you won't need the opts argument
var opts = {
    cwd: __dirname //this is actually pointless in a real application
}
function myCallback(error, stdout, stderr, status, signal){
    console.log(error);
    console.log(status);
    console.log(signal);
    console.log("I've finished...");
}
safeps.spawn(command, opts, myCallback);

Parameters:

  • command Array | String
  • [opts] Object optional
    • [safe] Boolean optional

      Whether to check the executable path.

    • [cwd] String optional

      Current working directory of the child process

    • [stdio] Array | String optional

      Child's stdio configuration.

    • [customFds] Array optional

      Deprecated File descriptors for the child to use for stdio.

    • [env] Object optional

      Environment key-value pairs.

    • [detached] Boolean optional

      The child will be a process group leader.

    • [uid] Number optional

      Sets the user identity of the process.

    • [gid] Number optional

      Sets the group identity of the process.

  • next Function

    callback

    • error Error
    • stdout Stream

      out stream

    • stderr Stream

      error stream

    • status Number

      node.js exit code

    • signal String

      unix style signal such as SIGKILL or SIGHUP

spawnMultiple

(
  • commands
  • [opts]
  • next
)

Exec multiple processes in the one method call. Launches new processes with the given array of commands. Each item in the commands array represents a command parameter sent to the safeps.exec method, so each item can be a command line string or an array of command line inputs. It is also possible to pass a single command string and in this case calling execMultiple will be effectively the same as calling safeps.exec.

Parameters:

  • commands Array | String
  • [opts] Object optional
    • [concurrency=1] Boolean optional

      Whether to exec processes concurrently.

    • cwd String

      Current working directory of the child process.

    • stdio Array | String

      Child's stdio configuration.

    • customFds Array

      Deprecated File descriptors for the child to use for stdio.

    • env Object

      Environment key-value pairs.

    • detached Boolean

      The child will be a process group leader.

    • uid Number

      Sets the user identity of the process.

    • gid Number

      Sets the group identity of the process.

  • next Function

    callback

    • error Error
    • results Array

      array of exec results

    • results[i].stdout Stream

      out buffer

    • results[i].stderr Stream

      error buffer

spawnMultiple

(
  • commands
  • [opts]
  • next
)

Spawn multiple processes in the one method call. Launches new processes with the given array of commands. Each item in the commands array represents a command parameter sent to the safeps.spawn method, so each item can be a command line string or an array of command line inputs. It is also possible to pass a single command string and in this case calling spawnMultiple will be effectively the same as calling safeps.spawn.

Parameters:

  • commands Array | String
  • [opts] Object optional
    • [concurrency=1] Boolean optional

      Whether to spawn processes concurrently.

    • cwd String

      Current working directory of the child process.

    • stdio Array | String

      Child's stdio configuration.

    • customFds Array

      Deprecated File descriptors for the child to use for stdio.

    • env Object

      Environment key-value pairs.

    • detached Boolean

      The child will be a process group leader.

    • uid Number

      Sets the user identity of the process.

    • gid Number

      Sets the group identity of the process.

  • next Function

    callback

    • error Error
    • results Array

      array of spawn results

    • results[i].stdout Stream

      out stream

    • results[i].stderr Stream

      error stream

    • results[i].status Number

      node.js exit code

    • results[i].signal String

      unix style signal such as SIGKILL or SIGHUP

spawnNodeModule

(
  • name
  • args
  • opts
  • next
)

Spawn Node Modules with cross platform support supports linux, heroku, osx, windows spawnNodeModule(name:string, args:array, opts:object, next:function) Better than https://github.com/mafintosh/npm-execspawn as it uses safeps

Parameters:

  • name String
  • args Array
  • opts Object
    • name String

      name of node module

    • [cwd=process.cwd()] String optional

      Current working directory of the child process.

  • next Function
    • err Object
    • stdout Stream

      out stream

    • stderr Stream

      error stream

    • status Number

      node.js exit code

    • signal String

      unix style signal such as SIGKILL or SIGHUP

spawnSync

(
  • command
  • [opts]
  • [next]
)
Object

Syncronised version of safeps.spawn. Will not return until the child process has fully closed. Results can be returned from the method call or via a passed callback. Even if a callback is passed to spawnSync, the method will still be syncronised with the child process and the callback will only return after the child process has closed.

Simple usage example:

var safeps = require('safeps');
var command = ['npm', 'install', 'jade', '--save'];

//a lot of the time you won't need the opts argument
var opts = {
    cwd: __dirname //this is actually pointless in a real application
};

var result = safeps.spawnSync(command, opts);

console.log(result.error);
console.log(result.status);
console.log(result.signal);
console.log("I've finished...");

Parameters:

  • command Array | String
  • [opts] Object optional
    • [safe] Boolean optional

      Whether to check the executable path.

    • [cwd] String optional

      Current working directory of the child process

    • [stdio] Array | String optional

      Child's stdio configuration.

    • [customFds] Array optional

      Deprecated File descriptors for the child to use for stdio.

    • [env] Object optional

      Environment key-value pairs.

    • [detached] Boolean optional

      The child will be a process group leader.

    • [uid] Number optional

      Sets the user identity of the process.

    • [gid] Number optional

      Sets the group identity of the process

  • [next] Function optional

    callback

    • error Error
    • stdout Stream

      out stream

    • stderr Stream

      error stream

    • status Number

      node.js exit code

    • signal String

      unix style signal such as SIGKILL or SIGHUP

Returns:

Object:

{error, pid, output, stdout, stderr, status, signal}

updateExecutableResult

(
  • result
  • [opts]
)
Object private

Internal: Prepare result of an execution

Parameters:

  • result Object
    • pid Object

      Number Pid of the child process

    • output Object

      output Array Array of results from stdio output

    • stdout Stream

      stdout The contents of output

    • stderr Stream

      stderr The contents of output

    • status Number

      status The exit code of the child process

    • signal String

      signal The signal used to kill the child process

    • error Error

      The error object if the child process failed or timed out

  • [opts] Object optional
    • [output] Object optional
    • [outputPrefix] Object optional

Returns:

Object:

result

Properties

execPathCache

Unknown private

Cache of executable paths