minor refactor.. factor reduce-unique out of the project

bin/generate-partial-cache.js

@@ -8,7 +8,7 @@ const fileSet = new FileSet()
 async function start () {
   await fileSet.add('./partials/**/*.hbs')
   const map = new Map()
-  for (const file of fileSet.files) {
+  for (const file of fileSet.files.sort()) {
     map.set(
       path.basename(file, '.hbs'),
       fs.readFileSync(file, 'utf8') || ''

helpers/ddata.js

@@ -739,85 +739,51 @@ function parentName (options) {
 
 /**
 returns a dmd option, e.g. "sort-by", "heading-depth" etc.
-@static
 */
 function option (name, options) {
   return objectGet(options.data.root.options, name)
 }
 
-/**
-@static
-*/
 function optionEquals (name, value, options) {
   return options.data.root.options[name] === value
 }
 
-/**
-@static
-*/
 function optionSet (name, value, options) {
   options.data.root.options[name] = value
 }
 
-/**
-@static
-*/
 function optionIsSet (name, options) {
   return options.data.root.options[name] !== undefined
 }
 
-/**
-@static
-*/
 function stripNewlines (input) {
   if (input) return input.replace(/[\r\n]+/g, ' ')
 }
 
-/**
-@static
-*/
 function headingDepth (options) {
   return options.data.root.options._depth + (options.data.root.options['heading-depth'])
 }
 
-/**
-@static
-*/
 function depth (options) {
   return options.data.root.options._depth
 }
 
-/**
-@static
-*/
 function depthIncrement (options) {
   options.data.root.options._depth++
 }
 
-/**
-@static
-*/
 function depthDecrement (options) {
   options.data.root.options._depth--
 }
 
-/**
-@static
-*/
 function indexDepth (options) {
   return options.data.root.options._indexDepth
 }
 
-/**
-@static
-*/
 function indexDepthIncrement (options) {
   options.data.root.options._indexDepth++
 }
 
-/**
-@static
-*/
 function indexDepthDecrement (options) {
   options.data.root.options._indexDepth--
 }

helpers/helpers.js

@@ -3,11 +3,9 @@ const arrayify = require('array-back')
 const handlebars = require('handlebars')
 const util = require('util')
 const commonSequence = require('common-sequence')
-const unique = require('reduce-unique')
 
 /**
 A library of helpers used exclusively by dmd.. dmd also registers helpers from ddata.
-@module
 */
 exports.escape = escape
 exports.inlineLinks = inlineLinks
@@ -194,13 +192,13 @@ function _groupBy (identifiers, groupByFields) {
   groupByFields = groupByFields.slice(0)
 
   groupByFields.forEach(function (group) {
-    const groupValues = identifiers
+    let groupValues = identifiers
       .filter(function (identifier) {
         /* exclude constructors from grouping.. re-implement to work off a `null` group value */
         return identifier.kind !== 'constructor'
       })
       .map(function (i) { return i[group] })
-      .reduce(unique, [])
+    groupValues = Array.from(new Set(groupValues)) // unique
     if (groupValues.length <= 1) groupByFields = groupByFields.filter(g => g !== group)
   })
   identifiers = _addGroup(identifiers, groupByFields)

helpers/selectors.js

@@ -17,15 +17,13 @@ exports.misc = misc
 
 /**
  * render the supplied block for each identifier in the query
- * @static
  */
 function identifiers (options) {
   return handlebars.helpers.each(ddata._identifiers(options), options)
 }
 
 /**
  * render the supplied block for the specified identifier
- * @static
  */
 function identifier (options) {
   const result = ddata._identifier(options)
@@ -34,23 +32,20 @@ function identifier (options) {
 
 /**
  * render the supplied block for each parent (global identifier, or module)
- * @static
  */
 function orphans (options) {
   return handlebars.helpers.each(ddata._orphans(options), options)
 }
 
 /**
  * render the supplied block for each identifier in global scope
- * @static
  */
 function globals (options) {
   return handlebars.helpers.each(ddata._globals(options), options)
 }
 
 /**
  * render the supplied block for each module
- * @static
  */
 function modules (options) {
   options.hash.kind = 'module'
@@ -59,7 +54,6 @@ function modules (options) {
 
 /**
  * render the supplied block for the specified module
- * @static
  */
 function module (options) {
   options.hash.kind = 'module'
@@ -69,7 +63,6 @@ function module (options) {
 
 /**
  * render the block for each class
- * @static
  */
 function classes (options) {
   options.hash.kind = 'class'
@@ -87,7 +80,6 @@ function class_ (options) {
 
 /**
  * render the block for each function/method
- * @static
  */
 function functions (options) {
   options.hash.kind = 'function'
@@ -123,7 +115,6 @@ function enum_ (options) {
 
 /**
  * render the supplied block for each orphan with no scope set
- * @static
  */
 function misc (options) {
   options.hash.scope = undefined

index.js

@@ -1,22 +1,26 @@
 const path = require('path')
+const fs = require('fs')
 const Cache = require('cache-point')
 const DmdOptions = require('./lib/dmd-options')
 const FileSet = require('file-set')
 const os = require('os')
-const fs = require('fs')
 const partialCache = require('./partials/partial-cache.js')
+const handlebars = require('handlebars')
+const arrayify = require('array-back')
+const walkBack = require('walk-back')
+const HandlebarsTemplate = require('./lib/handlebars-template.js')
 
 const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, './package.json'), 'utf8'))
 const dmdVersion = pkg.version
 
 /**
- * Transforms doclet data into markdown documentation.
+ * Transforms jsdoc-parse data into markdown documentation.
  * @param {object[]}
  * @param [options] {module:dmd-options} - The render options
  * @return {Promise<string>}
  * @alias module:dmd
  */
-async function dmd (templateData, options) {
+async function dmd (templateData = [], options) {
   options = new DmdOptions(options)
   if (skipCache(options)) {
     return generate(templateData, options)
@@ -31,61 +35,48 @@ async function dmd (templateData, options) {
   }
 }
 
+/* Expose cache so `jsdoc2md --clear` command can access it */
 dmd.cache = new Cache({ dir: path.join(os.tmpdir(), 'dmd') })
 
-async function generate (templateData, options) {
-  const fs = require('fs')
-  const path = require('path')
-  const arrayify = require('array-back')
-  const handlebars = require('handlebars')
-  const walkBack = require('walk-back')
-  const DmdOptions = require('./lib/dmd-options')
-
-  async function registerPartials (paths) {
-    const fileSet = new FileSet()
-    await fileSet.add(paths)
-    for (const file of fileSet.files) {
-      handlebars.registerPartial(
-        path.basename(file, '.hbs'),
-        fs.readFileSync(file, 'utf8') || ''
-      )
-    }
-  }
-
-  async function registerHelpers (helpers) {
-    const fileSet = new FileSet()
-    await fileSet.add(helpers)
-    for (const file of fileSet.files) {
-      handlebars.registerHelper(require(path.resolve(process.cwd(), file)))
-    }
-  }
-
-  /* Register handlebars helper modules */
-  ;['./helpers/helpers', './helpers/ddata', './helpers/selectors'].forEach(function (modulePath) {
-    handlebars.registerHelper(require(modulePath))
+async function loadPartialFiles (paths) {
+  const fileSet = new FileSet()
+  await fileSet.add(paths)
+  return fileSet.files.map(file => {
+    return [
+      path.basename(file, '.hbs'),
+      fs.readFileSync(file, 'utf8') || ''
+    ]
   })
+}
 
-  const inputData = templateData.map(function (row) {
-    return Object.assign({}, row)
+async function loadHelperFiles (helpers) {
+  const fileSet = new FileSet()
+  await fileSet.add(helpers)
+  return fileSet.files.map(file => {
+    return require(path.resolve(process.cwd(), file))
   })
+}
+
+async function generate (templateData, options) {
+  const handlebarsTemplate = new HandlebarsTemplate()
+
+  /* Copy input data */
+  const inputData = templateData.map(row => Object.assign({}, row))
   const inputOptions = Object.assign({}, options)
 
-  templateData = arrayify(templateData)
   options = Object.assign(new DmdOptions(), options)
   options.plugin = arrayify(options.plugin)
+  /* used by helpers.headingDepth */
   options._depth = 0
+  /* used by helpers.indexDepth */
   options._indexDepth = 0
+  templateData.options = options
 
-  /* state module, for sharing with the helpers */
+  /* state module, for sharing data between the helpers - functions as a global object */
   const state = require('./lib/state')
   state.templateData = templateData
   state.options = options
 
-  /* register all internal dmd partials. */
-  for (const [name, content] of partialCache) {
-    handlebars.registerPartial(name, content)
-  }
-
   /* if plugins were specified, register the helpers/partials from them too */
   if (options.plugin) {
     for (let i = 0; i < options.plugin.length; i++) {
@@ -111,24 +102,28 @@ async function generate (templateData, options) {
     }
   }
 
-  /* if additional partials/helpers paths were specified, register them too */
-  if (options.partial.length) await registerPartials(options.partial)
-  if (options.helper.length) await registerHelpers(options.helper)
+  /* register all internal and external dmd partials. */
+  const internalPartials = Array.from(partialCache)
+  const externalPartials = await loadPartialFiles(options.partial)
+  for (const [name, content] of [...internalPartials, ...externalPartials]) {
+    handlebars.registerPartial(name, content)
+  }
 
-  const compiled = handlebars.compile(options.template, {
-    preventIndent: true,
-    strict: false
-  })
-  templateData.options = options
-  const output = compiled(templateData)
+  /* Register internal helpers first so they can be overriden by user-defined helpers */
+  const internalHelpers = [require('./helpers/helpers.js'), require('./helpers/ddata.js'), require('./helpers/selectors.js')]
+  const externalHelpers = await loadHelperFiles(options.helper)
+  for (const helper of [...internalHelpers, ...externalHelpers]) {
+    handlebarsTemplate.handlebars.registerHelper(helper)
+  }
+
+  let output = handlebarsTemplate.generate(options.template, templateData)
 
-  let adjOutput = output
   if (options.EOL) {
-    adjOutput = output.replace(/\r?\n/gm, options.EOL === 'posix' ? '\n' : '\r\n')
+    output = output.replace(/\r?\n/gm, options.EOL === 'posix' ? '\n' : '\r\n')
   }
 
-  dmd.cache.writeSync([inputData, inputOptions, dmdVersion], adjOutput)
-  return adjOutput
+  dmd.cache.writeSync([inputData, inputOptions, dmdVersion], output)
+  return output
 }
 
 /* always skip the cache when custom plugins, partials or helpers are used */

lib/handlebars-template.js

@@ -0,0 +1,24 @@
+const handlebars = require('handlebars')
+const path = require('path')
+const fs = require('fs')
+
+class HandlebarsTemplate {
+  handlebars = handlebars
+
+  async registerPartialFile (file) {
+    handlebars.registerPartial(
+      path.basename(file, '.hbs'),
+      fs.readFileSync(file, 'utf8') || ''
+    )
+  }
+
+  generate (template, templateData) {
+    const compiled = handlebars.compile(template, {
+      preventIndent: true,
+      strict: false
+    })
+    return compiled(templateData)
+  }
+}
+
+module.exports = HandlebarsTemplate

lib/state.js

@@ -1,2 +1,3 @@
+/* This module operates as a global object importing clients can read/write to */
 exports.templateData = []
 exports.options = {}