replace renderSync with render (async)

some refactoring

Author: 75lb

index.js

@@ -5,7 +5,7 @@
 import path from 'path'
 import Cache from 'cache-point'
 import Explain from './lib/explain.js'
-import RenderSync from './lib/render-sync.js'
+import Render from './lib/render.js'
 import arrayify from 'array-back'
 import os from 'node:os'
 
@@ -41,11 +41,11 @@ async function explain (options) {
  * @prerequisite Requires node v0.12 or above
  * @static
  * @example
- * jsdoc.renderSync({ files: 'lib/*', destination: 'api-docs' })
+ * await jsdoc.render({ files: 'lib/*', destination: 'api-docs' })
  */
-function renderSync (options) {
+async function render (options) {
   options = new JsdocOptions(options)
-  const command = new RenderSync(options)
+  const command = new Render(options)
   return command.execute()
 }
 
@@ -150,4 +150,4 @@ class JsdocOptions {
   }
 }
 
-export { explain, renderSync, cache }
+export { explain, render, cache }

lib/explain.js

@@ -12,8 +12,7 @@ import { spawn } from 'child_process'
  * @static
  */
 class Explain extends JsdocCommand {
-  getOutput (err) {
-    if (err) return Promise.reject(err)
+  async getOutput () {
     if (this.options.cache && !this.options.source) {
       return this.readCache().catch(this._runJsdoc.bind(this))
     } else {
@@ -33,6 +32,7 @@ class Explain extends JsdocCommand {
         .concat(this.options.source ? this.tempFile.path : this.inputFileSet.files)
       jsdocArgs.unshift(this.jsdocPath)
 
+      /* TODO: replace with exec if you're only collecting the output */
       const handle = spawn('node', jsdocArgs)
       jsdocOutput.stdout = (await streamReadAll(handle.stdout)).toString()
       jsdocOutput.stderr = (await streamReadAll(handle.stderr)).toString()
@@ -51,6 +51,41 @@ class Explain extends JsdocCommand {
       })
     })
   }
+
+  verifyOutput (code, output) {
+    let parseFailed = false
+    let parsedOutput
+    try {
+      parsedOutput = JSON.parse(output.stdout)
+    } catch (err) {
+      parseFailed = true
+    }
+
+    if (code > 0 || parseFailed) {
+      const firstLineOfStdout = output.stdout.split(/\r?\n/)[0]
+      const err = new Error(output.stderr.trim() || firstLineOfStdout || 'Jsdoc failed.')
+      err.name = 'JSDOC_ERROR'
+      throw err
+    } else {
+      return parsedOutput
+    }
+  }
+
+  /**
+   * Returns a cached recordset
+   * @returns {Promise}
+   * @fulfil {object[]}
+   */
+  async readCache () {
+    if (this.cache) {
+      const promises = this.inputFileSet.files.map(file => fs.readFile(file, 'utf8'))
+      const contents = await Promise.all(promises)
+      this.cacheKey = contents.concat(this.inputFileSet.files)
+      return this.cache.read(this.cacheKey)
+    } else {
+      return Promise.reject()
+    }
+  }
 }
 
 export default Explain

lib/jsdoc-command.js

@@ -40,95 +40,21 @@ class JsdocCommand {
     )
   }
 
-  /**
-   * Template method returning the jsdoc output. Invoke later (for example via a command-queuing system) or immediately as required.
-   *
-   * 1. preExecute
-   * 2. validate
-   * 3. getOutput
-   * 4. postExecute
-   *
-   */
-  execute () {
-    this.preExecute()
-    const err = this.validate()
-    this.output = this.getOutput(err)
-    if (this.output instanceof Promise) {
-      return this.output
-        .then(result => {
-          this.postExecute()
-          return result
-        })
-        .catch(err => {
-          this.postExecute()
-          throw err
-        })
-    } else {
-      this.postExecute()
-      return this.output
-    }
-  }
-
-  /**
-   * Perform pre-execution processing here, e.g. expand input glob patterns.
-   */
-  preExecute () {
+  async execute () {
     this.inputFileSet = new FileSet(this.options.files)
-  }
-
-  /**
-   * Return an Error instance if execution should not proceed.
-   * @returns {null|Error}
-   */
-  validate () {
     assert.ok(
       this.options.files.length || this.options.source,
       'Must set either .files or .source'
     )
-  }
-
-  /**
-   * perform post-execution cleanup
-   */
-  postExecute () {
-    if (this.tempFile) {
-      this.tempFile.delete()
-    }
-  }
-
-  verifyOutput (code, output) {
-    let parseFailed = false
-    let parsedOutput
+    let result
     try {
-      parsedOutput = JSON.parse(output.stdout)
-    } catch (err) {
-      parseFailed = true
-    }
-
-    if (code > 0 || parseFailed) {
-      const firstLineOfStdout = output.stdout.split(/\r?\n/)[0]
-      const err = new Error(output.stderr.trim() || firstLineOfStdout || 'Jsdoc failed.')
-      err.name = 'JSDOC_ERROR'
-      throw err
-    } else {
-      return parsedOutput
-    }
-  }
-
-  /**
-   * Returns a cached recordset
-   * @returns {Promise}
-   * @fulfil {object[]}
-   */
-  async readCache () {
-    if (this.cache) {
-      const promises = this.inputFileSet.files.map(file => fs.readFile(file, 'utf8'))
-      const contents = await Promise.all(promises)
-      this.cacheKey = contents.concat(this.inputFileSet.files)
-      return this.cache.read(this.cacheKey)
-    } else {
-      return Promise.reject()
+      result = await this.getOutput()
+    } finally {
+      if (this.tempFile) {
+        this.tempFile.delete()
+      }
     }
+    return result
   }
 }
 

lib/render-sync.js

@@ -0,0 +1,21 @@
+import JsdocCommand from './jsdoc-command.js'
+import toSpawnArgs from 'object-to-spawn-args'
+import { spawn } from 'child_process'
+
+/**
+ * @static
+ */
+class Render extends JsdocCommand {
+  async getOutput () {
+    return new Promise((resolve, reject) => {
+      const jsdocArgs = toSpawnArgs(this.jsdocOptions)
+        .concat(this.options.source ? this.tempFile.path : this.options.files)
+
+      jsdocArgs.unshift(this.jsdocPath)
+      const handle = spawn('node', jsdocArgs, { stdio: 'inherit' })
+      handle.on('close', resolve)
+    })
+  }
+}
+
+export default Render

lib/render.js

@@ -25,7 +25,7 @@
     "node": ">=12.17"
   },
   "scripts": {
-    "test": "75lb-nature test test/*.js",
+    "test": "75lb-nature test-runner test/*.js",
     "docs": "75lb-nature jsdoc2md -t jsdoc2md/README.hbs index.js lib/*.js > README.md; echo"
   },
   "dependencies": {

package.json

@@ -41,4 +41,8 @@ test.set('.explain({ files }): generate a warning', async function () {
   return jsdoc.explain({ files: 'test/fixture/buggy/ignore-with-value.js' })
 })
 
+test.set('.explain({ files }): files is empty', async function () {
+  return jsdoc.explain({ files: [] })
+})
+
 export { test, only, skip }

test/explain.js

@@ -0,0 +1,28 @@
+import * as jsdoc from 'jsdoc-api'
+import Fixture from './lib/fixture.js'
+import { statSync } from 'fs'
+import { strict as a } from 'assert'
+
+const [test, only, skip] = [new Map(), new Map(), new Map()]
+
+test.set('.render({ files })', async function () {
+  Fixture.createTmpFolder('tmp')
+  Fixture.createTmpFolder('tmp/render')
+  const f = new Fixture('class-all')
+  await jsdoc.render({ files: f.sourcePath, destination: 'tmp/render/out' })
+  a.doesNotThrow(function () {
+    statSync('./tmp/render/out/index.html')
+  })
+})
+
+test.set('.render({ source, destination })', async function () {
+  Fixture.createTmpFolder('tmp')
+  Fixture.createTmpFolder('tmp/render')
+  const f = new Fixture('class-all')
+  await jsdoc.render({ source: f.getSource(), destination: 'tmp/render/out' })
+  a.doesNotThrow(function () {
+    statSync('./tmp/render/out/index.html')
+  })
+})
+
+export { test, only, skip }