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.
Item Index
Methods
- determineExecPath
- exec
- exec
- getCountryCode
- getEnvironmentPaths
- getExecPath
- getGitPath
- getHomePath
- getLanguageCode
- getLocaleCode
- getNodePath
- getNpmPath
- getStandardExecPaths
- getStandardExecPaths
- getTmpPath
- hasExecSync
- hasSpawnSync
- initGitRepo
- initNodeModules
- initOrPullGitRepo
- isExecutable
- isExecutableSync
- isWindows
- openProcess
- outputData
- prefixData
- prepareExecutableOptions
- spawn
- spawnMultiple
- spawnMultiple
- spawnNodeModule
- spawnSync
- updateExecutableResult
Properties
Methods
determineExecPath
-
possibleExecPaths
-
[opts]
-
next
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
Arraystring array of file paths
-
[opts]
Object optional-
[sync]
Boolean optionaltrue to execute sync rather than async
-
-
next
Function-
err
Error -
execPath
String
-
exec
-
command
-
[opts]
-
next
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 optionaltrue to execute sync rather than async
-
[cwd]
String optionalCurrent working directory of the child process
-
[env]
Object optionalEnvironment key-value pairs
-
[encoding='utf8']
String optional -
[shell]
String optionalShell 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 optionalLargest amount of data (in bytes) allowed on stdout or stderr - if exceeded child process is killed.
-
[killSignal='SIGTERM']
String optional -
[uid]
Number optionalSets the user identity of the process.
-
[gid]
Number optionalSets the group identity of the process.
-
-
next
Function-
err
Error -
stdout
Buffer | Stringout buffer
-
stderr
Buffer | Stringerror buffer
-
Returns:
{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 optionaltrue to execute sync rather than async
-
[cwd]
String optionalCurrent working directory of the child process
-
[env]
Object optionalEnvironment key-value pairs
-
[encoding='utf8']
String optional -
[shell]
String optionalShell 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 optionalLargest amount of data (in bytes) allowed on stdout or stderr - if exceeded child process is killed.
-
[killSignal='SIGTERM']
String optional -
[uid]
Number optionalSets the user identity of the process.
-
[gid]
Number optionalSets the group identity of the process.
-
-
next
Function-
err
Error -
stdout
Buffer | Stringout buffer
-
stderr
Buffer | Stringerror buffer
-
getCountryCode
-
localeCode
Given the localeCode, return the country code.
Parameters:
-
localeCode
String
Returns:
getEnvironmentPaths
()
Array
Get the system's environment paths.
Returns:
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
Stringpath 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
Given the localeCode, return the language code.
Parameters:
-
localeCode
String
Returns:
getLocaleCode
-
lang
Get locale code - eg: en-AU, fr-FR, zh-CN etc.
Parameters:
-
lang
String
Returns:
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
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:
string array of file paths
getStandardExecPaths
-
execName
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:
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:
hasSpawnSync
()
Boolean
Has spawn sync. Returns true if the child_process spawnSync method exists, otherwise false
Returns:
initGitRepo
-
opts
-
next
Initialize a git Repository. Requires internet access.
Parameters:
-
opts
Object-
path
Stringpath to initiate local repository
-
[remote='origin']
String optional -
url
Stringurl to git remote repository
-
[branch='master']
String optional -
log
String -
output
String -
[cwd=process.cwd()]
String optionalCurrent working directory of the child process.
-
-
next
Function-
err
Error -
results
Arrayarray of spawn results
-
results[i].stdout
Streamout stream
-
results[i].stderr
Streamerror stream
-
results[i].status
Numbernode.js exit code
-
results[i].signal
Stringunix 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
Streamout stream
-
stderr
Streamerror stream
-
status
Numbernode.js exit code
-
signal
Stringunix 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
Stringpath to local repository
-
[remote='origin']
String optional -
url
Stringurl to git remote repository
-
[branch='master']
String optional -
log
String -
output
String -
[cwd=process.cwd()]
String optionalCurrent working directory of the child process.
-
-
next
Function-
err
Error -
results
Arrayarray of spawn results
-
results[i].stdout
Streamout stream
-
results[i].stderr
Streamerror stream
-
results[i].status
Numbernode.js exit code
-
results[i].signal
Stringunix style signal such as SIGKILL or SIGHUP
-
isExecutable
-
path
-
[opts]
-
next
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
Stringpath to test
-
[opts]
Object optional-
[sync]
Boolean optionaltrue to test sync rather than async
-
-
next
Functioncallback
-
err
Error -
isExecutable
Boolean
-
Returns:
returned if opts.sync = true
isExecutableSync
-
path
-
opts
-
[next]
Is the path to a file object an executable? Synchronised version of isExecutable
Parameters:
-
path
Stringpath to test
-
opts
Object -
[next]
Function optional-
err
Error -
isExecutable
Boolean
-
Returns:
isWindows
()
Boolean
Returns whether or not we are running on a windows machine
Returns:
openProcess
-
fn
Open a file. Pass your callback to fire when it is safe to open the process
Parameters:
-
fn
Functioncallback
outputData
-
data
-
[channel = 'stdout']
-
prefix
Internal: Set output data
Parameters:
-
data
Object -
[channel = 'stdout']
Object optional -
prefix
Object
prefixData
-
data
-
[prefix = '>\t']
Internal: prefix data
Parameters:
-
data
Object -
[prefix = '>\t']
String optional
Returns:
data
prepareExecutableOptions
-
[opts]
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 optionalin stream
-
[stdio=null]
Array optionalChild's stdio configuration
-
[safe=true]
Boolean optional -
[env=process.env]
Object optional
-
Returns:
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 optionalWhether to check the executable path.
-
[cwd]
String optionalCurrent working directory of the child process
-
[stdio]
Array | String optionalChild's stdio configuration.
-
[customFds]
Array optionalDeprecated File descriptors for the child to use for stdio.
-
[env]
Object optionalEnvironment key-value pairs.
-
[detached]
Boolean optionalThe child will be a process group leader.
-
[uid]
Number optionalSets the user identity of the process.
-
[gid]
Number optionalSets the group identity of the process.
-
-
next
Functioncallback
-
error
Error -
stdout
Streamout stream
-
stderr
Streamerror stream
-
status
Numbernode.js exit code
-
signal
Stringunix 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 optionalWhether to exec processes concurrently.
-
cwd
StringCurrent working directory of the child process.
-
stdio
Array | StringChild's stdio configuration.
-
customFds
ArrayDeprecated File descriptors for the child to use for stdio.
-
env
ObjectEnvironment key-value pairs.
-
detached
BooleanThe child will be a process group leader.
-
uid
NumberSets the user identity of the process.
-
gid
NumberSets the group identity of the process.
-
-
next
Functioncallback
-
error
Error -
results
Arrayarray of exec results
-
results[i].stdout
Streamout buffer
-
results[i].stderr
Streamerror 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 optionalWhether to spawn processes concurrently.
-
cwd
StringCurrent working directory of the child process.
-
stdio
Array | StringChild's stdio configuration.
-
customFds
ArrayDeprecated File descriptors for the child to use for stdio.
-
env
ObjectEnvironment key-value pairs.
-
detached
BooleanThe child will be a process group leader.
-
uid
NumberSets the user identity of the process.
-
gid
NumberSets the group identity of the process.
-
-
next
Functioncallback
-
error
Error -
results
Arrayarray of spawn results
-
results[i].stdout
Streamout stream
-
results[i].stderr
Streamerror stream
-
results[i].status
Numbernode.js exit code
-
results[i].signal
Stringunix 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
Stringname of node module
-
[cwd=process.cwd()]
String optionalCurrent working directory of the child process.
-
-
next
Function-
err
Object -
stdout
Streamout stream
-
stderr
Streamerror stream
-
status
Numbernode.js exit code
-
signal
Stringunix style signal such as SIGKILL or SIGHUP
-
spawnSync
-
command
-
[opts]
-
[next]
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 optionalWhether to check the executable path.
-
[cwd]
String optionalCurrent working directory of the child process
-
[stdio]
Array | String optionalChild's stdio configuration.
-
[customFds]
Array optionalDeprecated File descriptors for the child to use for stdio.
-
[env]
Object optionalEnvironment key-value pairs.
-
[detached]
Boolean optionalThe child will be a process group leader.
-
[uid]
Number optionalSets the user identity of the process.
-
[gid]
Number optionalSets the group identity of the process
-
-
[next]
Function optionalcallback
-
error
Error -
stdout
Streamout stream
-
stderr
Streamerror stream
-
status
Numbernode.js exit code
-
signal
Stringunix style signal such as SIGKILL or SIGHUP
-
Returns:
{error, pid, output, stdout, stderr, status, signal}
updateExecutableResult
-
result
-
[opts]
Internal: Prepare result of an execution
Parameters:
-
result
Object-
pid
ObjectNumber Pid of the child process
-
output
Objectoutput Array Array of results from stdio output
-
stdout
Streamstdout The contents of output
-
stderr
Streamstderr The contents of output
-
status
Numberstatus The exit code of the child process
-
signal
Stringsignal The signal used to kill the child process
-
error
ErrorThe error object if the child process failed or timed out
-
-
[opts]
Object optional-
[output]
Object optional -
[outputPrefix]
Object optional
-
Returns:
result
Properties
execPathCache
Unknown
private
Cache of executable paths