Skip to content

Latest commit

 

History

History
291 lines (205 loc) · 9 KB

api.md

File metadata and controls

291 lines (205 loc) · 9 KB

Classes

Name Description
PackageManager Wrapper class for executing commands for a given package manager

Functions

Name Description
applyConfigOverrides(config, context) Normalize the config by applying any overrides for environments, commands, or local-only config file.
applyEnvironmentOverrides(gasketConfig, config, [localFile]) Normalize the config by applying any environment or local overrides
installDependency(dependency, gasket) installDependency - install dependency
requireWithInstall(dependency, gasket) requireWithInstall - load devDependency request programmatically when needed
runShellCommand(cmd, [argv], [options], [debug]) Promise friendly wrapper to running a shell command (eg: git, npm, ls) which passes back any { stdout, stderr } to the error thrown.
tryRequire(path) Tries to require a module, but ignores if it is not found. If not found, result will be null.
tryResolve(modulePath, options)

PackageManager

Wrapper class for executing commands for a given package manager

Kind: global class

new PackageManager(options)

Param Type Description
options object Options
[options.packageManager] string Name of manager, either npm (default) or yarn
options.dest string Target directory where node_module should exist
[options.npmconfig] string DEPRECATED Path to userconfig

packageManager.exec(cmd, args)

Executes npm in the application directory this.dest. This installation can be run multiple times.

Kind: instance method of PackageManager
Returns: Promise - promise
Access: public

Param Type Description
cmd string The command that needs to be executed.
args Array.<string> Additional CLI arguments to pass to npm.

packageManager.link(packages)

Executes npm link in the application directory this.dest.

Kind: instance method of PackageManager
Returns: Promise - promise
Access: public

Param Type Description
packages Array.<string> Explicit npm packages to link locally.

packageManager.install(args)

Executes npm install in the application directory this.dest. This installation can be run multiple times.

Kind: instance method of PackageManager
Returns: Promise - promise
Access: public

Param Type Description
args Array.<string> Additional CLI arguments to pass to npm.

packageManager.info(args)

Executes yarn or npm info, and returns parsed JSON data results.

Kind: instance method of PackageManager
Returns: Promise.<object> - stdout and data
Access: public

Param Type Description
args Array.<string> Additional CLI arguments to pass to npm.

PackageManager.spawnNpm(argv, spawnWith)

Executes the appropriate npm binary with the verbatim argv and spawnWith options provided. Passes appropriate debug flag for npm based on process.env.

Kind: static method of PackageManager
Returns: Promise - promise
Access: public

Param Type Description
argv Array.<string> Precise CLI arguments to pass to npm.
spawnWith object Options for child_process.spawn.

PackageManager.spawnYarn(argv, spawnWith)

Executes the appropriate yarn binary with the verbatim argv and spawnWith options provided. Passes appropriate debug flag for npm based on process.env.

Kind: static method of PackageManager
Returns: Promise - promise
Access: public

Param Type Description
argv Array.<string> Precise CLI arguments to pass to npm.
spawnWith object Options for child_process.spawn.

applyConfigOverrides(config, context)

Normalize the config by applying any overrides for environments, commands, or local-only config file.

Kind: global function
Returns: object - config

Param Type Description
config object Target config to be normalized
context object Context for applying overrides
context.env string Name of environment
[context.commandId] string Name of command
[context.root] string Project root; required if using localeFile
[context.localFile] string Optional file to load relative to gasket root

applyEnvironmentOverrides(gasketConfig, config, [localFile])

Deprecated

Normalize the config by applying any environment or local overrides

Kind: global function
Returns: object - config

Param Type Description
gasketConfig object Gasket config
config object Target config to be normalized
[localFile] string Optional file to load relative to gasket root

installDependency(dependency, gasket)

installDependency - install dependency

Kind: global function

Param Type Description
dependency string The dep/s needed
gasket Gasket Gasket instance

requireWithInstall(dependency, gasket)

requireWithInstall - load devDependency request programmatically when needed

Kind: global function
Returns: object ⎮ Array.<object> - module or list of modules

Param Type Description
dependency string | Array.<string> The require'ed dep/s needed
gasket Gasket Gasket instance

runShellCommand(cmd, [argv], [options], [debug])

Promise friendly wrapper to running a shell command (eg: git, npm, ls) which passes back any { stdout, stderr } to the error thrown.

Options can be passed to the underlying spawn. An additional signal option can be passed to use AbortController, allowing processes to be killed when no longer needed.

Kind: global function
Returns: Promise - A promise represents if command succeeds or fails.
Access: public

Param Type Description
cmd string Binary that is run
[argv] Array.<string> Arguments passed to npm binary through spawn.
[options] object Options passed to npm binary through spawn
[options.signal] object AbortControl signal allowing process to be canceled
[debug] boolean When present pipes std{out,err} to process.*

Example

const { runShellCommand } = require('@gasket/utils');

 async function helloWorld() {
  await runShellCommand('echo', ['hello world']);
}

Example

// With timeout using AbortController

const { runShellCommand } = require('@gasket/utils');
const AbortController = require('abort-controller');

 async function helloWorld() {
  const controller = new AbortController();
  // abort the process after 60 seconds
  const id = setTimeout(() => controller.abort(), 60000);
  await runShellCommand('long-process', ['something'], { signal: controller.signal });
  clearTimeout(id);
}

tryRequire(path)

Tries to require a module, but ignores if it is not found. If not found, result will be null.

Kind: global function
Returns: object - module

Param Type Description
path string Module to import

Example

const { tryRequire } = require('@gasket/utils');

 let someConfig = tryRequire('../might/be/a/path/to/some/file');

 if(!someConfig) {
  someConfig = require('./default-config')
}

tryResolve(modulePath, options)

Kind: global function
Returns: string - module path

Param Type Description
modulePath string Module to import
options object Paths to search for the module