Merge pull request #8 from mbland/stricter-type-checking

Check rollup types, add jsdoc-plugin-typescript

Author: mbland

index.js

@@ -38,35 +38,27 @@
 
 import PluginImpl, { PLUGIN_NAME } from './lib/index.js'
 // eslint-disable-next-line no-unused-vars
-import { PluginOptions, Transform } from './lib/types.js'
+import { PluginOptions } from './lib/types.js'
 
 /**
  * A Rollup plugin object for precompiling Handlebars templates.
  * @module rollup-plugin-handlebars-precompiler
  */
 
-/**
- * @typedef {object} RollupPlugin
- * @property {string} name - plugin name
- * @property {Function} resolveId - resolves the plugin's own import ID
- * @property {Function} load - emits the plugin's helper module code
- * @property {Function} transform - emits JavaScript code compiled from
- *   Handlebars templates
- * @see https://rollupjs.org/plugin-development/
- */
-
 /**
  * Returns a Rollup plugin object for precompiling Handlebars templates.
  * @function default
  * @param {PluginOptions} options - plugin configuration options
- * @returns {RollupPlugin} - the configured plugin object
+ * @returns {import("rollup").Plugin} - the configured plugin object
+ * @see https://rollupjs.org/plugin-development/
  */
 export default function HandlebarsPrecompiler(options) {
   const p = new PluginImpl(options)
   return {
     name: PLUGIN_NAME,
 
     /**
+     * @type {import("rollup").ResolveIdHook}
      * @param {string} id - import identifier to resolve
      * @returns {(string | undefined)} - the plugin ID if id matches it
      * @see https://rollupjs.org/plugin-development/#resolveid
@@ -76,6 +68,7 @@ export default function HandlebarsPrecompiler(options) {
     },
 
     /**
+     * @type {import("rollup").LoadHook}
      * @param {string} id - import identifier to load
      * @returns {(string | undefined)} - the plugin helper module if id matches
      * @see https://rollupjs.org/plugin-development/#load
@@ -84,7 +77,14 @@ export default function HandlebarsPrecompiler(options) {
       return p.shouldEmitHelpersModule(id) ? p.helpersModule() : undefined
     },
 
-    /** @type {Transform} */
+    /**
+     * @type {import("rollup").TransformHook}
+     * @param {string} code - potential Handlebars template to precompile
+     * @param {string} id - import identifier of possible Handlebars template
+     * @returns {(Partial<import("rollup").SourceDescription> | undefined)} -
+     *   the precompiled Handlebars template, if id identifies a template file
+     * @see https://rollupjs.org/plugin-development/#transform
+     */
     transform: function (code, id) {
       return p.isTemplate(id) ? p.compile(code, id) : undefined
     }

jsconfig.json

@@ -2,7 +2,8 @@
   "compilerOptions": {
     "checkJs": true,
     "lib": [
-      "ES2022"
+      "ES2022",
+      "DOM"
     ],
     "module": "node16",
     "target": "es2020",

jsdoc.json

@@ -1,10 +1,16 @@
 {
-  "plugins": [ "plugins/markdown" ],
+  "plugins": [
+    "plugins/markdown",
+    "jsdoc-plugin-typescript"
+  ],
   "recurseDepth": 10,
   "source": {
     "includePattern": ".+\\.js$",
     "exclude": ["node_modules"]
   },
+  "typescript": {
+    "moduleRoot": "."
+  },
   "opts": {
     "destination": "jsdoc",
     "recurse": true,

lib/index.js

@@ -36,11 +36,13 @@
  * obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+/**
+ * @module rollup-plugin-handlebars-precompiler/lib
+ */
+
 import collectPartials from './partials.js'
-import {
-  // eslint-disable-next-line no-unused-vars
-  Compiled, PartialName, PartialPath, PluginOptions, SourceMap, Transform
-} from './types.js'
+// eslint-disable-next-line no-unused-vars
+import { PartialName, PartialPath, PluginOptions } from './types.js'
 import { createFilter } from '@rollup/pluginutils'
 import Handlebars from 'handlebars'
 
@@ -78,7 +80,8 @@ const IMPORT_HELPERS = `import Render from '${PLUGIN_ID}'`
  * @param {number} numLinesBeforeTmpl - number of empty lines to add to the
  *   beginning of the source mappings to account for the generated code before
  *   the precompiled template
- * @returns {SourceMap} - potentially modified Handlebars source map
+ * @returns {import("rollup").SourceMapInput} - potentially modified Handlebars
+ *   source map
  */
 
 /**
@@ -156,7 +159,18 @@ export default class PluginImpl {
    */
   isTemplate(id) { return this.#isTemplate(id) }
 
-  /** @type {Transform} */
+  /**
+   * @typedef {object} Compiled
+   * @property {string} code - the precompiled Handlebars template code
+   * @property {string} map - the Handlebars source map as a JSON string
+   */
+
+  /**
+   * @param {string} code - Handlebars template source to precompile
+   * @param {string} id - file path used to import the Handlebars template
+   * @returns {Partial<import("rollup").SourceDescription>} - JavaScript
+   *   precompiled from a Handlebars template
+   */
   compile(code, id) {
     const opts = this.#compilerOpts(id)
     const ast = Handlebars.parse(code, opts)

lib/partials.js

@@ -36,6 +36,10 @@
  * obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+/**
+ * @module rollup-plugin-handlebars-precompiler/partials
+ */
+
 import Handlebars from 'handlebars'
 
 /**

lib/types.js

@@ -36,6 +36,10 @@
  * obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+/**
+ * @module rollup-plugin-handlebars-precompiler/types
+ */
+
 /**
  * @callback PartialName
  * @param {string} id - import identifier of a Handlebars partial template
@@ -53,16 +57,6 @@ export let PartialName
 /** @type {PartialPath} */
 export let PartialPath
 
-/**
- * An approximation of Handlebars's PrecompileOptions
- * @typedef {object} PrecompileOptions
- * @property {string} [srcName] - input file path used to generate source map;
- *   should not be set, and will be deleted if present
- * @property {string} [destName] - destination file path used to generate source
- *   map; should not be set, and will be deleted if present
- * @see https://handlebarsjs.com/api-reference/compilation.html
- */
-
 /**
  * @typedef {object} PluginOptions
  * @property {string[]} [helpers] - an array of file paths to modules containing
@@ -77,45 +71,11 @@ export let PartialPath
  *   name into the name used to apply the partial in other templates
  * @property {PartialPath} [partialPath] - function to transform a partial's
  *   name and that of the module importing it into its import path
- * @property {PrecompileOptions} [compiler] - compiler options passed through to
- *   Handlebars.parse() and Handlebars.precompile()
+ * @property {PrecompileOptions} [compiler] - Handlebars compiler options passed
+ *   through to Handlebars.parse() and Handlebars.precompile()
  * @property {boolean} [sourcemap] - disables source map generation when false
  * @property {boolean} [sourceMap] - disables source map generation when false
+ * @see https://handlebarsjs.com/api-reference/compilation.html
  */
 /** @type {PluginOptions} */
 export let PluginOptions
-
-/**
- * @typedef {object} Compiled
- * @property {string} code - the precompiled Handlebars template code
- * @property {string} map - the Handlebars source map as a JSON string
- */
-/** @type {Compiled} */
-export let Compiled
-
-/**
- * @typedef {object} SourceMap - a source map for transformed source code
- * @property {string} mappings - encoded mapping data
- * @see https://sourcemaps.info/spec.html
- */
-/** @type {SourceMap} */
-export let SourceMap
-
-/**
- * @typedef {object} TransformResult - result from RollupPlugin.transform()
- * @property {string} code - the transformed source code
- * @property {SourceMap} map - the source map for the transformed source code
- */
-/** @type {TransformResult} */
-export let TransformResult
-
-/**
- * @callback Transform
- * @param {string} code - source code to potentially transform
- * @param {string} id - import ID of source file
- * @returns {(TransformResult | undefined)} - JavaScript precompiled from a
- *   Handlebars template, if id matches the configured template filter
- * @see https://rollupjs.org/plugin-development/#transform
- */
-/** @type {Transform} */
-export let Transform

package.json

@@ -43,6 +43,8 @@
     "eslint-plugin-vitest": "^0.3.20",
     "jsdoc": "^4.0.2",
     "jsdoc-cli-wrapper": "^1.0.4",
+    "jsdoc-plugin-typescript": "^2.2.1",
+    "rollup": "^4.9.4",
     "typescript": "^5.3.3",
     "vitest": "^1.1.3"
   },