docs(api): update api docs

tunnckoCore · Dec 13, 2016 · 6d05674 · 6d05674
1 parent f0fd0de
commit 6d05674
Show file tree

Hide file tree

Showing 3 changed files with 124 additions and 23 deletions.
diff --git a/.verb.md b/.verb.md
@@ -14,6 +14,16 @@
 ## Table of Contents
 <!-- toc -->
 
+## Background
+
+### Why
+
+TODO
+
+### Resolution
+
+TODO
+
 ## Install
 Install with [npm](https://www.npmjs.com/)
 

diff --git a/README.md b/README.md
@@ -12,9 +12,13 @@
 You might also be interested in [always-done](https://github.com/hybridables/always-done#readme).
 
 ## Table of Contents
+- [Background](#background)
+  * [Why](#why)
+  * [Resolution](#resolution)
 - [Install](#install)
 - [Usage](#usage)
 - [API](#api)
+  * [resolvePackage](#resolvepackage)
 - [Related](#related)
 - [Contributing](#contributing)
 - [Building docs](#building-docs)
@@ -24,6 +28,16 @@ You might also be interested in [always-done](https://github.com/hybridables/alw
 
 _(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_
 
+## Background
+
+### Why
+
+TODO
+
+### Resolution
+
+TODO
+
 ## Install
 Install with [npm](https://www.npmjs.com/)
 
@@ -46,6 +60,43 @@ const resolvePackage = require('resolve-package')
 
 ## API
 
+### [resolvePackage](index.js#L53)
+> Get full absolute path of package with `name` from local node_modules or from globally installed.
+
+**Params**
+
+* `name` **{String}**: package name    
+* `opts` **{Function}**: optional options such as below    
+* `opts.cwd` **{String}**: directory where is the `node_modules` folder    
+* `opts.mainFile` **{String}**: main file for directories, default `index.js`    
+* `opts.mainField` **{String}**: name of the package.json's "main" field, default `main`    
+* `returns` **{Promise}**  
+
+**Example**
+
+```js
+const resolvePackage = require('resolve-package')
+
+resolvePackage('npm').then((fp) => {
+  console.log(fp)
+  // => '~/.nvm/versions/node/v7.0.0/lib/node_modules/npm/lib/npm.js'
+})
+
+resolvePackage('standard').then((fp) => {
+  console.log(fp)
+  // => '~/.nvm/versions/node/v7.0.0/lib/node_modules/standard/index.js'
+})
+
+resolvePackage('get-installed-path').then((fp) => {
+  console.log(fp)
+  // => '~/code/resolve-package/node_modules/get-installed-path/index.js'
+})
+
+resolvePackage('foo-quqixs-dasdasdh').catch((err) => {
+  console.error(err) // => Error module not found
+})
+```
+
 ## Related
 - [always-done](https://www.npmjs.com/package/always-done): Handle completion and errors with elegance! Support for streams, callbacks, promises, child processes, async/await and sync functions. A drop-in replacement… [more](https://github.com/hybridables/always-done#readme) | [homepage](https://github.com/hybridables/always-done#readme "Handle completion and errors with elegance! Support for streams, callbacks, promises, child processes, async/await and sync functions. A drop-in replacement for [async-done][] - pass 100% of its tests plus more")
 - [minibase](https://www.npmjs.com/package/minibase): Minimalist alternative for Base. Build complex APIs with small units called plugins. Works well with most of the already existing… [more](https://github.com/node-minibase/minibase#readme) | [homepage](https://github.com/node-minibase/minibase#readme "Minimalist alternative for Base. Build complex APIs with small units called plugins. Works well with most of the already existing [base][] plugins.")
@@ -93,9 +144,20 @@ Copyright © 2016, [Charlike Mike Reagent](http://i.am.charlike.online). Release
 
 ***
 
-_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.2.0, on December 11, 2016._  
+_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.2.0, on December 13, 2016._  
 _Project scaffolded using [charlike][] cli._
 
+[always-done]: https://github.com/hybridables/always-done
+[async-done]: https://github.com/gulpjs/async-done
+[base]: https://github.com/node-base/base
+[charlike]: https://github.com/tunnckocore/charlike
+[commitizen]: https://github.com/commitizen/cz-cli
+[dezalgo]: https://github.com/npm/dezalgo
+[once]: https://github.com/isaacs/once
+[standard-version]: https://github.com/conventional-changelog/standard-version
+[verb-generate-readme]: https://github.com/verbose/verb-generate-readme
+[verb]: https://github.com/verbose/verb
+
 [downloads-url]: https://www.npmjs.com/package/resolve-package
 [downloads-img]: https://img.shields.io/npm/dt/resolve-package.svg
 
@@ -117,13 +179,3 @@ _Project scaffolded using [charlike][] cli._
 [standard-url]: https://github.com/feross/standard
 [standard-img]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg
 
-[always-done]: https://github.com/hybridables/always-done
-[async-done]: https://github.com/gulpjs/async-done
-[base]: https://github.com/node-base/base
-[charlike]: https://github.com/tunnckocore/charlike
-[commitizen]: https://github.com/commitizen/cz-cli
-[dezalgo]: https://github.com/npm/dezalgo
-[once]: https://github.com/isaacs/once
-[standard-version]: https://github.com/conventional-changelog/standard-version
-[verb-generate-readme]: https://github.com/verbose/verb-generate-readme
-[verb]: https://github.com/verbose/verb
diff --git a/index.js b/index.js
@@ -11,11 +11,52 @@ const fs = require('fs')
 const path = require('path')
 const get = require('get-installed-path')
 
-const readPackage = (fp) => new Promise((resolve, reject) => {
-  fs.readFile(path.resolve(fp, 'package.json'), 'utf8', (err, str) => {
-    if (err) return reject(err)
-    const json = JSON.parse(str)
-    resolve(json)
+/**
+ * > Get full absolute path of package with `name` from
+ * local node_modules or from globally installed.
+ *
+ * **Example**
+ *
+ * ```js
+ * const resolvePackage = require('resolve-package')
+ *
+ * resolvePackage('npm').then((fp) => {
+ *   console.log(fp)
+ *   // => '~/.nvm/versions/node/v7.0.0/lib/node_modules/npm/lib/npm.js'
+ * })
+ *
+ * resolvePackage('standard').then((fp) => {
+ *   console.log(fp)
+ *   // => '~/.nvm/versions/node/v7.0.0/lib/node_modules/standard/index.js'
+ * })
+ *
+ * resolvePackage('get-installed-path').then((fp) => {
+ *   console.log(fp)
+ *   // => '~/code/resolve-package/node_modules/get-installed-path/index.js'
+ * })
+ *
+ * resolvePackage('foo-quqixs-dasdasdh').catch((err) => {
+ *   console.error(err) // => Error module not found
+ * })
+ * ```
+ *
+ * @name   resolvePackage
+ * @param  {String}   `name` package name
+ * @param  {Function} `opts` optional options such as below
+ * @param  {String}   `opts.cwd` directory where is the `node_modules` folder
+ * @param  {String}   `opts.mainFile` main file for directories, default `index.js`
+ * @param  {String}   `opts.mainField` name of the package.json's "main" field, default `main`
+ * @return {Promise}
+ * @api public
+ */
+
+const resolvePackage = (name, opts) => new Promise((resolve, reject) => {
+  opts = opts && typeof opts === 'object' ? opts : {}
+  opts.local = true
+
+  get(name, opts).then(tryLoad(opts, resolve), (e) => {
+    opts.local = false
+    get(name, opts).then(tryLoad(opts, resolve), reject)
   })
 })
 
@@ -40,13 +81,11 @@ const tryLoad = (opts, resolve) => (fp) => {
   )
 }
 
-const resolvePackage = (name, opts) => new Promise((resolve, reject) => {
-  opts = opts && typeof opts === 'object' ? opts : {}
-  opts.local = true
-
-  get(name, opts).then(tryLoad(opts, resolve), (e) => {
-    opts.local = false
-    get(name, opts).then(tryLoad(opts, resolve), reject)
+const readPackage = (fp) => new Promise((resolve, reject) => {
+  fs.readFile(path.resolve(fp, 'package.json'), 'utf8', (err, str) => {
+    if (err) return reject(err)
+    const json = JSON.parse(str)
+    resolve(json)
   })
 })