Add types

lib/index.js

@@ -1,15 +1,35 @@
 'use strict';
 
+/**
+ * @typedef {import("./types.ts").BabelParseError} BabelParseError
+ * @typedef {import("./types.ts").Config} Config
+ * @typedef {import("./types.ts").ArgsConfig} ArgsConfig
+ * @typedef {import("./types.ts").BabelOptions} BabelOptions
+ * @typedef {import("./types.ts").KarmaFile} KarmaFile
+ * @typedef {import("./types.ts").KarmaNextFn} KarmaNextFn
+ * @typedef {import("./types.ts").KarmaLogger} KarmaLogger
+ * @typedef {import("./types.ts").KarmaHelperFns} KarmaHelperFns
+ */
+
 var babel = require('@babel/core');
 
-// @param args {Object} - Config object of custom preprocessor.
-// @param config {Object} - Config object of babelPreprocessor.
-// @param logger {Object} - Karma's logger.
-// @helper helper {Object} - Karma's helper functions.
+/**
+ * @param {ArgsConfig} args - Config object of custom preprocessor.
+ * @param {Config} config - Config object of babelPreprocessor.
+ * @param {KarmaLogger} logger - Karma's logger.
+ * @param {KarmaHelperFns} helper - Karma's helper functions.
+ */
 function createPreprocessor(args, config, logger, helper) {
   var log = logger.create('preprocessor.babel');
   config = config || {};
 
+  /**
+   * @see http://karma-runner.github.io/6.4/dev/plugins.html
+   *
+   * @param {string} content of the file being processed
+   * @param {KarmaFile} file object describing the file being processed
+   * @param {KarmaNextFn} done function to be called when preprocessing is complete
+   */
   function preprocess(content, file, done) {
     log.debug('Processing "%s".', file.originalPath);
 
@@ -33,6 +53,15 @@ function createPreprocessor(args, config, logger, helper) {
   return preprocess;
 }
 
+/**
+ * Create Babel options from Karma config of this plugin.
+ *
+ * @param {ArgsConfig} customConfig
+ * @param {Config} baseConfig
+ * @param {KarmaHelperFns} helper
+ * @param {KarmaFile} file
+ * @return {BabelOptions}
+ */
 function createOptions(customConfig, baseConfig, helper, file) {
   // Ignore 'base' property of custom preprocessor's config.
   customConfig = helper.merge({}, customConfig);
@@ -50,6 +79,15 @@ function createOptions(customConfig, baseConfig, helper, file) {
   return options;
 }
 
+/**
+ * Create Babel options from file-specific callbacks
+ * in the Karma config of this plugin.
+ *
+ * @param {Config} config
+ * @param {KarmaHelperFns} helper
+ * @param {KarmaFile} file
+ * @return {BabelOptions}
+ */
 function createPerFileOptions(config, helper, file) {
   return Object.keys(config)
     .filter(function (optionName) { return optionName !== 'options'; })

lib/types.ts

@@ -0,0 +1,79 @@
+/**
+ * Babel options @see https://babeljs.io/docs/options
+ */
+export type BabelOptions = Record<string, any>
+
+/**
+ * Babel options @see https://babeljs.io/docs/options, but the value
+ * is a callback that receives a file and returns the Babel config value.
+ */
+export type PerFileOptions = Record<string, (file: KarmaFile) => any>
+
+/**
+ * Config of this plugin.
+ */
+export type Config = {
+  options?: BabelOptions
+} & PerFileOptions
+
+/**
+ * Custom-preprocessor config of this plugin.
+ */
+export type ArgsConfig = {
+  base: 'babel'
+  options?: BabelOptions
+} & PerFileOptions
+
+/**
+ * Babel parse error.
+ */
+export type BabelParseError = {
+  code: string
+  reasonCode: string
+  loc: {
+    line: number
+    column: number
+  }
+}
+
+/**
+ * Karma File.
+ *
+ * @see http://karma-runner.github.io/6.4/dev/plugins.html
+ */
+export type KarmaFile = {
+  /**
+   * the original, unmutated path
+   */
+  originalPath: string
+  /**
+   * the current file, mutable file path.
+   */
+  path: string
+   /**
+    * determines how to include a file, when serving
+    */
+  type: string
+  /**
+   * A mutable, keyed object where the keys are a valid
+   * encoding type ('gzip', 'compress', 'br', etc.) and
+   * the values are the encoded content. Encoded content
+   * should be stored here and not resolved using
+   * next(null, encodedContent)
+   */
+  encodings: Record<string, string>
+}
+
+/**
+ * Karma Next Function.
+ *
+ * @see http://karma-runner.github.io/6.4/dev/plugins.html
+ *
+ * function to be called when preprocessing is complete, should be called as
+ * next(null, processedContent) or next(error)
+ */
+export type KarmaNextFn = (error: Error | null, content?: string | null) => void;
+
+export type KarmaLogger = any;
+
+export type KarmaHelperFns = any;