Remove .explainSync().. Rewrite project as an ES Module

Replace collect-all with stream-read-all

Author: 75lb

.github/workflows/node.js.yml

@@ -26,4 +26,5 @@ jobs:
         node-version: ${{ matrix.node-version }}
         cache: 'npm'
     - run: npm install
+    - run: npm i -g @75lb/nature@^0.1.1
     - run: npm test

.gitignore

@@ -45,8 +45,6 @@ A programmatic interface for [jsdoc3](https://github.com/jsdoc3/jsdoc) with a fe
 
 * [jsdoc-api](#module_jsdoc-api)
     * _static_
-        * [.cache](#module_jsdoc-api.cache) : [<code>cache-point</code>](https://github.com/75lb/cache-point)
-        * [.explainSync([options])](#module_jsdoc-api.explainSync) ⇒ <code>Array.&lt;object&gt;</code>
         * [.explain([options])](#module_jsdoc-api.explain) ⇒ <code>Promise</code>
         * [.renderSync([options])](#module_jsdoc-api.renderSync)
     * _inner_
@@ -66,24 +64,7 @@ A programmatic interface for [jsdoc3](https://github.com/jsdoc3/jsdoc) with a fe
             * [.readme](#module_jsdoc-api..JsdocOptions+readme) : <code>string</code>
             * [.template](#module_jsdoc-api..JsdocOptions+template) : <code>string</code>
             * [.tutorials](#module_jsdoc-api..JsdocOptions+tutorials) : <code>string</code>
-
-<a name="module_jsdoc-api.cache"></a>
-
-### jsdoc.cache : [<code>cache-point</code>](https://github.com/75lb/cache-point)
-The [cache-point](https://github.com/75lb/cache-point) instance used when `cache: true` is specified on `.explain()` or `.explainSync()`.
-
-**Kind**: static property of [<code>jsdoc-api</code>](#module_jsdoc-api)  
-<a name="module_jsdoc-api.explainSync"></a>
-
-### jsdoc.explainSync([options]) ⇒ <code>Array.&lt;object&gt;</code>
-Returns jsdoc explain output.
-
-**Kind**: static method of [<code>jsdoc-api</code>](#module_jsdoc-api)  
-**Prerequisite**: Requires node v0.12 or above  
-
-| Param | Type |
-| --- | --- |
-| [options] | [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions) | 
+        * [~cache](#module_jsdoc-api..cache) : [<code>cache-point</code>](https://github.com/75lb/cache-point)
 
 <a name="module_jsdoc-api.explain"></a>
 
@@ -227,6 +208,12 @@ The path to the template to use. Default: path/to/jsdoc/templates/default.
 Directory in which JSDoc should search for tutorials.
 
 **Kind**: instance property of [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions)  
+<a name="module_jsdoc-api..cache"></a>
+
+### jsdoc-api~cache : [<code>cache-point</code>](https://github.com/75lb/cache-point)
+The [cache-point](https://github.com/75lb/cache-point) instance used when `cache: true` is specified on `.explain()` or `.explainSync()`.
+
+**Kind**: inner constant of [<code>jsdoc-api</code>](#module_jsdoc-api)  
 
 * * *
 

README.md

@@ -2,23 +2,23 @@
  * @module jsdoc-api
  * @typicalname jsdoc
  */
-const path = require('path')
-const Cache = require('cache-point')
+import path from 'path'
+import Cache from 'cache-point'
+import Explain from './lib/explain.js'
+import RenderSync from './lib/render-sync.js'
+import arrayify from 'array-back'
+import os from 'node:os'
 
 /**
- * Returns jsdoc explain output.
- *
- * @param [options] {module:jsdoc-api~JsdocOptions}
- * @returns {object[]}
- * @static
- * @prerequisite Requires node v0.12 or above
+ * @external cache-point
+ * @see https://github.com/75lb/cache-point
  */
-function explainSync (options) {
-  options = new JsdocOptions(options)
-  const ExplainSync = require('./lib/explain-sync')
-  const command = new ExplainSync(options, exports.cache)
-  return command.execute()
-}
+
+/**
+  * The [cache-point](https://github.com/75lb/cache-point) instance used when `cache: true` is specified on `.explain()` or `.explainSync()`.
+  * @type {external:cache-point}
+  */
+const cache = new Cache({ dir: path.join(os.tmpdir(), 'jsdoc-api') })
 
 /**
  * Returns a promise for the jsdoc explain output.
@@ -28,10 +28,9 @@ function explainSync (options) {
  * @returns {Promise}
  * @static
  */
-function explain (options) {
+async function explain (options) {
   options = new JsdocOptions(options)
-  const Explain = require('./lib/explain')
-  const command = new Explain(options, exports.cache)
+  const command = new Explain(options, cache)
   return command.execute()
 }
 
@@ -46,7 +45,6 @@ function explain (options) {
  */
 function renderSync (options) {
   options = new JsdocOptions(options)
-  const RenderSync = require('./lib/render-sync')
   const command = new RenderSync(options)
   return command.execute()
 }
@@ -58,7 +56,6 @@ function renderSync (options) {
 class JsdocOptions {
   constructor (options) {
     options = options || {}
-    const arrayify = require('array-back')
 
     /**
      * One or more filenames to process. Either this or `source` must be supplied.
@@ -153,16 +150,4 @@ class JsdocOptions {
   }
 }
 
-/**
- * @external cache-point
- * @see https://github.com/75lb/cache-point
- */
-
- exports.explainSync = explainSync
- exports.explain = explain
- exports.renderSync = renderSync
- /**
-  * The [cache-point](https://github.com/75lb/cache-point) instance used when `cache: true` is specified on `.explain()` or `.explainSync()`.
-  * @type {external:cache-point}
-  */
- exports.cache = new Cache({ dir: path.join(require('os').tmpdir(), 'jsdoc-api') })
+export { explain, renderSync, cache }

index.js

@@ -1,4 +1,7 @@
-const JsdocCommand = require('./jsdoc-command')
+import JsdocCommand from './jsdoc-command.js'
+import streamReadAll from 'stream-read-all'
+import toSpawnArgs from 'object-to-spawn-args'
+import { spawn } from 'child_process'
 
 /**
  * @module explain
@@ -18,27 +21,21 @@ class Explain extends JsdocCommand {
     }
   }
 
-  _runJsdoc () {
-    return new Promise((resolve, reject) => {
-      const collectAll = require('collect-all')
+  async _runJsdoc () {
+    return new Promise(async (resolve, reject) => {
       const jsdocOutput = {
         stdout: '',
-        stderr: '',
-        collectInto (dest) {
-          return collectAll(data => { this[dest] = data.toString() })
-        }
+        stderr: ''
       }
 
-      const toSpawnArgs = require('object-to-spawn-args')
       const jsdocArgs = toSpawnArgs(this.jsdocOptions)
-        .concat([ '-X' ])
+        .concat(['-X'])
         .concat(this.options.source ? this.tempFile.path : this.inputFileSet.files)
       jsdocArgs.unshift(this.jsdocPath)
 
-      const spawn = require('child_process').spawn
       const handle = spawn('node', jsdocArgs)
-      handle.stderr.pipe(jsdocOutput.collectInto('stderr'))
-      handle.stdout.pipe(jsdocOutput.collectInto('stdout'))
+      jsdocOutput.stdout = (await streamReadAll(handle.stdout)).toString()
+      jsdocOutput.stderr = (await streamReadAll(handle.stderr)).toString()
 
       handle.on('close', code => {
         try {
@@ -56,4 +53,4 @@ class Explain extends JsdocCommand {
   }
 }
 
-module.exports = Explain
+export default Explain

lib/explain-sync.js

@@ -1,5 +1,13 @@
-const arrayify = require('array-back')
-const path = require('path')
+import arrayify from 'array-back'
+import path from 'path'
+import TempFile from './temp-file.js'
+import FileSet from 'file-set'
+import assert from 'assert'
+import walkBack from 'walk-back'
+import { promises as fs } from 'node:fs'
+import currentModulePaths from 'current-module-paths'
+
+const { __dirname } = currentModulePaths(import.meta.url)
 
 /**
  * @module jsdoc-command
@@ -16,7 +24,6 @@ class JsdocCommand {
 
     this.cache = cache
     this.tempFile = null
-    const TempFile = require('./temp-file')
     if (options.source) this.tempFile = new TempFile(options.source)
 
     const jsdocOptions = Object.assign({}, options)
@@ -27,7 +34,6 @@ class JsdocCommand {
     this.options = options
     this.jsdocOptions = jsdocOptions
 
-    const walkBack = require('walk-back')
     this.jsdocPath = walkBack(
       path.join(__dirname, '..'),
       path.join('node_modules', 'jsdoc', 'jsdoc.js')
@@ -67,7 +73,6 @@ class JsdocCommand {
    * Perform pre-execution processing here, e.g. expand input glob patterns.
    */
   preExecute () {
-    const FileSet = require('file-set')
     this.inputFileSet = new FileSet(this.options.files)
   }
 
@@ -76,7 +81,6 @@ class JsdocCommand {
    * @returns {null|Error}
    */
   validate () {
-    const assert = require('assert')
     assert.ok(
       this.options.files.length || this.options.source,
       'Must set either .files or .source'
@@ -118,7 +122,6 @@ class JsdocCommand {
    */
   async readCache () {
     if (this.cache) {
-      const fs = require('fs').promises
       const promises = this.inputFileSet.files.map(file => fs.readFile(file, 'utf8'))
       const contents = await Promise.all(promises)
       this.cacheKey = contents.concat(this.inputFileSet.files)
@@ -127,15 +130,6 @@ class JsdocCommand {
       return Promise.reject()
     }
   }
-
-  readCacheSync () {
-    if (this.cache) {
-      const fs = require('fs')
-      const contents = this.inputFileSet.files.map(file => fs.readFileSync(file, 'utf8'))
-      this.cacheKey = contents.concat(this.inputFileSet.files)
-      return this.cache.readSync(this.cacheKey)
-    }
-  }
 }
 
-module.exports = JsdocCommand
+export default JsdocCommand

lib/explain.js

@@ -1,20 +1,19 @@
-const JsdocCommand = require('./jsdoc-command')
+import JsdocCommand from './jsdoc-command.js'
+import toSpawnArgs from 'object-to-spawn-args'
+import { spawnSync } from 'child_process'
 
 /**
  * @static
  */
 class RenderSync extends JsdocCommand {
   getOutput (err) {
     if (err) throw err
-    const toSpawnArgs = require('object-to-spawn-args')
     const jsdocArgs = toSpawnArgs(this.jsdocOptions)
       .concat(this.options.source ? this.tempFile.path : this.options.files)
 
     jsdocArgs.unshift(this.jsdocPath)
-
-    const spawnSync = require('child_process').spawnSync
     spawnSync('node', jsdocArgs)
   }
 }
 
-module.exports = RenderSync
+export default RenderSync

lib/jsdoc-command.js

@@ -1,14 +1,15 @@
-const fs = require('fs')
-const os = require('os')
-const crypto = require('crypto')
-const path = require('path')
+import fs from 'fs'
+import os from 'os'
+import crypto from 'crypto'
+import path from 'path'
 
 class TempFile {
   constructor (source) {
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jsdoc-api-'))
     this.path = path.join(tempDir, crypto.randomBytes(6).toString('hex') + '.js')
     fs.writeFileSync(this.path, source)
   }
+
   delete () {
     try {
       fs.unlinkSync(this.path)
@@ -18,4 +19,4 @@ class TempFile {
   }
 }
 
-module.exports = TempFile
+export default TempFile