jsdoc-api - npm Package Compare versions

Comparing version 0.1.1 to 0.2.0

es5/jsdoc-api.js

@@ -5,15 +5,19 @@ 'use strict';
 
+function _possibleConstructorReturn(self, call) { if (!self) { throw new ReferenceError("this hasn't been initialised - super() hasn't been called"); } return call && (typeof call === "object" || typeof call === "function") ? call : self; }
+
+function _inherits(subClass, superClass) { if (typeof superClass !== "function" && superClass !== null) { throw new TypeError("Super expression must either be null or a function, not " + typeof superClass); } subClass.prototype = Object.create(superClass && superClass.prototype, { constructor: { value: subClass, enumerable: false, writable: true, configurable: true } }); if (superClass) Object.setPrototypeOf ? Object.setPrototypeOf(subClass, superClass) : subClass.__proto__ = superClass; }
+
 function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }
 
+var Duplex = require('stream').Duplex;
+var path = require('path');
+var fs = require('fs');
 var walkBack = require('walk-back');
 var spawnSync = require('child_process').spawnSync;
 var spawn = require('child_process').spawn;
-var path = require('path');
-var fs = require('fs');
 var getTempPath = require('temp-path');
 var toSpawnArgs = require('object-to-spawn-args');
-var defer = require('defer-promise');
 var arrayify = require('array-back');
 var collectJson = require('collect-json');
-var Readable = require('stream').Readable;
+var collectAll = require('collect-all');
 
@@ -41,7 +45,36 @@ exports.explainSync = explainSync;
 
-function explain(files) {
+function explain(files, options) {
   return new Promise(function (resolve, reject) {
-    spawn(jsdocPath, ['-X'].concat(arrayify(files))).stdout.pipe(collectJson(function (data) {
-      resolve(data);
-    }));
+    var jsdocArgs = toSpawnArgs(options).concat(['-X']).concat(arrayify(files));
+    var output = {
+      stdout: '',
+      stderr: ''
+    };
+
+    var handle = spawn(jsdocPath, jsdocArgs);
+    handle.on('error', function (err) {
+      return reject(err);
+    }).stdout.pipe(collectJson(function (data) {
+      output.stdout = data;
+    })).on('error', function (err) {
+      if (/no input files/.test(err.message)) {
+        var invalidErr = new Error('Invalid input files [' + files + ']');
+        invalidErr.name = 'INVALID_FILES';
+        reject(invalidErr);
+      } else {
+        reject(err);
+      }
+    });
+    handle.stderr.pipe(collectAll(function (text) {
+      output.stderr = text;
+    })).on('error', function (err) {
+      return reject(err);
+    });
+    handle.on('close', function (code) {
+      if (code) {
+        reject(output.stderr);
+      } else {
+        resolve(output.stdout);
+      }
+    });
   });
@@ -53,3 +86,5 @@ }
   return new Promise(function (resolve, reject) {
-    spawn(jsdocPath, ['-X'].concat(tempFile.path)).stdout.pipe(collectJson(function (data) {
+    spawn(jsdocPath, ['-X'].concat(tempFile.path)).on('error', function (err) {
+      return reject(err);
+    }).stdout.pipe(collectJson(function (data) {
       resolve(data);
@@ -61,13 +96,4 @@ tempFile.delete();
 
-function createExplainStream(files) {
-  var stream = new Readable();
-  stream._read = function () {
-    var _this = this;
-
-    explain(files).then(function (output) {
-      _this.push(JSON.stringify(output, null, '  '));
-      _this.push(null);
-    });
-  };
-  return stream;
+function createExplainStream(files, options) {
+  return new ExplainStream(files, options);
 }
@@ -103,2 +129,63 @@
   return TempFile;
-})();
+})();
+
+var ExplainStream = (function (_Duplex) {
+  _inherits(ExplainStream, _Duplex);
+
+  function ExplainStream(options) {
+    _classCallCheck(this, ExplainStream);
+
+    var _this = _possibleConstructorReturn(this, Object.getPrototypeOf(ExplainStream).call(this));
+
+    options = options || {};
+    _this.files = arrayify(options.files);
+    delete options.files;
+    _this.options = options;
+
+    _this.on('pipe', function (src) {
+      if (!(_this.inProgress || options.files || options.source)) {
+        src.pipe(collectAll(function (source) {
+          explain.source(source, _this.options).then(function (output) {
+            _this.push(JSON.stringify(output, null, '  '));
+            _this.push(null);
+            _this.inProgress = false;
+          }).catch(function (err) {
+            return _this.emit('error', err);
+          });
+          _this.inProgress = true;
+        }));
+      }
+    });
+    return _this;
+  }
+
+  _createClass(ExplainStream, [{
+    key: 'start',
+    value: function start() {
+      var _this2 = this;
+
+      explain(this.files, this.options).then(function (output) {
+        _this2.push(JSON.stringify(output, null, '  '));
+        _this2.push(null);
+        _this2.inProgress = false;
+      }).catch(function (err) {
+        return _this2.emit('error', err);
+      });
+      this.inProgress = true;
+    }
+  }, {
+    key: '_read',
+    value: function _read() {
+      if (!this.inProgress && this.files.length) {
+        this.start();
+      }
+    }
+  }, {
+    key: '_write',
+    value: function _write(chunk, encoding, done) {
+      done();
+    }
+  }]);
+
+  return ExplainStream;
+})(Duplex);

lib/jsdoc-api.js

 'use strict'
+const Duplex = require('stream').Duplex
+const path = require('path')
+const fs = require('fs')
 const walkBack = require('walk-back')
 const spawnSync = require('child_process').spawnSync
 const spawn = require('child_process').spawn
-const path = require('path')
-const fs = require('fs')
 const getTempPath = require('temp-path')
 const toSpawnArgs = require('object-to-spawn-args')
-const defer = require('defer-promise')
 const arrayify = require('array-back')
 const collectJson = require('collect-json')
-const Readable = require('stream').Readable
+const collectAll = require('collect-all')
 
@@ -31,5 +31,7 @@ /**
 /**
+ * Returns jsdoc explain output
  * @param {string|string[]} - input file names
- * @returns {object} - jsdoc explain output
+ * @returns {object}
  * @static
+ * @node Requires version 0.12 and above
  */
@@ -40,9 +42,10 @@ function explainSync (files, options) {
   return JSON.parse(result.stdout)
-
 }
 
 /**
+ * Returns jsdoc explain output, taking source code as input.
  * @param {string} - source code
- * @returns {object[]} - jsdoc explain output
+ * @returns {object[]}
  * @static
+ * @node Requires version 0.12 and above
  */
@@ -59,12 +62,47 @@ explainSync.source = function explainSyncSource (source) {
  * @param {string|string[]} - input source files
+ * @param [options] {object}
+ * @param [options.configure]
  * @fulfil {object[]} - jsdoc explain output
  * @returns {Promise}
  * @static
+ * @throws `INVALID_FILES` - One or more files was not valid source code
  */
-function explain (files) {
+function explain (files, options) {
   return new Promise(function (resolve, reject) {
-    spawn(jsdocPath, [ '-X' ].concat(arrayify(files)))
-      .stdout.pipe(collectJson((data) => {
-        resolve(data)
+    const jsdocArgs = toSpawnArgs(options)
+      .concat([ '-X' ])
+      .concat(arrayify(files))
+    const output = {
+      stdout: '',
+      stderr: ''
+    }
+    // console.log(jsdocArgs)
+    const handle = spawn(jsdocPath, jsdocArgs)
+    handle
+      .on('error', err => reject(err))
+      .stdout.pipe(collectJson(data => {
+        output.stdout = data
       }))
+      .on('error', err => {
+        if (/no input files/.test(err.message)) {
+          const invalidErr = new Error(`Invalid input files [${files}]`)
+          invalidErr.name = 'INVALID_FILES'
+          reject(invalidErr)
+        } else {
+          reject(err)
+        }
+      })
+    handle
+      .stderr.pipe(collectAll(text => {
+        output.stderr = text
+      }))
+      .on('error', err => reject(err))
+    handle
+      .on('close', code => {
+        if (code) {
+          reject(output.stderr)
+        } else {
+          resolve(output.stdout)
+        }
+      })
   })
@@ -83,2 +121,3 @@ }
     spawn(jsdocPath, [ '-X' ].concat(tempFile.path))
+      .on('error', err => reject(err))
       .stdout.pipe(collectJson((data) => {
@@ -91,11 +130,11 @@ resolve(data)
 
-function createExplainStream (files) {
-  const stream = new Readable()
-  stream._read = function () {
-    explain(files).then(output => {
-      this.push(JSON.stringify(output, null, '  '))
-      this.push(null)
-    })
-  }
-  return stream
+/**
+ * @param {string|string[]} - input source files
+ * @param [options] {object}
+ * @param [options.configure]
+ * @returns {Readable}
+ * @static
+ */
+function createExplainStream (files, options) {
+  return new ExplainStream(files, options)
 }
@@ -136,1 +175,48 @@
 }
+
+class ExplainStream extends Duplex {
+  constructor (options) {
+    super()
+    options = options || {}
+    this.files = arrayify(options.files)
+    delete options.files
+    this.options = options
+
+    this.on('pipe', src => {
+      if (!(this.inProgress || options.files || options.source)) {
+        src.pipe(collectAll(source => {
+          explain.source(source, this.options)
+            .then(output => {
+              this.push(JSON.stringify(output, null, '  '))
+              this.push(null)
+              this.inProgress = false
+            })
+            .catch(err => this.emit('error', err))
+          this.inProgress = true
+        }))
+      }
+    })
+  }
+
+  start () {
+    explain(this.files, this.options)
+      .then(output => {
+        this.push(JSON.stringify(output, null, '  '))
+        this.push(null)
+        this.inProgress = false
+      })
+      .catch(err => this.emit('error', err))
+    this.inProgress = true
+  }
+
+  _read () {
+    if (!this.inProgress && this.files.length) {
+      this.start()
+    }
+  }
+
+  _write (chunk, encoding, done) {
+    done()
+  }
+
+}

package.json

 {
   "name": "jsdoc-api",
   "author": "Lloyd Brookes <[e-mail]>",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "A programmatic interface for jsdoc",
@@ -23,3 +23,4 @@ "repository": "https://github.com/75lb/jsdoc-api.git",
     "docs": "jsdoc2md -t jsdoc2md/README.hbs lib/*.js > README.md; echo",
-    "es5": "babel --presets babel-preset-es2015 --no-comments lib --out-dir es5"
+    "es5": "babel --presets babel-preset-es2015 --no-comments lib --out-dir es5",
+    "cover": "istanbul cover ./node_modules/.bin/tape test/*.js && cat coverage/lcov.info | ./node_modules/.bin/coveralls && rm -rf coverage; echo"
   },
@@ -29,2 +30,3 @@ "devDependencies": {
     "babel-preset-es2015": "^6.3.13",
+    "coveralls": "^2.11.6",
     "jsdoc-to-markdown": "^1.3.1",
@@ -36,5 +38,5 @@ "jsdoc2md-testbed": "~0.0.2",
   "dependencies": {
+    "collect-all": "~0.2.0",
     "collect-json": "^1.0.0",
     "command-line-args": "^2.1.3",
-    "defer-promise": "^0.1.1",
     "feature-detect-es6": "^1.2.0",
@@ -48,5 +50,6 @@ "jsdoc-75lb": "^3.5",
     "ignore": [
-      "es5"
+      "es5",
+      "tmp"
     ]
   }
 }

README.md

 [![view on npm](http://img.shields.io/npm/v/jsdoc-api.svg)](https://www.npmjs.org/package/jsdoc-api)
-[![npm module downloads per month](http://img.shields.io/npm/dm/jsdoc-api.svg)](https://www.npmjs.org/package/jsdoc-api)
+[![npm module downloads](http://img.shields.io/npm/dt/jsdoc-api.svg)](https://www.npmjs.org/package/jsdoc-api)
 [![Build Status](https://travis-ci.org/jsdoc2md/jsdoc-api.svg?branch=master)](https://travis-ci.org/jsdoc2md/jsdoc-api)
+[![Coverage Status](https://coveralls.io/repos/jsdoc2md/jsdoc-api/badge.svg?branch=master&service=github)](https://coveralls.io/github/jsdoc2md/jsdoc-api?branch=master)
 [![Dependency Status](https://david-dm.org/jsdoc2md/jsdoc-api.svg)](https://david-dm.org/jsdoc2md/jsdoc-api)
@@ -18,4 +19,5 @@ [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](https://github.com/feross/standard)
         * [.source(source)](#module_jsdoc-api.explainSync.source) ⇒ <code>Array.&lt;object&gt;</code>
-    * [.explain(files)](#module_jsdoc-api.explain) ⇒ <code>Promise</code>
+    * [.explain(files, [options])](#module_jsdoc-api.explain) ⇒ <code>Promise</code>
         * [.source(source)](#module_jsdoc-api.explain.source) ⇒ <code>Promise</code>
+    * [.createExplainStream(files, [options])](#module_jsdoc-api.createExplainStream) ⇒ <code>Readable</code>
     * [.renderSync(files, [options])](#module_jsdoc-api.renderSync)
@@ -26,4 +28,6 @@ * [.source(source, [options])](#module_jsdoc-api.renderSync.source)
 ### jsdoc.explainSync(files) ⇒ <code>object</code>
+Returns jsdoc explain output
+
 **Kind**: static method of <code>[jsdoc-api](#module_jsdoc-api)</code>  
-**Returns**: <code>object</code> - - jsdoc explain output  
+**Node**: Requires version 0.12 and above  
 
@@ -36,4 +40,6 @@ | Param | Type | Description |
 #### explainSync.source(source) ⇒ <code>Array.&lt;object&gt;</code>
+Returns jsdoc explain output, taking source code as input.
+
 **Kind**: static method of <code>[explainSync](#module_jsdoc-api.explainSync)</code>  
-**Returns**: <code>Array.&lt;object&gt;</code> - - jsdoc explain output  
+**Node**: Requires version 0.12 and above  
 
@@ -45,4 +51,8 @@ | Param | Type | Description |
 <a name="module_jsdoc-api.explain"></a>
-### jsdoc.explain(files) ⇒ <code>Promise</code>
+### jsdoc.explain(files, [options]) ⇒ <code>Promise</code>
 **Kind**: static method of <code>[jsdoc-api](#module_jsdoc-api)</code>  
+**Throws**:
+
+- `INVALID_FILES` - One or more files was not valid source code
+
 **Fulfil**: <code>object[]</code> - jsdoc explain output  
@@ -53,2 +63,4 @@
 | files | <code>string</code> &#124; <code>Array.&lt;string&gt;</code> | input source files |
+| [options] | <code>object</code> |  |
+| [options.configure] |  |  |
 
@@ -64,2 +76,12 @@ <a name="module_jsdoc-api.explain.source"></a>
 
+<a name="module_jsdoc-api.createExplainStream"></a>
+### jsdoc.createExplainStream(files, [options]) ⇒ <code>Readable</code>
+**Kind**: static method of <code>[jsdoc-api](#module_jsdoc-api)</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| files | <code>string</code> &#124; <code>Array.&lt;string&gt;</code> | input source files |
+| [options] | <code>object</code> |  |
+| [options.configure] |  |  |
+
 <a name="module_jsdoc-api.renderSync"></a>
@@ -66,0 +88,0 @@ ### jsdoc.renderSync(files, [options])

test/explain.js

@@ -44,3 +44,2 @@ var test = require('tape')
     .then(function (output) {
-      console.log(output)
       var expectedOutput = f.getExpectedOutput()
@@ -51,14 +50,1 @@ Fixture.removeFileSpecificData(output, expectedOutput)
 })
-
-test('.createExplainStream(files, options)', function (t) {
-  t.plan(1)
-  var f = new Fixture('global/class-all')
-  jsdoc.createExplainStream(f.sourcePath)
-    .pipe(collectJson(output => {
-      var expectedOutput = f.getExpectedOutput()
-      Fixture.removeFileSpecificData(output, expectedOutput)
-      t.deepEqual(output, expectedOutput)
-    }))
-})
-
-test('.createExplainStream.source(source, options)')

test/lib/fixture.js

@@ -20,2 +20,6 @@ var path = require('path')
 
+  this.createReadStream = function () {
+    return fs.createReadStream(this.sourcePath)
+  }
+
 }
@@ -22,0 +26,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1050461

increased by0.72%

Number of package files

41

increased by5.13%

Lines of code

1096

increased by20.97%

Number of lines in readme file

105

increased by26.51%

Worsened metrics

Dev dependency count

7

increased by16.67%

Dependency changes

• + Addedcollect-all@~0.2.0

• - Removeddefer-promise@^0.1.1

• - Removeddefer-promise@0.1.2(transitive)