You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by ra...@apache.org on 2018/08/14 12:37:34 UTC
[cordova-fetch] branch master updated: Improve and update docs (#42)
This is an automated email from the ASF dual-hosted git repository.
raphinesse pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cordova-fetch.git
The following commit(s) were added to refs/heads/master by this push:
new db08270 Improve and update docs (#42)
db08270 is described below
commit db08270ee11cdffc8890eb8dcf73bfda87ba0c5a
Author: Raphael von der Grün <ra...@gmail.com>
AuthorDate: Tue Aug 14 14:37:31 2018 +0200
Improve and update docs (#42)
* Improve docs and bring them up to date with the latest changes.
* Moves badges into headline.
Note that there are more supported options than documented. As they've not been documented before, they are considered private for now.
---
README.md | 75 +++++++++++++++++++++++++++++++++++++++++++++------------------
index.js | 34 ++++++++++++++---------------
2 files changed, 71 insertions(+), 38 deletions(-)
diff --git a/README.md b/README.md
index 253ea86..4ccee34 100644
--- a/README.md
+++ b/README.md
@@ -19,36 +19,69 @@
#
-->
-[](https://ci.appveyor.com/project/ApacheSoftwareFoundation/cordova-fetch/branch/master)
-[](https://travis-ci.org/apache/cordova-fetch)
[](https://nodei.co/npm/cordova-fetch/)
-# cordova-fetch
+# cordova-fetch [![Travis Badge]][Travis] [![AppVeyor Badge]][AppVeyor]
-This module is used for fetching modules from npm and gitURLs. It fetches the modules via `npm install`. It can also `npm uninstall` modules from a project.
+This package can be used to install and uninstall Node.js packages using npm.
-## Usage:
+## Usage
-### Fetching:
-```
-var fetch = require('cordova-fetch');
+### `fetch`
-fetch(spec, dest, opts);
-```
+Installs a module from npm, a git url or the local file system. Returns a `Promise` resolving to the absolute path to the installed package.
-`spec` can be a string containg a npm `packageID` or a `git URL`.
-`dest` is string of the directory location you wish to `npm install` these modules.
-`opts` is an Object of options cordova fetch handles. Currently, fetch only support the `save` option.
- eg. `{'save':true}`
+```js
+const fetch = require('cordova-fetch');
-### Removing:
+fetch(spec, dest, opts).then(pathToInstalledPackage => {
+ // Do something
+});
```
-var npmUninstall = require('cordova-fetch').uninstall;
-npmUninstall(spec, dest, opts);
+#### Parameters
+
+Parameter | Description
+-|-
+`spec` | A spec for the package to be installed (anything supported by `npm install`)
+`dest` | Location where to install the package
+`opts` | Additional options (optional)
+
+##### Options
+
+Option | Default | Description
+-|-|-
+`save` | `false` | Adds the package as dependency to `package.json` iff `true`
+
+### `uninstall`
+
+Uninstalls a package from given directory. Returns a `Promise` that resolves when removal has finished
+
+```js
+const { uninstall } = require('cordova-fetch');
+
+uninstall(packageName, dest, opts).then(() => {
+ // Do something
+});
```
-`spec` can be a string containg a npm `packageID`.
-`dest` is string of the directory location you wish to `npm uninstall` these modules.
-`opts` is an Object of options cordova fetch handles. Currently, fetch only support the `save` option.
- eg. `{'save':true}`
+#### Parameters
+
+Parameter | Description
+-|-
+`packageName` | Name of the package to be uninstalled
+`dest` | Location from where to uninstall the package
+`opts` | An Object with additional options
+
+##### Options
+
+Option | Default | Description
+-|-|-
+`save` | `false` | Removes dependency from `package.json` iff `true`
+
+
+[Travis Badge]: https://travis-ci.org/apache/cordova-fetch.svg?branch=master
+[Travis]: https://travis-ci.org/apache/cordova-fetch
+
+[AppVeyor Badge]: https://ci.appveyor.com/api/projects/status/6xv212nihtcnbsov?svg=true
+[AppVeyor]: https://ci.appveyor.com/project/ApacheSoftwareFoundation/cordova-fetch/branch/master
diff --git a/index.js b/index.js
index 5eb0831..da9f658 100644
--- a/index.js
+++ b/index.js
@@ -26,15 +26,15 @@ const { getInstalledPath } = require('get-installed-path');
const npa = require('npm-package-arg');
const semver = require('semver');
-/*
- * A function that npm installs a module from npm or a git url
- *
- * @param {String} target the packageID or git url
- * @param {String} dest destination of where to install the module
- * @param {Object} opts [opts={save:true}] options to pass to fetch module
+/**
+ * Installs a module from npm, a git url or the local file system.
*
- * @return {String|Promise} Returns string of the absolute path to the installed module.
+ * @param {String} target A spec for the package to be installed
+ * (anything supported by `npm install`)
+ * @param {String} dest Location where to install the package
+ * @param {Object} [opts={}] Additional options
*
+ * @return {Promise<string>} Absolute path to the installed package
*/
module.exports = function (target, dest, opts = {}) {
return Q()
@@ -111,11 +111,11 @@ function pathToInstalledPackage (spec, dest) {
});
}
-/*
+/**
* Checks to see if npm is installed on the users system
- * @return {Promise|Error} Returns true or a cordova error.
+ *
+ * @return {Promise<string>} Absolute path to npm.
*/
-
function isNpmInstalled () {
return which('npm').catch(_ => {
throw new CordovaError('"npm" command line tool is not installed: make sure it is accessible on your PATH.');
@@ -123,15 +123,15 @@ function isNpmInstalled () {
}
module.exports.isNpmInstalled = isNpmInstalled;
-/*
- * A function that deletes the target from node_modules and runs npm uninstall
- *
- * @param {String} target the packageID
- * @param {String} dest destination of where to uninstall the module from
- * @param {Object} opts [opts={save:true}] options to pass to npm uninstall
+
+/**
+ * Uninstalls the package `target` from `dest` using given options.
*
- * @return {Promise|Error} Returns a promise with the npm uninstall output or an error.
+ * @param {String} target Name of the package to be uninstalled
+ * @param {String} dest Location from where to uninstall the package
+ * @param {Object} [opts={}] Additional options
*
+ * @return {Promise<string>} Resolves when removal has finished
*/
module.exports.uninstall = function (target, dest, opts) {
var fetchArgs = ['uninstall'];
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org