Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

liftoff

Package Overview
Dependencies
Maintainers
4
Versions
58
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

liftoff - npm Package Compare versions

Comparing version 3.1.0 to 4.0.0

lib/array_find.js
lib/needs_lookup.js

224

index.js

@@ -8,3 +8,3 @@ var util = require('util');

var flaggedRespawn = require('flagged-respawn');
var isPlainObject = require('is-plain-object');
var isPlainObject = require('is-plain-object').isPlainObject;
var mapValues = require('object.map');

@@ -14,4 +14,6 @@ var fined = require('fined');

var findCwd = require('./lib/find_cwd');
var arrayFind = require('./lib/array_find');
var findConfig = require('./lib/find_config');
var fileSearch = require('./lib/file_search');
var needsLookup = require('./lib/needs_lookup');
var parseOptions = require('./lib/parse_options');

@@ -29,17 +31,18 @@ var silentRequire = require('./lib/silent_require');

Liftoff.prototype.requireLocal = function(module, basedir) {
Liftoff.prototype.requireLocal = function (moduleName, basedir) {
try {
var result = require(resolve.sync(module, { basedir: basedir }));
this.emit('require', module, result);
this.emit('preload:before', moduleName);
var result = require(resolve.sync(moduleName, { basedir: basedir }));
this.emit('preload:success', moduleName, result);
return result;
} catch (e) {
this.emit('requireFail', module, e);
this.emit('preload:failure', moduleName, e);
}
};
Liftoff.prototype.buildEnvironment = function(opts) {
Liftoff.prototype.buildEnvironment = function (opts) {
opts = opts || {};
// get modules we want to preload
var preload = opts.require || [];
var preload = opts.preload || [];

@@ -57,2 +60,94 @@ // ensure items to preload is an array

var exts = this.extensions;
var eventEmitter = this;
function findAndRegisterLoader(pathObj, defaultObj) {
var found = fined(pathObj, defaultObj);
if (!found) {
return;
}
if (isPlainObject(found.extension)) {
registerLoader(eventEmitter, found.extension, found.path, cwd);
}
return found.path;
}
function getModulePath(cwd, xtends) {
// If relative, we need to use fined to look up the file. If not, assume a node_module
if (needsLookup(xtends)) {
var defaultObj = { cwd: cwd, extensions: exts };
// Using `xtends` like this should allow people to use a string or any object that fined accepts
var foundPath = findAndRegisterLoader(xtends, defaultObj);
if (!foundPath) {
var name;
if (typeof xtends === 'string') {
name = xtends;
} else {
name = xtends.path || xtends.name;
}
var msg = 'Unable to locate one of your extends.';
if (name) {
msg += ' Looking for file: ' + path.resolve(cwd, name);
}
throw new Error(msg);
}
return foundPath;
}
return xtends;
}
var visited = {};
function loadConfig(cwd, xtends, preferred) {
var configFilePath = getModulePath(cwd, xtends);
if (visited[configFilePath]) {
throw new Error(
'We encountered a circular extend for file: ' +
configFilePath +
'. Please remove the recursive extends.'
);
}
var configFile;
try {
configFile = require(configFilePath);
} catch (e) {
// TODO: Consider surfacing the `require` error
throw new Error(
'Encountered error when loading config file: ' + configFilePath
);
}
visited[configFilePath] = true;
if (configFile && configFile.extends) {
var nextCwd = path.dirname(configFilePath);
return loadConfig(nextCwd, configFile.extends, configFile);
}
// Always extend into an empty object so we can call `delete` on `config.extends`
var config = extend(true /* deep */, {}, configFile, preferred);
delete config.extends;
return config;
}
var configFiles = {};
if (isPlainObject(this.configFiles)) {
configFiles = mapValues(this.configFiles, function (searchPaths, fileStem) {
var defaultObj = { name: fileStem, cwd: cwd, extensions: exts };
var foundPath = arrayFind(searchPaths, function (pathObj) {
return findAndRegisterLoader(pathObj, defaultObj);
});
return foundPath;
});
}
var config = mapValues(configFiles, function (startingLocation) {
var defaultConfig = {};
if (!startingLocation) {
return defaultConfig;
}
return loadConfig(cwd, startingLocation, defaultConfig);
});
// if cwd was provided explicitly, only use it for searching config

@@ -91,8 +186,11 @@ if (opts.cwd) {

// locate local module and package next to config or explicitly provided cwd
/* eslint one-var: 0 */
var modulePath, modulePackage;
var modulePath;
var modulePackage;
try {
var delim = path.delimiter;
var paths = (process.env.NODE_PATH ? process.env.NODE_PATH.split(delim) : []);
modulePath = resolve.sync(this.moduleName, { basedir: configBase || cwd, paths: paths });
var paths = process.env.NODE_PATH ? process.env.NODE_PATH.split(delim) : [];
modulePath = resolve.sync(this.moduleName, {
basedir: configBase || cwd,
paths: paths,
});
modulePackage = silentRequire(fileSearch('package.json', [modulePath]));

@@ -110,3 +208,6 @@ } catch (e) {}

// if it does, our module path is `main` inside package.json
modulePath = path.join(path.dirname(modulePackagePath), modulePackage.main || 'index.js');
modulePath = path.join(
path.dirname(modulePackagePath),
modulePackage.main || 'index.js'
);
cwd = configBase;

@@ -119,23 +220,6 @@ } else {

var exts = this.extensions;
var eventEmitter = this;
var configFiles = {};
if (isPlainObject(this.configFiles)) {
var notfound = { path: null };
configFiles = mapValues(this.configFiles, function(prop, name) {
var defaultObj = { name: name, cwd: cwd, extensions: exts };
return mapValues(prop, function(pathObj) {
var found = fined(pathObj, defaultObj) || notfound;
if (isPlainObject(found.extension)) {
registerLoader(eventEmitter, found.extension, found.path, cwd);
}
return found.path;
});
});
}
return {
cwd: cwd,
require: preload,
preload: preload,
completion: opts.completion,
configNameSearch: configNameSearch,

@@ -147,8 +231,9 @@ configPath: configPath,

configFiles: configFiles,
config: config,
};
};
Liftoff.prototype.handleFlags = function(cb) {
Liftoff.prototype.handleFlags = function (cb) {
if (typeof this.v8flags === 'function') {
this.v8flags(function(err, flags) {
this.v8flags(function (err, flags) {
if (err) {

@@ -161,9 +246,11 @@ cb(err);

} else {
process.nextTick(function() {
cb(null, this.v8flags);
}.bind(this));
process.nextTick(
function () {
cb(null, this.v8flags);
}.bind(this)
);
}
};
Liftoff.prototype.prepare = function(opts, fn) {
Liftoff.prototype.prepare = function (opts, fn) {
if (typeof fn !== 'function') {

@@ -175,7 +262,2 @@ throw new Error('You must provide a callback function.');

var completion = opts.completion;
if (completion && this.completions) {
return this.completions(completion);
}
var env = this.buildEnvironment(opts);

@@ -186,3 +268,8 @@

Liftoff.prototype.execute = function(env, forcedFlags, fn) {
Liftoff.prototype.execute = function (env, forcedFlags, fn) {
var completion = env.completion;
if (completion && this.completions) {
return this.completions(completion);
}
if (typeof forcedFlags === 'function') {

@@ -196,40 +283,29 @@ fn = forcedFlags;

this.handleFlags(function(err, flags) {
if (err) {
throw err;
}
flags = flags || [];
this.handleFlags(
function (err, flags) {
if (err) {
throw err;
}
flags = flags || [];
flaggedRespawn(flags, process.argv, forcedFlags, execute.bind(this));
flaggedRespawn(flags, process.argv, forcedFlags, execute.bind(this));
function execute(ready, child, argv) {
if (child !== process) {
var execArgv = getNodeFlags.fromReorderedArgv(argv);
this.emit('respawn', execArgv, child);
function execute(ready, child, argv) {
if (child !== process) {
var execArgv = getNodeFlags.fromReorderedArgv(argv);
this.emit('respawn', execArgv, child);
}
if (ready) {
preloadModules(this, env);
registerLoader(this, this.extensions, env.configPath, env.cwd);
fn.call(this, env, argv);
}
}
if (ready) {
preloadModules(this, env);
registerLoader(this, this.extensions, env.configPath, env.cwd);
fn.call(this, env, argv);
}
}
}.bind(this));
}.bind(this)
);
};
Liftoff.prototype.launch = function(opts, fn) {
if (typeof fn !== 'function') {
throw new Error('You must provide a callback function.');
}
var self = this;
self.prepare(opts, function(env) {
var forcedFlags = getNodeFlags.arrayOrFunction(opts.forcedFlags, env);
self.execute(env, forcedFlags, fn);
});
};
function preloadModules(inst, env) {
var basedir = env.cwd;
env.require.filter(toUnique).forEach(function(module) {
env.preload.filter(toUnique).forEach(function (module) {
inst.requireLocal(module, basedir);

@@ -236,0 +312,0 @@ });

4

lib/build_config_name.js

@@ -1,2 +0,2 @@

module.exports = function(opts) {
module.exports = function (opts) {
opts = opts || {};

@@ -14,5 +14,5 @@ var configName = opts.configName;

}
return extensions.map(function(ext) {
return extensions.map(function (ext) {
return configName + ext;
});
};

2

lib/file_search.js
var findup = require('findup-sync');
module.exports = function(search, paths) {
module.exports = function (search, paths) {
var path;

@@ -5,0 +5,0 @@ var len = paths.length;

6

lib/find_config.js

@@ -5,3 +5,3 @@ var fs = require('fs');

module.exports = function(opts) {
module.exports = function (opts) {
opts = opts || {};

@@ -14,3 +14,5 @@ var configNameSearch = opts.configNameSearch;

if (!Array.isArray(searchPaths)) {
throw new Error('Please provide an array of paths to search for config in.');
throw new Error(
'Please provide an array of paths to search for config in.'
);
}

@@ -17,0 +19,0 @@ if (!configNameSearch) {

2

lib/find_cwd.js
var path = require('path');
module.exports = function(opts) {
module.exports = function (opts) {
if (!opts) {

@@ -5,0 +5,0 @@ opts = {};

1

lib/get_node_flags.js

@@ -30,2 +30,1 @@ function arrayOrFunction(arrayOrFunc, env) {

};

2

lib/parse_options.js
var extend = require('extend');
module.exports = function(opts) {
module.exports = function (opts) {
var defaults = {

@@ -5,0 +5,0 @@ extensions: {

14

lib/register_loader.js
var rechoir = require('rechoir');
module.exports = function(eventEmitter, extensions, configPath, cwd) {
module.exports = function (eventEmitter, extensions, configPath, cwd) {
extensions = extensions || {};

@@ -11,5 +11,6 @@

var autoloads = rechoir.prepare(extensions, configPath, cwd, true);
if (autoloads instanceof Error) { // Only errors
autoloads.failures.forEach(function(failed) {
eventEmitter.emit('requireFail', failed.moduleName, failed.error);
if (autoloads instanceof Error) {
// Only errors
autoloads.failures.forEach(function (failed) {
eventEmitter.emit('loader:failure', failed.moduleName, failed.error);
});

@@ -19,3 +20,4 @@ return;

if (!Array.isArray(autoloads)) { // Already required or no config.
if (!Array.isArray(autoloads)) {
// Already required or no config.
return;

@@ -25,3 +27,3 @@ }

var succeeded = autoloads[autoloads.length - 1];
eventEmitter.emit('require', succeeded.moduleName, succeeded.module);
eventEmitter.emit('loader:success', succeeded.moduleName, succeeded.module);
};

2

lib/silent_require.js

@@ -1,2 +0,2 @@

module.exports = function(path) {
module.exports = function (path) {
try {

@@ -3,0 +3,0 @@ return require(path);

62

package.json
{
"name": "liftoff",
"version": "3.1.0",
"version": "4.0.0",
"description": "Launch your command line tool with ease.",
"author": "Tyler Kellen (http://goingslowly.com/)",
"contributors": [],
"repository": "js-cli/js-liftoff",
"author": "Gulp Team <team@gulpjs.com> (https://gulpjs.com/)",
"contributors": [
"Blaine Bublitz <blaine.bublitz@gmail.com> (https://github.com/phated)",
"Tyler Kellen <tyler@sleekcode.net> (https://github.com/tkellen)",
"Takayuki Sato (https://github.com/sttk)"
],
"repository": "gulpjs/liftoff",
"license": "MIT",
"engines": {
"node": ">= 0.8"
"node": ">=10.13.0"
},

@@ -19,26 +23,36 @@ "main": "index.js",

"scripts": {
"pretest": "eslint .",
"test": "mocha -t 5000 -b -R spec test/index && npm run legacy-test",
"legacy-test": "mocha -t 5000 -b -R spec test/launch",
"cover": "nyc --reporter=lcov --reporter=text-summary npm test"
"lint": "eslint .",
"pretest": "npm run lint",
"test": "nyc mocha --async-only"
},
"dependencies": {
"extend": "^3.0.0",
"findup-sync": "^3.0.0",
"fined": "^1.0.1",
"flagged-respawn": "^1.0.0",
"is-plain-object": "^2.0.4",
"object.map": "^1.0.0",
"rechoir": "^0.6.2",
"resolve": "^1.1.7"
"extend": "^3.0.2",
"findup-sync": "^5.0.0",
"fined": "^2.0.0",
"flagged-respawn": "^2.0.0",
"is-plain-object": "^5.0.0",
"object.map": "^1.0.1",
"rechoir": "^0.8.0",
"resolve": "^1.20.0"
},
"devDependencies": {
"chai": "^3.5.0",
"coffeescript": "^1.10.0",
"eslint": "^2.13.1",
"eslint-config-gulp": "^3.0.1",
"mocha": "^3.5.3",
"nyc": "^13.3.0",
"sinon": "~1.17.4"
"coffeescript": "^2.6.1",
"eslint": "^7.0.0",
"eslint-config-gulp": "^5.0.0",
"eslint-config-prettier": "^6.11.0",
"eslint-plugin-node": "^11.1.0",
"expect": "^27.0.0",
"mocha": "^8.0.0",
"nyc": "^15.0.0",
"sinon": "^11.0.0"
},
"nyc": {
"reporter": [
"lcov",
"text-summary"
]
},
"prettier": {
"singleQuote": true
},
"keywords": [

@@ -45,0 +59,0 @@ "command line"

413

README.md

@@ -7,26 +7,29 @@ <p align="center">

# liftoff [![Build Status](http://img.shields.io/travis/js-cli/js-liftoff.svg?label=travis-ci)](http://travis-ci.org/js-cli/js-liftoff) [![Build status](https://img.shields.io/appveyor/ci/phated/js-liftoff.svg?label=appveyor)](https://ci.appveyor.com/project/phated/js-liftoff)
<p align="center">
<a href="http://gulpjs.com">
<img height="257" width="114" src="https://raw.githubusercontent.com/gulpjs/artwork/master/gulp-2x.png">
</a>
</p>
# liftoff
> Launch your command line tool with ease.
[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][ci-image]][ci-url] [![Coveralls Status][coveralls-image]][coveralls-url]
[![NPM](https://nodei.co/npm/liftoff.png)](https://nodei.co/npm/liftoff/)
Launch your command line tool with ease.
## What is it?
[See this blog post](http://weblog.bocoup.com/building-command-line-tools-in-node-with-liftoff/), [check out this proof of concept](https://github.com/js-cli/js-hacker), or read on.
Say you're writing a CLI tool. Let's call it [hacker](https://github.com/js-cli/js-hacker). You want to configure it using a `Hackerfile`. This is node, so you install `hacker` locally for each project you use it in. But, in order to get the `hacker` command in your PATH, you also install it globally.
[See this blog post][liftoff-blog], [check out this proof of concept][hacker], or read on.
Now, when you run `hacker`, you want to configure what it does using the `Hackerfile` in your current directory, and you want it to execute using the local installation of your tool. Also, it'd be nice if the `hacker` command was smart enough to traverse up your folders until it finds a `Hackerfile`&mdash;for those times when you're not in the root directory of your project. Heck, you might even want to launch `hacker` from a folder outside of your project by manually specifying a working directory. Liftoff manages this for you.
Say you're writing a CLI tool. Let's call it [hacker]. You want to configure it using a `Hackerfile`. This is node, so you install `hacker` locally for each project you use it in. But, in order to get the `hacker` command in your PATH, you also install it globally.
So, everything is working great. Now you can find your local `hacker` and `Hackerfile` with ease. Unfortunately, it turns out you've authored your `Hackerfile` in coffee-script, or some other JS variant. In order to support *that*, you have to load the compiler for it, and then register the extension for it with node. Good news, Liftoff can do that, and a whole lot more, too.
Now, when you run `hacker`, you want to configure what it does using the `Hackerfile` in your current directory, and you want it to execute using the local installation of your tool. Also, it'd be nice if the `hacker` command was smart enough to traverse up your folders until it finds a `Hackerfile`&mdash;for those times when you're not in the root directory of your project. Heck, you might even want to launch `hacker` from a folder outside of your project by manually specifying a working directory. Liftoff manages this for you.
## API
So, everything is working great. Now you can find your local `hacker` and `Hackerfile` with ease. Unfortunately, it turns out you've authored your `Hackerfile` in coffee-script, or some other JS variant. In order to support _that_, you have to load the compiler for it, and then register the extension for it with node. Good news, Liftoff can do that, and a whole lot more, too.
### constructor(opts)
## Usage
Create an instance of Liftoff to invoke your application.
```js
const Liftoff = require('liftoff');
An example utilizing all options:
```js
const Hacker = new Liftoff({

@@ -40,8 +43,20 @@ name: 'hacker',

'.json': null,
'.coffee': 'coffee-script/register'
'.coffee': 'coffee-script/register',
},
v8flags: ['--harmony'] // or v8flags: require('v8flags')
v8flags: ['--harmony'], // or v8flags: require('v8flags')
});
Hacker.prepare({}, function (env) {
Hacker.execute(env, function (env) {
// Do post-execute things
});
});
```
## API
### constructor(opts)
Create an instance of Liftoff to invoke your application.
#### opts.name

@@ -51,6 +66,8 @@

Type: `String`
Type: `String`
Default: `null`
These are equivalent:
```js

@@ -60,14 +77,12 @@ const Hacker = Liftoff({

moduleName: 'hacker',
configName: 'hackerfile'
configName: 'hackerfile',
});
```
```js
const Hacker = Liftoff({name:'hacker'});
const Hacker = Liftoff({ name: 'hacker' });
```
#### opts.moduleName
Type: `String`
Sets which module your application expects to find locally when being run.
Type: `String`
Default: `null`

@@ -77,5 +92,6 @@

Sets the name of the configuration file Liftoff will attempt to find. Case-insensitive.
Sets the name of the configuration file Liftoff will attempt to find. Case-insensitive.
Type: `String`
Type: `String`
Default: `null`

@@ -85,5 +101,6 @@

Set extensions to include when searching for a configuration file. If an external module is needed to load a given extension (e.g. `.coffee`), the module name should be specified as the value for the key.
Set extensions to include when searching for a configuration file. If an external module is needed to load a given extension (e.g. `.coffee`), the module name should be specified as the value for the key.
Type: `Object`
Type: `Object`
Default: `{".js":null,".json":null}`

@@ -93,3 +110,4 @@

In this example Liftoff will look for `myappfile{.js,.json,.coffee}`. If a config with the extension `.coffee` is found, Liftoff will try to require `coffee-script/require` from the current working directory.
In this example Liftoff will look for `myappfile{.js,.json,.coffee}`. If a config with the extension `.coffee` is found, Liftoff will try to require `coffee-script/require` from the current working directory.
```js

@@ -101,4 +119,4 @@ const MyApp = new Liftoff({

'.json': null,
'.coffee': 'coffee-script/register'
}
'.coffee': 'coffee-script/register',
},
});

@@ -108,2 +126,3 @@ ```

In this example, Liftoff will look for `.myapp{rc}`.
```js

@@ -114,8 +133,8 @@ const MyApp = new Liftoff({

extensions: {
'rc': null
}
rc: null,
},
});
```
In this example, Liftoff will automatically attempt to load the correct module for any javascript variant supported by [interpret](https://github.com/js-cli/js-interpret) (as long as it does not require a register method).
In this example, Liftoff will automatically attempt to load the correct module for any javascript variant supported by [interpret] (as long as it does not require a register method).

@@ -125,10 +144,12 @@ ```js

name: 'myapp',
extensions: require('interpret').jsVariants
extensions: require('interpret').jsVariants,
});
```
#### opts.v8flags
Any flag specified here will be applied to node, not your program. Useful for supporting invocations like `myapp --harmony command`, where `--harmony` should be passed to node, not your program. This functionality is implemented using [flagged-respawn](http://github.com/js-cli/js-flagged-respawn). To support all v8flags, see [v8flags](https://github.com/js-cli/js-v8flags).
Any flag specified here will be applied to node, not your program. Useful for supporting invocations like `myapp --harmony command`, where `--harmony` should be passed to node, not your program. This functionality is implemented using [flagged-respawn]. To support all v8flags, see [v8flags].
Type: `Array|Function`
Type: `Array` or `Function`
Default: `null`

@@ -140,5 +161,6 @@

Sets what the [process title](http://nodejs.org/api/process.html#process_process_title) will be.
Sets what the [process title][process-title] will be.
Type: `String`
Type: `String`
Default: `null`

@@ -150,3 +172,4 @@

Type: `Function`
Type: `Function`
Default: `null`

@@ -158,5 +181,6 @@

__Note:__ This option is useful if, for example, you want to support an `.apprc` file in addition to an `appfile.js`. If you only need a single configuration file, you probably don't need this. In addition to letting you find multiple files, this option allows more fine-grained control over how configuration files are located.
**Note:** This option is useful if, for example, you want to support an `.apprc` file in addition to an `appfile.js`. If you only need a single configuration file, you probably don't need this. In addition to letting you find multiple files, this option allows more fine-grained control over how configuration files are located.
Type: `Object`
Type: `Object`
Default: `null`

@@ -166,37 +190,41 @@

The [`fined`](https://github.com/js-cli/fined) module accepts a string representing the path to search or an object with the following keys:
The [`fined`][fined] module accepts a string representing the path to search or an object with the following keys:
* `path` __(required)__
- `path` **(required)**
The path to search. Using only a string expands to this property.
Type: `String`
Type: `String`
Default: `null`
* `name`
- `name`
The basename of the file to find. Extensions are appended during lookup.
Type: `String`
Type: `String`
Default: Top-level key in `configFiles`
* `extensions`
- `extensions`
The extensions to append to `name` during lookup. See also: [`opts.extensions`](#optsextensions).
Type: `String|Array|Object`
Type: `String` or `Array` or `Object`
Default: The value of [`opts.extensions`](#optsextensions)
* `cwd`
- `cwd`
The base directory of `path` (if relative).
Type: `String`
Type: `String`
Default: The value of [`opts.cwd`](#optscwd)
* `findUp`
- `findUp`
Whether the `path` should be traversed up to find the file.
Type: `Boolean`
Type: `Boolean`
Default: `false`

@@ -207,2 +235,3 @@

In this example Liftoff will look for the `.hacker.js` file relative to the `cwd` as declared in `configFiles`.
```js

@@ -213,5 +242,5 @@ const MyApp = new Liftoff({

'.hacker': {
cwd: '.'
}
}
cwd: '.',
},
},
});

@@ -221,2 +250,3 @@ ```

In this example, Liftoff will look for `.hackerrc` in the home directory.
```js

@@ -230,7 +260,7 @@ const MyApp = new Liftoff({

extensions: {
'rc': null
}
}
}
}
rc: null,
},
},
},
},
});

@@ -240,2 +270,3 @@ ```

In this example, Liftoff will look in the `cwd` and then lookup the tree for the `.hacker.js` file.
```js

@@ -248,6 +279,6 @@ const MyApp = new Liftoff({

path: '.',
findUp: true
}
}
}
findUp: true,
},
},
},
});

@@ -257,2 +288,3 @@ ```

In this example, the `name` is overridden and the key is ignored so Liftoff looks for `.override.js`.
```js

@@ -265,6 +297,6 @@ const MyApp = new Liftoff({

path: '.',
name: '.override'
}
}
}
name: '.override',
},
},
},
});

@@ -274,2 +306,3 @@ ```

In this example, Liftoff will use the home directory as the `cwd` and looks for `~/.hacker.js`.
```js

@@ -282,6 +315,6 @@ const MyApp = new Liftoff({

path: '.',
cwd: '~'
}
}
}
cwd: '~',
},
},
},
});

@@ -292,3 +325,3 @@ ```

Prepares the environment for your application with provided options, and invokes your callback with the calculated environment as the first argument. The environment can be modified before using it as the first argument to `execute`.
Prepares the environment for your application with provided options, and invokes your callback with the calculated environment as the first argument. The environment can be modified before using it as the first argument to `execute`.

@@ -299,3 +332,3 @@ **Example Configuration w/ Options Parsing:**

const Liftoff = require('liftoff');
const MyApp = new Liftoff({name:'myapp'});
const MyApp = new Liftoff({ name: 'myapp' });
const argv = require('minimist')(process.argv.slice(2));

@@ -310,8 +343,11 @@ const onExecute = function (env, argv) {

};
MyApp.prepare({
cwd: argv.cwd,
configPath: argv.myappfile,
require: argv.require,
completion: argv.completion
}, onPrepare);
MyApp.prepare(
{
cwd: argv.cwd,
configPath: argv.myappfile,
preload: argv.preload,
completion: argv.completion,
},
onPrepare
);
```

@@ -327,5 +363,5 @@

'.hacker': {
home: { path: '.', cwd: '~' }
}
}
home: { path: '.', cwd: '~' },
},
},
});

@@ -336,9 +372,12 @@ const onExecute = function (env, argv) {

const onPrepare = function (env) {
env.configProps = ['home', 'cwd'].map(function(dirname) {
return env.configFiles['.hacker'][dirname]
}).filter(function(filePath) {
return Boolean(filePath);
}).reduce(function(config, filePath) {
return mergeDeep(config, require(filePath));
}, {});
env.configProps = ['home', 'cwd']
.map(function (dirname) {
return env.configFiles['.hacker'][dirname];
})
.filter(function (filePath) {
return Boolean(filePath);
})
.reduce(function (config, filePath) {
return mergeDeep(config, require(filePath));
}, {});

@@ -357,16 +396,24 @@ if (env.configProps.hackerfile) {

Change the current working directory for this launch. Relative paths are calculated against `process.cwd()`.
Change the current working directory for this execution. Relative paths are calculated against `process.cwd()`.
Type: `String`
Type: `String`
Default: `process.cwd()`
**Example Configuration:**
```js
const argv = require('minimist')(process.argv.slice(2));
MyApp.launch({
cwd: argv.cwd
}, invoke);
MyApp.prepare(
{
cwd: argv.cwd,
},
function (env) {
MyApp.execute(env, invoke);
}
);
```
**Matching CLI Invocation:**
```

@@ -380,15 +427,23 @@ myapp --cwd ../

Type: `String`
Type: `String`
Default: `null`
**Example Configuration:**
```js
var argv = require('minimist')(process.argv.slice(2));
MyApp.launch({
configPath: argv.myappfile
}, invoke);
MyApp.prepare(
{
configPath: argv.myappfile,
},
function (env) {
MyApp.execute(env, invoke);
}
);
```
**Matching CLI Invocation:**
```
```sh
myapp --myappfile /var/www/project/Myappfile.js

@@ -400,3 +455,4 @@ ```

These are functionally identical:
```
```sh
myapp --myappfile /var/www/project/Myappfile.js

@@ -407,3 +463,4 @@ myapp --cwd /var/www/project

These can run myapp from a shared directory as though it were located in another project:
```
```sh
myapp --myappfile /Users/name/Myappfile.js --cwd /var/www/project1

@@ -413,20 +470,27 @@ myapp --myappfile /Users/name/Myappfile.js --cwd /var/www/project2

#### opts.require
#### opts.preload
A string or array of modules to attempt requiring from the local working directory before invoking the launch callback.
A string or array of modules to attempt requiring from the local working directory before invoking the execute callback.
Type: `String|Array`
Type: `String|Array`
Default: `null`
**Example Configuration:**
```js
var argv = require('minimist')(process.argv.slice(2));
MyApp.launch({
require: argv.require
}, invoke);
MyApp.prepare(
{
preload: argv.preload,
},
function (env) {
MyApp.execute(env, invoke);
}
);
```
**Matching CLI Invocation:**
```js
myapp --require coffee-script/register
```sh
myapp --preload coffee-script/register
```

@@ -436,6 +500,6 @@

A function called after your environment is prepared. A good place to modify the environment before calling `execute`. When invoked, `this` will be your instance of Liftoff. The `env` param will contain the following keys:
A function called after your environment is prepared. A good place to modify the environment before calling `execute`. When invoked, `this` will be your instance of Liftoff. The `env` param will contain the following keys:
- `cwd`: the current working directory
- `require`: an array of modules that liftoff tried to pre-load
- `preload`: an array of modules that liftoff tried to pre-load
- `configNameSearch`: the config files searched for

@@ -450,3 +514,3 @@ - `configPath`: the full path to your configuration file (if found)

A function to start your application, based on the `env` given. Optionally takes an array of `forcedFlags`, which will force a respawn with those node or V8 flags during startup. Invokes your callback with the environment and command-line arguments (minus node & v8 flags) after the application has been executed.
A function to start your application, based on the `env` given. Optionally takes an array of `forcedFlags`, which will force a respawn with those node or V8 flags during startup. Invokes your callback with the environment and command-line arguments (minus node & v8 flags) after the application has been executed.

@@ -457,3 +521,3 @@ **Example:**

const Liftoff = require('liftoff');
const MyApp = new Liftoff({name:'myapp'});
const MyApp = new Liftoff({ name: 'myapp' });
const onExecute = function (env, argv) {

@@ -474,6 +538,6 @@ // Do post-execute things

A function called after your application is executed. When invoked, `this` will be your instance of Liftoff, `argv` will be all command-line arguments (minus node & v8 flags), and `env` will contain the following keys:
A function called after your application is executed. When invoked, `this` will be your instance of Liftoff, `argv` will be all command-line arguments (minus node & v8 flags), and `env` will contain the following keys:
- `cwd`: the current working directory
- `require`: an array of modules that liftoff tried to pre-load
- `preload`: an array of modules that liftoff tried to pre-load
- `configNameSearch`: the config files searched for

@@ -486,57 +550,69 @@ - `configPath`: the full path to your configuration file (if found)

### launch(opts, callback(env, argv))
### events
**Deprecated:** Please use `prepare` followed by `execute`. That's all this module does internally but those give you more control.
#### `on('preload:before', function(name) {})`
Launches your application with provided options, builds an environment, and invokes your callback, passing the calculated environment and command-line arguments (minus node & v8 flags) as the arguments.
Emitted before a module is pre-load. (But for only a module which is specified by `opts.preload`.)
Accepts any options that `prepare` allows, plus `opt.forcedFlags`.
```js
var Hacker = new Liftoff({ name: 'hacker', preload: 'coffee-script' });
Hacker.on('preload:before', function (name) {
console.log('Requiring external module: ' + name + '...');
});
```
#### opts.forcedFlags
#### `on('preload:success', function(name, module) {})`
**Deprecated:** If using `prepare`/`execute`, pass forcedFlags as the 2nd argument instead of using this option.
Emitted when a module has been pre-loaded.
Allows you to force node or V8 flags during the launch. This is useful if you need to make sure certain flags will always be enabled or if you need to enable flags that don't show up in `opts.v8flags` (as these flags aren't validated against `opts.v8flags`).
```js
var Hacker = new Liftoff({ name: 'hacker' });
Hacker.on('preload:success', function (name, module) {
console.log('Required external module: ' + name + '...');
// automatically register coffee-script extensions
if (name === 'coffee-script') {
module.register();
}
});
```
If this is specified as a function, it will receive the built `env` as its only argument and must return a string or array of flags to force.
#### `on('preload:failure', function(name, err) {})`
Type: `String|Array|Function`
Default: `null`
Emitted when a requested module cannot be preloaded.
**Example Configuration:**
```js
MyApp.launch({
forcedFlags: ['--trace-deprecation']
}, invoke);
var Hacker = new Liftoff({ name: 'hacker' });
Hacker.on('preload:failure', function (name, err) {
console.log('Unable to load:', name, err);
});
```
**Matching CLI Invocation:**
```js
myapp --trace-deprecation
```
#### `on('loader:success, function(name, module) {})`
### events
Emitted when a loader that matches an extension has been loaded.
#### require(name, module)
Emitted when a module is pre-loaded.
```js
var Hacker = new Liftoff({name:'hacker'});
Hacker.on('require', function (name, module) {
console.log('Requiring external module: '+name+'...');
// automatically register coffee-script extensions
if (name === 'coffee-script') {
module.register();
}
var Hacker = new Liftoff({
name: 'hacker',
extensions: {
'.ts': 'ts-node/register',
},
});
Hacker.on('loader:success', function (name, module) {
console.log('Required external module: ' + name + '...');
});
```
#### requireFail(name, err)
#### `on('loader:failure', function(name, err) {})`
Emitted when a requested module cannot be preloaded.
Emitted when no loader for an extension can be loaded. Emits an error for each failed loader.
```js
var Hacker = new Liftoff({name:'hacker'});
Hacker.on('requireFail', function (name, err) {
var Hacker = new Liftoff({
name: 'hacker',
extensions: {
'.ts': 'ts-node/register',
},
});
Hacker.on('loader:failure', function (name, err) {
console.log('Unable to load:', name, err);

@@ -546,3 +622,3 @@ });

#### respawn(flags, child)
#### `on('respawn', function(flags, child) {})`

@@ -554,3 +630,3 @@ Emitted when Liftoff re-spawns your process (when a [`v8flags`](#optsv8flags) is detected).

name: 'hacker',
v8flags: ['--harmony']
v8flags: ['--harmony'],
});

@@ -568,5 +644,5 @@ Hacker.on('respawn', function (flags, child) {

Check out how [gulp](https://github.com/gulpjs/gulp-cli/blob/master/index.js) uses Liftoff.
Check out how [gulp][gulp-cli-index] uses Liftoff.
For a bare-bones example, try [the hacker project](https://github.com/js-cli/js-hacker/blob/master/bin/hacker.js).
For a bare-bones example, try [the hacker project][hacker-index].

@@ -578,2 +654,33 @@ To try the example, do the following:

3. Install hacker next to it with `npm install hacker`.
3. Run `hacker` while in the same parent folder.
4. Run `hacker` while in the same parent folder.
## License
MIT
<!-- prettier-ignore-start -->
[downloads-image]: https://img.shields.io/npm/dm/liftoff.svg?style=flat-square
[npm-url]: https://www.npmjs.com/package/liftoff
[npm-image]: https://img.shields.io/npm/v/liftoff.svg?style=flat-square
[ci-url]: https://github.com/gulpjs/liftoff/actions?query=workflow:dev
[ci-image]: https://img.shields.io/github/workflow/status/gulpjs/liftoff/dev?style=flat-square
[coveralls-url]: https://coveralls.io/r/gulpjs/liftoff
[coveralls-image]: https://img.shields.io/coveralls/gulpjs/liftoff/master.svg?style=flat-square
<!-- prettier-ignore-end -->
<!-- prettier-ignore-start -->
[liftoff-blog]: https://bocoup.com/blog/building-command-line-tools-in-node-with-liftoff
[hacker]: https://github.com/gulpjs/hacker
[interpret]: https://github.com/gulpjs/interpret
[flagged-respawn]: http://github.com/gulpjs/flagged-respawn
[v8flags]: https://github.com/gulpjs/v8flags
[fined]: https://github.com/gulpjs/fined
[process-title]: http://nodejs.org/api/process.html#process_process_title
[gulp-cli-index]: https://github.com/gulpjs/gulp-cli/blob/master/index.js
[hacker-index]: https://github.com/gulpjs/js-hacker/blob/master/bin/hacker.js
<!-- prettier-ignore-end -->
CHANGELOG
LICENSE

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc