feat: better jsdoc typehints & defaults mgmt

lib/index.js

@@ -110,18 +110,31 @@ function validate({ filename, files }) {
 }
 
 /**
- * Plugin, the main plugin used by metalsmith
+ * @typedef {Object} Options
+ * @property {string} [pattern='**'] (*optional*) Limit the files to process by 1 or more glob patterns. Defaults to `'**'` (all)
+ * @property {Object} [engineOptions={}] (*optional*) Pass options to the jstransformer templating engine that's rendering your files. The default is `{}`
+ * @property {boolean} [suppressNoFilesError=false] (*optional*) Decide whether to ignore an error indicating that the plugin didn't find any matching files to process. The default is `false`
+ * @property {boolean} [setFilename=false] (*optional*) Some templating engines, like [pug](https://github.com/pugjs/pug), need a `filename` property to be present in the options to be able to process relative includes, extends, etc. Setting this option to `true` will add the current filename to the options passed to each jstransformer. The default is `false`
+ **/
+
+/** @type {Options} */
+const defaultOptions = {
+  pattern: '**',
+  engineOptions: {},
+  suppressNoFilesError: false,
+  setFilename: false
+}
+
+/**
+ * A metalsmith plugin for in-place templating
+ * @param {Options} options
+ * @returns {import('metalsmith').Plugin}
  */
+function initializeInPlace(options = defaultOptions) {
+  const settings = Object.assign({}, defaultOptions, options)
 
-module.exports = (options) =>
-  function inPlace(files, metalsmith, done) {
-    const defaults = {
-      pattern: '**',
-      engineOptions: {},
-      suppressNoFilesError: false,
-      setFilename: false
-    }
-    const settings = Object.assign({}, defaults, options)
+  return function inPlace(files, metalsmith, done) {
+    debug('Running with options %O', settings)
 
     // Check whether the pattern option is valid
     if (!(typeof settings.pattern === 'string' || Array.isArray(settings.pattern))) {
@@ -133,6 +146,7 @@ module.exports = (options) =>
     }
 
     // throw update error in case users didn't see the peerDependency warning
+    /* istanbul ignore next */
     if (!metalsmith.match) {
       throw new Error(
         'This version of @metalsmith/in-place requires metalsmith^2.4.1\'s newly added match method\nPlease update metalsmith"'
@@ -161,3 +175,6 @@ module.exports = (options) =>
       .then(() => done())
       .catch(/* istanbul ignore next */ (error) => done(error))
   }
+}
+
+module.exports = initializeInPlace

package.json

@@ -1,6 +1,6 @@
 {
   "author": "ismay",
-  "description": "A metalsmith plugin for in-place templating.",
+  "description": "A metalsmith plugin for in-place templating",
   "license": "MIT",
   "keywords": [
     "in-place",