Merge pull request #1 from Skelp/develop

Release 0.1.0

Author: neocotic

README.md

@@ -7,10 +7,8 @@
     888       888  888 Y88b.   Y88b  d88P Y88b.    888  888 888  888
     888       "Y888888  "Y8888P "Y8888P"   "Y8888P "Y888888 888  888
 
-[PacScan](https://github.com/Skelp/node-pacscan) provide information about all available packages for your module at
-runtime.
-
-> This library is very much still in early development! Watch this space.
+[PacScan](https://github.com/Skelp/node-pacscan) provides information about all available packages for your module at
+runtime by scanning `node_modules` as opposed to digging into dependency trees.
 
 [![Build](https://img.shields.io/travis/Skelp/node-pacscan/develop.svg?style=flat-square)](https://travis-ci.org/Skelp/node-pacscan)
 [![Coverage](https://img.shields.io/coveralls/Skelp/node-pacscan/develop.svg?style=flat-square)](https://coveralls.io/github/Skelp/node-pacscan)
@@ -37,11 +35,65 @@ You'll need to have at least [Node.js](https://nodejs.org) 4 or newer.
 
 ### `pacscan([options])`
 
-TODO: Document
+Scans for all packages available to your module asynchronously, returning a `Promise` to retrieve all of the package
+information, each of which will be in a format similar to the following:
+
+``` javascript
+{
+  // The directory of the package
+  directory: '/path/to/my-example-package/node_modules/example-server',
+  // The file path of the "main" file for the package or null if it has none
+  main: '/path/to/my-example-package/node_modules/example-server/server.js',
+  // The name of the package
+  name: 'example-server',
+  // The version of the package
+  version: '3.2.1'
+}
+```
+
+The `options` parameter is entirely optional and supports the following:
+
+| Option           | Description                                                                                                                               | Default Value |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `includeParents` | Whether the highest level package directory should be scanned or only the lowest level base directory.                                      | `false` |
+| `knockknock`     | Any options to be passed to [KnockKnock](https://github.com/Skelp/node-knockknock). `limit` will always be overridden to `1`.               | `null`  |
+| `path`           | The file/directory path from where to derive the base directory to be scanned. Path to module that called PacScan will be used when `null`. | `null`  |
+
+If you only want to list the packages available to your module/package:
+
+``` javascript
+const pacscan = require('pacscan')
+
+module.exports = function() {
+  pacscan()
+    .then((packages) => {
+      console.log(`${packages.length} packages found`)
+
+      // ...
+    })
+}
+```
+
+However, if you're calling PacScan from within a library that is most likely being included in another package as a
+dependency. In these cases, you might want to know all of the packages available in the base package (i.e. the highest
+level package that is not a dependency itself). All that you need to do for this is to enable the `includeParents`
+option.
 
 ### `pacscan.sync([options])`
 
-TODO: Document
+A synchronous alternative to `pacscan([options])`.
+
+``` javascript
+const pacscan = require('pacscan')
+
+module.exports = function() {
+  const packages = pacscan.sync()
+
+  console.log(`${packages.length} packages found`)
+
+  // ...
+}
+```
 
 ### `pacscan.version`
 
@@ -51,7 +103,7 @@ The current version of PacScan.
 const pacscan = require('pacscan')
 
 pacscan.version
-=> "0.1.0alpha"
+=> "0.1.0"
 ```
 
 ## Bugs

package.json

@@ -1,6 +1,6 @@
 {
   "name": "pacscan",
-  "version": "0.1.0alpha",
+  "version": "0.1.0",
   "description": "Scans for available packages",
   "homepage": "https://github.com/Skelp/node-pacscan",
   "bugs": {
@@ -23,6 +23,8 @@
   },
   "dependencies": {
     "debug": "*",
+    "glob": "^7.1.1",
+    "knockknock": "^0.2.0",
     "pkg-dir": "^1.0.0"
   },
   "devDependencies": {
@@ -31,15 +33,17 @@
     "eslint": "^3.16.0",
     "eslint-config-skelp": "^0.1.5",
     "istanbul": "^0.4.5",
-    "mocha": "^3.2.0"
+    "mkdirp": "^0.5.1",
+    "mocha": "^3.2.0",
+    "ncp": "^2.0.0",
+    "tmp": "^0.0.31"
   },
   "main": "src/pacscan.js",
   "scripts": {
     "report-coverage": "istanbul cover _mocha --report lcovonly -- -R spec \"test/**/*.spec.js\" && coveralls < coverage/lcov.info",
-    "test": "npm run test-lint && npm run test-suite && npm run test-coverage",
-    "test-coverage": "istanbul check-coverage",
-    "test-lint": "eslint \"src/**/*.js\" \"test/**/*.js\"",
-    "test-suite": "istanbul cover _mocha -- -R spec \"test/**/*.spec.js\""
+    "pretest": "eslint \"src/**/*.js\" \"test/**/*.js\"",
+    "test": "istanbul cover _mocha -- -R spec \"test/**/*.spec.js\"",
+    "posttest": "istanbul check-coverage"
   },
   "engines": {
     "node": ">=4"